# Software Feature Specification

## SF-SYS: System Management

**Software Feature ID:** SF-SYS  
**Mapped System Feature:** F-SYS (System Management Features)  
**Version:** 1.0  
**Date:** 2025-02-01  

## 1. Feature Overview

The System Management software feature implements comprehensive system lifecycle control, state management, user interface, and engineering access capabilities. This feature provides the software implementation of system state management, controlled teardown mechanisms, OLED-based status indication, and debug/engineering sessions.

### 1.1 Mapped System Features

- **F-SYS-01**: System State Management
- **F-SYS-02**: Controlled Teardown Mechanism
- **F-SYS-03**: Status Indication (OLED-Based HMI)
- **F-SYS-04**: Debug & Engineering Sessions
- **F-SYS-05**: GPIO & Hardware Discipline

## 2. Static View - Component Architecture

```mermaid
graph TB
    subgraph "Application Layer"
        STM[System State Manager]
        TM[Teardown Manager]
        HMI[HMI Controller]
        ES[Engineering Session]
    end
    
    subgraph "User Interface Layer"
        OLED[OLED Display Driver]
        BTN[Button Handler]
        MENU[Menu System]
        LED[LED Controller]
    end
    
    subgraph "System Services"
        SC[System Controller]
        GM[GPIO Manager]
        PM[Power Manager]
    end
    
    subgraph "Hardware Abstraction"
        I2C[I2C Wrapper]
        GPIO[GPIO Wrapper]
        PWR[Power Hardware]
    end
    
    STM --> SC
    TM --> STM
    HMI --> OLED
    HMI --> BTN
    HMI --> MENU
    ES --> STM
    OLED --> I2C
    BTN --> GPIO
    LED --> GPIO
    SC --> GM
    SC --> PM
    GM --> GPIO
    PM --> PWR
```

### 2.1 Component Interfaces

#### 2.1.1 System State Manager Interfaces

**Provided Interfaces:**
- `ISystemStateManager`: Main state management interface
- `IStateTransition`: State transition control interface
- `ISystemStatus`: System status query interface

**Required Interfaces:**
- `ISystemController`: System control interface
- `IEventSystem`: Event notification interface
- `IDiagnosticsManager`: Diagnostic reporting interface

#### 2.1.2 HMI Controller Interfaces

**Provided Interfaces:**
- `IHMIController`: Human-machine interface control
- `IDisplayManager`: Display management interface
- `IUserInput`: User input handling interface

**Required Interfaces:**
- `IOLEDDriver`: OLED display driver interface
- `IButtonHandler`: Button input interface
- `IMenuSystem`: Menu navigation interface

## 3. Dynamic View - System Management Sequences

### 3.1 System State Transition Sequence

```mermaid
sequenceDiagram
    participant TRIG as Trigger Event
    participant STM as System State Manager
    participant SC as System Controller
    participant COMP as System Components
    participant ES as Event System
    
    TRIG->>STM: requestStateTransition(new_state)
    STM->>STM: validateTransition(current_state, new_state)
    
    alt Valid Transition
        STM->>SC: prepareStateTransition(new_state)
        SC->>COMP: notifyStateChange(new_state)
        COMP-->>SC: transition_ready
        SC-->>STM: preparation_complete
        STM->>STM: executeStateTransition()
        STM->>ES: publishStateChangeEvent(new_state)
    else Invalid Transition
        STM->>ES: publishTransitionError(error_code)
    end
```

### 3.2 Controlled Teardown Sequence

```mermaid
sequenceDiagram
    participant STM as System State Manager
    participant TM as Teardown Manager
    participant SM as Sensor Manager
    participant DP as Data Pool
    participant CM as Communication Manager
    participant PM as Persistence Manager
    
    STM->>TM: initiateTeardown(reason)
    TM->>SM: stopSensorAcquisition()
    SM-->>TM: acquisition_stopped
    TM->>DP: flushDataBuffers()
    DP->>PM: persistCriticalData()
    PM-->>DP: data_persisted
    DP-->>TM: buffers_flushed
    TM->>CM: closeCommunicationSessions()
    CM-->>TM: sessions_closed
    TM->>TM: releaseHardwareResources()
    TM-->>STM: teardownComplete()
    STM->>STM: enterTargetState()
```

### 3.3 OLED HMI Interaction Sequence

```mermaid
sequenceDiagram
    participant USER as User
    participant BTN as Button Handler
    participant HMI as HMI Controller
    participant MENU as Menu System
    participant OLED as OLED Driver
    participant STM as System State Manager
    
    USER->>BTN: pressButton(SELECT)
    BTN->>HMI: onButtonPress(SELECT)
    HMI->>MENU: enterMenu()
    MENU->>OLED: displayMenu(menu_items)
    
    USER->>BTN: pressButton(DOWN)
    BTN->>HMI: onButtonPress(DOWN)
    HMI->>MENU: navigateDown()
    MENU->>OLED: updateDisplay(selected_item)
    
    USER->>BTN: pressButton(SELECT)
    BTN->>HMI: onButtonPress(SELECT)
    HMI->>MENU: selectMenuItem()
    MENU->>STM: getSystemStatus()
    STM-->>MENU: system_status
    MENU->>OLED: displayStatus(status_data)
```

