Project files

Hardware Deployment Guide (Follow Along with Your Hardware)

Purpose: Once you have your Raspberry Pi, Arduino, motors, and other hardware, follow this manual step by step to run the functions validated in the digital twin on real hardware. Companion files: See hardware_io_map.md for pin assignments and communication_protocol.md for protocols.

0. Required Hardware List

1. Wiring (Follow the wiring)

1.1 Raspberry Pi ↔ Arduino Communication (UART)

Raspberry Pi 4B            Level Shifter Module        Arduino Mega
GPIO14 (TXD) ────────────►  TTL(3.3V→5V)  ───────────► D19 (RX1)
GPIO15 (RXD) ◄────────────  TTL(5V→3.3V)  ◄─────────── D18 (TX1)
GND ──────────────────────►  Common Ground ────────────► GND

⚠️ A bidirectional level shifter module must be used (Arduino 5V → Raspberry Pi 3.3V direction), otherwise the Raspberry Pi GPIO will be burned out.

1.2 Arduino Actuators (Outputs)

1.3 Arduino Sensors/Buttons (Input)

1.4 Power Supply

Battery 12V ─┬─► ESC ─► Motor
             └─► DC-DC 5V ─► Raspberry Pi + Arduino

1.5 Cheers Assistant Audio (Independent of Sound Effects)

USB microphone ─► Raspberry Pi USB (Cheers Assistant audio input)
USB speaker/sound card ─► Raspberry Pi USB (Cheers Assistant playback response)
3.5mm audio ─► amplifier ─► speaker (engine roar/horn/intercom)

Dialogue and sound effects must use different sound cards; physical isolation is the most stable solution, otherwise engine noise may be captured by the microphone and affect recognition.

2. Download and Installation (Raspberry Pi)

2.1 Raspberry Pi System

# Recommended: Raspberry Pi OS (Bookworm, 64-bit)
# After installation, enable the serial port:
sudo raspi-config
# → Interface Options → Serial Port → Select "Login shell" as No, "Serial hardware" as Yes

2.2 Install Python Dependencies (Brain)

cd ~/OpenKidCar/software/raspberry_pi
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
# Vosk model (replaced by Ganbei Assistant; can be skipped unless offline voice control is needed)
# mkdir -p ~/vosk-model-small-cn-0.22 && download and extract to this directory

2.3 Install the "Ganbei Assistant" (py-xiaozhi)

git clone https://github.com/huangjunsen0406/py-xiaozhi.git
cd py-xiaozhi
python3 -m venv .venv          # Raspberry Pi default Python 3.11 ✅
.venv/bin/pip install -r requirements.txt
# Opus library: Built-in in the project as libs/libopus/linux/arm64/libopus.so, no manual installation required

3. Flashing the Cerebellum Firmware (Arduino)

cd ~/OpenKidCar/firmware/arduino
# Using PlatformIO (VSCode plugin or CLI)
pio run -e mega2560              # Compile
pio run -e mega2560 -t upload    # Flash (USB to Arduino)
# Alternatively, use Arduino IDE: open src/main.cpp, select Mega 2560 board, click Upload

After successful flashing: the serial monitor should display the cerebellum ready (READY V0.3).

4. Starting the Real Hardware System

4.1 Start the Xiaozhi Assistant Bridge

cd ~/py-xiaozhi
.venv/bin/python main.py --mode cli   # First-time activation required: visit xiaozhi.me to enter the verification code

4.2 Start the Digital Twin (with Real Arduino)

cd ~/OpenKidCar/software/raspberry_pi
# 必须先设家长端访问密码（安全）：未设密码会拒绝启动
export OPENKIDCAR_PASSWORD=你的密码
.venv/bin/python digital_twin/backend/twin_server.py 8000 8001 \
    --real-serial /dev/ttyACM0    # 树莓派上 Arduino 通常是 /dev/ttyACM0
# 小车端 http://localhost:8000（仅本机）；家长端 http://<树莓派IP>:8001（需密码登录）

🔐 Security: The parent end (port 8001) requires password login (session authentication); the car end (port 8000) only listens on localhost. Real hardware mode is now supported (--real-serial), see Section 6.

5. Verification Checklist (Test in Order)

6. To Be Developed: Real Serial Port Mode (Digital Twin Connects to Arduino)

Currently, twin_server.py hardcodes CerebellumSim (simulated cerebellum). To connect to a real Arduino, you need to add a startup parameter:

# twin_server.py modification ideas (about 20 lines)
# 1. Add parameter --real-serial /dev/ttyACM0
# 2. When this parameter is present:
#    from car_brain.app import SerialPort
#    self.ceb = None  # No longer using CerebellumSim
#    self.brain = Brain(SerialLink(SerialPort(port, 115200)))
# 3. State snapshot is read from the brain's maintained state (speed is parsed from Arduino STAT reports)
# 4. GPS/battery level is changed to be reported from Arduino / read from a real GPS module

The rest of the code (frontend, protocol, brain, Cheers Assistant) is fully reused, as it was originally designed with "protocol-driven + HAL abstraction" in mind.

7. Troubleshooting

• Raspberry Pi not receiving Arduino data: Check level shifting, baud rate 115200, and whether /dev/ttyACM0 exists (ls /dev/tty*)
• Cheers Assistant has no sound: Check if the USB microphone/speaker is recognized by the system (arecord -l / aplay -l)
• Engine noise interfering with conversation: Make sure conversation uses the USB sound card and sound effects use the 3.5 mm jack—keep them separate
• Burning/flashing fails: Unplug the Raspberry Pi serial connection from the Arduino before flashing (serial port conflict)

OpenKidCar · Cheers No. 1 · Build it by following the hardware guide