164 lines
8.2 KiB
Markdown
164 lines
8.2 KiB
Markdown
---
|
|
name: SRS+Architecture Rollout
|
|
overview: 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.
|
|
todos:
|
|
- id: fsm-normative
|
|
content: "Define full FSM: states, transitions, guards, actions; add per-state feature permissions"
|
|
status: pending
|
|
- id: fault-model
|
|
content: Define fault taxonomy + escalation/recovery rules; map DIAG severity to state transitions
|
|
status: pending
|
|
dependencies:
|
|
- fsm-normative
|
|
- id: srs-setup
|
|
content: Create ISO/IEC/IEEE 29148 SRS structure and SWR ID scheme; decide where SWR traceability lives (CSV vs MD annex)
|
|
status: pending
|
|
dependencies:
|
|
- fsm-normative
|
|
- id: derive-swr
|
|
content: Derive SWR-* from SR-* and features; ensure testability, state preconditions, and trace links
|
|
status: pending
|
|
dependencies:
|
|
- srs-setup
|
|
- fault-model
|
|
- id: static-architecture
|
|
content: Write static architecture views (context/component/data/concurrency) aligned to repo structure and constraints
|
|
status: pending
|
|
dependencies:
|
|
- derive-swr
|
|
- id: component-specs
|
|
content: Write component specs/APIs per major component; include threading model, ownership, errors, state behavior
|
|
status: pending
|
|
dependencies:
|
|
- static-architecture
|
|
- id: vv-matrix
|
|
content: Create verification matrix mapping SWR-* to unit/integration/HIL tests with acceptance criteria
|
|
status: pending
|
|
dependencies:
|
|
- 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
|
|
|
|
```mermaid
|
|
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
|
|
```
|
|
```mermaid
|
|
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 |