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 Project Definition) and forms the basis from which the system requirements in System Requirements are written.
The document is intentionally descriptive, not prescriptive. Statements here describe what the system is; testable “shall” statements belong in System Requirements.
Items that are not yet decided are kept as explicit placeholders and link to the corresponding open decisions in Project Plan.
System Overview¶
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:
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¶
The MOTSEN Tool operates as a bench instrument. Its external context consists of:
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. |
Subsystem Decomposition¶
The MOTSEN Tool is decomposed into the following subsystems. Each subsystem is described individually in the sections below.
|
![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;
UI [label="Native Desktop\nApplication"];
}
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 -> UI;
UI -> User;
User -> UI;
}](../_images/graphviz-777ba2d2494e63a7ec30931e29251d8b0aed8e87.png) |
Subsystem Descriptions¶
Power Stage¶
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. It is replaced by a custom PCB in Phase 3 (MIL_070). Key properties:
Open items:
|
Current and Voltage Sensing¶
Measurement chain that converts power-stage analog signals into digital samples used by the controller.
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¶
Reads the motor position sensors and provides position, direction, and speed to the controller. Phase scope:
The interface is also the input to sensor-health checks (phase sequence, Hall alignment, encoder direction). |
Embedded Controller¶
The MCU and its firmware. The controller hosts:
Portability is a stated goal: a second MCU platform must be supportable by Phase 2 exit. |
Safety and Protection¶
The MOTSEN Tool operates on real motors under power; protection is layered and applies independently of the control loop.
|
Host Communication Link¶
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:
|
Host Application¶
The host-side software is a native desktop application running locally on the user’s PC. It is a single-user, local-only tool — no authentication, no remote hosting, no cloud. The application communicates directly with the firmware over the host communication link. Components:
|
Measurement and Characterization Engine¶
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:
The two domains share procedures and are linked by the motor profile (DESC_038): a characterization run produces measured values that the user may save as a profile and later feed back into Health Check as the nominal values to compare against. Many Health Check verdicts therefore reuse the same excitation and acquisition the characterization procedures use — for example, a single low-voltage Rs procedure simultaneously yields the per-phase Rs value (characterization) and the open-winding, phase-to-phase short, and winding-balance verdicts (health check). The procedures are staged: Rs first, then Ld/Lq, pole pairs, then Kt. Each result is validated against a reference motor before being considered usable. |
Health Check Definition¶
This section details the Health Check domain. It is descriptive: it enumerates the checks the system performs, the basis on which each is detected, and the verdict each produces. The testable “shall” form of each check belongs in System Requirements.
A motor profile is an optional set of nominal/expected values for the motor under test: nominal per-phase Rs, Ld/Lq, flux linkage, pole-pair count, encoder PPR, inertia, friction, expected torque-at-speed, and the tolerances/thresholds applied to each. It is the data link between the two functional domains. Sources of a profile:
The profile is optional. Health Check degrades gracefully when it is absent:
Persistent storage of profiles on the host is a Phase 2 item (see DESC_036). |
Health Check is organized into two categories:
Every individual check resolves to one of three severities:
Where a check also yields a number (Rs, Ld, flux, PPR, offset, …), that measured value is reported alongside the verdict, so a Health Check run with no profile doubles as a characterization pass. |
Motor Check¶
Electrical checks of the three-phase winding. Most are derived from a single low-voltage Rs procedure that energizes each phase in turn and records current and resistance.
|
Checks of the rotor magnetics and pole count.
|
Checks of the mechanical behavior of the motor and any coupled load.
|
Sensor Check¶
Verifies the Hall-sensor channel. Signal-dependent checks are performed while the motor is driven open-loop.
|
Verifies the incremental (quadrature) encoder channel. Signal-dependent checks are performed while the motor is driven open-loop.
|
SinCos encoder and resolver sensor checks are placeholders. Resolver support is a Phase 3 item (see DESC_032); SinCos is not yet scheduled. The check set will mirror the incremental-encoder checks (presence, direction, offset, repeatability, runout) adapted to the analog sine/cosine channel once the hardware interface is defined. |
Motor Health Check Firmware Workflow¶
When a motor with completely unknown parameters is connected to MOTSEN, the Health Check domain executes a progressive, safety-oriented sequence that characterizes the motor and assesses its health. No prior knowledge of motor parameters is assumed; all required information is derived through a structured progression of increasingly demanding tests. The sequence is implemented as an explicit firmware state machine. Any state may
transition to Design principle — stationary tests before rotation: Stationary electrical characterization (Rs and Ldq tests) shall always be completed and validated before any motor rotation is initiated. Spin-based characterization is conditional on the stationary tests producing results that indicate controlled rotation can be performed safely. A temporary motor model, derived from the stationary electrical measurements, bounds the operating envelope of all subsequent spin tests. |
The Health Check firmware state machine comprises the following top-level states, executed in the order shown. Each state is described in detail in DESC_082 through DESC_085.
Nominal (fault-free) execution path and abnormal termination path: IDLE
↓
HARDWARE_SELF_CHECK
↓
PASSIVE_MOTOR_CHECK
↓
RS_TEST
↓
LDQ_TEST
↓
BUILD_TEMPORARY_MOTOR_MODEL
↓
ROTOR_ALIGNMENT
↓
CONTROLLED_SENSORLESS_SPIN_START
↓
OBSERVER_LOCK
↓
FLUX_LINKAGE_ESTIMATION
↓
PHASE_SEQUENCE_IDENTIFICATION
↓
POLE_PAIR_VERIFICATION
↓
MECHANICAL_CHARACTERIZATION
↓
SAFE_STOP
↓
REPORT_GENERATION
Any state → FAULT_STOP → REPORT_GENERATION
|
The first phase of the sequence consists of stationary tests executed without motor rotation. These tests must complete without a critical fault before spin-based tests are authorized. HARDWARE_SELF_CHECK Verifies that the MOTSEN hardware platform is operational before interacting with the motor under test. The following conditions are evaluated:
Any failure causes an immediate transition to PASSIVE_MOTOR_CHECK Verifies basic motor connection integrity before any electrical excitation is applied. The following conditions are evaluated:
Any failure causes an immediate transition to RS_TEST Characterizes stator resistance and detects winding faults (see also DESC_071). The test produces:
Critical winding faults (open winding, phase-to-phase short) cause a transition to
LDQ_TEST Characterizes motor inductance and evaluates magnetic symmetry. The test produces:
Physically invalid or unsafe inductance results cause a transition to |
BUILD_TEMPORARY_MOTOR_MODEL Following successful completion of the stationary electrical tests, the firmware constructs a temporary motor model from the measured parameters. The model is intentionally conservative: its limits are set below the measured electrical capabilities of the motor to ensure that subsequent spin tests operate within a safe envelope for an uncharacterized motor. The temporary model provides:
This model governs all spin-based states that follow. It is not persisted as a motor profile and is discarded at the conclusion of the Health Check run. Rationale: The temporary motor model is the gating mechanism that enforces the design principle that spin-based tests are only authorized after the stationary electrical tests have established that the motor winding is electrically sound and its parameters are sufficiently characterized to bound a safe rotation envelope. |
The second phase of the sequence executes spin-based tests. These states are reached only after the stationary electrical tests and the temporary motor model construction have both completed without critical fault. ROTOR_ALIGNMENT Moves the rotor to a known electrical position as a precondition for controlled
sensorless rotation. A limited alignment current is applied and the resulting response
is evaluated. Failure to achieve a valid aligned position causes a transition to
CONTROLLED_SENSORLESS_SPIN_START Initiates motor rotation using the conservative limits established by the temporary
motor model. The startup uses an open-loop trajectory with limited current and a
limited acceleration rate. Continuous fault monitoring is active throughout. If the
motor cannot be brought to rotation within the allowed envelope, the sequence
transitions to OBSERVER_LOCK Establishes stable sensorless speed and position estimation as a precondition for flux linkage and mechanical measurements. The following conditions are verified before the sequence proceeds:
Failure to achieve observer lock causes a transition to FLUX_LINKAGE_ESTIMATION Estimates the permanent-magnet flux linkage under steady-state rotation. The estimation uses measured Rs, Ld/Lq, current and voltage measurements, and estimated electrical speed. Results include:
PHASE_SEQUENCE_IDENTIFICATION Determines the effective motor phase sequence during rotation and its associated mechanical rotation direction. Results are reported as the detected phase sequence (e.g., UVW or UWV) and the associated rotation direction (CW or CCW). POLE_PAIR_VERIFICATION Verifies the motor pole-pair count from the estimated electrical speed and rotation data. Results include the detected pole-pair count and a verification confidence level. MECHANICAL_CHARACTERIZATION Evaluates mechanical health and load characteristics through three sub-tests: Friction and torque characterization — measures the torque required to maintain defined speeds, estimates friction, and assesses load consistency. Inertia estimation — estimates rotor inertia from the system response to controlled acceleration profiles. Coast-down test — removes drive and measures the natural deceleration profile, providing an indication of mechanical drag and bearing condition. |
SAFE_STOP Brings the motor to rest in a controlled manner before the sequence concludes. Speed is reduced to zero under controlled deceleration, torque is progressively reduced, PWM outputs are disabled, and the system transitions to the quiescent idle state. REPORT_GENERATION Collates all results from the Health Check sequence into a final report. The report includes:
|
Operating Modes¶
The MOTSEN Tool exposes two user-selectable operating modes, supported by a small set of firmware-enforced system states. The user chooses a mode in the UI; the firmware owns the state machine and enforces all transitions. User modes
System states (not user-selectable)
The detailed transition diagram is deferred to the system requirements document, which will refine these modes and states into testable behavior. |
Phase Scope Summary¶
Not every subsystem is present in every phase. The table below summarizes the scope of each subsystem per phase, mirroring the milestones in Project Plan.
|
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 Project Plan.
Final voltage range, continuous and peak current, switching frequency, gate-driver topology, and current-sense topology are pending. The 12–24 V / <100 W envelope from the project definition is the working assumption. |
UART and the on-wire frame format are pending. The description currently assumes a single point-to-point bi-directional link with framed packets and a streaming telemetry channel. |
Language and GUI framework for the desktop host application (Python/PyQt6, Python/Dear PyGui, C++/Qt, …) is pending. The application communicates directly with the firmware over the serial/USB link; no local web server is involved. |
Whether CAN is pulled into Phase 1 or kept strictly Phase 2 is pending. Default working assumption: Phase 2. |
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. |
The Motor Spin mode is intended as a general motor-control mode used to drive the motor during tests and as a standalone bench function. Its detailed scope — control method (open-loop commutation now, FOC later), the set of commandable references (speed, current, voltage, electrical angle), and which Health Check procedures invoke it — is pending. The working assumption is open-loop commutation in Phase 1, FOC in Phase 2. |
License and public-release policy is pending. Affects host-app packaging and firmware distribution; does not affect technical architecture. |
Traceability¶
This document derives from the project definition and feeds the system
requirements (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: