reSpeaker Clip firmware
Treat the checked-out source as authoritative. Read CLAUDE.md before changing
firmware: it contains the active NCS version, board sysbuild defaults, power
constraints, release workflow, and current hardware-test commands.
Route the task
| Area |
Source of truth |
Read when needed |
| AT protocol |
applications/clip/src/at_commands.c |
references/ble-at.md |
| BLE/UDP transfer |
transport_ble.c, transport_udp.c, wifi_udp.c |
references/wifi-udp.md |
| Recording and DSP |
audio.c, applications/clip/Kconfig |
references/audio.md |
| FATFS sessions |
storage.c |
references/storage.md |
| Idle and power-off |
clip_event.c, storage.c, battery.c, snippets |
references/power.md |
| Build, flash, artifacts |
CLAUDE.md, board Kconfig.sysbuild |
references/build-flash.md |
| Python package |
sdk/ |
Use the separate clip-sdk skill |
Keep applications/clip/tests intact. It is a legacy test/tool collection;
the installable SDK lives at sdk/ and must not silently inherit legacy
commands or response shapes.
Firmware workflow
- Inspect
git status; preserve unrelated worktree changes.
- Confirm the command, Kconfig, device-tree, storage, or transport contract in
source before editing docs or clients.
- Keep host-visible session IDs as exactly 14 decimal digits
YYYYMMDDHHMMSS; never expose physical FAT paths in the protocol.
- Validate user-controlled command arguments before storage, path, or transfer
access.
DOWNLOAD only accepts session or session:NNNN.opus.
- Build and test in proportion to the change. Flash only the image the user
requested;
--recover erases the device.
- Update
docs/protocol.md and sdk/ whenever an AT response, command, or
binary transfer frame changes.
Current protocol rules
- Success is
{"ok":true,"data":...} where data is command-specific.
Failures use {"ok":false,"msg":"..."}; do not expect error or numeric
error-code fields.
- Use
AT+GSTAT, not AT+STATUS?. Current recording commands are START,
STOP, PAUSE, RESUME, and MARK.
- Runtime commands for bitrate, codec complexity, AGC, noise suppression, and
dereverb do not exist. Audio mode is
normal or enhanced.
AT+PAIR=reset acknowledges first, then erases SD and reboots. Do not make a
client wait for the erase before receiving the response.AT+WIFI=on returns AP credentials; UDP uses port 8089. A host may use BLE
for control then switch file transfer to UDP.
Build and flash
source ~/ncs/v3.3.0/zephyr/zephyr-env.sh
export ZEPHYR_EXTRA_MODULES="$PWD"
west build --build-dir build-clip --board clip/nrf5340/cpuapp applications/clip
west build --build-dir build-clip --pristine --board clip/nrf5340/cpuapp applications/clip
west flash --build-dir build-clip && nrfutil device reset
Use --recover only when needed: it erases both cores. Build production with
the production snippet; it disables console/UART logging and is required for
meaningful idle-current measurements.
Validation checkpoints
- Build a pristine image after Kconfig, devicetree, sysbuild, or partition
changes.
- Flash both app and network-core images when checking BLE behavior.
- For low power, test the production image with SD idle power-off and FS logging
disabled; debug UART materially changes current.
- For storage changes, test new recording,
LIST, DOWNLOAD, cancellation,
deletion, and a power-cycle/remount path.
- For transfer changes, check BLE final CRC32 and UDP per-frame CRC32 plus
FILE_ACK retransmission.
1---2name: clip-dev3description: Develop, build, flash, test, or debug reSpeaker Clip firmware on the nRF5340 with NCS v3.3.0. Use for Zephyr board work, MCUboot/sysbuild, current AT commands, BLE or Wi-Fi UDP transport, SD recording storage, audio/DSP, OLED, PMIC, battery, low-power behavior, production images, and hardware tests.4---56# reSpeaker Clip firmware78Treat the checked-out source as authoritative. Read `CLAUDE.md` before changing9firmware: it contains the active NCS version, board sysbuild defaults, power10constraints, release workflow, and current hardware-test commands.1112## Route the task1314| Area | Source of truth | Read when needed |15|---|---|---|16| AT protocol | `applications/clip/src/at_commands.c` | `references/ble-at.md` |17| BLE/UDP transfer | `transport_ble.c`, `transport_udp.c`, `wifi_udp.c` | `references/wifi-udp.md` |18| Recording and DSP | `audio.c`, `applications/clip/Kconfig` | `references/audio.md` |19| FATFS sessions | `storage.c` | `references/storage.md` |20| Idle and power-off | `clip_event.c`, `storage.c`, `battery.c`, snippets | `references/power.md` |21| Build, flash, artifacts | `CLAUDE.md`, board `Kconfig.sysbuild` | `references/build-flash.md` |22| Python package | `sdk/` | Use the separate `clip-sdk` skill |2324Keep `applications/clip/tests` intact. It is a legacy test/tool collection;25the installable SDK lives at `sdk/` and must not silently inherit legacy26commands or response shapes.2728## Firmware workflow29301. Inspect `git status`; preserve unrelated worktree changes.312. Confirm the command, Kconfig, device-tree, storage, or transport contract in32 source before editing docs or clients.333. Keep host-visible session IDs as exactly 14 decimal digits34 `YYYYMMDDHHMMSS`; never expose physical FAT paths in the protocol.354. Validate user-controlled command arguments before storage, path, or transfer36 access. `DOWNLOAD` only accepts `session` or `session:NNNN.opus`.375. Build and test in proportion to the change. Flash only the image the user38 requested; `--recover` erases the device.396. Update `docs/protocol.md` and `sdk/` whenever an AT response, command, or40 binary transfer frame changes.4142## Current protocol rules4344- Success is `{"ok":true,"data":...}` where `data` is command-specific.45 Failures use `{"ok":false,"msg":"..."}`; do not expect `error` or numeric46 error-code fields.47- Use `AT+GSTAT`, not `AT+STATUS?`. Current recording commands are `START`,48 `STOP`, `PAUSE`, `RESUME`, and `MARK`.49- Runtime commands for bitrate, codec complexity, AGC, noise suppression, and50 dereverb do not exist. Audio mode is `normal` or `enhanced`.51- `AT+PAIR=reset` acknowledges first, then erases SD and reboots. Do not make a52 client wait for the erase before receiving the response.53- `AT+WIFI=on` returns AP credentials; UDP uses port `8089`. A host may use BLE54 for control then switch file transfer to UDP.5556## Build and flash5758```sh59source ~/ncs/v3.3.0/zephyr/zephyr-env.sh60export ZEPHYR_EXTRA_MODULES="$PWD"6162west build --build-dir build-clip --board clip/nrf5340/cpuapp applications/clip63west build --build-dir build-clip --pristine --board clip/nrf5340/cpuapp applications/clip64west flash --build-dir build-clip && nrfutil device reset65```6667Use `--recover` only when needed: it erases both cores. Build production with68the `production` snippet; it disables console/UART logging and is required for69meaningful idle-current measurements.7071## Validation checkpoints7273- Build a pristine image after Kconfig, devicetree, sysbuild, or partition74 changes.75- Flash both app and network-core images when checking BLE behavior.76- For low power, test the production image with SD idle power-off and FS logging77 disabled; debug UART materially changes current.78- For storage changes, test new recording, `LIST`, `DOWNLOAD`, cancellation,79 deletion, and a power-cycle/remount path.80- For transfer changes, check BLE final CRC32 and UDP per-frame CRC32 plus81 `FILE_ACK` retransmission.
Seeed-Studio