docs: uORB messages doc standard tweaks

Tools/msg/generate_msg_docs.py

@@ -17,10 +17,10 @@ VALID_FIELDS = { #Note, also have to add the message types as those can be field
     'uint32'
 }
 
-ALLOWED_UNITS = set(["m", "m/s", "m/s^2", "(m/s)^2", "deg", "deg/s", "rad", "rad/s", "rad^2", "rpm" ,"V", "A", "mA", "mAh", "W", "dBm", "h", "s", "ms", "us", "Ohm", "MB", "Kb/s", "degC","Pa","%","-"])
+ALLOWED_UNITS = set(["m", "m/s", "m/s^2", "(m/s)^2", "deg", "deg/s", "rad", "rad/s", "rad^2", "rpm" ,"V", "A", "mA", "mAh", "W", "Wh", "dBm", "h", "minutes", "s", "ms", "us", "Ohm", "MB", "Kb/s", "degC","Pa", "%", "norm", "-"])
 invalid_units = set()
-ALLOWED_FRAMES = set(["NED","Body"])
+ALLOWED_FRAMES = set(["NED", "Body", "FRD", "ENU"])
-ALLOWED_INVALID_VALUES = set(["NaN", "0"])
+ALLOWED_INVALID_VALUES = set(["NaN", "0", "-1"])
 ALLOWED_CONSTANTS_NOT_IN_ENUM = set(["ORB_QUEUE_LENGTH","MESSAGE_VERSION"])
 
 class Error:

msg/versioned/ActuatorMotors.msg

@@ -10,7 +10,7 @@ uint64 timestamp_sample  # [us] Sampling timestamp of the data this control resp
 
 uint16 reversible_flags # [-] Bitset indicating which motors are configured to be reversible
 
-uint8 ACTUATOR_FUNCTION_MOTOR1 = 101 #
+uint8 ACTUATOR_FUNCTION_MOTOR1 = 101
 
-uint8 NUM_CONTROLS = 12  #
+uint8 NUM_CONTROLS = 12
-float32[12] control      # [@range -1, 1] Normalized thrust. where 1 means maximum positive thrust, -1 maximum negative (if not supported by the output, <0 maps to NaN). NaN maps to disarmed (stop the motors)
+float32[12] control # [@range -1, 1] Normalized thrust. Where 1 means maximum positive thrust, -1 maximum negative (if not supported by the output, <0 maps to NaN). NaN maps to disarmed (stop the motors)

msg/versioned/ActuatorServos.msg

@@ -8,5 +8,5 @@ uint32 MESSAGE_VERSION = 0
 uint64 timestamp # [us] Time since system start
 uint64 timestamp_sample # [us] Sampling timestamp of the data this control response is based on
 
-uint8 NUM_CONTROLS = 8  #
+uint8 NUM_CONTROLS = 8
 float32[8] control # [-] [@range -1, 1] Normalized output. 1 means maximum positive position. -1 maximum negative position (if not supported by the output, <0 maps to NaN). NaN maps to disarmed.

msg/versioned/AirspeedValidated.msg

@@ -3,7 +3,6 @@
 # Provides information about airspeed (indicated, true, calibrated) and the source of the data.
 # Used by controllers, estimators and for airspeed reporting to operator.
 
-
 uint32 MESSAGE_VERSION = 1
 
 uint64 timestamp # [us] Time since system start

msg/versioned/BatteryStatus.msg

@@ -17,10 +17,9 @@ float32 discharged_mah     # [mAh] [@invalid -1] Discharged amount
 float32 remaining # [@range 0,1] [@invalid -1] Remaining capacity
 float32 scale # [-] [@range 1,] [@invalid -1] Scaling factor to compensate for lower actuation power caused by voltage sag
 float32 time_remaining_s # [s] [@invalid NaN] Predicted time remaining until battery is empty under previous averaged load
-float32 temperature        # [°C] [@invalid NaN] Temperature of the battery
+float32 temperature # [degC] [@invalid NaN] Temperature of the battery
 uint8 cell_count # [-] [@invalid 0] Number of cells
 
-
 uint8 source # [@enum SOURCE] Battery source
 uint8 SOURCE_POWER_MODULE = 0 # Power module (analog ADC or I2C power monitor)
 uint8 SOURCE_EXTERNAL = 1 # External (MAVLink, CAN, or external driver)

msg/versioned/FixedWingLateralSetpoint.msg

@@ -1,11 +1,12 @@
 # Fixed Wing Lateral Setpoint message
+#
 # Used by the fw_lateral_longitudinal_control module
 # At least one of course, airspeed_direction, or lateral_acceleration must be finite.
 
 uint32 MESSAGE_VERSION = 0
 
-uint64 timestamp                        # time since system start (microseconds)
+uint64 timestamp # [us] Time since system start
 
 float32 course # [rad] [@range -pi, pi] Desired direction of travel over ground w.r.t (true) North. NAN if not controlled directly.
 float32 airspeed_direction # [rad] [@range -pi, pi] Desired horizontal angle of airspeed vector w.r.t. (true) North. Same as vehicle heading if in the absence of sideslip. NAN if not controlled directly, takes precedence over course if finite.
-float32 lateral_acceleration 		# [m/s^2] [FRD] Lateral acceleration setpoint. NAN if not controlled directly, used as feedforward if either course setpoint or airspeed_direction is finite.
+float32 lateral_acceleration # [m/s^2] [@frame FRD] Lateral acceleration setpoint. NAN if not controlled directly, used as feedforward if either course setpoint or airspeed_direction is finite.

msg/versioned/FixedWingLongitudinalSetpoint.msg

@@ -1,14 +1,15 @@
 # Fixed Wing Longitudinal Setpoint message
+#
 # Used by the fw_lateral_longitudinal_control module
 # If pitch_direct and throttle_direct are not both finite, then the controller relies on altitude/height_rate and equivalent_airspeed to control vertical motion.
 # If both altitude and height_rate are NAN, the controller maintains the current altitude.
 
 uint32 MESSAGE_VERSION = 0
 
-uint64 timestamp                        # time since system start (microseconds)
+uint64 timestamp # [us] Time since system start
 
 float32 altitude # [m] Altitude setpoint AMSL, not controlled directly if NAN or if height_rate is finite
-float32 height_rate 			# [m/s] [ENU] Scalar height rate setpoint. NAN if not controlled directly
+float32 height_rate # [m/s] [@frame ENU] Scalar height rate setpoint. NAN if not controlled directly
 float32 equivalent_airspeed # [m/s] [@range 0, inf] Scalar equivalent airspeed setpoint. NAN if system default should be used
-float32 pitch_direct 			# [rad] [@range -pi, pi] [FRD] NAN if not controlled, overrides total energy controller
+float32 pitch_direct # [rad] [@range -pi, pi] [@frame FRD] NAN if not controlled, overrides total energy controller
 float32 throttle_direct # [norm] [@range 0,1] NAN if not controlled, overrides total energy controller

msg/versioned/GotoSetpoint.msg

@@ -1,26 +1,27 @@
 # Position and (optional) heading setpoints with corresponding speed constraints
-# Setpoints are intended as inputs to position and heading smoothers, respectively
+#
-# Setpoints do not need to be kinematically consistent
+# Setpoints are intended as inputs to position and heading smoothers, respectively.
-# Optional heading setpoints may be specified as controlled by the respective flag
+# Setpoints do not need to be kinematically consistent.
-# Unset optional setpoints are not controlled
+# Optional heading setpoints may be specified as controlled by the respective flag.
-# Unset optional constraints default to vehicle specifications
+# Unset optional setpoints are not controlled.
+# Unset optional constraints default to vehicle specifications.
 
 uint32 MESSAGE_VERSION = 0
 
-uint64 timestamp # time since system start (microseconds)
+uint64 timestamp # [us] Time since system start
 
 # setpoints
-float32[3] position # [m] NED local world frame
+float32[3] position # [m] [@frame NED] NED local world frame
 
 bool flag_control_heading # true if heading is to be controlled
 float32 heading # (optional) [rad] [-pi,pi] from North
 
 # constraints
 bool flag_set_max_horizontal_speed # true if setting a non-default horizontal speed limit
-float32 max_horizontal_speed # (optional) [m/s] maximum speed (absolute) in the NE-plane
+float32 max_horizontal_speed # [m/s] (optional) Maximum speed (absolute) in the NE-plane
 
 bool flag_set_max_vertical_speed # true if setting a non-default vertical speed limit
