Skip to content

Instantly share code, notes, and snippets.

@charbonnierg

charbonnierg/ble-monitor.md

Last active April 24, 2024 08:42
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save charbonnierg/c23080fdf27b4afd541563cf17ccb967 to your computer and use it in GitHub Desktop.
Save charbonnierg/c23080fdf27b4afd541563cf17ccb967 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
ble-monitor.md

blemonitor

Monitor BLE devices using Bluez and D-Bus.

Requirements

  • Bluez >= 5.56
  • Linux Kernel >= 5.10

Questions

  • How are discovery filters used by the passive scanning ? Are they ignored ?

Overview

  1. Open a connection to the D-Bus system bus.

  2. Call the method GetManagedObjects method on the org.freedesktop.DBus.ObjectManager interface at org.bluez object path.

  3. Parse the returned objects and extract the BLE adapters. For example, an adapter object path is /org/bluez/hci0.

  4. Make sure the adapter implements the interface org.bluez.AdvertisementMonitorManager1

    • note: this requires Bluez experimental mode enabled to exist

  5. Mount an object implementing the org.bluez.AdvertisementMonitor1 interface on a freely definable object path (for example /org/blemonitor/monitor0)

    • note: this requires Bluez experimental mode enabled to have an effect

  6. Call the method RegisterMonitor method of the org.bluez.AdvertisementMonitorManager1 interface on the adapter object path and pass the object path of the monitor object as argument (for example /org/blemonitor/monitor0).

  7. After use, the client should call UnregisterMonitor method of the org.bluez.AdvertisementMonitorManager1 interface on the adapter object and pass the object path of the previously registered monitor object as argument (for example /org/blemonitor/monitor0) to invalidate it.

Pitfalls

  • The Bluez experimental mode must be enabled to use the advertisement monitor feature. This can be done by adding --experimental to the Bluez command line arguments.

  • It is necessary to watch the D-Bus for added/removed entries in the object tree. This can be done by listening to the InterfacesAdded and InterfacesRemoved signals of the org.freedesktop.DBus.ObjectManager interface at the adapter object path.

  • It is necessary to watch the D-Bus for changes in the adapter properties. This can be done by listening to the PropertiesChanged signal of the org.freedesktop.DBus.Properties interface at the adapter object path.

  • The advertisement monitor object must be mounted on a unique object path. The object path must not be in use by another object.

  • The advertisement monitor object must be unregistered after use to avoid memory leaks.

About org.bluez.AdvertisementMonitor1

The org.bluez.AdvertisementMonitor1 interface is used to monitor BLE advertisements. The interface has the following methods:

Method Parameter Type Return Type Description
Release() - - Called as a signal for a client to perform clean-up when monitor cannot be activated after it was exposed or after monitor has been deactivated.
Activate() - - After a monitor was exposed, this gets called as a signal for client to get acknowledged when a monitor has been activated, so the client can expect to receive calls on DeviceFound() or DeviceLost().
DeviceFound(device) 'o' (object path) - This gets called to notify the client of finding the targeted device. Once receiving the call, the client should start to monitor the corresponding device to retrieve the changes on RSSI and advertisement content.
DeviceLost(device) 'o' (object path) - This gets called to notify the client of losing the targeted device. Once receiving this call, the client should stop monitoring the corresponding device.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment