PX4 uses a number of MAVLink interfaces for integrating path planning services from a companion computer (including obstacle avoidance in missions, safe landing, and future services):
- The MAVLink Path Planning Protocol message TRAJECTORY_REPRESENTATION_WAYPOINTS is used to sent the current and next waypoint, and receive a stream of setpoints for the new path.
- Alternatively, via mavlink the TRAJECTORY_REPRESENTATION_BEZIER can be used, parameterized by time, to specify the moving position setpoint of the vehicle over a given amount of time.
- The HEARTBEAT/Connection Protocol is used for "proof of life" detection.
- LOCAL_POSITION_NED and ALTITUDE send the vehicle local position and altitude, respectively.
Tip The message flows from PX4 UORB topics, through MAVLink, to ROS and back again are all documented in: PX4/avoidance > Message Flows.
All services that use this interface send and receive messages of the same type/format. Developers can therefore use this interface to create their own new companion-side path planning services, or tweak the existing planner software.
Path planning is activated in PX4 by setting the COM_OBS_AVOID to 1.
Companion-side hardware setup and hardware/software configuration is provided in the PX4/avoidance Github repo.
The actual setup/configuration required depends on the planner being used.
Warning Only one planner can run on the companion computer at a time (at time of writing). This means that offboard features that use different planners cannot be enabled on the same vehicle. a vehicle at the same time (e.g. a vehicle can support obstacle avoidance and collision prevent, but not also safe landing - or visa versa).
PX4 sends information about the desired path to the companion computer (when COM_OBS_AVOID=
, in modes for which the path planning interface has been integrated), and receives back a stream of setpoints for the planned path.
The path information is, in both cases, transported in TRAJECTORY_REPRESENTATION_WAYPOINTS messages.
PX4 sends the desired path in TRAJECTORY_REPRESENTATION_WAYPOINTS
messages at 5Hz.
The fields set by PX4 as shown:
time_usec
: UNIX Epoch time.valid_points
: 3- Point 0 - Current waypoint type adapted by FlightTaskAutoMapper (see notes below):
pos_x[0]
,pos_y[0]
,pos_z[0]
: Type adapted x-y-z NED local position of current mission waypoint.vel_x[0]
,vel_y[0]
,vel_z[0]
: Type adapted x-y-z NED local velocity of current mission waypoint.acc_x[0]
,acc_y[0]
,acc_z[0]
: NaNpos_yaw[0]
: Current yaw anglevel_yaw[0]
: NaNcommand[0]
: The MAVLink Command for the current waypoint.
- Point 1 - Current waypoint (Unmodified/not type adapted)):
pos_x[1]
,pos_y[1]
,pos_z[1]
: x-y-z NED local position of current mission waypointvel_x[1]
,vel_y[1]
,vel_z[1]
: NaNacc_x[1]
,acc_y[1]
,acc_z[1]
: NaNpos_yaw[1]
: Yaw setpointvel_yaw[1]
: Yaw speed setpointcommand[1]
: The MAVLink Command for the current waypoint.
- Point 2 - Next waypoint in local coordinates (unmodified/not type adapted):
pos_x[2]
,pos_y[2]
,pos_z[2]
: x-y-z NED local position of next mission waypointvel_x[2]
,vel_y[2]
,vel_z[2]
: NaNacc_x[2]
,acc_y[2]
,acc_z[2]
: NaNpos_yaw[2]
: Yaw setpointvel_yaw[2]
: Yaw speed setpointcommand[2]
: The MAVLink Command for the next waypoint.
- All other indices/fields are set as NaN.
Notes:
- Point 0 is the current waypoint/target modified based on the type of target.
For example, it makes sense when landing to specify the target x, y coordinates and a descent velocity.
To achieve this
FlightTaskAutoMapper
modifies land waypoints in Point 0 to set the z component of position to NAN and the z-velocity to a desired value. - Point 1 and 2 are not used by the safe landing planner.
- Point 1 is used by local and global planner.
On the companion side, MAVROS translates the MAVLink message into ROS messages, which are eventually handled by the appropriate planner.
The planner plans a path to the waypoint/target, and sends it to the vehicle as a stream of TRAJECTORY_REPRESENTATION_WAYPOINTS
messages that have the setpoint in Point 0.
The fields for the messages from the companion computer are set as shown:
time_usec
: UNIX Epoch time.valid_points
: 1- Current vehicle information:
pos_x[0]
,pos_y[0]
,pos_z[0]
: x-y-z NED vehicle local position setpointvel_x[0]
,vel_y[0]
,vel_z[0]
: x-y-z NED velocity setpointacc_x[0]
,acc_y[0]
,acc_z[0]
: NaNpos_yaw[0]
: Yaw angle setpointvel_yaw[0]
: Yaw speed setpointcommand[0]
: NaN.
- All other indices/fields are set as NaN.
A planner that implements this interface must:
- Emit setpoints at more than 2Hz when receiving messages from PX4. PX4 will enter Hold mode if no message is received for more than 0.5s.
- Mirror back setpoints it receives when it doesn't support planning for the current vehicle state (e.g. the local planner would mirror back messages sent during safe landing, because it does not support Land mode).
PX4 safely handles the case where messages are not received from the offboard system:
- If no planner is running and
COM_OBS_AVOID
is enabled at/from boot:- preflight checks will fail (irrespective of vehicle mode) and it won't fly until
COM_OBS_AVOID
is set to 0.
- preflight checks will fail (irrespective of vehicle mode) and it won't fly until
- If no planner is running and
COM_OBS_AVOID
is enabled after boot:- the vehicle will run normally in manual modes
- if you switch to an autonomous mode (e.g. Land Mode) it will immediately fall back to Hold mode.
- When external path planning is enabled
- if the
HEARTBEAT
is lost PX4 will emit a status message (which is displayed in QGroundControl) stating either "Avoidance system lost" or "Avoidance system timeout" (depending on the vehicle state). This is irrespective of the current flight mode. - if a trajectory message is not received for more than 0.5 seconds and the vehicle is in an autonomous mode (Return, Mission, Takeoff, Land), the vehicle will switch into Hold mode.
Note A planner must always provide points in this timeframe.
- A planner will mirror back setpoints it receives when the vehicle is in a mode/state for which it doesn't provide path planning. (i.e. the vehicle will follow its desired path, delayed by a very small amount).
- if the
If the obstacle avoidance interface is enabled, it can also receive mavlink messages in the TRAJECTORY_REPRESENTATION_BEZIER format. This is parsed as follows:
- The number of Bezier control points determines the degree of the Bezier curve. For example, 3 points makes a quadratic bezier curve with constant acceleration.
- The Bezier curve must be the same degree in x,y,z and yaw, with all Bezier control points finite
- The
delta
array should have the value corresponding with the last Bezier control point indicate the duration that the waypoint takes to execute the curve to that point, from beginning to end. Other values in thedelta
array are ignored. - The timestamp of the mavlink message should be the time that the curve starts, and communication delay and clock mismatch will be compensated for on the flight controller via the timesync mechanism.
- The control points should all be specified in local coordinates.
- Bezier curves do not only expire after 0.5s like the waypoint interface, but also after the execution time of the bezier curve has been reached. Be careful not to specify such short times for the bezier curve that you cannot send the next one in time.
Tested companion computers and cameras are listed in PX4/avoidance.