diff --git a/docs/en/middleware/dds_topics.md b/docs/en/middleware/dds_topics.md index 3426987762..b2c9d7fa8f 100644 --- a/docs/en/middleware/dds_topics.md +++ b/docs/en/middleware/dds_topics.md @@ -13,9 +13,10 @@ This document shows a markdown-rendered version of [dds_topics.yaml](https://git | Topic | Type | Rate Limit | | ---------------------------------------- | -------------------------------------------------------------------------------------- | ---------- | | `/fmu/out/airspeed_validated` | [px4_msgs::msg::AirspeedValidated](../msg_docs/AirspeedValidated.md) | 50.0 | -| `/fmu/out/arming_check_request` | [px4_msgs::msg::ArmingCheckRequest](../msg_docs/ArmingCheckRequest.md) | 5.0 | +| `/fmu/out/arming_check_request` | [px4_msgs::msg::ArmingCheckRequest](../msg_docs/ArmingCheckRequest.md) | | `/fmu/out/battery_status` | [px4_msgs::msg::BatteryStatus](../msg_docs/BatteryStatus.md) | 1.0 | | `/fmu/out/collision_constraints` | [px4_msgs::msg::CollisionConstraints](../msg_docs/CollisionConstraints.md) | 50.0 | +| `/fmu/out/config_overrides_confirm` | [px4_msgs::msg::ConfigOverrides](../msg_docs/ConfigOverrides.md) | | `/fmu/out/estimator_status_flags` | [px4_msgs::msg::EstimatorStatusFlags](../msg_docs/EstimatorStatusFlags.md) | 5.0 | | `/fmu/out/failsafe_flags` | [px4_msgs::msg::FailsafeFlags](../msg_docs/FailsafeFlags.md) | 5.0 | | `/fmu/out/gimbal_device_attitude_status` | [px4_msgs::msg::GimbalDeviceAttitudeStatus](../msg_docs/GimbalDeviceAttitudeStatus.md) | 20.0 | @@ -27,6 +28,7 @@ This document shows a markdown-rendered version of [dds_topics.yaml](https://git | `/fmu/out/position_setpoint_triplet` | [px4_msgs::msg::PositionSetpointTriplet](../msg_docs/PositionSetpointTriplet.md) | 5.0 | | `/fmu/out/register_ext_component_reply` | [px4_msgs::msg::RegisterExtComponentReply](../msg_docs/RegisterExtComponentReply.md) | | `/fmu/out/sensor_combined` | [px4_msgs::msg::SensorCombined](../msg_docs/SensorCombined.md) | +| `/fmu/out/setpoint_config_reply` | [px4_msgs::msg::SetpointConfigReply](../msg_docs/SetpointConfigReply.md) | | `/fmu/out/timesync_status` | [px4_msgs::msg::TimesyncStatus](../msg_docs/TimesyncStatus.md) | 10.0 | | `/fmu/out/transponder_report` | [px4_msgs::msg::TransponderReport](../msg_docs/TransponderReport.md) | | `/fmu/out/vehicle_attitude` | [px4_msgs::msg::VehicleAttitude](../msg_docs/VehicleAttitude.md) | 50.0 | @@ -49,7 +51,6 @@ This document shows a markdown-rendered version of [dds_topics.yaml](https://git | `/fmu/in/actuator_motors` | [px4_msgs::msg::ActuatorMotors](../msg_docs/ActuatorMotors.md) | | `/fmu/in/actuator_servos` | [px4_msgs::msg::ActuatorServos](../msg_docs/ActuatorServos.md) | | `/fmu/in/arming_check_reply` | [px4_msgs::msg::ArmingCheckReply](../msg_docs/ArmingCheckReply.md) | -| `/fmu/in/config_control_setpoints` | [px4_msgs::msg::VehicleControlMode](../msg_docs/VehicleControlMode.md) | | `/fmu/in/config_overrides_request` | [px4_msgs::msg::ConfigOverrides](../msg_docs/ConfigOverrides.md) | | `/fmu/in/distance_sensor` | [px4_msgs::msg::DistanceSensor](../msg_docs/DistanceSensor.md) | | `/fmu/in/fixed_wing_lateral_setpoint` | [px4_msgs::msg::FixedWingLateralSetpoint](../msg_docs/FixedWingLateralSetpoint.md) | @@ -72,6 +73,7 @@ This document shows a markdown-rendered version of [dds_topics.yaml](https://git | `/fmu/in/rover_steering_setpoint` | [px4_msgs::msg::RoverSteeringSetpoint](../msg_docs/RoverSteeringSetpoint.md) | | `/fmu/in/rover_throttle_setpoint` | [px4_msgs::msg::RoverThrottleSetpoint](../msg_docs/RoverThrottleSetpoint.md) | | `/fmu/in/sensor_optical_flow` | [px4_msgs::msg::SensorOpticalFlow](../msg_docs/SensorOpticalFlow.md) | +| `/fmu/in/setpoint_config` | [px4_msgs::msg::SetpointConfig](../msg_docs/SetpointConfig.md) | | `/fmu/in/telemetry_status` | [px4_msgs::msg::TelemetryStatus](../msg_docs/TelemetryStatus.md) | | `/fmu/in/trajectory_setpoint` | [px4_msgs::msg::TrajectorySetpoint](../msg_docs/TrajectorySetpoint.md) | | `/fmu/in/unregister_ext_component` | [px4_msgs::msg::UnregisterExtComponent](../msg_docs/UnregisterExtComponent.md) | @@ -286,7 +288,6 @@ They are not build into the module, and hence are neither published or subscribe - [UlogStreamAck](../msg_docs/UlogStreamAck.md) - [VehicleAcceleration](../msg_docs/VehicleAcceleration.md) - [VehicleAirData](../msg_docs/VehicleAirData.md) -- [VehicleAngularAccelerationSetpoint](../msg_docs/VehicleAngularAccelerationSetpoint.md) - [VehicleAngularVelocity](../msg_docs/VehicleAngularVelocity.md) - [VehicleAttitudeSetpointV0](../msg_docs/VehicleAttitudeSetpointV0.md) - [VehicleCommandAckV0](../msg_docs/VehicleCommandAckV0.md) diff --git a/docs/en/msg_docs/ConfigOverrides.md b/docs/en/msg_docs/ConfigOverrides.md index 05163d6844..6704e9a1ea 100644 --- a/docs/en/msg_docs/ConfigOverrides.md +++ b/docs/en/msg_docs/ConfigOverrides.md @@ -6,7 +6,7 @@ pageClass: is-wide-page Configurable overrides by (external) modes or mode executors. -**TOPICS:** config_overrides config_overrides_request +**TOPICS:** config_overrides config_overrides_request config_overrides_confirm ## Fields @@ -56,7 +56,7 @@ uint8 source_id # ID depending on source_type uint8 ORB_QUEUE_LENGTH = 4 -# TOPICS config_overrides config_overrides_request +# TOPICS config_overrides config_overrides_request config_overrides_confirm ``` ::: diff --git a/docs/en/msg_docs/RegisterExtComponentRequest.md b/docs/en/msg_docs/RegisterExtComponentRequest.md index 0585e8aec7..1eb04eeae6 100644 --- a/docs/en/msg_docs/RegisterExtComponentRequest.md +++ b/docs/en/msg_docs/RegisterExtComponentRequest.md @@ -30,7 +30,7 @@ Request to register an external component. | Name | Type | Value | Description | | --------------------------------------------------------------------- | -------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | MESSAGE_VERSION | `uint32` | 2 | -| LATEST_PX4_ROS2_API_VERSION | `uint16` | 1 | API version compatibility. Increase this on a breaking semantic change. Changes to any message field are detected separately and do not require an API version change. | +| LATEST_PX4_ROS2_API_VERSION | `uint16` | 2 | API version compatibility. Increase this on a breaking semantic change. Changes to any message field are detected separately and do not require an API version change. | | ORB_QUEUE_LENGTH | `uint8` | 2 | ## Source Message @@ -49,7 +49,7 @@ uint64 timestamp # time since system start (microseconds) uint64 request_id # ID, set this to a random value char[25] name # either the requested mode name, or component name -uint16 LATEST_PX4_ROS2_API_VERSION = 1 # API version compatibility. Increase this on a breaking semantic change. Changes to any message field are detected separately and do not require an API version change. +uint16 LATEST_PX4_ROS2_API_VERSION = 2 # API version compatibility. Increase this on a breaking semantic change. Changes to any message field are detected separately and do not require an API version change. uint16 px4_ros2_api_version # Set to LATEST_PX4_ROS2_API_VERSION diff --git a/docs/en/msg_docs/SetpointConfig.md b/docs/en/msg_docs/SetpointConfig.md new file mode 100644 index 0000000000..4081d6fb27 --- /dev/null +++ b/docs/en/msg_docs/SetpointConfig.md @@ -0,0 +1,97 @@ +--- +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](#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 {#TYPE} + +Used in field(s): [type](#fld_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_ROVER_POSITION | `uint16` | 7 | RoverPositionSetpoint | +| TYPE_ROVER_SPEED_ATTITUDE | `uint16` | 8 | RoverSpeedSetpoint and RoverAttitudeSetpoint | +| TYPE_ROVER_SPEED_RATE | `uint16` | 9 | RoverSpeedSetpoint and RoverRateSetpoint | +| TYPE_ROVER_SPEED_STEERING | `uint16` | 10 | RoverSpeedSetpoint and RoverSteeringSetpoint | +| TYPE_ROVER_THROTTLE_ATTITUDE | `uint16` | 11 | RoverThrottleSetpoint and RoverAttitudeSetpoint | +| TYPE_ROVER_THROTTLE_RATE | `uint16` | 12 | RoverThrottleSetpoint and RoverRateSetpoint | +| TYPE_ROVER_THROTTLE_STEERING | `uint16` | 13 | RoverThrottleSetpoint and RoverSteeringSetpoint | +| 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)](https://github.com/PX4/PX4-Autopilot/blob/main/msg/versioned/SetpointConfig.msg) + +::: details Click here to see original file + +```c +# 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_ROVER_POSITION = 7 # RoverPositionSetpoint +uint16 TYPE_ROVER_SPEED_ATTITUDE = 8 # RoverSpeedSetpoint and RoverAttitudeSetpoint +uint16 TYPE_ROVER_SPEED_RATE = 9 # RoverSpeedSetpoint and RoverRateSetpoint +uint16 TYPE_ROVER_SPEED_STEERING = 10 # RoverSpeedSetpoint and RoverSteeringSetpoint +uint16 TYPE_ROVER_THROTTLE_ATTITUDE = 11 # RoverThrottleSetpoint and RoverAttitudeSetpoint +uint16 TYPE_ROVER_THROTTLE_RATE = 12 # RoverThrottleSetpoint and RoverRateSetpoint +uint16 TYPE_ROVER_THROTTLE_STEERING = 13 # RoverThrottleSetpoint and RoverSteeringSetpoint +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). +``` + +::: diff --git a/docs/en/msg_docs/SetpointConfigReply.md b/docs/en/msg_docs/SetpointConfigReply.md new file mode 100644 index 0000000000..772aff693b --- /dev/null +++ b/docs/en/msg_docs/SetpointConfigReply.md @@ -0,0 +1,74 @@ +--- +pageClass: is-wide-page +--- + +# SetpointConfigReply (UORB message) + +Reply to SetpointConfig. + +**TOPICS:** setpoint_config_reply + +## Fields + +| Name | Type | Unit [Frame] | Range/Enum | Description | +| ------------------------------------------------------------------- | -------- | ------------ | ----------------- | -------------------------------------------------- | +| timestamp | `uint64` | us | | Time since system start | +| type | `uint16` | | | See SetpointConfig::TYPE\_\* | +| source_id | `uint8` | | | nav_state of the mode that sent the SetpointConfig | +| result | `uint8` | | [RESULT](#RESULT) | +| mode_req_angular_velocity | `bool` | | | +| mode_req_attitude | `bool` | | | +| mode_req_local_alt | `bool` | | | +| mode_req_local_position | `bool` | | | + +## Enums + +### RESULT {#RESULT} + +Used in field(s): [result](#fld_result) + +| Name | Type | Value | Description | +| ----------------------------------------------------------------------- | ------- | ----- | ---------------------------------------------------- | +| RESULT_SUCCESS | `uint8` | 0 | +| RESULT_FAILURE_OTHER | `uint8` | 1 | +| RESULT_UNSUPPORTED | `uint8` | 2 | Setpoint type is unsupported for the current vehicle | +| RESULT_UNKNOWN_SETPOINT_TYPE | `uint8` | 3 | The setpoint type is not known | + +## Constants + +| Name | Type | Value | Description | +| --------------------------------------------- | -------- | ----- | ----------- | +| MESSAGE_VERSION | `uint32` | 0 | + +## Source Message + +[Source file (GitHub)](https://github.com/PX4/PX4-Autopilot/blob/main/msg/versioned/SetpointConfigReply.msg) + +::: details Click here to see original file + +```c +# Reply to SetpointConfig + +uint32 MESSAGE_VERSION = 0 + +uint64 timestamp # [us] Time since system start + +uint16 type # See SetpointConfig::TYPE_* + +uint8 source_id # nav_state of the mode that sent the SetpointConfig + +uint8 RESULT_SUCCESS = 0 +uint8 RESULT_FAILURE_OTHER = 1 +uint8 RESULT_UNSUPPORTED = 2 # Setpoint type is unsupported for the current vehicle +uint8 RESULT_UNKNOWN_SETPOINT_TYPE = 3 # The setpoint type is not known +uint8 result # [@enum RESULT] + +# Mode requirements for using the given setpoint type. A mode will use these and apply them to the arming check reply (PX4 does not do that itself). +# Certain setpoint types can be used in a reduced way, for example a TrajectorySetpoint without position control. In that case PX4 still sets all requirement flags, and the mode will then ignore mode_req_local_position. +bool mode_req_angular_velocity +bool mode_req_attitude +bool mode_req_local_alt +bool mode_req_local_position +``` + +::: diff --git a/docs/en/msg_docs/VehicleControlMode.md b/docs/en/msg_docs/VehicleControlMode.md index e1cacee2b8..98c4a07408 100644 --- a/docs/en/msg_docs/VehicleControlMode.md +++ b/docs/en/msg_docs/VehicleControlMode.md @@ -4,7 +4,9 @@ pageClass: is-wide-page # VehicleControlMode (UORB message) -**TOPICS:** vehicle_control_mode config_control_setpoints +Defines which controllers should run. + +**TOPICS:** vehicle_control_mode ## Fields @@ -20,27 +22,18 @@ pageClass: is-wide-page | flag_control_velocity_enabled | `bool` | | | true if horizontal velocity (implies direction) is controlled | | flag_control_altitude_enabled | `bool` | | | true if altitude is controlled | | flag_control_climb_rate_enabled | `bool` | | | true if climb rate is controlled | -| flag_control_acceleration_enabled | `bool` | | | true if acceleration is controlled | | flag_control_attitude_enabled | `bool` | | | true if attitude stabilization is mixed in | | flag_control_rates_enabled | `bool` | | | true if rates are stabilized | | flag_control_allocation_enabled | `bool` | | | true if control allocation is enabled | -| flag_control_termination_enabled | `bool` | | | true if flighttermination is enabled | -| source_id | `uint8` | | | Mode ID (nav_state) | - -## Constants - -| Name | Type | Value | Description | -| --------------------------------------------- | -------- | ----- | ----------- | -| MESSAGE_VERSION | `uint32` | 0 | ## Source Message -[Source file (GitHub)](https://github.com/PX4/PX4-Autopilot/blob/main/msg/versioned/VehicleControlMode.msg) +[Source file (GitHub)](https://github.com/PX4/PX4-Autopilot/blob/main/msg/VehicleControlMode.msg) ::: details Click here to see original file ```c -uint32 MESSAGE_VERSION = 0 +# Defines which controllers should run uint64 timestamp # time since system start (microseconds) bool flag_armed # synonym for actuator_armed.armed @@ -54,16 +47,9 @@ bool flag_control_position_enabled # true if position is controlled bool flag_control_velocity_enabled # true if horizontal velocity (implies direction) is controlled bool flag_control_altitude_enabled # true if altitude is controlled bool flag_control_climb_rate_enabled # true if climb rate is controlled -bool flag_control_acceleration_enabled # true if acceleration is controlled bool flag_control_attitude_enabled # true if attitude stabilization is mixed in bool flag_control_rates_enabled # true if rates are stabilized bool flag_control_allocation_enabled # true if control allocation is enabled -bool flag_control_termination_enabled # true if flighttermination is enabled - -# TODO: use dedicated topic for external requests -uint8 source_id # Mode ID (nav_state) - -# TOPICS vehicle_control_mode config_control_setpoints ``` ::: diff --git a/docs/en/msg_docs/index.md b/docs/en/msg_docs/index.md index fa74a47f4b..1a552cb0c8 100644 --- a/docs/en/msg_docs/index.md +++ b/docs/en/msg_docs/index.md @@ -36,6 +36,8 @@ Graphs showing how these are used [can be found here](../middleware/uorb_graph.m - [RaptorStatus](RaptorStatus.md) — Raptor Status. - [RegisterExtComponentReply](RegisterExtComponentReply.md) - [RegisterExtComponentRequest](RegisterExtComponentRequest.md) — Request to register an external component. +- [SetpointConfig](SetpointConfig.md) — Setpoint configuration message. +- [SetpointConfigReply](SetpointConfigReply.md) — Reply to SetpointConfig. - [TrajectorySetpoint](TrajectorySetpoint.md) — Trajectory setpoint in NED frame. Input to PID position controller. Needs to be kinematically consistent and feasible for smooth flight. setting a value to NaN means the state should not be controlled. - [UnregisterExtComponent](UnregisterExtComponent.md) - [VehicleAngularVelocity](VehicleAngularVelocity.md) @@ -43,7 +45,6 @@ Graphs showing how these are used [can be found here](../middleware/uorb_graph.m - [VehicleAttitudeSetpoint](VehicleAttitudeSetpoint.md) - [VehicleCommand](VehicleCommand.md) — Vehicle Command uORB message. Used for commanding a mission / action / etc. Follows the MAVLink COMMAND_INT / COMMAND_LONG definition. - [VehicleCommandAck](VehicleCommandAck.md) — Vehicle Command Acknowledgement uORB message. -- [VehicleControlMode](VehicleControlMode.md) - [VehicleGlobalPosition](VehicleGlobalPosition.md) — Fused global position in WGS84. This struct contains global position estimation. It is not the raw GPS. measurement (@see vehicle_gps_position). This topic is usually published by the position. estimator, which will take more sources of information into account than just GPS,. e.g. control inputs of the vehicle in a Kalman-filter implementation. - [VehicleLandDetected](VehicleLandDetected.md) - [VehicleLocalPosition](VehicleLocalPosition.md) — Fused local position in NED. The coordinate system origin is the vehicle position at the time when the EKF2-module was started. @@ -277,8 +278,8 @@ Graphs showing how these are used [can be found here](../middleware/uorb_graph.m - [UlogStreamAck](UlogStreamAck.md) — Ack a previously sent ulog_stream message that had. the NEED_ACK flag set. - [VehicleAcceleration](VehicleAcceleration.md) - [VehicleAirData](VehicleAirData.md) — Vehicle air data. -- [VehicleAngularAccelerationSetpoint](VehicleAngularAccelerationSetpoint.md) - [VehicleConstraints](VehicleConstraints.md) — Local setpoint constraints in NED frame. setting something to NaN means that no limit is provided. +- [VehicleControlMode](VehicleControlMode.md) — Defines which controllers should run. - [VehicleImu](VehicleImu.md) — IMU readings in SI-unit form. - [VehicleImuStatus](VehicleImuStatus.md) - [VehicleLocalPositionSetpoint](VehicleLocalPositionSetpoint.md) — Local position setpoint in NED frame. Telemetry of PID position controller to monitor tracking. NaN means the state was not controlled.