System Requirements
===================

Purpose
-------

This document lists the system-level requirements for the MOTSEN Tool. Every
requirement is derived from a single ``desc`` node in :doc:`system_description`
and is written as a small, testable "shall" statement so that one verification
case can later cover one requirement.

Rules used in this document:

* Each ``sysreq`` makes a single claim. Compound behaviors are split into
  multiple requirements.
* ``derived_from`` points to exactly one ``DESC_*``. If two descriptions apply,
  the requirement is split.
* Requirements that depend on an open decision use ``status: placeholder`` and
  ``linked_to:`` the relevant ``DEC_*`` in :doc:`../01_Project/project_plan`.
* Forward links to hardware/software requirements and to test cases are added
  as those documents come online; they are intentionally not stubbed here.

Top-Level Requirements
----------------------

.. sysreq:: Target motor class
   :id: SYS_001
   :status: draft
   :derived_from: DESC_001

   MOTSEN shall operate on three-phase permanent-magnet synchronous motors
   (PMSM, IPMSM) and brushless DC motors (BLDC).

.. sysreq:: Results presented on the host PC
   :id: SYS_002
   :status: draft
   :derived_from: DESC_001

   MOTSEN shall present every measurement and diagnostic result through the
   host PC user interface.

.. sysreq:: MVP operating envelope
   :id: SYS_003
   :status: draft
   :derived_from: DESC_001

   MOTSEN shall operate from a DC bus in the 12–24 V range with an output below
   100 W for the Phase 1 (MVP) target.

System Context
--------------

.. sysreq:: Single-user single-PC operation
   :id: SYS_010
   :status: draft
   :derived_from: DESC_010

   MOTSEN shall be operable by a single user from a single host PC.

.. sysreq:: No external lab instruments required
   :id: SYS_011
   :status: draft
   :derived_from: DESC_010

   MOTSEN shall perform its specified functions without requiring any external
   laboratory instrument (oscilloscope, LCR meter, power analyzer, signal
   generator).

.. sysreq:: No remote connectivity required
   :id: SYS_012
   :status: draft
   :derived_from: DESC_011

   MOTSEN shall provide every feature without requiring a network or cloud
   connection.

Power Stage Requirements
------------------------

.. sysreq:: Three-phase drive
   :id: SYS_030
   :status: draft
   :derived_from: DESC_030

   The power stage shall drive three motor phases from the DC bus.

.. sysreq:: Center-aligned PWM with dead-time
   :id: SYS_031
   :status: draft
   :derived_from: DESC_030

   The power stage shall be driven by center-aligned PWM with a configurable
   dead-time on each half-bridge.

.. sysreq:: PWM synchronized to ADC sampling
   :id: SYS_032
   :status: draft
   :derived_from: DESC_030

   PWM generation shall be synchronized with ADC sampling such that phase
   currents are sampled at a defined point within the PWM cycle.

.. sysreq:: Configurable PWM frequency
   :id: SYS_033
   :status: placeholder
   :derived_from: DESC_030
   :linked_to: DEC_001

   The PWM frequency shall be configurable. The supported range is a
   placeholder pending eval-board selection (DEC_001).

.. sysreq:: Fast output disable
   :id: SYS_034
   :status: draft
   :derived_from: DESC_030

   On output-disable, the power stage shall return all three phases to a
   high-impedance state within one PWM period.

Sensing Requirements
--------------------

.. sysreq:: Phase current measurement
   :id: SYS_040
   :status: draft
   :derived_from: DESC_031

   MOTSEN shall measure the current in each motor phase.

.. sysreq:: PWM-synchronous current sampling
   :id: SYS_041
   :status: draft
   :derived_from: DESC_031

   Phase currents shall be sampled synchronously with the PWM cycle.

.. sysreq:: DC-bus voltage measurement
   :id: SYS_042
   :status: draft
   :derived_from: DESC_031

   MOTSEN shall measure the DC-bus voltage.

.. sysreq:: DC-bus over/under-voltage supervision
   :id: SYS_043
   :status: draft
   :derived_from: DESC_031

   MOTSEN shall trip a fault when the DC-bus voltage falls below or exceeds
   firmware-configurable thresholds.

.. sysreq:: Sensing chain calibrated before characterization
   :id: SYS_044
   :status: draft
   :derived_from: DESC_031

   MOTSEN shall not report a characterization result before the sensing chain
   has been calibrated against a reference for the current session or stored
   calibration.

Position Sensor Requirements
----------------------------

.. sysreq:: Hall sensor readout
   :id: SYS_050
   :status: draft
   :derived_from: DESC_032

   MOTSEN shall read the state of each Hall sensor input.

.. sysreq:: Hall decoding to sector and direction
   :id: SYS_051
   :status: draft
   :derived_from: DESC_032

   MOTSEN shall decode Hall states into a 6-state commutation sector and an
   inferred direction of rotation.

.. sysreq:: Incremental encoder support
   :id: SYS_052
   :status: placeholder
   :derived_from: DESC_032
   :linked_to: MIL_042

   MOTSEN shall read an incremental encoder alongside Hall sensors. Scheduled
   for Phase 2 (MIL_042).

.. sysreq:: Resolver support
   :id: SYS_053
   :status: placeholder
   :derived_from: DESC_032
   :linked_to: MIL_077

   MOTSEN shall read a resolver. Scheduled for Phase 3 (MIL_077).

.. sysreq:: Detect disconnected position sensor
   :id: SYS_054
   :status: draft
   :derived_from: DESC_032

   MOTSEN shall detect a missing or disconnected position sensor and report it
   as a sensor-check failure.

Embedded Controller Requirements
--------------------------------

.. sysreq:: HAL coverage
   :id: SYS_060
   :status: draft
   :derived_from: DESC_033

   The firmware shall provide a hardware abstraction layer covering GPIO, UART,
   timer, ADC, and PWM peripherals.

.. sysreq:: MVP target MCU
   :id: SYS_061
   :status: draft
   :derived_from: DESC_033

   The Phase 1 (MVP) firmware shall run on the NXP S32K322 MCU.

.. sysreq:: Second MCU support
   :id: SYS_062
   :status: placeholder
   :derived_from: DESC_033
   :linked_to: MIL_048

   The firmware shall support a second MCU family without modification to
   application-layer code. Scheduled for Phase 2 (MIL_048).

.. sysreq:: HAL implementation strategy
   :id: SYS_063
   :status: placeholder
   :derived_from: DESC_033
   :linked_to: DEC_005

   The HAL implementation strategy (NXP RTD/SDK wrap vs thin register layer)
   is pending DEC_005.

Safety & Protection Requirements
--------------------------------

.. sysreq:: Firmware current limit always active
   :id: SYS_070
   :status: draft
   :derived_from: DESC_034

   The firmware shall enforce a configured current limit at all times while
   PWM output is enabled.

.. sysreq:: PWM disabled on fault within one control cycle
   :id: SYS_071
   :status: draft
   :derived_from: DESC_034

   On any detected fault, the firmware shall disable PWM output within one
   control cycle.

.. sysreq:: Independent hardware overcurrent latch
   :id: SYS_072
   :status: draft
   :derived_from: DESC_034

   A hardware overcurrent latch shall trip the PWM outputs independently of
   the firmware control loop.

.. sysreq:: Explicit fault acknowledgement
   :id: SYS_073
   :status: draft
   :derived_from: DESC_034

   The system shall exit the Fault state only after an explicit acknowledgement
   from the user.

.. sysreq:: Power-on safe state
   :id: SYS_074
   :status: draft
   :derived_from: DESC_034

   On power-on, the system shall enter the Idle / Safe state with PWM disabled.

.. sysreq:: Sensor-check excitation current cap
   :id: SYS_075
   :status: draft
   :derived_from: DESC_034

   In Sensor Check mode, excitation current shall be limited to a value below
   the configured Run-mode current limit.

Host Communication Link Requirements
------------------------------------

.. sysreq:: Parameter read/write
   :id: SYS_080
   :status: draft
   :derived_from: DESC_035

   The host link shall provide read and write access to firmware parameters.

.. sysreq:: Telemetry streaming
   :id: SYS_081
   :status: draft
   :derived_from: DESC_035

   The host link shall provide a streaming telemetry channel for live signals.

.. sysreq:: Host-link disconnect forces Idle
   :id: SYS_082
   :status: draft
   :derived_from: DESC_035

   On loss of the host link, the firmware shall transition the tool to the
   Idle / Safe state.

.. sysreq:: Host-link physical and framing layer
   :id: SYS_083
   :status: placeholder
   :derived_from: DESC_035
   :linked_to: DEC_003

   The physical layer (UART vs USB-CDC) and the on-wire frame format are
   pending DEC_003.

.. sysreq:: CAN interface
   :id: SYS_084
   :status: placeholder
   :derived_from: DESC_035
   :linked_to: MIL_043; DEC_004

   MOTSEN shall provide a CAN interface. Scheduled for Phase 2 (MIL_043);
   inclusion in Phase 1 is pending DEC_004.

Host Application Requirements
-----------------------------

.. sysreq:: Local web server serves the UI
   :id: SYS_090
   :status: draft
   :derived_from: DESC_036

   The host application shall serve the user interface from a local web server
   running on the host PC.

.. sysreq:: Live phase current display
   :id: SYS_091
   :status: draft
   :derived_from: DESC_036

   The UI shall display live phase currents.

.. sysreq:: Live position sensor display
   :id: SYS_092
   :status: draft
   :derived_from: DESC_036

   The UI shall display the live state of the active position sensor.

.. sysreq:: Parameter editing from UI
   :id: SYS_093
   :status: draft
   :derived_from: DESC_036

   The UI shall allow the user to read and edit firmware parameters and apply
   them to the running firmware.

.. sysreq:: Single-user, no authentication
   :id: SYS_094
   :status: draft
   :derived_from: DESC_036

   The host application shall be single-user and shall not require
   authentication.

.. sysreq:: Mode and fault display
   :id: SYS_095
   :status: draft
   :derived_from: DESC_036

   The UI shall display the current operating mode and any active fault.

.. sysreq:: Scripting interface
   :id: SYS_096
   :status: placeholder
   :derived_from: DESC_036
   :linked_to: MIL_044

   The host application shall expose a scriptable interface for running
   measurement sequences without manual UI interaction. Scheduled for Phase 2
   (MIL_044).

.. sysreq:: Persistent parameter and result storage
   :id: SYS_097
   :status: placeholder
   :derived_from: DESC_036
   :linked_to: MIL_047

   The host application shall persist motor parameters and measurement results
   to the host filesystem. Scheduled for Phase 2 (MIL_047).

Measurement & Characterization Requirements
-------------------------------------------

.. sysreq:: Measure phase resistance Rs
   :id: SYS_100
   :status: draft
   :derived_from: DESC_037

   MOTSEN shall measure motor phase resistance Rs.

.. sysreq:: Rs accuracy against reference motor
   :id: SYS_101
   :status: draft
   :derived_from: DESC_037

   The Rs result shall agree with a reference motor measurement within a
   documented tolerance.

.. sysreq:: Detect incorrect phase sequence
   :id: SYS_102
   :status: draft
   :derived_from: DESC_037

   The sensor health check shall detect an incorrect phase sequence and report
   it as a failure with a clear diagnostic message.

.. sysreq:: Detect Hall misalignment
   :id: SYS_103
   :status: draft
   :derived_from: DESC_037

   The sensor health check shall detect Hall sensor misalignment and report it
   as a failure with a clear diagnostic message.

.. sysreq:: Sensor health check end-to-end from UI
   :id: SYS_104
   :status: draft
   :derived_from: DESC_037

   The sensor health check shall run end-to-end on a real motor when triggered
   from the host UI and shall report a pass/fail result back to the UI.

.. sysreq:: Measure Ld and Lq
   :id: SYS_105
   :status: placeholder
   :derived_from: DESC_037
   :linked_to: MIL_040

   MOTSEN shall measure D-axis and Q-axis inductances Ld and Lq. Scheduled
   for Phase 2 (MIL_040).

.. sysreq:: Measure back-EMF / torque constant
   :id: SYS_106
   :status: placeholder
   :derived_from: DESC_037
   :linked_to: MIL_041

   MOTSEN shall measure the back-EMF constant and torque constant Kt.
   Scheduled for Phase 2 (MIL_041).

Operating Mode Requirements
---------------------------

.. sysreq:: Defined mode set
   :id: SYS_110
   :status: draft
   :derived_from: DESC_040

   MOTSEN shall expose exactly five operating modes to the user: Idle / Safe,
   Sensor Check, Characterization, Run, and Fault.

.. sysreq:: Firmware-enforced transitions
   :id: SYS_111
   :status: draft
   :derived_from: DESC_040

   All operating-mode transitions shall be enforced by the firmware. UI
   actions request transitions; firmware decides whether to grant them.

.. sysreq:: Fault preempts all modes
   :id: SYS_112
   :status: draft
   :derived_from: DESC_040

   On any detected fault, the system shall transition immediately to the Fault
   state from any source mode.

.. sysreq:: Fault exit requires acknowledgement
   :id: SYS_113
   :status: draft
   :derived_from: DESC_040

   The system shall exit Fault only into Idle / Safe, and only after explicit
   user acknowledgement.

.. sysreq:: No direct Characterization to Run
   :id: SYS_114
   :status: draft
   :derived_from: DESC_040

   The system shall not transition directly between Characterization and Run.
   Any such transition shall pass through Idle / Safe.

.. sysreq:: Phase 1 Run is open-loop
   :id: SYS_115
   :status: placeholder
   :derived_from: DESC_040
   :linked_to: MIL_045

   Phase 1 Run mode shall be open-loop commutation only. FOC closed-loop
   control is scheduled for Phase 2 (MIL_045).

Open-Decision Placeholders
--------------------------

These requirements are intentionally redundant with the placeholder
descriptions in :doc:`system_description` so that the open decisions are
visible from both sides.

.. sysreq:: Final power-stage ratings — pending
   :id: SYS_120
   :status: placeholder
   :derived_from: DESC_060
   :linked_to: DEC_001

   Final voltage range, continuous/peak current, switching frequency, and gate
   driver topology are pending DEC_001 (eval board selection).

.. sysreq:: Host-link physical & framing — pending
   :id: SYS_121
   :status: placeholder
   :derived_from: DESC_061
   :linked_to: DEC_003

   Host-link physical layer and frame format are pending DEC_003.

.. sysreq:: Host backend stack — pending
   :id: SYS_122
   :status: placeholder
   :derived_from: DESC_062
   :linked_to: DEC_002

   Backend language and framework for the local web server are pending
   DEC_002.

.. sysreq:: HAL strategy — pending
   :id: SYS_123
   :status: placeholder
   :derived_from: DESC_063
   :linked_to: DEC_005

   HAL implementation strategy is pending DEC_005.

.. sysreq:: CAN scope — pending
   :id: SYS_124
   :status: placeholder
   :derived_from: DESC_064
   :linked_to: DEC_004

   Whether CAN is in Phase 1 or strictly Phase 2 is pending DEC_004.

.. sysreq:: Sensorless control scope — pending
   :id: SYS_125
   :status: placeholder
   :derived_from: DESC_065
   :linked_to: DEC_006

   Whether sensorless control is in scope, and for which phase, is pending
   DEC_006.

.. sysreq:: License & publication policy — pending
   :id: SYS_126
   :status: placeholder
   :derived_from: DESC_066
   :linked_to: DEC_007

   License selection and publication policy are pending DEC_007.

Traceability
------------

Each ``sysreq`` above declares ``derived_from:`` exactly one ``DESC_*`` node in
:doc:`system_description`. Forward links downward will be added as the
following documents come online:

* ``implemented_by:`` to ``HWREQ_*`` and ``SWREQ_*`` once
  :doc:`../03_Hardware/hardware_requirements` and
  :doc:`../04_Software/software_requirements` are populated.
* ``verified_by:`` to ``TEST_*`` once :doc:`system_test_plan` is populated.

Placeholder requirements (``status: placeholder``) close in two ways:

* By closure of their referenced ``DEC_*`` (an architectural decision is made),
  at which point the requirement is rewritten to a concrete ``shall`` and the
  status moves to ``draft``.
* By their referenced ``MIL_*`` becoming active in the current phase, at which
  point the placeholder requirement becomes a real requirement for that phase.