Skip to contentSkip to conversation

Propagate disconnection reason

PATCH Superseded Frédéric Danis 3 participants 8 messages May 20, 2025 – May 21, 2025 1 message not in the archive Bluetooth drivers

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

v2 cover Propagate disconnection reason

Currently a client application is informed of the disconnection by the update of the Connected property to false.
This sends a Disconnected signal with the disconnection reason before the property is updated.

This will help client application to know the reason for the disconnection and to take appropriate action.

bluetoothctl is updated to display the disconnection reason on reception of the signal.

This can be tested in bluetoothctl by disconnecting a device, which generates:
[SIGNAL] org.bluez.Device1.Disconnected disconnection-local-host

v1->v2: Propagate numerical reason instead of text one
Improve documentation
Display disconnect reason in numerical and text in bluetoothctl

Frédéric Danis (3):
src/device: Add Disconnected signal to propagate disconnection reason doc/device: Add Disconnected signal
client: Display disconnection reason

 client/main.c            | 40 ++++++++++++++++++++++++++++++++++
 doc/org.bluez.Device.rst | 47 ++++++++++++++++++++++++++++++++++++++++
 src/adapter.c            | 13 ++++++-----
 src/device.c             | 16 ++++++++++++--
 src/device.h             |  3 ++-
 5 files changed, 111 insertions(+), 8 deletions(-)
Signature · 1 line
2.43.0
#1 lore raw

PATCH v2 1/3 src/device: Add Disconnected signal to propagate disconnection reason

Currently a client application is informed of the disconnection by the update of the Connected property to false.
This sends a Disconnected signal with the disconnection reason before the property is updated.

This helps client application to know the reason for the disconnection and to take appropriate action.
---
v1->v2: Propagate numerical reason instead of text one

 src/adapter.c | 13 ++++++++-----
 src/device.c  | 16 ++++++++++++++--
 src/device.h  |  3 ++-
 3 files changed, 24 insertions(+), 8 deletions(-)
