pbio/drv/bluetooth_btstack: Make peripheral scan/connect robust.

This replaces the state machine logic of the scan and connect task with placing logic synchronously in a protothread. At every stage, we can detect, report and return errors, and handle cancellation correctly.

This fixes a longstanding issue where the Xbox Controller would sometimes not pair to a SPIKE Prime Hub, even though a second attempt usually worked. Now we can catch the return codes from the security manager and re-try pairing within the task, or retry the whole task a second time. We also allow re-encryption now rather than disconnecting when this is attempted.

Extensive USB logging is added to catch issues and flow of the connection process.

Author: laurensvalk

CHANGELOG.md

@@ -33,7 +33,9 @@
 - Fixed Powered Up remote and Xbox Controller working only after the first
   connection. All of the above Remote and Xbox Controller were introduced in
   the previous beta release, so did not affect any stable release ([support#2521]).
+- Fixed Xbox Controller sometimes not working the first time ([support#1509]).
 
+[support#1509]: https://github.com/pybricks/support/issues/1509
 [support#1962]: https://github.com/pybricks/support/issues/1962
 [support#2468]: https://github.com/pybricks/support/issues/2468
 [support#2497]: https://github.com/pybricks/support/issues/2497

lib/pbio/drv/bluetooth/bluetooth.c

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// Copyright (c) 2018-2025 The Pybricks Authors
+// Copyright (c) 2018-2026 The Pybricks Authors
 
 // Common Bluetooth driver code
 
@@ -195,6 +195,11 @@ pbio_error_t pbdrv_bluetooth_peripheral_scan_and_connect(pbdrv_bluetooth_periphe
         return PBIO_ERROR_BUSY;
     }
 
+    // Must provide matchers.
+    if (!config || !config->match_adv || !config->match_adv_rsp) {
+        return PBIO_ERROR_INVALID_ARG;
+    }
+
     // Used to compare subsequent advertisements, so we should reset it.
     memset(peri->bdaddr, 0, sizeof(peri->bdaddr));
 
@@ -311,6 +316,7 @@ pbio_error_t pbdrv_bluetooth_await_peripheral_command(pbio_os_state_t *state, vo
 
 void pbdrv_bluetooth_cancel_operation_request(void) {
     // Only some peripheral actions support cancellation.
+    DEBUG_PRINT("Bluetooth operation cancel requested.\n");
     peripheral_singleton.cancel = true;
 }
 
@@ -645,6 +651,7 @@ void pbdrv_bluetooth_deinit(void) {
     // is, a task got stuck, so exit forcefully.
     if (advertising_or_scan_err == PBIO_ERROR_AGAIN || peripheral_singleton.err == PBIO_ERROR_AGAIN) {
         // Hard reset without waiting on completion of any process.
+        DEBUG_PRINT("Bluetooth deinit: forcing hard reset due to busy tasks.\n");
         pbdrv_bluetooth_controller_reset_hard();
         return;
     }