Skip to content

About

USB + Bluetooth volume/scroll/macro knob firmware for the Elecrow CrowPanel 1.28" ESP32-S3 rotary display (Arduino + LVGL)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Input Knob: volume, scroll, shortcuts and a trackpad on one round ESP32-S3 dial

Input Knob

Build Release License

Turn an Elecrow CrowPanel 1.28" or 1.46" ESP32-S3 rotary display into a volume, scroll, shortcut and mini-trackpad knob for your computer, phone or tablet, over USB or Bluetooth.

Arduino + LVGL firmware for the Elecrow CrowPanel 1.28" (240x240 GC9A01, 5-LED ring) and 1.46" (360x360 JD9855, 8-LED ring) HMI ESP32 Rotary Displays (round IPS capacitive touch screen, rotary encoder with push button, RGB LED ring). The firmware auto-detects the connected board size at boot (or can be pinned via CROWPANEL_SIZE in config.h). The knob shows up as an ordinary keyboard + mouse + media-key device, so the host needs no driver or companion app. It is not a general macro-pad framework: there are four fixed modes, and shortcuts are edited in code.


Quick Start

Just want to use it? Download the prebuilt firmware from the latest release and flash it from your browser; the release notes have the steps. No Arduino setup needed.

Building from source: you need the knob, a USB-C data cable, a Mac (Windows/Linux work too; see HOWTO) and the Arduino IDE 2 with the esp32 by Espressif 3.x board package.

# 1. Get the code
git clone https://github.com/bsommers/input-knob.git && cd input-knob

# 2. Install the exact LVGL / LovyanGFX / NeoPixel versions Elecrow ships, plus lv_conf.h
git clone --depth 1 https://github.com/Elecrow-RD/CrowPanel-1.28inch-HMI-ESP32-Rotary-Display-240-240-IPS-Round-Touch-Knob-Screen.git /tmp/elecrow
mkdir -p ~/Documents/Arduino/libraries
cp -R /tmp/elecrow/example/Arduino/libraries/{lvgl,LovyanGFX,Adafruit_NeoPixel,lv_conf.h} ~/Documents/Arduino/libraries/

# 3. Plug the knob in and upload (board settings come from sketch.yaml)
./upload.sh

The screen lights up with Volume in blue and USB in green at the top. Turn the knob and the computer's volume follows.

First flash over Elecrow's factory firmware? If upload.sh can't connect, hold BOOT, plug the knob in, release, and run it again.


What It Does

  • Controls volume: turn for volume up/down, click to mute, double-click to play/pause.
  • Scrolls: turn for the scroll wheel, click for middle-click, double-click to switch vertical/horizontal.
  • Fires shortcuts: turn to pick Copy, Paste, Undo, Redo, Screenshot, Mission Control / Task View or Lock; click to send it. Double-click switches between Mac (Cmd) and PC (Ctrl/Win) shortcuts, and the choice survives power-off.
  • Acts as a mini trackpad: in Trackpad mode, drag on the screen to move the cursor, tap to left-click, touch and hold to right-click, turn the knob to scroll.
  • Responds to touch everywhere: tap = knob click, swipe left/right = change mode, swipe up/down = page scroll (Scroll mode) or next/previous shortcut (Macro mode).
  • Lights the LED ring: a soft glow in the mode's colour, a needle that follows the knob, flashes for mute and macros, orange breathing while Bluetooth is pairing, and a red pulse if the connection drops.
  • Switches modes with a long press of the knob or a swipe.
  • Picks USB or Bluetooth automatically: USB when a computer is on the cable, otherwise Bluetooth LE as Input Knob (on a charger or power bank).
  • Recovers after host sleep: re-attaches to USB if the computer's sleep/wake drops the connection (implemented, not yet verified on a real sleep cycle; replug if it gets stuck).

Architecture Overview

               ┌───────────────────────────────────────────────────────┐
  encoder ────►│ knob.cpp ──► input-knob.ino ──► hid.cpp (router)      │
  + button     │              (modes)  │           │             │     │
               │                       ▼           ▼             ▼     │
               │                 ui.cpp (LVGL)  usb_hid.cpp  ble_hid.cpp
               │                       │           │             │     │
               │                 display.cpp       │             │     │
               └───────────────────────┼───────────┼─────────────┼─────┘
                                       ▼           ▼             ▼
                               ╔════════════╗ ╔══════════╗ ╔══════════╗
                               ║ GC9A01 LCD ║ ║ USB host ║ ║ BLE host ║
                               ╚════════════╝ ╚══════════╝ ╚══════════╝
flowchart LR
    Knob[Encoder + button] --> App[input-knob.ino modes]
    App --> UI[ui.cpp / LVGL] --> LCD[(Round display)]
    App --> Router[hid.cpp router]
    Router -->|USB mounted| USB[usb_hid.cpp] --> Host1([Computer over USB])
    Router -->|otherwise| BLE[ble_hid.cpp] --> Host2([Computer / phone over Bluetooth])
Loading

Details: docs/ARCHITECTURE.md.


Project Structure

input-knob/
├── input-knob.ino   — modes and what each turn / click does
├── board.h          — GPIO map and board model helpers (1.28" and 1.46")
├── config.h         — tunables: board size override, encoder direction, button timing, scroll speed, brightness
├── knob.h/.cpp      — interrupt-driven encoder; click / double-click / long-press detection
├── touch.h/.cpp     — CST816D touch panel: taps, long press, swipes, drag deltas
├── leds.h/.cpp      — WS2812 LED ring: mode glow, turn needle, flashes, pairing breathing
├── hid.h/.cpp       — input actions, routed to USB or Bluetooth
├── usb_hid.h/.cpp   — USB HID (TinyUSB) + reconnect-after-host-sleep watchdog
├── ble_hid.h/.cpp   — Bluetooth LE HID (HID over GATT)
├── keys.h           — raw HID key, modifier and media codes
├── macros.h         — Mac and PC shortcut tables
├── display.h/.cpp   — LovyanGFX panel + LVGL display driver
├── ui.h/.cpp        — the round screen: link status, mode, value, hint, dial ring
├── sketch.yaml      — board + Tools-menu settings for arduino-cli
├── upload.sh        — build, upload, and start the firmware
└── docs/            — architecture, purpose, how-to, brochure

Configuration

Compile-time settings in config.h:

Setting Default Description
CROWPANEL_SIZE 0 0 auto-detects 1.28" vs 1.46" at boot; set 128 or 146 to force
ENCODER_REVERSED false Flip if clockwise turns the volume down
BUTTON_DEBOUNCE_MS 25 Button debounce time
BUTTON_DOUBLE_CLICK_MS 300 Max gap between clicks of a double-click
BUTTON_LONG_PRESS_MS 600 Hold time that switches mode
SCROLL_LINES_PER_DETENT 1 Wheel units per encoder click
BACKLIGHT_PERCENT 60 Screen brightness
TOUCH_TAP_SLOP_PX 12 Finger movement still counted as a tap or hold
TOUCH_SWIPE_MIN_PX 50 Distance a swipe must travel
TOUCH_IGNORE_AFTER_TURN_MS 400 Touches ignored after a knob turn, so a resting finger doesn't tap
TRACKPAD_GAIN / TRACKPAD_ACCELERATION 2.0 / 0.15 Cursor speed and acceleration
SWIPE_SCROLL_LINES 10 Wheel units per swipe in Scroll mode
LED_BRIGHTNESS 60 LED ring brightness cap (0–255)
LED_RING_REVERSED false Flip if the LED needle runs against the knob

Shortcuts live in macros.h. Runtime setting: Mac/PC shortcuts (double-click in Macro mode), stored in flash.

Board settings (also in sketch.yaml) for the Arduino IDE Tools menu:

Setting Value
Board ESP32S3 Dev Module
USB Mode USB-OTG (TinyUSB) (the build stops with an error otherwise)
USB CDC On Boot Disabled (the firmware starts the USB serial port itself, so it can name the device "Input Knob")
Upload Mode USB-OTG CDC (TinyUSB)
PSRAM OPI PSRAM
Flash Size 16MB (128Mb)
Partition Scheme Huge APP (3MB No OTA/1MB SPIFFS)

Development

There are no automated tests; changes are verified by compiling and trying them on the knob.

# Compile only (uses sketch.yaml)
arduino-cli compile .

# Compile, upload and start
./upload.sh

# Watch the knob's serial log (failed HID sends are reported here)
arduino-cli monitor -p /dev/cu.usbmodem<id> -c baudrate=115200

No arduino-cli on your PATH? The Arduino IDE bundles one at /Applications/Arduino IDE.app/Contents/Resources/app/lib/backend/resources/arduino-cli; upload.sh finds it automatically.


Documentation

Document Description
Architecture Modules, input-to-host data flow, USB/Bluetooth switching, design decisions
Purpose Why this exists, goals, non-goals, trade-offs
How-To Guide Install, pair, add a shortcut, add a mode, fix common problems
Brochure One-page overview for sharing

Hardware reference: Elecrow's 1.28" wiki / example repo and 1.46" example repo (pin maps, schematics, factory firmware).


Contributing

Issues and pull requests are welcome. Keep transport-specific code inside usb_hid.cpp / ble_hid.cpp, compile before opening a PR, and say in the PR what you tested on hardware.


License

Apache License 2.0.

About

USB + Bluetooth volume/scroll/macro knob firmware for the Elecrow CrowPanel 1.28" ESP32-S3 rotary display (Arduino + LVGL)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages