ASF_01_sys_sw_arch/curser_plan.md

name, overview, todos

name	overview	todos
SRS+Architecture Rollout	Define a prioritized set of fixes and produce an ISO/IEC/IEEE 29148-style Software Requirements Specification for the full Sensor Hub scope, then derive static architecture views and component-level specifications with traceability back to features and system requirements.	id content status fsm-normative Define full FSM: states, transitions, guards, actions; add per-state feature permissions pending id content status dependencies fault-model Define fault taxonomy + escalation/recovery rules; map DIAG severity to state transitions pending fsm-normative id content status dependencies srs-setup Create ISO/IEC/IEEE 29148 SRS structure and SWR ID scheme; decide where SWR traceability lives (CSV vs MD annex) pending fsm-normative id content status dependencies derive-swr Derive SWR-* from SR-* and features; ensure testability, state preconditions, and trace links pending srs-setup fault-model id content status dependencies static-architecture Write static architecture views (context/component/data/concurrency) aligned to repo structure and constraints pending derive-swr id content status dependencies component-specs Write component specs/APIs per major component; include threading model, ownership, errors, state behavior pending static-architecture id content status dependencies vv-matrix Create verification matrix mapping SWR-* to unit/integration/HIL tests with acceptance criteria pending component-specs

SRS + Static Architecture + Component Design Plan (Sensor Hub)

Context and constraints

• Scope: Sensor Hub (Sub-Hub) only; Main Hub/Cloud out of scope except interfaces.
• Source of truth: Features in [System Design/Features/](System Design/Features/), system requirements in [System Design/system_requirementsand_and_traceability.csv](System Design/system_requirementsand_and_traceability.csv), review gate in [System Design/System Review Checklist.md](System Design/System Review Checklist.md).
• Standard: ISO/IEC/IEEE 29148-style SRS (per your selection).
• Non-negotiables: reliability > convenience, security mandatory, OTA fail-safe, power loss expected, SD failure assumed.

Phase 0 — Close the definition gaps (before writing SW requirements)

These are blockers because SW requirements must be testable and state-scoped.

• Define the full system FSM (normative)
  • Produce a complete state set (including missing ones like BootFailure, SdDegraded, Service, etc.) and a transition table with guards, actions, and allowed callers.
  • Tie back to SR-SYS-001..006 in the CSV.
• Define cross-feature execution rules per state (normative)
  • For each feature group (DAQ/DQC/COM/DIAG/DATA/OTA/SEC/SYS), specify allowed/forbidden actions per state.
  • Must satisfy [System Design/Features/Cross-Feature Constraints.md](System Design/Features/Cross-Feature Constraints.md) (notably CFC-ARCH-02, CFC-DATA-02, CFC-SEC-01/02, CFC-DBG-01).
• Define failure handling model (normative)
  • Fault taxonomy (info/warn/error/fatal), escalation rules, latching rules, recovery behaviors.
  • Link to DIAG requirements SR-DIAG-* and SYS state transitions.

Phase 1 — Create the SRS (ISO/IEC/IEEE 29148) for full Sensor Hub

Deliver a dedicated SRS document set that derives software requirements from the system requirements CSV.

• Create SRS structure (new docs under System Design/SRS/)
  • SRS.md (main), plus annexes for traceability, interfaces, and timing/resource budgets.
• Derive Software Requirements (SWRS) from System Requirements (SR-*)
  • For each SR-* (CSV), create one or more SWR-* that is:
    • atomic and testable
    • state-scoped (explicit state preconditions)
    • implementation-neutral (no “use mutex”, no “use FreeRTOS queue”)
  • Maintain bidirectional traceability: Feature -> SR -> SWR -> Component -> Test.
• Mandatory SRS sections (tailored for embedded)
  • Operational states and modes (normative)
  • External interfaces (Main Hub link, peer link, debug port) (normative)
  • Data model (sensor record, diagnostics record, MC dataset, persistence records) (normative)
  • Quality requirements: timing determinism, memory constraints, storage wear, power-loss behavior, security posture (normative)

Phase 2 — Static architecture (architecture views + constraints)

This converts SRS into implementable structure while enforcing separation of concerns.

• Create architecture views in [software design/components/ARCHITECTURE.md](software design/components/ARCHITECTURE.md) (or extend existing arch.md but remove non-audited claims):
  • Context view: Sensor Hub and external actors (Main Hub, SD, sensors)
  • Container/component view: align to repo structure under [software design/components/](software design/components/)
  • Data flow view: sensor data path, diagnostic path, OTA path
  • Concurrency view: tasks, priorities, ownership of blocking I/O
• Turn constraints into enforceable rules
  • Explicitly map each cross-feature constraint to architecture mechanisms (e.g., “DP is sole persistence interface”).

Phase 3 — Component specifications (design inputs, not code)

Produce component-level specs that implement SWRs without ambiguity.

• For each major component (STM, event_system, persistence, diag_task, error_handler, sensor_manager, machine_constant_manager, fw_upgrader, main_hub_apis, network_stack, diag_protocol_stack):
  • responsibilities and non-responsibilities
  • public APIs (C/C++ headers), threading model, owned resources
  • error model and diagnostics emitted
  • state dependencies (what each component does per FSM state)
  • acceptance tests per SWR

Phase 4 — Verification planning (definition-level)

• Create a V&V matrix mapping SWR-* to:
  • unit tests, integration tests, HIL/system tests
  • measurable acceptance criteria (timing, memory, recovery)

Initial ordering (what to do first)

1. FSM + transition table + per-state feature permissions (SYS backbone)
2. DP/persistence contract (data integrity backbone)
3. Diagnostics + error taxonomy + escalation rules
4. COM/OTA/SEC contracts (secure channels, OTA safety)
5. DAQ/DQC flow + timing budgets + data model
6. HMI/debug session restrictions and isolation

Mermaid artifacts to include in the docs

stateDiagram-v2
    [*] --> Init
    Init --> Running: initOk
    Init --> BootFailure: secureBootFail
    Running --> Warning: nonFatalFault
    Warning --> Running: faultCleared
    Running --> OtaPrep: otaRequestAccepted
    OtaPrep --> Teardown: beginTeardown
    Teardown --> OtaUpdate: teardownComplete
    OtaUpdate --> Running: otaSuccess
    OtaUpdate --> Fault: otaFail
    Running --> Fault: fatalFault
    Fault --> Teardown: controlledRecovery
    Teardown --> Init: reboot

flowchart TD
    Sensors-->DriversSensors
    DriversSensors-->SensorManager
    SensorManager-->EventSystem
    EventSystem-->DataPool
    DataPool-->Persistence
    DataPool-->MainHubApis
    EventSystem-->DiagTask
    DiagTask-->ErrorHandler
    ErrorHandler-->StateManager

Files that will be created/updated

• Create: System Design/SRS/SRS.md (+ annexes) and System Design/SRS/Traceability_SWRS.csv
• Update/extend: [System Design/system_requirementsand_and_traceability.csv](System Design/system_requirementsand_and_traceability.csv) to include SWR rows and links (or keep SWR in a dedicated CSV and link by IDs)
• Update/extend: [software design/components/ARCHITECTURE.md](software design/components/ARCHITECTURE.md) / arch.md to reflect audited, testable architecture views
• Create: per-component specs under software design/components/*/ARCHITECTURE.md (or SPEC.md) for each major component

Deliverables checklist

• ISO/IEC/IEEE 29148-style SRS with SWR-* requirements
• FSM + transition table + per-state execution rules
• Static architecture views (context/component/data/concurrency)
• Component specifications + API sketches (headers only, no implementation)
• Traceability matrix and initial V&V mapping