# System State Machine Specification

**Document Type:** Normative System Specification  
**Scope:** Sensor Hub (Sub-Hub) Operational States  
**Traceability:** SR-SYS-001, SR-SYS-002, SR-SYS-003

## 1. Purpose

This document defines the complete finite state machine (FSM) governing the Sensor Hub's operational lifecycle. All system components SHALL respect state-based operation restrictions as defined herein.

## 2. State Definitions

### 2.1 State Enumeration

| State ID | State Name | Description | Entry Condition |
|----------|------------|-------------|-----------------|
| `INIT` | Initialization | Hardware and software initialization phase | Power-on, reset, or post-teardown |
| `BOOT_FAILURE` | Boot Failure | Secure boot verification failed | Secure boot check failure during INIT |
| `RUNNING` | Normal Operation | Active sensor acquisition and communication | Successful initialization |
| `WARNING` | Degraded Operation | Non-fatal fault detected, degraded functionality | Non-critical fault detected during RUNNING |
| `FAULT` | Fatal Error | Critical fault, core functionality disabled | Fatal error or cascading failures |
| `OTA_PREP` | OTA Preparation | Preparing for firmware update | OTA request accepted, validation pending |
| `OTA_UPDATE` | OTA Update Active | Firmware update in progress | Firmware transfer and flashing |
| `MC_UPDATE` | Machine Constants Update | Machine constants update in progress | MC update request accepted |
| `TEARDOWN` | Controlled Shutdown | Safe shutdown sequence execution | Update, fault recovery, or manual command |
| `SERVICE` | Service Mode | Engineering/diagnostic interaction | Debug session active |
| `SD_DEGRADED` | SD Card Degraded | SD card failure detected, fallback mode | SD card access failure |

### 2.2 State Characteristics

#### INIT
- **Duration:** Bounded (max 5 seconds)
- **Allowed Operations:** Hardware initialization, secure boot verification, MC loading
- **Forbidden Operations:** Sensor acquisition, communication, persistence writes
- **Exit Conditions:** Success → RUNNING, Secure boot failure → BOOT_FAILURE

#### BOOT_FAILURE
- **Duration:** Indefinite (requires manual intervention)
- **Allowed Operations:** Diagnostic reporting, secure boot retry (limited)
- **Forbidden Operations:** All application features
- **Exit Conditions:** Manual reset, secure boot success → INIT

#### RUNNING
- **Duration:** Indefinite (normal operation)
- **Allowed Operations:** All features (DAQ, DQC, COM, DIAG, DATA, HMI)
- **Forbidden Operations:** OTA, MC update (must transition via TEARDOWN)
- **Exit Conditions:** Fault → WARNING/FAULT, OTA request → OTA_PREP, MC update → MC_UPDATE, Debug session → SERVICE

#### WARNING
- **Duration:** Until fault cleared or escalated
- **Allowed Operations:** Degraded DAQ, COM, DIAG (limited), DATA (read-only)
- **Forbidden Operations:** OTA, MC update
- **Exit Conditions:** Fault cleared → RUNNING, Fault escalated → FAULT

#### FAULT
- **Duration:** Until recovery attempt or manual intervention
- **Allowed Operations:** Diagnostic reporting, error logging, controlled teardown
- **Forbidden Operations:** Sensor acquisition, communication (except diagnostics)
- **Exit Conditions:** Recovery attempt → TEARDOWN, Manual reset → INIT

#### OTA_PREP
- **Duration:** Bounded (max 2 seconds)
- **Allowed Operations:** OTA readiness validation, teardown initiation
- **Forbidden Operations:** Sensor acquisition, new communication sessions
- **Exit Conditions:** Ready → TEARDOWN, Rejected → RUNNING

#### OTA_UPDATE
- **Duration:** Bounded (max 10 minutes)
- **Allowed Operations:** Firmware reception, validation, flashing
- **Forbidden Operations:** Sensor acquisition, normal communication, persistence (except OTA data)
- **Exit Conditions:** Success → RUNNING (after reboot), Failure → FAULT

#### MC_UPDATE
- **Duration:** Bounded (max 30 seconds)
- **Allowed Operations:** MC reception, validation, teardown
- **Forbidden Operations:** Sensor acquisition, normal communication
- **Exit Conditions:** Success → TEARDOWN, Failure → RUNNING

