Software Requirements¶
Purpose¶
This document lists the software-level requirements for the MOTSEN Tool. Each
requirement is a small testable “shall” statement derived from a single
SWARCH_* block in Software Architecture or, where the software is
the primary realization of a system behavior, directly from a SYS_* node
in System Requirements.
Conventions:
One requirement, one observable behavior.
derived_frompoints to exactly oneSWARCH_*orSYS_*.All requirements are MCU-agnostic. Where a requirement references the MCU, it does so through the HAL, never by vendor name.
Items pending an open decision use
status: placeholderandlinked_tothe relevantDEC_*.
HAL Requirements¶
The HAL shall expose interfaces for GPIO, UART, timer, ADC, PWM, and NVM peripheral classes. |
HAL public headers shall not contain MCU vendor identifiers, SDK macros, or register definitions. |
Source files outside the HAL implementation directory shall not include MCU vendor headers or access MCU registers. |
The HAL implementation for a given build target shall be selected at build time via a single configuration parameter. |
Pin assignments and peripheral instance bindings shall be supplied to the HAL as build-time configuration; they shall not be hard-coded in HAL source files. |
Driver Requirements¶
The PWM driver shall expose |
The PWM driver shall configure the HAL PWM unit for center-aligned complementary output with a non-zero dead-time. |
The ADC sampler shall publish a fresh sample frame (three phase currents and DC-bus voltage) within one PWM period of the ADC end-of-conversion interrupt. |
The ADC sampler shall apply per-channel scale and offset from the calibration store before publishing sample values. |
The Hall reader shall maintain the current commutation sector and an inferred direction of rotation, updated on every Hall edge and on a periodic poll. |
The comms framer shall encode and decode frames of the on-wire format using a single byte-stream interface in each direction. |
Services Layer Requirements¶
The firmware shall provide a 1 kHz (or faster) system tick driven by a HAL timer. |
The firmware shall provide non-blocking |
The firmware shall provide a cooperative scheduler that runs registered periodic tasks from the main loop. The scheduler shall not preempt. |
The control / measurement step, Hall sector update, and comms RX byte intake shall execute in interrupt context and shall not depend on the cooperative scheduler. |
The parameter store shall expose every runtime-tunable parameter by a stable numeric ID. |
A parameter write shall be range-checked against the parameter’s declared bounds; writes outside the bounds shall be rejected and reported to the host. |
The measurement engine shall refuse to publish a characterization result when the calibration store does not contain values for every channel used in the procedure. |
The protocol shall support three message classes: Parameter, Telemetry, and Command. |
The protocol shall include a version field in the frame header and the firmware shall report a mismatch back to the host without entering any error state of its own. |
The safety supervisor shall run on every ADC sample frame and check instantaneous phase currents and DC-bus voltage against the configured limits. |
On any limit breach the safety supervisor shall disable PWM via the PWM driver before returning from the sample ISR. |
After disabling PWM, the safety supervisor shall request a transition to the Fault state and shall record the fault cause and the offending sample frame in the logger. |
The logger shall not block its caller and shall not perform dynamic allocation. |
The logger shall forward events on the protocol’s telemetry channel as the host comms scheduler runs. |
Application Layer Requirements¶
The operating-mode state machine shall be the sole writer of the current operating mode. No other module shall change the mode directly. |
The state machine shall reject any mode transition request that does not satisfy the rules in Firmware-enforced transitions (SYS_111) through No direct Characterization ... (SYS_114). |
The state machine shall accept a Fault entry request from any source mode and shall execute the Fault entry actions before returning. |
The state machine shall exit Fault only on receiving an explicit acknowledgement command from the host, and shall transition only to Idle / Safe. |
The sensor health check procedure shall complete on a real motor and shall return one of {pass, fail-phase-sequence, fail-hall-alignment, fail-connectivity} along with a textual diagnostic. |
The sensor health check procedure shall declare its own current limit before enabling PWM, and that limit shall be lower than the configured Run-mode current limit. |
The Rs measurement procedure shall declare its own current limit before enabling PWM and shall abort the procedure on any safety-supervisor trip. |
The Rs measurement procedure shall return a result containing the measured Rs value, the test current, the measured DC voltage, and the pass/fail outcome against the configured tolerance. |
The open-loop commutation control loop shall run in the ADC sampler interrupt context and shall complete within one PWM period. |
The open-loop commutation control loop shall not command a duty cycle that would cause the safety supervisor’s current limit to be reached under nominal conditions. |
Host-Side Software Requirements¶
The browser UI shall be a single-page application that does not require a page reload during normal use. |
The UI shall display live phase currents, position sensor state, the current operating mode, and any active fault, updated from the telemetry channel. |
The UI shall provide an explicit trigger for the sensor health check and for the Rs measurement procedure, and shall display the returned result. |
The host-side protocol implementation shall implement the same message classes, the same version negotiation, and the same frame format as the firmware-side implementation. |
The host application shall not implement user authentication or multi-user session handling. |
The local web server shall bind to a loopback interface by default and shall not be reachable from outside the host PC without an explicit user opt-in. |
Build and Configuration Requirements¶
The firmware source tree shall build for every supported target without modification to source files outside the HAL implementation directory. |
Optional features (CAN, encoder, resolver, FOC, scripting) shall be compiled out of builds for which they are not enabled. |
The firmware shall not call dynamic memory allocation routines after the startup phase has completed. |
Phase 2 and Phase 3 Placeholders¶
Incremental encoder driver software. Scheduled for Phase 2 (MIL_042). |
Resolver driver software. Scheduled for Phase 3 (MIL_077). |
Ld / Lq measurement procedure. Scheduled for Phase 2 (MIL_040). |
Back-EMF and torque-constant measurement procedure. Scheduled for Phase 2 (MIL_041). |
Field-oriented closed-loop control. Scheduled for Phase 2 (MIL_045). |
Host scripting interface for measurement sequences. Scheduled for Phase 2 (MIL_044). |
Persistent storage of parameters and results on the host. Scheduled for Phase 2 (MIL_047). |
Open-Decision Placeholders¶
Backend language and framework for the local web server are pending DEC_002. |
Final on-wire frame format and physical layer are pending DEC_003. |
Whether HAL implementations wrap the MCU vendor SDK or sit on registers is pending DEC_005. |
Sensorless observer scope is pending DEC_006. |
Traceability¶
Forward links from swreq to software test cases (TEST_* in
<no title>) will be added as the software test plan is
populated.