pbio/main: Wait for Bluetooth end at pbio.

Other than safely freeing allocated memory, application code shouldn't have to
worry about deinitializing the Bluetooth driver, so move it towards the pbio
layer. Disconnecting from peripherals at the end is not unlike stopping motors etc.

Author: laurensvalk

bricks/_common/micropython.c

@@ -314,7 +314,7 @@ static void run_user_program(void) {
             // The global scope is preserved to facilitate debugging, but we
             // stop active resources like motors and sounds. They are stopped
             // but not reset so the user can restart them in the REPL.
-            pbio_stop_all(false);
+            pbio_main_soft_stop();
 
             // Enter REPL.
             run_repl();
@@ -420,9 +420,10 @@ void pbsys_main_run_program(pbsys_main_program_t *program) {
             run_user_program();
             break;
     }
+}
+
+void pbsys_main_run_program_cleanup(void) {
 
-    // De-init bluetooth resources (including flushing stdout) that may use
-    // memory allocated by MicroPython before we wipe it.
     pb_package_pybricks_deinit();
 
     gc_sweep_all();

lib/pbio/drv/bluetooth/bluetooth.c

@@ -296,7 +296,12 @@ pbio_error_t pbdrv_bluetooth_await_peripheral_command(pbio_os_state_t *state, vo
     // of interest and will be cancelled if the active function supports it.
     pbio_os_timer_set(&peri->watchdog, 10);
 
-    return peripheral_singleton.func ? peripheral_singleton.err : PBIO_SUCCESS;
+    return peri->func ? peri->err : PBIO_SUCCESS;
+}
+
+void pbdrv_bluetooth_cancel_operation_request(void) {
+    // Only some peripheral actions support cancellation.
+    peripheral_singleton.cancel = true;
 }
 
 //

lib/pbio/include/pbdrv/bluetooth.h

@@ -421,6 +421,15 @@ pbio_error_t pbdrv_bluetooth_peripheral_write_characteristic(uint16_t handle, co
  */
 pbio_error_t pbdrv_bluetooth_await_peripheral_command(pbio_os_state_t *state, void *context);
 
+/**
+ * Requests active Bluetooth tasks to be cancelled. It is up to the task
+ * implementation to respect or ignore it. The task should still be awaited
+ * with ::pbdrv_bluetooth_await_advertise_or_scan_command or
+ * with ::pbdrv_bluetooth_await_peripheral_command. Cancelling just allows
+ * some commands to exit earlier.
+ */
+void pbdrv_bluetooth_cancel_operation_request(void);
+
 //
 // Functions related to advertising and scanning.
 //
@@ -565,6 +574,9 @@ static inline pbio_error_t pbdrv_bluetooth_await_peripheral_command(pbio_os_stat
     return PBIO_ERROR_NOT_SUPPORTED;
 }
 
+static inline void pbdrv_bluetooth_cancel_operation_request(void) {
+}
+
 static inline pbio_error_t pbdrv_bluetooth_start_advertising(bool start) {
     return PBIO_ERROR_NOT_SUPPORTED;
 }

lib/pbio/include/pbio/main.h

@@ -10,6 +10,7 @@
 
 void pbio_init(bool start_processes);
 void pbio_deinit(void);
-void pbio_stop_all(bool reset);
+void pbio_main_stop_application_resources();
+void pbio_main_soft_stop(void);
 
 #endif // _PBIO_MAIN_H_

lib/pbio/include/pbsys/main.h

@@ -110,6 +110,15 @@ pbio_error_t pbsys_main_program_validate(pbsys_main_program_t *program);
  */
 void pbsys_main_run_program(pbsys_main_program_t *program);
 
+/**
+ * Cleans up after running main application program, such as wiping application
+ * heap.
+ *
+ * This is separate from ::pbsys_main_run_program so that the system can
+ * safely close resources and unset callbacks before this cleanup runs.
+ */
+void pbsys_main_run_program_cleanup(void);
+
 /**
  * Stops (cancels) the main application program.
  *

lib/pbio/src/main.c

@@ -8,9 +8,12 @@
 
 #include <stdbool.h>
 
+#include <pbdrv/bluetooth.h>
+#include <pbdrv/display.h>
 #include <pbdrv/sound.h>
 
 #include <pbio/battery.h>
+#include <pbio/image.h>
 #include <pbio/imu.h>
 #include <pbio/motor_process.h>
 #include <pbio/port_interface.h>
@@ -51,26 +54,62 @@ void pbio_deinit(void) {
 }
 
 /**
- * Stops all user-level background processes. Called when the user application
- * completes to get these modules back into their default state. Drivers and
- * OS-level processes continue running.
+ * Stops resources like motors or sounds or peripheral procedures that take a
+ * long time.
  *
- * @param [in]  reset  Whether to reset all user-level processes to a clean
- *                     state (true), or whether to only stop active outputs
- *                     like sound or motors (false). The latter is useful to
- *                     preserve the state for debugging, without sound or
- *                     movement getting in the way, or out of control.
+ * Useful to get the system in a safe state for the user without doing a full
+ * reset. Applications can all this to enter a user debug mode like the
+ * MicroPython REPL.
  */
-void pbio_stop_all(bool reset) {
-    #if PBIO_CONFIG_LIGHT
-    if (reset) {
-        pbio_light_animation_stop_all();
-    }
-    #endif
+void pbio_main_soft_stop(void) {
 
-    pbio_port_stop_user_actions(reset);
+    pbio_port_stop_user_actions(false);
 
     pbdrv_sound_stop();
+
+    pbdrv_bluetooth_cancel_operation_request();
+}
+
+static void wait_for_bluetooth(void) {
+    pbio_os_state_t unused;
+    while (pbdrv_bluetooth_await_advertise_or_scan_command(&unused, NULL) == PBIO_ERROR_AGAIN ||
+           pbdrv_bluetooth_await_peripheral_command(&unused, NULL) == PBIO_ERROR_AGAIN) {
+
+        // Run event loop until Bluetooth is idle.
+        pbio_os_run_processes_and_wait_for_event();
+    }
+}
+
+/**
+ * Stops all application-level background processes. Called when the user
+ * application completes to get these modules back into their default state.
+ * Drivers and OS-level processes continue running.
+ */
+void pbio_main_stop_application_resources() {
+
+    pbio_main_soft_stop();
+
+    // Let ongoing task finish first.
+    wait_for_bluetooth();
+
+    // Stop broadcasting, observing and disconnect peripheral.
+    pbdrv_bluetooth_start_broadcasting(NULL, 0);
+    wait_for_bluetooth();
+
+    pbdrv_bluetooth_start_observing(NULL);
+    wait_for_bluetooth();
+
+    pbdrv_bluetooth_peripheral_disconnect();
+    wait_for_bluetooth();
+
+    #if PBIO_CONFIG_LIGHT
+    pbio_light_animation_stop_all();
+    #endif
+
+    #if PBDRV_CONFIG_DISPLAY
+    pbio_image_fill(pbdrv_display_get_image(), 0);
+    pbdrv_display_update();
+    #endif
 }
 
 /** @} */

lib/pbio/sys/light_matrix.c

@@ -153,28 +153,21 @@ static uint32_t pbsys_hub_light_matrix_user_program_animation_next(pbio_light_an
 }
 
 /**
- * Updates light matrix behavior when program is started or stopped.
- *
- * @param start   @c true for start or @c false for stop.
+ * Updates light matrix behavior when program is started.
  */
-void pbsys_hub_light_matrix_handle_user_program_start(bool start) {
+void pbsys_hub_light_matrix_handle_user_program_start(void) {
 
     #if PBSYS_CONFIG_HUB_LIGHT_MATRIX_DISPLAY
     pbio_image_fill(pbdrv_display_get_image(), 0);
     pbdrv_display_update();
     return;
     #endif
 
-    if (start) {
-        // The user animation updates only a subset of pixels to save time,
-        // so the rest must be cleared before it starts.
-        pbsys_hub_light_matrix_user_program_animation_clear();
-        pbio_light_animation_init(&pbsys_hub_light_matrix->animation, pbsys_hub_light_matrix_user_program_animation_next);
-        pbio_light_animation_start(&pbsys_hub_light_matrix->animation);
-    } else {
-        // If the user program has ended, show stop sign and selected slot.
-        pbsys_hub_light_matrix_show_idle_ui(100);
-    }
+    // The user animation updates only a subset of pixels to save time,
+    // so the rest must be cleared before it starts.
+    pbsys_hub_light_matrix_user_program_animation_clear();
+    pbio_light_animation_init(&pbsys_hub_light_matrix->animation, pbsys_hub_light_matrix_user_program_animation_next);
+    pbio_light_animation_start(&pbsys_hub_light_matrix->animation);
 }
 
 #endif // PBSYS_CONFIG_HUB_LIGHT_MATRIX

lib/pbio/sys/light_matrix.h

@@ -11,12 +11,12 @@
 #if PBSYS_CONFIG_HUB_LIGHT_MATRIX
 void pbsys_hub_light_matrix_init(void);
 void pbsys_hub_light_matrix_deinit(void);
-void pbsys_hub_light_matrix_handle_user_program_start(bool start);
+void pbsys_hub_light_matrix_handle_user_program_start(void);
 void pbsys_hub_light_matrix_update_program_slot(void);
 #else
 #define pbsys_hub_light_matrix_init()
 #define pbsys_hub_light_matrix_deinit()
-#define pbsys_hub_light_matrix_handle_user_program_start(start)
+#define pbsys_hub_light_matrix_handle_user_program_start()
 #define pbsys_hub_light_matrix_update_program_slot()
 #endif
 

lib/pbio/sys/main.c

@@ -102,7 +102,7 @@ int main(int argc, char **argv) {
         pbsys_status_set_program_id(program.id);
         pbsys_status_set(PBIO_PYBRICKS_STATUS_USER_PROGRAM_RUNNING);
         pbsys_host_stdin_set_callback(pbsys_main_stdin_event);
-        pbsys_hub_light_matrix_handle_user_program_start(true);
+        pbsys_hub_light_matrix_handle_user_program_start();
 
         #if PBSYS_CONFIG_STATUS_LIGHT
         #if PBSYS_CONFIG_STATUS_LIGHT_STATE_ANIMATIONS
@@ -123,18 +123,22 @@ int main(int argc, char **argv) {
         // Run the main application.
         pbsys_main_run_program(&program);
 
+        // Stop motors, user animations, user bluetooth activity, etc.
+        pbio_main_stop_application_resources();
+
         // Get system back in idle state.
         pbsys_status_clear(PBIO_PYBRICKS_STATUS_USER_PROGRAM_RUNNING);
         pbsys_host_stdin_set_callback(NULL);
         pbsys_program_stop_set_buttons(PBIO_BUTTON_CENTER);
-        pbsys_hub_light_matrix_handle_user_program_start(false);
-        pbio_stop_all(true);
         program.start_request_type = PBSYS_MAIN_PROGRAM_START_REQUEST_TYPE_NONE;
 
         // Handle pending events triggered by the status change, such as
         // stopping status light animation.
         while (pbio_os_run_processes_once()) {
         }
+
+        // Finalize application now that system resources are safely closed.
+        pbsys_main_run_program_cleanup();
     }
 
     // Stop system processes and selected drivers in reverse order. This will

pybricks/common/pb_type_ble.c

@@ -577,26 +577,8 @@ mp_obj_t pb_type_BLE_new(mp_obj_t broadcast_channel_in, mp_obj_t observe_channel
     return MP_OBJ_FROM_PTR(self);
 }
 
-static void wait_for_bluetooth(void) {
-    pbio_os_state_t state;
-    while (pbdrv_bluetooth_await_advertise_or_scan_command(&state, NULL) == PBIO_ERROR_AGAIN) {
-        MICROPY_VM_HOOK_LOOP;
-
-        // Stop waiting (and potentially blocking) in case of forced shutdown.
-        if (pbsys_status_test(PBIO_PYBRICKS_STATUS_SHUTDOWN_REQUEST)) {
-            break;
-        }
-    }
-}
-
 void pb_type_ble_start_cleanup(void) {
 
-    wait_for_bluetooth();
-    pbdrv_bluetooth_start_broadcasting(NULL, 0);
-    wait_for_bluetooth();
-    pbdrv_bluetooth_start_observing(NULL);
-    wait_for_bluetooth();
-
     observed_data = NULL;
     num_observed_data = 0;
 }