Release of BlueZ 5.5

Again, mostly a bug fix release with fixes to SDP, AVRCP, NFC and name resolving during discovery. There are also some new features:

  • New passthrough operations for AVRCP
  • Auto-pairing (PIN lookup) support
  • Proper HID reconnection support

Besides these externally visible changes there was also a rather big refactoring patch-set that went in to establish a new “service” concept internally within bluetoothd and its plugins. This paves the way to have each remote service represented as a separate object through D-Bus, something which may already appear in the next BlueZ release.


Release of sbc-1.1

With this release the SBC library now supports encoding and decoding of the mSBC codec used with Handsfree 1.6  Wideband Speech feature.


Release of BlueZ 5.4

It has been a fairly quiet period since BlueZ 5.3 (hopefully meaning the current tree is in a pretty good shape and doesn’t have any major issues) but the amount of fixes and minor feature additions has now grown big enough to justify a new release. So here we go with BlueZ 5.4! It consists mostly of bug fixes but some new features have also crept in:

  • Improved AVRCP 1.5 feature support (mostly player handling related)
  • New key mappings for AVRCP Target role (for systems that need more than traditional playback control)
  • Improved MAP client features, including Message Notification Service (MNS)
  • Improved command line client (client/bluetoothctl) agent callback support


Release of BlueZ 5.3

This is mostly a bug fix release with several fixes and improvements to A2DP and AVRCP. There’s also a fix to the local adapter name setting, some fixes to SDP processing (thanks to newly implemented unit tests for the SDP library) as well as an update to the latest neard API to support NFC based pairing.


Release of BlueZ 5.2

This release fixes some issues with LE pairing and re-connections and also enables the possibility of connecting LE through the Device1.Connect D-Bus method. There is also a fix to the Profile interface where bluetoothd now waits for reverse SDP to complete before accepting a connection and calling the NewConnection D-Bus method (important so that the right profile version and features can be included in the method call). Besides the bug fixes there’s also more AVRCP 1.5 support  related to volume control and browsing.


Release of BlueZ 5.1

This is mostly a bugfix release covering issues that were discovered since 5.0, but there are also a couple of new feature additions:

  • Integration with systemd’s hostname daemon. The local Bluetooth adapter name will automatically be set through this (if available).
  • New test tools:
    • tools/mgmt-tester: Test cases for the kernel Management interface. Depends on the hci_vhci kernel module and uses it to verify that the right actions occur also on the HCI level and not just at the kernel-user space border (i.e. the management interface itself).
    • unit/test-sdp: This test tool provides the entire set of SDP qualification test cases.
    • unit/test-eir: Test tool for testing the parsing of various EIR and AD data. The btsnoop tool has also received support for extracting EIR and AD data chunks out of HCI traces.
  • Experimental MediaPlayer1 interface introduced. See doc/media-api.txt and tools/mpris-player (which provides a user session proxy to export remote media players as local MPRIS capable ones). Note that this interface is unstable (may see backwards incompatible changes) and needs to be explicitly enabled using the –experimental bluetoothd command line switch.


Release of BlueZ 5.0

After more than a half year of development the BlueZ project is proud to announce the release of BlueZ 5 with numerous new features, API simplifications and other improvements. With this release BlueZ only supports the new Bluetooth Management kernel interface that was introduced in Linux 3.4, so essentially this is the minimum kernel requirement for BlueZ 5. For Low Energy support at least kernel version 3.5 is needed.


The new major version indicates that the API is not backwards compatible with BlueZ 4, which means that any applications, agents, etc will need to be updated. The BlueZ internal test scripts and tools have naturally already been updated to support the new API.

With this release the hcidump (bluez-hcidump.git) and obexd (obexd.git) projects have been merged into the main BlueZ project (bluez.git) and new releases of them will come as part of new 5.x BlueZ releases.

