software and system v1

1 software design/components/storage_drivers/STORAGE_DRIVERS_OVERVIEW.md

@@ -0,0 +1,168 @@
+# Storage Drivers Overview
+## ASF Sensor Hub (Sub-Hub) Embedded System
+
+**Document ID:** COMP-STORAGE-OVERVIEW-001  
+**Version:** 1.0  
+**Date:** 2025-02-01  
+**Platform:** ESP32-S3, ESP-IDF v5.4
+
+---
+
+## 1. Purpose
+
+The Storage Drivers provide hardware-specific implementations for SD Card and NVM (Non-Volatile Memory) access, abstracting ESP-IDF v5.4 storage APIs. These drivers enable Data Persistence component to access storage without direct ESP-IDF dependencies.
+
+**Primary Goal:** Enable Data Persistence to store and retrieve data from SD Card and NVM.
+
+---
+
+## 2. Storage Driver Architecture
+
+```
+Data Persistence
+    ↓
+Storage Drivers (This Layer)
+    ├─> SD Card Driver
+    └─> NVM Driver
+    ↓
+OSAL Wrappers (SPI for SD, NVS for NVM)
+    ↓
+ESP-IDF Storage APIs
+    ↓
+Hardware (SD Card, Flash)
+```
+
+---
+
+## 3. Storage Driver Components
+
+| Component ID | Component Name | Purpose | ESP-IDF Service |
+|--------------|----------------|---------|-----------------|
+| C-STORAGE-SD | SD Card Driver | SD card file system access | `driver/sdmmc_host.h`, `fatfs/vfs/esp_vfs_fat.h` |
+| C-STORAGE-NVM | NVM Driver | Non-volatile storage access | `nvs_flash.h`, `nvs.h` |
+
+---
+
+## 4. SD Card Driver
+
+### 4.1 Responsibilities
+
+- SD card initialization (SDMMC 4-bit mode)
+- FAT32 file system mounting
+- File read/write operations
+- Directory management
+- Wear-aware write management
+- SD card health monitoring
+- Error detection and recovery
+
+### 4.2 ESP-IDF Integration
+
+- Uses `sdmmc_host.h` for SDMMC interface
+- Uses `esp_vfs_fat.h` for FAT32 file system
+- SDMMC 4-bit mode for performance
+- SPI mode fallback (if needed)
+
+### 4.3 File System Structure
+
+```
+/sd/
+  ├── data/
+  │   ├── sensors/
+  │   │   └── YYYYMMDD_HHMMSS.dat
+  │   └── diagnostics/
+  │       └── diag.log
+  ├── config/
+  │   └── machine_constants.json
+  └── ota/
+      └── firmware.bin
+```
+
+---
+
+## 5. NVM Driver
+
+### 5.1 Responsibilities
+
+- NVS (Non-Volatile Storage) initialization
+- Key-value pair storage
+- Encrypted storage support
+- Namespace management
+- Data integrity verification
+- Wear leveling (handled by ESP-IDF)
+
+### 5.2 ESP-IDF Integration
+
+- Uses `nvs_flash.h` for NVS initialization
+- Uses `nvs.h` for key-value operations
+- Supports encrypted NVS partitions
+- Automatic wear leveling
+
+### 5.3 Namespace Structure
+
+- `system` - System configuration
+- `sensors` - Sensor calibration data
+- `security` - Security keys and certificates
+- `diagnostics` - Diagnostic data
+- `ota` - OTA update state
+
+---
+
+## 6. Error Handling
+
+### 6.1 SD Card Errors
+
+- Card detection failures
+- File system corruption
+- Write failures
+- Read failures
+- Card removal detection
+
+### 6.2 NVM Errors
+
+- NVS initialization failures
+- Write failures (full partition)
+- Read failures (corrupted data)
+- Namespace errors
+
+### 6.3 Error Recovery
+
+- SD card remount on error
+- NVS erase and reinitialize on corruption
+- Error reporting to Diagnostics Manager
+- State transition to SD_DEGRADED (for SD card)
+
+---
+
+## 7. Dependencies
+
+### 7.1 OSAL Dependencies
+
+- **OSAL-SPI:** SD card SPI mode (if used)
+- **OSAL-GPIO:** SD card detection pin
+
+### 7.2 Application Dependencies
+
+- **Logger:** Storage event logging
+- **Diagnostics Manager:** Error reporting
+- **Security Manager:** Encryption support
+
+---
+
+## 8. Traceability
+
+### 8.1 System Requirements
+
+- **SR-DATA-001:** Persistent sensor data storage
+- **SR-DATA-004:** Data Persistence component interface
+- **SR-DATA-012:** SD card failure handling
+
+### 8.2 Software Requirements
+
+- **SWR-DATA-001:** Persist timestamped sensor data
+- **SWR-DATA-012:** Handle SD card failures gracefully
+- **SWR-DATA-013:** Wear-aware storage management
+
+---
+
+**Document Status:** Complete  
+**Next Review:** Before implementation