pbio/protocol: Don't add new program start command.

Add optional payload to existing command instead.
pybricks · Sep 2, 2024 · f41537c · f41537c
1 parent 67a1bfd
commit f41537c
Show file tree

Hide file tree

Showing 3 changed files with 28 additions and 41 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,10 +13,8 @@
   correction of the `hub.imu.heading()` value ([support#1678]).
 - Added `update_heading_correction` to interactively set the heading
   correction value ([support#1678]).
-- Added command to start downloaded or builtin user program with a one byte
-  program identifier. The existing START_PROGRAM and START_REPL are special
-  cases of this new more generic command, but will remain available for
-  backwards compatibility. For now, this is added to start various builtin
+- Added optional one byte program identifier to program start command.
+  For now, this is added to start various builtin
   programs, but it prepares for the ability to start different downloaded
   programs too  ([pybricks-micropython#254]).
 - Added one byte program identifier to the hub status report to the host.

diff --git a/lib/pbio/include/pbio/protocol.h b/lib/pbio/include/pbio/protocol.h
@@ -85,26 +85,36 @@ typedef enum {
     PBIO_PYBRICKS_COMMAND_STOP_USER_PROGRAM = 0,
 
     /**
-     * Requests that the user program should be started.
+     * Requests that a user program should be started.
+     *
+     * The optional payload parameter was added in Pybricks Profile v1.4.0.
+     *
+     * Parameters:
+     * - payload: Optional program identifier (one byte). Slots 0--127 are
+     *            reserved for downloaded user programs. Slots 128--255 are
+     *            for builtin user programs. If no program identifier is
+     *            given, the currently active program slot will be started.
+     *
+     * Errors:
+     * - ::PBIO_PYBRICKS_ERROR_BUSY if another program is already running.
+     * - ::PBIO_PYBRICKS_ERROR_INVALID_COMMAND if the requested program is not available (since Pybricks Profile v1.4.0.)
      *
      * Errors:
      * - ::PBIO_PYBRICKS_ERROR_BUSY if another program is already running.
      *
      * @since Pybricks Profile v1.2.0
-     * @deprecated in Pybricks Profile v1.4.0.
-     *   Use ::PBIO_PYBRICKS_COMMAND_START_USER_OR_BUILTIN_PROGRAM instead.
      */
     PBIO_PYBRICKS_COMMAND_START_USER_PROGRAM = 1,
 
     /**
-     * Requests that the REPL should be started.
+     * Requests that the REPL should be started. This is the same as sending
+     * ::PBIO_PYBRICKS_COMMAND_START_USER_PROGRAM with payload ::PBIO_PYBRICKS_USER_PROGRAM_ID_REPL.
      *
      * Errors:
      * - ::PBIO_PYBRICKS_ERROR_BUSY if another program is already running.
+     * - ::PBIO_PYBRICKS_ERROR_INVALID_COMMAND if the REPL program is not available.
      *
      * @since Pybricks Profile v1.2.0
-     * @deprecated in Pybricks Profile v1.4.0.
-     *   Use ::PBIO_PYBRICKS_COMMAND_START_USER_OR_BUILTIN_PROGRAM instead.
      */
     PBIO_PYBRICKS_COMMAND_START_REPL = 2,
 
@@ -183,23 +193,6 @@ typedef enum {
      * @since Pybricks Profile v1.4.0
      */
     PBIO_PYBRICKS_COMMAND_WRITE_APP_DATA = 7,
-
-    /**
-     * Requests that a previously downloaded user program or builtin user
-     * program is started.
-     *
-     * Parameters:
-     * - payload: Program identifier (one byte). Slots 0--127 are reserved for
-     *            downloaded user programs. Slots 128--255 are for builtin user
-     *            programs.
-     *
-     * Errors:
-     * - ::PBIO_PYBRICKS_ERROR_BUSY if another program is already running.
-     * - ::PBIO_PYBRICKS_ERROR_INVALID_COMMAND if the requested program is not available.
-     *
-     * @since Pybricks Profile v1.4.0.
-     */
-    PBIO_PYBRICKS_COMMAND_START_USER_OR_BUILTIN_PROGRAM = 8,
 } pbio_pybricks_command_t;
 /**
  * Application-specific error codes that are used in ATT_ERROR_RSP.

diff --git a/lib/pbio/sys/command.c b/lib/pbio/sys/command.c
@@ -42,12 +42,17 @@ pbio_pybricks_error_t pbsys_command(const uint8_t *data, uint32_t size) {
             pbsys_program_stop(false);
             return PBIO_PYBRICKS_ERROR_OK;
 
-        case PBIO_PYBRICKS_COMMAND_START_USER_PROGRAM:
-            // Deprecated. For backwards compatibility with Pybricks
-            // Profile < v1.4.0, assume we should start user program 0.
+        case PBIO_PYBRICKS_COMMAND_START_USER_PROGRAM: {
+            if (size > 2) {
+                return PBIO_PYBRICKS_ERROR_VALUE_NOT_ALLOWED;
+            }
+            pbio_pybricks_user_program_id_t program_id = PBIO_PYBRICKS_USER_PROGRAM_ID_FIRST_SLOT;
+            if (size == 2) {
+                program_id = data[1];
+            }
             return pbio_pybricks_error_from_pbio_error(
-                pbsys_main_program_request_start(PBIO_PYBRICKS_USER_PROGRAM_ID_FIRST_SLOT));
-
+                pbsys_main_program_request_start(program_id));
+        }
         #if PBSYS_CONFIG_FEATURE_BUILTIN_USER_PROGRAM_REPL
         case PBIO_PYBRICKS_COMMAND_START_REPL:
             // Deprecated. For backwards compatibility with Pybricks
@@ -95,15 +100,6 @@ pbio_pybricks_error_t pbsys_command(const uint8_t *data, uint32_t size) {
             const uint8_t *data_to_write = &data[3];
             return pbio_pybricks_error_from_pbio_error(write_app_data_callback(offset, data_size, data_to_write));
         }
-
-        case PBIO_PYBRICKS_COMMAND_START_USER_OR_BUILTIN_PROGRAM:
-            // Identifier payload required
-            if (size != 2) {
-                return PBIO_PYBRICKS_ERROR_VALUE_NOT_ALLOWED;
-            }
-            return pbio_pybricks_error_from_pbio_error(
-                pbsys_main_program_request_start(data[1]));
-
         default:
             return PBIO_PYBRICKS_ERROR_INVALID_COMMAND;
     }