Puppy Firmware and Development

RIG-Puppy's firmware development lives in the RIG series development repository LuwuDynamics/rig_omni. The repository serves multiple RIG products; this chapter focuses only on Puppy build, source layout, configuration, and extension points.

Requirements #

Clone and Build #

git clone https://github.com/LuwuDynamics/rig_omni.git
cd rig_omni
source ~/esp/esp-idf/export.sh
idf.py set-target esp32s3
idf.py menuconfig  # RIG-Omni Configuration -> Board Type -> RIG-Puppy
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

Build a release package:

python tools/gen_bin_package.py  # Output: bin/rig-puppy.bin

Architecture #

RIG-Puppy adopts a highly integrated single-chip architecture. All sensing, control, and AI logic run on a single ESP32-S3 — no external co-processor is needed. This approach delivers high performance while reducing component count and simplifying development.

The project provides open-source resources including schematics, 3D models, firmware code and component lists, plus an assembly tutorial. It is well suited for learning motion control, large-language-model integration, multi-modal systems, and IoT communication.

Hardware Abstraction Layer

• MCU: ESP32-S3-WROOM-1-N16R8 (Dual-core 240 MHz, 2.4G Wi-Fi + BLE 5.0, 16 MB Flash, 8 MB PSRAM)
• Motion bus (UART): TX/RX serial bus driving 5 EM-3 micro servos, with ID-based addressing and status feedback. All 5 servos are daisy-chained on the same signal bus for 5-DOF locomotion.
• Vision link (DVP/SPI): GC0308 camera captures images via DVP interface; ST7789 240×240 1.3" square LCD refreshes expressions over SPI.
• Audio system (I²S): INMP441 MEMS digital microphone for audio input; MAX98357A amplifier drives an 8 Ω 2 W speaker.
• Attitude sensing (I²C): On-board 6-axis IMU (TDK ICM-42670-P) for real-time attitude detection and motion assistance.

Main controller

Vision link — camera & display

Audio system — microphone & amplifier

Project Structure

rig_omni/
  main/
    audio/                 audio, wake word, processors
    display/               LCD driver, EAF animations, LVGL
    led/                   LED strip and GPIO light
    protocols/             MQTT and WebSocket
    boards/
      common/              shared IMU, buttons, BLE, battery, camera
      puppy/               RIG-Puppy board type
    assets/                language packs, fonts
    application.cc/h       application lifecycle
    mcp_server.cc/h        MCP remote-control service
    ota.cc/h               OTA firmware update
    settings.cc/h          NVS settings
  partitions/16m.csv       16MB flash partition
  tools/                   build and asset tools

Key Kconfig Options

Run:

idf.py menuconfig

Useful options:

PUPPY_ENABLE_BLE_CONTROLis disabled by default because BLE may increase memory pressure and affect voice/MCP services.

Puppy Board Directory

main/boards/puppy/
  puppy_board.cc            board initialization and service binding
  board_config.h            board pins and config
  config.json               board config
  xgo.cc / xgo.h            servo communication and motion control
  xgo_action.cc / .h        preset actions
  ble_remote_control.cc/.h  BLE remote control
  emoji/                    emotion assets
  240_240/                  240x240 assets
  wakenet/                  wake word model

MCP Tool Extension

Puppy firmware uses MCP tools to expose robot capabilities such as motion, actions, lights, and camera snapshots.

mcp_server.AddTool("self.robot.move",
    "Move forward/backward in cm",
    PropertyList({Property("distance", kPropertyTypeInteger, -20, 20)}),
    [this](const PropertyList& props) -> ReturnValue {
        int distance = props["distance"].value<int>();
        // Execute movement
        return true;
    });

Puppy Development Suggestions

For Puppy-focused secondary development, start with:

1. Add preset actions in xgo_action.cc/h.

2. Register new MCP tools or action entries in puppy_board.cc.

3. Replace or extend expression assets in emoji/and 240_240/.

4. Check board_config.hagainst the actual hardware batch.

5. Evaluate memory usage before enabling BLE remote control, because it may affect voice and MCP services.