Chopper body v2

Chopper Body V2

Acknowledgments

This firmware was strongly influenced by the Amidala firmware by thePunderWoman.

ESP32-based body controller for the Chopper robot. Controls drive motors, dome rotation, body servos, MP3 audio, and a bubble machine via ESP-NOW commands from the controller.

Features

• MDDS30 drive motors — PWM Independent mode, differential steering
• Cytron MD10C dome rotation — bidirectional speed control
• Pololu Maestro servos — scripted body animations via Serial1
• MP3 audio player — serial protocol playback via Serial2
• Bubbles relay — on/off control
• ESP-NOW — encrypted communication with the controller
• WiFi AP + OTA — web interface at chopper.body for firmware updates
• Safety timeout — motors stop after 500ms without commands or on ESP-NOW disconnect

ESP32 Pin Assignments

GPIO12 and GPIO13 (previously used for MDDS30) are intentionally left unconnected — GPIO12 is an ESP32 boot-strapping pin (flash voltage select) and stray HIGH signals on it during power-up can put the board in a reset loop. GPIO22/23 (previously Maestro) and GPIO34 (previously dome encoder B) are also now unused.

MDDS30 DIP Switch Setting

0b10110100 — PWM Independent mode. All three hardware UARTs remain free.

Serial Port Allocation

Build

Requires PlatformIO.

Before your first build, set up ESP-NOW encryption keys — see Generating ESP-NOW keys below. The build will fail with a clear error if .env is missing.

# One-time setup: copy the template and fill in real keys
cp .env.example .env

# Compile firmware
pio run

# Upload to ESP32
pio run --target upload

# Run unit tests (native)
pio test -e native

# Monitor serial output
pio device monitor

Project Structure

pcb/                                  # KiCad project (schematic, board, gerbers)
firmware/
  platformio.ini
  .env.example                       # Template for ESP-NOW keys — copy to .env
  partitions/ota_4MB.csv
  scripts/load_secrets.py            # Pre-build: .env -> include/secrets.h
  scripts/embed_web.py              # Pre-build: inlines CSS into HTML
  web/
    assets/common.css                # Shared styles
    index.html                       # Home page (info + links)
    update.html                      # OTA firmware upload page
  include/
    web_pages.h                      # AUTO-GENERATED by embed_web.py
    secrets.h                        # AUTO-GENERATED by load_secrets.py, gitignored
  src/
    config.h                         # Pin definitions, timeouts (keys come from secrets.h)
    main.cpp                         # Setup/loop, WiFi, command dispatch
    communication/
      MessageTypes.h                 # BodyCommand / BodyTelemetry structs
      EspNowController.h/.cpp        # ESP-NOW encrypted communication
    motor/
      MotorController.h/.cpp         # MDDS30 + L298N motor control
    servo/
      ServoController.h/.cpp         # Pololu Maestro body servos

ESP-NOW Protocol

Controller -> Body (msgType = 3, 26 bytes)

Body -> Controller (msgType = 4, 8 bytes)

WiFi Access Point

• SSID: ChopperBody
• IP: 192.168.5.1
• mDNS: chopper-body.local
• Pages: / (home), /update (OTA)
• API: /api/info (JSON: version, uptime, heap, MAC)

Generating ESP-NOW keys

This board talks to the other Chopper boards over encrypted ESP-NOW. Before your first build, generate two 16-byte (128-bit) keys — a Primary Master Key (PMK) and a Local Master Key (LMK) — and put them in a .env file (gitignored, never commit it) at the project root:

cp .env.example .env

Generate two random 16-byte keys, each as 32 hex characters:

# Option 1: openssl
openssl rand -hex 16   # run twice — once for PMK_KEY, once for LMK_KEY

# Option 2: python
python3 -c "import secrets; print(secrets.token_hex(16))"

Edit .env and paste the values in:

PMK_KEY=<first random hex string>
LMK_KEY=<second random hex string>

These two keys must be byte-for-byte identical across chopper body, chopper head, and chopper receiver — generate them once and copy the same .env values into all three projects. Mismatched keys mean the boards can't decrypt each other's ESP-NOW packets and the mesh will never connect.

.env also holds CONTROLLER_MAC — the controller's WiFi MAC address (as hex, e.g. C0CDD6CA29E0), which must likewise be identical across all three firmware projects — and WIFI_AP_PASSWORD, the password for this board's local OTA-update access point (pick your own, at least 8 characters; unlike the other values, this one doesn't need to match the other boards).

scripts/load_secrets.py runs automatically before every build (see platformio.ini) and turns .env into include/secrets.h, which config.h includes. Neither .env nor the generated secrets.h are committed to git — the build fails with a clear error if .env is missing.