#### TEARDOWN
- **Duration:** Bounded (max 500ms)
- **Allowed Operations:** Data flush, resource release, state persistence
- **Forbidden Operations:** New sensor acquisition, new communication sessions
- **Exit Conditions:** Complete → INIT (reset), OTA → OTA_UPDATE, MC → MC_UPDATE

#### SERVICE
- **Duration:** Until session closed
- **Allowed Operations:** Diagnostic access, read-only inspection, controlled commands
- **Forbidden Operations:** Sensor acquisition (may be paused), OTA, MC update
- **Exit Conditions:** Session closed → RUNNING

#### SD_DEGRADED
- **Duration:** Until SD recovery or manual intervention
- **Allowed Operations:** Sensor acquisition (no persistence), communication, diagnostics
- **Forbidden Operations:** Persistence writes (except critical diagnostics)
- **Exit Conditions:** SD recovery → RUNNING, Manual intervention → SERVICE

## 3. State Transition Table

| From State | To State | Trigger | Guard Condition | Action | Authorized Caller |
|------------|----------|---------|-----------------|--------|------------------|
| `[*]` | `INIT` | Power-on, Reset | None | Initialize hardware, secure boot check | System |
| `INIT` | `RUNNING` | Init success | Secure boot OK, MC loaded, sensors detected | Start DAQ, COM, DIAG tasks | System Manager |
| `INIT` | `BOOT_FAILURE` | Secure boot fail | Secure boot verification failed | Log security fault, disable application | Secure Boot |
| `BOOT_FAILURE` | `INIT` | Manual reset | None | Reset system | User/Engineer |
| `RUNNING` | `WARNING` | Non-fatal fault | Diagnostic severity = WARNING | Degrade functionality, notify | Error Handler |
| `RUNNING` | `FAULT` | Fatal fault | Diagnostic severity = FATAL | Stop critical features | Error Handler |
| `RUNNING` | `OTA_PREP` | OTA request | OTA request received, system ready | Validate readiness | OTA Manager |
| `RUNNING` | `MC_UPDATE` | MC update request | MC update received, authenticated | Validate MC | MC Manager |
| `RUNNING` | `SERVICE` | Debug session | Debug session authenticated | Pause non-critical tasks | Debug Manager |
| `RUNNING` | `SD_DEGRADED` | SD failure | SD card access failure detected | Disable persistence writes | Persistence |
| `WARNING` | `RUNNING` | Fault cleared | Diagnostic cleared, system healthy | Restore full functionality | Error Handler |
| `WARNING` | `FAULT` | Fault escalated | Multiple warnings or critical fault | Stop degraded features | Error Handler |
| `FAULT` | `TEARDOWN` | Recovery attempt | Recovery command received | Initiate controlled shutdown | System Manager |
| `OTA_PREP` | `TEARDOWN` | OTA ready | Readiness validated | Begin teardown | OTA Manager |
| `OTA_PREP` | `RUNNING` | OTA rejected | Readiness check failed | Resume normal operation | OTA Manager |
| `TEARDOWN` | `OTA_UPDATE` | Teardown complete (OTA) | OTA pending, data flushed | Enter OTA state | System Manager |
| `TEARDOWN` | `MC_UPDATE` | Teardown complete (MC) | MC update pending, data flushed | Enter MC update | System Manager |
| `TEARDOWN` | `INIT` | Teardown complete (reset) | Reset requested, data flushed | Reset system | System Manager |
| `OTA_UPDATE` | `RUNNING` | OTA success | Firmware flashed, validated | Reboot into new firmware | OTA Manager |
| `OTA_UPDATE` | `FAULT` | OTA failure | Firmware validation failed | Log error, enter fault | OTA Manager |
| `MC_UPDATE` | `TEARDOWN` | MC update complete | MC validated, applied | Reinitialize system | MC Manager |
| `SERVICE` | `RUNNING` | Session closed | Debug session terminated | Resume normal operation | Debug Manager |
| `SD_DEGRADED` | `RUNNING` | SD recovered | SD card access restored | Re-enable persistence | Persistence |
| `SD_DEGRADED` | `SERVICE` | Manual intervention | User intervention required | Enter service mode | User/Engineer |

## 4. Per-State Feature Execution Rules

### 4.1 DAQ (Data Acquisition) Feature

