# WonderEcho Pro — Research (2026-04-11)

## What It Actually Is

The WonderEcho Pro is an **all-in-one voice interaction module** built on the **CI1302 chip** from Chipintelli. Key specs:

- **Chip:** CI1302 with Brain Neural Processing Unit (BNPU)
- **CPU:** 220 MHz
- **Flash:** 2MB (capable of storing up to 300 command words)
- **Recognition:** Offline neural network, hardware-accelerated
- **Wake word:** "Hello Hiwonder" (default, customizable)
- **Languages:** English + Chinese
- **Accuracy:** ~98% (manufacturer claim)
- **Far-field voice recognition** — works up to ~5m away
- **Built-in:** noise-canceling microphone, hi-fi speaker, amplifier chip, I2C chip for comms
- **Ports:** Type-C (power + firmware + USB audio passthrough on Pro variant), I2C (slave at `0x34`)

## How It Works

### Operating Mode
1. User says wake word ("Hello Hiwonder")
2. Module responds "I'm here" and enters recognition mode
3. User says a command (e.g., "go straight")
4. Module broadcasts confirmation ("going straight")
5. Module writes command byte to I2C register `0x64`
6. Master device (Arduino/STM32/Pi) reads register to get the command
7. After 15s of silence, module enters sleep mode

### I2C Protocol (address 0x34)
| Register | Purpose |
|----------|---------|
| `0x64` | Recognition result (1 byte — 0x00 = no recognition, 0x01 = forward, 0x02 = back, 0x03 = left, 0x04 = right, 0x09 = stop, ...) |
| `0x6E` | Broadcast trigger (2 bytes: type + ID). Type `0x00` = command-entry phrase, `0xFF` = general phrase |
| `0x03` | I2C address reconfiguration (0x33 or 0x34, default 0x34) — new-version modules only |

### Command Word Mapping (default firmware)
| Voice Command | Return Code | Broadcast Response |
|---------------|-------------|-------------------|
| "go straight" | `0x01` | "going straight" |
| "go backward" | `0x02` | "going backward" |
| "turn left" | `0x03` | "turning left" |
| "turn right" | `0x04` | "turning right" |
| "stop" | `0x09` | "copy that" |
| (100+ more) | (various) | (various) |

Full list: [Hiwonder Google Drive — Command Word Protocol List](https://drive.google.com/drive/folders/1xo5YZnQU_wgp0oPT7s2kWCnCrKcfP8ba?usp=sharing)

## Current Wiring on Our Car (2026-04-11) — USB-ONLY COMPOSITE DEVICE

**The WonderEcho Pro variant in our TurboPi Advanced Kit has only a USB-C port** (no I2C pads/headers on the physical module — confirmed by physical inspection by Rajesh).

But this is NOT a limitation — because per the official **TonyPi Pro AI Voice Interaction Course** ([docs.hiwonder.com](https://docs.hiwonder.com/projects/TonyPi_Pro/en/latest/docs/6_ai_voice_interaction_course.html)), the Pro variant exposes the CI1302's wake-word + command output over a **USB-serial bridge** (CH340 chip, 115200 baud), not I2C. The same USB-C cable carries everything:

### USB Composite Device Architecture

```
WonderEcho Pro (USB-C) ─┐
                         │
                         ├──> QinHeng USB Hub (1a86:8091)
                         │    ├── Port 1: CH340 serial (1a86:7523) → /dev/ttyUSB0
                         │    │         └── CI1302 UART @ 115200 baud
                         │    │             └── Wake-word + 300 command bytes
                         │    │
                         │    └── Port 2: JMTek USB Audio Class (0c76:161f)
                         │              ├── Interface 0: Audio Control
                         │              ├── Interface 1: Audio Streaming (speaker)
                         │              ├── Interface 2: Audio Streaming (mic)
                         │              └── Interface 3: HID (volume buttons)
```

### Verified on Pi (2026-04-11)
- `lsusb -t` confirms both the CH340 and the JMTek audio device sit behind the same QinHeng USB hub (1a86:8091), port 2 of the Pi's xHCI root.
- ALSA card 2 = JMTek USB PnP Audio Device with both capture + playback working.
- 2-second mic test captured 64KB at 16kHz mono successfully.
- I2C scan (`i2cdetect -y 1`) shows ONLY `0x77` (sonar). Nothing at 0x34. Confirms I2C is not used.

### Pending Verification (2026-04-11 PM)
- [x] **CONFIRMED 2026-04-11**: Physical unplug test proved the WonderEcho Pro is a USB composite device containing: QinHeng hub `1a86:8091` + CH340 serial `1a86:7523` (/dev/ttyUSB0) + JMTek audio `0c76:161f` (ALSA card 2). All three vanish when unplugged, all three reappear when plugged in. The CI1302's UART output IS accessible via `/dev/ttyUSB0` at 115200 baud.
- [x] **RESOLVED 2026-04-11**: Tested with Hiwonder's exact Python code (`serial.Serial(None, 115200, 8, N, 1)` with `rts=False, dtr=False` before open) — still zero bytes when user spoke "Hello HiWonder" at the car. **Conclusion: our WonderEcho Pro ships without firmware.** The TurboPi Advanced Kit docs explicitly list "Firmware Flashing" (section 8.1.3) as a prerequisite step: *"Refer to Section 6.1... to flash the firmware onto the WonderEcho Pro module. Once the firmware has been successfully burned, install the module onto the robot."* Requires Windows PC + PACK_UPDATE_TOOL.exe + `hello hiwonder firmware.bin` + RST button press.

### Hiwonder's Official Python Code (for when firmware is flashed)

From TonyPi Pro docs, section 6.3.6 (`/home/pi/TonyPi/Functions/voice_interaction/word_detect.py`):

```python
import serial

cmd_dict = {
    b"\xaa\x55\x03\x00\xfb": 'wakeup',
    b"\xaa\x55\x02\x00\xfb": 'sleep',
    b"\xaa\x55\x00\x01\xfb": 'forward',
    b"\xaa\x55\x00\x02\xfb": 'back',
    b"\xaa\x55\x00\x03\xfb": 'turn_left',
    b"\xaa\x55\x00\x04\xfb": 'turn_right',
}

class WonderEcho:
    def __init__(self, port):
        self.s = serial.Serial(None, 115200, serial.EIGHTBITS,
                               serial.PARITY_NONE, serial.STOPBITS_ONE,
                               timeout=0.02)
        self.s.rts = False   # CRITICAL — default asserted state holds CI1302 in reset
        self.s.dtr = False   # CRITICAL — same reason
        self.s.setPort(port)
        self.s.open()
        self.s.reset_input_buffer()

    def detect(self):
        return self.s.read(5)  # 5-byte frames: AA 55 <type> <id> FB
```

Wire protocol: `0xAA 0x55 <type> <id> 0xFB`
- Wake frame: `AA 55 03 00 FB`
- Sleep frame: `AA 55 02 00 FB`
- Command frame: `AA 55 00 <id> FB` (id 01=forward, 02=back, 03=turn_left, 04=turn_right)

### What We Have
- ✅ USB microphone (noise-canceled, far-field, up to 5m in quiet rooms)
- ✅ USB speaker (3.0W per channel, hi-fi, amplified)
- ⏳ Offline wake word detection — **likely available via CH340 USB serial** (awaiting physical verification)
- ⏳ 300 Hiwonder preset commands — **likely available via CH340 USB serial** (same)

**CORRECTION:** I previously wrote that the CI1302's wake-word detection was unavailable on our hardware. That was based on reading the basic WonderEcho (non-Pro) docs, which only describes I2C. The Pro variant uses the SAME CI1302 chip but routes its UART output through a CH340 serial bridge inside the USB-C composite. The capability is accessible on our hardware — we just need to read `/dev/ttyUSB0` at 115200 baud instead of wiring I2C.

## Options for her-os Integration

### Option A: Annie speaks through the car (RECOMMENDED for Sunday)
- **Hardware changes:** none
- **Effort:** ~2 hours
- **What we get:** Annie's Kokoro TTS plays through the car speaker. When Annie responds in Telegram, the audio comes out of the car, not the phone. The car literally becomes her body.
- **Implementation:**
  - New `POST /speak` endpoint on turbopi-server — accepts WAV bytes, plays via `aplay -D plughw:2,0`
  - Annie-side: Kokoro TTS generates WAV on Titan, POSTs to Pi `/speak`
  - Integrate with `car_demo` lifecycle: demo start/stop announcements through car speaker
- **Use cases:**
  - Guest: "Annie, what can your car do?" → Annie's voice comes out of the car: "I've learned quite a few tricks..."
  - Demo start: car says "Chase ball mode! Put a blue ball down and I'll follow it!"
  - Demo stop: car says "That was fun! Want another trick?"

### Option B: Talk TO the car (post-Sunday, ambitious)
- **Hardware changes:** none
- **Effort:** ~6-8 hours
- **What we get:** Full bidirectional voice. Guest walks up to the car and talks — WonderEcho mic captures, Pi streams to Titan, Whisper transcribes, Gemma 4 responds, Kokoro TTS plays back through the car.
- **Wake mechanism:** push-to-talk button (simplest) or Picovoice Porcupine with custom "Hey Annie" wake word (~4-6h extra)
- **Implementation:**
  - Pi-side: WebSocket or HTTP streaming audio endpoint, VAD trigger, forward audio to Titan
  - Titan-side: new endpoint in annie-voice that accepts streamed audio (similar to phone integration)
  - Handle turn-taking, latency, barge-in
- **Use case:** fully embodied Annie — the car is the interface, no phone needed

### Option C: Porcupine Custom Wake Word (future)
- **Hardware changes:** none
- **Effort:** ~4-6 hours
- **What we get:** custom wake word like "Hey Annie" running locally on the Pi, triggered by WonderEcho mic
- **Use case:** guest says "Hey Annie" in front of the car → car wakes up, captures following audio, streams to Titan for processing
- **Only needed if we want hands-free wake instead of push-to-talk**

### Option D: ~~Wire I2C for offline wake word~~ — **NOT POSSIBLE**
- **Ruled out (2026-04-11):** the WonderEcho Pro variant in our TurboPi Advanced Kit does not expose I2C pads/headers. Only the USB-C port is accessible. The CI1302 chip's wake-word detection and 300 command words cannot be reached from the Pi on this hardware. This is a hardware constraint, not a software one.
- **If we ever want this:** we'd need to buy a separate WonderEcho module (non-Pro?) that exposes I2C pins, or desolder/solder the Pro variant to expose the CI1302's I2C lines (risky).

## Recommendation

**For Sunday demo: Option A ONLY.** ~2 hours of work, no hardware risk, high wow factor. Annie's voice comes from the car.

**Post-Sunday: Option B** (talk to the car directly) as the next big milestone. Option C (custom wake word) only if we want hands-free instead of push-to-talk.

**The CI1302 BNPU is unusable silicon on our variant.** Move on — we have Whisper + Gemma 4 + Kokoro on a 128 GB unified-memory GPU, which is far more capable than any onboard wake-word chip anyway.

## Sources
- [WonderEcho Module Introduction](https://docs.hiwonder.com/projects/WonderEcho/en/latest/docs/1_Module_Introduction.html)
- [WonderEcho Getting Started](https://docs.hiwonder.com/projects/WonderEcho/en/latest/docs/2_Getting_Started.html)
- [WonderEcho Multi-Controller Communication](https://docs.hiwonder.com/projects/WonderEcho/en/latest/docs/4_Multiple_Controller_Communication_Tutorial.html)
- [WonderEcho Firmware Development](https://docs.hiwonder.com/projects/WonderEcho/en/latest/docs/5_Firmware_Development.html)
- [TurboPi Large AI Model Courses](https://docs.hiwonder.com/projects/TurboPi/en/advanced/docs/8.Large_AI_Model_Courses.html)
- Hiwonder command word protocol list (Google Drive — see I2C tutorial page)