We have a separate BlueZ 5 API introduction and porting guide for developers, but here are a few of the more high level changes since the BlueZ 4.x series:

  • Move to standard D-Bus ObjectManager & Properties interface
  • Remove Manager interface as the same functionality comes through ObjectManager
  • Remove support for audio UNIX socket interface (the Media D-Bus interface replaces it)
  • SBC library moved into its own project
  • GStreamer elements removed after submitting them to the upstream GStreamer project
  • Removal of the Service interface and introduction of a new (libbluetooth independent) Profile interface
  • New bluetoothctl command line too for interacting with BlueZ
  • New btmon monitoring tool
  • Remove internal support for telephony (HFP and HSP) profiles. They should be implemented using the new Profile interface preferably by the telephony subsystem of choice (e.g. oFono which already supports this)
  • General connection establishment procedure and vastly simplified D-Bus API for it
  • The adapter power state is not stored persistently and remembered over bluetoothd restarts. An external entity (like ConnMan) is expected to handle this.
  • libbluetooth not installed by default as it’s not really useful or recommended anymore. The new Profile interface further decreases its usefulness.
  • INI-style format for all storage file. Old files from BlueZ 4 are auto-converted.
  • Merge obex-client into the main obexd daemon
  • D-Bus interface versions with the intent to always keep support at least for the two latest versions.
  • New Low Energy profiles:
    • Cycling Speed
    • Scan Parameters
    • Alert
    • Heartrate
    • HID over GATT (HoG)

BlueZ 5 API introduction and porting guide

The BlueZ 5 D-Bus API contains significant changes compared to BlueZ 4. The bulk of the changes are due to the following features in BlueZ 5:

  • Transformation to use standard D-Bus Properties and ObjectManager interfaces (available in the D-Bus specification document)
  • Introduction of interface versions (e.g. org.bluez.Adapter1). When new versions are introduced we’ll try to keep supporting at least the two latest versions simultaneously.
  • The simplification or removal of per-profile interfaces and the addition of a general org.bluez.Device1.Connect method to connect profiles.
  • The removal of the org.bluez.Service interface (used for registering SDP records and authorization) and the introduction of a new org.bluez.Profile1 interface
  • Dynamic device object creation during device discovery
  • Introduction of an AgentManager1 interface
  • Base path moved to “/org/bluez”. This shouldn’t make much difference though as the main entry point to any interaction through D-Bus is the ObjectManager.GetManagedObjects call.

D-Bus Properties

The D-Bus Properties interface generalizes access to object/interface properties. BlueZ 4 implemented properties with custom GetProperties and SetProperty methods and PropertyChanged signals on each interface that needed them. Since the release of BlueZ 4 a standard Properties interface has been completed and instead of having these methods and signal on specific interfaces there exists a generic org.freedesktop.DBus.Properties interface on each object with methods such as Set, Get and GetAll as well as a PropertiesChanged signal. These methods and signals contain the specific interface the property belongs to as part of the message parameters. One feature which the standard properties interface exposes that didn’t exist in BlueZ 4 is the invalidation of a property. This is particularly convenient to relay the information that a property doesn’t exist any more.

D-Bus ObjectManager

The D-Bus ObjectManager interface is a generic way of accessing the the entire object hierarchy of a D-Bus service. It includes signals for interface addition and removal and a single GetManagedObjects method which returns all available objects in a service, including interfaces of the objects as well as all properties on all interfaces. The actual ObjectManager interface can be found on the root (“/”) path of the BlueZ service.

Because most tasks of managing and discovering objects can be done through ObjectManager many methods, signals and properties in BlueZ 4 became redundant and were decided to be removed. One of the most notable of these removals is the old org.bluez.Manager interface. In BlueZ 5 there does not exist anything that would correspond to this. Instead, an application would discover the available adapters by performing a ObjectManager.GetManagedObjects call and look for any returned objects with an “org.bluez.Adapter1″ interface. The concept of a default adapter was always a bit fuzzy and the value could’t be changed, so if applications need something like it they could e.g. just pick the first adapter they encounter in the GetManagedObjects reply.

There’s a test/get-managed-objects test script in the source tree that can be used to see the bluetoothd objects exported by ObjectManager.

Device discovery

Bluetooth Low Energy essentially extended Bluetooth addresses with one extra bit, requiring one to always know whether an address is “random” or “public”. This caused issues with the BlueZ 4 API where the address was given to BlueZ in the CreateDevice and CreatePairedDevice calls. Since the parameter didn’t contain any of this extra random/public information bluetoothd had to maintain an internal cache to look up the necessary info. Another complication to the matter is that the BlueZ D-Bus API doesn’t differentiate between traditional BR/EDR devices and LE devices so there are essentially three possible address types: BR/EDR, LE public and LE random.

