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 :doc:`software_architecture` or, where the software is the primary realization of a system behavior, directly from a ``SYS_*`` node in :doc:`../02_System/system_requirements`. Conventions: * One requirement, one observable behavior. * ``derived_from`` points to exactly one ``SWARCH_*`` or ``SYS_*``. * 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: placeholder`` and ``linked_to`` the relevant ``DEC_*``. HAL Requirements ---------------- .. swreq:: HAL covers required peripheral classes :id: SWREQ_010 :status: draft :derived_from: SWARCH_010 The HAL shall expose interfaces for GPIO, UART, timer, ADC, PWM, and NVM peripheral classes. .. swreq:: HAL header purity :id: SWREQ_011 :status: draft :derived_from: SWARCH_011 HAL public headers shall not contain MCU vendor identifiers, SDK macros, or register definitions. .. swreq:: HAL is the only MCU-aware code :id: SWREQ_012 :status: draft :derived_from: SWARCH_011 Source files outside the HAL implementation directory shall not include MCU vendor headers or access MCU registers. .. swreq:: HAL selected at build time :id: SWREQ_013 :status: draft :derived_from: SWARCH_012 The HAL implementation for a given build target shall be selected at build time via a single configuration parameter. .. swreq:: HAL pin/peripheral mapping is build configuration :id: SWREQ_014 :status: draft :derived_from: SWARCH_012 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 ------------------- .. swreq:: PWM driver entry points :id: SWREQ_020 :status: draft :derived_from: SWARCH_020 The PWM driver shall expose ``apply_duties``, ``enable``, and ``disable`` entry points and no others related to PWM output. .. swreq:: PWM driver configures dead-time :id: SWREQ_021 :status: draft :derived_from: SWARCH_020 The PWM driver shall configure the HAL PWM unit for center-aligned complementary output with a non-zero dead-time. .. swreq:: ADC sampler latency :id: SWREQ_022 :status: draft :derived_from: SWARCH_021 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. .. swreq:: ADC sampler applies calibration :id: SWREQ_023 :status: draft :derived_from: SWARCH_021 The ADC sampler shall apply per-channel scale and offset from the calibration store before publishing sample values. .. swreq:: Hall reader maintains sector and direction :id: SWREQ_024 :status: draft :derived_from: SWARCH_022 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. .. swreq:: Comms framer is byte-stream symmetric :id: SWREQ_025 :status: draft :derived_from: SWARCH_025 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 --------------------------- .. swreq:: System tick :id: SWREQ_030 :status: draft :derived_from: SWARCH_030 The firmware shall provide a 1 kHz (or faster) system tick driven by a HAL timer. .. swreq:: Non-blocking timing primitives :id: SWREQ_031 :status: draft :derived_from: SWARCH_030 The firmware shall provide non-blocking ``delay`` and ``timeout`` primitives backed by the system tick. .. swreq:: Cooperative scheduler :id: SWREQ_032 :status: draft :derived_from: SWARCH_030 The firmware shall provide a cooperative scheduler that runs registered periodic tasks from the main loop. The scheduler shall not preempt. .. swreq:: Real-time work in ISR context :id: SWREQ_033 :status: draft :derived_from: SWARCH_031 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. .. swreq:: Parameter access by ID :id: SWREQ_040 :status: draft :derived_from: SWARCH_040 The parameter store shall expose every runtime-tunable parameter by a stable numeric ID. .. swreq:: Parameter write validation :id: SWREQ_041 :status: draft :derived_from: SWARCH_040 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. .. swreq:: Calibration store applied before publication :id: SWREQ_042 :status: draft :derived_from: SWARCH_041 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. .. swreq:: Protocol message classes :id: SWREQ_050 :status: draft :derived_from: SWARCH_050 The protocol shall support three message classes: Parameter, Telemetry, and Command. .. swreq:: Protocol version negotiation :id: SWREQ_051 :status: draft :derived_from: SWARCH_050 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. .. swreq:: Safety supervisor runs every sample :id: SWREQ_060 :status: draft :derived_from: SWARCH_060 The safety supervisor shall run on every ADC sample frame and check instantaneous phase currents and DC-bus voltage against the configured limits. .. swreq:: Safety supervisor disables PWM on breach :id: SWREQ_061 :status: draft :derived_from: SWARCH_060 On any limit breach the safety supervisor shall disable PWM via the PWM driver before returning from the sample ISR. .. swreq:: Safety supervisor transitions to Fault :id: SWREQ_062 :status: draft :derived_from: SWARCH_060 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. .. swreq:: Logger non-blocking :id: SWREQ_070 :status: draft :derived_from: SWARCH_070 The logger shall not block its caller and shall not perform dynamic allocation. .. swreq:: Logger forwards on telemetry :id: SWREQ_071 :status: draft :derived_from: SWARCH_070 The logger shall forward events on the protocol's telemetry channel as the host comms scheduler runs. Application Layer Requirements ------------------------------ .. swreq:: State machine owns mode :id: SWREQ_080 :status: draft :derived_from: SWARCH_080 The operating-mode state machine shall be the sole writer of the current operating mode. No other module shall change the mode directly. .. swreq:: Mode transition rules enforced :id: SWREQ_081 :status: draft :derived_from: SWARCH_080 The state machine shall reject any mode transition request that does not satisfy the rules in :need:`SYS_111` through :need:`SYS_114`. .. swreq:: Fault entry from any mode :id: SWREQ_082 :status: draft :derived_from: SWARCH_080 The state machine shall accept a Fault entry request from any source mode and shall execute the Fault entry actions before returning. .. swreq:: Fault exit requires acknowledgement :id: SWREQ_083 :status: draft :derived_from: SWARCH_080 The state machine shall exit Fault only on receiving an explicit acknowledgement command from the host, and shall transition only to Idle / Safe. .. swreq:: Sensor health check end-to-end :id: SWREQ_090 :status: draft :derived_from: SWARCH_090 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. .. swreq:: Sensor health check current cap :id: SWREQ_091 :status: draft :derived_from: SWARCH_090 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. .. swreq:: Rs procedure declares its limit :id: SWREQ_100 :status: draft :derived_from: SWARCH_091 The Rs measurement procedure shall declare its own current limit before enabling PWM and shall abort the procedure on any safety-supervisor trip. .. swreq:: Rs result reporting :id: SWREQ_101 :status: draft :derived_from: SWARCH_091 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. .. swreq:: Open-loop commutation control rate :id: SWREQ_110 :status: draft :derived_from: SWARCH_100 The open-loop commutation control loop shall run in the ADC sampler interrupt context and shall complete within one PWM period. .. swreq:: Open-loop current limit enforcement :id: SWREQ_111 :status: draft :derived_from: SWARCH_100 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 ------------------------------- .. swreq:: Browser UI single-page :id: SWREQ_120 :status: draft :derived_from: SWARCH_111 The browser UI shall be a single-page application that does not require a page reload during normal use. .. swreq:: UI live signal panel :id: SWREQ_121 :status: draft :derived_from: SWARCH_111 The UI shall display live phase currents, position sensor state, the current operating mode, and any active fault, updated from the telemetry channel. .. swreq:: UI procedure trigger :id: SWREQ_122 :status: draft :derived_from: SWARCH_111 The UI shall provide an explicit trigger for the sensor health check and for the Rs measurement procedure, and shall display the returned result. .. swreq:: Host protocol parity :id: SWREQ_123 :status: draft :derived_from: SWARCH_112 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. .. swreq:: Host single-user :id: SWREQ_124 :status: draft :derived_from: SWARCH_110 The host application shall not implement user authentication or multi-user session handling. .. swreq:: Local server binds local interface :id: SWREQ_125 :status: draft :derived_from: SWARCH_110 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 ------------------------------------ .. swreq:: Single source tree, multiple targets :id: SWREQ_130 :status: draft :derived_from: SWARCH_120 The firmware source tree shall build for every supported target without modification to source files outside the HAL implementation directory. .. swreq:: Feature gating at compile time :id: SWREQ_131 :status: draft :derived_from: SWARCH_121 Optional features (CAN, encoder, resolver, FOC, scripting) shall be compiled out of builds for which they are not enabled. .. swreq:: No dynamic allocation after startup :id: SWREQ_132 :status: draft :derived_from: SWARCH_122 The firmware shall not call dynamic memory allocation routines after the startup phase has completed. Phase 2 and Phase 3 Placeholders -------------------------------- .. swreq:: Encoder reader :id: SWREQ_200 :status: placeholder :derived_from: SWARCH_023 :linked_to: MIL_042 Incremental encoder driver software. Scheduled for Phase 2 (MIL_042). .. swreq:: Resolver driver :id: SWREQ_201 :status: placeholder :derived_from: SWARCH_024 :linked_to: MIL_077 Resolver driver software. Scheduled for Phase 3 (MIL_077). .. swreq:: Ld / Lq measurement :id: SWREQ_202 :status: placeholder :derived_from: SWARCH_092 :linked_to: MIL_040 Ld / Lq measurement procedure. Scheduled for Phase 2 (MIL_040). .. swreq:: Back-EMF / Kt measurement :id: SWREQ_203 :status: placeholder :derived_from: SWARCH_093 :linked_to: MIL_041 Back-EMF and torque-constant measurement procedure. Scheduled for Phase 2 (MIL_041). .. swreq:: FOC control :id: SWREQ_204 :status: placeholder :derived_from: SWARCH_101 :linked_to: MIL_045 Field-oriented closed-loop control. Scheduled for Phase 2 (MIL_045). .. swreq:: Scripting interface :id: SWREQ_205 :status: placeholder :derived_from: SWARCH_113 :linked_to: MIL_044 Host scripting interface for measurement sequences. Scheduled for Phase 2 (MIL_044). .. swreq:: Host persistence :id: SWREQ_206 :status: placeholder :derived_from: SWARCH_114 :linked_to: MIL_047 Persistent storage of parameters and results on the host. Scheduled for Phase 2 (MIL_047). Open-Decision Placeholders -------------------------- .. swreq:: Host backend stack — pending :id: SWREQ_900 :status: placeholder :derived_from: SWARCH_900 :linked_to: DEC_002 Backend language and framework for the local web server are pending DEC_002. .. swreq:: Host link protocol — pending :id: SWREQ_901 :status: placeholder :derived_from: SWARCH_901 :linked_to: DEC_003 Final on-wire frame format and physical layer are pending DEC_003. .. swreq:: HAL strategy — pending :id: SWREQ_902 :status: placeholder :derived_from: SWARCH_014 :linked_to: DEC_005 Whether HAL implementations wrap the MCU vendor SDK or sit on registers is pending DEC_005. .. swreq:: Sensorless control — pending :id: SWREQ_903 :status: placeholder :derived_from: SWARCH_902 :linked_to: DEC_006 Sensorless observer scope is pending DEC_006. Traceability ------------ Forward links from ``swreq`` to software test cases (``TEST_*`` in :doc:`software_test_plan`) will be added as the software test plan is populated.