analysis

2026-01-25 17:17:08 +01:00
parent edd3e96591
commit 0daead7821
21 changed files with 1636 additions and 11 deletions
--- a/Documentation/01_Communication_Architecture.md
+++ b/Documentation/01_Communication_Architecture.md
@@ -0,0 +1,39 @@
+# 1. Communication Architecture
+
+## Overview
+The communication architecture for the ASF project is designed to be industrial-grade, ensuring reliability, low latency, and high throughput for critical operations like Over-the-Air (OTA) updates and real-time monitoring.
+
+## Primary & Secondary Communication Stack
+The system utilizes a multi-layered communication approach to ensure connectivity even in challenging environments.
+
+| Role | Technology | Why (Industrial Rationale) |
+| :--- | :--- | :--- |
+| **Primary Uplink** | **Wi-Fi 802.11n (2.4 GHz)** | Leverages existing infrastructure and provides high throughput necessary for OTA updates. |
+| **Peer-to-Peer** | **ESP-NOW** | Provides deterministic, low-latency communication without dependency on an Access Point (AP). |
+| **Long-range Fallback** | **LoRa (External Module)** | Ensures resilience at farm-scale distances where Wi-Fi may not reach. |
+
+> **Note:** Zigbee on ESP32-S3 is currently not considered industrial-mature in ESP-IDF. ESP-NOW is the preferred choice for reliable peer-to-peer communication.
+
+## Application Protocol
+To avoid the pitfalls of raw TCP sockets or unversioned custom protocols, the system adopts **MQTT over TLS 1.2**.
+
+| Item | Decision |
+| :--- | :--- |
+| **Broker** | Main Hub / Edge Gateway |
+| **QoS** | QoS 1 (At least once delivery) |
+| **Retain** | Used for configuration topics only |
+| **Payload** | CBOR (Binary, versioned for efficiency and compatibility) |
+| **Topic Model** | `/farm/{site}/{house}/{node}/...` |
+
+### Why MQTT?
+* **Store-and-Forward:** Handles intermittent connectivity gracefully.
+* **Built-in Keepalive:** Monitors connection health automatically.
+* **Industrial Tooling:** Compatible with standard monitoring and management tools.
+* **Native Support:** Stable implementation within the ESP-IDF framework.
+
+## Heartbeat & Liveness
+A formalized heartbeat mechanism is implemented to feed into predictive maintenance systems.
+
+* **Interval:** 10 seconds
+* **Timeout:** 3 missed heartbeats (30 seconds) triggers an "offline" status.
+* **Payload includes:** Uptime, firmware version, free heap memory, RSSI (signal strength), and an error bitmap.
--- a/Documentation/02_Security_Model.md
+++ b/Documentation/02_Security_Model.md
@@ -0,0 +1,36 @@
+# 2. Security Model
+
+## Overview
+Security is a non-negotiable requirement for industrial systems. The ASF project leverages the hardware security features of the ESP32-S3 to establish a robust Root of Trust and secure communication channels.
+
+## Root of Trust
+The following features are mandatory to ensure the integrity of the device and its firmware:
+
+*   **Secure Boot V2:** Ensures only digitally signed firmware can run on the device.
+*   **Flash Encryption:** Protects the firmware and sensitive data stored in flash memory from physical access.
+*   **eFuse-based Anti-rollback:** Prevents the installation of older, potentially vulnerable firmware versions.
+
+> **Industrial Standard:** These features are the baseline for any production-ready industrial embedded system.
+
+## Device Identity & Authentication
+A unique identity for each device is established using X.509 certificates and mutual TLS (mTLS).
+
+| Item | Implementation |
+| :--- | :--- |
+| **Identity** | Device-unique X.509 certificate |
+| **Private Key** | Stored securely in eFuse or encrypted flash |
+| **Authentication** | Mutual TLS (mTLS) for all broker communications |
+| **Provisioning** | Handled via a secure factory or onboarding mode |
+
+### Key Insight
+The ESP32-S3 is optimized to handle a single device certificate efficiently. It is recommended to avoid managing large certificate chains on the device itself to conserve resources.
+
+## Key Lifecycle Management
+The lifecycle of security keys is managed from manufacturing through operation and eventual revocation.
+
+| Phase | Mechanism |
+| :--- | :--- |
+| **Manufacturing** | Injection of the unique device certificate and private key. |
+| **Operation** | Use of TLS session keys for encrypted communication. |
+| **Rotation** | Certificate rotation managed on the broker/server side. |
+| **Revocation** | Use of Certificate Revocation Lists (CRL) or broker-side denylists. |
--- a/Documentation/03_OTA_Strategy.md
+++ b/Documentation/03_OTA_Strategy.md
@@ -0,0 +1,36 @@
+# 3. OTA Strategy
+
+## Overview
+Over-the-Air (OTA) updates are critical for maintaining and improving industrial devices in the field. The ASF strategy focuses on safety, reliability, and automatic recovery from failed updates.
+
+## Partition Layout
+For a device with **8MB of flash**, the following partition layout is recommended to support safe OTA updates:
+
+| Partition | Size | Purpose |
+| :--- | :--- | :--- |
+| **bootloader** | - | Initial boot code |
+| **partition_table** | - | Defines the flash layout |
+| **factory** | - | Optional minimal rescue firmware |
+| **ota_0** | 3.5 MB | Primary application slot |
+| **ota_1** | 3.5 MB | Secondary application slot for updates |
+| **nvs** | 64 KB | Encrypted Non-Volatile Storage for config |
+| **phy_init** | - | Physical layer initialization data |
+| **coredump** | 64 KB | Storage for crash logs and debugging |
+
+## OTA Policy
+A formal policy ensures that updates are downloaded correctly and that the system can roll back if the new firmware is unstable.
+
+| Step | Rule |
+| :--- | :--- |
+| **Download** | Conducted via HTTPS or MQTT in chunks. |
+| **Chunk Size** | 4096 bytes (optimized for flash page size). |
+| **Integrity** | Verified using a full image SHA-256 hash. |
+| **Validation** | System must boot and send a health report. |
+| **Confirmation** | The application must confirm stability within 60 seconds. |
+| **Failure** | Automatic rollback to the previous known-good version. |
+
+### Closing the Gaps
+This strategy directly addresses the following gaps:
+*   **GAP-OTA-001:** Reliable image delivery.
+*   **GAP-OTA-002:** Integrity and authenticity verification.
+*   **GAP-OTA-003:** Safe rollback mechanisms.
--- a/Documentation/04_Sensor_Data_Acquisition.md
+++ b/Documentation/04_Sensor_Data_Acquisition.md
@@ -0,0 +1,40 @@
+# 4. Sensor & Data Acquisition
+
+## Overview
+Reliable data acquisition is the core of the ASF system. The strategy focuses on abstraction, redundancy, and data validation to ensure that the system operates on accurate information.
+
+## Sensor Abstraction Layer (SAL)
+To ensure long-term maintainability and the ability to swap hardware components, a Sensor Abstraction Layer is implemented. Every sensor driver must implement the following interface:
+
+*   `sensor_read()`: Retrieve the latest value.
+*   `sensor_calibrate()`: Perform sensor-specific calibration.
+*   `sensor_validate()`: Check if the reading is within physical bounds.
+*   `sensor_health_check()`: Verify the operational status of the hardware.
+
+## Industrial Sensor Strategy
+For critical parameters, a primary and backup sensor strategy is employed, often using different technologies or interfaces to avoid common-mode failures.
+
+### Example: CO₂ Monitoring
+| Feature | Primary Sensor | Backup Sensor |
+| :--- | :--- | :--- |
+| **Model** | Sensirion SCD41 | Senseair S8 |
+| **Interface** | I²C | UART |
+| **Calibration** | Self-calibration | Manual calibration |
+
+**Rule:** Every critical parameter must have two qualified sensor options.
+
+## Warm-Up & Validity States
+Sensors do not provide valid data immediately upon power-up. The system explicitly tracks sensor states:
+
+> **INIT** → **WARMUP** → **STABLE** → **DEGRADED** → **FAILED**
+
+Raw values are never published without an accompanying **validity flag** indicating the current state.
+
+## Data Filtering
+To ensure data stability without excessive complexity, a simple and robust filtering approach is used:
+
+1.  **Median Filter (N=5):** Removes outliers and transient noise.
+2.  **Rate-of-Change Limiter:** Prevents physically impossible jumps in values.
+3.  **Physical Bounds Check:** Rejects readings that are outside the sensor's or environment's possible range.
+
+This approach provides high reliability without the overhead of complex algorithms like Kalman filters.
--- a/Documentation/05_Data_Persistence_Reliability.md
+++ b/Documentation/05_Data_Persistence_Reliability.md
@@ -0,0 +1,29 @@
+# 5. Data Persistence & Reliability
+
+## Overview
+In industrial environments, data must be preserved even during power failures or network outages. The ASF project uses a combination of SD card storage and Non-Volatile Storage (NVS) to ensure data integrity.
+
+## SD Card Usage (Industrial Pattern)
+The SD card is used for high-volume data logging. To prevent premature wear and ensure reliability, the following patterns are followed:
+
+| Aspect | Decision |
+| :--- | :--- |
+| **File System** | FAT32 |
+| **Mode** | SDMMC 4-bit (for performance and reliability) |
+| **Structure** | Circular time-bucket files (e.g., daily logs) |
+| **Write Pattern** | Append-only to minimize directory updates |
+| **Flush Policy** | Triggered on power-loss interrupt or periodic intervals |
+
+> **Warning:** Never write small files frequently. This causes excessive wear on the SD card's flash translation layer.
+
+## NVS (Non-Volatile Storage) Rules
+The internal NVS is used for small, critical pieces of data.
+
+| Data Type | Storage Location |
+| :--- | :--- |
+| **Calibration Data** | NVS (Encrypted) |
+| **System Constants** | NVS |
+| **Counters** | RAM (with periodic commit to NVS) |
+| **System Logs** | SD Card or dedicated Flash partition |
+
+By separating high-frequency logs from critical configuration data, the system ensures that configuration remains intact even if the logging medium fails.
--- a/Documentation/06_Diagnostics_Maintainability.md
+++ b/Documentation/06_Diagnostics_Maintainability.md
@@ -0,0 +1,32 @@
+# 6. Diagnostics & Maintainability
+
+## Overview
+To support a fleet of devices, the system must provide clear diagnostics that allow for remote troubleshooting and predictive maintenance.
+
+## Diagnostic Code System
+A standardized diagnostic code system is used to categorize and report issues across the fleet.
+
+**Format: `0xSCCC`**
+*   **S:** Severity (1 = Info, 2 = Warning, 3 = Error, 4 = Critical)
+*   **CCC:** Subsystem Code
+
+| Range | Subsystem |
+| :--- | :--- |
+| **0x1xxx** | Data Acquisition (DAQ) |
+| **0x2xxx** | Communication (COM) |
+| **0x3xxx** | Security (SEC) |
+| **0x4xxx** | Over-the-Air Updates (OTA) |
+| **0x5xxx** | Hardware (HW) |
+
+This structured approach enables **fleet analytics**, allowing operators to identify patterns of failure across many devices.
+
+## Layered Watchdogs
+To ensure the system remains responsive, multiple levels of watchdogs are implemented:
+
+| Watchdog | Purpose | Baseline Timeout |
+| :--- | :--- | :--- |
+| **Task WDT** | Detects deadlocks in specific FreeRTOS tasks. | 10 seconds |
+| **Interrupt WDT** | Detects hangs within Interrupt Service Routines (ISRs). | 3 seconds |
+| **RTC WDT** | Provides a final safety net for total system freezes. | 30 seconds |
+
+These layered watchdogs ensure that the device can recover automatically from software glitches or hardware-induced hangs.
--- a/Documentation/07_Power_Fault_Handling.md
+++ b/Documentation/07_Power_Fault_Handling.md
@@ -0,0 +1,21 @@
+# 7. Power & Fault Handling
+
+## Overview
+Farms are harsh environments with unstable power. The ASF system is designed to handle brownouts and sudden power losses gracefully.
+
+## Brownout & Power Loss Management
+The system monitors the input voltage and takes immediate action if it drops below a safe threshold.
+
+| Feature | Implementation |
+| :--- | :--- |
+| **Brownout Detect** | Set at 3.0 V |
+| **ISR Action** | Set a "Power Loss" flag and immediately flush critical buffers to NVS/SD. |
+| **Recovery** | Perform a clean reboot once power is stable. |
+
+## Hardware Recommendations for Resilience
+To further improve reliability in the field, the following hardware additions are recommended:
+
+*   **Supercapacitor:** Provides 1–2 seconds of additional runtime after power loss, allowing for a graceful shutdown and data flush.
+*   **External RTC Battery:** Ensures the system clock remains accurate even during extended power outages, which is critical for time-stamped logging.
+
+By anticipating power issues, the system prevents data corruption and ensures a predictable recovery process.
--- a/Documentation/08_GPIO_Hardware_Discipline.md
+++ b/Documentation/08_GPIO_Hardware_Discipline.md
@@ -0,0 +1,20 @@
+# 8. GPIO & Hardware Discipline
+
+## Overview
+Proper hardware discipline is essential to prevent intermittent failures and ensure that the ESP32-S3 operates within its design limits.
+
+## Mandatory Rules
+The following rules must be strictly followed during hardware design and firmware configuration:
+
+1.  **No Strapping Pins:** Avoid using strapping pins (GPIO 0, 3, 45, 46) for general-purpose I/O that could interfere with the boot process.
+2.  **I²C Pull-up Audit:** Ensure all shared I²C buses have appropriate physical pull-up resistors. Do not rely solely on internal pull-ups for industrial reliability.
+3.  **No ADC2 with Wi-Fi:** The ADC2 unit cannot be used when Wi-Fi is active. All analog sensors must be connected to ADC1 pins.
+
+## Canonical GPIO Map
+A single, authoritative GPIO map document must be maintained. This document serves as the "source of truth" for both hardware engineers and firmware developers, preventing pin conflicts and ensuring consistent behavior across hardware revisions.
+
+| Pin | Function | Direction | Notes |
+| :--- | :--- | :--- | :--- |
+| ... | ... | ... | ... |
+
+By adhering to these disciplines, the project avoids the "maker-grade" shortcuts that often lead to unreliable performance in production environments.
--- a/Documentation/08_GPIO_Hardware_Discipline.md,text_
+++ b/Documentation/08_GPIO_Hardware_Discipline.md,text_
@@ -0,0 +1 @@
+
--- a/Documentation/09_System_Evolution.md
+++ b/Documentation/09_System_Evolution.md
@@ -0,0 +1,27 @@
+# 9. System Evolution: Prototype to Industrial
+
+## Overview
+The ASF project is transitioning from a functional prototype to an industrial-grade embedded product. This document summarizes the current state and the value added by the new architectural decisions.
+
+## Current Status
+The project already possesses a strong foundation:
+*   **Good Functional Coverage:** The core requirements are well-understood and implemented.
+*   **Clear System Intent:** The goals of the system are well-defined.
+*   **Excellent Hardware Choice:** The ESP32-S3 provides the necessary performance and security features.
+
+## Industrial Enhancements
+The proposed architecture adds the following critical layers:
+
+| Enhancement | Benefit |
+| :--- | :--- |
+| **Determinism** | Predictable behavior under all operating conditions. |
+| **Security Maturity** | Protection against physical and network-based threats. |
+| **Fleet-scale Maintainability** | Tools and patterns for managing thousands of devices. |
+| **Industrial Fault Tolerance** | Graceful handling of power, network, and sensor failures. |
+
+## Next Steps
+To continue the evolution of the ASF system, the following activities are recommended:
+1.  **Formal System Architecture Diagram:** Visualizing the data flow and component interactions.
+2.  **FreeRTOS Task Model:** Defining the priority and resource allocation for all software tasks.
+3.  **Factory Provisioning Workflow:** Automating the secure injection of identities and configuration.
+4.  **ESP-IDF Component Mapping:** Translating these architectural decisions into specific Kconfig options and code modules.
--- a/Documentation/Factory
+++ b/Documentation/Factory
@@ -0,0 +1,56 @@
+# Factory Provisioning Workflow
+
+## Overview
+The factory provisioning workflow is the process of preparing a "blank" ESP32-S3 module for use in the field. This process must be secure, automated, and repeatable to ensure every device has a unique identity and the correct security settings.
+
+## The Workflow Steps
+
+### Phase 1: Hardware Preparation & Initial Flash
+1.  **Connect Device:** The blank module is placed in a programming fixture.
+2.  **Flash Bootloader & Partition Table:** The basic structure of the flash memory is defined.
+3.  **Flash Factory Firmware:** A minimal "testing" firmware is loaded to verify hardware functionality (GPIOs, Sensors, Wi-Fi).
+
+### Phase 2: Security & Identity Injection
+1.  **Generate Unique Keys:** The provisioning PC generates a unique private key and a Certificate Signing Request (CSR) for the device.
+2.  **Sign Certificate:** The CSR is sent to the company's Certificate Authority (CA), which returns a signed X.509 certificate.
+3.  **Inject Identity:** The unique certificate and private key are written to the device's **NVS (Encrypted)** or **eFuse** area.
+4.  **Burn eFuses:**
+    *   Enable **Flash Encryption**.
+    *   Enable **Secure Boot**.
+    *   Set the **Secure Boot Public Key Hash**.
+    *   Disable JTAG (to prevent physical debugging/hacking).
+
+### Phase 3: Final Application Loading
+1.  **Flash Production Firmware:** The full ASF application is loaded into the `ota_0` partition.
+2.  **Verify Integrity:** The system performs a full boot-up test to ensure it can decrypt the flash and verify the secure boot signature.
+
+### Phase 4: Cloud Registration
+1.  **Register Serial Number:** The device's unique ID (MAC address or Serial) and its public certificate are uploaded to the Cloud/MQTT Broker's "Allowed Devices" list.
+2.  **Labeling:** A QR code is printed and attached to the device, containing its Serial Number and Provisioning Date.
+
+## Workflow Diagram (Conceptual)
+
+```text
+[ Blank Device ] 
+      |
+      v
+[ 1. Hardware Test ] ----(Fail)----> [ Reject/Repair ]
+      |
+      v
+[ 2. Identity Injection ] <---(From CA)--- [ Unique Certs ]
+      |
+      v
+[ 3. Security Locking ] (Flash Encrypt, Secure Boot)
+      |
+      v
+[ 4. Final App Flash ]
+      |
+      v
+[ 5. Cloud Sync ] ----> [ Ready for Shipment ]
+```
+
+## Tools Required
+*   **esptool.py:** For flashing and eFuse operations.
+*   **esp_secure_cert_tool:** For managing certificates on ESP32.
+*   **Custom Provisioning Script:** A Python script to coordinate the CA communication and the flashing process.
+*   **Provisioning PC:** A secure computer with access to the company's private CA.
--- a/Documentation/Gap_Analysis_Review.md
+++ b/Documentation/Gap_Analysis_Review.md
@@ -0,0 +1,611 @@
+# Gap Analysis & Solutions Review
+
+**Date:** 2025-01-19  
+**Reviewer:** Senior Embedded Systems Architect  
+**Status:** Comprehensive Analysis
+
+## Executive Summary
+
+The proposed gap analysis and solutions demonstrate **strong industrial engineering practices** and address the critical gaps identified in the engineering review. The technology choices are **well-justified**, **ESP32-S3-appropriate**, and **suitable for harsh farm environments**. 
+
+**Overall Assessment: ✅ APPROVED with Minor Recommendations**
+
+---
+
+## 1. Communication Architecture Analysis
+
+### ✅ **EXCELLENT CHOICES**
+
+#### 1.1 Wi-Fi 802.11n (2.4 GHz)
+**Assessment:** ✅ **EXCELLENT**
+
+**Strengths:**
+- Native ESP32-S3 support (mature drivers)
+- Good range and penetration for farm structures
+- Sufficient throughput for OTA updates (150 Mbps theoretical, ~20-30 Mbps practical)
+- Compatible with existing farm infrastructure
+- Lower power than 5 GHz alternatives
+
+**Recommendations:**
+- ✅ Specify minimum RSSI threshold for connection (-85 dBm recommended)
+- ✅ Implement automatic channel selection to avoid interference
+- ✅ Add Wi-Fi power management (PSM) for battery-operated scenarios (if applicable)
+
+#### 1.2 MQTT over TLS 1.2
+**Assessment:** ✅ **EXCELLENT**
+
+**Strengths:**
+- Industry-standard protocol (ISO/IEC 20922)
+- Store-and-forward capability (QoS 1/2)
+- Built-in keepalive (connection health monitoring)
+- Lightweight (small code footprint)
+- Native ESP-IDF support (esp_mqtt component)
+
+**Recommendations:**
+- ✅ **CRITICAL:** Specify MQTT broker version compatibility (e.g., Mosquitto 2.x, HiveMQ)
+- ✅ **CRITICAL:** Define maximum message size (recommend 8KB for ESP32-S3)
+- ✅ Consider MQTT-SN for extremely constrained scenarios (not needed for current design)
+- ✅ Specify topic naming convention in detail (partially done, needs completion)
+
+**Topic Structure Recommendation:**
+```
+/farm/{site_id}/{house_id}/{node_id}/{data_type}/{sensor_id}
+/farm/{site_id}/{house_id}/{node_id}/status/heartbeat
+/farm/{site_id}/{house_id}/{node_id}/cmd/{command_type}
+/farm/{site_id}/{house_id}/{node_id}/diag/{severity}
+```
+
+#### 1.3 ESP-NOW for Peer-to-Peer
+**Assessment:** ✅ **GOOD** (with caveats)
+
+**Strengths:**
+- Deterministic, low-latency communication
+- No AP dependency
+- Native ESP32-S3 support
+- Low power consumption
+
+**Concerns:**
+- Limited range (~200m line-of-sight, ~50m through walls)
+- No built-in encryption (must implement application-layer encryption)
+- No acknowledgment mechanism (must implement at application layer)
+
+**Recommendations:**
+- ⚠️ **IMPORTANT:** Implement application-layer encryption for ESP-NOW (AES-128 minimum)
+- ⚠️ **IMPORTANT:** Implement acknowledgment and retry mechanism
+- ✅ Specify maximum peer count (ESP-NOW supports up to 20 peers)
+- ✅ Define use cases for ESP-NOW (time sync, emergency alerts, mesh coordination)
+
+#### 1.4 CBOR Encoding
+**Assessment:** ✅ **EXCELLENT**
+
+**Strengths:**
+- Binary format (efficient, ~30-50% smaller than JSON)
+- Versioned payloads (backward compatibility)
+- Standardized (RFC 8949)
+- Good library support (TinyCBOR, QCBOR)
+
+**Recommendations:**
+- ✅ Specify CBOR schema versioning strategy
+- ✅ Define maximum payload size per message type
+- ✅ Consider schema validation on Main Hub side
+
+#### 1.5 LoRa as Fallback
+**Assessment:** ⚠️ **NEEDS CLARIFICATION**
+
+**Concerns:**
+- External module required (additional cost, complexity)
+- Different protocol stack (not native ESP-IDF)
+- Lower data rate (may not support OTA updates)
+- Regulatory considerations (frequency bands, power limits)
+
+**Recommendations:**
+- ⚠️ **CLARIFY:** Is LoRa truly needed, or is Wi-Fi + ESP-NOW sufficient?
+- ⚠️ **IF REQUIRED:** Specify LoRa module (e.g., SX1276, SX1262)
+- ⚠️ **IF REQUIRED:** Define LoRa use cases (emergency alerts only? data backup?)
+- ⚠️ **IF REQUIRED:** Specify LoRaWAN vs. raw LoRa (LoRaWAN adds complexity but provides network management)
+
+**Alternative Consideration:**
+- Consider **cellular (LTE-M/NB-IoT)** as fallback instead of LoRa if farm has cellular coverage
+- Provides higher data rate, better for OTA updates
+- More expensive but more reliable in some regions
+
+---
+
+## 2. Security Model Analysis
+
+### ✅ **EXCELLENT - INDUSTRY STANDARD**
+
+#### 2.1 Secure Boot V2
+**Assessment:** ✅ **EXCELLENT - MANDATORY**
+
+**Strengths:**
+- Hardware-enforced root of trust
+- Prevents unauthorized firmware execution
+- ESP32-S3 native support
+- Industry standard for industrial IoT
+
+**Recommendations:**
+- ✅ **CRITICAL:** Document key management and signing infrastructure
+- ✅ **CRITICAL:** Define secure key storage (HSM, secure signing server)
+- ✅ Specify bootloader version compatibility
+- ✅ Define rollback policy (anti-rollback eFuse settings)
+
+#### 2.2 Flash Encryption
+**Assessment:** ✅ **EXCELLENT - MANDATORY**
+
+**Strengths:**
+- Protects IP and sensitive data
+- Hardware-accelerated (AES-256)
+- Transparent to application (automatic decryption)
+- Prevents physical attacks
+
+**Recommendations:**
+- ✅ **CRITICAL:** Document key derivation and storage
+- ✅ Specify encryption mode (Release mode recommended for production)
+- ✅ Define encrypted partition layout
+
+#### 2.3 Mutual TLS (mTLS)
+**Assessment:** ✅ **EXCELLENT**
+
+**Strengths:**
+- Strong authentication (both sides verified)
+- Prevents man-in-the-middle attacks
+- Industry standard
+- ESP-IDF native support (mbedTLS)
+
+**Recommendations:**
+- ✅ **CRITICAL:** Specify certificate lifecycle management
+- ✅ **CRITICAL:** Define certificate rotation strategy
+- ✅ Specify certificate revocation mechanism (CRL, OCSP)
+- ⚠️ **IMPORTANT:** ESP32-S3 optimized for single device certificate - avoid large certificate chains
+- ✅ Define maximum certificate size (recommend <2KB)
+
+#### 2.4 eFuse Anti-Rollback
+**Assessment:** ✅ **EXCELLENT**
+
+**Strengths:**
+- Prevents downgrade attacks
+- Hardware-enforced
+- Cannot be bypassed
+
+**Recommendations:**
+- ⚠️ **WARNING:** eFuse is one-time programmable - define version numbering strategy carefully
+- ✅ Specify version number format (e.g., major.minor.patch → single integer)
+- ✅ Document version increment policy
+
+---
+
+## 3. OTA Strategy Analysis
+
+### ✅ **EXCELLENT - PRODUCTION-READY**
+
+#### 3.1 A/B Partitioning
+**Assessment:** ✅ **EXCELLENT**
+
+**Strengths:**
+- Safe rollback mechanism
+- No "bricking" risk
+- Industry standard approach
+- ESP-IDF native support
+
+**Partition Layout Review:**
+```
+✅ bootloader: Appropriate
+✅ ota_0: 3.5 MB - Sufficient for application
+✅ ota_1: 3.5 MB - Sufficient for updates
+✅ nvs: 64 KB - Appropriate for configuration
+✅ coredump: 64 KB - Good for debugging
+⚠️ factory: Not specified - Consider minimal rescue firmware
+```
+
+**Recommendations:**
+- ✅ **CRITICAL:** Verify total partition size fits in 8MB flash
+  - Bootloader: ~32KB
+  - Partition table: ~4KB
+  - ota_0: 3.5MB
+  - ota_1: 3.5MB
+  - nvs: 64KB
+  - coredump: 64KB
+  - phy_init: ~4KB
+  - **Total: ~7.1MB** ✅ Fits in 8MB
+- ✅ Specify factory partition size if used (recommend 256KB minimum)
+- ✅ Define partition table versioning strategy
+
+#### 3.2 OTA Policy
+**Assessment:** ✅ **EXCELLENT**
+
+**Strengths:**
+- Chunked download (reliable)
+- Integrity verification (SHA-256)
+- Automatic rollback (safety)
+- Health check confirmation (validation)
+
+**Recommendations:**
+- ✅ **CRITICAL:** Specify chunk size rationale (4096 bytes = flash page size - correct)
+- ✅ **CRITICAL:** Define maximum OTA duration timeout (recommend 15 minutes total)
+- ⚠️ **IMPORTANT:** 60-second health check window may be too short for slow networks
+  - **Recommendation:** Increase to 120 seconds or make configurable
+- ✅ Specify what constitutes "health report" (heartbeat? sensor data? both?)
+- ✅ Define rollback trigger conditions (boot failure? no health report? both?)
+
+**OTA Flow Validation:**
+```
+1. Download via HTTPS/MQTT ✅
+2. Chunk size 4096 bytes ✅
+3. SHA-256 verification ✅
+4. Boot validation ✅
+5. Health report within 60s ⚠️ (may need adjustment)
+6. Automatic rollback on failure ✅
+```
+
+---
+
+## 4. Sensor Data Acquisition Analysis
+
+### ✅ **EXCELLENT - WELL-DESIGNED**
+
+#### 4.1 Sensor Abstraction Layer (SAL)
+**Assessment:** ✅ **EXCELLENT**
+
+**Strengths:**
+- Hardware independence
+- Maintainability
+- Testability (mock sensors)
+- Future-proof (sensor swaps)
+
+**Interface Review:**
+```
+✅ sensor_read() - Appropriate
+✅ sensor_calibrate() - Appropriate
+✅ sensor_validate() - Appropriate
+✅ sensor_health_check() - Excellent addition
+```
+
+**Recommendations:**
+- ✅ Add `sensor_getMetadata()` for sensor capabilities (range, accuracy, etc.)
+- ✅ Add `sensor_reset()` for recovery from fault states
+- ✅ Specify error codes per interface function
+
+#### 4.2 Redundant Sensor Strategy
+**Assessment:** ⚠️ **GOOD but NEEDS COST-BENEFIT ANALYSIS**
+
+**Strengths:**
+- High reliability
+- Fault detection
+- Common-mode failure avoidance
+
+**Concerns:**
+- **Cost:** Doubles sensor cost for critical parameters
+- **Complexity:** Requires sensor fusion logic
+- **Power:** May increase power consumption
+
+**Recommendations:**
+- ⚠️ **IMPORTANT:** Define which parameters are "critical" (CO2? Temperature? All?)
+- ⚠️ **IMPORTANT:** Specify sensor fusion algorithm (average? weighted? voting?)
+- ⚠️ **IMPORTANT:** Define conflict resolution (what if sensors disagree significantly?)
+- ✅ Consider redundancy only for **life-safety critical** parameters (CO2, NH3)
+- ✅ For non-critical parameters (light, humidity), single sensor may be sufficient
+
+**Recommended Criticality Matrix:**
+| Parameter | Criticality | Redundancy Required? |
+|-----------|-------------|---------------------|
+| CO2 | HIGH (asphyxiation risk) | ✅ YES |
+| NH3 | HIGH (toxic gas) | ✅ YES |
+| Temperature | MEDIUM (animal welfare) | ⚠️ MAYBE (if budget allows) |
+| Humidity | MEDIUM | ❌ NO |
+| Light | LOW | ❌ NO |
+| VOC | MEDIUM | ⚠️ MAYBE |
+
+#### 4.3 Sensor State Machine
+**Assessment:** ✅ **EXCELLENT**
+
+**State Flow:**
+```
+INIT → WARMUP → STABLE → DEGRADED → FAILED
+```
+
+**Strengths:**
+- Explicit state tracking
+- Validity flags
+- Prevents invalid data publication
+
+**Recommendations:**
+- ✅ Specify warmup duration per sensor type (e.g., CO2: 30s, Temperature: 5s)
+- ✅ Define transition criteria (e.g., STABLE → DEGRADED: 3 consecutive out-of-range readings)
+- ✅ Specify recovery behavior (FAILED → STABLE: manual intervention? automatic retry?)
+
+#### 4.4 Data Filtering
+**Assessment:** ✅ **GOOD - SIMPLE AND EFFECTIVE**
+
+**Filtering Strategy:**
+1. Median Filter (N=5) ✅
+2. Rate-of-Change Limiter ✅
+3. Physical Bounds Check ✅
+
+**Strengths:**
+- Simple (low CPU overhead)
+- Robust (median resists outliers)
+- Deterministic (predictable behavior)
+
+**Recommendations:**
+- ✅ Specify rate-of-change limits per sensor type (e.g., Temperature: ±5°C/min)
+- ✅ Define physical bounds per sensor type (e.g., CO2: 0-5000 ppm)
+- ⚠️ **CONSIDER:** Moving average for smoothing (if needed for specific sensors)
+
+---
+
+## 5. Data Persistence Analysis
+
+### ✅ **EXCELLENT - WEAR-AWARE DESIGN**
+
+#### 5.1 SD Card Strategy
+**Assessment:** ✅ **EXCELLENT**
+
+**Strengths:**
+- FAT32 (universal compatibility)
+- SDMMC 4-bit (high performance)
+- Circular time-bucket files (wear distribution)
+- Append-only writes (minimal directory updates)
+
+**Recommendations:**
+- ✅ **CRITICAL:** Specify file rotation policy (daily? hourly? size-based?)
+- ✅ **CRITICAL:** Define maximum file size (recommend 10-50MB per file)
+- ✅ Specify directory structure (e.g., `/sdcard/data/YYYY-MM-DD/`)
+- ✅ Define SD card health monitoring (bad block detection, wear leveling status)
+- ⚠️ **IMPORTANT:** Consider wear leveling at file system level (if SD card doesn't have it)
+
+**SD Card Write Pattern Example:**
+```
+/sdcard/
+  /data/
+    2025-01-19_sensor.dat (append-only, rotate daily)
+    2025-01-19_diag.dat (append-only, rotate daily)
+  /ota/
+    firmware.bin (temporary, deleted after update)
+```
+
+#### 5.2 NVS Usage
+**Assessment:** ✅ **EXCELLENT**
+
+**Data Separation:**
+- Calibration Data → NVS (Encrypted) ✅
+- System Constants → NVS ✅
+- Counters → RAM (periodic commit) ✅
+- System Logs → SD Card ✅
+
+**Strengths:**
+- Critical data protected (NVS)
+- High-frequency data on SD (wear distribution)
+- Appropriate separation
+
+**Recommendations:**
+- ✅ Specify NVS namespace organization
+- ✅ Define NVS key naming convention
+- ✅ Specify commit frequency for RAM counters (recommend every 10 minutes or on teardown)
+
+---
+
+## 6. Diagnostics & Maintainability Analysis
+
+### ✅ **EXCELLENT - FLEET-SCALE READY**
+
+#### 6.1 Diagnostic Code System
+**Assessment:** ✅ **EXCELLENT**
+
+**Format: `0xSCCC`**
+- S: Severity (1-4)
+- CCC: Subsystem Code
+
+**Strengths:**
+- Standardized format
+- Fleet analytics capability
+- Clear categorization
+
+**Recommendations:**
+- ✅ **CRITICAL:** Complete the diagnostic code registry (define all codes)
+- ✅ Specify diagnostic code versioning (for firmware evolution)
+- ✅ Define diagnostic code documentation requirements (each code must have description)
+
+**Subsystem Code Allocation:**
+```
+✅ 0x1xxx - Data Acquisition (DAQ)
+✅ 0x2xxx - Communication (COM)
+✅ 0x3xxx - Security (SEC)
+✅ 0x4xxx - Over-the-Air Updates (OTA)
+✅ 0x5xxx - Hardware (HW)
+⚠️ MISSING: System Management (SYS) - Recommend 0x6xxx
+⚠️ MISSING: Persistence (DATA) - Recommend 0x7xxx
+⚠️ MISSING: Diagnostics (DIAG) - Recommend 0x8xxx
+```
+
+#### 6.2 Layered Watchdogs
+**Assessment:** ✅ **EXCELLENT**
+
+**Watchdog Hierarchy:**
+- Task WDT: 10s ✅
+- Interrupt WDT: 3s ✅
+- RTC WDT: 30s ✅
+
+**Strengths:**
+- Multi-level protection
+- Appropriate timeouts
+- Automatic recovery
+
+**Recommendations:**
+- ✅ Specify watchdog feed locations (which tasks feed which watchdog)
+- ✅ Define watchdog recovery behavior (reboot? state transition?)
+- ⚠️ **IMPORTANT:** Ensure watchdogs are fed during OTA (may take longer than 30s)
+
+---
+
+## 7. Power & Fault Handling Analysis
+
+### ✅ **EXCELLENT - RESILIENT DESIGN**
+
+#### 7.1 Brownout Detection
+**Assessment:** ✅ **EXCELLENT**
+
+**Configuration:**
+- Brownout threshold: 3.0V ✅
+- ISR action: Power loss flag + flush ✅
+- Recovery: Clean reboot ✅
+
+**Strengths:**
+- Hardware-backed detection
+- Immediate response
+- Data protection
+
+**Recommendations:**
+- ✅ **CRITICAL:** Verify 3.0V threshold is appropriate for ESP32-S3 (check datasheet)
+  - ESP32-S3 minimum operating voltage: 2.3V (typical)
+  - 3.0V provides good margin ✅
+- ✅ Specify brownout ISR execution time limit (must complete within capacitor hold time)
+- ✅ Define brownout recovery delay (wait for voltage stabilization before reboot)
+
+#### 7.2 Hardware Recommendations
+**Assessment:** ✅ **EXCELLENT**
+
+**Recommendations:**
+- Supercapacitor (1-2s runtime) ✅
+- External RTC battery ✅
+
+**Strengths:**
+- Graceful shutdown capability
+- Time accuracy preservation
+- Production-ready approach
+
+**Recommendations:**
+- ✅ Specify supercapacitor capacity (recommend 0.5-1.0F for 1-2s at 3.3V)
+- ✅ Specify RTC battery type (CR2032 typical, 3V, 220mAh)
+- ✅ Define RTC battery monitoring (low battery detection)
+
+---
+
+## 8. GPIO & Hardware Discipline Analysis
+
+### ✅ **EXCELLENT - CRITICAL FOR RELIABILITY**
+
+#### 8.1 Mandatory Rules
+**Assessment:** ✅ **EXCELLENT - ALL CRITICAL**
+
+**Rules:**
+1. No strapping pins ✅
+2. I2C pull-up audit ✅
+3. No ADC2 with Wi-Fi ✅
+
+**Strengths:**
+- Prevents common failures
+- Production-grade discipline
+- Hardware/firmware alignment
+
+**Recommendations:**
+- ✅ **CRITICAL:** Complete the GPIO map table (currently shows "...")
+- ✅ Specify strapping pins explicitly (GPIO 0, 3, 45, 46 on ESP32-S3)
+- ✅ Define I2C pull-up resistor values (recommend 2.2kΩ - 4.7kΩ for 3.3V)
+- ✅ Specify I2C bus speed (recommend 100kHz for reliability, 400kHz if needed)
+- ✅ Document ADC1 pin assignments (avoid ADC2 pins when Wi-Fi active)
+
+**GPIO Map Template:**
+```
+| Pin | Function | Direction | Notes |
+|-----|----------|-----------|-------|
+| GPIO 0 | BOOT (strapping) | Input | DO NOT USE |
+| GPIO 3 | JTAG (strapping) | Input | DO NOT USE |
+| GPIO 4 | I2C SDA (Sensor Bus) | I/O | External 4.7kΩ pull-up |
+| GPIO 5 | I2C SCL (Sensor Bus) | Output | External 4.7kΩ pull-up |
+| GPIO 6 | SPI MOSI (SD Card) | Output | - |
+| GPIO 7 | SPI MISO (SD Card) | Input | - |
+| GPIO 8 | SPI CLK (SD Card) | Output | - |
+| GPIO 9 | SPI CS (SD Card) | Output | - |
+| ... | ... | ... | ... |
+```
+
+---
+
+## 9. System Evolution Analysis
+
+### ✅ **GOOD - CLEAR TRANSITION PATH**
+
+**Assessment:** ✅ **GOOD**
+
+**Strengths:**
+- Clear current state assessment
+- Well-defined enhancements
+- Actionable next steps
+
+**Recommendations:**
+- ✅ Prioritize next steps (which is most critical?)
+- ✅ Define success criteria for each enhancement
+- ✅ Specify timeline/milestones
+
+---
+
+## Overall Assessment
+
+### ✅ **STRENGTHS**
+
+1. **Industrial-Grade Choices:** All technology selections are appropriate for industrial deployment
+2. **ESP32-S3 Optimized:** Solutions leverage ESP32-S3 native capabilities
+3. **Security-First:** Comprehensive security model with hardware root of trust
+4. **Reliability-Focused:** Power handling, watchdogs, and fault tolerance well-designed
+5. **Maintainability:** Diagnostic system enables fleet-scale management
+6. **Cost-Conscious:** Solutions balance reliability with cost (except redundant sensors - needs review)
+
+### ⚠️ **AREAS NEEDING CLARIFICATION**
+
+1. **LoRa Fallback:** Is it truly needed? Cost-benefit analysis required
+2. **Redundant Sensors:** Define criticality matrix and cost justification
+3. **GPIO Map:** Complete the canonical GPIO mapping table
+4. **Diagnostic Codes:** Complete the diagnostic code registry
+5. **OTA Health Check:** 60-second window may be too short
+6. **Topic Structure:** Complete MQTT topic naming convention
+
+### ✅ **RECOMMENDATIONS SUMMARY**
+
+#### Critical (Must Address):
+1. ✅ Complete GPIO mapping table
+2. ✅ Complete diagnostic code registry
+3. ✅ Define certificate lifecycle management
+4. ✅ Specify OTA health check window (consider 120s)
+5. ✅ Complete MQTT topic structure
+
+#### Important (Should Address):
+1. ⚠️ Cost-benefit analysis for redundant sensors
+2. ⚠️ Clarify LoRa fallback necessity
+3. ⚠️ Define sensor fusion algorithm for redundant sensors
+4. ⚠️ Specify SD card file rotation policy
+5. ⚠️ Define maximum message sizes
+
+#### Nice-to-Have (Consider):
+1. Consider cellular fallback instead of LoRa
+2. Add sensor metadata interface to SAL
+3. Define diagnostic code versioning strategy
+4. Specify supercapacitor and RTC battery specifications
+
+---
+
+## Final Verdict
+
+**✅ APPROVED for Implementation**
+
+The proposed solutions are **technically sound**, **industry-appropriate**, and **well-aligned with ESP32-S3 capabilities**. The architecture demonstrates **mature engineering practices** suitable for **production deployment in harsh farm environments**.
+
+**Recommendation:** Proceed with implementation after addressing the **Critical** items listed above. The **Important** items should be resolved during detailed design phase.
+
+**Confidence Level:** **HIGH** - Solutions are production-ready with minor clarifications needed.
+
+---
+
+## Traceability
+
+This analysis addresses gaps identified in:
+- Engineering Review Report (System Review Checklist)
+- System Requirements Specification (SRS)
+- Cross-Feature Constraints
+- System State Machine Specification
+
+All proposed solutions align with:
+- ISO/IEC/IEEE 29148 SRS requirements
+- Industrial IoT best practices
+- ESP-IDF v5.4 capabilities
+- Farm environment constraints
--- a/Documentation/Global
+++ b/Documentation/Global
@@ -0,0 +1,28 @@
+# Global Summary: ASF Gap Analysis & Solutions
+
+## Executive Summary
+This document consolidates the findings of the ASF gap analysis and the proposed industrial-grade solutions. The transition from a prototype to a production-ready system involves closing critical gaps in communication, security, reliability, and maintainability.
+
+## Gap & Solution Matrix
+
+| Arena | Identified Gaps | Proposed Industrial Solution |
+| :--- | :--- | :--- |
+| **1. Communication** | Lack of versioning, raw sockets, unreliable peer-to-peer. | **MQTT over TLS 1.2** with **CBOR** payloads; **ESP-NOW** for deterministic P2P. |
+| **2. Security** | No hardware root of trust, weak device identity. | **Secure Boot V2**, **Flash Encryption**, and **mTLS** with unique device certificates. |
+| **3. OTA Updates** | Risk of "bricking," no integrity checks. | **A/B Partitioning** with automatic rollback and **SHA-256** verification. |
+| **4. Data Acquisition** | Tight coupling with hardware, no sensor validation. | **Sensor Abstraction Layer (SAL)**, redundant sensors, and explicit validity states. |
+| **5. Data Persistence** | SD card wear, risk of data loss on power failure. | **Batch writing**, **FAT32 SDMMC 4-bit**, and **Power-loss flush** mechanisms. |
+| **6. Diagnostics** | Limited visibility into fleet health. | **Standardized Diagnostic Codes (0xSCCC)** and **Layered Watchdogs**. |
+| **7. Power Handling** | Vulnerability to brownouts. | **Brownout detection (3.0V)** and hardware-backed graceful shutdown. |
+| **8. Hardware Discipline** | Potential pin conflicts, unreliable I2C. | **Strict GPIO mapping**, no strapping pins, and audited physical pull-ups. |
+| **9. System Evolution** | Prototype-level architecture. | **Industrial-grade framework** focusing on determinism and fault tolerance. |
+
+## Key Deliverables
+The following documentation set has been created to guide the implementation:
+1.  **Individual Arena Files (01-09):** Detailed technical specifications for each system layer.
+2.  **Proposed Solution Guide:** A "for dummies" explanation of the background and mechanics of the solutions.
+3.  **Factory Provisioning Workflow:** A step-by-step guide for secure device manufacturing.
+4.  **Global Summary:** This overview of the entire project status.
+
+## Conclusion
+By implementing these solutions, the ASF project moves beyond a functional prototype into a robust, secure, and maintainable industrial product capable of reliable operation in demanding farm environments.
--- a/Documentation/Proposed
+++ b/Documentation/Proposed
@@ -0,0 +1,59 @@
+# Proposed Solution Guide: Industrial ASF
+
+## Introduction
+This guide explains the "Proposed Solution" for the ASF project in simple terms. It is designed to help anyone understand how the system works, the background behind the decisions, and why these "industrial" patterns are used instead of simpler "maker" methods.
+
+---
+
+## 1. The "Brain" and its Security (ESP32-S3)
+### Background
+The ESP32-S3 is a powerful microcontroller. In a "maker" project, you just upload code and it runs. In an **industrial** project, we must ensure the code hasn't been tampered with and that no one can steal the "secret sauce" (your intellectual property).
+
+### How it Works
+*   **Secure Boot:** Think of this as a digital signature check. Every time the device starts, it checks the signature of the code. If it doesn't match, it won't run.
+*   **Flash Encryption:** This scrambles the data stored on the chip. If someone desolders the chip and tries to read it, they will only see gibberish.
+
+---
+
+## 2. Talking to the World (MQTT & TLS)
+### Background
+Devices need to send data to a central server. Using simple "web requests" (HTTP) can be slow and unreliable on a farm.
+
+### How it Works
+*   **MQTT:** This is like a post office. The device "publishes" a message to a "topic" (like a mailbox), and the server "subscribes" to it. It's very lightweight and stays connected even if the signal is weak.
+*   **TLS (mTLS):** This is the "S" in "HTTPS," but stronger. Both the device and the server have "ID cards" (certificates). They check each other's IDs before talking. This ensures no one can "pretend" to be your device or your server.
+
+---
+
+## 3. Updating the Software (OTA)
+### Background
+When the devices are out on a farm, you can't go to each one with a USB cable to update the software. You need to do it over the air (OTA).
+
+### How it Works
+*   **A/B Slots:** The device has two "slots" for software. While it's running from Slot A, it downloads the new version into Slot B.
+*   **The Safety Net:** After downloading, it tries to start Slot B. If Slot B crashes or can't connect to the internet within 60 seconds, the device says "Oops!" and automatically switches back to the working Slot A. This prevents "bricking" the device.
+
+---
+
+## 4. Handling Sensors (The SAL)
+### Background
+Sensors can be finicky. Sometimes they give wrong readings, and sometimes the company stops making a specific model.
+
+### How it Works
+*   **The "Translator" (SAL):** Instead of the main code talking directly to a "Sensirion SCD41" sensor, it talks to a "CO2 Sensor Translator." If you switch to a different brand of sensor later, you only change the translator, not the whole system.
+*   **The "Rule of Two":** For important things (like CO2 or Temperature), we use two different sensors. If one fails or gives a crazy reading, the system can detect it and use the other one.
+
+---
+
+## 5. Saving Data (SD Cards)
+### Background
+SD cards are great for storage but they "wear out" if you write to them too often in the same spot.
+
+### How it Works
+*   **Batch Writing:** Instead of writing every single heartbeat to the SD card, the system collects them in memory and writes them all at once in a big "chunk." This makes the SD card last much longer.
+*   **Power Loss Protection:** The system "listens" to the power. If the power starts to drop, it uses a tiny bit of stored energy (from a capacitor) to quickly finish writing the last bit of data before it shuts down.
+
+---
+
+## Summary for Dummies
+In short, we are moving from a system that **"just works"** to a system that **"keeps working"** even when things go wrong (bad power, bad sensors, bad hackers, or bad internet).
--- a/Documentation/Review_Executive_Summary.md
+++ b/Documentation/Review_Executive_Summary.md
@@ -0,0 +1,103 @@
+# Gap Analysis Review - Executive Summary
+
+**Date:** 2025-01-19  
+**Status:** ✅ **APPROVED with Minor Recommendations**
+
+## Quick Assessment
+
+| Category | Rating | Status |
+|----------|--------|--------|
+| **Communication Architecture** | ⭐⭐⭐⭐⭐ | ✅ Excellent |
+| **Security Model** | ⭐⭐⭐⭐⭐ | ✅ Excellent |
+| **OTA Strategy** | ⭐⭐⭐⭐⭐ | ✅ Excellent |
+| **Sensor Data Acquisition** | ⭐⭐⭐⭐ | ✅ Good (redundancy needs review) |
+| **Data Persistence** | ⭐⭐⭐⭐⭐ | ✅ Excellent |
+| **Diagnostics** | ⭐⭐⭐⭐ | ✅ Good (codes need completion) |
+| **Power Handling** | ⭐⭐⭐⭐⭐ | ✅ Excellent |
+| **GPIO Discipline** | ⭐⭐⭐⭐⭐ | ✅ Excellent (map needs completion) |
+| **System Evolution** | ⭐⭐⭐⭐ | ✅ Good |
+
+**Overall Rating: ⭐⭐⭐⭐⭐ (4.7/5.0)**
+
+## Key Findings
+
+### ✅ **EXCELLENT CHOICES** (No Changes Needed)
+
+1. **MQTT over TLS 1.2** - Industry standard, perfect for industrial IoT
+2. **Secure Boot V2 + Flash Encryption** - Mandatory for production, well-implemented
+3. **A/B OTA Partitioning** - Safe, reliable, industry-proven
+4. **Sensor Abstraction Layer (SAL)** - Maintainable, testable, future-proof
+5. **Wear-Aware SD Card Strategy** - Prevents premature failure
+6. **Layered Watchdogs** - Multi-level protection
+7. **Brownout Detection** - Critical for farm environments
+
+### ⚠️ **NEEDS CLARIFICATION** (5 Items)
+
+1. **LoRa Fallback** - Is it truly needed? Cost-benefit analysis required
+2. **Redundant Sensors** - Define which parameters are critical (cost impact)
+3. **GPIO Map** - Complete the canonical mapping table
+4. **Diagnostic Codes** - Complete the code registry (0x6xxx, 0x7xxx, 0x8xxx missing)
+5. **OTA Health Check** - 60s may be too short (consider 120s)
+
+### ✅ **MINOR RECOMMENDATIONS** (Enhancements)
+
+1. Complete MQTT topic structure specification
+2. Define sensor fusion algorithm for redundant sensors
+3. Specify SD card file rotation policy
+4. Define certificate lifecycle management
+5. Specify maximum message sizes
+
+## Technology Stack Validation
+
+| Technology | Choice | Justification | Status |
+|------------|--------|---------------|--------|
+| Wi-Fi 802.11n | ✅ | Native support, good range, sufficient throughput | ✅ Approved |
+| MQTT | ✅ | Industry standard, store-and-forward, lightweight | ✅ Approved |
+| TLS 1.2 | ✅ | Strong security, ESP-IDF native | ✅ Approved |
+| ESP-NOW | ✅ | Deterministic P2P, low latency | ✅ Approved (needs encryption) |
+| CBOR | ✅ | Efficient binary encoding | ✅ Approved |
+| LoRa | ⚠️ | External module, low data rate | ⚠️ Needs justification |
+| Secure Boot V2 | ✅ | Hardware root of trust | ✅ Approved |
+| Flash Encryption | ✅ | IP protection, data security | ✅ Approved |
+| A/B Partitioning | ✅ | Safe OTA, rollback capability | ✅ Approved |
+
+## Critical Action Items
+
+### Must Complete Before Implementation:
+
+1. ✅ **GPIO Mapping Table** - Complete pin assignments
+2. ✅ **Diagnostic Code Registry** - Define all subsystem codes
+3. ✅ **MQTT Topic Structure** - Complete topic naming convention
+4. ✅ **Certificate Lifecycle** - Define provisioning, rotation, revocation
+5. ✅ **OTA Health Check Window** - Validate 60s or increase to 120s
+
+### Should Complete During Design:
+
+1. ⚠️ **Redundant Sensor Analysis** - Cost-benefit and criticality matrix
+2. ⚠️ **LoRa Justification** - Is it needed? Alternative analysis
+3. ⚠️ **Sensor Fusion Algorithm** - How to combine redundant sensor data
+4. ⚠️ **SD Card Rotation Policy** - File size limits, rotation frequency
+
+## Risk Assessment
+
+| Risk | Severity | Mitigation Status |
+|------|----------|-------------------|
+| Incomplete GPIO Map | HIGH | ⚠️ Needs completion |
+| Missing Diagnostic Codes | MEDIUM | ⚠️ Needs completion |
+| LoRa Cost/Complexity | MEDIUM | ⚠️ Needs justification |
+| Redundant Sensor Cost | MEDIUM | ⚠️ Needs analysis |
+| OTA Health Check Timing | LOW | ⚠️ Needs validation |
+
+## Final Recommendation
+
+**✅ PROCEED WITH IMPLEMENTATION**
+
+The proposed solutions are **technically sound** and **production-ready**. Address the **Critical Action Items** before starting implementation. The **Should Complete** items can be resolved during detailed design.
+
+**Confidence Level:** **HIGH** (90%)
+
+The architecture demonstrates **mature industrial engineering practices** and is suitable for **long-term field deployment**.
+
+---
+
+**See Full Analysis:** `Gap_Analysis_Review.md`
--- a/Documentation/global_solutions.md
+++ b/Documentation/global_solutions.md
@@ -0,0 +1,68 @@
+# ASF Sensor Hub – Industrial Gap Resolution & Architecture Proposal
+
+**Target Platform:** ESP32-S3  
+**SDK:** ESP-IDF v5.4  
+**Domain:** Industrial / Agricultural Automation (Smart Poultry Farm)
+
+---
+
+## 1. Introduction
+
+This document provides a **comprehensive proposal to close the identified system gaps** in the ASF Sensor Hub design.  
+The focus is on **industrial-grade reliability, security, maintainability, and scalability**, aligned with best practices used in commercial automation and IoT systems.
+
+The solutions proposed here are **technology-backed**, **ESP32-S3–aware**, and suitable for **long-term field deployment in harsh farm environments**.
+
+---
+
+## 2. Communication Architecture
+
+### 2.1 Selected Technologies Overview
+
+| Layer | Technology |
+|-----|-----------|
+| Physical / Link | Wi-Fi 802.11n (2.4 GHz) |
+| Messaging | MQTT |
+| Security | TLS 1.2 (Mutual Authentication) |
+| Peer-to-peer | ESP-NOW |
+| Payload Encoding | CBOR |
+
+---
+
+### 2.2 Wi-Fi 802.11n (2.4 GHz)
+
+#### Background
+Wi-Fi 802.11n at 2.4 GHz is the **most widely supported industrial wireless standard** for embedded devices.  
+It offers a good balance between:
+- Range
+- Penetration through farm structures
+- Throughput (sufficient for OTA updates)
+
+#### Why Chosen
+- Native support on ESP32-S3
+- Existing farm infrastructure compatibility
+- Mature ESP-IDF drivers
+- High data rate for OTA firmware updates
+
+#### How It Works
+The Sensor Hub connects to a local Access Point and establishes a persistent TCP/IP connection to the Main Hub or Edge Gateway.
+
+---
+
+### 2.3 MQTT (Message Queuing Telemetry Transport)
+
+#### Background
+MQTT is a **lightweight publish/subscribe protocol** designed specifically for unreliable networks and constrained devices.
+
+#### Why Chosen
+- Store-and-forward messaging
+- Built-in keepalive mechanism
+- QoS levels for delivery guarantees
+- Massive industrial adoption (SCADA, IIoT)
+
+#### How It Works
+- Sensor Hub publishes data to topic hierarchies
+- Main Hub subscribes to relevant topics
+- Configuration and commands flow in reverse direction
+
+**Example Topic Structure:**
--- a/Documentation/pasted_content.txt
+++ b/Documentation/pasted_content.txt
@@ -0,0 +1,328 @@
+Great, thanks for sharing the gap analysis — this is actually a **very solid foundation** already. What’s missing now is not “features”, but **industrial-grade decisions, architectures, and concrete implementation patterns** that close those gaps in a *reliable, production-ready* way on **ESP32-S3 + ESP-IDF v5.4**.
+
+Below is a **structured proposal** that:
+
+* Closes the **critical & high gaps**
+* Uses **industrial best practices**
+* Stays **realistic for ESP32-S3**
+* Avoids “maker-grade” shortcuts
+
+I’ll group this by **system layer**, not by gap ID — that’s how real systems are engineered.
+
+---
+
+# 1️⃣ Communication Architecture (Industrial-Grade Proposal)
+
+## 1.1 Primary & Secondary Communication Stack
+
+### ✅ Final Decision
+
+| Role                               | Technology                  | Why (Industrial Rationale)                   |
+| ---------------------------------- | --------------------------- | -------------------------------------------- |
+| **Primary uplink**                 | **Wi-Fi 802.11n (2.4 GHz)** | Existing infra, high throughput for OTA      |
+| **Peer-to-peer**                   | **ESP-NOW**                 | Deterministic, low latency, no AP dependency |
+| **Long-range fallback (optional)** | **LoRa (external module)**  | Farm-scale resilience                        |
+
+> ⚠️ Zigbee on ESP32-S3 is **not industrial-mature** in ESP-IDF. ESP-NOW is far more reliable.
+
+---
+
+## 1.2 Application Protocol (This Is a Big Gap)
+
+### ❌ Avoid
+
+* Raw TCP sockets
+* Custom binary protocols without versioning
+
+### ✅ Use
+
+**MQTT over TLS 1.2**
+
+| Item        | Decision                        |
+| ----------- | ------------------------------- |
+| Broker      | Main Hub / Edge Gateway         |
+| QoS         | QoS 1 (at least once)           |
+| Retain      | Config topics only              |
+| Payload     | CBOR (binary, versioned)        |
+| Topic model | `/farm/{site}/{house}/{node}/…` |
+
+📌 **Why MQTT?**
+
+* Store-and-forward
+* Built-in keepalive
+* Industrial tooling & monitoring
+* ESP-IDF native support (stable)
+
+---
+
+## 1.3 Heartbeat & Liveness (Formalized)
+
+```text
+Heartbeat interval:     10 s
+Missed heartbeats:      3 → offline
+Payload:
+{
+  uptime,
+  fw_version,
+  free_heap,
+  rssi,
+  error_bitmap
+}
+```
+
+This directly feeds **predictive maintenance**.
+
+---
+
+# 2️⃣ Security Model (Non-Negotiable for Industrial Systems)
+
+## 2.1 Root of Trust (ESP32-S3 Strength)
+
+### Mandatory Features
+
+✅ Secure Boot V2
+✅ Flash Encryption
+✅ eFuse-based version anti-rollback
+
+> **No exceptions.** This is where “industrial” starts.
+
+---
+
+## 2.2 Device Identity & Authentication
+
+### Proposed Model (Used in Industry)
+
+| Item         | Implementation                        |
+| ------------ | ------------------------------------- |
+| Identity     | **Device-unique X.509 certificate**   |
+| Private key  | Stored in **eFuse / encrypted flash** |
+| Auth         | **Mutual TLS (mTLS)**                 |
+| Provisioning | Factory or secure onboarding mode     |
+
+📌 **Key insight**
+ESP32-S3 can handle **1 device cert perfectly**. Do **NOT** try to manage large cert chains on-device.
+
+---
+
+## 2.3 Key Lifecycle (Often Ignored — You Shouldn’t)
+
+| Phase         | Mechanism                 |
+| ------------- | ------------------------- |
+| Manufacturing | Inject device cert + key  |
+| Operation     | TLS session keys only     |
+| Rotation      | Broker-side cert rotation |
+| Revocation    | CRL or broker denylist    |
+
+---
+
+# 3️⃣ OTA Strategy (Industrial Safe Updates)
+
+## 3.1 Partition Layout (Recommended)
+
+For **8MB flash**:
+
+```text
+bootloader
+partition_table
+factory (optional minimal rescue)
+ota_0 (3.5 MB)
+ota_1 (3.5 MB)
+nvs (64 KB, encrypted)
+phy_init
+coredump (64 KB)
+```
+
+---
+
+## 3.2 OTA Policy (Formal)
+
+| Step         | Rule                        |
+| ------------ | --------------------------- |
+| Download     | HTTPS / MQTT chunks         |
+| Chunk size   | 4096 bytes                  |
+| Integrity    | SHA-256 full image          |
+| Validation   | Boot + health report        |
+| Confirmation | App must confirm within 60s |
+| Failure      | Automatic rollback          |
+
+This closes **GAP-OTA-001/002/003** cleanly.
+
+---
+
+# 4️⃣ Sensor & Data Acquisition (Reliability Focus)
+
+## 4.1 Sensor Abstraction Layer (SAL)
+
+This is **critical** for long-term maintainability.
+
+```c
+sensor_read()
+sensor_calibrate()
+sensor_validate()
+sensor_health_check()
+```
+
+Each sensor driver **must implement** this interface.
+
+---
+
+## 4.2 Approved Industrial Sensor Strategy
+
+### Example (CO₂)
+
+| Primary          | Backup             |
+| ---------------- | ------------------ |
+| Sensirion SCD41  | Senseair S8        |
+| I²C              | UART               |
+| Self-calibration | Manual calibration |
+
+📌 **Rule:**
+Every *critical parameter* → **two qualified sensor options**
+
+---
+
+## 4.3 Warm-Up & Validity States
+
+Define sensor states explicitly:
+
+```text
+INIT → WARMUP → STABLE → DEGRADED → FAILED
+```
+
+Never publish raw values without a **validity flag**.
+
+---
+
+## 4.4 Filtering (Simple & Robust)
+
+**Recommended Default**
+
+* Median filter (N=5)
+* Rate-of-change limiter
+* Physical bounds check
+
+This avoids Kalman overengineering.
+
+---
+
+# 5️⃣ Data Persistence & Reliability
+
+## 5.1 SD Card (Industrial Pattern)
+
+| Aspect        | Decision                   |
+| ------------- | -------------------------- |
+| FS            | FAT32                      |
+| Mode          | SDMMC 4-bit                |
+| Structure     | Circular time-bucket files |
+| Write pattern | Append-only                |
+| Flush         | On power-loss interrupt    |
+
+📌 **Never write small files frequently** → SD wear.
+
+---
+
+## 5.2 NVS Usage Rules
+
+| Data        | Location              |
+| ----------- | --------------------- |
+| Calibration | NVS (encrypted)       |
+| Constants   | NVS                   |
+| Counters    | RAM + periodic commit |
+| Logs        | SD / flash partition  |
+
+---
+
+# 6️⃣ Diagnostics & Maintainability
+
+## 6.1 Diagnostic Code System
+
+**Proposed Format**
+
+```
+0xSCCC
+S = Severity (1–4)
+CCC = Subsystem code
+```
+
+| Range  | Subsystem |
+| ------ | --------- |
+| 0x1xxx | DAQ       |
+| 0x2xxx | COM       |
+| 0x3xxx | SEC       |
+| 0x4xxx | OTA       |
+| 0x5xxx | HW        |
+
+This allows **fleet analytics**, not just debugging.
+
+---
+
+## 6.2 Watchdogs (Layered)
+
+| Watchdog      | Purpose             |
+| ------------- | ------------------- |
+| Task WDT      | Deadlocks           |
+| Interrupt WDT | ISR hangs           |
+| RTC WDT       | Total system freeze |
+
+**10s / 3s / 30s** is a good baseline.
+
+---
+
+# 7️⃣ Power & Fault Handling (Farm Reality)
+
+## 7.1 Brownout & Power Loss
+
+| Feature         | Implementation       |
+| --------------- | -------------------- |
+| Brownout detect | 3.0 V                |
+| ISR action      | Flag + flush buffers |
+| Recovery        | Clean reboot         |
+
+Optional but recommended:
+
+* Supercap for 1–2 seconds
+* External RTC battery
+
+---
+
+# 8️⃣ GPIO & Hardware Discipline
+
+## Mandatory Rules
+
+❌ No strapping pins
+❌ No shared I²C without pull-up audit
+❌ No ADC2 for Wi-Fi systems
+
+Create **one canonical GPIO map document** — no exceptions.
+
+---
+
+# 9️⃣ What You Have vs What You Need
+
+### You already have:
+
+✅ Good functional coverage
+✅ Clear system intent
+✅ ESP32-S3 (excellent choice)
+
+### What this proposal adds:
+
+✅ Determinism
+✅ Security maturity
+✅ Fleet-scale maintainability
+✅ Industrial fault tolerance
+
+---
+
+## 🚜 Bottom Line
+
+Your system is **no longer a prototype** — it’s becoming an **industrial embedded product**.
+
+If you want, next we can:
+
+* Turn this into a **formal system architecture diagram**
+* Define a **FreeRTOS task model**
+* Design a **factory provisioning workflow**
+* Or map this directly to **ESP-IDF components & Kconfig options**
+
+Just tell me where you want to go next.