update

2026-01-26 12:43:14 +01:00
parent c631110349
commit bedcd373f5
133 changed files with 37347 additions and 29 deletions
--- a/Design/system_design/features/[SYS]
+++ b/Design/system_design/features/[SYS]
@@ -0,0 +1,326 @@
+<macro class="toc op-uc-placeholder op-uc-toc">
+</macro>
+
+#   
+System Management Features
+
+## Sensor Hub (Sub-Hub) Scope
+
+## 1 Feature Overview
+
+The **System Management Features** provide deterministic control over the Sensor Hub’s operational lifecycle, runtime state visibility, controlled shutdown behavior, and engineering interaction capabilities.
+
+This feature group is responsible for:
+
+*   Managing system operational states and transitions
+    
+*   Ensuring safe teardown during updates or failures
+    
+*   Providing local human–machine interaction via OLED display and buttons
+    
+*   Supporting engineering/debug sessions for diagnostics and maintenance
+    
+
+These features act as the **supervisory layer** governing all other functional domains (DAQ, DQC, COM, DIAG, DATA, OTA, SEC).
+
+## 2 Scope and Assumptions
+
+**In Scope**
+
+*   ESP32-S3 Sensor Hub
+    
+*   OLED-based local UI (I2C)
+    
+*   Physical input buttons
+    
+*   Controlled state transitions and teardown
+    
+*   Debug and engineering access
+    
+
+**Out of Scope**
+
+*   Main Hub UI
+    
+*   Cloud dashboards
+    
+*   User authentication / role management
+    
+
+## 3 Sub-Feature Breakdown
+
+### 3.1 F-SYS-01: System State Management
+
+#### Description
+
+System State Management defines and controls the operational states of the Sensor Hub and governs all valid transitions between them.
+
+The system operates as a **finite state machine (FSM)** with deterministic behavior.
+
+#### Typical System States
+
+*   **INIT** – Hardware and software initialization
+    
+*   **RUNNING** – Normal sensor acquisition and communication
+    
+*   **WARNING** – Non-fatal fault detected, degraded operation
+    
+*   **FAULT** – Fatal error, core functionality disabled
+    
+*   **OTA\_UPDATE** – Firmware update in progress
+    
+*   **MC\_UPDATE** – Machine constants update in progress
+    
+*   **TEARDOWN** – Controlled shutdown sequence
+    
+*   **IDLE / SERVICE** – Engineering or diagnostic interaction
+    
+
+#### Responsibilities
+
+*   Enforce valid state transitions
+    
+*   Notify dependent components of state changes
+    
+*   Prevent unsafe operations during restricted states
+    
+
+### 3.2 F-SYS-02: Controlled Teardown Mechanism
+
+#### Description
+
+The Controlled Teardown Mechanism ensures that the Sensor Hub transitions safely from an active state into reset, update, or shutdown without data loss or corruption.
+
+Teardown is triggered by:
+
+*   Firmware update
+    
+*   Machine constant update
+    
+*   Fatal system fault
+    
+*   Manual engineering command
+    
+
+#### Teardown Sequence (Mandatory)
+
+1.  Stop sensor acquisition tasks
+    
+2.  Flush pending data via DP component
+    
+3.  Persist calibration, diagnostics, and runtime state
+    
+4.  Close communication sessions
+    
+5.  Release hardware resources
+    
+6.  Enter target state (reset, OTA, idle)
+    
+
+#### Responsibilities
+
+*   Guarantee data consistency
+    
+*   Ensure deterministic shutdown behavior
+    
+*   Prevent flash or SD corruption
+    
+
+### 3.3 F-SYS-03: Status Indication (OLED-Based HMI)
+
+#### Description
+
+The Sensor Hub provides local system visibility using an **OLED display connected via I2C**, replacing LED indicators.
+
+The display, together with **three physical buttons (Up / Down / Select)**, forms a minimal local Human–Machine Interface (HMI).
+
+#### Default Information Displayed (Main Screen)
+
+1.  **Connectivity status**
+    
+    *   Connected / Disconnected
+        
+    *   Signal strength (RSSI) if available
+        
+2.  **System status**
+    
+    *   Current system state (RUNNING, WARNING, FAULT, OTA, etc.)
+        
+3.  **Connected sensors**
+    
+    *   Count and/or summary status
+        
+4.  **Time and date**
+    
+    *   Synchronized system time
+        
+
+#### Menu Navigation Behavior
+
+*   **Select button**
+    
+    *   From main screen → opens menu
+        
+    *   From submenu → returns to main screen
+        
+*   **Up / Down buttons**
+    
+    *   Navigate menu entries
+        
+    *   Scroll within pages if applicable
+        
+
+#### Menu Structure
+
+**Main Menu**
+
+*   **Diagnostics**
+    
+    *   Lists active and stored diagnostic codes
+        
+    *   Displays occurrence count per diagnostic
+        
+*   **Sensors**
+    
+    *   Lists all detected sensors
+        
+    *   Displays sensor type and configuration status
+        
+*   **Health**
+    
+    *   Displays SD card usage
+        
+    *   Displays overall system health indicators
+        
+
+#### Responsibilities
+
+*   Provide real-time system visibility
+    
+*   Support local inspection without external tools
+    
+*   Reflect system state and diagnostics accurately
+    
+
+### 3.4 F-SYS-04: Debug &amp; Engineering Sessions
+
+#### Description
+
+Debug &amp; Engineering Sessions allow authorized engineers to interact with the Sensor Hub for diagnostics, inspection, and controlled operations.
+
+Sessions may be established via:
+
+*   Wired interface (e.g., USB/UART)
+    
+*   Secure communication channel (logical session)
+    
+
+#### Supported Capabilities
+
+*   Retrieve diagnostic logs
+    
+*   Read machine constant files
+    
+*   Inspect system state and health
+    
+*   Trigger controlled actions (e.g., reboot, teardown)
+    
+*   Monitor runtime logs
+    
+
+#### Session Types
+
+*   **Diagnostic Session** – Read-only access for inspection
+    
+*   **Debug Session** – Command execution and deeper inspection
+    
+
+## 4 Functional Interaction Overview
+
+### System State &amp; Teardown Relationship
+
+```text
+RUNNING
+   ↓ (Update / Fault)
+TEARDOWN
+   ↓
+OTA_UPDATE / MC_UPDATE / RESET
+```
+
+### Local HMI Interaction
+
+```text
+OLED Display ← System State Manager
+Buttons → UI Controller → State/Menu Logic
+```
+
+## 5 System SHALL Requirements (Formal)
+
+### System State Management
+
+*   **SR-SYS-001**: The system shall implement a defined finite state machine for operational control.
+    
+*   **SR-SYS-002**: The system shall restrict operations based on the current system state.
+    
+*   **SR-SYS-003**: The system shall notify system components of state transitions.
+    
+
+### Controlled Teardown
+
+*   **SR-SYS-004**: The system shall execute a controlled teardown sequence before firmware or machine constant updates.
+    
+*   **SR-SYS-005**: The system shall persist all critical runtime data before completing teardown.
+    
+*   **SR-SYS-006**: The system shall prevent data corruption during teardown and reset operations.
+    
+
+### Status Indication &amp; HMI
+
+*   **SR-SYS-007**: The system shall provide a local OLED display using I2C communication.
+    
+*   **SR-SYS-008**: The system shall display connectivity status, system state, sensor summary, and time/date.
+    
+*   **SR-SYS-009**: The system shall provide menu navigation using Up, Down, and Select buttons.
+    
+*   **SR-SYS-010**: The system shall provide diagnostic, sensor, and health information via the local menu.
+    
+
+### Debug &amp; Engineering Sessions
+
+*   **SR-SYS-011**: The system shall support diagnostic sessions for retrieving logs and system status.
+    
+*   **SR-SYS-012**: The system shall support debug sessions for controlled engineering operations.
+    
+*   **SR-SYS-013**: The system shall restrict debug actions to authorized sessions only.
+
+### GPIO & Hardware Discipline [NEW]
+
+*   **SR-SYS-014**: The system shall enforce GPIO discipline by avoiding strapping pins (GPIO 0, 3, 45, 46) for general-purpose I/O.
+*   **SR-SYS-015**: The system shall ensure all shared I2C buses have appropriate physical pull-up resistors (2.2kΩ - 4.7kΩ for 3.3V).
+*   **SR-SYS-016**: The system shall use ADC1 for all analog sensors when Wi-Fi is active (ADC2 is not available with Wi-Fi).
+*   **SR-SYS-017**: The system shall maintain a canonical GPIO map document as a single source of truth.
+
+## 6 Traceability Matrix
+
+| Feature ID | System Requirements |
+|------------|---------------------|
+| F-SYS-01 | SR-SYS-001, SR-SYS-002, SR-SYS-003 |
+| F-SYS-02 | SR-SYS-004, SR-SYS-005, SR-SYS-006 |
+| F-SYS-03 | SR-SYS-007, SR-SYS-008, SR-SYS-009, SR-SYS-010 |
+| F-SYS-04 | SR-SYS-011, SR-SYS-012, SR-SYS-013 |
+| F-SYS-05 | SR-SYS-014, SR-SYS-015, SR-SYS-016, SR-SYS-017 |
+
+## 7 Dependencies
+
+*   Diagnostics &amp; Health Monitoring Features
+    
+*   Persistence &amp; DP Component
+    
+*   Communication Features
+    
+*   Security &amp; Safety Features
+    
+*   OTA Features
+    
+
+##