NordicBTKeyBridge

NordicBTKeyBridge turns a Nordic Semiconductors Bluetooth Low Energy (BLE) board into a keyboard bridge. It accepts key event packets over USB CDC (serial) and exposes a BLE HID keyboard to a target host (Windows, Linux, macOS, iPad etc).

It lets you programmatically send key events to a host that supports BLE HID keyboards.

Related projects

• keybridged: Go HTTP daemon + client library that sends key events to bridge firmware over UART/USB CDC.
• PicoUSBKeyBridge: wired USB HID version of this idea (UART -> USB keyboard).

Architecture at a glance

flowchart LR
  app[YourApp_or_Scripts] --> http[keybridged_HTTP_API]
  http --> cdc[USB_CDC_Serial]
  cdc --> fw[NordicBTKeyBridge_Firmware]
  fw --> ble[BLE_HID_Keyboard]
  ble --> host[TargetHost]

Loading

Use cases:

• Automate iPads or tablets that only accept Bluetooth keyboards.
• Drive hardware test rigs that need deterministic input events.
• Programmatically emulate keyboard input from software workflows.

What you need

• A Nordic board supported by the latest NCS with a USB port.
• This firmware.

Example hardware

I am using the nRF52840 Dongle. Another example is the Seeed Studio XIAO nRF52840 Sense.

Backend daemon (keybridged)

To actually send key events, you usually run the companion daemon on your computer: keybridged.

It keeps a persistent USB CDC connection to the device and exposes a small HTTP API.

keybridged defaults are set to this project's USB CDC VID/PID (VID 0x1915, PID 0x520F), so in the common case you can run:

go run github.com/2opremio/keybridged/cmd/keybridged@latest

Quick test (send A = HID code 4 + Shift):

curl -X POST "http://localhost:9876/pressandrelease" \
  -H "Content-Type: application/json" \
  -d '{"type":"keyboard","code":4,"modifiers":{"left_shift":true}}'

Build

Prerequisites

• nRF Connect for VS Code extension (for SDK/toolchain installation and building).
• Git.

For nRF52840 dongle (example hardware)

You have two options:

1. Use prebuilt firmware (easiest):

   • Download nrf52840_dongle_merged.hex from the latest release.
   • Skip to the Flash section.

2. Build from source:

   • Follow the build instructions below.

Build from source

Tested with NCS 3.2.1 and the matching Toolchain Manager toolchain.

1. Install nRF Connect for VS Code and follow the official quick setup guide: https://docs.nordicsemi.com/bundle/nrf-connect-vscode/page/get_started/quick_setup.html

2. Install the SDK and toolchain (if not already installed):

   • In VS Code, open the nRF Connect view.
   • Under WELCOME, click Manage SDKs and install nRF Connect SDK v3.2.1.
   • Click Manage toolchains and install the matching nRF Connect SDK Toolchain v3.2.1.

3. Open the NordicBTKeyBridge folder in VS Code.

4. In the nRF Connect view, under Applications, click Add build configuration.

5. In the Add Build Configuration screen:

   • For nRF52840 dongle: Set CMake Preset to Build for nrf52840dongle.
   • For other boards: No preset is available; configure Board target and other settings manually.
   • Select SDK/toolchain v3.2.1.

6. Build.

The output will be in build/merged.hex (or your configured build directory).

Flash

For nRF52840 dongle

Use the nRF Connect Programmer app (part of nRF Connect for Desktop):

1. Install nRF Connect for Desktop and the Programmer app.
2. Push the small flashing button on the dongle (the lateral button, not the main GPIO button) to put it into bootloader mode.
3. Plug in the dongle.
4. Open Programmer → select the dongle.
5. "Add file" → pick nrf52840_dongle_merged.hex (prebuilt) or build/merged.hex (if you built from source).
6. "Write".

For other boards

Flashing steps vary by board (bootloaders/debug probes differ). Use the vendor's recommended flashing method for Zephyr/NCS projects.

Device identity (serial vs keyboard)

There are two separate identities involved in a typical setup:

• Serial side (what keybridged uses): the USB VID/PID of this device's USB CDC interface.
  • Default: VID 0x1915, PID 0x520F.
  • This is what keybridged -vid/-pid matches.
• Keyboard side (what the target host sees): the BLE HID keyboard identity.
  • BLE is not USB, so there is no "USB VID/PID" on the BLE link.
  • This firmware sets a Bluetooth PnP ID (VID/PID) via the Device Information Service (DIS): VID 0x1915, PID 0xEEEF (values borrowed from Nordic's HID keyboard samples because they're a reasonable, known pair).

Pairing

Pair once from your host's Bluetooth settings (Just Works). The device stores bonds and will auto-reconnect to the last bonded host on restart. If you "forget" the device on the host and pair again, the device will automatically replace the old bond (no manual reset required).

To pair a different host, just connect from the new host; the previous bond will be overwritten automatically. This is intentionally simple and optimized for quick repairs/rebonding.

Security note: this behavior is less secure than strict bonding. While the device is disconnected, an unauthorized host could pair and take over by overwriting the bond. We accept this trade-off for ease of use. We may add a more secure mode later if requested.

Serial protocol

The serial protocol is shared with PicoUSBKeyBridge#serial-protocol and documented there.

Porting

This firmware targets Nordic-based boards today, but it should be portable to any USB+BLE capable board supported by Zephyr.