esc: clarify RPM/command direction meaning

Reverse should only be used for reverse thrust, not simply a motor that happens to be spinning counter-clockwise.
dronecan · Jan 24, 2025 · 3bcb345 · 3bcb345
1 parent 30d02e1
commit 3bcb345
Show file tree

Hide file tree

Showing 3 changed files with 10 additions and 4 deletions.
diff --git a/uavcan/equipment/esc/1030.RawCommand.uavcan b/uavcan/equipment/esc/1030.RawCommand.uavcan
@@ -1,7 +1,9 @@
 #
-# Raw ESC command normalized into [-8192, 8191]; negative values indicate reverse rotation.
-# The ESC should normalize the setpoint into its effective input range.
+# Raw ESC command normalized into [-8192, 8191]. The ESC should normalize the setpoint into its effective input range.
 # Non-zero setpoint value below minimum should be interpreted as min valid setpoint for the given motor.
+# Positive values indicate forward rotation, negative values indicate reverse rotation, and zero indicates no rotation.
+# Forward rotation shall be the direction causing forward thrust. For example, a typical quadcopter always commands
+# non-negative values for all four motors, independent of ESC configuration, motor wiring, or propeller direction.
 #
 
 int14[<=20] cmd
diff --git a/uavcan/equipment/esc/1031.RPMCommand.uavcan b/uavcan/equipment/esc/1031.RPMCommand.uavcan
@@ -2,7 +2,9 @@
 # Simple RPM setpoint.
 # The ESC should automatically clamp the setpoint according to the minimum and maximum supported RPM;
 # for example, given a ESC that operates in the range 100 to 10000 RPM, a setpoint of 1 RPM will be clamped to 100 RPM.
-# Negative values indicate reverse rotation.
+# Positive values indicate forward rotation, negative values indicate reverse rotation, and zero indicates no rotation.
+# Forward rotation shall be the direction causing forward thrust. For example, a typical quadcopter always sets
+# non-negative values for all four motors, independent of ESC configuration, motor wiring, or propeller direction.
 #
 
 int18[<=20] rpm
diff --git a/uavcan/equipment/esc/1034.Status.uavcan b/uavcan/equipment/esc/1034.Status.uavcan
@@ -9,7 +9,9 @@ float16 voltage             # Volt
 float16 current             # Ampere. Can be negative in case of a regenerative braking.
 float16 temperature         # Kelvin
 
-int18 rpm                   # Negative value indicates reverse rotation
+int18 rpm                   # Current value, with the same sign convention as RPMCommand. For example, a typical
+                            # quadcopter reports non-negative values for all four motors, independent of ESC
+                            # configuration, motor wiring, or propeller direction.
 
 uint7 power_rating_pct      # Instant demand factor in percent (percent of maximum power); range 0% to 127%.