src/adapter.c +8 -5
index fd425e6d2..a10721489 100644
@@ -7549,7 +7549,8 @@ struct agent *adapter_get_agent(struct btd_adapter *adapter)
 
 static void adapter_remove_connection(struct btd_adapter *adapter,
 						struct btd_device *device,
-						uint8_t bdaddr_type)
+						uint8_t bdaddr_type,
+						uint8_t reason)
 {
 	bool remove_device = false;
 
@@ -7560,7 +7561,7 @@ static void adapter_remove_connection(struct btd_adapter *adapter,
 		return;
 	}
 
-	device_remove_connection(device, bdaddr_type, &remove_device);
+	device_remove_connection(device, bdaddr_type, &remove_device, reason);
 
 	device_cancel_authentication(device, TRUE);
 
@@ -7601,9 +7602,11 @@ static void adapter_stop(struct btd_adapter *adapter)
 		struct btd_device *device = adapter->connections->data;
 		uint8_t addr_type = btd_device_get_bdaddr_type(device);
 
-		adapter_remove_connection(adapter, device, BDADDR_BREDR);
+		adapter_remove_connection(adapter, device, BDADDR_BREDR,
+						MGMT_DEV_DISCONN_UNKNOWN);
 		if (addr_type != BDADDR_BREDR)
-			adapter_remove_connection(adapter, device, addr_type);
+			adapter_remove_connection(adapter, device, addr_type,
+						MGMT_DEV_DISCONN_UNKNOWN);
 	}
 
 	g_dbus_emit_property_changed(dbus_conn, adapter->path,
@@ -8551,7 +8554,7 @@ static void dev_disconnected(struct btd_adapter *adapter,
 
 	device = btd_adapter_find_device(adapter, &addr->bdaddr, addr->type);
 	if (device) {
-		adapter_remove_connection(adapter, device, addr->type);
+		adapter_remove_connection(adapter, device, addr->type, reason);
 		disconnect_notify(device, reason);
 	}
 
src/device.c +14 -2
index d230af0a8..00a0fbfc7 100644
@@ -3417,6 +3417,12 @@ static const GDBusMethodTable device_methods[] = {
 	{ }
 };
 
+static const GDBusSignalTable device_signals[] = {
+	{ GDBUS_SIGNAL("Disconnected",
+			GDBUS_ARGS({ "reason", "y" })) },
+	{ }
+};
+
 static gboolean
 dev_property_get_prefer_bearer(const GDBusPropertyTable *property,
 				DBusMessageIter *iter, void *data)
@@ -3638,7 +3644,8 @@ static void set_temporary_timer(struct btd_device *dev, unsigned int timeout)
 }
 
 void device_remove_connection(struct btd_device *device, uint8_t bdaddr_type,
-								bool *remove)
+								bool *remove,
+								uint8_t reason)
 {
 	struct bearer_state *state = get_state(device, bdaddr_type);
 	DBusMessage *reply;
@@ -3708,6 +3715,11 @@ void device_remove_connection(struct btd_device *device, uint8_t bdaddr_type,
 	g_slist_free_full(device->eir_uuids, g_free);
 	device->eir_uuids = NULL;
 
+	g_dbus_emit_signal(dbus_conn, device->path, DEVICE_INTERFACE,
+						"Disconnected",
+						DBUS_TYPE_BYTE, &reason,
+						DBUS_TYPE_INVALID);
+
 	g_dbus_emit_property_changed(dbus_conn, device->path,
 						DEVICE_INTERFACE, "Connected");
 
@@ -4611,7 +4623,7 @@ static struct btd_device *device_new(struct btd_adapter *adapter,
 
 	if (g_dbus_register_interface(dbus_conn,
 					device->path, DEVICE_INTERFACE,
-					device_methods, NULL,
+					device_methods, device_signals,
 					device_properties, device,
 					device_free) == FALSE) {
 		error("Unable to register device interface for %s", address);
src/device.h +2 -1
index a35bb1386..4eebcebe9 100644
@@ -134,7 +134,8 @@ gboolean device_is_authenticating(struct btd_device *device);
 void device_add_connection(struct btd_device *dev, uint8_t bdaddr_type,
 							uint32_t flags);
 void device_remove_connection(struct btd_device *device, uint8_t bdaddr_type,
-								bool *remove);
+							bool *remove,
+							uint8_t reason);
 void device_request_disconnect(struct btd_device *device, DBusMessage *msg);
 bool device_is_disconnecting(struct btd_device *device);
 void device_set_ltk(struct btd_device *device, const uint8_t val[16],
Signature · 1 line
2.43.0
#2 lore raw

Re: [PATCH BlueZ v2 1/3] src/device: Add Disconnected signal to propagate disconnection reason

Hi Frédéric,

Quoted 67 lines · Frédéric Danis

Currently a client application is informed of the disconnection by the update of the Connected property to false.
This sends a Disconnected signal with the disconnection reason before the property is updated.

This helps client application to know the reason for the disconnection and to take appropriate action.
---
v1->v2: Propagate numerical reason instead of text one

 src/adapter.c | 13 ++++++++-----
 src/device.c  | 16 ++++++++++++++--
 src/device.h  |  3 ++-
 3 files changed, 24 insertions(+), 8 deletions(-)
src/adapter.c +8 -5
index fd425e6d2..a10721489 100644
@@ -7549,7 +7549,8 @@ struct agent *adapter_get_agent(struct btd_adapter *adapter)
 
 static void adapter_remove_connection(struct btd_adapter *adapter,
                                                struct btd_device *device,
-                                               uint8_t bdaddr_type)
+                                               uint8_t bdaddr_type,
+                                               uint8_t reason)
 {
        bool remove_device = false;
 
@@ -7560,7 +7561,7 @@ static void adapter_remove_connection(struct btd_adapter *adapter,
                return;
        }
 
-       device_remove_connection(device, bdaddr_type, &remove_device);
+       device_remove_connection(device, bdaddr_type, &remove_device, reason);
 
        device_cancel_authentication(device, TRUE);
 
@@ -7601,9 +7602,11 @@ static void adapter_stop(struct btd_adapter *adapter)
                struct btd_device *device = adapter->connections->data;
                uint8_t addr_type = btd_device_get_bdaddr_type(device);
 
-               adapter_remove_connection(adapter, device, BDADDR_BREDR);
+               adapter_remove_connection(adapter, device, BDADDR_BREDR,
+                                               MGMT_DEV_DISCONN_UNKNOWN);
                if (addr_type != BDADDR_BREDR)
-                       adapter_remove_connection(adapter, device, addr_type);
+                       adapter_remove_connection(adapter, device, addr_type,
+                                               MGMT_DEV_DISCONN_UNKNOWN);
        }
 
        g_dbus_emit_property_changed(dbus_conn, adapter->path,
@@ -8551,7 +8554,7 @@ static void dev_disconnected(struct btd_adapter *adapter,
 
        device = btd_adapter_find_device(adapter, &addr->bdaddr, addr->type);
        if (device) {
-               adapter_remove_connection(adapter, device, addr->type);
+               adapter_remove_connection(adapter, device, addr->type, reason);
                disconnect_notify(device, reason);
        }
 
src/device.c +0 -0
index d230af0a8..00a0fbfc7 100644

src/device.c static const GDBusMethodTable device_methods[] = { · line 3422

Quoted 6 lines
src/device.c +3 -0
@@ -3417,6 +3417,12 @@ static const GDBusMethodTable device_methods[] = {
        { }
 };
 
+static const GDBusSignalTable device_signals[] = {
+       { GDBUS_SIGNAL("Disconnected",
+                       GDBUS_ARGS({ "reason", "y" })) },

Ive changed my mind regarding this, this should actually have the same format as Device.Connect error reply, so we use the same domain of errors org.bluez.Error.{Name} followed by its message.

Quoted 55 lines
src/device.c +11 -2
+       { }
+};
+
 static gboolean
 dev_property_get_prefer_bearer(const GDBusPropertyTable *property,
                                DBusMessageIter *iter, void *data)
@@ -3638,7 +3644,8 @@ static void set_temporary_timer(struct btd_device *dev, unsigned int timeout)
 }
 
 void device_remove_connection(struct btd_device *device, uint8_t bdaddr_type,
-                                                               bool *remove)
+                                                               bool *remove,
+                                                               uint8_t reason)
 {
        struct bearer_state *state = get_state(device, bdaddr_type);
        DBusMessage *reply;
@@ -3708,6 +3715,11 @@ void device_remove_connection(struct btd_device *device, uint8_t bdaddr_type,
        g_slist_free_full(device->eir_uuids, g_free);
        device->eir_uuids = NULL;
 
+       g_dbus_emit_signal(dbus_conn, device->path, DEVICE_INTERFACE,
+                                               "Disconnected",
+                                               DBUS_TYPE_BYTE, &reason,
+                                               DBUS_TYPE_INVALID);
+
        g_dbus_emit_property_changed(dbus_conn, device->path,
                                                DEVICE_INTERFACE, "Connected");
 
@@ -4611,7 +4623,7 @@ static struct btd_device *device_new(struct btd_adapter *adapter,
 
        if (g_dbus_register_interface(dbus_conn,
                                        device->path, DEVICE_INTERFACE,
-                                       device_methods, NULL,
+                                       device_methods, device_signals,
                                        device_properties, device,
                                        device_free) == FALSE) {
                error("Unable to register device interface for %s", address);
src/device.h +2 -2
index a35bb1386..4eebcebe9 100644
@@ -134,7 +134,8 @@ gboolean device_is_authenticating(struct btd_device *device);
 void device_add_connection(struct btd_device *dev, uint8_t bdaddr_type,
                                                        uint32_t flags);
 void device_remove_connection(struct btd_device *device, uint8_t bdaddr_type,
-                                                               bool *remove);
+                                                       bool *remove,
+                                                       uint8_t reason);
 void device_request_disconnect(struct btd_device *device, DBusMessage *msg);
 bool device_is_disconnecting(struct btd_device *device);
 void device_set_ltk(struct btd_device *device, const uint8_t val[16],
--

2.43.0

Signature · 1 line
Luiz Augusto von Dentz
#3 lore raw

Re: [PATCH BlueZ v2 1/3] src/device: Add Disconnected signal to propagate disconnection reason

Hi Luiz,

Quoted 73 lines · Luiz Augusto von Dentz

Hi Frédéric,

Quoted 69 lines · Frédéric Danis

Currently a client application is informed of the disconnection by the update of the Connected property to false.
This sends a Disconnected signal with the disconnection reason before the property is updated.

This helps client application to know the reason for the disconnection and to take appropriate action.
---
v1->v2: Propagate numerical reason instead of text one

  src/adapter.c | 13 ++++++++-----
  src/device.c  | 16 ++++++++++++++--
  src/device.h  |  3 ++-
  3 files changed, 24 insertions(+), 8 deletions(-)
src/adapter.c +8 -5
index fd425e6d2..a10721489 100644
@@ -7549,7 +7549,8 @@ struct agent *adapter_get_agent(struct btd_adapter *adapter)
 
  static void adapter_remove_connection(struct btd_adapter *adapter,
                                                 struct btd_device *device,
-                                               uint8_t bdaddr_type)
+                                               uint8_t bdaddr_type,
+                                               uint8_t reason)
  {
         bool remove_device = false;
 
@@ -7560,7 +7561,7 @@ static void adapter_remove_connection(struct btd_adapter *adapter,
                 return;
         }
 
-       device_remove_connection(device, bdaddr_type, &remove_device);
+       device_remove_connection(device, bdaddr_type, &remove_device, reason);
 
         device_cancel_authentication(device, TRUE);
 
@@ -7601,9 +7602,11 @@ static void adapter_stop(struct btd_adapter *adapter)
                 struct btd_device *device = adapter->connections->data;
                 uint8_t addr_type = btd_device_get_bdaddr_type(device);
 
-               adapter_remove_connection(adapter, device, BDADDR_BREDR);
+               adapter_remove_connection(adapter, device, BDADDR_BREDR,
+                                               MGMT_DEV_DISCONN_UNKNOWN);
                 if (addr_type != BDADDR_BREDR)
-                       adapter_remove_connection(adapter, device, addr_type);
+                       adapter_remove_connection(adapter, device, addr_type,
+                                               MGMT_DEV_DISCONN_UNKNOWN);
         }
 
         g_dbus_emit_property_changed(dbus_conn, adapter->path,
@@ -8551,7 +8554,7 @@ static void dev_disconnected(struct btd_adapter *adapter,
 
         device = btd_adapter_find_device(adapter, &addr->bdaddr, addr->type);
         if (device) {
-               adapter_remove_connection(adapter, device, addr->type);
+               adapter_remove_connection(adapter, device, addr->type, reason);
                 disconnect_notify(device, reason);
         }
 
src/device.c +0 -0
index d230af0a8..00a0fbfc7 100644
@@ -3417,6 +3417,12 @@ static const GDBusMethodTable device_methods[] = {
         { }
  };
 
Quoted 6 lines

src/device.c static const GDBusMethodTable device_methods[] = { · line 3422

Quoted 3 lines
src/device.c +3 -0
+static const GDBusSignalTable device_signals[] = {
+       { GDBUS_SIGNAL("Disconnected",
+                       GDBUS_ARGS({ "reason", "y" })) },

Ive changed my mind regarding this, this should actually have the same format as Device.Connect error reply, so we use the same domain of errors org.bluez.Error.{Name} followed by its message.

I'm not sure to understand this point as some of the possible reason are not errors like MGMT_DEV_DISCONN_LOCAL_HOST or MGMT_DEV_DISCONN_REMOTE, and so org.bluez.Error.{Name} seems inappropriate to me here.

To be more similar to other methods, the Disconnected signal may provide the reason as text and numerical value, which can be useful in case of 'disconnection-unknown' text.

Signature · 6 lines
Frédéric Danis
Senior Software Engineer

Collabora Ltd.
Platinum Building, St John's Innovation Park, Cambridge CB4 0DS, United Kingdom
Registered in England & Wales, no. 5513718

A message that is not in the archive (sent off-list or not yet received): [email protected]

#5 lore raw

Re: [PATCH BlueZ v2 1/3] src/device: Add Disconnected signal to propagate disconnection reason

Hi Frédéric,

Quoted 87 lines · Frédéric Danis

Hi Luiz,

On 20/05/2025 18:41, Luiz Augusto von Dentz wrote:

Hi Frédéric,

On Tue, May 20, 2025 at 12:26 PM Frédéric Danis
<[email protected]> wrote:

Currently a client application is informed of the disconnection by the update of the Connected property to false.
This sends a Disconnected signal with the disconnection reason before the property is updated.

This helps client application to know the reason for the disconnection and to take appropriate action.
---
v1->v2: Propagate numerical reason instead of text one

 src/adapter.c | 13 ++++++++-----
 src/device.c  | 16 ++++++++++++++--
 src/device.h  |  3 ++-
 3 files changed, 24 insertions(+), 8 deletions(-)
src/adapter.c +8 -5
index fd425e6d2..a10721489 100644
@@ -7549,7 +7549,8 @@ struct agent *adapter_get_agent(struct btd_adapter *adapter)
 
 static void adapter_remove_connection(struct btd_adapter *adapter,
                                                struct btd_device *device,
-                                               uint8_t bdaddr_type)
+                                               uint8_t bdaddr_type,
+                                               uint8_t reason)
 {
        bool remove_device = false;
 
@@ -7560,7 +7561,7 @@ static void adapter_remove_connection(struct btd_adapter *adapter,
                return;
        }
 
-       device_remove_connection(device, bdaddr_type, &remove_device);
+       device_remove_connection(device, bdaddr_type, &remove_device, reason);
 
        device_cancel_authentication(device, TRUE);
 
@@ -7601,9 +7602,11 @@ static void adapter_stop(struct btd_adapter *adapter)
                struct btd_device *device = adapter->connections->data;
                uint8_t addr_type = btd_device_get_bdaddr_type(device);
 
-               adapter_remove_connection(adapter, device, BDADDR_BREDR);
+               adapter_remove_connection(adapter, device, BDADDR_BREDR,
+                                               MGMT_DEV_DISCONN_UNKNOWN);
                if (addr_type != BDADDR_BREDR)
-                       adapter_remove_connection(adapter, device, addr_type);
+                       adapter_remove_connection(adapter, device, addr_type,
+                                               MGMT_DEV_DISCONN_UNKNOWN);
        }
 
        g_dbus_emit_property_changed(dbus_conn, adapter->path,
@@ -8551,7 +8554,7 @@ static void dev_disconnected(struct btd_adapter *adapter,
 
        device = btd_adapter_find_device(adapter, &addr->bdaddr, addr->type);
        if (device) {
-               adapter_remove_connection(adapter, device, addr->type);
+               adapter_remove_connection(adapter, device, addr->type, reason);
                disconnect_notify(device, reason);
        }
 
src/device.c +3 -0
index d230af0a8..00a0fbfc7 100644
@@ -3417,6 +3417,12 @@ static const GDBusMethodTable device_methods[] = {
        { }
 };
 
+static const GDBusSignalTable device_signals[] = {
+       { GDBUS_SIGNAL("Disconnected",
+                       GDBUS_ARGS({ "reason", "y" })) },
 

Ive changed my mind regarding this, this should actually have the same format as Device.Connect error reply, so we use the same domain of errors org.bluez.Error.{Name} followed by its message.

Quoted 3 lines

I'm not sure to understand this point as some of the possible reason are not errors like MGMT_DEV_DISCONN_LOCAL_HOST or MGMT_DEV_DISCONN_REMOTE, and so org.bluez.Error.{Name} seems inappropriate to me here.

We can do something like org.bluez.Error.None for these, or use a different domain like org.bluez.Reason.Local, that still is a fixed string that client can match, rather than a free format string, note that sometimes an error can cause a clean disconnect but in that case we want to capture the error not the disconnect reason.

Quoted 2 lines

To be more similar to other methods, the Disconnected signal may provide the reason as text and numerical value, which can be useful in case of 'disconnection-unknown' text.

But we are already masking the numerical reason, besides for D-Bus it sort of makes more sense to use a domain name to describe errors.

Signature · 1 line
Luiz Augusto von Dentz
#6 lore raw
In reply to Frédéric Danis

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=964653

---Test result---

Test Summary:

CheckPatch                    PENDING   0.27 seconds
GitLint                       PENDING   0.28 seconds
BuildEll                      PASS      19.94 seconds
BluezMake                     PASS      2553.76 seconds
MakeCheck                     PASS      20.74 seconds
MakeDistcheck                 PASS      199.00 seconds
CheckValgrind                 PASS      275.54 seconds
CheckSmatch                   PASS      300.86 seconds
bluezmakeextell               PASS      127.42 seconds
IncrementalBuild              PENDING   0.22 seconds
ScanBuild                     PASS      896.76 seconds

Details
##############################
Test: CheckPatch - PENDING
Desc: Run checkpatch.pl script
Output:

##############################
Test: GitLint - PENDING
Desc: Run gitlint
Output:

##############################
Test: IncrementalBuild - PENDING
Desc: Incremental build with the patches in the series Output:

---
Regards,
Linux Bluetooth

#7 lore raw

PATCH v2 2/3 doc/device: Add Disconnected signal

In reply to Frédéric Danis

---
v1->v2: Replace text reason by numerical reason
Improve documentation

 doc/org.bluez.Device.rst | 47 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
doc/org.bluez.Device.rst +47 -0
index 80501eddd..771b7613f 100644
@@ -155,6 +155,53 @@ array{array{byte}} GetServiceRecords() [experimental]
 	:org.bluez.Error.NotConnected:
 	:org.bluez.Error.DoesNotExist:
 
+Signals
+-------
+
+void Disconnected(byte reason)
+````````````````````````````````
+
+	This signal is launched when a device is disconnected, with the reason of
+	the disconnection.
+
+	This could be used by client application, depending on internal policy, to
+	try to reconnect to the device in case of timeout or unknown disconnection,
+	or to try to connect to another device.
+
+	Possible reasons:
+
+	:0:
+		Unknown.
+
+	:1:
+		Timeout.
+
+		The link supervision timeout has expired for a connection or the
+		synchronization timeout has expired for a broadcast.
+
+	:2:
+		Disconnected from local host.
+
+		The local device terminated the connection, terminated synchronization
+		with a broadcaster, or terminated broadcasting packets.
+
+	:3:
+		Disconnected from remote.
+
+		This disconnection can be due to:
+			- the user on the remote device either terminated the connection
+			  or stopped broadcasting packets,
+			- the remote device terminated the connection because of low
+			  resources,
+			- the remote device terminated the connection because the device
+			  is about to power off.
+
+	:4:
+		Authentication failure.
+
+	:5:
+		Local host suspend.
+
 Properties
 ----------
 
Signature · 1 line
2.43.0
#8 lore raw

PATCH v2 3/3 client: Display disconnection reason

In reply to Frédéric Danis

The new org.bluez.Device1.Disconnected signal propagates the disconnection reason.
---
v1->v2: Display disconnect reason in numerical and text

 client/main.c | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)
client/main.c +40 -0
index 57d71f2b6..274d02c9e 100644
@@ -706,9 +706,49 @@ static void property_changed(GDBusProxy *proxy, const char *name,
 	}
 }
 
+static const char *disconnect_reason(uint8_t reason)
+{
+	switch (reason) {
+	case 0:
+		return "unknown";
+	case 1:
+		return "timeout";
+	case 2:
+		return "local host";
+	case 3:
+		return "remote";
+	case 4:
+		return "authentication failure";
+	case 5:
+		return "local suspend";
+	default:
+		return "unknown value";
+	}
+}
+
 static void message_handler(DBusConnection *connection,
 					DBusMessage *message, void *user_data)
 {
+	if (!strcmp(dbus_message_get_member(message), "Disconnected")) {
+		DBusMessageIter iter;
+		u_int8_t reason;
+
+		if (!dbus_message_iter_init(message, &iter))
+			goto failed;
+
+		if (dbus_message_iter_get_arg_type(&iter) != DBUS_TYPE_BYTE)
+			goto failed;
+
+		dbus_message_iter_get_basic(&iter, &reason);
+
+		bt_shell_printf("[SIGNAL] %s.%s %u (%s)\n",
+					dbus_message_get_interface(message),
+					dbus_message_get_member(message),
+					reason, disconnect_reason(reason));
+		return;
+	}
+
+failed:
 	bt_shell_printf("[SIGNAL] %s.%s\n", dbus_message_get_interface(message),
 					dbus_message_get_member(message));
 }
Signature · 1 line
2.43.0