| State | Allowed Operations | Restrictions |
|-------|-------------------|--------------|
| `INIT` | None | Sensor initialization only |
| `RUNNING` | Full acquisition cycle | None |
| `WARNING` | Degraded acquisition (reduced frequency) | Failed sensors excluded |
| `FAULT` | None | Acquisition stopped |
| `OTA_PREP` | None | Acquisition stopped |
| `OTA_UPDATE` | None | Acquisition stopped |
| `MC_UPDATE` | None | Acquisition stopped |
| `TEARDOWN` | None | Acquisition stopped |
| `SERVICE` | Paused (optional read-only) | No new samples |
| `SD_DEGRADED` | Full acquisition | Data not persisted |
| `BOOT_FAILURE` | None | Not applicable |

### 4.2 DQC (Data Quality & Calibration) Feature

| State | Allowed Operations | Restrictions |
|-------|-------------------|--------------|
| `INIT` | Sensor detection, MC loading | No calibration |
| `RUNNING` | Full quality checks, calibration | None |
| `WARNING` | Degraded quality checks | Reduced validation |
| `FAULT` | Error reporting only | No quality checks |
| `OTA_PREP` | None | Quality checks stopped |
| `OTA_UPDATE` | None | Quality checks stopped |
| `MC_UPDATE` | MC validation only | No sensor calibration |
| `TEARDOWN` | None | Quality checks stopped |
| `SERVICE` | Read-only inspection | No calibration |
| `SD_DEGRADED` | Full quality checks | Results not persisted |
| `BOOT_FAILURE` | None | Not applicable |

### 4.3 COM (Communication) Feature

| State | Allowed Operations | Restrictions |
|-------|-------------------|--------------|
| `INIT` | None | No communication |
| `RUNNING` | Full bidirectional communication | None |
| `WARNING` | Limited communication (diagnostics only) | Reduced bandwidth |
| `FAULT` | Diagnostic reporting only | No data transmission |
| `OTA_PREP` | OTA negotiation only | No other communication |
| `OTA_UPDATE` | OTA data transfer only | No other communication |
| `MC_UPDATE` | MC transfer only | No other communication |
| `TEARDOWN` | Session closure only | No new sessions |
| `SERVICE` | Debug session communication | No Main Hub communication |
| `SD_DEGRADED` | Full communication | Data not persisted |
| `BOOT_FAILURE` | Diagnostic reporting only | Limited communication |

### 4.4 DIAG (Diagnostics) Feature

| State | Allowed Operations | Restrictions |
|-------|-------------------|--------------|
| `INIT` | Boot diagnostics | Limited logging |
| `RUNNING` | Full diagnostics | None |
| `WARNING` | Full diagnostics | None |
| `FAULT` | Full diagnostics | None |
| `OTA_PREP` | OTA diagnostics | Limited scope |
| `OTA_UPDATE` | OTA progress diagnostics | Limited scope |
| `MC_UPDATE` | MC update diagnostics | Limited scope |
| `TEARDOWN` | Teardown diagnostics | Limited scope |
| `SERVICE` | Full diagnostics (read access) | No new diagnostics |
| `SD_DEGRADED` | Full diagnostics | Persistence limited |
| `BOOT_FAILURE` | Security diagnostics | Limited scope |

### 4.5 DATA (Persistence) Feature

| State | Allowed Operations | Restrictions |
|-------|-------------------|--------------|
| `INIT` | MC loading only | No writes |
| `RUNNING` | Full persistence | None |
| `WARNING` | Read-only, critical writes | Limited writes |
| `FAULT` | Critical diagnostics only | No sensor data writes |
| `OTA_PREP` | Read-only | No writes |
| `OTA_UPDATE` | OTA data only | No sensor data writes |
| `MC_UPDATE` | MC writes only | No sensor data writes |
| `TEARDOWN` | Critical data flush only | Authorized writes only |
| `SERVICE` | Read-only | No writes |
| `SD_DEGRADED` | Read-only (if possible) | No writes |
| `BOOT_FAILURE` | None | Not applicable |

### 4.6 OTA Feature

| State | Allowed Operations | Restrictions |
|-------|-------------------|--------------|
| `INIT` | None | OTA not active |
| `RUNNING` | OTA negotiation only | No transfer |
| `WARNING` | None | OTA blocked |
| `FAULT` | None | OTA blocked |
| `OTA_PREP` | Readiness validation | No transfer |
| `OTA_UPDATE` | Full OTA operations | None |
| `MC_UPDATE` | None | OTA blocked |
| `TEARDOWN` | None | OTA blocked |
| `SERVICE` | None | OTA blocked |
| `SD_DEGRADED` | None | OTA blocked |
| `BOOT_FAILURE` | None | OTA blocked |

### 4.7 SEC (Security) Feature

| State | Allowed Operations | Restrictions |
|-------|-------------------|--------------|
| `INIT` | Secure boot verification | Must complete before app start |
| `RUNNING` | Full security (encryption, authentication) | None |
| `WARNING` | Full security | None |
| `FAULT` | Security diagnostics | Limited operations |
| `OTA_PREP` | OTA authentication | None |
| `OTA_UPDATE` | Firmware verification | None |
| `MC_UPDATE` | MC authentication | None |
| `TEARDOWN` | Key protection | None |
| `SERVICE` | Debug authentication | None |
| `SD_DEGRADED` | Full security | None |
| `BOOT_FAILURE` | Security fault handling | Limited operations |

### 4.8 SYS (System Management) Feature

| State | Allowed Operations | Restrictions |
|-------|-------------------|--------------|
| `INIT` | State management, initialization | Limited operations |
| `RUNNING` | Full system management | None |
| `WARNING` | Degraded management | Limited operations |
| `FAULT` | Fault recovery management | Limited operations |
| `OTA_PREP` | OTA state management | Limited operations |
| `OTA_UPDATE` | OTA state management | Limited operations |
| `MC_UPDATE` | MC state management | Limited operations |
| `TEARDOWN` | Teardown execution | Limited operations |
| `SERVICE` | Service mode management | Limited operations |
| `SD_DEGRADED` | Degraded management | Limited operations |
| `BOOT_FAILURE` | Boot failure management | Limited operations |

## 5. State Transition Timing Requirements

| Transition | Maximum Duration | Justification |
|------------|------------------|---------------|
| `[*]` → `INIT` | 100ms | Power-on initialization |
| `INIT` → `RUNNING` | 5s | Hardware init, secure boot, MC load |
| `INIT` → `BOOT_FAILURE` | 2s | Secure boot verification |
| `RUNNING` → `WARNING` | 50ms | Fault detection and state change |
| `RUNNING` → `FAULT` | 50ms | Critical fault detection |
| `RUNNING` → `OTA_PREP` | 100ms | OTA request processing |
| `OTA_PREP` → `TEARDOWN` | 2s | Readiness validation |
| `TEARDOWN` → `OTA_UPDATE` | 500ms | Data flush and resource release |
| `TEARDOWN` → `INIT` | 500ms | Data flush and reset |
| `OTA_UPDATE` → `RUNNING` | 10 minutes | Firmware transfer and flashing |
| `RUNNING` → `SERVICE` | 100ms | Debug session establishment |
| `SERVICE` → `RUNNING` | 50ms | Debug session closure |

## 6. State Notification Mechanism

All state transitions SHALL notify registered components via the Event System:
- **Event Type:** `SYSTEM_STATE_CHANGED`
- **Payload:** Previous state, new state, transition reason
- **Subscribers:** All feature managers (DAQ, DQC, COM, DIAG, DATA, OTA, SEC, SYS)

## 7. Traceability

- **SR-SYS-001:** Implemented via complete FSM definition
- **SR-SYS-002:** Implemented via per-state feature execution rules
- **SR-SYS-003:** Implemented via state notification mechanism

## 8. Mermaid State Diagram

```mermaid
stateDiagram-v2
    [*] --> INIT
    INIT --> RUNNING: initSuccess
    INIT --> BOOT_FAILURE: secureBootFail
    BOOT_FAILURE --> INIT: manualReset
    RUNNING --> WARNING: nonFatalFault
    RUNNING --> FAULT: fatalFault
    RUNNING --> OTA_PREP: otaRequest
    RUNNING --> MC_UPDATE: mcUpdateRequest
    RUNNING --> SERVICE: debugSession
    RUNNING --> SD_DEGRADED: sdFailure
    WARNING --> RUNNING: faultCleared
    WARNING --> FAULT: faultEscalated
    FAULT --> TEARDOWN: recoveryAttempt
    OTA_PREP --> TEARDOWN: otaReady
    OTA_PREP --> RUNNING: otaRejected
    TEARDOWN --> OTA_UPDATE: otaPending
    TEARDOWN --> MC_UPDATE: mcPending
    TEARDOWN --> INIT: resetRequested
    OTA_UPDATE --> RUNNING: otaSuccess
    OTA_UPDATE --> FAULT: otaFailure
    MC_UPDATE --> TEARDOWN: mcComplete
    SERVICE --> RUNNING: sessionClosed
    SD_DEGRADED --> RUNNING: sdRecovered
    SD_DEGRADED --> SERVICE: manualIntervention
```
