Keybird v1.0.12

Transform your Raspberry Pi into a professional USB keyboard, mouse, and media controller with web-based management.

Control a computer from another computer, customize per-keyboard mappings, suppress keys or functions that auto-enter, and manage everything through a modern Bootstrap 5 dark theme web interface. But why does this exist BHB.buzz

🔗 GitHub: github.com/mcyork/keybird

🎯 What Is This?

The Pi HID Bridge turns a Raspberry Pi into a composite USB HID device that emulates:

⌨️ Keyboard with 100+ mapped keys
🖱️ Mouse with 3 buttons + scroll wheel
🎵 Media keys (volume, play/pause, etc.)

Plus unique features:

🎹 Multi-keyboard pass-through - Monitor YubiKey, Dell, Apple, Microsoft keyboards simultaneously
🔧 Per-keyboard custom mappings - YubiKey Enter suppression, key remapping, text macros
📋 Emulation profile switching - Pretend to be different keyboard models
🖱️ Web trackpad with automatic calibration for different displays
🌐 Web UI - Control from laptop, phone, or tablet

⚡ Quick Start (2 Minutes)

Prerequisites

Raspberry Pi 4 Model B (tested and validated)
- Full functionality including keyboard pass-through
Raspberry Pi Zero 2 W (tested and validated)
- ⚠️ Keyboard functionality only - no pass-through capability due to single USB port hardware limitation
⚠️ NOT compatible with Pi 5 (USB gadget mode unresolved issues)
USB-C data cable - Must support data, not just charging (Pi 4B)
Micro-USB data cable - Must support data, not just charging (Pi Zero 2 W)
- Pi connected to network (WiFi or Ethernet)
- Pi has SSH enabled (default on Raspberry Pi OS)

Deploy from Your Computer (No SSH login needed!)

# 1. Install pi-shell and keybird on YOUR COMPUTER
pip install pi-shell keybird

# 2. Add your Pi (one-time setup with password-less SSH)
pi-shell add mypi --host 192.168.1.50 --user pi --password raspberry --push-key

# 3. Deploy to Pi (single command!)
keybird-deploy mypi

Done! 🎉 Access web UI at http://192.168.1.50:8080

📦 Note: Keybird not yet on PyPI. For now, install from source:

pip install pi-shell
git clone https://github.com/mcyork/keybird.git
cd keybird
pip install .
pi-shell add mypi --host 192.168.1.50 --user pi --password raspberry --push-key
keybird-deploy mypi

What Gets Installed

✅ Flask web app with Bootstrap 5 dark theme UI
✅ USB HID gadget (keyboard + mouse + media keys)
✅ Systemd services (auto-start on boot)
✅ Boot configuration (enables USB gadget mode)
✅ Dependencies (flask, evdev)

Manual Deployment (See Under the Hood)

Want transparency? See manual-deploy/README.md for step-by-step SSH deployment.

Post-Installation

Connect Hardware

Connect your Pi's USB-C port to your target computer's USB port.

Access Web UI

open http://<pi-ip>:8080

Done! 🎉

🎹 Core Features

Multi-Keyboard Pass-Through

Note: This feature requires Raspberry Pi 4 Model B (Pi Zero 2 W lacks physical USB host ports for keyboards)

Monitor all keyboards at once:

YubiKey NEO
Dell WK636 Wireless Keyboard
Apple Magic Keyboard
Microsoft keyboards
Any USB keyboard

Each keyboard can have its own custom key mappings!

Example: Suppress YubiKey's auto-Enter key while keeping Enter normal on other keyboards.

Emulation Profile Switching

Pretend to be different keyboards:

Dell WK636 (VID: 046d, PID: c52b)
Apple Magic Keyboard (VID: 05ac, PID: 029f)
Logitech Unifying Receiver (VID: 046d, PID: 4049)
Any keyboard you clone!

Why? Some software only works with specific keyboard models. Clone the required keyboard and switch profiles as needed.

Mouse Control

Two ways to control the mouse:

Web Trackpad - Beautiful 500x350px trackpad in browser
- Click on trackpad → sends click to target PC
- Move in trackpad → cursor moves
- Right-click → context menu
- Scroll wheel → page scrolling
- Auto-calibration for your display size
Physical Mouse Pass-Through - Plug real mice into Pi
- Forwards all movements and clicks
- Multi-mouse support
- Zero latency

Per-Keyboard Custom Mappings

Three mapping types:

HID Remap - Map key X to key Y
- Example: Map F13 to Print Screen
Text Replacement - Map key to type text
- Example: Map F14 to type "show ip interface brief"
Suppress - Ignore specific keys
- Example: Suppress Enter key on YubiKey only

Management UI:

Select keyboard from dropdown
View all mappings in table
Add/Edit/Delete mappings
Export/Import for backup

📱 Web Interface

Access at http://<pi-ip>:8080

Modern Bootstrap 5 dark theme with tabbed interface:

Header Controls (Always Visible)

Status Bar: USB connection and emulation profile status
Mode Toggles: Keyboard and mouse pass-through switches
Quick Actions: Reboot button

Tab 1: Control (Default)

Send Text: Batch send text as keystrokes to connected computer
Trackpad: Interactive mouse control with sensitivity and calibration

Tab 2: Learning

Unmapped Keys: Auto-detected unknown keys with one-click mapping
HID Reference: Quick lookup for common HID codes

Tab 3: Mappings

Keyboard Management: Select any connected keyboard
Custom Mappings: Suppress keys, remap, or send text macros
Per-Keyboard Rules: Different mappings for each physical device

Tab 4: Settings

Emulation Profiles: Switch which keyboard device the Pi pretends to be
Detected Keyboards: See all physically connected keyboards
Export/Import: Backup your profiles and mappings

🚀 Advanced Usage

YubiKey Integration

Problem: YubiKey OTP mode sends Enter after password
Solution: Suppress Enter key on YubiKey only

1. Go to Mappings tab
2. Select "Yubico Yubikey NEO OTP+U2F+CCID"
3. Add Mapping:
   - Key Code: 28 (Enter)
   - Action Type: 🚫 Suppress
4. Done! YubiKey outputs password without auto-submit

Trackpad Calibration

Problem: Different screens need different sensitivities
Solution: Calibrate for each display

1. Enable Mouse Pass-through toggle in header
2. Go to Control tab → Click 🎯 Calibrate button
3. Use physical mouse to click 4 corners of screen
4. Save as "Windows Desktop" or "MacBook Pro"
5. Disable mouse pass-through toggle
6. Use web trackpad with perfect sensitivity!

Profile Switching

Problem: Some software requires specific keyboard models
Solution: Clone and switch profiles

1. Plug target keyboard into Pi
2. Go to Settings tab → Detected Physical Keyboards
3. Click "Clone" button next to the keyboard
4. Pi reboots as that keyboard
5. Use Emulation Profile dropdown to switch between saved profiles anytime

Multi-Computer Setup

Best Practice with KVM:

[Powered USB Hub] ← Constant power
      ↓
   [KVM] ← Switches USB data
      ↓
[Computer A] [Computer B] [Computer C]

Connected to hub:
- Raspberry Pi (via USB-C data cable)
  - Your keyboards
  - Your mice
- Microphone
- Other USB devices

Benefits:
- Pi stays powered (no reboot when switching)
- All devices switch together
- Web UI always accessible
- Different calibrations per computer

📦 What Gets Installed

On the Pi

Application Files:

/home/pi/pi-hid-bridge/
├── app/pi_kb.py              # Flask app (2,850+ lines)
├── scripts/
│   ├── setup_gadget_composite.sh  # Creates USB gadget
│   ├── cleanup_gadget.sh          # Removes USB gadget
│   └── gadget.conf                # VID/PID configuration
├── systemd/
│   ├── hid-gadget.service         # Auto-start gadget
│   └── pi-hid-bridge.service      # Auto-start Flask
└── requirements.txt               # Python deps

Runtime Data Files:

/home/pi/
├── keyboard_profiles.json         # Emulation profiles
├── keyboard_mappings.json         # Per-keyboard custom mappings
└── trackpad_calibrations.json     # Trackpad calibrations

System Configuration:

/boot/firmware/config.txt          # dtoverlay=dwc2 added
/boot/firmware/cmdline.txt         # modules-load=dwc2 added
/etc/systemd/system/               # Services installed

USB Devices Created:

/dev/hidg0                         # Keyboard
/dev/hidg1                         # Consumer Control (media keys)
/dev/hidg2                         # Mouse

🛠️ Pi Shell CLI

This project uses Pi Shell - a pip-installable CLI tool for managing Raspberry Pis via SSH.

Install: pip install pi-shell
GitHub: github.com/mcyork/pi-shell

Essential Commands

After adding your Pi with pi-shell add mypi ..., you can use the symlink:

# Check status
pi-shell status mypi

# Execute commands (streaming output)
mypi run-stream "command"

# Send files
mypi send /local/file /remote/path

# Read files
mypi read /remote/file > local-file

# List all Pis
pi-shell list

Deployment Commands

# Deploy from scratch
keybird-deploy mypi

# Quick restart (already deployed)
cd keybird/manual-deploy
./quick-start.sh mypi

🔌 Hardware Setup

Raspberry Pi 4 Model B

USB Ports:

USB-C port
- USB gadget output (connects to target computer)
4× USB-A ports - Connect keyboards, mice, YubiKey, etc.
Ethernet - Management network
Wi-Fi - Wireless management (optional)

Wiring:

Target Computer USB Port
         ↓
    [USB-C Cable] ← Data + Power
         ↓
    Pi USB-C Port
    
Pi USB-A Ports:
    ├─ Keyboard 1 (Dell)
    ├─ Keyboard 2 (YubiKey)
    ├─ Mouse 1 (Logitech)
    └─ Mouse 2 (Microsoft)

Power Options:

Via USB-C from target - If target provides enough power
Via GPIO pins - 5V to pins 2/4, GND to pin 6
PoE HAT - Power over Ethernet

📚 Documentation

Getting Started

Manual Deployment README - Deploy without pip install
Manual Deployment Guide - Step-by-step SSH deployment

Maintenance

Uninstall Guide - Complete removal instructions

🐛 Troubleshooting

USB Not Connecting

Check USB status:

mypi run-stream 'cat /sys/class/udc/*/state'

Should show: configured
If shows: not attached → Check USB cable is data-capable

Manually recreate gadget:

mypi run-stream 'sudo systemctl restart hid-gadget.service'

Services Won't Start

Check logs:

mypi run-stream 'sudo journalctl -u pi-hid-bridge.service -n 50'
mypi run-stream 'sudo journalctl -u hid-gadget.service -n 50'

Manual restart:

mypi run-stream 'sudo systemctl restart hid-gadget.service'
mypi run-stream 'sudo systemctl restart pi-hid-bridge.service'

Keyboard Pass-Through Not Working

Check keyboards detected:

curl http://<pi-ip>:8080/detected_keyboards

Enable pass-through:

Open web UI
Toggle "Keyboard Pass-through" in header

Check logs:

mypi run-stream 'sudo journalctl -u pi-hid-bridge.service -f'

Mouse Not Working

Check mouse devices exist:

mypi run-stream 'ls -la /dev/hidg*'

Should see: /dev/hidg0, /dev/hidg1, /dev/hidg2

If missing hidg2:

mypi run-stream 'sudo systemctl restart hid-gadget.service'

Web UI Not Loading

Check Flask is running:

mypi run-stream 'sudo systemctl status pi-hid-bridge.service'

Check it's listening:

mypi run-stream 'sudo ss -tlnp | grep 8080'

View live logs:

mypi run-stream 'sudo journalctl -u pi-hid-bridge.service -f'

🔄 Updating & Backup

Update Python Backend

mypi send app/pi_kb.py /home/pi/pi-hid-bridge/app/pi_kb.py
mypi run-stream 'sudo systemctl restart pi-hid-bridge.service'

Update Web UI (No Restart Needed)

mypi send templates/index.html /home/pi/pi-hid-bridge/templates/index.html
mypi send static/css/style.css /home/pi/pi-hid-bridge/static/css/style.css
mypi send static/js/app.js /home/pi/pi-hid-bridge/static/js/app.js
# Just refresh browser

Backup Profiles and Mappings

# Download from Pi
mypi read /home/pi/keyboard_profiles.json > backup_profiles.json
mypi read /home/pi/keyboard_mappings.json > backup_mappings.json
mypi read /home/pi/trackpad_calibrations.json > backup_calibrations.json

Or use Web UI → Export buttons.

Restore Backups

# Upload to Pi
mypi send backup_profiles.json /home/pi/keyboard_profiles.json
mypi send backup_mappings.json /home/pi/keyboard_mappings.json
mypi send backup_calibrations.json /home/pi/trackpad_calibrations.json

# Restart service
mypi run-stream 'sudo systemctl restart pi-hid-bridge.service'

Full Re-Deploy

keybird-deploy mypi

🌐 API Reference

Health Check

GET /health

USB Status

GET /usb_status
# Returns: {"state": "configured", "attached": true}

Keyboard Pass-Through

GET /passthrough
# Check status

POST /passthrough
# Body: {"enabled": true}
# Toggle on/off

Mouse Pass-Through

GET /mouse_passthrough
POST /mouse_passthrough
# Body: {"enabled": true}

Mouse Control

POST /mouse_move
# Body: {"dx": 10, "dy": -5, "buttons": 0, "wheel": 0}

POST /mouse_click
# Body: {"button": "left"}  # or "right", "middle"

Send Text

POST /send_text
# Body: {"text": "Hello, world!"}

Detected Keyboards

GET /detected_keyboards
# Returns list of physical keyboards with VID/PID

Detected Mice

GET /detected_mice
# Returns list of physical mice

Emulation Profiles

GET /emulation_profiles
# List all saved profiles

POST /emulation_profiles/switch
# Body: {"profile_id": "logitech_4049"}

Keyboard Mappings

GET /keyboard_mappings/all
# List all keyboards with mappings

GET /keyboard_mappings/<kbd_id>
# Get specific keyboard's mappings

POST /keyboard_mappings/<kbd_id>/mapping
# Body: {"code": 28, "type": "suppress"}

DELETE /keyboard_mappings/<kbd_id>/mapping/<code>

Trackpad Calibration

POST /calibration/start
# Start calibration process

GET /calibration/status
# Check calibration progress

POST /calibration/save
# Body: {"name": "Windows Desktop", "sensitivity": 3.2, "points": [...]}

GET /calibrations
# List all saved calibrations

POST /calibrations/<cal_id>/activate
# Activate a calibration profile

System Control

POST /reboot
# Reboot the Pi

📖 Detailed Documentation

Getting Started

Read DEPLOYMENT_QUICK_REFERENCE.md for deployment cheat sheet
Read DEPLOYMENT_GUIDE.md for detailed manual deployment

Feature Guides

LEARNING_MODE_GUIDE.md - Map unknown keys interactively
YUBIKEY_SUPPRESS_EXAMPLE.md - Suppress YubiKey Enter key
MOUSE_CONTROL_GUIDE.md - Use the web trackpad
TRACKPAD_CALIBRATION_GUIDE.md - Calibrate for your display
PROFILES_AND_MAPPINGS.md - Understand emulation vs mappings

Advanced Topics

KEYBOARD_VENDOR_NOTES.md - Why Dell keyboards show as Logitech
MOUSE_PASSTHROUGH_GUIDE.md - Physical mouse forwarding
FINDINGS.md - Pi 5 USB gadget investigation

🏗️ Architecture

Components

┌─────────────────────────────────────────────────┐
│           Target Computer (Windows/Mac/Linux)    │
│                        ▲                         │
│                        │ USB HID                 │
└────────────────────────┼─────────────────────────┘
                         │
                    USB-C Cable
                         │
┌────────────────────────▼─────────────────────────┐
│              Raspberry Pi 4 Model B              │
│  ┌───────────────────────────────────────────┐  │
│  │  Composite USB HID Gadget                 │  │
│  │  - /dev/hidg0 (Keyboard)                  │  │
│  │  - /dev/hidg1 (Consumer Control)          │  │
│  │  - /dev/hidg2 (Mouse)                     │  │
│  └───────────────────────────────────────────┘  │
│                      ▲                           │
│                      │                           │
│  ┌───────────────────┴───────────────────────┐  │
│  │         Flask Web App (pi_kb.py)          │  │
│  │  - Keyboard pass-through                  │  │
│  │  - Mouse pass-through                     │  │
│  │  - Custom mappings engine                 │  │
│  │  - Profile management                     │  │
│  │  - Calibration system                     │  │
│  │  - Web UI server                          │  │
│  └───────────────────┬───────────────────────┘  │
│                      │                           │
│                      │ evdev                     │
│                      ▼                           │
│  ┌──────────────────────────────────────────┐   │
│  │     Physical Input Devices               │   │
│  │  - Keyboards (YubiKey, Dell, Apple...)   │   │
│  │  - Mice (Logitech, Microsoft...)         │   │
│  └──────────────────────────────────────────┘   │
│                                                  │
│  Network: Ethernet + Wi-Fi ◄─── Web Browser     │
└──────────────────────────────────────────────────┘

Data Flow

Keyboard Pass-Through:

Physical Keyboard → evdev → Pi → Custom Mappings → HID Report → Target PC

Web Trackpad:

Browser → HTTP → Pi → Calibration → HID Report → Target PC

Profile Switching:

User Selection → Update gadget.conf → Reboot → New VID/PID → Target PC sees different keyboard

🤝 Contributing

This is a personal project, but suggestions welcome!

Areas for improvement:

Additional mapping types (delays, sequences)
Drag-and-drop mouse support
Encrypted macro implementation
AI command generation
GamePad emulation

📜 License

Personal project - use at your own risk!

🙏 Acknowledgments

Built with:

Flask - Web framework
evdev - Linux input device interface
Python - Glue holding it all together
Pi Shell - Pi management CLI (github.com/mcyork/pi-shell)

