VirtusCo Porter Robot — ESP32 Motor Controller & Sensor Fusion Firmware RTOS: Zephyr · Build Tool: west · Language: C++17

The Porter robot uses 2× ESP32 microcontrollers running Zephyr RTOS, communicating with the RPi 4/5 master over USB CDC Serial (/dev/ttyACM*).

esp32_firmware/
├── README.md                 # This file
├── motor_controller/         # ESP32 #1 — Motor control firmware
│   ├── CMakeLists.txt
│   ├── prj.conf              # Kconfig configuration
│   ├── app.overlay            # Devicetree overlay (GPIO, PWM, USB)
│   └── src/
│       └── main.cpp
├── sensor_fusion/            # ESP32 #2 — Sensor fusion firmware
│   ├── CMakeLists.txt
│   ├── prj.conf
│   ├── app.overlay
│   └── src/
│       └── main.cpp
└── common/                   # Shared code between both firmwares
    ├── include/
    │   ├── protocol.h        # USB CDC binary protocol (shared with RPi)
    │   └── crc16.h           # CRC16 implementation
    └── src/
        ├── protocol.cpp
        └── crc16.cpp

# Install Zephyr SDK and west (see skills/zephyr/01_getting_started.md)
pip install west
west init ~/zephyrproject
cd ~/zephyrproject && west update
west zephyr-export
pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt
west sdk install

cd esp32_firmware/motor_controller
west build -p always -b esp32_devkitc/esp32/procpu
west flash

cd esp32_firmware/sensor_fusion
west build -p always -b esp32_devkitc/esp32/procpu
west flash

west espressif monitor
# or
minicom --device /dev/ttyUSB0 -b 115200

The RPi ↔ ESP32 communication uses USB CDC ACM (virtual serial) with a binary protocol:

• USB CDC ACM — Virtual serial port for RPi communication
• PWM — Motor speed control via BTS7960
• GPIO — Direction control, encoder inputs, sensor triggers
• ADC — Battery voltage monitoring
• State Machine Framework (SMF) — Motor control state machine
• zbus — Internal message passing between subsystems
• Logging — Structured logging via Zephyr logging subsystem
• Task Watchdog — Safety monitoring for motor control
• Shell — Debug shell over secondary UART (development only)

• Zephyr Skills — Comprehensive Zephyr RTOS reference
• OBJECTIVES.md — Project goals and hardware architecture
• COMPANY.md — Company context and product vision