Skip to content

docs(offboard): clarify BODY_NED velocity/acceleration-only support#27806

Open
mrpollo wants to merge 1 commit into
mainfrom
mrpollo/docs-offboard-body-ned
Open

docs(offboard): clarify BODY_NED velocity/acceleration-only support#27806
mrpollo wants to merge 1 commit into
mainfrom
mrpollo/docs-offboard-body-ned

Conversation

@mrpollo

@mrpollo mrpollo commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

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.

  • Copter/VTOL: add an info block stating BODY_NED only applies to velocity and acceleration setpoints and that position setpoints must use LOCAL_NED.
  • Fixed-wing: remove BODY_NED from the supported frames, since fixed-wing offboard only accepts position setpoints, which that frame cannot carry.
  • Update stale code links still pointing at FlightTaskOffboard.cpp, removed in 2021.

The rover section already scopes BODY_NED to velocity setpoints correctly and is unchanged.

… 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>
@github-actions

github-actions Bot commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

@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.


  1. 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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

kind:chore Maintenance work that keeps the project healthy. scope:docs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants