Add component batteries and Fast Pair Message Stream
Subsystems (2)
v2 cover Add component batteries and Fast Pair Message Stream
True wireless earbuds can report separate charge states for the left bud, right bud, and charging case. Battery1 currently has one fixed object per Device1, so BlueZ cannot expose those values without collapsing them into one percentage.
Extend the battery core and provider API to support child Battery1 objects with a stable identifier, optional percentage, and optional charging state. The existing Battery1 object at the Device1 path remains the aggregate compatibility interface. Component objects and their new properties remain experimental.
Add an experimental Fast Pair Message Stream profile. The Message Stream specification defines both a fixed endpoint UUID over RFCOMM and an L2CAP PSM transport:
https://developers.google.com/nearby/fast-pair/specifications/extensions/messagestream
This series implements the RFCOMM variant. Pixel Buds Pro advertise the fixed UUID in SDP, from which the profile obtains the RFCOMM channel. L2CAP Message Stream support is left for future work.
The Device Information extension defines battery update message group 0x03, code 0x03, with three component bytes using the Battery Notification encoding:
https://developers.google.com/nearby/fast-pair/specifications/extensions/deviceinformation
https://developers.google.com/nearby/fast-pair/specifications/extensions/batterynotification
The generic unknown-level status bit is retained for earbuds. The TWS-specific unsupported-case value 0xff is treated as unavailable:
If the Message Stream closes while BR/EDR remains connected, invalidate the values and reconnect with exponential backoff. Reset the backoff only after a battery-producing stream remains connected for the maximum backoff interval, and do not retry permanent local errors. Once BR/EDR disappears, cancel pending work and remove the component objects. The final patch adds a standalone diagnostic and provider tool for interoperability testing.
Existing UPower versions continue to consume the aggregate Battery1 object. When experimental BlueZ is enabled, they may log a coldplug warning for a child object and ignore it because they expect Device1 at the same path. The aggregate remains available, so the currently displayed value is preserved.
UPower support for component objects, including python-dbusmock integration tests, is available here:
https://gitlab.freedesktop.org/mkurz/upower/-/commits/fastpair-multi-battery
It is based on:
https://gitlab.freedesktop.org/upower/upower/-/merge_requests/337
With the Bluetooth address anonymised, the object hierarchy observed with Pixel Buds Pro was:
/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/battery_left /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/battery_right /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/battery_case
Each child implements org.bluez.Battery1. GetAll returned:
battery_left:
Percentage = 92
Source = "Fast Pair Message Stream" Device = /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF Identifier = "left"
Charging = false
battery_right:
Percentage = 90
Source = "Fast Pair Message Stream" Device = /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF Identifier = "right"
Charging = false
battery_case:
Source = "Fast Pair Message Stream" Device = /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF Identifier = "case"
Charging = false
Percentage was absent from the case object because its reported level was unknown. This layout can be reproduced with python-dbusmock.
The complete path was tested through patched BlueZ, UPower, Solid, PowerDevil, BlueZQt and BlueDevil. KDE Plasma's Power & Battery applet displayed separate left, right and case batteries, including an unknown case level, and the Bluetooth applet displayed all three components. Related KDE changes are:
https://invent.kde.org/frameworks/solid/-/merge_requests/264
https://invent.kde.org/plasma/powerdevil/-/merge_requests/666
The series was tested with Pixel Buds Pro using an ASan/UBSan build. The live tests covered fresh left/right/case reports, an unavailable case value, explicit Message Stream disconnection, remote device disconnection, reconnection, adapter power-down, and cancellation of a profile connection in progress. Component properties were invalidated or removed as appropriate, and the daemon reported no sanitizer failure.
The full 40-test make check suite passes under ASan/UBSan. The seven Fast Pair parser tests provide 100% line coverage (55/55) and 95.83% branch-direction coverage (46/48) for message-stream.c. They cover complete, fragmented, coalesced/partial, zero-length and maximum-length frames, invalid input, unknown-level status bits, the unavailable-case sentinel, and reserved battery values.
Changes in v2:
- Clarify the RFCOMM transport and cite the protocol sources.
- Gate component objects and properties behind experimental mode.
- Document opaque component paths and the provider properties separately.
- Replace Message Stream magic numbers with shared named constants.
- Correct unknown-level and TWS unsupported-case decoding.
- Invalidate stale values and make disconnect handling reliable with dual-mode devices.
- Add reconnect backoff, permanent-error handling, and safe pending-connect cancellation.
- Improve the diagnostic provider's ObjectManager lifecycle and isolate it per adapter.
- Expand parser tests and record their coverage in doc/test-coverage.txt.
v1:
https://lore.kernel.org/r/[email protected]
Matthias Kurz (4):
battery: Add component battery objects
doc: Document component battery objects
fastpair: Add Message Stream battery profile
test: Add Fast Pair Message Stream tool
.gitignore | 1 + Makefile.am | 8 + Makefile.plugins | 5 + Makefile.tools | 2 +- doc/org.bluez.Battery.rst | 35 +- doc/org.bluez.BatteryProvider.rst | 16 + doc/test-coverage.txt | 3 +- profiles/fastpair/fastpair.c | 650 +++++++++++++++++++++++++++++ profiles/fastpair/message-stream.c | 135 ++++++ profiles/fastpair/message-stream.h | 58 +++ src/battery.c | 401 +++++++++++++++--- src/battery.h | 4 + test/test-fastpair | 568 +++++++++++++++++++++++++ unit/test-fastpair.c | 322 ++++++++++++++ 14 files changed, 2146 insertions(+), 62 deletions(-) create mode 100644 profiles/fastpair/fastpair.c create mode 100644 profiles/fastpair/message-stream.c create mode 100644 profiles/fastpair/message-stream.h create mode 100755 test/test-fastpair create mode 100644 unit/test-fastpair.c
base-commit: c73fa2f9ae2d366cb8a4f101fa9a5ccd9f33a4ea
Signature · 1 line
2.55.0
PATCH v2 1/4 battery: Add component battery objects
Allow one Bluetooth device to export multiple Battery1 objects while keeping the legacy aggregate object at the device path.
Component objects expose their parent Device1 path, a stable identifier, an optional percentage, and an optional charging state. Extend BatteryProvider1 handling with the same semantics so external providers can publish multiple batteries too.
Keep component objects and their new properties behind the experimental D-Bus flag while the API is being established.
--- src/battery.c | 401 ++++++++++++++++++++++++++++++++++++++++++-------- src/battery.h | 4 + 2 files changed, 347 insertions(+), 58 deletions(-)
src/battery.c +343 -58
@@ -35,11 +35,18 @@#define BATTERY_MAX_PERCENTAGE 100 +struct battery_provider ; +struct btd_battery {char *path;/* D-Bus object path */ +char *device_path;/* Parent Device1 object path, if any */ +char *identifier;/* Stable component identifier, if any */ uint8_t percentage;/* valid between 0 to 100 inclusively */ +int charging;/* 0 or 1 when known, -1 otherwise */ char *source;/* Descriptive source of the battery info */ char *provider_path;/* The provider root path, if any */ +char *provider_object_path;/* The provider battery object, if any */ +struct battery_provider *provider;/* Does not own pointer */ struct bt_battery *filter; };
@@ -86,18 +93,29 @@ static bool match_path(const void *data, const void *user_data)return g_strcmp0 (battery->path, path) ==0 ; } -static struct btd_battery *battery_new (const char *path,const char *source, -const char *provider_path) +static struct btd_battery *battery_new (const char *path, +const char *device_path, +const char *identifier, +const char *source, +const char *provider_path, +const char *provider_object_path, +struct battery_provider *provider) {struct btd_battery *battery; battery = new0(struct btd_battery, 1); battery->path =g_strdup (path); + battery->device_path =g_strdup (device_path); + battery->identifier =g_strdup (identifier); battery->percentage =UINT8_MAX ; + battery->charging =-1 ;if (source) battery->source =g_strdup (source);if (provider_path) battery->provider_path =g_strdup (provider_path); +if (provider_object_path) + battery->provider_object_path =g_strdup (provider_object_path); + battery->provider = provider; battery->filter =bt_battery_new ();return battery;
@@ -105,11 +123,12 @@ static struct btd_battery *battery_new(const char *path, const char *source,static void battery_free (struct btd_battery *battery) { -if (battery->path) -g_free (battery->path); - -if (battery->source) -g_free (battery->source); +g_free (battery->path); +g_free (battery->device_path); +g_free (battery->identifier); +g_free (battery->source); +g_free (battery->provider_path); +g_free (battery->provider_object_path);if (battery->filter) {bt_battery_free (battery->filter);
@@ -157,15 +176,83 @@ static gboolean property_source_exists(const GDBusPropertyTable *property,return battery->source !=NULL ; } +static gboolean property_device_get (const GDBusPropertyTable *property, +DBusMessageIter *iter,void *data) +{ +struct btd_battery *battery = data; + +dbus_message_iter_append_basic (iter,DBUS_TYPE_OBJECT_PATH , + &battery->device_path); + +return TRUE; +} + +static gboolean property_device_exists (const GDBusPropertyTable *property, +void *data) +{ +struct btd_battery *battery = data; + +return battery->device_path !=NULL ; +} + +static gboolean property_identifier_get (const GDBusPropertyTable *property, +DBusMessageIter *iter,void *data) +{ +struct btd_battery *battery = data; + +dbus_message_iter_append_basic (iter,DBUS_TYPE_STRING , + &battery->identifier); + +return TRUE; +} + +static gboolean property_identifier_exists (const GDBusPropertyTable *property, +void *data) +{ +struct btd_battery *battery = data; + +return battery->identifier !=NULL ; +} + +static gboolean property_charging_get (const GDBusPropertyTable *property, +DBusMessageIter *iter,void *data) +{ +struct btd_battery *battery = data; +dbus_bool_t charging = battery->charging; + +dbus_message_iter_append_basic (iter,DBUS_TYPE_BOOLEAN , &charging); + +return TRUE; +} + +static gboolean property_charging_exists (const GDBusPropertyTable *property, +void *data) +{ +struct btd_battery *battery = data; + +return battery->charging >=0 ; +} +static const GDBusPropertyTable battery_properties[] = { {"Percentage" ,"y" , property_percentage_get,NULL , property_percentage_exists }, {"Source" ,"s" , property_source_get,NULL , property_source_exists }, + {"Device" ,"o" , property_device_get,NULL , property_device_exists, +G_DBUS_PROPERTY_FLAG_EXPERIMENTAL }, + {"Identifier" ,"s" , property_identifier_get,NULL , + property_identifier_exists,G_DBUS_PROPERTY_FLAG_EXPERIMENTAL }, + {"Charging" ,"b" , property_charging_get,NULL , + property_charging_exists,G_DBUS_PROPERTY_FLAG_EXPERIMENTAL }, {} }; -struct btd_battery *btd_battery_register (const char *path,const char *source, -const char *provider_path) +static struct btd_battery *battery_register (const char *path, +const char *device_path, +const char *identifier, +const char *source, +const char *provider_path, +const char *provider_object_path, +struct battery_provider *provider) {struct btd_battery *battery;
@@ -181,7 +268,8 @@ struct btd_battery *btd_battery_register(const char *path, const char *source,return NULL ; } - battery =battery_new (path, source, provider_path); + battery =battery_new (path, device_path, identifier, source, + provider_path, provider_object_path, provider);battery_add (battery); if (!g_dbus_register_interface(btd_get_dbus_connection(), battery->path,
@@ -201,8 +289,78 @@ struct btd_battery *btd_battery_register(const char *path, const char *source,return battery; } +struct btd_battery *btd_battery_register (const char *path,const char *source, +const char *provider_path) +{ +return battery_register (path,NULL ,NULL , source, provider_path,NULL , +NULL ); +} + +static char *battery_build_component_path (const char *device_path, +const char *identifier) +{ +const unsigned char *str = (const unsigned char *) identifier; +GString *path; + +if (!device_path || !identifier || !identifier[0 ]) +return NULL ; + + path =g_string_new (device_path); +g_string_append (path,"/battery_" ); + +for (; *str; str++) { +if (g_ascii_isalnum (*str)) +g_string_append_c (path, *str); +else +g_string_append_printf (path,"_%02x" , *str); + } + +return g_string_free (path, FALSE); +} + +static struct btd_battery * +battery_register_component (const char *device_path,const char *identifier, +const char *source,const char *provider_path, +const char *provider_object_path, +struct battery_provider *provider) +{ +struct btd_battery *battery; +char *path; + +if (!(g_dbus_get_flags () &G_DBUS_FLAG_ENABLE_EXPERIMENTAL )) { +DBG ("component batteries require experimental interfaces" ); +return NULL ; + } + + path =battery_build_component_path (device_path, identifier); +if (!path) { +error ("error registering battery: invalid component" ); +return NULL ; + } + + battery =battery_register (path, device_path, identifier, source, + provider_path, provider_object_path, + provider); +g_free (path); + +return battery; +} + +struct btd_battery *btd_battery_register_component (const char *device_path, +const char *identifier, +const char *source) +{ +return battery_register_component (device_path, identifier, source,NULL , +NULL ,NULL ); +} +bool btd_battery_unregister (struct btd_battery *battery) { +if (!battery) { +error ("error unregistering battery: battery is null" ); +return false; + } +DBG ("path = %s" , battery->path);if (!queue_find (batteries,NULL , battery)) {
@@ -227,6 +385,11 @@ bool btd_battery_unregister(struct btd_battery *battery)bool btd_battery_update (struct btd_battery *battery,uint8_t percentage) { +if (!battery) { +error ("error updating battery: battery is null" ); +return false; + } +DBG ("path = %s" , battery->path);if (!queue_find (batteries,NULL , battery)) {
@@ -234,7 +397,7 @@ bool btd_battery_update(struct btd_battery *battery, uint8_t percentage)return false; } -if (percentage >BATTERY_MAX_PERCENTAGE ) { +if (percentage >BATTERY_MAX_PERCENTAGE && percentage !=UINT8_MAX ) {error ("error updating battery: percentage is not valid" );return false; }
@@ -242,16 +405,76 @@ bool btd_battery_update(struct btd_battery *battery, uint8_t percentage)if (battery->percentage == percentage)return true; - battery->percentage =bt_battery_charge (battery->filter, percentage); +if (percentage ==UINT8_MAX ) { + battery->percentage = percentage; +bt_battery_free (battery->filter); +free (battery->filter); + battery->filter =bt_battery_new (); + }else { + battery->percentage =bt_battery_charge (battery->filter, + percentage); + } +g_dbus_emit_property_changed (btd_get_dbus_connection (), battery->path,BATTERY_INTERFACE ,"Percentage" );return true; } -static struct btd_battery *find_battery_by_path (const char *path) +bool btd_battery_update_charging (struct btd_battery *battery,int charging) { -return queue_find (batteries, match_path, path); +if (!battery) { +error ("error updating battery: battery is null" ); +return false; + } + +DBG ("path = %s" , battery->path); + +if (!queue_find (batteries,NULL , battery)) { +error ("error updating battery: battery is not registered" ); +return false; + } + +if (charging <-1 || charging >1 ) { +error ("error updating battery: charging state is not valid" ); +return false; + } + +if (battery->charging == charging) +return true; + + battery->charging = charging; +g_dbus_emit_property_changed (btd_get_dbus_connection (), battery->path, +BATTERY_INTERFACE ,"Charging" ); + +return true; +} + +struct provider_battery_match { +struct battery_provider *provider; +const char *object_path; +}; + +static bool match_provider_battery (const void *data,const void *user_data) +{ +const struct btd_battery *battery = data; +const struct provider_battery_match *match = user_data; + +return battery->provider == match->provider && +g_strcmp0 (battery->provider_object_path, + match->object_path) ==0 ; +} + +static struct btd_battery *find_provider_battery ( +struct battery_provider *provider, +const char *object_path) +{ +struct provider_battery_match match = { + .provider = provider, + .object_path = object_path, + }; + +return queue_find (batteries, match_provider_battery, &match); } static void provided_battery_property_changed_cb(GDBusProxy *proxy,
@@ -259,29 +482,51 @@ static void provided_battery_property_changed_cb(GDBusProxy *proxy, DBusMessageIter *iter, void *user_data) { -uint8_t percentage =0 ; -const char *export_path; -DBusMessageIter dev_iter; +struct btd_battery *battery; +struct battery_provider *provider = user_data; +const char *path =g_dbus_proxy_get_path (proxy); -if (g_dbus_proxy_get_property (proxy,"Device" , &dev_iter) == FALSE) + battery =find_provider_battery (provider, path); +if (!battery)return ; -dbus_message_iter_get_basic (&dev_iter, &export_path); +if (!strcmp (name,"Percentage" )) { +uint8_t percentage =UINT8_MAX ; + +if (iter) { +if (dbus_message_iter_get_arg_type (iter) != +DBUS_TYPE_BYTE ) +return ; + +dbus_message_iter_get_basic (iter, &percentage); + } -if (strcmp (name,"Percentage" ) !=0 ) +DBG ("battery percentage changed on %s, percentage = %d" , path, + percentage); +btd_battery_update (battery, percentage);return ; + } + +if (!strcmp (name,"Charging" )) { +dbus_bool_t value; +int charging =-1 ; -if (iter) { -if (dbus_message_iter_get_arg_type (iter) !=DBUS_TYPE_BYTE ) +if (!(g_dbus_get_flags () &G_DBUS_FLAG_ENABLE_EXPERIMENTAL ))return ; -dbus_message_iter_get_basic (iter, &percentage); - } +if (iter) { +if (dbus_message_iter_get_arg_type (iter) != +DBUS_TYPE_BOOLEAN ) +return ; -DBG ("battery percentage changed on %s, percentage = %d" , -g_dbus_proxy_get_path (proxy), percentage); +dbus_message_iter_get_basic (iter, &value); + charging = value; + } -btd_battery_update (find_battery_by_path (export_path), percentage); +DBG ("battery charging changed on %s, charging = %d" , path, + charging); +btd_battery_update_charging (battery, charging); + } }static void provided_battery_added_cb (GDBusProxy *proxy,void *user_data)
@@ -290,10 +535,13 @@ static void provided_battery_added_cb(GDBusProxy *proxy, void *user_data)struct btd_battery *battery;struct btd_device *device;const char *path =g_dbus_proxy_get_path (proxy); -const char *export_path; +const char *device_path; +const char *identifier =NULL ;const char *source =NULL ;uint8_t percentage; +dbus_bool_t charging;DBusMessageIter iter; +bool experimental;if (strcmp (g_dbus_proxy_get_interface (proxy),BATTERY_PROVIDER_INTERFACE ) !=0 )
@@ -304,68 +552,105 @@ static void provided_battery_added_cb(GDBusProxy *proxy, void *user_data)return ; } -dbus_message_iter_get_basic (&iter, &export_path); +if (dbus_message_iter_get_arg_type (&iter) !=DBUS_TYPE_OBJECT_PATH ) { +warn ("Battery object %s has an invalid device path" , path); +return ; + } + +dbus_message_iter_get_basic (&iter, &device_path); device =btd_adapter_find_device_by_path (provider->manager->adapter, - export_path); + device_path);if (!device ||device_is_temporary (device)) {warn ("Ignoring non-existent device path for battery %s" , - export_path); + device_path);return ; } -if (find_battery_by_path (export_path)) { -DBG ("Battery for %s is already provided, ignoring the new one" , - export_path); + experimental =g_dbus_get_flags () &G_DBUS_FLAG_ENABLE_EXPERIMENTAL ; + +if (g_dbus_proxy_get_property (proxy,"Identifier" , &iter) == TRUE) { +if (dbus_message_iter_get_arg_type (&iter) !=DBUS_TYPE_STRING ) { +warn ("Battery object %s has an invalid identifier" , + path); +return ; + } + +dbus_message_iter_get_basic (&iter, &identifier); +if (!identifier[0 ]) { +warn ("Battery object %s has an empty identifier" , path); +return ; + } + +if (!experimental) { +warn ("Ignoring experimental component battery %s" , + path); +return ; + } + } + +if (g_dbus_proxy_get_property (proxy,"Source" , &iter) == TRUE && +dbus_message_iter_get_arg_type (&iter) == +DBUS_TYPE_STRING ) +dbus_message_iter_get_basic (&iter, &source); + +if (identifier) { + battery =battery_register_component (device_path, identifier, + source, provider->path, + path, provider); + }else { + battery =battery_register (device_path,NULL ,NULL , source, + provider->path, path, provider); + } + +if (!battery) { +warn ("Unable to add battery object %s for %s" , path, + device_path);return ; }g_dbus_proxy_set_property_watch ( proxy, provided_battery_property_changed_cb, provider); -if (g_dbus_proxy_get_property (proxy,"Source" , &iter) == TRUE) -dbus_message_iter_get_basic (&iter, &source); - - battery =btd_battery_register (export_path, source, provider->path); -DBG ("provided battery added %s" , path);/* Percentage property may not be immediately available, that's okay * since we monitor changes to this property. */ -if (g_dbus_proxy_get_property (proxy,"Percentage" , &iter) == FALSE) -return ; - -dbus_message_iter_get_basic (&iter, &percentage); +if (g_dbus_proxy_get_property (proxy,"Percentage" , &iter) == TRUE && +dbus_message_iter_get_arg_type (&iter) == +DBUS_TYPE_BYTE ) { +dbus_message_iter_get_basic (&iter, &percentage); +btd_battery_update (battery, percentage); + } -btd_battery_update (battery, percentage); +if (experimental) { +if (g_dbus_proxy_get_property (proxy,"Charging" , + &iter) == TRUE && +dbus_message_iter_get_arg_type (&iter) == +DBUS_TYPE_BOOLEAN ) { +dbus_message_iter_get_basic (&iter, &charging); +btd_battery_update_charging (battery, charging); + } + } }static void provided_battery_removed_cb (GDBusProxy *proxy,void *user_data) {struct battery_provider *provider = user_data;struct btd_battery *battery; -const char *export_path; -DBusMessageIter iter; +const char *path =g_dbus_proxy_get_path (proxy);if (strcmp (g_dbus_proxy_get_interface (proxy),BATTERY_PROVIDER_INTERFACE ) !=0 )return ; -if (g_dbus_proxy_get_property (proxy,"Device" , &iter) == FALSE) -return ; +DBG ("provided battery removed %s" , path); -dbus_message_iter_get_basic (&iter, &export_path); - -DBG ("provided battery removed %s" ,g_dbus_proxy_get_path (proxy)); - - battery =find_battery_by_path (export_path); + battery =find_provider_battery (provider, path);if (!battery)return ; -if (g_strcmp0 (battery->provider_path, provider->path) !=0 ) -return ; -g_dbus_proxy_set_property_watch (proxy,NULL ,NULL );btd_battery_unregister (battery);
@@ -384,7 +669,7 @@ static void unregister_if_path_has_prefix(void *data, void *user_data)struct btd_battery *battery = data;struct battery_provider *provider = user_data; -if (g_strcmp0 (battery->provider_path, provider->path) ==0 ) +if (battery->provider == provider)btd_battery_unregister (battery); }
@@ -392,7 +677,7 @@ static void battery_provider_free(gpointer data) {struct battery_provider *provider = data; -/* Unregister batteries under the root path of provider->path */ +/* Unregister batteries registered by this provider. */ queue_foreach (batteries, unregister_if_path_has_prefix, provider);if (provider->owner)
src/battery.h +4 -0
@@ -14,8 +14,12 @@ struct btd_battery_provider_manager;struct btd_battery *btd_battery_register (const char *path,const char *source,const char *provider_path); +struct btd_battery *btd_battery_register_component (const char *device_path, +const char *identifier, +const char *source);bool btd_battery_unregister (struct btd_battery *battery);bool btd_battery_update (struct btd_battery *battery,uint8_t percentage); +bool btd_battery_update_charging (struct btd_battery *battery,int charging);struct btd_battery_provider_manager *btd_battery_provider_manager_create (struct btd_adapter *adapter);
Signature · 1 line
2.55.0
PATCH v2 2/4 doc: Document component battery objects
In reply to Matthias KurzDescribe the experimental component Battery1 properties, their opaque object paths, and how BatteryProvider1 implementations publish several batteries for one device.
--- doc/org.bluez.Battery.rst | 35 +++++++++++++++++++++++++++++-- doc/org.bluez.BatteryProvider.rst | 16 ++++++++++++++ 2 files changed, 49 insertions(+), 2 deletions(-)
doc/org.bluez.Battery.rst +33 -2
@@ -17,15 +17,27 @@ Interface :Service: org.bluez :Interface: org.bluez.Battery1 :Object path: [variable prefix]/{hci0,hci1,...}/dev_{BDADDR} + [/battery_{identifier}] + +Component battery objects are experimental. Their object paths are +implementation details and shall be treated as opaque. Clients shall use the +``Device`` and ``Identifier`` properties to associate a component with its +parent device and its stable identity. + +For diagnostic purposes, ASCII letters and digits in the identifier are kept +in the object path. Every other byte is encoded as an underscore followed by +two lowercase hexadecimal digits. Properties ---------- -byte Percentage [readonly] -`````````````````````````` +byte Percentage [readonly, optional] +```````````````````````````````````` The percentage of battery left as an unsigned 8-bit integer. +The property is absent while the battery level is unknown. + string Source [readonly, optional] ``````````````````````````````````
@@ -36,3 +48,22 @@ This property is informational only and may be useful for debugging purposes. Providers from **org.bluez.BatteryProvider(5)** may make use of this property to indicate where the battery report comes from (e.g. "HFP 1.7", "HID", or the profile UUID). + +object Device [readonly, optional, experimental] +```````````````````````````````````````````````````````````` + +The object path of the device containing this battery. + +This property is present on component battery objects below the device object. + +string Identifier [readonly, optional, experimental] +```````````````````````````````````````````````````````````` + +A stable identifier for this battery within the device, such as ``left``, +``right``, or ``case``. + +boolean Charging [readonly, optional, experimental] +```````````````````````````````````````````````````````````` + +Indicates whether this battery is currently charging. The property is absent +while the charging state is unknown.
doc/org.bluez.BatteryProvider.rst +16 -0
@@ -30,3 +30,19 @@ object Device [readonly] ```````````````````````` The object path of the device that has this battery. + +string Identifier [readonly, optional, experimental] +```````````````````````````````````````````````````````````` + +A non-empty identifier that is unique among the batteries for this device. +Multiple batteries may refer to the same device when each provides a unique +identifier. They are reflected as component **org.bluez.Battery1** objects. + +A provider object without this property represents the legacy aggregate +battery and is reflected directly on the device object. + +boolean Charging [readonly, optional, experimental] +```````````````````````````````````````````````````````````` + +Indicates whether this battery is currently charging. The property is absent +while the charging state is unknown.
Signature · 1 line
2.55.0
PATCH v2 3/4 fastpair: Add Message Stream battery profile
In reply to Matthias KurzConnect to the experimental Fast Pair Message Stream service advertised by compatible BR/EDR devices and parse its 16-bit-length framed messages.
The Message Stream specification defines a fixed endpoint UUID over RFCOMM and a separate L2CAP PSM transport. This implementation supports the RFCOMM variant; L2CAP support is left for future work:
https://developers.google.com/nearby/fast-pair/specifications/extensions/messagestream
Publish left, right, and case values as component Battery1 objects. The Device Information extension defines the battery update message. Its three component bytes use the Battery Notification encoding:
https://developers.google.com/nearby/fast-pair/specifications/extensions/deviceinformation
https://developers.google.com/nearby/fast-pair/specifications/extensions/batterynotification
Include unknown percentage and charging-state transitions. Decode unknown levels using the generic Battery Notification status bit while treating the TWS-specific case value 0xff as unavailable, as required for hearables:
If only the Message Stream is lost, invalidate its values and reconnect. Use exponential backoff and reset it only after a battery-producing stream remains stable. Remove the objects once the BR/EDR bearer disappears.
Keep pending connection callbacks alive through cancellation and ignore callbacks for detached or superseded channels.
--- .gitignore | 1 + Makefile.am | 8 + Makefile.plugins | 5 + doc/test-coverage.txt | 3 +- profiles/fastpair/fastpair.c | 650 +++++++++++++++++++++++++++++ profiles/fastpair/message-stream.c | 135 ++++++ profiles/fastpair/message-stream.h | 58 +++ unit/test-fastpair.c | 322 ++++++++++++++ 8 files changed, 1181 insertions(+), 1 deletion(-) create mode 100644 profiles/fastpair/fastpair.c create mode 100644 profiles/fastpair/message-stream.c create mode 100644 profiles/fastpair/message-stream.h create mode 100644 unit/test-fastpair.c
.gitignore +1 -0
@@ -116,6 +116,7 @@ unit/test-hog unit/test-bap unit/test-bass unit/test-battery +unit/test-fastpair unit/test-tmap unit/test-gmap unit/test-mcp
Makefile.am +8 -0
@@ -799,6 +799,14 @@ unit_test_battery_SOURCES = unit/test-battery.c unit_test_battery_LDADD = src/libshared-glib.la \ lib/libbluetooth-internal.la $(GLIB_LIBS) +unit_tests += unit/test-fastpair + +unit_test_fastpair_SOURCES = unit/test-fastpair.c \ + profiles/fastpair/message-stream.h \ + profiles/fastpair/message-stream.c +unit_test_fastpair_LDADD = src/libshared-glib.la \ + lib/libbluetooth-internal.la $(GLIB_LIBS) + unit_tests += unit/test-rap unit_test_rap_SOURCES = unit/test-rap.c $(btio_sources)
Makefile.plugins +5 -0
@@ -88,6 +88,11 @@ endif builtin_modules += battery builtin_sources += profiles/battery/battery.c +builtin_modules += fastpair +builtin_sources += profiles/fastpair/fastpair.c \ + profiles/fastpair/message-stream.h \ + profiles/fastpair/message-stream.c + builtin_modules += rap builtin_sources += profiles/ranging/rap.c \ profiles/ranging/rap_hci.c
doc/test-coverage.txt +2 -1
@@ -31,8 +31,9 @@ test-gdbus-client 13 D-Bus client handling test-gatt 180 GATT qualification test cases test-hog 6 HID Over GATT qualification test cases test-battery 10 Battery charge test cases +test-fastpair 7 Fast Pair Message Stream parsing ----- - 771 + 778 Automated end-to-end testing
profiles/fastpair/fastpair.c new file +650 -0
650 lines not on this page · raw message
profiles/fastpair/message-stream.c new file +135 -0
135 lines not on this page · raw message
profiles/fastpair/message-stream.h new file +58 -0
58 lines not on this page · raw message
unit/test-fastpair.c new file +322 -0
322 lines not on this page · raw message
Signature · 1 line
2.55.0
PATCH v2 4/4 test: Add Fast Pair Message Stream tool
In reply to Matthias KurzAdd a standalone profile client that prints Fast Pair Message Stream frames and can optionally publish left, right, and case values through BatteryProvider1.
Publish dynamic component lifecycle signals, scope providers per adapter, and invalidate measurements when a stream closes. Warn users to disable the built-in Fast Pair plugin when using the external profile.
--- Makefile.tools | 2 +- test/test-fastpair | 568 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 569 insertions(+), 1 deletion(-) create mode 100755 test/test-fastpair
Makefile.tools +1 -1
@@ -552,7 +552,7 @@ test_scripts += test/bluezutils.py \ test/test-discovery test/test-manager test/test-adapter \ test/test-device test/simple-agent \ test/simple-endpoint \ - test/test-network test/test-profile \ + test/test-network test/test-profile test/test-fastpair \ test/service-record.dtd \ test/service-did.xml test/service-spp.xml test/service-opp.xml \ test/service-ftp.xml test/simple-player test/test-nap \
test/test-fastpair new file +568 -0
568 lines not on this page · raw message
Signature · 1 line
2.55.0
This is automated email and please do not reply to this email!
Dear submitter,
Thank you for submitting the patches to the linux bluetooth mailing list. This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=1149924
---Test result---
Test Summary:
CheckPatch FAIL 3.10 seconds GitLint PASS 1.34 seconds BuildEll PASS 21.53 seconds BluezMake PASS 626.39 seconds MakeCheck PASS 19.77 seconds MakeDistcheck PASS 165.13 seconds CheckValgrind PASS 236.59 seconds CheckSmatch PASS 320.33 seconds bluezmakeextell PASS 103.89 seconds IncrementalBuild PASS 669.66 seconds ScanBuild PASS 1035.62 seconds
Details
##############################
Test: CheckPatch - FAIL
Desc: Run checkpatch.pl script
Output:
[BlueZ,v2,1/4] battery: Add component battery objects WARNING:BAD_SIGN_OFF: Non-standard signature: Assisted-by:
#114:
ERROR:BAD_SIGN_OFF: Unrecognized email address: 'Codex:gpt-5.6-sol' #114:
/github/workspace/src/patch/14762094.patch total: 1 errors, 1 warnings, 575 lines checked
NOTE: For some of the reported defects, checkpatch may be able to
mechanically convert to the typical style using --fix or --fix-inplace.
/github/workspace/src/patch/14762094.patch has style problems, please review.
NOTE: Ignored message types: COMMIT_MESSAGE COMPLEX_MACRO CONST_STRUCT FILE_PATH_CHANGES MISSING_SIGN_OFF PREFER_PACKED SPDX_LICENSE_TAG SPLIT_STRING SSCANF_TO_KSTRTO
NOTE: If any of the errors are false positives, please report
them to the maintainer, see CHECKPATCH in MAINTAINERS.
[BlueZ,v2,2/4] doc: Document component battery objects WARNING:BAD_SIGN_OFF: Non-standard signature: Assisted-by:
#107:
ERROR:BAD_SIGN_OFF: Unrecognized email address: 'Codex:gpt-5.6-sol' #107:
/github/workspace/src/patch/14762093.patch total: 1 errors, 1 warnings, 70 lines checked
NOTE: For some of the reported defects, checkpatch may be able to
mechanically convert to the typical style using --fix or --fix-inplace.
/github/workspace/src/patch/14762093.patch has style problems, please review.
NOTE: Ignored message types: COMMIT_MESSAGE COMPLEX_MACRO CONST_STRUCT FILE_PATH_CHANGES MISSING_SIGN_OFF PREFER_PACKED SPDX_LICENSE_TAG SPLIT_STRING SSCANF_TO_KSTRTO
NOTE: If any of the errors are false positives, please report
them to the maintainer, see CHECKPATCH in MAINTAINERS.
[BlueZ,v2,3/4] fastpair: Add Message Stream battery profile WARNING:COMMIT_LOG_LONG_LINE: Possible unwrapped commit description (prefer a maximum 75 chars per line) #110:
https://developers.google.com/nearby/fast-pair/specifications/extensions/messagestream
WARNING:BAD_SIGN_OFF: Non-standard signature: Assisted-by:
#132:
ERROR:BAD_SIGN_OFF: Unrecognized email address: 'Codex:gpt-5.6-sol' #132:
/github/workspace/src/patch/14762096.patch total: 1 errors, 2 warnings, 1207 lines checked
NOTE: For some of the reported defects, checkpatch may be able to
mechanically convert to the typical style using --fix or --fix-inplace.
/github/workspace/src/patch/14762096.patch has style problems, please review.
NOTE: Ignored message types: COMMIT_MESSAGE COMPLEX_MACRO CONST_STRUCT FILE_PATH_CHANGES MISSING_SIGN_OFF PREFER_PACKED SPDX_LICENSE_TAG SPLIT_STRING SSCANF_TO_KSTRTO
NOTE: If any of the errors are false positives, please report
them to the maintainer, see CHECKPATCH in MAINTAINERS.
[BlueZ,v2,4/4] test: Add Fast Pair Message Stream tool WARNING:BAD_SIGN_OFF: Non-standard signature: Assisted-by:
#111:
ERROR:BAD_SIGN_OFF: Unrecognized email address: 'Codex:gpt-5.6-sol' #111:
ERROR:EXECUTE_PERMISSIONS: do not set execute permissions for source files #132: FILE: test/test-fastpair
/github/workspace/src/patch/14762095.patch total: 2 errors, 1 warnings, 576 lines checked
NOTE: For some of the reported defects, checkpatch may be able to
mechanically convert to the typical style using --fix or --fix-inplace.
/github/workspace/src/patch/14762095.patch has style problems, please review.
NOTE: Ignored message types: COMMIT_MESSAGE COMPLEX_MACRO CONST_STRUCT FILE_PATH_CHANGES MISSING_SIGN_OFF PREFER_PACKED SPDX_LICENSE_TAG SPLIT_STRING SSCANF_TO_KSTRTO
NOTE: If any of the errors are false positives, please report
them to the maintainer, see CHECKPATCH in MAINTAINERS.
https://github.com/bluez/bluez/pull/2428
---
Regards,
Linux Bluetooth
Hi,
A gentle ping on this v2 series. It addresses the feedback on v1 and was tested end-to-end with Pixel Buds Pro through UPower and KDE Plasma.
Would you have time to take another look? Please let me know if I should change or split anything to make the series easier to review.
Regards,
Matthias
Luiz Augusto von Dentz
maintainerHi Matthias,
Quoted 8 lines · Matthias Kurz
Hi,
A gentle ping on this v2 series. It addresses the feedback on v1 and was tested end-to-end with Pixel Buds Pro through UPower and KDE Plasma.
Would you have time to take another look? Please let me know if I should change or split anything to make the series easier to review.
A full review may take a while since this is a large set. I'll move the unit-testable part to src/shared/fastpair.{c,h} though and have it as a separate commit. Regarding the test ID check, if Google doesn't have a set o test cases it performs for certification, we can mimic those as unit tests.
Btw, these device would only use fastpair to expose their batteries or it does expose them as well via AT command? In fact it looks like HFP 1.8 has introduced support for battery indicator:
So I'm not sure we should go with the proprietary Google FastPair, which is probably only really meant for Android, unless it is the only source. Also, are you going to be available to maintain this code or is this a one-time effort just to get it working for your device? Im probably not interested in maintaining proprietary protocols at the stack, so maybe this should be pushed back to some other layer that uses RegisterProfile and just registers batteries from an external entity. That way, what we would be left to do is just to support multiple batteries per device.
Signature · 1 line
Luiz Augusto von Dentz
Hi Luiz,
Thanks for taking a look.
I captured the HFP negotiation with the Pixel Buds Pro. The session negotiates the standard HF Indicator 2 (Battery Level), and the buds send:
AT+BIEV=2,93
The existing stack publishes this through a single Battery1 interface on the Device1 path. The standard HFP battery indicator has no component identifier, so it cannot distinguish the left bud, right bud, and case. The Fast Pair Device Information message is the only source I have observed for those three separate values.
Although Fast Pair is Google-specific, the relevant Message Stream and battery wire formats are publicly documented. The battery path works after ordinary Bluetooth pairing; it does not use Google's account-based pairing flow or a cloud service.
I am willing to maintain the Fast Pair code long-term and follow up on bugs, review feedback, and protocol changes.
If the Fast Pair plugin remains in BlueZ, I will move the unit-testable parser to src/shared/fastpair.{c,h} as a separate commit. Google publishes wire-format examples and certification guidance containing applicable battery scenarios, but I have not found a public protocol-level parser-vector suite. I can mirror the published examples and applicable certification cases in the unit tests.
The complete path has been tested with real Pixel Buds Pro through BlueZ, UPower, and KDE Plasma. The related downstream work is here:
UPower:
https://gitlab.freedesktop.org/mkurz/upower/-/commits/fastpair-multi-battery
Solid:
https://invent.kde.org/frameworks/solid/-/merge_requests/264
PowerDevil:
https://invent.kde.org/plasma/powerdevil/-/merge_requests/666
To reduce the review size, I can split the next revision into a core multiple-battery Battery1/BatteryProvider1 series and a separate Fast Pair RFC while we decide where the latter belongs.
If Fast Pair should live outside BlueZ, is there an existing component you have in mind? PipeWire's BlueZ backend already uses the external Profile1 and BatteryProvider1 interfaces, but a vendor-specific, non-audio battery protocol may also be outside its scope. Otherwise, would you expect this to become a new standalone daemon?
The external architecture is viable: test/test-fastpair already demonstrates using RegisterProfile together with BatteryProvider1.
Would that split be your preferred direction?
Regards,
Matthias
Hi Luiz, hi Bastien,
A short update on the downstream support: the UPower implementation is now available for review as a Draft MR:
https://gitlab.freedesktop.org/upower/upower/-/merge_requests/344
It consumes the proposed component Battery1 API, independently of whether the component data comes from a built-in profile or an external battery provider. It remains Draft while the BlueZ API is under review, and retains support for ordinary single-battery reporting from unmodified BlueZ.
I also retested the current branches today with real Pixel Buds Pro, checking BlueZ and UPower readings alongside KDE Plasma's battery and Bluetooth widgets. This covered a real case percentage, its transition to Unknown, earbud charging-state changes, remote disconnect cleanup, and reconnect at the same object paths without duplicate entries.
The MR includes integration tests and details of the compatibility behavior and hardware validation. Hopefully this provides useful downstream context for reviewing the generic component-battery API while the placement of the Fast Pair implementation is still discussed.
Regards,
Matthias
This is automated email and please do not reply to this email!
Dear submitter,
Thank you for submitting the patches to the linux bluetooth mailing list. This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/series/1149924/
---Test result---
Test Summary:
CheckPatch FAIL 2.91 seconds GitLint PASS 1.07 seconds BuildEll PASS 21.83 seconds BluezMake PASS 389.14 seconds MakeCheck PASS 14.12 seconds MakeDistcheck PASS 141.75 seconds CheckValgrind PASS 233.56 seconds CheckSmatch PASS 293.14 seconds bluezmakeextell PASS 95.25 seconds IncrementalBuild PASS 434.52 seconds ScanBuild PASS 1140.05 seconds
Details
##############################
Test: CheckPatch - FAIL
Desc: Run checkpatch.pl script
Output:
[BlueZ,v2,4/4] test: Add Fast Pair Message Stream tool ERROR:EXECUTE_PERMISSIONS: do not set execute permissions for source files #132: FILE: test/test-fastpair
/github/workspace/src/patch/14762095.patch total: 1 errors, 0 warnings, 576 lines checked
NOTE: For some of the reported defects, checkpatch may be able to
mechanically convert to the typical style using --fix or --fix-inplace.
/github/workspace/src/patch/14762095.patch has style problems, please review.
NOTE: Ignored message types: COMMIT_MESSAGE COMPLEX_MACRO CONST_STRUCT FILE_PATH_CHANGES MISSING_SIGN_OFF PREFER_PACKED SPDX_LICENSE_TAG SPLIT_STRING SSCANF_TO_KSTRTO
NOTE: If any of the errors are false positives, please report
them to the maintainer, see CHECKPATCH in MAINTAINERS.
https://github.com/bluez/bluez/pull/2515
---
Regards,
Linux Bluetooth
This series was applied to bluetooth/bluez.git (master) by Luiz Augusto von Dentz <[email protected]>:
Hello:
This series was applied to bluetooth/bluez.git (master) by Luiz Augusto von Dentz <[email protected]>:
Quoted 5 lines · On Fri, 21 Aug 2026 18:07:59 +0200 you wrote:
True wireless earbuds can report separate charge states for the left bud, right bud, and charging case. Battery1 currently has one fixed object per Device1, so BlueZ cannot expose those values without collapsing them into one percentage.
Quoted 7 lines
Extend the battery core and provider API to support child Battery1 objects with a stable identifier, optional percentage, and optional charging state. The existing Battery1 object at the Device1 path remains the aggregate compatibility interface. Component objects and their new properties remain experimental.
[...]
Here is the summary with links:
- [BlueZ,v2,1/4] battery: Add component battery objects
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=e977e8042755 - [BlueZ,v2,2/4] doc: Document component battery objects https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=1f0812f0b47e - [BlueZ,v2,3/4] fastpair: Add Message Stream battery profile https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=738a389928f6 - [BlueZ,v2,4/4] test: Add Fast Pair Message Stream tool https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=e7963702fb3d
You are awesome, thank you!
Signature · 2 lines
Deet-doot-dot, I am a bot. https://korg.docs.kernel.org/patchwork/pwbot.html