Usb hid display

usb-hid-display

A firmware for Raspberry Pi Pico (RP2040) that turns cheap off-the-shelf components (rotary encoder, push buttons, SSD1306 OLED) into a standalone USB micro-panel for embedded Linux devices.

What is this?

This firmware creates a USB composite device with two interfaces:

• HID Mouse — The rotary encoder and directional buttons appear as a standard USB mouse to the host. A host-side daemon (such as micropanel) interprets the relative mouse movements as menu navigation: up, down, left, right, and select.
• CDC Serial (/dev/ttyACMx) — The host writes binary commands over this serial port to control the SSD1306 OLED display: draw text, progress bars, set brightness, etc.

Together, these two interfaces form a self-contained hardware menu system — physical buttons for input, OLED for output — driven entirely from the host over a single USB cable. No drivers required; the device uses standard USB HID and CDC ACM classes supported by all major operating systems.

Features

• USB HID Mouse: rotary encoder for horizontal movement, directional buttons for X/Y navigation, push button for left-click/select
• USB CDC Serial: binary command protocol to draw text, progress bars, control brightness/power/inversion on the SSD1306
• Single USB connection: both HID and CDC interfaces available simultaneously
• Robust I2C communication with timeouts (no hangs if display disconnects)
• Proper quadrature decoding with Gray code for reliable rotary input
• Per-button debouncing for all inputs
• Unique USB serial number derived from RP2040 chip ID
• Runtime landscape/portrait orientation via GPIO jumper (single firmware binary)

Hardware Variants

Custom PCB — RP2040-Micropanel

A purpose-built PCB designed in KiCad with a Waveshare RP2040-Zero module, SSD1306 OLED, and 5 tactile buttons on a compact board. KiCad project files are available in the hardware/ directory.

Prototype — Hand-Soldered

The same firmware runs on any RP2040 board with hand-wired connections on a general-purpose PCB. No custom PCB required — see the wiring diagram in the Directional Push Buttons section below.

Hardware Requirements

• Raspberry Pi Pico (RP2040)
• SSD1306 OLED display (128x64, I2C version)
• Rotary encoder with push button
• 4x directional push buttons (active-low, directly connected to GPIO with internal pull-ups)
• Micro USB cable
• Optional: jumper wire for portrait mode (GPIO 27 to GND)

Hardware Connections

SSD1306 OLED Display (I2C)

Rotary Encoder

Orientation Jumper

The firmware detects landscape or portrait mode at boot from GPIO 27:

No separate firmware builds needed — a single .uf2 handles both orientations. The detected orientation is reflected in the USB product string ("USB HID Display (landscape)" or "USB HID Display (portrait)").

Directional Push Buttons (active-low, directly connected to GND)

Pre-compiled .uf2 binary with this GPIO config can be downloaded from here.

The table below shows the landscape orientation (default) mapping. In portrait mode, the physical button roles rotate: LEFT becomes UP, RIGHT becomes DOWN, DOWN becomes LEFT, UP becomes RIGHT.

Portrait/landscape mapping summary:

Note: Each directional button press generates two HID movement events (one immediate, one after ~16ms) to match rotary encoder step responsiveness. Host-side daemons should account for this when interpreting navigation input.

Serial Command Protocol

The device exposes a CDC serial port (/dev/ttyACMx) that accepts binary commands to control the display:

Protocol Limits and Caveats

• MAX_CMD_SIZE is 128 bytes total per command buffer.
• Commands that exceed the buffer are truncated to avoid parser desynchronization.
• CMD_DRAW_TEXT uses length-based framing: the len byte specifies exactly how many text bytes follow (max 124).
• All commands have deterministic framing — fixed-length (0x01, 0x03-0x07) or length-prefixed (0x02).
• Text Y is page-based (8-pixel rows): use 0, 8, 16, ..., 56.

Example (Python)

import serial

ser = serial.Serial('/dev/ttyACM0', timeout=1)

# Clear display
ser.write(bytes([0x01]))

# Draw text "Hello" at position (0, 0) — len=5
ser.write(bytes([0x02, 0, 0, 5]) + b'Hello')

# Draw progress bar at (10, 30), 108px wide, 12px tall, 75%
ser.write(bytes([0x06, 10, 30, 108, 12, 75]))

# Set brightness to max
ser.write(bytes([0x05, 255]))

Test Commands (optional, build-time enabled)

When built with -DENABLE_TEST_COMMANDS=ON, the firmware accepts command 0xF0 for automated hardware testing. This allows the host test framework to inject simulated HID input events through the CDC serial port without physically pressing buttons.

Production firmware ignores 0xF0 entirely.

Navigation test commands produce orientation-independent logical directions — the same HID output regardless of landscape/portrait build.

Timing: Allow at least 60ms between nav commands and 80ms after button press before sending the next test command. The host test framework can detect test firmware by sending ping and waiting 500ms for a reply.

Building the Firmware

Prerequisites

sudo apt update
sudo apt install git cmake gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential libstdc++-arm-none-eabi-newlib

Clone and build

git clone --recursive https://github.com/raspberrypi/pico-sdk.git ~/pico-sdk
export PICO_SDK_PATH=~/pico-sdk

git clone https://github.com/hackboxguy/usb-hid-display.git
cd usb-hid-display/rp2040/
mkdir build && cd build
cmake .. -DFIRMWARE_VERSION=1.0.0
make -j$(nproc)

Build options

FIRMWARE_VERSION is embedded in USB descriptors and exposed to the host via sysfs during USB enumeration. Orientation is detected at runtime from the GPIO 27 jumper (no build flag needed).

Test command build

To build firmware with test commands enabled (for automated hardware testing):

cmake .. -DENABLE_TEST_COMMANDS=ON -DFIRMWARE_VERSION=1.0.1
make -j$(nproc)

Production builds (without -DENABLE_TEST_COMMANDS=ON) ignore the test command byte entirely.

Flashing

1. Hold the BOOTSEL button on the Pico and connect it via USB
2. The Pico mounts as a USB mass storage device
3. Copy the firmware:

# Check dmesg for the device node (e.g. /dev/sda1)
sudo mount /dev/sdXN /mnt
sudo cp usb_hid_display.uf2 /mnt/
sudo umount /mnt

After flashing, the device enumerates as:

• /dev/input/eventX -- HID mouse (rotary encoder + buttons)
• /dev/ttyACMX -- CDC serial port (display commands)

Verify

# Test HID input events
sudo evtest /dev/input/eventX

# Test display commands
echo -ne '\x01' > /dev/ttyACM0          # clear display
echo -ne '\x02\x00\x00\x05Hello' > /dev/ttyACM0  # draw "Hello" at (0,0), len=5

USB Device Info

Version Encoding

FIRMWARE_VERSION=X.Y.Z is encoded as USB bcdDevice = 0xXYZ0:

Reading firmware info from host

The daemon (or any tool) can read firmware version and orientation from sysfs without opening the serial port:

# Find the device (filter by VID:PID)
DEVPATH=$(grep -rl "1209" /sys/bus/usb/devices/*/idVendor 2>/dev/null | head -1 | xargs dirname)

# Read product string (includes orientation)
cat "$DEVPATH/product"    # e.g. "USB HID Display (portrait)"

# Read firmware version (BCD format)
cat "$DEVPATH/bcdDevice"  # e.g. "1100" for v1.1.0

Host Integration

Use stable paths instead of raw eventX / ttyACM0 indices:

# serial path
ls -l /dev/serial/by-id/

# input path
ls -l /dev/input/by-id/

Optional udev rule for a stable symlink:

# /etc/udev/rules.d/99-usb-hid-display.rules
SUBSYSTEM=="tty", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="0001", SYMLINK+="usb-hid-display-%s{serial}"

sudo udevadm control --reload-rules
sudo udevadm trigger

Troubleshooting

License

See LICENSE for details.