# filippoxausa/redpanda4x4 architecture

> Architecture diagram of the GitHub repository filippoxausa/redpanda4x4, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/filippoxausa/redpanda4x4
- Repository: https://github.com/filippoxausa/redpanda4x4

## Overview

1. **Repository shape**
   - The repo is split into two primary ESP32 firmware projects: `RedPanda4x4_sender` and `RedPanda4x4_receiver`.
   - Around them are two optional companion pieces: a camera streaming sketch under `src/cam` and a vehicle status monitor sketch under `src/receiverMonitor`.
   - The main architectural boundary is the wireless link between controller and rover: **ESP-NOW**.

2. **Controller / TX subsystem**
   - `RedPanda4x4_sender` is the handheld controller firmware.
   - It reads two joysticks and an **MPU6500 IMU**, then turns those inputs into a compact control message.
   - It also has a UART output to a separate TFT/CYD monitor board, so the controller is both a sender and a local UI source.

3. **Vehicle / RX subsystem**
   - `RedPanda4x4_receiver` runs on the rover ESP32 and is responsible for actuation and onboard feedback.
   - It receives wireless control messages, interprets them, and drives motors, servos, buzzer, and OLED.
   - This side also owns the autonomous obstacle-avoidance behavior, so the vehicle is not just a passive receiver.

4. **Shared message contract**
   - `control_msg.h` exists in both sender and receiver projects, which indicates a shared data contract across the ESP-NOW link.
   - That shared message is the architectural seam between human input on TX and motion/behavior on RX.
   - The sender packages joystick/tilt/autonomous intent; the receiver consumes the latest message as its command input.

5. **Wireless command flow**
   - Input originates from joystick axes, joystick buttons, and IMU orientation on the controller.
   - Those inputs are normalized in the sender, then transmitted over ESP-NOW.
   - On the rover, the ESP-NOW receive module stores the most recent command and hands it to control logic rather than directly driving hardware from the radio callback.

6. **Motion and actuator layer on the vehicle**
   - Motor control is isolated in `motor_tb6612.*`, which wraps the TB6612FNG dual motor driver for the 4WD chassis.
   - `servo_cam.*` and `servo_ultrasonic.*` represent two separate servo-controlled actuators: camera pan and ultrasonic sensor scanning.
   - `buzzer.*` and `display_oled.*` provide local feedback, keeping human-visible state on the rover itself.

7. **Vehicle perception and safety inputs**
   - `ir_sensor.*` and the ultrasonic subsystem provide obstacle sensing for the rover.
   - The ultrasonic sensor is mounted on a scan servo, which means perception is not fixed-angle; the rover can actively sample space to the left and right.
   - These sensors feed the autonomous driving decisions and also act as safety inputs even when the rover is under manual command.

8. **Autonomous driving subsystem**
   - `auto_drive.*` and `control_logic.*` together implement the rover’s behavior selection.
   - The README shows a finite-state machine with states for forward, stop, scan, back, and turn.
   - This autonomy lives on the vehicle side, so auto-navigation does not depend on the controller continuously micromanaging motion.

9. **Feedback and operator visibility**
   - The rover reports status locally via an SSD1306 OLED and a buzzer, so the vehicle can communicate mode and events without the controller.
   - The controller also has a monitor board path through UART, which creates a second UI channel distinct from the wireless command channel.
   - This gives the system three visibility surfaces: controller-side monitor, vehicle OLED, and audible buzzer.

10. **Optional camera/vision path**
   - The camera module is architecturally separate from the control loop.
   - It serves an MJPEG stream over HTTP using ESP32-camera style infrastructure, and a Python host script can consume that stream and run YOLO ONNX inference.
   - This vision path is for observation/detection only; it does not appear to be in the main control loop between TX and RX.

11. **Build and runtime boundary**
   - The two main firmware projects are PlatformIO-based ESP32 applications, which keeps controller and rover firmware isolated at the project level.
   - The camera and monitor pieces are separate Arduino-style sketches, reinforcing that they are optional companions rather than part of the core control runtime.
   - The architecture therefore centers on two embedded nodes connected by ESP-NOW, with separate peripherals and optional auxiliary devices around them.

