From 3609d97c956f510ee8b6dd8ed2b8f754809161e1 Mon Sep 17 00:00:00 2001 From: Rubin Gerritsen Date: Thu, 30 May 2024 13:04:41 +0200 Subject: [PATCH] Bluetooth: Document reasons for HCI command timeouts When reading the error message: "ASSERTION_FAIL: command opcode 0x0c03 timeout with err -11" it may not be obvious what is wrong with their setup unless you are very familiar with HCI. This commit adds some more documentation to make this more obvious. Signed-off-by: Rubin Gerritsen --- subsys/bluetooth/host/hci_core.c | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/subsys/bluetooth/host/hci_core.c b/subsys/bluetooth/host/hci_core.c index 9a87a47f6db..c394c36cc8d 100644 --- a/subsys/bluetooth/host/hci_core.c +++ b/subsys/bluetooth/host/hci_core.c @@ -329,8 +329,20 @@ int bt_hci_cmd_send_sync(uint16_t opcode, struct net_buf *buf, net_buf_put(&bt_dev.cmd_tx_queue, net_buf_ref(buf)); + /* Wait for a response from the Bluetooth Controller. + * The Controller may fail to respond if: + * - It was never programmed or connected. + * - There was a fatal error. + * + * See the `BT_HCI_OP_` macros in hci_types.h or + * Core_v5.4, Vol 4, Part E, Section 5.4.1 and Section 7 + * to map the opcode to the HCI command documentation. + * Example: 0x0c03 represents HCI_Reset command. + */ err = k_sem_take(&sync_sem, HCI_CMD_TIMEOUT); - BT_ASSERT_MSG(err == 0, "command opcode 0x%04x timeout with err %d", opcode, err); + BT_ASSERT_MSG(err == 0, + "Controller unresponsive, command opcode 0x%04x timeout with err %d", + opcode, err); status = cmd(buf)->status; if (status) {