Software Architecture¶
Purpose¶
This document describes the firmware and host-side software architecture of the MOTSEN Tool: the layers, the modules within each layer, the threading and timing model, and the seams that make the firmware portable across MCUs. It sits between System Description and Software Requirements.
The architecture is intentionally MCU-agnostic. Every MCU-specific concern is confined to the hardware abstraction layer (HAL). Application, services, and measurement code use only HAL interfaces, never vendor SDK calls or register access.
Architecture Overview¶
The firmware is organized in four layers, lower layers do not call upward:
The host side adds two further layers above the link: a local web server and a browser UI. The on-wire protocol is the seam between firmware and host. |
| digraph sw_layers { rankdir=BT; node [shape=box, style="rounded,filled", fillcolor="#D5F5E3"]; HAL [label="HAL\n(GPIO, UART, Timer, ADC, PWM, NVM)"]; Drv [label="Drivers\n(PWM, ADC, Hall, Comms framer)"]; Svc [label="Services\n(Tick, Scheduler, Params, Safety, Protocol, Logger)"]; App [label="Application\n(State machine, Measurement, Control)"]; Wire [label="On-wire protocol", shape=ellipse, fillcolor="#FCF3CF"]; Host [label="Host: local web server + browser UI", fillcolor="#D6EAF8"]; HAL -> Drv; Drv -> Svc; Svc -> App; App -> Wire [style=dashed, dir=both]; Wire -> Host [style=dashed, dir=both]; } |
Hardware Abstraction Layer¶
The HAL exposes interfaces for the peripheral classes required by MCU peripheral classes used (HWARCH_060): GPIO, UART, timer, ADC, PWM, and NVM. Each interface is defined in pure C and contains no MCU-specific identifiers. |
The HAL is the only place where MCU vendor headers, SDK calls, or register access may appear. Layers above the HAL #include only HAL headers. A new MCU is supported by adding a new HAL implementation; no change above the HAL is required. |
The HAL implementation for a given MCU is selected at build time. Pin assignments and peripheral instances are passed in as build-time configuration, not hard-coded in the HAL source. |
The HAL is sized to the minimum needed by the current phase. New HAL functions are added only when a driver or service needs them. This is the mitigation for RISK_002 (HAL over-engineered prematurely). |
Whether each HAL implementation wraps the MCU vendor’s RTD/SDK or sits directly on registers is pending DEC_005. |
Drivers Layer¶
The PWM driver translates the application’s duty-cycle commands into HAL
calls. It configures center-aligned mode, complementary outputs,
dead-time, and ADC trigger generation. It exposes a single
|
The ADC sampler runs in the ADC end-of-conversion interrupt and delivers a struct of fresh phase currents and DC-bus voltage to the control loop within one PWM period. It applies calibration scale and offset before publishing the values. |
The Hall reader samples Hall inputs on edge interrupts and on a periodic poll. It maintains the current commutation sector and an inferred direction, and exposes them as read-only state. |
Incremental encoder driver. Scheduled for Phase 2 (MIL_042). |
Resolver excitation and demodulation driver. Scheduled for Phase 3 (MIL_077). |
The comms framer encodes and decodes frames on the host link using the selected on-wire format (pending DEC_003). It exposes a byte-stream interface to the protocol service and a frame interface to the link’s HAL UART instance. |
Services Layer¶
A single timer-driven system tick provides non-blocking timing primitives and drives a cooperative scheduler for periodic work that is not time-critical (telemetry assembly, host comms, status updates). |
Real-time work runs in interrupt context, not on the scheduler:
The application loop runs at lower priority and is preempted by these ISRs. No RTOS is required. |
The parameter store holds the runtime-tunable values (limits, measurement settings, calibration). Parameters are accessible by ID from the host link. RAM-only in Phase 1; non-volatile persistence is a placeholder until the NVM-bearing HAL is required. |
Sensing-chain calibration coefficients (scale, offset for each channel) live in the calibration store and are applied by the ADC sampler. The measurement engine refuses to publish a characterization result if the calibration store is empty (see Sensing chain calibrated be... (SYS_044)). |
The protocol service runs on top of the comms framer. It defines three message classes:
Protocol versioning is included in the frame header so that host and firmware can detect a mismatch. |
The safety supervisor runs on every ADC sample and checks instantaneous current and DC-bus voltage against firmware-configurable limits. On any limit breach it:
|
The logger collects diagnostic events into a small in-RAM ring buffer and forwards them on the telemetry channel. Events include faults, mode transitions, and procedure start/end markers. The logger has no blocking calls and never allocates. |
Application Layer¶
The state machine is the single owner of the operating mode (Idle, Sensor Check, Characterization, Run, Fault). It accepts transition requests from the protocol service, validates them against the rules in Firmware-enforced transitions (SYS_111) to No direct Characterization ... (SYS_114), and drives mode-entry / exit actions (PWM enable/disable, current limit selection). |
The sensor health check is a sequence of low-energy stimuli that validates phase sequence, Hall alignment, and basic connectivity. It runs entirely in firmware, with the host receiving only command and result frames. |
Rs is measured by applying a controlled DC current along a known electrical axis and computing R = V / I after settling. The procedure declares its own current limit, ramps to the test current, and aborts the procedure if the limit is breached. |
Ld / Lq measurement. Scheduled for Phase 2 (MIL_040). |
Back-EMF and torque-constant measurement. Scheduled for Phase 2 (MIL_041). |
The Phase 1 control loop drives open-loop sinusoidal commutation with an enforced current limit. The control loop runs synchronously with the ADC sampler (see Real-time execution model (SWARCH_031)). |
Field-oriented control. Scheduled for Phase 2 (MIL_045). |
Host-Side Software¶
A local web server on the host PC serves the UI static assets and bridges a real-time channel to the firmware over the host link. The backend language and framework are pending DEC_002. |
The browser UI provides a single-page application showing live phase currents, sensor state, the current operating mode, and any active fault. It triggers measurement procedures via the protocol and displays their results. |
The host has its own implementation of the comms protocol defined by Comms protocol (SWARCH_050). Frame format and physical layer match the firmware side (pending DEC_003). |
A scriptable interface on the host allows running measurement sequences without the browser UI. Scheduled for Phase 2 (MIL_044). |
Persistent storage of motor parameters and measurement results on the host filesystem. Scheduled for Phase 2 (MIL_047). |
Build and Configuration¶
The firmware build accepts a “target” parameter that selects the HAL implementation, the pin/peripheral mapping, and the feature set for the target phase. The same source tree builds for all supported targets. |
Optional features (CAN, encoder, resolver, FOC, etc.) are gated at compile time so that the Phase 1 build does not pull in Phase 2 or 3 code. |
The firmware shall not use dynamic memory allocation after startup. All buffers are sized at build time. |
Open Items¶
Backend language and framework for the local web server are pending DEC_002. |
The exact frame format and physical layer of the host link are pending DEC_003. The architecture above assumes the existence of a framed bi-directional channel but does not bind it. |
Whether observer-based sensorless control is in scope is pending DEC_006. |
Traceability¶
Each swarch node above declares derived_from exactly one DESC_*
node in System Description. The forward direction is
populated by swreq nodes in Software Requirements, which declare
derived_from either a SYS_* requirement or a SWARCH_* block here.