Project files

Brain Project (Raspberry Pi / Desktop)

The brain of Ganbei No. 1 — responsible for AI interaction, decision-making, and communication with the cerebellum.

Cross-platform: Python code runs the same set on Windows development and Raspberry Pi (Linux) deployment.

Architecture

car_brain/
├── protocol/          Protocol module
│   ├── crc8.py        CRC8 checksum (consistent with Arduino side)
│   ├── commands.py    Command constants (consistent with Arduino side commands.h)
│   └── frame.py       Frame packaging / parsing
├── serial_link.py     Serial communication layer (frame transmission and reception)
├── brain.py           Brain state machine (state view / heartbeat / button decision)
└── app.py             CLI entry point
tests/
├── test_protocol.py   Protocol unit tests
└── test_brain_loop.py Brain↔Cerebellum memory joint debugging tests

Installation

pip install -r requirements.txt   # Requires pyserial

Running Tests

# Protocol unit tests + brain↔cerebellum joint debugging tests
python -m unittest discover -s tests -v

test_brain_loop.py uses two threads and memory pipes to simulate the complete "brain ↔ cerebellum" conversation, allowing protocol loopback verification without any hardware.

Running the Demo

Method 1: Connect to a Real/Virtual Serial Port

# Windows real serial port
python -m car_brain.app --port COM3 --demo

# Linux / Raspberry Pi
python -m car_brain.app --port /dev/ttyAMA0 --demo

Method 2: Directly drive the native cerebellum (no serial port required, recommended for joint debugging)

First, compile the native cerebellum program (see firmware/arduino/README.md), then let the brain drive it via stdin/stdout pipes:

python -m car_brain.app --native ../firmware/arduino/.pio/build/native/program.exe --demo

This way, you don't need to install com0com virtual serial ports on Windows to see the complete two-way conversation.

🎙️ Voice Control (Offline Recognition with VOSK)

Wake up by saying "Ganbei chulai" (cheers) into the microphone, then give a command; or say everything in one go (e.g., "Ganbei chulai turn on the light").

Supported commands: turn on the headlights / turn off the lights / mute / unmute / level one to four / emergency stop.

Preparation (one-time)

# 1. Create a Python 3.13 virtual environment (system 3.14 may not fully support speech libraries)
py -3.13 -m venv .venv

# 2. Install dependencies
.venv\Scripts\python.exe -m pip install -r requirements.txt

# 3. Download the VOSK Chinese model (~42MB) and extract it to the user directory:
#    https://alphacephei.com/vosk/models/vosk-model-small-cn-0.22.zip
#    The extracted directory should be ~/vosk-model-small-cn-0.22
#    Alternatively, set the environment variable VOSK_MODEL to point to the model directory

Running Voice Control

.venv\Scripts\python.exe -m car_brain.app --native <cerebellum_exe_path> --voice --seconds 120

A microphone is required. Voice recognition is offline and does not require an internet connection. On Windows, it will say "I'm listening, please give a command" as voice feedback.

How to Add / Remove Commands

The "list" of commands is in the COMMAND_RULES table in car_brain/voice.py (each line = one group of synonyms + command):

COMMAND_RULES = (
    (("turn on the headlights", "turn on the lights", "turn on the light", "lights on"), ("light", "on")),  # synonyms → command
    (("brake", "emergency brake", "stop"), ("ebrk", None)),
)

• Add synonyms: Simply add words to the keyword tuple in the corresponding line
• Add new commands, reuse existing actions: Add a new line and use an existing command name (e.g., strip)
• Add completely new actions: Add a new line + add a processing branch in on_voice_command in car_brain/app.py; if a new protocol command is needed, also add a method in car_brain/brain.py
• Delete commands: Simply delete the corresponding line

Changing the TTS Voice

Set the environment variable TTS_VOICE (default: zh-CN-XiaoxiaoNeural 晓晓):

set TTS_VOICE=zh-CN-YunxiNeural   # Yunxi (male voice)
set TTS_VOICE=zh-CN-XiaoyiNeural  # Xiaoyi (female voice)

Options: XiaoxiaoNeural (晓晓) / YunxiNeural (云希) / YunyangNeural (云扬) / XiaoyiNeural (晓伊).

Directory Planning (Future Iterations)

• audio/ —— Engine sound synthesis + audio management
• cloud/ —— 4G communication / MQTT / app integration
• gps/ —— Location reporting