### Upload Firmware to ESP32 Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/README.md Use this command to upload the firmware to your ESP32 device using PlatformIO. Ensure PlatformIO Core is installed. ```bash pio run -t upload ``` -------------------------------- ### Erase and Upload Firmware to ESP32 Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/README.md Use this command to first erase the existing firmware and then upload the new firmware to your ESP32 device. This is useful when starting from a previously flashed device. ```bash pio run -t erase && pio run -t upload ``` -------------------------------- ### Device Name and Owner Commands Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/REFERENCE.md Commands to set the device's display name and owner's name. The device should acknowledge these commands with `{"ack":"","ok":true}`. ```json {"cmd":"name","name":"Clawd"} ``` ```json {"cmd":"owner","name":"Felix"} ``` -------------------------------- ### Owner Name Command Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/REFERENCE.md Sent on connect to identify the owner of the desktop application. ```json { "cmd": "owner", "name": "Felix" } ``` -------------------------------- ### Project Directory Structure Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/README.md Overview of the Claude Desktop Buddy project's file and directory layout. This helps in understanding the organization of source code, assets, and tools. ```plaintext src/ main.cpp — loop, state machine, UI screens buddy.cpp — ASCII species dispatch + render helpers buddies/ — one file per species, seven anim functions each ble_bridge.cpp — Nordic UART service, line-buffered TX/RX character.cpp — GIF decode + render data.h — wire protocol, JSON parse xfer.h — folder push receiver stats.h — NVS-backed stats, settings, owner, species choice characters/ — example GIF character packs tools/ — generators and converters ``` -------------------------------- ### Folder Push Protocol - Begin Character Transfer Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/REFERENCE.md Initiates the transfer of a folder's contents. The desktop sends `char_begin` with the total size, and the device acknowledges. If the device does not want the files, it should not ack `char_begin`. ```json desktop: {"cmd":"char_begin","name":"bufo","total":184320} ``` ```json device: {"ack":"char_begin","ok":true} ``` -------------------------------- ### Flash Character to Data Directory Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/README.md Stages a character pack into the data directory and uploads it directly via USB using PlatformIO. This is useful for iterating on characters without the BLE round-trip. ```bash tools/flash_character.py characters/bufo ``` -------------------------------- ### Permission Decision Commands Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/REFERENCE.md When a 'prompt' is present in the heartbeat snapshot, your device can respond with a permission decision. The 'id' must match the 'prompt.id' exactly. Use 'once' to approve the tool call or 'deny' to reject it. ```json {"cmd":"permission","id":"req_abc123","decision":"once"} ``` ```json {"cmd":"permission","id":"req_abc123","decision":"deny"} ``` -------------------------------- ### Time Synchronization Command Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/REFERENCE.md Sent on connect for time synchronization. The array contains epoch seconds and the timezone offset in seconds. ```json { "time": [1775731234, -25200] } ``` -------------------------------- ### Device Status Response Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/REFERENCE.md JSON response for the 'status' command, polled by the desktop to update the Hardware Buddy window's stats panel. Fields can be omitted if data is unavailable. ```json { "ack": "status", "ok": true, "data": { "name": "Clawd", "sec": true, "bat": { "pct": 87, "mV": 4012, "mA": -120, "usb": true }, "sys": { "up": 8412, "heap": 84200 }, "stats": { "appr": 42, "deny": 3, "vel": 8, "nap": 12, "lvl": 5 } } } ``` -------------------------------- ### Command Acknowledgment Structure Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/REFERENCE.md Standard JSON structure for acknowledging commands sent from the desktop to the device. Use `ok:false` and an optional `error` field for failures. `n` is a generic counter. ```json { "ack": "", "ok": true, "n": 0 } ``` -------------------------------- ### Turn Event JSON Structure Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/REFERENCE.md This JSON structure is sent when a completed turn fires an event containing raw SDK content. Events larger than 4KB are dropped. ```json { "evt": "turn", "role": "assistant", "content": [{ "type": "text", "text": "..." }] } ``` -------------------------------- ### Character Pack Manifest JSON Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/README.md Defines the metadata for a custom GIF character pack, including name, colors, and animation states. Use this structure for the manifest.json file within a character pack folder. ```json { "name": "bufo", "colors": { "body": "#6B8E23", "bg": "#000000", "text": "#FFFFFF", "textDim": "#808080", "ink": "#000000" }, "states": { "sleep": "sleep.gif", "idle": ["idle_0.gif", "idle_1.gif", "idle_2.gif"], "busy": "busy.gif", "attention": "attention.gif", "celebrate": "celebrate.gif", "dizzy": "dizzy.gif", "heart": "heart.gif" } } ``` -------------------------------- ### Status Command Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/REFERENCE.md The 'status' command is polled by the desktop application periodically to gather device statistics. The response structure is detailed in the 'Status response' section. ```json {"cmd":"status"} ``` -------------------------------- ### Folder Push Protocol - File Transfer Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/REFERENCE.md Transfers individual files within a folder. The desktop sends file metadata, then chunks of data, and waits for acknowledgments after each step. The device decodes and appends chunks sequentially. ```json desktop: {"cmd":"file","path":"manifest.json","size":412} ``` ```json device: {"ack":"file","ok":true} ``` ```json desktop: {"cmd":"chunk","d":""} ``` ```json device: {"ack":"chunk","ok":true,"n":} ``` -------------------------------- ### Heartbeat Snapshot JSON Structure Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/REFERENCE.md The desktop app sends a heartbeat snapshot when something changes or as a keepalive every 10 seconds. This JSON structure includes session counts, a message summary, recent transcript entries, and token usage. ```json { "total": 3, "running": 1, "waiting": 1, "msg": "approve: Bash", "entries": ["10:42 git push", "10:41 yarn test", "10:39 reading file..."], "tokens": 184502, "tokens_today": 31200, "prompt": { "id": "req_abc123", "tool": "Bash", "hint": "rm -rf /tmp/foo" } } ``` -------------------------------- ### Folder Push Protocol - End File Transfer Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/REFERENCE.md Signals the end of a file transfer. The desktop sends `file_end`, and the device acknowledges with the final size written. This is repeated for each file in the folder. ```json desktop: {"cmd":"file_end"} ``` ```json device: {"ack":"file_end","ok":true,"n":} ``` -------------------------------- ### Folder Push Protocol - End Character Transfer Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/REFERENCE.md Signals the completion of all file transfers for a folder. The desktop sends `char_end`, and the device sends a final acknowledgment. Validate `file.path` to prevent overwriting unintended files. ```json desktop: {"cmd":"char_end"} ``` ```json device: {"ack":"char_end","ok":true} ``` -------------------------------- ### Unpair Command Source: https://github.com/anthropics/claude-desktop-buddy/blob/main/REFERENCE.md Command to erase stored BLE bonds. The device should acknowledge this command with `{"ack":"unpair","ok":true}`. This is sent when the user clicks 'Forget' in the desktop app. ```json {"cmd":"unpair"} ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.