api/common: add torque limit setter

Also document units of torque

doc/api/signaltypes.rst

@@ -172,7 +172,7 @@ the light is off and 100% when the light is fully on. When you choose 50%, this
 means that the light is perceived as approximately half as bright to the human
 eye.
 
-Force
+Force and torque
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. _force:
@@ -194,6 +194,12 @@ following table to convert to and from other units.
 | 1 lbf = | 4448 | 4.448 | 1                           |
 +---------+------+-------+-----------------------------+
 
+.. _torque:
+
+torque: mNm
+------------
+Torque values are expressed in millinewtonmeter (mNm) unless stated otherwise.
+
 Electricity
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

pybricks/_common.py

@@ -54,8 +54,8 @@ class Control:
             motor this is the number of encoder pulses per degree of rotation.
     """
 
-    def limits(self, speed, acceleration, actuation):
-        """Configures the maximum speed, acceleration, and actuation.
+    def limits(self, speed, acceleration, duty, torque):
+        """Configures the maximum speed, acceleration, duty, and torque.
 
         If no arguments are given, this will return the current values.
 
@@ -64,8 +64,10 @@ class Control:
                 Maximum speed. All speed commands will be capped to this value.
             acceleration (:ref:`acceleration` or :ref:`linacceleration`):
                 Maximum acceleration.
-            actuation (:ref:`percentage`):
-                Maximum actuation as percentage of absolute maximum.
+            duty (:ref:`percentage`):
+                Maximum duty cycle during control.
+            torque (:ref:`torque`):
+                Maximum feedback torque during control.
         """
         pass
 
@@ -75,11 +77,14 @@ class Control:
         If no arguments are given, this will return the current values.
 
         Arguments:
-            kp (int): Proportional position (or integral speed) control
-                constant.
-            ki (int): Integral position control constant.
+            kp (int): Proportional position control
+                constant. It is the feedback torque per degree of
+                error: µNm/deg.
+            ki (int): Integral position control constant. It is the feedback
+                torque per accumulated degree of error: µNm/(deg s).
             kd (int): Derivative position (or proportional speed) control
-                constant.
+                constant. It is the feedback torque per
+                unit of speed: µNm/(deg/s).
             integral_range (:ref:`angle` or :ref:`distance`): Region around
                 the target angle or distance, in which integral control errors
                 are accumulated.