| name | clip-sdk |
| description | Develop, test, package, or debug the standalone reSpeaker Clip Python SDK in sdk/. Use for typed AT APIs, Bleak or UDP transports, streaming downloads, CLI tools, clip.web, BLE-to-Wi-Fi handoff, package extras, console scripts, and SDK compatibility with current Clip firmware. |
reSpeaker Clip Python SDK
Work only in sdk/ unless the task explicitly changes the firmware protocol.
Do not move, import, or rewrite applications/clip/tests; it is the legacy
tool collection retained for hardware and historical use.
Source and compatibility rules
- Read the current command registrations in
applications/clip/src/at_commands.c before adding or changing an SDK API.
- Treat
docs/protocol.md and firmware source as the protocol contract; update
both SDK and protocol documentation when the firmware contract changes.
- Do not emulate removed legacy commands such as
BITRATE, COMPLEXITY,
NOISE, AGC, DEREVERB, or PURGE.
- Preserve response semantics: failures use
msg, successful payloads are
usually under data, and the protocol has no request ID.
Implementation workflow
- Keep AT requests serialized. After a timeout, reconnect before issuing a
new request so a late response cannot be assigned to another command.
- Validate session IDs (
YYYYMMDDHHMMSS) and logical chunk names
(NNNN.opus) before constructing an AT command or filesystem path.
- Stream transfer payloads to
*.part, verify declared length and final CRC32,
then atomically rename. Never buffer a complete recording in memory.
- Distinguish BLE frames from UDP frames: UDP DATA has a per-frame CRC32 and
requires FILE_ACK after full-file verification.
- Keep optional functionality in extras:
ble, web, and their console
commands must fail clearly when an optional dependency is absent.
- Keep the local web service loopback-only by default. Browser code requests a
host Wi-Fi handoff; only Python may invoke
nmcli, networksetup, or
netsh.
Required checks
cd sdk
pytest -q
python -m pip wheel --no-deps --wheel-dir /tmp/clip-sdk-wheel .
Inspect wheel metadata and console scripts after changing pyproject.toml.
When testing clip.web, install the web extra; add ble only for BLE use.
Hardware transfer and host Wi-Fi join tests are integration tests: do not claim
them successful without a real Clip and a supported 5 GHz host adapter.
Useful commands
python -m pip install -e '.[dev,ble]'
python -m pip install -e '.[web,ble]'
clip.terminal --transport ble
clip.sync --transport udp --all
clip.web --transport ble
clip.wifi --address AA:BB:CC:DD:EE:FF
Read references/sdk-contract.md for frame,
packaging, and Wi-Fi handoff details.
