# DevBellBridge **Repository Path**: xqtang/devbell-bridge ## Basic Information - **Project Name**: DevBellBridge - **Description**: This DevBell repository is designed to run on the Trae endpoint. - **Primary Language**: Python - **License**: MulanPSL-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-30 - **Last Updated**: 2026-11-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
English · 简体中文
# DevBell PC Bridge  DevBell mirrors a Trae (IDE) session's state onto the AI Passport: the handheld shows whether Trae is idle, working, waiting for a confirmation or a choice, done, or blocked by an error, and **speaks a voice prompt in Chinese or English** whenever a human has to act on the computer. The PC side is a small Python program that keeps one BLE link to the device and exposes a local HTTP API plus a CLI. > Standalone packaging of the bridge for simple deployment. The same code also > ships inside the `ai-passport` repository under `tools/devbell_bridge/`; > this project is the distribution to copy to other machines. > > **New here?** The end-to-end guide (flashing the firmware, deploying, > auto-start, driving the device, troubleshooting) is > [docs/devbell-guide.md](docs/devbell-guide.md). ```text Trae / shell / any tool --HTTP--> bridge --BLE--> AI Passport ``` ## Requirements - Python 3.10+ (developed on 3.10.11) - `bleak` (BLE client, Windows/macOS/Linux) - AI Passport running the DevBell firmware, powered on and within radio range - No pairing step: the firmware advertises an open GATT service named `DevBell` ```bash pip install . # from the project root; installs bleak + the devbell / devbell-bridge commands pip install ".[test]" # additionally installs pytest for the test suite ``` ## Run the bridge For a persistent, always-on bridge run the **watchdog** (it restarts the bridge if it is killed for any reason): ```bash devbell-bridge-watchdog # equivalent: python -X utf8 -m devbell_bridge.watchdog ``` For a one-off foreground run (e.g. debugging): ```bash devbell-bridge # HTTP API on 127.0.0.1:8765 devbell-bridge --verbose # same, with BLE logs devbell-bridge --port 9000 # equivalent without the console script: python -X utf8 -m devbell_bridge ``` Windows convenience wrappers (require `pip install .` first): ```bat scripts\devbell-bridge.cmd scripts\devbell.cmd show ``` The bridge reconnects on its own. If the device is off it keeps scanning and the HTTP API returns `503` until the link is up. To start the bridge automatically at Windows logon, see [devbell-autostart](docs/devbell-autostart.md). ## CLI ```bash devbell status working -m "refactoring devbell_ui.c" devbell status waiting_confirm -m "Allow writing main/CMakeLists.txt?" devbell status done -m "firmware built" devbell status error -m "build failed: undefined reference" devbell show # device state, battery, volume, mute devbell ping # round-trip check devbell mute toggle # or on / off devbell volume 80 devbell lang en # English UI and voice; lang zh switches back ``` `state` accepts English keys (`idle`, `working`, `waiting_confirm`, `waiting_choice`, `done`, `error`), their numbers `0..5`, or the Chinese labels shown on the device (the localized README lists them verbatim). `--silent` updates the screen without sound; `--force` re-speaks even when the state is unchanged. ## HTTP API | Method | Path | Body | Purpose | | --- | --- | --- | --- | | POST | `/status` | `{"state": "...", "message": "...", "force_alert": false, "silent": false}` | push a state | | POST | `/config` | `{"volume": 0-100, "muted": false, "lang": "zh\|en"}` | volume / mute / language | | POST | `/ping` | `{}` | liveness | | GET | `/status` | – | snapshot: state, battery, volume, mute, language, last button | | GET | `/health` | – | `{"ok": true, "connected": true}` | A POST answers after the device ACKs (3 s timeout): ```json {"seq": 12, "acked": true, "accepted": true, "result": 0} ``` ## Behaviour on the device - `waiting_confirm` / `waiting_choice` speak a prompt telling the user to check the computer, and re-speak every 20 s (at most 3 times) until acknowledged. - Language (`zh` by default) governs both the screen labels and the voice clips. It **auto-follows the language of the `message` text** in every `POST /status` — any CJK ideograph (Hanzi) flips to `zh`, otherwise `en`. Explicit overrides via `devbell lang en` or `POST /config {"lang": "en"}` are valid only until the next status push. A reboot returns to Chinese. - `done` and `error` speak once. - The `done` marker and its prompt stay on screen for 17 s: an `idle` pushed right after is deferred, and `working → idle` without a `done` is treated as a completion. - `idle` and `working` are silent. - Short press **OK**: acknowledge, stop the voice, report a button event to the bridge. - Long press **OK**: toggle mute (screen only, no sound). - **UP/DOWN**: scroll the message card. ## Protocol Binary frames, 9 bytes of overhead, CRC16-CCITT-FALSE, little endian. See `src/devbell_bridge/protocol.py` — kept byte-identical with the firmware's `main/devbell_protocol.h` in the `ai-passport` repository. ## Tests ```bash pytest ``` ## Verified vs unverified - **Verified**: framing/CRC/UTF-8 truncation unit tests on both sides, firmware build, PC-side state mapping. - **Unverified**: real BLE throughput on your radio, Windows BLE adapter quirks, voice loudness in a real room, end-to-end latency from Trae action to sound.