Skip to content
ryanpetrisPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Cordial logo

Cordial

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.

Latest release App: Linux x86-64 MIT license

Download  |  Quick Start  |  Supported Boards  |  Documentation

Why Cordial

  • 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 cordial executable provides a native GTK4/libadwaita desktop app, a full-screen TUI, an interactive shell, and scriptable one-shot CLI commands with JSON protocol logging.

Supported Boards

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.

Quick Start

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.

1. Install 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.zst

Ubuntu 26.04 (resolute) or Debian 13 (substitute trixie for resolute):

sudo apt install ./cordial_[0-9]*-1~resolute_amd64.deb

Using another distribution? Download the AppImage or portable tar archive; see the Installation guide for setup, udev permissions, and GNOME tray icon details.

2. Flash Firmware

For RP2040 and RP2350 boards:

  1. Download and extract your board's firmware archive from the latest release.
  2. Hold BOOTSEL (or BOOT) while plugging the board into USB so it mounts as a USB drive.
  3. Copy the extracted .uf2 file 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.

3. Pair a Device

  1. Plug in the adapter and launch Cordial.
  2. Open the adapter in the sidebar, select Add Device, and put your Bluetooth peripheral into pairing mode.
  3. 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 shell

Documentation

User 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:

License

Cordial is licensed under the MIT License. Third-party components retain their own licenses; see notices/.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages