pbio/control: Rename load attribute to pid_average.

This is a more accurate description and avoids questionable sign
definitions.

Also add notes in pybricks.common.Control about methods deprecated in
future versions.

Author: laurensvalk

CHANGELOG.md

@@ -12,6 +12,10 @@
   catches the `SystemExit` exception ([pybricks-micropython#117]).
 - Changed `PrimeHub.display.image()` to `PrimeHub.display.icon()` and renamed
   its kwarg from `image` to `icon` ([support#409]).
+- Deprecated `Control.load()`, `Control.stalled()`, and `Control.done()`
+  methods, but they will continue to exist in the firmware until further
+  notice ([support#822]). New scripts are encouraged to use the (improved)
+  variants available directly on `Motor` objects.
 
 ### Fixed
 - Fixed connecting `Remote` on BOOST move hub ([support#793]).
@@ -23,6 +27,7 @@
 [pybricks-micropython#117]: https://github.com/pybricks/pybricks-micropython/pull/117
 [support#409]: https://github.com/pybricks/support/issues/409
 [support#793]: https://github.com/pybricks/support/issues/793
+[support#793]: https://github.com/pybricks/support/issues/822
 
 ## [3.2.0b5] - 2022-11-11
 

lib/pbio/include/pbio/control.h

@@ -130,7 +130,7 @@ typedef struct _pbio_control_t {
     /**
      * Slow moving average of the PID output, which is a measure for load.
      */
-    int32_t load;
+    int32_t pid_average;
     /**
      * Flag that says whether the controller is currently stalled.
      */
@@ -161,7 +161,6 @@ bool pbio_control_type_is_position(pbio_control_t *ctl);
 bool pbio_control_type_is_time(pbio_control_t *ctl);
 bool pbio_control_is_stalled(pbio_control_t *ctl, uint32_t *stall_duration);
 bool pbio_control_is_done(pbio_control_t *ctl);
-int32_t pbio_control_get_load(pbio_control_t *ctl);
 
 // Start new control command:
 

lib/pbio/src/control.c

@@ -172,7 +172,7 @@ void pbio_control_update(pbio_control_t *ctl, uint32_t time_now, pbio_control_st
     ctl->on_target = pbio_control_check_completion(ctl, ref->time, state, &ref_end);
 
     // Save (low-pass filtered) load for diagnostics
-    ctl->load = (ctl->load * (100 - PBIO_CONFIG_CONTROL_LOOP_TIME_MS) + torque * PBIO_CONFIG_CONTROL_LOOP_TIME_MS) / 100;
+    ctl->pid_average = (ctl->pid_average * (100 - PBIO_CONFIG_CONTROL_LOOP_TIME_MS) + torque * PBIO_CONFIG_CONTROL_LOOP_TIME_MS) / 100;
 
     // Decide actuation based on whether control is on target.
     if (!ctl->on_target) {
@@ -273,7 +273,7 @@ void pbio_control_stop(pbio_control_t *ctl) {
     ctl->type = PBIO_CONTROL_NONE;
     ctl->on_target = true;
     ctl->stalled = false;
-    ctl->load = 0;
+    ctl->pid_average = 0;
 }
 
 /**
@@ -703,16 +703,3 @@ bool pbio_control_is_stalled(pbio_control_t *ctl, uint32_t *stall_duration) {
 bool pbio_control_is_done(pbio_control_t *ctl) {
     return ctl->type == PBIO_CONTROL_NONE || ctl->on_target;
 }
-
-/**
- * Gets the load experienced by the controller.
- *
- * It is determined as a slow moving average of the PID output, which is a
- * measure for how hard the controller must work to stay on target.
- *
- * @param [in]  ctl             The control instance.
- * @return                      The approximate load (control units).
- */
-int32_t pbio_control_get_load(pbio_control_t *ctl) {
-    return ctl->type == PBIO_CONTROL_NONE ? 0 : ctl->load;
-}

pybricks/common/pb_type_control.c

@@ -231,21 +231,32 @@ STATIC mp_obj_t common_Control_trajectory(mp_obj_t self_in) {
 }
 MP_DEFINE_CONST_FUN_OBJ_1(common_Control_trajectory_obj, common_Control_trajectory);
 
+// DELETEME: This method should not be used in V3.2 or later. It may be removed
+// in a future version
 // pybricks._common.Control.done
 STATIC mp_obj_t common_Control_done(mp_obj_t self_in) {
     common_Control_obj_t *self = MP_OBJ_TO_PTR(self_in);
     return mp_obj_new_bool(pbio_control_is_done(self->control));
 }
 MP_DEFINE_CONST_FUN_OBJ_1(common_Control_done_obj, common_Control_done);
 
+// DELETEME: This method should not be used in V3.2 or later. It may be removed
+// in a future version
 // pybricks._common.Control.load
 STATIC mp_obj_t common_Control_load(mp_obj_t self_in) {
     common_Control_obj_t *self = MP_OBJ_TO_PTR(self_in);
+
+    if (!pbio_control_is_active(self->control)) {
+        return mp_obj_new_int(0);
+    }
+
     // Read currently applied PID feedback torque and return as mNm.
-    return mp_obj_new_int(pbio_control_get_load(self->control) / 1000);
+    return mp_obj_new_int(self->control->pid_average / 1000);
 }
 MP_DEFINE_CONST_FUN_OBJ_1(common_Control_load_obj, common_Control_load);
 
+// DELETEME: This method should not be used in V3.2 or later. It may be removed
+// in a future version
 // pybricks._common.Control.stalled
 STATIC mp_obj_t common_Control_stalled(mp_obj_t self_in) {
     common_Control_obj_t *self = MP_OBJ_TO_PTR(self_in);