Bluez: where can i find all the definitions documented in /doc?

i want to learn about bluetooth programming in C.
After some research i found this linked on the Bluez official website. https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/

since iam not familiar with this linux type of documentation i cant really get much out of it but i made some assumptions.

my first try was to look at the first function in doc/adapter-api.txt and there is no mention where the functions are located.
so i searched for it in every /lib file and could not find anything.

so where can i find all the definitions documented in /doc?

BlueZ is the Bluetooth stack for Linux and it has a few API's for people to use. Below is a list of the possible API’s starting from lowest level and going to the highest. For most people, the higher the better.

Raw HCI

This bypasses the BlueZ bluetoothd that is running on a Linux system that is used to coordinate interactions with the Bluetooth hardware. This API is outside of the BlueZ infrastructure so is not documented by the BlueZ project. All the information is available in the Bluetooth Core Specification which runs to about 3,256 pages for the 5.2 version of the spec.

If using this level it is a good idea to stop the Bluetooth service from starting the Bluetooth daemon so they are not conflicting. There is no safety net with HCI so you really, really need to know what you are doing.

MGMT Socket

The BlueZ Bluetooth Mamagement API is the next step up and the lowest level that the BlueZ developers recommend. This looks quite "HCI" in its API but it commnicates with the bluetoothd which issues HCI commands to the hardware.

This is documented at:
https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/mgmt-api.txt

D-Bus API

This should be the go to level for most people wanting to interact with the BlueZ API’s. The commands interact with the bluetoothd which issues HCI commands to the hardware.

The good point of a D-Bus API is that it is language agnostic. However, it seems the number of people that are familiar with D-Bus is a relatively small and so it is another level of indirection to learn before using the API.

Most popular programming languages appear to have bindings to D-Bus. Some of the bindings are listed at:

https://www.freedesktop.org/wiki/Software/DBusBindings/

The BlueZ D-Bus API is split across multiple documents depending what piece of functionality is required. For interacting with the Bluetooth Adapter it is documented at:

https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/adapter-api.txt

And the device API is at:

https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/device-api.txt

etc...

Before diving in to coding it might be useful to experiment with interacting with the BlueZ bluetoothd through the D-Bus API. This can be done with various command line tools. I'm going to assume that you will be using the gdbus library for your C code so that seems like a good choice to experiment with on the command line.

The BlueZ D-Bus API for the Linux Bluetooth adapter is probably the easiest to get started with.

The documentation for this API is at:

https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/adapter-api.txt

At the top of the document it says what the D-Bus Service and Interface is. And that the object path can be variable.

Service     org.bluez
Interface   org.bluez.Adapter1

The bluetoothd is communicating on the D-Bus System bus.

D-Bus has a GetManagedObjects method that we can use to report all the things BlueZ knows about. To list all this information about BlueZ use:

$ gdbus call --system --dest org.bluez --object-path / --method org.freedesktop.DBus.ObjectManager.GetManagedObjects

This is usually a lot of information so let's use grep to find the object path for the adapter:

$ gdbus call --system --dest org.bluez --object-path / --method org.freedesktop.DBus.ObjectManager.GetManagedObjects | grep -Pio "/org/bluez/hci.*Adapter1"

/org/bluez/hci0': {'org.freedesktop.DBus.Introspectable': {}, 'org.bluez.Adapter1

So we can now see that (for me) the D-Bus object path is /org/bluez/hci0. I can introspect this now:

$ gdbus introspect --system --dest org.bluez --object-path /org/bluez/hci0

Now I have the Service, Interface and Object Path I can call methods as documented by BlueZ. For example to find what available filters that can be given to SetDiscoveryFilter:

$ gdbus call --system --dest org.bluez --object-path /org/bluez/hci0 --method org.bluez.Adapter1.GetDiscoveryFilters

(['UUIDs', 'RSSI', 'Pathloss', 'Transport', 'DuplicateData'],)

To get all the properties on the Adapter then we can use the GetAll method (that we can see from the introspection) is on the org.freedesktop.DBus.Properties interface. A call example:

$ gdbus call --system --dest org.bluez --object-path /org/bluez/hci0 --method org.freedesktop.DBus.Properties.GetAll "org.bluez.Adapter1"

To get the value of one property we use Get:

$ gdbus call --system --dest org.bluez --object-path /org/bluez/hci0 --method org.freedesktop.DBus.Properties.Get "org.bluez.Adapter1" "Powered"

To set the value of a property we use Set:

$ gdbus call --system --dest org.bluez --object-path /org/bluez/hci0 --method org.freedesktop.DBus.Properties.Set "org.bluez.Adapter1" "Powered" "<boolean true>"

The following looks like a useful introduction to doing some of this in C:

https://www.linumiz.com/bluetooth-list-devices-using-gdbus/

There is a talk "Doing Bluetooth Low Energy on Linux" by Szymon Janc that may also be useful background. It is available on YouTube:

https://youtu.be/VMDyebKT5c4

And a PDF of the slides:

https://elinux.org/images/3/32/Doing_Bluetooth_Low_Energy_on_Linux.pdf