Inspired by Black Hat Booze (https://bhb.buzz) and the deep obsession with the distilation process - be it for spirits or code.

🗑️ Uninstalling

Keybird makes system-level changes that need proper cleanup:

# Complete removal (cleans everything)
sudo keybird-uninstall

# Then remove Python package
sudo pip uninstall keybird

# Reboot to apply boot config changes
sudo reboot

The uninstall script removes:

✅ USB gadget configuration (boot files)
✅ Systemd services
✅ Installed files in /opt/keybird/

Preserves (in case you reinstall):

💾 Saved profiles, mappings, calibrations in /home/pi/

See UNINSTALL.md for manual uninstall steps.

🆘 Support

Check logs:

sudo journalctl -u pi-hid-bridge.service -f

Reset everything (pip install users):

sudo systemctl restart hid-gadget.service
sudo systemctl restart pi-hid-bridge.service

Reset everything (manual deploy users):

cd keybird/manual-deploy
./quick-start.sh mypi

🚀 Version History

v1.0.12 (Dec 2025) - Pass-Through Initialization Fix: Fixed pass-through flags initialization at module level (now properly enabled on boot), improved deployment script to use source files during development, ensures GUI correctly shows pass-through status on startup
v1.0.11 (Dec 2025) - Pass-Through Reliability & Key Mapping Fixes: Fixed pass-through always enabled on boot (flags set before threads start, removed retry limits), fixed key mapping modifier handling to preserve user modifier state, improved mouse polling rate (1ms timeout), fixed indentation error in mouse pass-through loop
v1.0.10 (Dec 2025) - Auto-Start & UI Fixes: Pass-through modes (keyboard and mouse) now auto-start on boot by default, UI toggles correctly reflect enabled state, restored missing LED indicators and controls on Control tab
v1.0.9 (Nov 2025) - Human-Readable HID Code Dropdown: Added dropdown with human-readable key names (Delete, Enter, F1-F24, etc.) instead of requiring hex codes, with Custom option for unknown keys
v1.0.8 (Nov 2025) - Revert to File-Copying Deployment: Restored original deployment approach for better workflow (edit locally, deploy to multiple Pis)
v1.0.7 (Nov 2025) - Editable Mappings & Modifier Support: Auto-inject captured keys into editable table, inline editing of all mappings, modifier support (Ctrl+Alt+Shift+Win) for key combinations like Ctrl+Alt+Del
v1.0.6 (Nov 2025) - LED Control & Robustness: Added LED forwarding (sync host lock keys to physical keyboards), real-time LED status indicators, clickable lock key toggles in GUI, and improved pass-through crash recovery
v1.0.5 (Nov 2025) - Listen Mode & Branding: Added key listening mode for easy keyboard mapping, auto-start pass-through on boot, keyboard deduplication, favicon integration, and rebranded to "Keybird"
v1.0.4 (Oct 2025) - PyPI Fix: Corrected package build to include touch support for iPhone/iPad trackpad
v1.0.3 (Oct 2025) - Mobile Support: Added touch support for iPhone/iPad trackpad - touch to move cursor, tap to click, two-finger right-click
v1.0.2 (Oct 2025) - Modernization: Updated to Python 3.10+, replaced deprecated pkg_resources with importlib.resources
v1.0.1 (Oct 2025) - Bug fix: Fixed silent crash in keyboard pass-through mode
v1.0 (Oct 2025) - Initial release with keyboard pass-through, web UI, mouse control, trackpad calibration, multi-keyboard support, profiles, per-keyboard mappings, and YubiKey support
v0.1 (Oct 2025) - Initial prototype

Ready to control your computers like a pro? Deploy and enjoy! 🎮

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
.cursor/rules		.cursor/rules
docs		docs
keybird		keybird
manual-deploy		manual-deploy
pi-hid-bridge		pi-hid-bridge
.gitignore		.gitignore
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
pyproject.toml		pyproject.toml

License

mcyork/keybird

Folders and files

Latest commit

History

Repository files navigation

Keybird v1.0.12

🎯 What Is This?

⚡ Quick Start (2 Minutes)

Prerequisites

Deploy from Your Computer (No SSH login needed!)

What Gets Installed

Manual Deployment (See Under the Hood)

Post-Installation

Connect Hardware

Access Web UI

🎹 Core Features

Multi-Keyboard Pass-Through

Emulation Profile Switching

Mouse Control

Per-Keyboard Custom Mappings

📱 Web Interface

Header Controls (Always Visible)

Tab 1: Control (Default)

Tab 2: Learning

Tab 3: Mappings

Tab 4: Settings

🚀 Advanced Usage

YubiKey Integration

Trackpad Calibration

Profile Switching

Multi-Computer Setup

📦 What Gets Installed

On the Pi

🛠️ Pi Shell CLI

Essential Commands

Deployment Commands

🔌 Hardware Setup

Raspberry Pi 4 Model B

📚 Documentation

Getting Started

Maintenance

🐛 Troubleshooting

USB Not Connecting

Services Won't Start

Keyboard Pass-Through Not Working

Mouse Not Working

Web UI Not Loading

🔄 Updating & Backup

Update Python Backend

Update Web UI (No Restart Needed)

Backup Profiles and Mappings

Restore Backups

Full Re-Deploy

🌐 API Reference

Health Check

USB Status

Keyboard Pass-Through

Mouse Pass-Through

Mouse Control

Send Text

Detected Keyboards

Detected Mice

Emulation Profiles

Keyboard Mappings

Trackpad Calibration

System Control

📖 Detailed Documentation

Getting Started

Feature Guides

Advanced Topics

🏗️ Architecture

Components

Data Flow

🤝 Contributing

📜 License

🙏 Acknowledgments

Inspired by Black Hat Booze (https://bhb.buzz) and the deep obsession with the distilation process - be it for spirits or code.

🗑️ Uninstalling

🆘 Support

Packages