Main entry points: [`RedPanda4x4_receiver/src/control_logic.cpp`](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/control_logic.cpp) (Control logic), [`RedPanda4x4_sender/src/espnow_sender.cpp`](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_sender/src/espnow_sender.cpp) (ESP-NOW TX), [`RedPanda4x4_receiver/src/auto_drive.cpp`](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/auto_drive.cpp) (Auto drive), [`RedPanda4x4_sender/src/main.cpp`](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_sender/src/main.cpp) (Sender main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_controller["Controller TX"]
  node_sender_main["Sender main<br/>entrypoint<br/>[main.cpp]"]
  node_joystick["Joystick<br/>input module<br/>[joystick.cpp]"]
  node_imu["MPU6500<br/>sensor module<br/>[mpu6500_reader.cpp]"]
  node_tx_link["ESP-NOW TX<br/>wireless sender<br/>[espnow_sender.cpp]"]
end

subgraph group_vehicle["Vehicle RX"]
  node_rx_main["Receiver main<br/>entrypoint<br/>[main.cpp]"]
  node_rx_link["ESP-NOW RX<br/>wireless receiver"]
  node_logic["Control logic<br/>state logic<br/>[control_logic.cpp]"]
  node_auto_drive["Auto drive<br/>autonomy<br/>[auto_drive.cpp]"]
  node_motor["Motor driver<br/>actuator driver<br/>[motor_tb6612.cpp]"]
  node_cam_servo["Cam servo<br/>actuator driver<br/>[servo_cam.cpp]"]
  node_scan_servo["Scan servo<br/>actuator driver"]
  node_ir["IR sensor<br/>sensor module<br/>[ir_sensor.cpp]"]
  node_oled["OLED display<br/>status output<br/>[display_oled.cpp]"]
  node_buzzer["Buzzer<br/>status output<br/>[buzzer.cpp]"]
end

subgraph group_shared["Shared Contract"]
  node_tx_msg["Control msg<br/>shared packet<br/>[control_msg.h]"]
  node_rx_msg["Control msg<br/>shared packet<br/>[control_msg.h]"]
end

subgraph group_aux["Optional Companions"]
  node_cam_sketch["Camera sketch<br/>vision companion<br/>[cam.ino]"]
  node_vision["YOLO host<br/>host inference<br/>[script.py]"]
  node_monitor["Monitor board<br/>uart companion"]
end

node_sender_main -->|"reads input"| node_joystick
node_sender_main -->|"reads input"| node_imu
node_joystick -->|"control state"| node_tx_link
node_imu -->|"tilt state"| node_tx_link
node_tx_link -->|"encodes"| node_tx_msg
node_tx_msg -->|"shared schema"| node_rx_msg
node_tx_link -->|"ESP-NOW"| node_rx_link
node_rx_main -->|"initializes"| node_rx_link
node_rx_link -->|"latest command"| node_logic
node_rx_msg -->|"interprets"| node_logic
node_logic -->|"selects mode"| node_auto_drive
node_logic -->|"drives"| node_motor
node_logic -->|"positions"| node_cam_servo
node_logic -->|"scans"| node_scan_servo
node_ir -->|"safety input"| node_auto_drive
node_scan_servo -->|"range scan"| node_auto_drive
node_auto_drive -->|"autonomous motion"| node_motor
node_logic -->|"status"| node_oled
node_logic -->|"alerts"| node_buzzer
node_sender_main -->|"UART status"| node_monitor
node_cam_sketch -->|"MJPEG stream"| node_vision

click node_sender_main "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_sender/src/main.cpp"
click node_joystick "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_sender/src/joystick.cpp"
click node_imu "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_sender/src/mpu6500_reader.cpp"
click node_tx_link "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_sender/src/espnow_sender.cpp"
click node_tx_msg "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_sender/include/control_msg.h"
click node_rx_main "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/main.cpp"
click node_rx_link "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/espnow_receiver.cpp"
click node_rx_msg "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/include/control_msg.h"
click node_logic "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/control_logic.cpp"
click node_auto_drive "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/auto_drive.cpp"
click node_motor "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/motor_tb6612.cpp"
click node_cam_servo "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/servo_cam.cpp"
click node_scan_servo "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/servo_ultrasonic.cpp"
click node_ir "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/ir_sensor.cpp"
click node_oled "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/display_oled.cpp"
click node_buzzer "https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/buzzer.cpp"
click node_cam_sketch "https://github.com/filippoxausa/redpanda4x4/blob/main/src/cam/cam/cam.ino"
click node_vision "https://github.com/filippoxausa/redpanda4x4/blob/main/src/cam/script.py"
click node_monitor "https://github.com/filippoxausa/redpanda4x4/blob/main/src/receiverMonitor/receiverMonitor.ino"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sender_main,node_joystick,node_imu,node_tx_link toneBlue
class node_rx_main,node_rx_link,node_logic,node_auto_drive,node_motor,node_cam_servo,node_scan_servo,node_ir,node_oled,node_buzzer toneAmber
class node_tx_msg,node_rx_msg toneMint
class node_cam_sketch,node_vision,node_monitor toneRose
```

## Components

### Controller TX

Handheld sender firmware and local monitor output.

- [Sender main](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_sender/src/main.cpp): entrypoint · Controller runtime bootstrap and loop. · `RedPanda4x4_sender/src/main.cpp`
- [Joystick](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_sender/src/joystick.cpp): input module · Reads stick axes and buttons. · `RedPanda4x4_sender/src/joystick.cpp`
- [MPU6500](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_sender/src/mpu6500_reader.cpp): sensor module · Reads orientation and tilt for control input. · `RedPanda4x4_sender/src/mpu6500_reader.cpp`
- [ESP-NOW TX](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_sender/src/espnow_sender.cpp): wireless sender · Packages controller state and transmits it. · `RedPanda4x4_sender/src/espnow_sender.cpp`

### Vehicle RX

Rover firmware for actuation, sensing, and autonomy.

- [Receiver main](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/main.cpp): entrypoint · Rover runtime bootstrap and loop. · `RedPanda4x4_receiver/src/main.cpp`
- [ESP-NOW RX](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/espnow_receiver.cpp): wireless receiver · Receives commands and stores latest state. · `RedPanda4x4_receiver/src/espnow_receiver.cpp`
- [Control logic](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/control_logic.cpp): state logic · Selects manual, safe, and autonomous behavior. · `RedPanda4x4_receiver/src/control_logic.cpp`
- [Auto drive](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/auto_drive.cpp): autonomy · Finite-state navigation and obstacle response. · `RedPanda4x4_receiver/src/auto_drive.cpp`
- [Motor driver](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/motor_tb6612.cpp): actuator driver · Controls the TB6612FNG dual motor stage. · `RedPanda4x4_receiver/src/motor_tb6612.cpp`
- [Cam servo](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/servo_cam.cpp): actuator driver · Pans the camera mount. · `RedPanda4x4_receiver/src/servo_cam.cpp`
- [Scan servo](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/servo_ultrasonic.cpp): actuator driver · Sweeps the ultrasonic sensor for scanning. · `RedPanda4x4_receiver/src/servo_ultrasonic.cpp`
- [IR sensor](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/ir_sensor.cpp): sensor module · Detects nearby obstacles and ground conditions. · `RedPanda4x4_receiver/src/ir_sensor.cpp`
- [OLED display](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/display_oled.cpp): status output · Shows rover mode and state locally. · `RedPanda4x4_receiver/src/display_oled.cpp`
- [Buzzer](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/src/buzzer.cpp): status output · Audible alerts and feedback. · `RedPanda4x4_receiver/src/buzzer.cpp`

### Shared Contract

Message schema used across the ESP-NOW link.

- [Control msg](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_sender/include/control_msg.h): shared packet · Compact control payload shared with the rover. · `RedPanda4x4_sender/include/control_msg.h`
- [Control msg](https://github.com/filippoxausa/redpanda4x4/blob/main/RedPanda4x4_receiver/include/control_msg.h): shared packet · Shared command schema consumed on the rover. · `RedPanda4x4_receiver/include/control_msg.h`

### Optional Companions

Separate sketch-based peripherals outside the main control loop.

- [Camera sketch](https://github.com/filippoxausa/redpanda4x4/blob/main/src/cam/cam/cam.ino): vision companion · Standalone MJPEG camera stream and capture runtime. · `src/cam/cam/cam.ino`
- [YOLO host](https://github.com/filippoxausa/redpanda4x4/blob/main/src/cam/script.py): host inference · Python-side camera consumer and object detection pipeline. · `src/cam/script.py`
- [Monitor board](https://github.com/filippoxausa/redpanda4x4/blob/main/src/receiverMonitor/receiverMonitor.ino): uart companion · Separate TFT/CYD monitor path fed by the controller over UART. · `src/receiverMonitor/receiverMonitor.ino`

## Connections

- Sender main → Joystick: reads input · Controller loop samples stick state.
- Sender main → MPU6500: reads input · Controller loop samples orientation.
- Joystick → ESP-NOW TX: control state · Joystick values are normalized into commands.
- MPU6500 → ESP-NOW TX: tilt state · IMU data is folded into the command packet.
- ESP-NOW TX → Control msg: encodes · Sender fills the shared control message.
- Control msg → Control msg: shared schema · Both firmware projects use the same contract.
- ESP-NOW TX → ESP-NOW RX: ESP-NOW · Commands are transmitted wirelessly to the rover.
- Receiver main → ESP-NOW RX: initializes · Rover sets up radio receive path.
- ESP-NOW RX → Control logic: latest command · Receive module hands off stored command state.
- Control msg → Control logic: interprets · Control logic consumes the shared command format.
- Control logic → Auto drive: selects mode · Behavior layer switches into autonomous states when needed.
- Control logic → Motor driver: drives · Motion commands reach the motor stage.
- Control logic → Cam servo: positions · Control logic can move the camera mount.
- Control logic → Scan servo: scans · Control logic can sweep the ultrasonic sensor.
- IR sensor → Auto drive: safety input · Obstacle sensing influences autonomous behavior.
- Scan servo → Auto drive: range scan · Swept ultrasonic readings support navigation decisions.
- Auto drive → Motor driver: autonomous motion · FSM outputs movement decisions to the drivetrain.
- Control logic → OLED display: status · Mode and events are shown locally on the rover.
- Control logic → Buzzer: alerts · Events are signaled acoustically.
- Sender main → Monitor board: UART status · Controller also feeds a separate local monitor board.
- Camera sketch → YOLO host: MJPEG stream · Standalone camera stream can be consumed for inference.
