ASF_01_sys_sw_arch/System Design/system_design/features/[SYS] System Management Features.md

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 & Engineering Sessions

Description

Debug & 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 & Teardown Relationship

RUNNING
   ↓ (Update / Fault)
TEARDOWN
   ↓
OTA_UPDATE / MC_UPDATE / RESET

Local HMI Interaction

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 & 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 & 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 & Health Monitoring Features

• Persistence & DP Component

• Communication Features

• Security & Safety Features

• OTA Features