D-Bus API for HFPD

The HFP for Linux package provides a service daemon, hfpd, that performs most of the low-level functions required to implement the hands-free side of Bluetooth Hands-Free Profile. The hfpd process attaches to the D-Bus session bus, and is entirely controlled via D-Bus messages. All of its status can be retrieved via D-Bus, and changes to its status are notified through D-Bus signals.

The D-Bus APIs are ideally suited for constructing hands-free applications using high-level languages, such as Python, C#, or even Perl. As a lower level and much more complicated alternative, one may use the libhfp C++ APIs.

The D-Bus APIs described in this document are relatively complete. The hfconsole application is implemented entirely in Python, and uses dbus-python to access D-Bus APIs described in this document. It does not directly depend on BlueZ, and does not use the BlueZ D-Bus APIs or Python bindings. The APIs described here, and PyGTK, are the only dependencies of hfconsole in order for it to do its job.

HFPD Features

• Supports device scanning, connection, disconnection, and automatic reconnection
• Supports multiple concurrently connected audio gateway devices
• Resilient to loss of Bluetooth service
• Supports the ALSA and OSS audio hardware interfaces
• Supports audio system test modes
• Supports microphone input cleanup, including echo cancellation and noise reduction.
• Supports simple recording and playback of stored audio files, e.g. for recording calls and playing ring tones.

D-Bus Access

A D-Bus client wishing to make use of HFPD must be able to connect to D-Bus, and send and receive messages. The simplest way to do this is to choose an appropriate D-Bus binding for your language or toolkit. An updated list of bindings can be found connected to the D-Bus home page.

The HFPD process acquires the D-Bus unique name net.sf.nohands.hfpd .

The install target of the HFP for Linux Makefiles will install a D-Bus service description file for HFPD. This allows dbus-daemon to start HFPD as needed. D-Bus clients of this API only need to send messages to the HFPD unique name in order for HFPD to be started. D-Bus clients do not need to be concerned with starting and stopping HFPD themselves.

Two known object paths are intended as the primary points of access to D-Bus clients:

• /net/sf/nohands/hfpd , with interface net.sf.nohands.hfpd.HandsFree
• /net/sf/nohands/hfpd/soundio , with interface net.sf.nohands.hfpd.SoundIo

For each known audio gateway device, an object with interface net.sf.nohands.hfpd.AudioGateway will be instantiated. A new object of this type can be instantiated for an audio gateway device with a specific Bluetooth address using net.sf.nohands.hfpd.HandsFree.AddDevice(), and the paths of all such objects of this type are enumerated in net.sf.nohands.hfpd.HandsFree.AudioGateways.

All interfaces provided by HFPD are introspectable and should be usable with most any language binding.

D-Bus Properties

HFPD D-Bus objects make extensive use of the standard D-Bus properties interface, org.freedesktop.DBus.Properties. Ideally, one would expect a D-Bus language binding for an object-oriented language to expose properties as simple data members of the proxy objects. For example, in Python, the following would make a lot of sense to set the net.sf.nohands.hfpd.HandsFree.SecMode property on an HFPD instance:

 hfpd = dbus.Interface(
        dbus.get_object('net.sf.nohands.hfpd',
                        '/net/sf/nohands/hfpd'),
                        dbus_interface = 'net.sf.nohands.hfpd.HandsFree')
 hfpd.SecMode = 2

Unfortunately, a number of D-Bus language bindings, including dbus-python, skimp on properties and do not provide access to properties in the most transparent possible way. Depending on the language and bindings package used, a D-Bus client application of HFPD may need to take extra measures to access properties, often manually invoking org.freedesktop.DBus.Properties.Get and org.freedesktop.DBus.Properties.Set . For example, the above must instead be implemented as:

 hfpd = dbus.Interface(
        dbus.get_object('net.sf.nohands.hfpd',
                        '/net/sf/nohands/hfpd'),
                        dbus_interface = 'net.sf.nohands.hfpd.HandsFree')
 hfpdprop = dbus.Interface(
        dbus.get_object('net.sf.nohands.hfpd',
                        '/net/sf/nohands/hfpd'),
                        dbus_interface = 'org.freedesktop.DBus.Properties')
 hfpdprop.Set('net.sf.nohands.hfpd.HandsFree', 'SecMode', 2)

For more information on the standard D-Bus properties interface, consult the D-Bus specification.

D-Bus Client Guide

The purpose of an HFPD D-Bus client is to implement the very high-level logic of managing audio gateway devices and audio connections, and of course, presenting status information to the user. It is possible to create a complete D-Bus client for HFPD that is very simple. Such a program might implement the following:

• Keep a private configuration file, and use it to save the Bluetooth address of at least one audio gateway device that it is bound to.
• Connect to HFPD using D-Bus, and claim the device(s) remembered in its configuration file using net.sf.nohands.hfpd.HandsFree.AddDevice().
• For each claimed device:
  • Set the net.sf.nohands.hfpd.AudioGateway.AutoReconnect property to true.
  • Register to receive the net.sf.nohands.hfpd.AudioGateway.AudioStateChanged signal, and use the signal handler to start streaming audio to and from the audio gateway device, using net.sf.nohands.hfpd.SoundIo.AudioGatewayStart(), or failing that, close the audio connection with net.sf.nohands.hfpd.AudioGateway.CloseAudio().
  • Register to receive the net.sf.nohands.hfpd.AudioGateway.StateChanged and net.sf.nohands.hfpd.AudioGateway.CallStateChanged signals, and use them to display simple status for the audio gateway.

It is also possible to create a D-Bus client that does not claim any devices. Such a client might maintain a status display, and either depend on another client to claim and manage audio gateway devices, or depend on HFPD's list of permanently known audio gateway devices to permit incoming connections.

---