add test

I2C_emulation_flow.md

@@ -0,0 +1,124 @@
+
+# SCD30 HIL Framework Documentation
+
+## 1. System Architecture
+
+The system consists of three layers. The PC handles the **Logic**, the Emulator handles the **Signal Bridge**, and the Target runs the **Production Code**.
+
+```mermaid
+graph TD
+    subgraph "PC (Python)"
+        A[Global Test Script] <--> B[HIL Library]
+    end
+    subgraph "Emulator ESP32 (Slave)"
+        C[UART Driver] <--> D[I2C Slave Driver]
+    end
+    subgraph "Target ESP32 (Master)"
+        E[SCD30 Driver Component] <--> F[Application Logic]
+    end
+
+    B <-- "921600 Baud Serial" --> C
+    D <-- "I2C Bus (Clock Stretching)" --> E
+
+```
+
+---
+
+## 2. The Logic Workflow (Sequence)
+
+This is the most critical part: how we synchronize a slow PC with a fast I2C bus.
+
+```mermaid
+sequenceDiagram
+    participant PC as Python (Global Script)
+    participant Slave as ESP32 Emulator (Slave)
+    participant Master as ESP32 Target (Master)
+
+    Note over Master: App calls scd30_read_data()
+    Master->>Slave: I2C Write: [0x03, 0x00] (Read Cmd)
+    activate Slave
+    Slave->>PC: UART Send: "CMD:0300\n"
+    Note right of Slave: Slave STRETCHES Clock (SCL LOW)
+    
+    Note over PC: Lib parses CMD, calculates<br/>Floats & CRCs
+    PC->>Slave: UART Send: "DATA:010203...\n"
+    
+    Slave->>Slave: Parse Hex to Bytes
+    Slave->>Master: Load I2C Buffer & Release SCL
+    deactivate Slave
+    Master->>Slave: I2C Read: 18 Bytes
+    
+    Note over Master: App parses bytes to Float
+    Master->>PC: UART Print: "CO2: 450.00..."
+    Note over PC: Global script captures & logs to CSV
+
+```
+
+---
+
+## 3. Component Breakdown
+
+### A. Target ESP32 (`scd30.c`)
+
+* **Role:** Acts as the I2C Master. It believes it is talking to a real SCD30.
+* **Key Logic:** * **Initialization:** Configures `scl_wait_us = 150000`. This is the timeout for how long it will wait while the Slave is stretching the clock.
+* **Parsing:** Takes 18 bytes and reconstructs three 32-bit floats. It skips every 3rd byte because that is the CRC.
+* **Polling:** It continuously asks "Are you ready?" (0x0202) until the Emulator (PC) replies with "Yes" (0x01).
+
+
+
+### B. Emulator ESP32 (`main.c`)
+
+* **Role:** The "Transparent Bridge."
+* **Key Logic:**
+* **Event-Driven:** Uses a callback (`on_recv_done`) to notify a task that the Master has sent a command.
+* **Clock Stretching:** By not loading the TX buffer immediately, the hardware automatically holds the SCL line low. This pauses the Master's CPU.
+* **Synchronization:** It bridges the I2C domain (microseconds) to the PC domain (milliseconds).
+
+
+
+### C. Python Library (`hil_lib.py`)
+
+* **Role:** The "Sensor Physics Engine."
+* **Key Logic:**
+* **SCD30 Protocol Emulation:** It knows that if the Master sends `0202`, it must reply with `000103` (Ready).
+* **Data Formatting:** Converts human-readable numbers (like `450.0`) into the raw hex bytes and CRCs the ESP32 expects.
+
+
+
+### D. Global Script (`run_test.py`)
+
+* **Role:** The "Test Orchestrator."
+* **Key Logic:**
+* **Iteration:** Loops through a list of test values.
+* **Verification:** It acts as a "Man-in-the-Middle." It knows what value it *sent* to the sensor and reads the Target's serial to see what value the Target *received*.
+* **Persistence:** Saves the input/output pair into a `.csv` for audit and validation.
+
+
+
+---
+
+## 4. Hardware Connectivity
+
+| Connection | Requirement | Why? |
+| --- | --- | --- |
+| **SDA to SDA** | 4.7kΩ Pull-up to 3.3V | Data signal integrity |
+| **SCL to SCL** | 4.7kΩ Pull-up to 3.3V | Clock signal integrity |
+| **GND to GND** | Solid Copper Wire | Reference voltage for signals |
+| **UART 0** | USB Cable to PC | Command/Data bridge |
+
+---
+
+## 5. Troubleshooting the Workflow
+
+* **Symptom:** Target says `Failed to read data`.
+* **Cause:** Python script took longer than 200ms to respond OR `scl_wait_us` is too low.
+
+
+* **Symptom:** Target reads `0.00`.
+* **Cause:** The CRC check failed in the C code, or the Python script sent the bytes in the wrong order.
+
+
+* **Symptom:** CSV only has Column 1, not Column 2.
+* **Cause:** The Target ESP32 is not printing to the correct Serial port, or the baud rate is mismatched.
+