docs(offboard): clarify BODY_NED velocity/acceleration-only support#27806
docs(offboard): clarify BODY_NED velocity/acceleration-only support#27806mrpollo wants to merge 1 commit into
Conversation
… setpoints only BODY_NED position setpoints have never been supported: the receiver rotates velocity and acceleration into the local frame and sets position to NAN, and for fixed-wing (position setpoints only) the frame cannot be used at all. The docs listed input combinations and coordinate frames as independent lists, implying every combination works in every frame, which misled users into filing #27617. Also update stale code links still pointing at FlightTaskOffboard.cpp, removed in the v1.12 offboard rework (#16739). Signed-off-by: Ramon Roche <mrpollo@gmail.com>
|
No broken links found in changed files. |
|
|
||
| - PX4 supports the coordinate frames (`coordinate_frame` field): [MAV_FRAME_LOCAL_NED](https://mavlink.io/en/messages/common.html#MAV_FRAME_LOCAL_NED) and [MAV_FRAME_BODY_NED](https://mavlink.io/en/messages/common.html#MAV_FRAME_BODY_NED). | ||
| - PX4 supports the coordinate frame (`coordinate_frame` field): [MAV_FRAME_LOCAL_NED](https://mavlink.io/en/messages/common.html#MAV_FRAME_LOCAL_NED). | ||
| [MAV_FRAME_BODY_NED](https://mavlink.io/en/messages/common.html#MAV_FRAME_BODY_NED) only applies to velocity and acceleration setpoints, which are ignored for fixed-wing, so it cannot be used. |
There was a problem hiding this comment.
@mrpollo If its all true then what you have done looks good - in particular fixing up links so people can find the source and self-verify.
Needs a technical reviewer though, as Claude seems to think this statement is wrong.
- The BODY_NED / fixed-wing assertion — this is incorrect
The claim "MAV_FRAME_BODY_NED only applies to velocity and acceleration setpoints, which are ignored for
fixed-wing, so it cannot be used" does not hold up against the current code.
Fixed-wing offboard is handled by src/modules/fw_mode_manager/FixedWingModeManager.cpp (not the navigator —
offboard falls through to a no-op there), which subscribes directly to trajectory_setpoint and does consume
velocity and acceleration (lines ~2123–2189):
- velocity[0]/[1] → written to _pos_sp_triplet.current.vx/vy, and combined with acceleration to compute a
signed loiter_radius (turn curvature) via a velocity/acceleration cross-product (lines 2154–2173). - velocity[2] → vz (height rate).
- If lat/lon and vx/vy are both finite, set_control_mode_current() (lines 387–399) selects
FW_POSCTRL_MODE_AUTO_PATH — literally commented "Offboard position with velocity setpoints" — which feeds
velocity_2d and the acceleration-derived curvature into navigatePathTangent(). - There's also a dedicated SETPOINT_TYPE_VELOCITY → control_auto_velocity() path for velocity-only setpoints.
This isn't new or experimental — it traces back through fw_pos_control_l1/fw_pos_control history and was
touched as recently as 2026-06-08 and 2026-06-25 (bug fixes to this exact logic), so it's actively maintained,
shipping behavior.
Practical implication: send SET_POSITION_TARGET_LOCAL_NED with MAV_FRAME_BODY_NED and only
velocity+acceleration set (position is always forced to NAN in this frame by the mavlink receiver) —
fixed-wing will actually fly a curved path/velocity setpoint from it, not ignore it.
Worth noting: the pre-existing (unchanged by this PR) line just above — "Position setpoint (x, y, z only;
velocity and acceleration setpoints are ignored)" — has the same underlying error: even when position and
velocity/acceleration are all sent together, FW doesn't ignore the velocity/acceleration; it switches to the
AUTO_PATH mode using them. So this commit's fix is built on top of an already-incorrect premise in the doc,
and ends up repeating rather than correcting it.
Recommendation: before merging, this line needs a rewrite reflecting that FW offboard does use velocity (as
path tangent) and acceleration (as curvature feedforward) via FixedWingModeManager, and the pre-existing
"ignored" line nearby should likely be fixed in the same PR since it's the same misconception. Want me to
draft corrected wording for both spots?
The offboard docs list the supported SET_POSITION_TARGET_LOCAL_NED input combinations and the supported coordinate frames as two independent lists, which reads as if every combination works in every frame. It doesn't: BODY_NED position setpoints have never been supported. The receiver rotates velocity and acceleration setpoints into the local frame and sets position to NAN, a behavior that predates the v1.12 offboard rework (#16739) and was kept there deliberately. This mismatch misled the reporter of #27617 into filing the works-as-designed behavior as a firmware bug.
The rover section already scopes BODY_NED to velocity setpoints correctly and is unchanged.