USB Keyboard Mode

Use your ESP32-S3 as a real USB keyboard

USB Keyboard Mode turns your ESP32-S3 into a live USB HID keyboard. Instead of executing pre-written DuckyScript files, keystrokes are forwarded in real time from a paired display controller (C5) to the host PC.

How It Works

  1. The S3 installs as a USB HID keyboard (composite device with keyboard + mouse interfaces)
  2. The C5 on-screen keyboard sends each pressed key as a badusb type_char command over GhostLink
  3. The S3 receives the command and sends it as a USB HID keyboard report to the host PC

This effectively turns the C5 display into a wireless keyboard relay.

Usage

From the Display Menu (Remote)

  1. Navigate to BadUSB
  2. Select USB Keyboard
  3. The C5 sends badusb keyboard_start to the S3
  4. The S3 activates USB HID keyboard mode
  5. Key events from the C5 are forwarded to the host PC in real time
  6. Select Done or Exit to leave the keyboard screen, then select Cancel on the status popup to stop keyboard mode

Via CLI (Standalone S3)

Start:

badusb keyboard_start

Stop:

badusb keyboard_stop

Type text through the active keyboard mode:

badusb type <text>

Type one ASCII character by numeric code:

badusb type_char <ascii>

Send a single keypress (HID modifier + keycode):

badusb keysend <modifier> <keycode>

Example — send Ctrl+C:

badusb keysend 1 6

(Modifier 1 = Left Ctrl, keycode 6 = ‘c’ in HID)

HID Modifier Values

ValueModifier
0x01Left Ctrl
0x02Left Shift
0x04Left Alt
0x08Left GUI (Windows)
0x10Right Ctrl
0x20Right Shift
0x40Right Alt
0x80Right GUI

Modifiers can be combined with bitwise OR. For example, Ctrl+Shift = 0x03.

HID Keycode Reference

Common keycodes (hex):

KeyCode
a-z0x04-0x1D
1-90x1E-0x26
00x27
Enter0x28
Escape0x29
Backspace0x2A
Tab0x2B
Space0x2C
F1-F120x3A-0x45
Arrow Right0x4F
Arrow Left0x50
Arrow Down0x51
Arrow Up0x52

Full reference: USB HID Usage Tables

Notes

  • USB required: The S3 must be plugged into the host PC. If VSENSE is configured, it waits for USB connection automatically.
  • Mutually exclusive: USB Keyboard Mode cannot run at the same time as BadUSB scripts or Mouse Jiggler — they share the same USB HID device.
  • Composite device: When active, the S3 presents as both a keyboard and mouse (composite HID). The mouse interface is idle unless the Mouse Jiggler is used.
  • Immediate display typing: The C5 on-screen keyboard sends each key as it is pressed; Done only exits the keyboard screen.
  • CDC Console unavailable: The USB serial console is not available while HID mode is active.