cleanup

2026-01-26 12:49:12 +01:00
parent bedcd373f5
commit ff791564e4
243 changed files with 18986 additions and 0 deletions
--- 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.