Your Bluetooth keyboard, mouse, and gamepad, presented as plain USB.
Cordial turns an inexpensive microcontroller board into a standalone Bluetooth-to-USB adapter. Pair your wireless peripherals once and plug the adapter into any computer, KVM switch, or OS. No host Bluetooth, no drivers, and no background software required.
Download | Quick Start | Supported Boards | Documentation
- Plain USB everywhere: The host sees standard USB keyboards, mice, and gamepads, so your devices work in BIOS/UEFI, disk-encryption prompts, KVM switches, and locked-down machines without host Bluetooth or drivers.
- Standalone and portable: Pairings, device preferences, and input profiles are stored on the adapter itself. Quit the app or move the adapter to another computer and everything keeps working.
- Sleep-friendly: Bluetooth connections stay alive while the host sleeps, standard USB remote wake is supported, and nothing typed during suspend is replayed on wake.
- Logitech HID++ integration: Translates special keys for Linux, Windows, or macOS, reports battery status, and configures DPI, SmartShift, scroll direction, backlighting, Fn-row behavior, and auto power-off on supported Logitech devices.
- USB gamepads: RP2040 and RP2350 boards forward Bluetooth controllers as standard USB HID or XInput gamepads, with automatic builtin mappings for common Xbox, DualShock 4, and Luna layouts.
- On-adapter input profiles: Remap keys, mouse buttons, and controller inputs, scale pointer or scroll axes, and stack per-device layers directly on the adapter. Edit keyboard and mouse rules in VIA or Vial, or edit any rule from the CLI; see Input profiles.
- One native companion tool: A single
cordialexecutable provides a native GTK4/libadwaita desktop app, a full-screen TUI, an interactive shell, and scriptable one-shot CLI commands with JSON protocol logging.
| Board | Firmware Code | Bluetooth | Gamepads | Input Profiles |
|---|---|---|---|---|
| Raspberry Pi Pico W | pico_w |
Classic and BLE | HID and XInput | No |
| Raspberry Pi Pico 2 W | pico2_w |
Classic and BLE | HID and XInput | Yes |
| Pimoroni Pico Plus 2 W | pimoroni_pico_plus2_w |
Classic and BLE | HID and XInput | Yes |
| Waveshare RP2350B-Plus-W | waveshare_rp2350b_plus_w |
Classic and BLE | HID and XInput | Yes |
| ESP32-S3 (4 MiB+ flash, native USB) | esp32s3 |
BLE only | No | Yes |
Each board's release archive is named cordial-firmware-<version>-<code>.tar.gz.
A Linux x86-64 computer is used to flash firmware and configure the adapter. Once paired, the adapter works with any operating system without running Cordial.
Download the package for your distribution from the latest release. The cordial package includes the desktop app, TUI, CLI, and udev rules.
Arch Linux:
sudo pacman -U cordial-[0-9]*-1-x86_64.pkg.tar.zstUbuntu 26.04 (resolute) or Debian 13 (substitute trixie for resolute):
sudo apt install ./cordial_[0-9]*-1~resolute_amd64.debUsing another distribution? Download the AppImage or portable tar archive; see the Installation guide for setup, udev permissions, and GNOME tray icon details.
For RP2040 and RP2350 boards:
- Download and extract your board's firmware archive from the latest release.
- Hold BOOTSEL (or BOOT) while plugging the board into USB so it mounts as a USB drive.
- Copy the extracted
.uf2file onto the drive. The board reboots as a Cordial adapter.
For ESP32-S3 download-mode and esptool instructions, or debug firmware builds, see Firmware installation.
- Plug in the adapter and launch Cordial.
- Open the adapter in the sidebar, select Add Device, and put your Bluetooth peripheral into pairing mode.
- Select Pair next to the device and follow any passkey prompt.
You can also manage adapters from a terminal:
cordial desktop # launch the GTK4/libadwaita desktop app
cordial tui # open the full-screen terminal UI
cordial adapter list # list attached adapters
cordial --port PORT # open the interactive shellUser guides:
- Installation -- packages, AppImage, udev permissions, tray icon, and firmware flashing
- Gamepad outputs -- HID and XInput controller setup and slot pools
- Input profiles -- remapping, layers, VIA/Vial editing, and builtin controller rules
- Logitech HID++ support -- feature inventory, special-key translations, and device settings
Developer and technical references:
- Building from source -- Docker and local builds, board presets, packaging, and test suites
- USB control protocol -- serial API, framing, commands, records, HID forwarding, and client behavior
- On-board storage format -- flash layout, LittleFS records, migrations, and recovery
Cordial is licensed under the MIT License. Third-party components retain their own licenses; see notices/.