Initially, all the tools were command-line based and the libraries used raw sockets to access the Host Controller Interface offered by hardware. But since the early beginning of its adoption, there was interest to integrate it into the different desktop alternatives, mainly Gnome and KDE. Sharing the Bluetooth interface across the different desktop applications required a different approach: a daemon that took care of all the Bluetooth tasks that take place outside of the Linux Kernel, and an interface that would allow sharing access to that daemon. D-Bus had been designed as a common initiative for interoperability among free-software desktop environments, managed by FreeDesktop, and had already been adopted by the major Linux desktops, so it became the preferred option for that interface.
D-Bus, short for desktop bus, is an interprocess communication mechanism that uses a message bus. The bus is responsible for taking the messages sent by any process connected to it and delivering them to other processes in the same bus.There are two types of message bus. There is the system bus that permits connecting with the different system components, like the Bluetooth stack, that is controlled via BlueZ. There is also a session bus for each user logged into the system.
In order to use Bluetooth from an application, the application needs to connect to the system message bus and interact with it. Services get connected to the D-Bus by registering to it. D-Bus keeps an inventory of these things, these pieces of functionality that are connected to the bus. They are represented as objects, in the sense of object-oriented design. Each available object implements one or more interfaces which are represented with reverse DNS strings. Interfaces have properties, methods, and signals. Properties have values that can be get or set. Methods can be invoked and may or may not have a result. But interfaces also define signals (i.e., events) that an object can emit without any external trigger.
When we connect to D-Bus as a client, it provides us with a unique connection name (unique identifier of this connection). When objects are exported to the D-Bus –i.e., registered to it– they get a unique identifier. That identifier is encoded as a path which is used to route and deliver messages to that object. Applications may send messages to those objects and/or subscribe to signals emitted by them.
Linux, among other operating systems, implements a thin layer to enable communication between the host and the controller of the Bluetooth stack. That layer is known as Host-Controller Interface.
In the past,hciconfig and hcitool were the blessed tools to work with Bluetooth, but they used raw sockets and were deprecated around 2017. Nowadays, the recommended tools are bluetoothctl and btmgmt, although I believe that the old tools have been changed under their skin and are available without using raw sockets.
Enabling the Bluetooth radio was usually done with sudo hciconfig hci0 up. Nowadays, we can use bluetoothctl instead:
1bluetoothctl2[bluetooth]# show3Controller XX:XX:XX:XX:XX:XX (public)4 Name: ...5 Alias: ...6 Powered: no7 ...8[bluetooth]# power on9Changing power on succeeded10[CHG] Controller XX:XX:XX:XX:XX:XX Powered: yes11[bluetooth]# show12Controller XX:XX:XX:XX:XX:XX (public)13 Name: ...14 Alias: ...15 Powered: yes16 ...With the radio on, we can start scanning for BLE devices:
1bluetoothctl2[bluetooth]# menu scan3[bluetooth]# transport le4[bluetooth]# back5[bluetooth]# scan on6[bluetooth]# devicesThis shows several devices and my RP2 here:
Device XX:XX:XX:XX:XX RP2-SENSOR
Now that we know the MAC address/name pairs, we can use the former piece of data to connect to it:
1 [bluetooth]# connect XX:XX:XX:XX:XX:XX2 Attempting to connect to XX:XX:XX:XX:XX:XX3 Connection successful4 [NEW] Primary Service (Handle 0x2224)5 /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service00046 00001801-0000-1000-8000-00805f9b34fb7 Generic Attribute Profile8[NEW] Characteristic (Handle 0x7558)9 /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0004/char000510 00002a05-0000-1000-8000-00805f9b34fb11 Service Changed12[NEW] Primary Service (Handle 0x78c4)13 /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service000714 0000180a-0000-1000-8000-00805f9b34fb15 Device Information16[NEW] Characteristic (Handle 0x7558)17 /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0007/char000818 00002a29-0000-1000-8000-00805f9b34fb19 Manufacturer Name String20[NEW] Characteristic (Handle 0x7558)21 /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0007/char000a22 00002a24-0000-1000-8000-00805f9b34fb23 Model Number String24[NEW] Characteristic (Handle 0x7558)25 /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0007/char000c26 00002a25-0000-1000-8000-00805f9b34fb27 Serial Number String28[NEW] Characteristic (Handle 0x7558)29 /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0007/char000e30 00002a26-0000-1000-8000-00805f9b34fb31 Firmware Revision String32[NEW] Characteristic (Handle 0x7558)33 /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0007/char001034 00002a27-0000-1000-8000-00805f9b34fb35 Hardware Revision String36[NEW] Primary Service (Handle 0xb324)37 /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service001238 0000181a-0000-1000-8000-00805f9b34fb39 Environmental Sensing40[NEW] Characteristic (Handle 0x7558)41 /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0012/char001342 00002a1c-0000-1000-8000-00805f9b34fb43 Temperature Measurement44[NEW] Descriptor (Handle 0x75a0)45 /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0012/char0013/desc001546 00002902-0000-1000-8000-00805f9b34fb47 Client Characteristic Configuration48[NEW] Descriptor (Handle 0x75a0)49 /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0012/char0013/desc001650 0000290d-0000-1000-8000-00805f9b34fb51 Environmental Sensing Trigger Setting52[RP2-SENSOR]# scan offNow we can use the General Attribute Profile (GATT) to send commands to the device, including listing the attributes, reading a characteristic, and receiving notifications.
1[RP2-SENSOR]# menu gatt2[RP2-SENSOR]# list-attributes3...4Characteristic (Handle 0x0001)5 /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0012/char00136 00002a1c-0000-1000-8000-00805f9b34fb7 Temperature Measurement8...9[RP2-SENSOR]# select-attribute /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0012/char001310[MPY BTSTACK:/service0012/char0013]# read11Attempting to read /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0012/char001312[CHG] Attribute /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0012/char0013 Value:13 00 0c 10 00 fe .....14 00 0c 10 00 fe .....15[MPY BTSTACK:/service0012/char0013]# notify on16[CHG] Attribute /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0012/char0013 Notifying: yes17Notify started18[CHG] Attribute /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0012/char0013 Value:19 00 3b 10 00 fe .;...20[CHG] Attribute /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0012/char0013 Value:21 00 6a 10 00 fe .j...22[MPY BTSTACK:/service0012/char0013]# notify offAnd we leave it in its original state:
1[MPY BTSTACK:/service0012/char0013]# back2[MPY BTSTACK:/service0012/char0013]# disconnect3Attempting to disconnect from 28:CD:C1:0F:4B:AE4[CHG] Device 28:CD:C1:0F:4B:AE ServicesResolved: no5Successful disconnected6[CHG] Device 28:CD:C1:0F:4B:AE Connected: no7[bluetooth]# power off8Changing power off succeeded9[CHG] Controller B8:27:EB:4D:70:A6 Powered: no10[CHG] Controller B8:27:EB:4D:70:A6 Discovering: no11[bluetooth]# exitdbus-send comes with D-Bus.
We are going to send a message to the system bus. The message is addressed to "org.freedesktop.DBus" which is the service implemented by D-Bus itself. We use the single D-Bus instance, "/org/freedesktop/DBus". And we use the "Introspect" method of the "org.freedesktop.DBus.Introspectable". Hence, it is a method call. Finally, it is important to highlight that we must request that the reply gets printed, with "–print-reply" if we want to be able to watch it.
1dbus-send --system --print-reply --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.Introspectable.Introspect | lessThis method call has a long reply, but let me highlight some interesting parts. Right after the header, we get the description of the interface "org.freedesktop.DBus":
1<node>2 <interface name="org.freedesktop.DBus">3 <method name="Hello">4 <arg direction="out" type="s"/>5 </method>6 <method name="RequestName">7 ...8 </method>9 <method name="ReleaseName">10 ...These are the methods, properties and signals related to handling connections to the bus and information about it. Methods may have parameters (args with direction "in") and results (args with direction "out") and both define the type of the expected data. Signals also declare the arguments, but they are broadcasted and no response is expected, so there is no need to use "direction."
Then we have an interface to expose the D-Bus properties:
1<interface name="org.freedesktop.DBus.Properties">2...And a description of the "org.freedesktop.DBus.Introspectable" interface that we have already used to obtain all the interfaces. Inception? Maybe.
1<interface name="org.freedesktop.DBus.Introspectable">2 <method name="Introspect">3 <arg direction="out" type="s"/>4 </method>5</interface>Finally, we find three other interfaces:
1 <interface name="org.freedesktop.DBus.Monitoring">2 ...3 </interface>4 <interface name="org.freedesktop.DBus.Debug.Stats">5 ...6 </interface>7 <interface name="org.freedesktop.DBus.Peer">8 ...9 </interface>10</node>Let's use the method of the first interface that tells us what is connected to the bus. In my case, I get:
1dbus-send --system --print-reply --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.ListNames2method return time=1698320750.822056 sender=org.freedesktop.DBus -> destination=:1.50 serial=3 reply_serial=23 array [4 string "org.freedesktop.DBus"5 string ":1.7"6 string "org.freedesktop.login1"7 string "org.freedesktop.timesync1"8 string ":1.50"9 string "org.freedesktop.systemd1"10 string "org.freedesktop.Avahi"11 string "org.freedesktop.PolicyKit1"12 string ":1.43"13 string "org.bluez"14 string "org.freedesktop.ModemManager1"15 string ":1.0"16 string ":1.1"17 string ":1.2"18 string ":1.3"19 string ":1.4"20 string "fi.w1.wpa_supplicant1"21 string ":1.5"22 string ":1.6"23 ]The "org.bluez" is the service that we want to use. We can use introspect with it:
1dbus-send --system --print-reply=literal --dest=org.bluez /org/bluez org.freedesktop.DBus.Introspectable.Introspect |2xmllint --format - | lessxmllint can be installed with sudo apt-get install libxml2-utils.
After the header, I get the following interfaces:
1<node>2 <interface name="org.freedesktop.DBus.Introspectable">3 <method name="Introspect">4 <arg name="xml" type="s" direction="out"/>5 </method>6 </interface>7 <interface name="org.bluez.AgentManager1">8 <method name="RegisterAgent">9 <arg name="agent" type="o" direction="in"/>10 <arg name="capability" type="s" direction="in"/>11 </method>12 <method name="UnregisterAgent">13 <arg name="agent" type="o" direction="in"/>14 </method>15 <method name="RequestDefaultAgent">16 <arg name="agent" type="o" direction="in"/>17 </method>18 </interface>19 <interface name="org.bluez.ProfileManager1">20 <method name="RegisterProfile">21 <arg name="profile" type="o" direction="in"/>22 <arg name="UUID" type="s" direction="in"/>23 <arg name="options" type="a{sv}" direction="in"/>24 </method>25 <method name="UnregisterProfile">26 <arg name="profile" type="o" direction="in"/>27 </method>28 </interface>29 <interface name="org.bluez.HealthManager1">30 <method name="CreateApplication">31 <arg name="config" type="a{sv}" direction="in"/>32 <arg name="application" type="o" direction="out"/>33 </method>34 <method name="DestroyApplication">35 <arg name="application" type="o" direction="in"/>36 </method>37 </interface>38 <node name="hci0"/>39</node>Have you noticed the node that represents the child object for the HCI0? We could also have learned about it using busctl tree org.bluez. And we can query that child object too. We will now obtain the information about HCI0 using introspection but send the message to BlueZ and refer to the HCI0 instance.
1dbus-send --system --print-reply=literal --dest=org.bluez /org/bluez/hci0 org.freedesktop.DBus.Introspectable.Introspect | xmllint --format - | less1<node>2 <interface name="org.freedesktop.DBus.Introspectable">3 <method name="Introspect">4 <arg name="xml" type="s" direction="out"/>5 </method>6 </interface>7 <interface name="org.bluez.Adapter1">8 <method name="StartDiscovery"/>9 <method name="SetDiscoveryFilter">10 <arg name="properties" type="a{sv}" direction="in"/>11 </method>12 <method name="StopDiscovery"/>13 <method name="RemoveDevice">14 <arg name="device" type="o" direction="in"/>15 </method>16 <method name="GetDiscoveryFilters">17 <arg name="filters" type="as" direction="out"/>18 </method>19 <property name="Address" type="s" access="read"/>20 <property name="AddressType" type="s" access="read"/>21 <property name="Name" type="s" access="read"/>22 <property name="Alias" type="s" access="readwrite"/>23 <property name="Class" type="u" access="read"/>24 <property name="Powered" type="b" access="readwrite"/>25 <property name="Discoverable" type="b" access="readwrite"/>26 <property name="DiscoverableTimeout" type="u" access="readwrite"/>27 <property name="Pairable" type="b" access="readwrite"/>28 <property name="PairableTimeout" type="u" access="readwrite"/>29 <property name="Discovering" type="b" access="read"/>30 <property name="UUIDs" type="as" access="read"/>31 <property name="Modalias" type="s" access="read"/>32 <property name="Roles" type="as" access="read"/>33 </interface>34 <interface name="org.freedesktop.DBus.Properties">35 <method name="Get">36 <arg name="interface" type="s" direction="in"/>37 <arg name="name" type="s" direction="in"/>38 <arg name="value" type="v" direction="out"/>39 </method>40 <method name="Set">41 <arg name="interface" type="s" direction="in"/>42 <arg name="name" type="s" direction="in"/>43 <arg name="value" type="v" direction="in"/>44 </method>45 <method name="GetAll">46 <arg name="interface" type="s" direction="in"/>47 <arg name="properties" type="a{sv}" direction="out"/>48 </method>49 <signal name="PropertiesChanged">50 <arg name="interface" type="s"/>51 <arg name="changed_properties" type="a{sv}"/>52 <arg name="invalidated_properties" type="as"/>53 </signal>54 </interface>55 <interface name="org.bluez.GattManager1">56 <method name="RegisterApplication">57 <arg name="application" type="o" direction="in"/>58 <arg name="options" type="a{sv}" direction="in"/>59 </method>60 <method name="UnregisterApplication">61 <arg name="application" type="o" direction="in"/>62 </method>63 </interface>64 <interface name="org.bluez.LEAdvertisingManager1">65 <method name="RegisterAdvertisement">66 <arg name="advertisement" type="o" direction="in"/>67 <arg name="options" type="a{sv}" direction="in"/>68 </method>69 <method name="UnregisterAdvertisement">70 <arg name="service" type="o" direction="in"/>71 </method>72 <property name="ActiveInstances" type="y" access="read"/>73 <property name="SupportedInstances" type="y" access="read"/>74 <property name="SupportedIncludes" type="as" access="read"/>75 <property name="SupportedSecondaryChannels" type="as" access="read"/>76 </interface>77 <interface name="org.bluez.Media1">78 <method name="RegisterEndpoint">79 <arg name="endpoint" type="o" direction="in"/>80 <arg name="properties" type="a{sv}" direction="in"/>81 </method>82 <method name="UnregisterEndpoint">83 <arg name="endpoint" type="o" direction="in"/>84 </method>85 <method name="RegisterPlayer">86 <arg name="player" type="o" direction="in"/>87 <arg name="properties" type="a{sv}" direction="in"/>88 </method>89 <method name="UnregisterPlayer">90 <arg name="player" type="o" direction="in"/>91 </method>92 <method name="RegisterApplication">93 <arg name="application" type="o" direction="in"/>94 <arg name="options" type="a{sv}" direction="in"/>95 </method>96 <method name="UnregisterApplication">97 <arg name="application" type="o" direction="in"/>98 </method>99 </interface>100 <interface name="org.bluez.NetworkServer1">101 <method name="Register">102 <arg name="uuid" type="s" direction="in"/>103 <arg name="bridge" type="s" direction="in"/>104 </method>105 <method name="Unregister">106 <arg name="uuid" type="s" direction="in"/>107 </method>108 </interface>109</node>Let's check the status of the Bluetooth radio using D-Bus messages to query the corresponding property:
1dbus-send --system --type=method_call --print-reply --dest=org.bluez /org/bluez/hci0 org.freedesktop.DBus.Properties.Get string:org.bluez.Adapter1 string:PoweredWe can then switch the radio on, setting the same property:
1dbus-send --system --type=method_call --print-reply --dest=org.bluez /org/bluez/hci0 org.freedesktop.DBus.Properties.Set string:org.bluez.Adapter1 string:Powered variant:boolean:trueAnd check the status of the radio again to verify the change:
1dbus-send --system --type=method_call --print-reply --dest=org.bluez /org/bluez/hci0 org.freedesktop.DBus.Properties.Get string:org.bluez.Adapter1 string:PoweredThe next step is to start scanning, and it seems that we should use this command:
1dbus-send --system --type=method_call --print-reply --dest=org.bluez /org/bluez/hci0 org.bluez.Adapter1.StartDiscoveryBut this doesn't work because dbus-send exits almost immediately and BlueZ keeps track of the D-Bus clients that request the discovery.
bluetoothctl
Instead, we are going to use the command line utility bluetoothctl and monitor the messages that go through the system bus.
We start dbus-monitor for the system bus and redirect the output to a file. We launch bluetoothctl and inspect the log. This connects to the D-Bus with a "Hello" method. It invokes AddMatch to show interest in BlueZ. It does GetManagedObjects to find the objects that are managed by BlueZ.
We then select Low Energy (menu scan, transport le, back). This doesn't produce messages because it just configures the tool.
We start scanning (scan on), connect to the device (connect XX:XX:XX:XX:XX:XX), and stop scanning (scan off). In the log, the second message is a method call to start scanning (StartDiscovery), preceded by a call (to SetDiscoveryFilter) with LE as a parameter. Then, we find signals –one per device that is discoverable– with all the metadata of the device, including its MAC address, its name (if available), and the transmission power that is normally used to estimate how close a device is, among other properties. The app shows its interest in the devices it has found with an AddMatch method call, and we can see signals with properties updates.
Then, a call to the method Connect of the org.bluez.Device1 interface is invoked with the path pointing to the desired device. Finally, when we stop scanning, we can find an immediate call to StopDiscovery, and the app declares that it is no longer interested in updates of the previously discovered devices with calls to the RemoveMatch method. A little later, an announcement signal tells us that the "connected" property of that device has changed, and then there's a signal letting us know that InterfacesAdded implemented org.bluez.GattService1, org.bluez.GattCharacteristic1 for each of the services and characteristics. We get a signal with a "ServicesResolved" property stating that the present services are Generic Access Service, Generic Attribute Service, Device Information Service, and Environmental Sensing Service (0x1800, 0x1801, 0x180A, and 0x181A). In the process, the app uses AddMatch to show interest in the different services and characteristics.
We select the attribute for the temperature characteristic (select-attribute /org/bluez/hci0/dev_28_CD_C1_0F_4B_AE/service0012/char0013), which doesn't produce any D-Bus messages. Then, we read the characteristic that generates a method call to ReadValue of the org.bluez.GattCharacteristic1 interface with the path that we have previously selected. Right after, we receive a method return message with the five bytes of that characteristic.
As for notifications, when we enable them (notify on), a method call to StartNotify is issued with the same parameters as the ReadValue one. The notification comes as a PropertiesChanged signal that contains the new value and then we send the StopNotify command. Both changes to the notification state produce signals that share the new state.
In the next article, I will try to use the information that we have gathered about the D-Bus messages to interact with the Bluetooth stack using C++.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4