The BlueZ project recently made a new major release, BlueZ version 5. This release brings tons of new features and improvements, however it is also accompanied by a significant API change that makes it non-backwards compatible. BlueZ has changed to use the standard D-Bus Properties and Object Manager infrastructure, simplifying the handling of D-Bus interfaces and notifications. In addition to matching to D-Bus standards, the API of some of our interfaces also had to change, either to support new features and use cases or to optimize the API usage.
Another sensible change is related to the kernel requirements of BlueZ 5.0. BlueZ developers have recently added the Bluetooth Management (MGMT) Interface to the Linux Kernel, which significantly improves the Bluetooth experience on Linux. Among other things, you now get fine control of the HCI commands and events we send and receive to/from the Bluetooth device. In the past, this control was split between userspace and the kernel, creating synchronization problems. Now, it is handled solely by the MGMT interface in an internal queue inside the kernel. This change makes the bluetoothd daemon wake up a lot less often, saving more CPU and power for your system. A nice side-effect of those changes is that we could also get rid of blocking operations in the bluetoothd daemon when talking with Bluetooth devices.
As the MGMT interface is the only one to support the new Bluetooth Low Energy devices, BlueZ developers decided to drop support for the old interface once MGMT was completed. As a result, you need to be running Linux Kernel 3.4 or newer to use BlueZ 5.
While BlueZ developers felt the API change was necessary for this new BlueZ release, they understand that API breaks are painful for everyone. Therefore, in BlueZ 5 they introduced the notion of API versioning. For example, let’s say that today BlueZ supports “org.bluez.Device1” and “org.bluez.AgentManager1” interfaces, among others. The “1“ would refer to version 1 of the API. If for some reason we need to upgrade the Device API a new interface, “org.bluez.Device2”, could be created while still supporting the “org.bluez.Device1” interface. The two interfaces will therefore be supported simultaneously, giving you time to port your software to the new API instead of seeing things breaking overnight.
To help you with the migration to BlueZ 5, we released an extensive guide introducing the new APIs.
If you need help to bring your product to the future of Bluetooth on Linux, Collabora is available to assist you with your adoption of BlueZ 5. We can also help you on any commercial support, development or training around BlueZ, come talk to us.