Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[WIP] Offboard mode topic restructure #3031

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

[WIP] Offboard mode topic restructure #3031

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
93624d2
Offboard mode: slighty better intro
hamishwillee Feb 1, 2024
ec1f050
Minor structural changes
hamishwillee Feb 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 31 additions & 7 deletions en/flight_modes/offboard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,17 @@

[<img src="../../assets/site/position_fixed.svg" title="Position fix required (e.g. GPS)" width="30px" />](../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.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note to self. Intent is to push the ROS 2 specifics and MAVLink specifics as far as possible into those instructions. The MAVLink part more or less done but the ROS 2 not yet done, as is pending response to #3031 (comment)

When that is done probably merge the content in the top of page and description into the description (as far as possible) as there is duplication now.


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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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)

Expand All @@ -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

Expand Down
Loading