To solve this issue we decided to simply get rid of explicit CreateDevice/CreatePairedDevice methods and instead dynamically create device objects as they are discovered during device discovery. Since ObjectManager is available this also means that a separate DeviceFound signal is no longer needed. Instead an application doing discovery can simply track newly created device objects through the usual ObjectManager signals. To pair a device (identical to the old CreatePairedDevice) a new Device1.Pair method was added, and to skip pairing and just connect a Device1.Connect method was added (similar, but not quite the same as the old CreateDevice). Once the discovery stops, devices neither connected to or paired will be automatically removed by bluetoothd within three minutes.

There’s a test/test-discovery test script in the source tree that can both be used for testing discovery as well as an example of how to implement device discovery support to an application (which methods and signals are involved, etc)

General device connection procedure

BlueZ 4 had a general Device.Disconnect method but no general Connect. The closest you would get was the Connect method on the Audio interface which grouped together all audio profiles into a single coordinated connection procedure.

Through internal re-factoring and creation of a cleaner internal profile interface BlueZ 5 has been able to generalize this for all profiles and introduce a Device1.Connect method. Any implemented profile can elect to participate in this general connection procedure and will get connected when the user calls the method. Internally this method contains some special knowledge about the recommended connection order for profiles and will sort the profiles based on that. One example is the audio profiles where it’s desirable to have HFP connected first, then A2DP and finally AVRCP.

What this interface means to applications is that instead of trying to discover supported profiles of a device and then deciding exactly which interface’s Connect method needs to be called (org.bluez.Input, org.bluez.Audio, etc. in BlueZ 4) the application can straight proceed to call Device1.Connect and not worry about the details.

To test the Device1.Connect() functionality you can e.g. use the test/test-device script: test-device connect <remote addr>

The new Profile1 interface (and removal of org.bluez.Service)

BlueZ 5 introduces a new generic D-Bus interface for implementing external profiles. The profile (residing in a separate process) implements a org.bluez.Profile1 interface and registers an object implementing it through a new ProfileManager1 interface on the BlueZ side. In the RegisterProfile method (on the ProfileManager1 interface) the profile needs to at least provide the UUID for the profile to be registered. BlueZ has internally a table of defaults for common profiles so no other information is necessarily needed. However, if the profile desires to it can provide information such as the full SDP record (XML encoded), desired security level, enable/disable authorization, version, features, role, name, etc.

Once the profile is registered bluetoothd will take over all tasks needing to be done until the point of a fully created connection for the profile. This includes registering an SDP record (for server-side profiles), starting server sockets or connecting client sockets, and performing authorization (for server-side profiles). Once bluetoothd has completed these tasks it will pass the new connection to the external profile object through a Profile1.NewConnection method call. The method call contains the file descriptor (socket) for the connection as well as a dictionary of properties for the connection. These properties can include things like Version and Features (fetches from the remote SDP record) or even profile-specific entries which bluetoothd internally provides a mechanism to register hooks for.

Since this interface fulfills the same tasks (and more) than the org.bluez.Service interface in BlueZ 4 the old interface has been removed. At the time of BlueZ 5 release, existing projects that have been converted to use the new Profile interface include obexd (all OBEX profiles) as well as oFono (for HFP).

There are a few test scripts in the source tree like test/test-profile and test/test-hfp that can be used as examples for interacting with the ProfileManager1 interface.

The new AgentManager1 interface

BlueZ requires the registration of Agent objects to handle pairing and incoming connection authorization. BlueZ 5 does away with the old Adapter.RegisterAgent method and the agent parameter of the CreatePairedDevice method (Device1.Pair in BlueZ 5) in favor of a more generic AgentManager1 inteface. All agents need to be registered through this interface and BlueZ will automatically pick the agent of same application that called Device1.Pair (assuming that application also owns an agent). An AgentManager1.RequestDefault method exists for an agent to request to become the default one, in which case it will be assigned to handle all incoming (remotely initiated) requests. An agent that previously registered itself with Adapter.RegisterAgent should register itself as the default agent in BlueZ 5.

There are also a few changes for the Agent1 interface (in addition to the rename from Agent to Agent1). Firstly, the ConfirmModeChange method has been removed as this was tied in to the Adapter.RequestSession functionality which was also removed (due to not adding much value). Secondly, there is a new RequestAuthorization method used for requesting authorization for pairing requests which would otherwise not trigger any action for the user. The main situation where this would occur is an incoming SSP pairing request that would trigger the just-works model.

There’s a test/simple-agent test script for testing the AgentManager1 interface as well as giving an example of how agent registration is done.