Context Navigation

Bluetooth Input

Bluetooth Input

Description

The Bluetooth Input daemon provides an interface to access Bluetooth Human Interface Devices. The Manager interface provides methods to list, create and remove input devices objects. The Device interface provides methods to retrieve device information, connect and disconnect.

Currently, fake input devices and device initiated connections are not supported.

The input service can be initiated even if there isn't an adapter available. Obviously new input objects can't be created since an adapter is required to perform service handle/record search.

Input Objects

(1) Represents a host initiated connection. Where a previously created input object is used to connect to a HID compliant device.
(2) Represents a remote initiated connection.

Stored Devices

When a new device is created and registered some service record attributes are stored in the file system("/var/lib/bluetooth/xx:xx:xx:xx:xx:xx/input"). The stored devices are automatically registered(D-Bus path) when the input service starts. All input files are read even the related local adapter is not available, making possible attach the adapter later and use the input object without any problem.

source:/input/input-api.txt

bluez/utils/input

manager.c -- contains the methods to create new input device/fake inputs.
device.c -- contains the generic functions used retrieve the common input device properties.
wii.c -- TBD
common.c -- common functions shared by input and fake inputs devices.
server.c -- contains the code to handle incoming connection from HID devices

Input API

Input Manager hierarchy (experimental)
======================================
Service		retrieved using org.bluez.Manager.ActivateService("input"). No well known name defined.
Interface	org.bluez.input.Manager
Object path	/org/bluez/input

Methods		array{string} ListDevices()
			Returns an array of available input devices path.

                string CreateDevice(string address)
                        Create an input device object. The HID service
                        record will be retrieved and the pairing will
                        be initiated if needed.

                        On success it will return the path of the
                        newly created device object.

                void RemoveDevice(string path)
                        Remove the input device object for a given path.

Signals         void DeviceCreated(string path)

                void DeviceRemoved(string path)

Input Device hierarchy (experimental)
======================================

Service         retrieved using org.bluez.Manager.ListServices(). No well known name defined.
Interface       org.bluez.input.Device
Object path     /org/bluez/input/{keyboard*|mouse*|...}

Methods         string GetAddress()

                        Returns the device address.

                        Example: "00:11:22:33:44:55"

                string GetName()

                        Returns the service name.

                uint16 GetProductId()

                        Returns the product id.

                uint16 GetVendorId()

                        Returns the vendor id.

                boolean IsConnected()

                        Returns the connection status.

                void Connect()

                        Connect to the input device.

                void Disconnect()

                        Disconnect from the input device.

Signals		TBD

Configuration File

The configuration file defines some service properties. When the BlueZ daemon starts all services(.service) files under "/etc/bluetooth" are loaded.
Input service file(input.service) example:

[Bluetooth Service]
Identifier=input
Name=Input service
Description=Bluetooth HID based Input service
Autostart=true

Device Creation Scenario

The following figure shows how clients can use the Input API.

(1) The device discovery procedure is outside the scope of this document. Clients/Wizards can use stored Input device address, start a discovery procedure or just listen for "RemoteDeviceFound?" signals.
(2) When the system start, only the Bluetooth services with the flag "Autostart" enabled will be activated(Read the Configuration file section). When sending an ActivateService? message, the client/wizard will obtain the Bus ID required to send messages directly to the service.
(3) Represents a CreateDevice? call used to create a new input device. Only peripheral major class is accepted.
(4) Represents service discovery calls. The input service will use the BlueZ D-Bus API to search the remote device records. The service records contains the remote device properties required to connect to the HID device. Clients using the input service doesn't need to worry about the service search procedure.
(5) Represents a host initiated call to establish a input connection.

Host/HID initiated connections

At the ending of CreateDevice? method the input service daemon automatically connects/disconnect to the control and interrupt channels enabling HID initiated connections. After that host initiated and HID initiated connections will be available. The host can call Device.Connect or the user can press a HID key starting the HID initiated connection.

Security

Trigger the bonding process is not input service's task. If the user wants create an encrypted keyboard connection an external application(wizard or other) should start the bonding.

For keyboards, if the link key(Bonding) is available, the input service will try authenticate and encrypt the link. When it is not available, an unencrypted connection is established.

The Bluetooth input service is fully integrated with the BlueZ Authorization API. When a incoming connection is detected the input service uses the Authorization interface to ask if the connection is allowed or not.

BlueZ Gnome authorization request example: