[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1664":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":14,"forks30d":14,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":21,"hasPages":21,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":14,"starSnapshotCount":14,"syncStatus":27,"lastSyncTime":28,"discoverSource":29},1664,"claude-desktop-buddy-esp32","vthinkxie\u002Fclaude-desktop-buddy-esp32","vthinkxie","esp32-s3-touch-amoled-1.8",null,"C++",230,24,1,0,6,12,44,18,4.19,"Other",false,"main",[],"2026-06-12 02:00:31","# claude-desktop-buddy — ESP32 AMOLED port\n\n\u003Cimg src=\"image.jpg\" width=\"400\" \u002F>\n\nClaude for macOS and Windows can connect Claude Cowork and Claude Code to\nmaker devices over BLE, so developers and makers can build hardware that\ndisplays permission prompts, recent messages, and other interactions.\n\nThis is a port of [anthropics\u002Fclaude-desktop-buddy](https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-desktop-buddy)\n(originally targeting M5StickC Plus) to four Waveshare ESP32 AMOLED\nboards. The BLE wire protocol is unchanged — same pairing, same desktop\napps, just a larger screen.\n\n> **Building your own device?** You don't need any of the code here. See\n> **[REFERENCE.md](REFERENCE.md)** for the wire protocol: Nordic UART\n> Service UUIDs, JSON schemas, and the folder push transport.\n\n## Supported boards\n\nAll four run the **same main.cpp \u002F UI** — board-specific wiring, drivers and\ncanvas→panel scaling are isolated in `src\u002Fhw\u002F` + one header per board\nunder `src\u002Fboards\u002F`.\n\n| | [ESP32-S3-Touch-AMOLED-1.8](https:\u002F\u002Fdocs.waveshare.com\u002FESP32-S3-Touch-AMOLED-1.8) | [ESP32-S3-Touch-AMOLED-1.75C](https:\u002F\u002Fdocs.waveshare.com\u002FESP32-S3-Touch-AMOLED-1.75C) | [ESP32-C6-Touch-AMOLED-2.16](https:\u002F\u002Fdocs.waveshare.com\u002FESP32-C6-Touch-AMOLED-2.16) | [ESP32-S3-Touch-AMOLED-2.16](https:\u002F\u002Fdocs.waveshare.com\u002FESP32-S3-Touch-AMOLED-2.16) |\n| --- | --- | --- | --- | --- |\n| MCU | ESP32-S3R8 (8 MB OPI PSRAM, 8 MB flash) | same | ESP32-C6FH8 (160 MHz RISC-V single-core, 8 MB flash, **no PSRAM**) | ESP32-S3R8 (8 MB OPI PSRAM, 8 MB flash) |\n| Panel | 1.8\" **rectangular** 368×448 AMOLED | 1.75\" **round** 466×466 AMOLED | 2.16\" **rounded-square** 480×480 AMOLED | 2.16\" **rounded-square** 480×480 AMOLED (**rotated 90°**) |\n| Display driver | SH8601 (QSPI) | CO5300 (QSPI) | SH8601 (QSPI) | CO5300 (QSPI) |\n| Touch | FT3168 @ 0x38 | CST92xx @ 0x5A | CST9217 @ 0x5A | CST9217 @ 0x5A |\n| GPIO expander | TCA9554 (LCD\u002FTP resets routed through it) | none — resets are direct GPIOs | none — resets are direct GPIOs | none — resets are direct GPIOs |\n| RTC | PCF85063 (I²C) | none — software clock synced from desktop | PCF85063 (I²C) | PCF85063 (I²C) |\n| IMU | QMI8658 | same | same | same |\n| PMU | AXP2101 | same | same | same |\n| Audio | ES8311 + amp + speaker | same | ES8311 + ES7210 (output + mic codec) | same |\n| Buttons | Key1 (GPIO0 BOOT) + AXP PEK | same (physical layout swapped; corrected in firmware) | three: PWR\u002FIO10\u002FBOOT; PWR is active-HIGH via MOSFET inverter + AXP PWRON | three: PWR\u002FIO18\u002FBOOT; PWR is active-HIGH via BSS138 inverter |\n| Canvas → panel | 184×224 canvas → **2× nearest-neighbor** → 368×448 | 184×224 canvas → **1.5× bilinear** → 276×336 centred in 466×466 (black border) | 184×224 canvas → **2× nearest-neighbor** → 368×448 centred at (56, 16) in 480×480 (56 px L\u002FR \u002F 16 px T\u002FB black border) | 184×224 canvas → **2× nearest-neighbor** → 368×448 centred at (56, 16) in 480×480 (56 px L\u002FR \u002F 16 px T\u002FB black border) |\n\nInternal canvas is **184×224** on all four. The 1.75C rounds the content\ninside its circular bezel; keeping the logical canvas identical means\nUI code, fonts and all buddy rendering are completely board-agnostic.\n\nThe firmware targets ESP32-S3 and ESP32-C6 with Arduino framework 3.x via the\n[pioarduino](https:\u002F\u002Fgithub.com\u002Fpioarduino\u002Fplatform-espressif32) platform.\n\n## Flashing\n\nInstall\n[PlatformIO Core](https:\u002F\u002Fdocs.platformio.org\u002Fen\u002Flatest\u002Fcore\u002Finstallation\u002F),\nthen pick the env that matches your board:\n\n```bash\n# 1.8\" rectangular AMOLED (ESP32-S3)\npio run -e waveshare-esp32s3-touch-amoled-1-8 -t upload\n\n# 1.75C round AMOLED (ESP32-S3)\npio run -e waveshare-esp32s3-touch-amoled-1-75c -t upload\n\n# 2.16\" rounded-square AMOLED (ESP32-C6)\npio run -e waveshare-esp32c6-touch-amoled-2-16 -t upload\n\n# 2.16\" rounded-square AMOLED (ESP32-S3)\npio run -e waveshare-esp32s3-touch-amoled-2-16 -t upload\n```\n\nIf you're starting from a previously-flashed device (e.g. the factory\nXiaozhi firmware), wipe it first:\n\n```bash\npio run -e \u003Cenv> -t erase && pio run -e \u003Cenv> -t upload\n```\n\nLittleFS auto-formats on first boot if the partition isn't recognised.\n\n### Adding another board\n\n1. Add a new header at `src\u002Fboards\u002Fboard_\u003Cname>.h` declaring all\n   `PIN_*`, `BOARD_HW_W\u002FH`, `BOARD_SAFE_INSET`, and capability flags —\n   the existing headers cover ~16 flags between them\n   (`BOARD_HAS_PSRAM`, `BOARD_HAS_TCA9554`, `BOARD_HAS_PCF85063`,\n   `BOARD_HAS_AXP2101`, `BOARD_HAS_PA_CTRL`, `BOARD_HAS_KEY2`,\n   `BOARD_DISPLAY_CO5300`, `BOARD_DISPLAY_LETTERBOX`,\n   `BOARD_DISPLAY_OFFSET_X\u002FY`, `BOARD_DISPLAY_SCALE`,\n   `BOARD_DISPLAY_PUSH_STREAMED`, `BOARD_DISPLAY_SH8601_VENDOR_INIT`,\n   `BOARD_CO5300_COL_OFFSET`, `BOARD_CO5300_MADCTL`,\n   `BOARD_LCD_RST_VIA_PMU`, `BOARD_AXP_PWRON_4S_OFF`,\n   `BOARD_AXP_ENABLE_AUX_LDOS`, `BOARD_KEY1_ACTIVE_HIGH`,\n   `BOARD_BTN_THIRD`, `BOARD_BTN_SWAP_AB`, `BOARD_TOUCH_CST92XX`).\n   Pick the values that match your board.\n2. Add a `#elif defined(BOARD_\u003CNAME>)` branch in `src\u002Fhw\u002Fpins.h`.\n3. Add a matching `[env:\u003Cname>]` block in `platformio.ini` with the\n   `-DBOARD_\u003CNAME>` build flag.\n\n`main.cpp` and `buddies\u002F` stay untouched.\n\nOnce running you can also wipe everything from the device itself:\n**hold the A button (Key1 on 1.8\u002F1.75C, PWR on the 2.16 boards) →\nsettings → reset → factory reset → tap twice**.\n\n## Pairing\n\nTo pair your device with Claude, first enable developer mode (**Help →\nTroubleshooting → Enable Developer Mode**). Then open the Hardware Buddy\nwindow in **Developer → Open Hardware Buddy…**, click **Connect**, and pick\nyour device from the list (advertised as `Claude-XXXX`). macOS will prompt\nfor Bluetooth permission on first connect; grant it.\n\nThe device shows a 6-digit passkey on screen — type it on the desktop to\ncomplete LE Secure Connections bonding. Once paired, the bridge\nauto-reconnects whenever both sides are awake.\n\n## Controls\n\n### ESP32-S3 boards (1.8 & 1.75C)\n\nThe board has two physical keys. **Key1** is the BOOT button (acts as\n\"A\" in the table). **Key3** is the AXP power key — short-press is \"B\",\nlong-press toggles screen off, very-long-press hardware-shuts-down.\n\n|                          | Normal               | Pet         | Info        | Approval    |\n| ------------------------ | -------------------- | ----------- | ----------- | ----------- |\n| **Key1** (BOOT)          | next screen          | next screen | next screen | **approve** |\n| **Key3** (PWR, short)    | scroll transcript    | next page   | next page   | **deny**    |\n| **Hold Key1**            | menu                 | menu        | menu        | menu        |\n| **Key3** (PWR, ~1s long) | toggle screen off    |             |             |             |\n| **Key3** (PWR, ~6s)      | hard power off       |             |             |             |\n| **Shake**                | dizzy                |             |             | —           |\n| **Face-down**            | nap (energy refills) |             |             |             |\n\n### ESP32-C6-Touch-AMOLED-2.16 controls\n\nThe board has three physical keys:\n- **PWR** (middle) — primary action \u002F confirm (= A button)\n- **IO10** (left) — secondary \u002F back \u002F scroll (= B button)\n- **BOOT** (right) — open menu shortcut\n\n|                          | Normal               | Pet         | Info        | Approval    |\n| ------------------------ | -------------------- | ----------- | ----------- | ----------- |\n| **PWR** (middle)         | next screen          | next screen | next screen | **approve** |\n| **IO10** (left, short)   | scroll transcript    | next page   | next page   | **deny**    |\n| **Hold PWR**             | menu                 | menu        | menu        | menu        |\n| **BOOT** (right)         | open menu (shortcut) | open menu   | open menu   | open menu   |\n| **PWR held 4 s**         | power off (AXP cuts ALDO3; press again to wake) |             |             |             |\n| **Shake**                | dizzy                |             |             | —           |\n| **Face-down**            | nap (energy refills) |             |             |             |\n\n### ESP32-S3-Touch-AMOLED-2.16 controls\n\nThe board has three physical keys:\n- **PWR** (middle) — primary action \u002F confirm (= A button)\n- **IO18** (left) — secondary \u002F back \u002F scroll (= B button)\n- **BOOT** (right) — open menu shortcut\n\n|                          | Normal               | Pet         | Info        | Approval    |\n| ------------------------ | -------------------- | ----------- | ----------- | ----------- |\n| **PWR** (middle)         | next screen          | next screen | next screen | **approve** |\n| **IO18** (left, short)   | scroll transcript    | next page   | next page   | **deny**    |\n| **Hold PWR**             | menu                 | menu        | menu        | menu        |\n| **BOOT** (right)         | open menu (shortcut) | open menu   | open menu   | open menu   |\n| **PWR held 4 s**         | power off (AXP cuts ALDO3; press again to wake) |             |             |             |\n| **Shake**                | dizzy                |             |             | —           |\n| **Face-down**            | nap (energy refills) |             |             |             |\n\n### Touch (all boards)\n\nTouch is supplemental — keys remain primary:\n\n- **Swipe up \u002F down** — cycle through all 9 pages (Normal → Pet ×2 → Info ×6). The A button (Key1 on S3 1.8\u002F1.75C, PWR on the 2.16 boards) short-press remains a coarser 3-mode jumper.\n- **Swipe left \u002F right** (clock home screen) — cycle ASCII species\n- **Approval screen** — tap upper half = approve, lower half = deny\n- **Menu \u002F Settings \u002F Reset** — tap a row to select+confirm in one go\n- **Info \u002F Pet pages** — tap top-right corner to cycle pages\n- **Normal HUD** — tap buddy = heart, bottom 32 px = scroll transcript\n\n### Sleep & wake\n\n- **USB plugged** — never auto-offs; the clock face stays visible\n- **Battery + clock visible** — auto-off after **5 minutes**\n- **Battery + other screens** — auto-off after **30 seconds**\n- **Approval prompt up** — never auto-offs\n\nAny key press or screen tap wakes the panel.\n\n## Notable differences from the M5StickC original\n\n- **Display layer** — Arduino_GFX + PSRAM Canvas (was M5.Lcd \u002F TFT_eSprite)\n- **Attention indicator** — small red pill at top of screen\n  (M5 used a GPIO red LED; the AMOLED board has none)\n- **Landscape clock removed** — 368×448 is near-square; rotation pointless\n- **Battery current not exposed** — XPowersLib \u002F AXP2101 only reports\n  voltage, %, and isCharging. The info-page \"current\" reads 0 mA\n- **Transcript supports CJK** — uses `chill7_h_cjk` font for the HUD lines\n  so Chinese \u002F Japanese log entries render legibly\n- **Other UI strings stay ASCII** — non-ASCII bytes in `msg`, `promptTool`\n  and `promptHint` are replaced with random Matrix-rain symbols rather\n  than rendering as garbage glyphs\n- **ESP32-S3 2.16\" rotation** — the Waveshare ESP32-S3-Touch-AMOLED-2.16 panel is physically mounted 90° rotated from its natural orientation; this is handled in firmware via MADCTL=0xA0 and is transparent to the UI code\n\n## Per-state animations\n\n| State       | Trigger                     | Feel                                      |\n| ----------- | --------------------------- | ----------------------------------------- |\n| `sleep`     | bridge not connected        | eyes closed, slow breathing               |\n| `idle`      | connected, nothing urgent   | blinking, looking around                  |\n| `busy`      | sessions actively running   | sweating, working                         |\n| `attention` | approval pending            | alert, **red top-bar pulses**             |\n| `celebrate` | level up (every 50K tokens) | confetti, bouncing                        |\n| `dizzy`     | you shook the device        | spiral eyes, wobbling                     |\n| `heart`     | approved in under 5s        | floating hearts                           |\n\nEighteen ASCII species, each with all seven animations. **Settings →\nascii pet** cycles them; choice persists in NVS.\n\n## Custom GIF characters\n\nIf you want a custom GIF character instead of an ASCII buddy, drag a\ncharacter pack folder onto the drop target in the Hardware Buddy window.\nThe app streams it over BLE and the device switches to GIF mode live.\n**Settings → reset → delete char** reverts to ASCII mode.\n\nA character pack is a folder with `manifest.json` and 96 px-wide GIFs:\n\n```json\n{\n  \"name\": \"bufo\",\n  \"colors\": {\n    \"body\": \"#6B8E23\",\n    \"bg\": \"#000000\",\n    \"text\": \"#FFFFFF\",\n    \"textDim\": \"#808080\",\n    \"ink\": \"#000000\"\n  },\n  \"states\": {\n    \"sleep\": \"sleep.gif\",\n    \"idle\": [\"idle_0.gif\", \"idle_1.gif\", \"idle_2.gif\"],\n    \"busy\": \"busy.gif\",\n    \"attention\": \"attention.gif\",\n    \"celebrate\": \"celebrate.gif\",\n    \"dizzy\": \"dizzy.gif\",\n    \"heart\": \"heart.gif\"\n  }\n}\n```\n\nState values can be a single filename or an array. Arrays rotate\nloop-by-loop, useful for an idle activity carousel.\n\nGIFs are 96 px wide; up to ~140 px tall keeps the character above the HUD.\nThe whole folder must fit under 1.8 MB; `gifsicle --lossy=80 -O3 --colors 64`\ntypically cuts 40–60 %.\n\nSee `characters\u002Fbufo\u002F` for a working example. If you're iterating on a\ncharacter and would rather skip the BLE round-trip,\n`tools\u002Fflash_character.py characters\u002Fbufo` stages it into `data\u002F` and runs\n`pio run -t uploadfs` directly over USB.\n\n## Project layout\n\n```\nsrc\u002F\n  main.cpp           — loop, state machine, UI screens (board-agnostic)\n  buddy.{cpp,h}      — ASCII species dispatch + render helpers\n  buddies\u002F           — one file per species, seven anim functions each\n  character.{cpp,h}  — GIF decode + render\n  ble_bridge.{cpp,h} — Nordic UART service, line-buffered TX\u002FRX\n  data.h             — wire protocol, JSON parse, CJK matrixifier\n  xfer.h             — folder push receiver\n  stats.h            — NVS-backed stats, settings, owner, species choice\n  boards\u002F            — one .h per supported board (pins + capability flags)\n  hw\u002F                — board HAL (display, input, power, imu, rtc,\n                       audio, expander, border). pins.h dispatches on\n                       the BOARD_* build flag\nlib\u002F\n  ES8311\u002F            — vendored Espressif codec driver\n  Arduino_DriveBus\u002F  — vendored FT3168 touch driver (1.8)\n  Adafruit_XCA9554\u002F  — vendored TCA9554 expander driver (1.8)\ncharacters\u002F          — example GIF character packs\ntools\u002F               — generators and converters\ndocs\u002Fsuperpowers\u002F    — design specs + implementation plans\n```\n\nCST92xx touch (1.75C, both 2.16 boards) and PCF85063 RTC (1.8, both\n2.16 boards) come in through `SensorLib` via `platformio.ini` lib_deps\nrather than being vendored.\n\n## Availability\n\nThe BLE API is only available when the Claude desktop apps are in\ndeveloper mode (**Help → Troubleshooting → Enable Developer Mode**).\nIt's intended for makers and developers and isn't an officially\nsupported product feature.\n","该项目将Anthropic的Claude桌面助手移植到了四款Waveshare ESP32 AMOLED开发板上，通过BLE连接到macOS和Windows平台上的Claude Cowork及Claude Code应用，实现在硬件设备上显示权限请求、最近消息等交互内容。项目采用C++语言编写，支持多种不同规格的AMOLED显示屏（1.8英寸矩形、1.75英寸圆形、2.16英寸圆角方形），并针对每种屏幕尺寸进行了适配优化，包括触摸控制、GPIO扩展等功能的支持。适用于希望利用ESP32构建与Claude服务集成的小型智能设备开发者或爱好者，如可穿戴设备、桌面辅助工具等场景。",2,"2026-06-11 02:45:19","CREATED_QUERY"]