How filippoxausa/redpanda4x4 works
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: control_logic.cpp Control logic · espnow_sender.cpp ESP-NOW TX · auto_drive.cpp Auto drive · main.cpp Sender main
Components 19
Controller TX
Handheld sender firmware and local monitor output.
- Sender main · Controller runtime bootstrap and loop.
RedPanda4x4_sender/src/main.cpp - Joystick · Reads stick axes and buttons.
RedPanda4x4_sender/src/joystick.cpp - MPU6500 · Reads orientation and tilt for control input.
RedPanda4x4_sender/src/mpu6500_reader.cpp - ESP-NOW TX · Packages controller state and transmits it.
RedPanda4x4_sender/src/espnow_sender.cpp
Vehicle RX
Rover firmware for actuation, sensing, and autonomy.
- Receiver main · Rover runtime bootstrap and loop.
RedPanda4x4_receiver/src/main.cpp - ESP-NOW RX · Receives commands and stores latest state.
RedPanda4x4_receiver/src/espnow_receiver.cpp - Control logic · Selects manual, safe, and autonomous behavior.
RedPanda4x4_receiver/src/control_logic.cpp - Auto drive · Finite-state navigation and obstacle response.
RedPanda4x4_receiver/src/auto_drive.cpp - Motor driver · Controls the TB6612FNG dual motor stage.
RedPanda4x4_receiver/src/motor_tb6612.cpp - Cam servo · Pans the camera mount.
RedPanda4x4_receiver/src/servo_cam.cpp - Scan servo · Sweeps the ultrasonic sensor for scanning.
RedPanda4x4_receiver/src/servo_ultrasonic.cpp - IR sensor · Detects nearby obstacles and ground conditions.
RedPanda4x4_receiver/src/ir_sensor.cpp - OLED display · Shows rover mode and state locally.
RedPanda4x4_receiver/src/display_oled.cpp - Buzzer · Audible alerts and feedback.
RedPanda4x4_receiver/src/buzzer.cpp
Shared Contract
Message schema used across the ESP-NOW link.
- Control msg · Compact control payload shared with the rover.
RedPanda4x4_sender/include/control_msg.h - Control msg · 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 · Standalone MJPEG camera stream and capture runtime.
src/cam/cam/cam.ino - YOLO host · Python-side camera consumer and object detection pipeline.
src/cam/script.py - Monitor board · Separate TFT/CYD monitor path fed by the controller over UART.
src/receiverMonitor/receiverMonitor.ino
Connections 21
- 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.