claude-knob

KO | EN

gitlite — search

#python #typescript #llm #go #golang #machine-learning #rust #deep-learning #java #windows #awesome #kubernetes #pytorch #open-source

(★ 22)

A Knob For Claude

claude-knob Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Claude Knob: A knob for your Claude

> Hardware on this one is the
> [CrowPanel 1.28" HMI ESP32 Rotary Display](https://www.elecrow.com/crowpanel-1-28inch-hmi-esp32-rotary-display-240-240-ips-round-touch-knob-screen.html?r=cmVsYXRl).
> [Elecrow](https://www.elecrow.com/) shipped me a sample to mess
> with, cheers!

A USB rotary-knob companion for the same board: plug it into your Mac,
get a knob that drives Claude Code.

| Gesture       | What it sends   | What you'd use it for           |
| ------------- | --------------- | ------------------------------- |
| Rotate CW     | ↓ Down arrow    | Scroll the chat / pick next     |
| Rotate CCW    | ↑ Up arrow      | Scroll back                     |
| Single tap    | ⏎ Enter         | Submit / confirm                |
| Double tap    | Ctrl+C          | Interrupt the current response  |
| Hold (>300ms) | Space (held)    | Push-to-talk voice mode         |

While you use it, the round screen shows a small orange Claude pet
([from openpets.dev](https://openpets.dev/pets/claude-f187e74a)) reacting
to what you're doing: bobbing while idle, walking left/right when you
turn the knob, jumping when you tap, gently bouncing while you hold for
voice. The 5 RGB LEDs around the rim chase like a comet in the direction
you're turning, flash on tap, and pulse softly while holding.

---

## Glossary (skip if you know this)

- **ESP32-S3**: the microcontroller chip on the board. It runs your
  firmware, drives the screen, and talks USB. You program it once and
  it runs that program every time it's powered on.
- **Arduino framework**: the easiest programming environment for ESP32.
  Code structure is `setup()` runs once, `loop()` runs forever.
- **PlatformIO**: a build system + library manager. It downloads the
  ESP32 toolchain, your dependencies, compiles your code, and flashes
  it to the board. Think of it as "Cargo for embedded".
- **Flashing**: writing your compiled firmware to the chip over USB.
- **HID**: Human Interface Device. When the firmware enables HID
  keyboard, the OS sees your board as a regular keyboard and accepts
  keystrokes from it just like a real one.

---

## What you need

### Hardware

- 1 × CrowPanel 1.28" HMI ESP32 Rotary Display
  ([buy from Elecrow](https://www.elecrow.com/crowpanel-1-28-inch-hmi-esp32-rotary-display-240-240-ips-round-touch-knob-screen.html))
- 1 × USB-C cable (data, not just power)
- *(optional)* a 3D printer, for the enclosure in `3d/` (see below)

The board is fully assembled. No soldering, no wiring.

### Enclosure

`3d/claude knob.3mf` is a printable stand for the board. It is the
orange base you can see in the photo at the top of this README. To
assemble: slice and print the model, thread your cable through the
hole in the enclosure first, plug it into the port on the back of the
board, then seat the knob into the cradle so the rotating top sits
flush with the opening. The enclosure is optional, but without it the
bare board slides around on your desk and is awkward to grip while you
turn it.

### Software

- A computer with **macOS, Linux, or Windows**
- **Python 3.10+** (already on most systems; verify with `python3 --version`)
- **PlatformIO Core** (installation below)
- **Git** (to clone this repository)

That's it. No Arduino IDE, no ESP-IDF setup.

---

## Installing PlatformIO

PlatformIO has a CLI and a VSCode extension. Pick one.

### Option A: CLI only (recommended, easy)

```bash
python3 -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py)"
```

That installer drops a `platformio` binary into `~/.platformio/penv/bin/`.
Add it to your shell so `pio` works from anywhere:

```bash
# zsh (macOS default):
echo 'export PATH="$HOME/.platformio/penv/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# bash:
echo 'export PATH="$HOME/.platformio/penv/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

Verify:

```bash
pio --version
# PlatformIO Core, version 6.x.x
```

### Option B: VSCode extension

Install [Visual Studio Code](https://code.visualstudio.com/) and then the
[PlatformIO IDE extension](https://platformio.org/install/ide?install=vscode).
Open this project's folder, and PlatformIO will offer to install
dependencies automatically. Build/flash buttons live in the status bar.

The rest of this README uses the CLI.

---

## Building and flashing

### First time

```bash
git clone <this-repo-url> claude-knob
cd claude-knob

# Plug the board in via USB-C, then put it into download mode:
# 1. Hold the BOOT button on the back of the board
# 2. While still holding BOOT, plug in (or press RESET)
# 3. Release BOOT after ~1 second
#
# This is only required for the very first flash. After that, normal
# auto-reset usually works.

# Find which port the board is on:
ls /dev/cu.usbmodem*       # macOS
# /dev/cu.usbmodem1101      ← something like this
# Linux:    ls /dev/ttyACM* /dev/ttyUSB*
# Windows:  Device Manager → Ports (COM & LPT)

# Build + upload:
pio run -t upload --upload-port /dev/cu.usbmodem1101
```

First build takes ~2 minutes. PlatformIO downloads the ESP32 toolchain
(~200 MB) and the libraries (LovyanGFX, ESP32Encoder, Adafruit NeoPixel).
Subsequent builds take seconds.

Once flashed, the screen lights up and the device shows up as a USB
keyboard called **"ESP32-S3"** (the default name; you can rename it).
You might see a **"Keyboard Setup Assistant"** popup on macOS. Just
close it.

### Subsequent flashes

After the first flash, you usually just need:

```bash
pio run -t upload
```

PlatformIO auto-detects the port. **If it fails with "Failed to connect"**,
it's the auto-reset edge case. Repeat the BOOT-button procedure above
once and re-run the command.

### Watching the serial log

```bash
pio device monitor -b 115200
```

Exit with **Ctrl+C** (or **Ctrl+] then q** in some setups).

### Erasing the chip

If you want to wipe everything (e.g., before flashing someone else's
firmware):

```bash
pio run -t erase
```

---

## How it works

When the firmware runs, your computer sees the board as **two USB
devices over the same cable**:

1. A **HID keyboard**, used to send keystrokes (arrows, Enter, Space,
   Ctrl+C).
2. A **USB-CDC serial port**, used by `pio device monitor` and by the
   flasher.

The Arduino `loop()` runs at ~60 fps and does four things each frame:

1. **Read the encoder.** A hardware counter (PCNT) keeps track of how
   many detents you've turned the knob since last check. Each detent
   becomes one HID keystroke (↑ or ↓), one LED kick, and a brief switch
   to the "walking" pet animation.
2. **Read the button.** Press, release, and timing are tracked. A short
   press is a tap; held >300ms is a hold; two taps within 200ms is a
   double-tap.
3. **Render the pet.** A 240×240 off-screen sprite (in PSRAM) is cleared,
   the current animation frame is blitted into the middle, and the
   sprite is pushed to the GC9A01 display over SPI via DMA.
4. **Update the LEDs.** A small array tracks each LED's alpha; it
   decays every frame, and rotation events kick the "head" of the chase
   to the next position. Tap, double-tap, and hold each have their own
   ramping pattern.

The Claude pet has five baked-in animations (idle blink, walk left, walk
right, jump, gentle bounce). 32 frames at 128×128 RGB565 pixels, about
1 MB total, generated offline from a single
[openpets.dev](https://openpets.dev) sprite sheet.

---

## Project layout

```
claude-knob/
├── platformio.ini            ← project + board config (read this if anything's off)
├── partitions_arduino.csv    ← flash layout: 16MB flash, 8MB app slot
├── src/
│   ├── main.cpp              ← Arduino setup() + loop() + state machine
│   ├── lgfx_board.h          ← LovyanGFX panel/bus/light config for this board
│   └── anim/                 ← generated sprite C arrays (don't edit by hand)
│       ├── anim.h            ← animation table + frame counts
│       ├── idle_00.h         ← one .h per frame
│       ├── walk_left_00.h
│       └── …
├── assets/
│   └── raw/                  ← chroma-keyed PNGs (one per character pose)
├── tools/                    ← offline asset pipeline
│   ├── slice_sprites.py      ← splits the source sheet into per-pose PNGs
│   ├── contact_sheet.py      ← labelled grid preview (helpful for picking poses)
│   ├── preview_anim.py       ← what the screen will look like, rendered to PNG
│   └── build_anim_arduino.py ← encodes selected PNGs into the C arrays
├── 3d/
│   └── claude knob.3mf       ← printable enclosure; drop the board in after flashing
└── README.md
```

---

## Customising

Everything below lives in `src/main.cpp` unless noted otherwise.

### Change the keys

Look for `poll_encoder()` and `poll_button()`. Each gesture calls
`hid_write()`, `hid_press()`, or `hid_ctrl_c()` with a USB HID usage
ID:

```cpp
hid_write(0xD9);   // KEY_DOWN_ARROW
hid_write(0xDA);   // KEY_UP_ARROW
hid_write(0xB0);   // KEY_RETURN
hid_press(' ');    // SPACE
```

The full list of `KEY_*` codes lives in
`.pio/libdeps/crowpanel/USB/src/USBHIDKeyboard.h`.

### Change the timing

At the top of `main.cpp`:

```cpp
static constexpr int HOLD_MS        = 300;   // press > this → hold (Space)
static constexpr int DOUBLE_TAP_MS  = 200;   // two taps within this → Ctrl+C
static constexpr int WALK_LINGER_MS = 350;   // pet keeps walking after last detent
```

### Reverse the rotation direction

The two branches in `poll_encoder()` (one for `delta >= 4`, one for
`delta <= -4`) decide which physical direction sends Up vs Down and
which way the pet walks / the chase trail runs. Swap the contents of
the two branches to invert.

### Change the LED color or palette

`update_leds()` builds RGB values per state. Change the constants
inside each case to taste; the pet's warm-orange (`R=255, G=115, B=40`)
is the current baseline.

### Disable HID temporarily

If you want to iterate on visuals without macOS reading every encoder
turn as a keystroke (it gets annoying), set:

```cpp
#define ENABLE_HID 0
```

at the top of `main.cpp`. The board still does everything except
emit keys.

### Regenerate the sprite art

If you want to use different poses or a different character:

1. Drop a new spritesheet PNG/WebP into `tools/slice_sprites.py` (edit
   the `SHEET` path).
2. Run `python3 tools/slice_sprites.py` to slice the sheet into
   individual pose PNGs in `assets/raw/`.
3. Run `python3 tools/contact_sheet.py` to produce
   `/tmp/claude_contact.png`, a labelled grid so you can pick which
   pose goes into which animation.
4. Edit the `ANIMS` map at the top of `tools/build_anim_arduino.py`
   to point at the pose filenames you want for each animation.
5. Run `python3 tools/build_anim_arduino.py` to re-generate the C
   arrays in `src/anim/`.
6. `pio run -t upload` to reflash with the new art.

---

## Troubleshooting

**"Failed to connect to ESP32-S3: No serial data received"**
Auto-reset didn't work this time. Do the BOOT-button procedure
(hold BOOT → plug in → release) and retry `pio run -t upload`.

**Screen is black after flash**
Try power-cycling (unplug and replug). If still black, monitor the
serial output with `pio device monitor`; look for the
`==== claude-knob (arduino) boot ====` line and any `display ready`
log. If those appear but the screen is dark, the backlight may not be
on; verify `PIN_BL` (= 46) hasn't been changed.

**LEDs do nothing**
Verify the WS2812 pin (`BSP_LED_GPIO` = 48) in `main.cpp` matches your
board. If it does and they still don't light, swap data + ground at the
solder pads (rare on commercial boards but possible).

**Pet shows wrong colors / artifacts**
Make sure `canvas.setSwapBytes(true)` is set in `setup()`. RGB565 byte
order matters and the GC9A01 expects big-endian on the wire while the
host is little-endian.

**HID typing into the wrong window**
HID just sends keystrokes. The OS routes them to whichever window has
focus. Focus the chat or terminal you actually want to drive before
turning the knob.

---

## Credits

- Pet artwork from [openpets.dev](https://openpets.dev/pets/claude-f187e74a).
- Hardware reference + pinout from the
  [Elecrow CrowPanel wiki](https://www.elecrow.com/wiki/CrowPanel_1.28inch-HMI_ESP32_Rotary_Display.html).
- Display driver: [LovyanGFX](https://github.com/lovyan03/LovyanGFX).
- Encoder driver: [ESP32Encoder](https://github.com/madhephaestus/ESP32Encoder).
- LED driver: [Adafruit NeoPixel](https://github.com/adafruit/Adafruit_NeoPixel).
- BLE protocol reference (not used here, but worth a look if you want
  hardware that talks directly to Claude Desktop):
  [anthropics/claude-desktop-buddy](https://github.com/anthropics/claude-desktop-buddy).

claude-knob

claude-knob Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

claude-knob

claude-knob Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README