ASF_01_sys_sw_arch/1 software design/features/SF-SYS_System_Management.md

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

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

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

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

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