Files

mahmamdouh 304371c6b8 cleanup sw req

2026-02-01 19:47:53 +01:00

7.3 KiB

Raw Blame History

Software Feature Specification

SF-DATA: Persistence & Data Management

Software Feature ID: SF-DATA
Mapped System Feature: F-DATA (Persistence & Data Management Features)
Version: 1.0
Date: 2025-02-01

1. Feature Overview

The Persistence & Data Management software feature implements secure, reliable storage and retrieval of sensor data, system configuration, and diagnostic information. This feature provides the software implementation of persistent sensor data storage, data persistence abstraction, and safe data handling during system state transitions.

1.1 Mapped System Features

F-DATA-01: Persistent Sensor Data Storage
F-DATA-02: Data Persistence Abstraction (DP Component)
F-DATA-03: Safe Data Handling During State Transitions
F-DATA-04: Power-Loss Data Protection

2. Static View - Component Architecture

graph TB
    subgraph "Application Layer"
        DP[Data Pool]
        PERS[Persistence Manager]
    end
    
    subgraph "Storage Abstraction Layer"
        SA[Storage Abstraction]
        FC[File Controller]
        DC[Data Controller]
    end
    
    subgraph "Driver Layer"
        SD[SD Card Driver]
        NVM[NVM Driver]
        FS[File System]
    end
    
    subgraph "Hardware Abstraction"
        SPI[SPI Wrapper]
        FLASH[Flash Wrapper]
    end
    
    DP --> PERS
    PERS --> SA
    SA --> FC
    SA --> DC
    FC --> FS
    DC --> FS
    FS --> SD
    FS --> NVM
    SD --> SPI
    NVM --> FLASH

2.1 Component Interfaces

2.1.1 Data Pool Interfaces

Provided Interfaces:

IDataPool: Main data storage interface
IDataQuery: Data retrieval interface
IDataSubscription: Data change notification interface

Required Interfaces:

IPersistenceManager: Persistent storage interface
IEventSystem: Event notification interface

2.1.2 Persistence Manager Interfaces

Provided Interfaces:

IPersistenceManager: Persistence management interface
IStorageHealth: Storage health monitoring interface
IDataIntegrity: Data integrity verification interface

Required Interfaces:

IStorageAbstraction: Storage layer interface
IFileSystem: File system interface
IDiagnostics: Diagnostic reporting interface

3. Dynamic View - Data Persistence Sequences

3.1 Sensor Data Storage Sequence

sequenceDiagram
    participant SM as Sensor Manager
    participant DP as Data Pool
    participant PM as Persistence Manager
    participant SA as Storage Abstraction
    participant FS as File System
    
    SM->>DP: storeSensorData(sensor_data)
    DP->>DP: validateData(sensor_data)
    DP->>PM: persistData(sensor_data)
    PM->>PM: formatRecord(sensor_data)
    PM->>SA: writeData(record)
    SA->>FS: writeFile(filename, data)
    FS-->>SA: write_result
    SA-->>PM: persistence_result
    PM-->>DP: operation_status
    DP->>DP: updateMemoryCache()

3.2 Safe Teardown Data Flush Sequence

sequenceDiagram
    participant STM as System State Manager
    participant DP as Data Pool
    participant PM as Persistence Manager
    participant SA as Storage Abstraction
    participant DIAG as Diagnostics
    
    STM->>DP: initiateTeardown()
    DP->>DP: stopDataIngestion()
    DP->>PM: flushAllBuffers()
    PM->>SA: syncAllData()
    SA->>SA: verifyDataIntegrity()
    SA-->>PM: flush_complete
    PM->>DIAG: logTeardownEvent()
    PM-->>DP: teardown_ready
    DP-->>STM: teardownComplete()

3.3 Power-Loss Protection Sequence

sequenceDiagram
    participant BOD as Brownout Detector
    participant PM as Persistence Manager
    participant DP as Data Pool
    participant SA as Storage Abstraction
    participant SC as Supercapacitor
    
    BOD->>PM: brownoutDetected()
    PM->>DP: emergencyFlush()
    DP->>PM: getCriticalData()
    PM->>SA: writeEmergencyData(critical_data)
    SA->>SA: fastWrite(data)
    Note over SC: Supercapacitor provides 1-2s runtime
    SA-->>PM: emergency_write_complete
    PM->>PM: enterSafeShutdown()

4. Software Constraints

4.1 Performance Constraints

SWC-DATA-001: Data write operations must complete within 50ms for normal operation
SWC-DATA-002: Emergency data flush must complete within 1 second during brownout
SWC-DATA-003: Data retrieval operations must not block sensor acquisition

4.2 Resource Constraints

SWC-DATA-004: Maximum data buffer size limited to 32KB per data type
SWC-DATA-005: File system operations limited to 10 concurrent handles
SWC-DATA-006: Storage wear-leveling must be implemented for SD card longevity

4.3 Reliability Constraints

SWC-DATA-007: Data integrity verification required for all write operations
SWC-DATA-008: Atomic write operations must be used to prevent corruption
SWC-DATA-009: Storage health monitoring must detect and report failures

4.4 Security Constraints

SWC-DATA-010: Sensitive data must be encrypted before storage
SWC-DATA-011: Data access must be controlled through defined interfaces only
SWC-DATA-012: Storage tampering detection mechanisms required

5. Traceability Matrix - Software Requirements

Software Requirement ID	Feature Mapping	Component	Verification Method
SWR-DATA-001	F-DATA-01	Persistence Manager	Integration Test
SWR-DATA-002	F-DATA-01	Data Pool	Unit Test
SWR-DATA-003	F-DATA-01	Persistence Manager	Unit Test
SWR-DATA-004	F-DATA-02	Data Pool	Unit Test
SWR-DATA-005	F-DATA-02	Storage Abstraction	Unit Test
SWR-DATA-006	F-DATA-02	Persistence Manager	Unit Test
SWR-DATA-007	F-DATA-03	Persistence Manager	Integration Test
SWR-DATA-008	F-DATA-03	Data Pool	Unit Test
SWR-DATA-009	F-DATA-03	Storage Abstraction	Unit Test
SWR-DATA-010	F-DATA-04	Persistence Manager	Hardware Test
SWR-DATA-011	F-DATA-04	Persistence Manager	Hardware Test
SWR-DATA-012	F-DATA-04	Storage Abstraction	Performance Test
SWR-DATA-013	F-DATA-04	Persistence Manager	Unit Test

6. Implementation Notes

6.1 Storage Architecture

Dual storage support: SD Card (primary) and NVM (backup/critical data)
File system: FAT32 for SD Card, NVS for NVM
Data organization: Time-based directories for sensor data
Retention policy: Configurable via Machine Constants

6.2 Data Integrity

CRC32 checksums for all stored data records
Atomic write operations using temporary files and rename
Regular storage health checks and bad sector detection
Automatic data recovery from backup storage when possible

6.3 Power-Loss Protection

Hardware brownout detector at 3.0V threshold
Supercapacitor provides 1-2 seconds of operation during power loss
Critical data prioritization during emergency flush
Fast write algorithms optimized for emergency scenarios

6.4 Data Organization

Sensor data: /data/sensors/YYYY/MM/DD/sensor_id.dat
Configuration: /config/machine_constants.json
Diagnostics: /logs/diagnostics/YYYY/MM/diagnostic.log
System state: /state/system_state.dat

6.5 Error Handling

Storage failures trigger diagnostic events
Automatic fallback to secondary storage medium
Data corruption detection and recovery procedures
Storage space monitoring and cleanup policies

7.3 KiB Raw Blame History