diff --git a/en/flight_modes/offboard.md b/en/flight_modes/offboard.md index 0c7c23957c55..84954e9a864d 100644 --- a/en/flight_modes/offboard.md +++ b/en/flight_modes/offboard.md @@ -2,12 +2,17 @@ [](../getting_started/flight_modes.md#key_position_fixed) -The vehicle obeys position, velocity, acceleration, attitude, attitude rates or thrust/torque setpoints provided by some source that is external to the flight stack, such as a companion computer. -The setpoints may be provided using MAVLink (or a MAVLink API such as [MAVSDK](https://mavsdk.mavlink.io/)) or by [ROS 2](../ros/ros2.md). +The _Offboard_ mode allows PX4 to be controlled by some source that is external to the flight stack, such as a companion computer. +The offboard controller supplies a stream of position, velocity, acceleration, attitude, attitude rate, or thrust/torque setpoints, which are injected into the [PX4 control architecture](../flight_stack/controller_diagrams.md) as though they had been generated by the equivalent internal controller — the corresponding internal controllers that would otherwise have generated the setpoint (in another mode) are turned off. + +The setpoints may be provided using [MAVLink](#mavlink-offboard-control) or by [ROS 2](#ros-2-offboard-control). PX4 requires that the external controller provides a continuous 2Hz "proof of life" signal, by streaming any of the supported MAVLink setpoint messages or the ROS 2 [OffboardControlMode](../msg_docs/OffboardControlMode.md) message. PX4 enables offboard control only after receiving the signal for more than a second, and will regain control if the signal stops. +Different vehicle frame types implement different [control architectures](../flight_stack/controller_diagrams.md). +As a result the setpoints and setpoint combinations that can be set depend on the vehicle. + :::note - This mode requires position or pose/attitude information - e.g. GPS, optical flow, visual-inertial odometry, mocap, etc. @@ -38,9 +43,9 @@ Note that offboard mode only supports a very limited set of MAVLink commands and Operations, like taking off, landing, return to launch, may be best handled using the appropriate modes. Operations like uploading, downloading missions can be performed in any mode. -## ROS 2 Messages +## ROS 2 Offboard Control + -The following ROS 2 messages and their particular fields and field values are allowed for the specified frames. In addition to providing heartbeat functionality, `OffboardControlMode` has two other main purposes: 1. Controls the level of the [PX4 control architecture](../flight_stack/controller_diagrams.md) at which offboard setpoints must be injected, and disables the bypassed controllers. @@ -84,6 +89,8 @@ Before using offboard mode with ROS 2, please spend a few minutes understanding ### Copter +The following [ROS 2](../ros/ros2.md) messages and their particular fields and field values are allowed for Copter frames: + - [px4_msgs::msg::TrajectorySetpoint](https://github.com/PX4/PX4-Autopilot/blob/main/msg/TrajectorySetpoint.msg) - The following input combinations are supported: @@ -112,7 +119,8 @@ Before using offboard mode with ROS 2, please spend a few minutes understanding ### Generic Vehicle -The following offboard control modes bypass all internal PX4 control loops and should be used with great care. +The following [ROS 2](../ros/ros2.md) messages and their particular fields and field values are allowed for any frames. +These offboard control modes bypass all internal PX4 control loops and should be used with great care: - [px4_msgs::msg::VehicleThrustSetpoint](https://github.com/PX4/PX4-Autopilot/blob/main/msg/VehicleThrustSetpoint.msg) + [px4_msgs::msg::VehicleTorqueSetpoint](https://github.com/PX4/PX4-Autopilot/blob/main/msg/VehicleTorqueSetpoint.msg) @@ -125,9 +133,25 @@ The following offboard control modes bypass all internal PX4 control loops and s - All the values normalized in \[-1, 1\]. For outputs that do not support negative values, negative entries map to `NaN`. - `NaN` maps to disarmed. -## MAVLink Messages +## MAVLink Offboard Control + +Offboard mode setpoints can be set using MAVLink (either using a generated library or a MAVLink API such as [MAVSDK](https://mavsdk.mavlink.io/)). + +:::note +ROS 2 should be used instead of MAVLink for use cases where very high setpoint rates are required. +::: + +In offboard mode the setpoints are injected into the [PX4 control architecture](../flight_stack/controller_diagrams.md) as though they had been generated by the equivalent internal controller — the corresponding internal controllers that would otherwise have generated the setpoint (in another mode) are turned off. +In other modes the MAVLink setpoint messages are ignored. + +PX4 must receive a stream of MAVLink setpoint messages at 2 Hz or greater as proof that the external controller is healthy: + +- The stream must be sent for at least a second before PX4 will arm in offboard mode, or switch to offboard mode when flying. +- If the rate falls below 2Hz while under external control PX4 will switch out of offboard mode after a timeout ([COM_OF_LOSS_T](#COM_OF_LOSS_T)), and attempt to land or perform some other failsafe action. + The action depends on whether or not RC control is available, and is defined in the parameter [COM_OBL_RC_ACT](#COM_OBL_RC_ACT). -The following MAVLink messages and their particular fields and field values are allowed for the specified vehicle frames. +Since different vehicle frame types implement different [control architectures](../flight_stack/controller_diagrams.md), the setpoints and setpoint combinations that can be set depend on the vehicle. +The following MAVLink messages and their particular fields and field values are allowed for the specified frames. ### Copter/VTOL