btkbdd man page

btkbdd — 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.


Lubomir Rintel <lkundrak@v3.sk>
Collin R. Mulliner <collin@betaversion.net>


Parts of code were taken from were taken from xkbd-bthid project.

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 <https://github.com/lkundrak/virtkbd>. 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


Explore man page connections for btkbdd(8).

1.5 2015-10-13