Files
PX4-Autopilot/docs/en/msg_docs/SetpointConfig.md
T
Michael Fritsche e8b3274ab0 feat(msg): rename rover throttle setpoint to surface_vehicle_thrust_setpoint (#29777)
* feat(msg): rename rover throttle setpoint to surface_vehicle_*

The throttle setpoint was the last rover topic shared by rovers and boats
without the surface_vehicle_* prefix decided in #29524. Rename
RoverThrottleSetpoint to SurfaceVehicleThrottleSetpoint and the
TYPE_ROVER_THROTTLE_* setpoint types to TYPE_SURFACE_VEHICLE_THROTTLE_*.
The type values are unchanged.

The topic rename breaks ROS 2 users anyway, so also shorten the fields of
the throttle and speed setpoints to x and y: the message name already says
what the value is and [@frame Body] states the frame.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Michael Fritsche <frimi999@gmail.com>

* fix(zenoh): bring surface_vehicle rename to the zenoh dds topics

* fix(concept): rename rover throttle setpoint to surface_vehicle_* in navigation terminology

* fix(tools): update px4-ros2-interface-lib pin

* docs(msg): describe sideways fields as omnidirectional, not mecanum

The surface vehicle messages are shared by rovers and boats, and the lateral
axis applies to any vehicle that can move sideways, not only mecanum rovers.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Michael Fritsche <frimi999@gmail.com>

* docs(ros2): use the surface vehicle setpoint type names of the interface lib

The pinned px4-ros2-interface-lib names the rover setpoint types
SurfaceVehicle*SetpointType. The table and the example reference still used
the old Rover*SetpointType class names, which do not exist in that version.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Michael Fritsche <frimi999@gmail.com>

* feat(msg)!: rename surface vehicle throttle setpoint to thrust setpoint

The setpoint is a normalized force command along the body x and y axes,
which is a thrust, not a throttle. Throttle stays the name for the motor
command the actuator control derives from it.

surface_vehicle_throttle_setpoint is now surface_vehicle_thrust_setpoint
(SurfaceVehicleThrustSetpoint), and SetpointConfig
TYPE_SURFACE_VEHICLE_THROTTLE_* are now TYPE_SURFACE_VEHICLE_THRUST_*
(same values). The px4-ros2-interface-lib pin follows the matching rename
there.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Michael Fritsche <frimi999@gmail.com>

* fix(tools): update px4-ros2-interface-lib pin

* fix(commander): do not enable velocity control for surface vehicle thrust setpoints

The SurfaceVehicleThrust* setpoint types enabled the velocity flag, taken
over from the original interface lib configuration. Nothing in these types
uses velocity, and offboard mode maps the same combinations without it.

The flag kept the rover speed controller running: switching from a
SurfaceVehicleSpeed* to a SurfaceVehicleThrust* type sets the same flags,
so the controllers were not reset and a stale speed setpoint kept
overriding the commanded thrust. It also made external modes that only
command thrust require a local position estimate.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Michael Fritsche <frimi999@gmail.com>

* docs(msg): apply review suggestions for the surface vehicle setpoints

Add long descriptions to the thrust and speed setpoints and the speed
status, name modules instead of C++ classes, and use single spaces before
field comments. Rename the speed status PID integrals from pid_throttle_*
to pid_thrust_*, since the speed controller drives the thrust setpoint.

Update the docs and the rover control structure diagram for the thrust
setpoint and omnidirectional vehicles, note the Rover*SetpointType names of
PX4 v1.17 and v1.18, and add the ROS 2 release note.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Michael Fritsche <frimi999@gmail.com>

---------

Signed-off-by: Michael Fritsche <frimi999@gmail.com>
2026-11-13 10:05:26 +01:00

8.0 KiB

pageClass
pageClass
is-wide-page

SetpointConfig (UORB message)

Setpoint configuration message.

Published by external modes and PX4 will respond with SetpointConfigReply.

TOPICS: setpoint_config

Fields

Name Type Unit [Frame] Range/Enum Description
timestamp uint64 us Time since system start
type uint16 TYPE setpoint type (corresponding to one or more setpoint messages)
source_id uint8 nav_state of the mode
should_apply bool if true: apply as current setpoint configuration (mode should be active). If false: setpoint configuration is not changed (can be used to check if a setpoint can be used with the current vehicle configuration).
timeout_ms uint16 Configure setpoint timeout. If no setpoint received for this time, PX4 triggers a failsafe. 0 disables the timeout (unresponsive modes still trigger a timeout through arming checks).

Enums

TYPE

Used in field(s): type

Name Type Value Description
TYPE_INVALID uint16 0
TYPE_DIRECT_ACTUATORS uint16 1 ActuatorMotors and ActuatorServos
TYPE_MULTICOPTER_GOTO uint16 2 GotoSetpoint
TYPE_FIXEDWING_LATERAL_LONGITUDINAL uint16 3 FixedWingLateralSetpoint and FixedWingLongitudinalSetpoint
TYPE_TRAJECTORY uint16 4 TrajectorySetpoint
TYPE_RATES uint16 5 VehicleRatesSetpoint
TYPE_ATTITUDE uint16 6 VehicleAttitudeSetpoint
TYPE_SURFACE_VEHICLE_POSITION uint16 7 SurfaceVehiclePositionSetpoint
TYPE_SURFACE_VEHICLE_SPEED_ATTITUDE uint16 8 SurfaceVehicleSpeedSetpoint and SurfaceVehicleAttitudeSetpoint
TYPE_SURFACE_VEHICLE_SPEED_RATE uint16 9 SurfaceVehicleSpeedSetpoint and SurfaceVehicleRateSetpoint
TYPE_SURFACE_VEHICLE_SPEED_STEERING uint16 10 SurfaceVehicleSpeedSetpoint and SurfaceVehicleSteeringSetpoint
TYPE_SURFACE_VEHICLE_THRUST_ATTITUDE uint16 11 SurfaceVehicleThrustSetpoint and SurfaceVehicleAttitudeSetpoint
TYPE_SURFACE_VEHICLE_THRUST_RATE uint16 12 SurfaceVehicleThrustSetpoint and SurfaceVehicleRateSetpoint
TYPE_SURFACE_VEHICLE_THRUST_STEERING uint16 13 SurfaceVehicleThrustSetpoint and SurfaceVehicleSteeringSetpoint
TYPE_TRAJECTORY_6DOF uint16 14 TrajectorySetpoint6dof
TYPE_THRUST_AND_TORQUE uint16 15 VehicleThrustSetpoint and VehicleTorqueSetpoint
TYPE_POSITION_TRIPLET uint16 16 PositionSetpointTriplet

Constants

Name Type Value Description
MESSAGE_VERSION uint32 0

Source Message

Source file (GitHub)

::: details Click here to see original file

# Setpoint configuration message
#
# Published by external modes and PX4 will respond with SetpointConfigReply.

uint32 MESSAGE_VERSION = 0

uint64 timestamp # [us] Time since system start

uint16 TYPE_INVALID = 0
uint16 TYPE_DIRECT_ACTUATORS = 1 # ActuatorMotors and ActuatorServos
uint16 TYPE_MULTICOPTER_GOTO = 2 # GotoSetpoint
uint16 TYPE_FIXEDWING_LATERAL_LONGITUDINAL = 3 # FixedWingLateralSetpoint and FixedWingLongitudinalSetpoint
uint16 TYPE_TRAJECTORY = 4 # TrajectorySetpoint
uint16 TYPE_RATES = 5 # VehicleRatesSetpoint
uint16 TYPE_ATTITUDE = 6 # VehicleAttitudeSetpoint
uint16 TYPE_SURFACE_VEHICLE_POSITION = 7 # SurfaceVehiclePositionSetpoint
uint16 TYPE_SURFACE_VEHICLE_SPEED_ATTITUDE = 8 # SurfaceVehicleSpeedSetpoint and SurfaceVehicleAttitudeSetpoint
uint16 TYPE_SURFACE_VEHICLE_SPEED_RATE = 9 # SurfaceVehicleSpeedSetpoint and SurfaceVehicleRateSetpoint
uint16 TYPE_SURFACE_VEHICLE_SPEED_STEERING = 10 # SurfaceVehicleSpeedSetpoint and SurfaceVehicleSteeringSetpoint
uint16 TYPE_SURFACE_VEHICLE_THRUST_ATTITUDE = 11 # SurfaceVehicleThrustSetpoint and SurfaceVehicleAttitudeSetpoint
uint16 TYPE_SURFACE_VEHICLE_THRUST_RATE = 12 # SurfaceVehicleThrustSetpoint and SurfaceVehicleRateSetpoint
uint16 TYPE_SURFACE_VEHICLE_THRUST_STEERING = 13 # SurfaceVehicleThrustSetpoint and SurfaceVehicleSteeringSetpoint
uint16 TYPE_TRAJECTORY_6DOF = 14 # TrajectorySetpoint6dof
uint16 TYPE_THRUST_AND_TORQUE = 15 # VehicleThrustSetpoint and VehicleTorqueSetpoint
uint16 TYPE_POSITION_TRIPLET = 16 # PositionSetpointTriplet

uint16 type # [@enum TYPE] setpoint type (corresponding to one or more setpoint messages)

uint8 source_id # nav_state of the mode

bool should_apply # if true: apply as current setpoint configuration (mode should be active). If false: setpoint configuration is not changed (can be used to check if a setpoint can be used with the current vehicle configuration).

uint16 timeout_ms # Configure setpoint timeout. If no setpoint received for this time, PX4 triggers a failsafe. 0 disables the timeout (unresponsive modes still trigger a timeout through arming checks).

:::