ASF-Nabd/ASF_01_sys_sw_arch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

cleanup

Browse Source
This commit is contained in:
mahmamdouh
2026-01-26 12:49:12 +01:00
parent bedcd373f5
commit ff791564e4
243 changed files with 18986 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

192
system_design/features/[DATA] Persistence & Data Management Features.md Normal file
View File

@@ -0,0 +1,192 @@
<macro class="toc op-uc-placeholder op-uc-toc">
</macro>
# Feature Engineering Specification
## Persistence &amp; Data Management Features
**Feature Group ID:** FG-DATA
**Scope:** Sensor Hub (Sub-Hub only)
**Target Platform:** ESP32-S3–based Sensor Hub
**Applies To:** Indoor poultry farm sensor hubs
**Dependencies:**
* Sensor Data Acquisition (FG-DAQ)
* Data Quality &amp; Calibration (FG-DQC)
* Diagnostics &amp; Health Monitoring (FG-DIAG)
* System State Management / Teardown Mechanism
## 1\. Purpose and Objectives
The **Persistence &amp; Data Management Features** define how the Sensor Hub stores, protects, and manages critical runtime and historical data. These features ensure that:
* Sensor data and system state are not lost during resets or failures
* Data storage is abstracted from application logic
* Critical data is safely handled during firmware updates, configuration changes, or fatal faults
The persistence layer is a **foundational system service**, supporting diagnostics, calibration, OTA, and recovery operations.
## 2\. Feature Overview and Relationships
<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature ID</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Feature Name</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Primary Objective</p></th><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Related Features</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DATA-01</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Persistent Sensor Data Storage</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Store timestamped sensor data</p></td><td class="op-uc-table--cell"><p class="op-uc-p">DAQ, COM</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DATA-02</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Data Persistence Abstraction (DP)</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Abstract storage access</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Application Layer</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p">F-DATA-03</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Safe Data Handling During State Transitions</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Protect data during teardown</p></td><td class="op-uc-table--cell"><p class="op-uc-p">OTA, System Mgmt</p></td></tr></tbody></table></figure>
## 3\. Functional Feature Descriptions
### 3.1 F-DATA-01: Persistent Sensor Data Storage
**Description**
The system shall persist timestamped sensor data to non-volatile storage to support historical analysis, diagnostics correlation, and recovery scenarios.
Persistence may include:
* Filtered sensor values
* Timestamps
* Sensor validity and status metadata
The persistence policy (frequency, retention window, overwrite behavior) is configurable and optimized for storage longevity and performance.
**Key Capabilities**
* Non-volatile storage (SD card / NVM)
* Timestamped records
* Configurable retention policy
* Integration with DAQ and COM
### 3.2 F-DATA-02: Data Persistence Abstraction (DP Component)
**Description**
The system shall provide a **Data Persistence (DP) component** that abstracts storage access for all upper layers. Application and feature modules interact with the DP component rather than directly accessing storage hardware.
The DP component manages:
* Data model definitions
* Serialization and deserialization
* Storage backend selection
* Consistency and integrity guarantees
**Key Capabilities**
* Unified persistence API
* Storage backend abstraction
* Centralized data ownership
* Reduced coupling between layers
### 3.3 F-DATA-03: Safe Data Handling During State Transitions
**Description**
The system shall ensure safe and deterministic handling of data during critical state transitions, including:
* Firmware updates (OTA)
* Machine Constants updates
* System resets
* Fatal error handling
Before entering such transitions, the system executes a controlled data finalization process to flush buffers, persist critical state, and verify data integrity.
**Key Capabilities**
* Controlled data flush
* Atomic write operations
* Data integrity checks
* Coordination with teardown mechanism
## 4\. System Requirements (Formal SHALL Statements)
### 4.1 Persistent Sensor Data Storage
**SR-DATA-001**
The system shall persist timestamped sensor data in non-volatile storage.
**SR-DATA-002**
The system shall store sensor data together with sensor identifiers, timestamps, and validity status.
**SR-DATA-003**
The system shall support configurable data retention and overwrite policies.
### 4.2 Data Persistence Abstraction (DP Component)
**SR-DATA-004**
The system shall provide a Data Persistence (DP) component as the sole interface for persistent data access.
**SR-DATA-005**
The system shall prevent application and feature modules from directly accessing storage hardware.
**SR-DATA-006**
The DP component shall support serialization and deserialization of structured system data.
### 4.3 Safe Data Handling During State Transitions
**SR-DATA-007**
The system shall ensure that all critical runtime data is flushed to non-volatile storage before entering a controlled teardown or reset.
**SR-DATA-008**
The system shall protect data integrity during firmware updates and configuration changes.
**SR-DATA-009**
The system shall verify successful data persistence before completing a state transition.
### 4.4 Power-Loss Data Protection [NEW]
**SR-DATA-010**
The system shall detect brownout conditions using hardware brownout detector (BOD) at 3.0V threshold.
**SR-DATA-011**
The system shall immediately flush critical data buffers to non-volatile storage upon brownout detection.
**SR-DATA-012**
The system shall complete data flush operations within supercapacitor runtime (1-2 seconds) during brownout.
**SR-DATA-013**
The system shall implement wear-aware batch writing to prevent SD card wear.
## 5\. Feature ↔ System Requirement Mapping
| Feature ID | System Requirements |
|------------|---------------------|
| F-DATA-01 | SR-DATA-001, SR-DATA-002, SR-DATA-003 |
| F-DATA-02 | SR-DATA-004, SR-DATA-005, SR-DATA-006 |
| F-DATA-03 | SR-DATA-007, SR-DATA-008, SR-DATA-009 |
| F-DATA-04 | SR-DATA-010, SR-DATA-011, SR-DATA-012, SR-DATA-013 |
## 6\. Engineering Notes
* The DP component aligns with your **DP Stack** already defined in the architecture.
* Atomic write strategies (e.g., temp file + rename) are recommended.
* Diagnostic events should be generated on persistence failures.
* Storage wear-leveling considerations apply for SD/NVM.
##