mermaids

flake.nix

@@ -25,6 +25,7 @@
         cargo-espflash
         espup
 	mosquitto
+	mermaid-cli
       ];
 
 shellHook = ''

mqtt_display/docs/critical_data_flow_points.mermaid

@@ -0,0 +1,37 @@
+graph TD
+    START[MPU reads @50ms = 20 Hz] --> A{IMU_CHANNEL<br/>try_send}
+    
+    A -->|Full| DROP1[❌ DROP: Channel full<br/>16 slots @ 50ms = 800ms buffer]
+    A -->|OK| B[Main Loop receive]
+    
+    B --> C[Drain loop:<br/>Get freshest reading]
+    C --> D{Time check:<br/>≥3s since last?}
+    
+    D -->|No| E[Skip MQTT]
+    D -->|Yes| F{mqtt_set_imu<br/>try_lock IMU_LATEST}
+    
+    F -->|Locked| DROP2[❌ SKIP: Mutex busy]
+    F -->|OK| G[Store payload]
+    
+    E --> H[show_imu]
+    G --> H
+    
+    H --> I{DISPLAY_CHANNEL<br/>try_send}
+    I -->|Full| DROP3[❌ DROP: Display slow<br/>8 slots @ 100ms = 800ms buffer]
+    I -->|OK| J[Display renders]
+    
+    G --> K[MQTT Task loop]
+    K --> L{IMU_LATEST<br/>try_lock}
+    
+    L -->|Empty/Locked| M[Skip this iteration]
+    L -->|Has data| N[Send to broker<br/>QoS0 no retain]
+    
+    N --> O{TCP send result}
+    O -->|Fail| RECONNECT[❌ Session dies<br/>Reconnect in 5s]
+    O -->|OK| P[✅ Data sent]
+    
+    style DROP1 fill:#ffcccc
+    style DROP2 fill:#ffcccc
+    style DROP3 fill:#ffcccc
+    style RECONNECT fill:#ffcccc
+    style P fill:#ccffcc

mqtt_display/docs/mpu_data_flow.mermaid

@@ -0,0 +1,54 @@
+sequenceDiagram
+    participant HW as MPU6050 Hardware
+    participant MPU as MPU Task<br/>(Core 0)
+    participant CH as IMU_CHANNEL<br/>[16 slots]
+    participant MAIN as Main Loop<br/>(Core 0)
+    participant LATEST as IMU_LATEST<br/>(Mutex)
+    participant MQTT as MQTT Task<br/>(Core 1)
+    participant DISP as Display API
+    
+    Note over MPU: Every 50ms
+    MPU->>HW: Read sensor (I2C)
+    HW-->>MPU: Raw data
+    MPU->>MPU: Convert to ImuReading
+    MPU->>CH: try_send(reading)
+    
+    alt Channel full
+        CH--xMPU: Drop (log warning)
+    else Channel has space
+        CH-->>MPU: OK
+    end
+    
+    Note over MAIN: Continuous loop
+    MAIN->>CH: receive() [blocking]
+    CH-->>MAIN: reading
+    
+    Note over MAIN: Drain queue
+    loop While available
+        MAIN->>CH: try_receive()
+        CH-->>MAIN: newer reading
+    end
+    
+    MAIN->>DISP: show_imu(reading)<br/>[try_send]
+    
+    Note over MAIN: Every 3 seconds
+    alt Time >= 3s since last
+        MAIN->>MAIN: Format JSON payload
+        MAIN->>LATEST: mqtt_set_imu()<br/>[try_lock]
+        
+        alt Mutex available
+            LATEST-->>MAIN: Stored
+        else Mutex locked
+            LATEST--xMAIN: Skip
+        end
+    end
+    
+    Note over MQTT: Continuous loop
+    MQTT->>LATEST: try_lock()
+    
+    alt Data available
+        LATEST-->>MQTT: payload
+        MQTT->>MQTT: send_message("esp32/imu")
+    else No data
+        LATEST--xMQTT: None
+    end

mqtt_display/docs/overall_system_architecture.mermaid

@@ -0,0 +1,42 @@
+graph TB
+    subgraph "Core 0 - Application"
+        MPU[MPU Task<br/>50ms sampling]
+        DISPLAY[Display Task<br/>100ms refresh]
+        MAIN[Main Loop]
+        BUTTONS[Button Task]
+    end
+    
+    subgraph "Core 1 - Network"
+        WIFI[WiFi Connection Task]
+        NETWORK[Network Stack Runner]
+        MQTT[MQTT Task]
+    end
+    
+    subgraph "Shared Channels"
+        IMU_CH[(IMU_CHANNEL<br/>size: 16)]
+        DISP_CH[(DISPLAY_CHANNEL<br/>size: 8)]
+        CMD_CH[(CMD_CHAN<br/>size: 8)]
+        EVT_CH[(EVT_CHAN<br/>size: 8)]
+        IMU_LATEST[(IMU_LATEST<br/>Mutex)]
+    end
+    
+    subgraph "Hardware"
+        MPU_HW[MPU6050<br/>I2C 0x68]
+        OLED[SSD1306<br/>I2C]
+        BROKER[MQTT Broker]
+    end
+    
+    MPU_HW -->|I2C Read| MPU
+    MPU -->|send| IMU_CH
+    IMU_CH -->|receive| MAIN
+    MAIN -->|try_send| DISP_CH
+    MAIN -->|mqtt_set_imu| IMU_LATEST
+    DISP_CH -->|receive| DISPLAY
+    DISPLAY -->|I2C Write| OLED
+    IMU_LATEST -->|try_lock| MQTT
+    MQTT <-->|TCP/IP| BROKER
+    BUTTONS -->|push_key| DISP_CH
+    
+    style IMU_CH fill:#ff9999
+    style DISP_CH fill:#99ccff
+    style IMU_LATEST fill:#ffcc99