## 4. Software Constraints

### 4.1 Performance Constraints
- **SWC-SYS-001**: State transitions must complete within 500ms
- **SWC-SYS-002**: OLED display updates must complete within 100ms
- **SWC-SYS-003**: Button response time must be < 50ms

### 4.2 Resource Constraints
- **SWC-SYS-004**: System state data limited to 1KB
- **SWC-SYS-005**: OLED display buffer limited to 2KB
- **SWC-SYS-006**: Menu system limited to 10 levels deep

### 4.3 Reliability Constraints
- **SWC-SYS-007**: System state must be persistent across resets
- **SWC-SYS-008**: Teardown sequence must be atomic and uninterruptible
- **SWC-SYS-009**: HMI must remain functional during system faults

### 4.4 Hardware Constraints
- **SWC-SYS-010**: GPIO strapping pins must be avoided for general I/O
- **SWC-SYS-011**: I2C buses must have proper pull-up resistors (2.2kΩ-4.7kΩ)
- **SWC-SYS-012**: ADC1 must be used exclusively when Wi-Fi is active

## 5. Traceability Matrix - Software Requirements

| Software Requirement ID | Feature Mapping | Component | Verification Method |
|-------------------------|-----------------|-----------|-------------------|
| SWR-SYS-001 | F-SYS-01 | System State Manager | Unit Test |
| SWR-SYS-002 | F-SYS-01 | System State Manager | Unit Test |
| SWR-SYS-003 | F-SYS-01 | System State Manager | Integration Test |
| SWR-SYS-004 | F-SYS-02 | Teardown Manager | Integration Test |
| SWR-SYS-005 | F-SYS-02 | Teardown Manager | Unit Test |
| SWR-SYS-006 | F-SYS-02 | Teardown Manager | Unit Test |
| SWR-SYS-007 | F-SYS-03 | HMI Controller | Hardware Test |
| SWR-SYS-008 | F-SYS-03 | HMI Controller | Integration Test |
| SWR-SYS-009 | F-SYS-03 | HMI Controller | Unit Test |
| SWR-SYS-010 | F-SYS-03 | Menu System | Unit Test |
| SWR-SYS-011 | F-SYS-04 | Engineering Session | Integration Test |
| SWR-SYS-012 | F-SYS-04 | Engineering Session | Unit Test |
| SWR-SYS-013 | F-SYS-04 | Engineering Session | Security Test |
| SWR-SYS-014 | F-SYS-05 | GPIO Manager | Hardware Test |
| SWR-SYS-015 | F-SYS-05 | GPIO Manager | Hardware Test |
| SWR-SYS-016 | F-SYS-05 | GPIO Manager | Hardware Test |
| SWR-SYS-017 | F-SYS-05 | GPIO Manager | Documentation Review |

## 6. Implementation Notes

### 6.1 System State Machine
- States: INIT, RUNNING, WARNING, FAULT, OTA_UPDATE, MC_UPDATE, TEARDOWN, SERVICE
- State transitions validated against predefined state transition matrix
- State persistence in NVM for recovery after unexpected resets
- State change notifications broadcast via event system

### 6.2 Teardown Mechanism
- Teardown triggered by: OTA update, MC update, fatal fault, manual command
- Mandatory sequence: Stop acquisition → Flush data → Persist state → Close sessions → Release resources
- Teardown timeout protection to prevent system hang
- Teardown status reporting via diagnostics

### 6.3 OLED HMI System
- Display: 128x64 OLED via I2C (SSD1306 compatible)
- Three buttons: UP (GPIO_NUM_X), DOWN (GPIO_NUM_Y), SELECT (GPIO_NUM_Z)
- Menu structure: Main screen → Menu → Submenus → Actions
- Display content: Connectivity, system state, sensor status, time/date
- Menu items: Diagnostics, Sensors, Health, System Info

### 6.4 Engineering Access
- Local access via OLED/button interface
- Remote access via secure communication session
- Session types: Diagnostic (read-only), Debug (command execution)
- Access control integrated with security management
- Session logging for audit trail

### 6.5 GPIO Management
- Centralized GPIO allocation and management
- Strapping pin avoidance (GPIO 0, 3, 45, 46)
- I2C pull-up resistor verification (2.2kΩ-4.7kΩ @ 3.3V)
- ADC1 exclusive use when Wi-Fi active
- GPIO map documentation as single source of truth

### 6.6 Power Management
- Power state awareness and control
- Brownout detection and response
- Sleep mode management for power optimization
- Power consumption monitoring and reporting

### 6.7 Error Handling
- System state corruption detection and recovery
- HMI failure fallback mechanisms
- Teardown failure recovery procedures
- Engineering session error handling and recovery