-float32 max_vertical_speed # (optional) [m/s] maximum speed (absolute) in the D-axis
+float32 max_vertical_speed # [m/s] (optional) Maximum speed (absolute) in the D-axis
 
 bool flag_set_max_heading_rate # true if setting a non-default heading rate limit
-float32 max_heading_rate # (optional) [rad/s] maximum heading rate (absolute)
+float32 max_heading_rate # [rad/s] (optional) Maximum heading rate (absolute)

msg/versioned/LateralControlConfiguration.msg

@@ -1,8 +1,9 @@
 # Fixed Wing Lateral Control Configuration message
+#
 # Used by the fw_lateral_longitudinal_control module to constrain FixedWingLateralSetpoint messages.
 
 uint32 MESSAGE_VERSION = 0
 
-uint64 timestamp          # time since system start (microseconds)
+uint64 timestamp # [us] Time since system start
 
-float32 lateral_accel_max # [m/s^2] currently maps to a maximum roll angle, accel_max = tan(roll_max) * GRAVITY
+float32 lateral_accel_max # [m/s^2] Currently maps to a maximum roll angle, accel_max = tan(roll_max) * GRAVITY

msg/versioned/LongitudinalControlConfiguration.msg

@@ -1,17 +1,18 @@
 # Fixed Wing Longitudinal Control Configuration message
+#
 # Used by the fw_lateral_longitudinal_control module and TECS to constrain FixedWingLongitudinalSetpoint messages
 # and configure the resultant setpoints.
 
 uint32 MESSAGE_VERSION = 0
 
-uint64 timestamp                        # time since system start (microseconds)
+uint64 timestamp # [us] Time since system start
 
-float32 pitch_min   			# [rad][@range -pi, pi] defaults to FW_P_LIM_MIN if NAN.
+float32 pitch_min # [rad] [@range -pi, pi] Defaults to FW_P_LIM_MIN if NAN.
-float32 pitch_max   			# [rad][@range -pi, pi] defaults to FW_P_LIM_MAX if NAN.
+float32 pitch_max # [rad] [@range -pi, pi] Defaults to FW_P_LIM_MAX if NAN.
-float32 throttle_min 			# [norm] [@range 0,1] deaults to FW_THR_MIN if NAN.
+float32 throttle_min # [norm] [@range 0,1] Defaults to FW_THR_MIN if NAN.
-float32 throttle_max 			# [norm] [@range 0,1] defaults to FW_THR_MAX if NAN.
+float32 throttle_max # [norm] [@range 0,1] Defaults to FW_THR_MAX if NAN.
-float32 climb_rate_target 		# [m/s] target climbrate to change altitude. Defaults to FW_T_CLIMB_MAX if NAN. Not used if height_rate is directly set in FixedWingLongitudinalSetpoint.
+float32 climb_rate_target # [m/s] Target climbrate to change altitude. Defaults to FW_T_CLIMB_MAX if NAN. Not used if height_rate is directly set in FixedWingLongitudinalSetpoint.
-float32 sink_rate_target 		# [m/s] target sinkrate to change altitude. Defaults to FW_T_SINK_MAX if NAN. Not used if height_rate is directly set in FixedWingLongitudinalSetpoint.
+float32 sink_rate_target # [m/s] Target sinkrate to change altitude. Defaults to FW_T_SINK_MAX if NAN. Not used if height_rate is directly set in FixedWingLongitudinalSetpoint.
-float32 speed_weight 			# [@range 0,2], 0=pitch controls altitude only, 2=pitch controls airspeed only
+float32 speed_weight # [-] [@range 0,2] 0=pitch controls altitude only, 2=pitch controls airspeed only
-bool enforce_low_height_condition 	# [boolean] if true, the altitude controller is configured with an alternative timeconstant for tighter altitude tracking
+bool enforce_low_height_condition # If true, the altitude controller is configured with an alternative timeconstant for tighter altitude tracking
-bool disable_underspeed_protection 	# [boolean] if true, underspeed handling is disabled in the altitude controller
+bool disable_underspeed_protection # If true, underspeed handling is disabled in the altitude controller