System Description ================== Purpose ------- This document describes the MOTSEN Tool from a system point of view. It defines the system boundary, the external entities the system interacts with, the internal subsystems, and the operating modes. It is derived from the project definition (see :doc:`../01_Project/definition`) and forms the basis from which the system requirements in :doc:`system_requirements` are written. The document is intentionally descriptive, not prescriptive. Statements here describe *what the system is*; testable "shall" statements belong in :doc:`system_requirements`. Items that are not yet decided are kept as explicit placeholders and link to the corresponding open decisions in :doc:`../01_Project/project_plan`. System Overview --------------- .. desc:: MOTSEN system overview :id: DESC_001 :status: draft :derived_from: PRJ_001 :linked_to: MIL_021 The MOTSEN Tool is a bench instrument for commissioning, characterizing, and diagnosing permanent-magnet synchronous and brushless DC motors (PMSM / IPMSM / BLDC). It combines the functions traditionally provided by a separate inverter, oscilloscope, LCR meter, power analyzer, and vendor tuning software into a single connected device driven from a host PC. The tool consists of: * A power-electronics stage that drives a three-phase motor under test. * Measurement hardware for phase currents, DC-bus voltage, and position sensors. * An embedded controller (MCU and firmware) implementing real-time control, sensing, measurement procedures, and safety logic. * A host PC application providing a user interface, parameter editing, and a live data view. * A host↔firmware communication link. The initial target motor class is PMSM/BLDC at low voltage (12–24 V) and below 100 W. Other motor types and higher power ranges are explicit non-goals for the current phases. System Context -------------- .. desc:: System context and external entities :id: DESC_010 :status: draft :derived_from: PRJ_001 The MOTSEN Tool operates as a bench instrument. Its external context consists of: * **Motor under test (MUT)** — the three-phase PMSM/BLDC motor connected to the power stage, including its position sensors (Hall, encoder, later resolver). * **DC power source** — a bench supply (current-limited during development) feeding the DC bus. * **Host PC** — a personal computer running the host application and browser-based UI. * **User** — a motor control engineer, validation engineer, production technician, or researcher operating the tool through the host PC. * **Mechanical load (optional)** — a brake, dyno, or coupled load for tests that require a mechanical reaction. Not part of the tool itself. The tool does not connect to any cloud service, network infrastructure, or shared database. All interaction with the user is mediated by the host PC. .. desc:: System boundary :id: DESC_011 :status: draft :derived_from: PRJ_001 Inside the system boundary: * Power stage hardware * Sensing hardware (current, voltage, position) * Embedded controller (MCU + firmware) * Host↔firmware physical and logical link * Host PC application and UI Outside the system boundary: * Motor under test and its wiring * DC supply and any external safety equipment (fuse, e-stop) * Host PC hardware and operating system * Mechanical load equipment Subsystem Decomposition ----------------------- .. desc:: Subsystem decomposition :id: DESC_020 :status: draft :derived_from: PRJ_001 The MOTSEN Tool is decomposed into the following subsystems. Each subsystem is described individually in the sections below. .. list-table:: :header-rows: 1 :widths: 25 75 * - Subsystem - Role * - Power Stage - Drives three motor phases from the DC bus with PWM-controlled half bridges. * - Current & Voltage Sensing - Measures phase currents and DC-bus voltage and presents them to the controller. * - Position Sensor Interface - Reads motor position sensors (Hall in Phase 1, encoder in Phase 2, resolver in Phase 3). * - Embedded Controller - Runs firmware: hardware abstraction, control loops, measurement procedures, and the firmware-side communication endpoint. * - Safety & Protection - Enforces current, voltage, and timing limits in both firmware and hardware. * - Host Communication Link - Physical and protocol link between firmware and the host PC. * - Host Application - Local server on the host PC, browser-based UI, parameter editing, live data view. * - Measurement & Characterization Engine - The set of procedures that run on the firmware (and assist on the host) to perform sensor checks and parameter estimation. .. desc:: Subsystem block diagram :id: DESC_021 :status: draft :derived_from: PRJ_001 .. graphviz:: digraph motsen_blocks { rankdir=LR; node [shape=box, style="rounded,filled", fillcolor="#F4F6F7"]; subgraph cluster_tool { label="MOTSEN Tool"; style=dashed; Ctrl [label="Embedded\nController\n(MCU + FW)"]; Power [label="Power Stage\n(3-phase inverter)"]; Sense [label="Current &\nVoltage Sensing"]; Pos [label="Position Sensor\nInterface"]; Safe [label="Safety &\nProtection"]; Link [label="Host Comms\nLink"]; } subgraph cluster_host { label="Host PC"; style=dashed; Server [label="Local Web\nServer"]; UI [label="Browser UI"]; } DC [label="DC Supply", shape=ellipse, fillcolor="#FFF2CC"]; Motor [label="Motor Under\nTest (+ sensors)", shape=ellipse, fillcolor="#FFF2CC"]; User [label="User", shape=ellipse, fillcolor="#FFF2CC"]; DC -> Power; Power -> Motor [label="3-phase"]; Motor -> Pos [label="Hall / Enc / Resolver"]; Power -> Sense [label="I, V"]; Sense -> Ctrl; Pos -> Ctrl; Ctrl -> Power [label="PWM"]; Ctrl -> Safe; Safe -> Power [label="latch trip"]; Ctrl -> Link; Link -> Server; Server -> UI; UI -> User; User -> UI; } Subsystem Descriptions ---------------------- Power Stage ~~~~~~~~~~~ .. desc:: Power stage :id: DESC_030 :status: draft :derived_from: PRJ_001 :linked_to: MIL_008; MIL_012; DEC_001 A three-phase inverter that drives the motor under test from the DC bus. In Phase 1 the power stage is provided by an off-the-shelf evaluation board; the specific board is an open decision (see DEC_001). It is replaced by a custom PCB in Phase 3 (MIL_070). Key properties: * Three half-bridges with complementary switching and configurable dead-time. * Operates at a DC bus in the 12–24 V range. * Continuous output below 100 W for the MVP target. * Designed to be driven by center-aligned PWM synchronized to ADC sampling. Open items: * DEC_001 — selected eval board (closes through MIL_008). * Final voltage, current, and switching frequency ratings — placeholder pending the selection above. Current and Voltage Sensing ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. desc:: Current and voltage sensing :id: DESC_031 :status: draft :derived_from: PRJ_001 :linked_to: MIL_010; MIL_011 Measurement chain that converts power-stage analog signals into digital samples used by the controller. * **Phase currents** — sensed on the low side and sampled in synchronization with the PWM cycle. Scale, offset, and noise floor are calibrated against a known reference (MIL_010). * **DC-bus voltage** — sensed and used both for control and for under-/over-voltage supervision (MIL_011). * **Auxiliary signals (future)** — temperature, additional bus rails, and motor temperature are placeholders for later phases. The sensing chain is the dominant source of measurement uncertainty for the characterization features and must be characterized before any parameter estimation result is reported. Position Sensor Interface ~~~~~~~~~~~~~~~~~~~~~~~~~ .. desc:: Position sensor interface :id: DESC_032 :status: draft :derived_from: PRJ_001 :linked_to: MIL_014; MIL_042; MIL_077 Reads the motor position sensors and provides position, direction, and (later) speed to the controller. Phase scope: * **Phase 1** — Hall sensors only. A 6-state decoder yields commutation sector and inferred direction (MIL_014). * **Phase 2** — Incremental encoder support added alongside Hall (MIL_042). * **Phase 3** — Resolver support added (MIL_077). The interface is also the input to sensor-health checks (phase sequence, Hall alignment, encoder direction). Embedded Controller ~~~~~~~~~~~~~~~~~~~ .. desc:: Embedded controller :id: DESC_033 :status: draft :derived_from: PRJ_001 :linked_to: MIL_004; MIL_005; MIL_007; MIL_048; DEC_005 The MCU and its firmware. The MVP target MCU is the NXP S32K322. The controller hosts: * A hardware abstraction layer (HAL) over GPIO, UART, timers, ADC, and PWM. * The control loops (open-loop commutation in Phase 1, FOC in Phase 2). * The measurement and characterization procedures. * The firmware-side host communication endpoint. * The safety supervisor (firmware portion). Portability is a stated goal: a second MCU platform must be supportable by Phase 2 exit (MIL_048). The strategy for the HAL — wrapping the NXP RTD/SDK versus a thin register- level layer — is an open decision (DEC_005). The HAL is intentionally designed to the minimum needed for Phase 1 (see RISK_002). Safety and Protection ~~~~~~~~~~~~~~~~~~~~~ .. desc:: Safety and protection :id: DESC_034 :status: draft :derived_from: PRJ_001 :linked_to: MIL_009; MIL_013; RISK_007 The MOTSEN Tool operates on real motors under power; protection is layered and applies independently of the control loop. * **Firmware limits** — enforced current and speed limits in the control software, immediate disable of PWM on detected fault. * **Hardware overcurrent latch** — an analog/digital latch that trips the PWM outputs in hardware, independent of the firmware control loop (MIL_013). Recovery is an explicit, documented procedure. * **Bench safety procedures** — a current-limited supply and a documented power-up checklist (MIL_009) are used during all development testing. * **Out of scope** — functional safety certification, SIL/ASIL compliance, and mechanical guarding are explicit non-goals for the project (see project definition). Host Communication Link ~~~~~~~~~~~~~~~~~~~~~~~ .. desc:: Host communication link :id: DESC_035 :status: draft :derived_from: PRJ_001 :linked_to: MIL_006; MIL_016; MIL_043; DEC_003; DEC_004 The link between firmware and the host PC. It carries parameter read/write commands, a streaming log/telemetry channel, and command/response traffic for measurement procedures. Phase scope: * **Phase 1** — A single point-to-point link to the host PC. The physical layer (UART vs USB-CDC) and the frame format are an open decision (DEC_003, closes through MIL_016). * **Phase 2** — CAN added as a secondary interface (MIL_043). Whether CAN is pulled into Phase 1 is itself an open decision (DEC_004). * **Phase 3** — Field interfaces (CANopen, EtherCAT) listed in the project definition as future possibilities; not in current scope. Host Application ~~~~~~~~~~~~~~~~ .. desc:: Host application :id: DESC_036 :status: draft :derived_from: PRJ_001 :linked_to: MIL_017; MIL_018; MIL_044; MIL_046; DEC_002; RISK_004 The host-side software runs locally on the user's PC. It is a single-user, local-only tool — no authentication, no remote hosting, no cloud (RISK_004). Components: * **Local web server** — serves the static UI assets and bridges a real-time channel (e.g. WebSocket) to the firmware over the host communication link (MIL_017). The backend language and framework are an open decision (DEC_002). * **Browser UI** — the user-facing dashboard. Shows live phase currents and sensor state, allows parameter editing, and triggers measurement procedures (MIL_018, MIL_046). * **Test automation framework (Phase 2)** — a scriptable interface for running measurement sequences without manual UI interaction (MIL_044). * **Parameter storage and project files (Phase 2)** — persistent storage of motor parameters and measurement results on the host (MIL_047). Measurement and Characterization Engine ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. desc:: Measurement and characterization engine :id: DESC_037 :status: draft :derived_from: PRJ_001 :linked_to: MIL_019; MIL_020; MIL_040; MIL_041; RISK_005 The set of procedures that perform sensor checks and motor parameter estimation. Most of the procedure runs on the firmware (real-time signal injection and acquisition); the host receives results and may post-process and present them. Two functional domains, as defined in the project definition: 1. **Sensor Health Check** — phase-sequence correctness, Hall alignment, encoder direction, sensor consistency, electrical connectivity, signal integrity. Detects incorrect motor wiring before unsafe operation (MIL_019). 2. **Motor Characterization** — phase resistance Rs (MIL_020), D/Q-axis inductances Ld/Lq (MIL_040), back-EMF and torque constant Kt (MIL_041), electrical phase offset, and rotor position characteristics. Thermal behavior is a future item. Algorithm complexity is a known risk (RISK_005). The procedures are staged: Rs first, then Ld/Lq, then Kt. Each result is validated against a reference motor before being considered usable. Operating Modes --------------- .. desc:: Operating modes :id: DESC_040 :status: draft :derived_from: PRJ_001 The MOTSEN Tool operates in a small number of distinct modes. The modes are exposed at the system level — the user sees them in the UI, and the firmware enforces transitions. .. list-table:: :header-rows: 1 :widths: 22 78 * - Mode - Description * - Idle / Safe - PWM disabled, bus voltage monitored, no current flowing through the motor. This is the power-on default and the recovery state after any fault. * - Sensor Check - Low-energy stimulus is applied for the sole purpose of verifying sensor connectivity and alignment. Strict current limits apply. * - Characterization - Defined measurement procedures are executed (Rs, Ld/Lq, Kt, ...). The motor may be energized with controlled excitation but is not driven for motion in most procedures. * - Run (control) - The motor is driven under closed-loop or open-loop control. Phase 1 supports open-loop commutation only; FOC is added in Phase 2 (MIL_045). * - Fault - A protection event has occurred. PWM is latched off in hardware and firmware. The user must acknowledge the fault to return to Idle. The detailed transition diagram is deferred to the system requirements document, which will refine these into testable behavior. Phase Scope Summary ------------------- .. desc:: Subsystem presence by project phase :id: DESC_050 :status: draft :derived_from: PRJ_001 Not every subsystem is present in every phase. The table below summarizes the scope of each subsystem per phase, mirroring the milestones in :doc:`../01_Project/project_plan`. .. list-table:: :header-rows: 1 :widths: 25 25 25 25 * - Subsystem - Phase 1 (MVP) - Phase 2 (Full) - Phase 3 (Productized) * - Power Stage - Eval board - Eval board - Custom PCB * - Current/Voltage Sensing - Phase I + Vbus - + extra rails - Production-cal * - Position Sensors - Hall - Hall + Encoder - + Resolver * - Embedded Controller - S32K322 only - Second MCU - Production FW * - Safety - FW + HW latch - Same, hardened - Reliability tested * - Host Link - UART or USB-CDC - + CAN - + field bus (TBD) * - Host App - Local web UI - + scripting, params - User-ready * - Measurement Engine - Sensor check + Rs - + Ld/Lq, Kt - + production tests Open Items and Placeholders --------------------------- The descriptions above include items that depend on decisions that have not yet been made. Each placeholder below is intentionally kept here, in the system description, so that the gap is visible to anyone reading top-down from the project definition. They close through the corresponding decisions in :doc:`../01_Project/project_plan`. .. desc:: Power-stage capability — pending eval board selection :id: DESC_060 :status: placeholder :derived_from: PRJ_001 :linked_to: DEC_001; MIL_008 Final voltage range, continuous and peak current, switching frequency, gate-driver topology, and current-sense topology are pending DEC_001. The 12–24 V / <100 W envelope from the project definition is the working assumption. .. desc:: Host-link physical layer and framing — pending :id: DESC_061 :status: placeholder :derived_from: PRJ_001 :linked_to: DEC_003; MIL_016 UART vs USB-CDC and the on-wire frame format are pending DEC_003. The description currently assumes a single point-to-point bi-directional link with framed packets and a streaming telemetry channel. .. desc:: Host backend stack — pending :id: DESC_062 :status: placeholder :derived_from: PRJ_001 :linked_to: DEC_002; MIL_017 Backend language and framework for the local server (Python/FastAPI, Node.js, Go, ...) is pending DEC_002. The description assumes a local-only server that serves static assets and a real-time channel. .. desc:: HAL strategy — pending :id: DESC_063 :status: placeholder :derived_from: PRJ_001 :linked_to: DEC_005; MIL_004; MIL_048 Whether the HAL wraps NXP RTD/SDK or is a thin register-level layer is pending DEC_005. The choice affects portability cost when the second MCU is added in Phase 2. .. desc:: CAN scope — pending :id: DESC_064 :status: placeholder :derived_from: PRJ_001 :linked_to: DEC_004; MIL_043 Whether CAN is pulled into Phase 1 or kept strictly Phase 2 is pending DEC_004. Default working assumption: Phase 2. .. desc:: Sensorless control scope — pending :id: DESC_065 :status: placeholder :derived_from: PRJ_001 :linked_to: DEC_006 Whether observer-based sensorless control is in scope, and for which phase, is pending DEC_006. Not described as a present subsystem until the decision closes. .. desc:: Publication / license — pending :id: DESC_066 :status: placeholder :derived_from: PRJ_001 :linked_to: DEC_007 License and public-release policy is pending DEC_007. Affects host-app packaging and firmware distribution; does not affect technical architecture. Traceability ------------ This document derives from the project definition (PRJ_001) and feeds the system requirements (:doc:`system_requirements`). Each ``desc`` node above is intended to be referenced by one or more ``sysreq`` nodes when the requirements document is populated. Forward links to milestones and decisions in the project plan are kept on the description nodes themselves so that: * A placeholder makes its open decision visible at the description level. * Each subsystem can be traced forward into the milestones that build it and the hardware/software requirements that detail it.