btkbdd - Man Page

Bluetooth Keyboard Daemon


btkbdd [-s addr] [-t addr] [-c file] [-d] device


This tool starts a Bluetooth HID Keyboard service, serving keystrokes  obtained via Linux Input subsystem's event device (evdev). In practical terms, it turns your Linux box with a physical keyboard into  a Bluetooth keyboard, which can be used by various Bluetooth HID capable  devices, including desktop or tablet computers, smart phones, game  consoles and so on.

It implements most of the important HID protocol features, including  robust connection restores (virtual cabling) and report protocol (as  required by Apple's Darwin-based devices). It is possible and encouraged  to use the tool from udev, starting it when event devices appear after a  keyboard is plugged in.


-s addr

Accept connections on given Bluetooth address. Useful when your computer has multiple Bluetooth Host Controller Interfaces (HCI).

Class of this device is changed into keyboard while the program is running and restored upon termination.

Defaults to accepting connections on any interface, while changing the class only of the first interface hci0, which is a sane default for computers with a single HCI.

-t addr

Attempt connecting to given address upon key press, if no connection has  been estabilished yet. This can be used to effectively “hardwire” the  keyboard to a given host.

Once an incoming connection is estabilished and terminated, btkbdd always tries to restore it upon a key press event.

-c file

Save the last connected remote address into given file upon termination  and restore it on startup.

Use this option if you want to remember last connected device between  btkbdd runs.


Become a daemon.  Give up controlling terminal, open file descriptors and  double-fork to escape parent process control.

While breaking process hierarchy has certain disadvantages and is  deprecated with modern service control daemons such as systemd(8)), it is necessary to do so with udevd(8), otherwise btkbdd would block  the whole worker process.


Linux input subsystem event device to use as source for key presses.


Use with udev(7) and systemd(1) is recommended. Look into 90-btkbdd.rules and btkbdd@.service files distributed with btkbdd for examples.

btkbdd /dev/input/event8

Most basic usage — just open a keyboard device and listen for incoming  connections.  When in doubt about which physical device corresponds to an  event device node, use udevadm info --attribute-walk --name=file to  identify the device and its connection details.

btkbdd /dev/input/event8 -s EC:55:F9:EF:12:34 -c /var/lib/btkbdd/keyboard.cable

Only accept connections on given HCI and remember the connected device. You can discover your HCI device addresses with hcitool dev command.

btkbdd /dev/input/event8 -t EC:55:F9:EF:56:78

Initiate a connection to given Bluetooth host. You can discover available devices with hcitool scan.


Bluez bluetoothd(8) daemon is likely to listen for HID events. For btkbdd to accept connection you need to disable the Bluez input plugin by setting DisablePlugins = input in /etc/bluetooth/main.conf.

Nothing but errors is logged and when in daemon mode even the error output  is lost. Attach strace(1) or launch btkbdd manually to troubleshoot  errors.

Only a common 101-key keyboard is supported.

To estabilish pairing with iPad, iPod Touch or iPhone, connection must be initiated and authenticated via bluetooth-applet(1)  before starting btkbdd. Otherwise the device will initiate a PIN-based  authentication that is not supported. Once trust is estabilished, connections will work without a need for any other hassle.


btkbdd can be redistributed under the same terms and conditions as  xkbd-bthid itself: GNU General Public License (any version at your option).

The source code repository can be obtained from <>. Bug fixes and feature ehancements licensed under same conditions as btkbdd  are welcome via GIT pull requests.

See Also

udev(7), systemd(1), systemd.service(5), systemd.unit(5), bluetoothd(8), hcitool(1),  USB Device Class Definition for Human Interface Devices (HID), Bluetooth HID Profile.

Referenced By


2021-07-21 1.5 System management commands