Skip to content

Mission item - separate out to own doc - #761

Open
hamishwillee wants to merge 6 commits into
masterfrom
pr_mission_item_docs
Open

hamishwillee wants to merge 6 commits into
masterfrom
pr_mission_item_docs

Conversation

@hamishwillee

Copy link
Copy Markdown
Collaborator

This add docs for behaviour of mission items.

It pulls the loiter ones that were already documented and adds some waypoint and condition gate.

@peterbarker The gate thing is quite different from a waypoint - its not on the path.

@peterbarker

Copy link
Copy Markdown
Contributor

Could I suggest move then modify. Or modify then move. I think some of the changes make ArduPilot non-compliant.

Also, I don't think ArduPilot's even remotely close to being compliant with some of the diagrams in here :-)

@hamishwillee

hamishwillee commented Sep 11, 2026 •

Copy link
Copy Markdown
Collaborator Author

@peterbarker Except for he waypoint doc, nothing that changed has is different meaning - all I did was split the loiter doc, asking claude to reproduce the content in sections. So in theory only the Waypoint bit needs checking.

In addition, this exactly reproduces the spec for the params. Again, non compliant before, still not compliant and so on.

I don't want to move then redo this but I will confirm any divergence from the spec terms and write tests that verify the loiter and waypoint behave is as documented (or not).

@peterbarker

Copy link
Copy Markdown
Contributor

Sorry, but you're not just moving stuff. You're rewording and changing the meanings.

I'm not saying don't do both - just don't do them in the same commit - especially when you're accidentally changing things....

1 — Hovering vehicles must now circle for LOITER_TURNS

Before:

Loiter commands are provided to allow a vehicle to hold at a location for a specified time or number of turns, until it reaches the specified altitude, or indefinitely.
Multicopter vehicles stop at the specified point (within a _vehicle-specific_ acceptance radius that is not set by the mission item).
Forward-moving vehicles (e.g. fixed-wing) _circle_ the point with the specified radius/direction.

After:
A fixed wing vehicle will fly a circle circle.
A hovering vehicle that implements this command is also expected to circle at the given radius (for other loiter commands they would hold in place).

2 — Heading Required / Xtrack extended to LOITER_TO_ALT

Before:

::: info
The remaining parameters (xtrack and heading) apply only to forward flying aircraft (not multicopters!)
:::
Xtrack and heading define the location at which a forward flying (fixed wing) vehicle will _exit the loiter circle, and its path to the next waypoint_ (these apply only to `MAV_CMD_NAV_LOITER_TIME` and `MAV_CMD_NAV_LOITER_TURNS`).

After (shared exit-conditions section, incl. the softened "not multicopters!" note):
#### Exit Conditions: Heading Required & Xtrack Location {#loiter_exit}
::: info
Heading Required and Xtrack Location apply to forward-flying aircraft; for multicopters they only matter where the vehicle actually circles.

After (now referenced from LOITER_TO_ALT):
[MAV_CMD_NAV_LOITER_TO_ALT](../messages/common.md#MAV_CMD_NAV_LOITER_TO_ALT) loiters at the specified latitude/longitude — or, if both are `0`, at the current position — until the target altitude is reached, then the mission advances (subject to the [exit conditions](#loiter_exit) above).

| 1: Heading Required | Leave the loiter circle only once heading towards the next waypoint (`0` = leave once altitude is reached). See [Exit Conditions](#loiter_exit) above. | min:0 max:1 increment:1 |
| 2: Radius | Loiter radius for forward-only moving vehicles (not multicopters). Positive: clockwise, negative: counter-clockwise; `0` means no change to the standard loiter radius. | m |
| 3 | Empty. | |
| 4: Xtrack Location | Exit location and path to the next waypoint. See [Exit Conditions](#loiter_exit) above. | min:0 max:1 increment:1 |

3 — LOITER_UNLIM direction correction

Before:

- [MAV_CMD_NAV_LOITER_UNLIM](../messages/common.md#MAV_CMD_NAV_LOITER_UNLIM) - Loiter at specified location for an unlimited amount of time, yawing to face a given direction.

The direction of loiter for `MAV_CMD_NAV_LOITER_UNLIM` can be set using `param4` (Yaw).

After (no counterpart — claim deleted; nearest text):
[MAV_CMD_NAV_LOITER_UNLIM](../messages/common.md#MAV_CMD_NAV_LOITER_UNLIM) loiters at the specified location indefinitely — nothing in the mission item itself ends the loiter.

| 3: Radius | Loiter radius for forward-only moving vehicles (not multicopters). Positive: clockwise, negative: counter-clockwise. | m |
| 4: Yaw | Desired yaw angle. `NaN` to use the current system yaw heading mode. | deg |

@hamishwillee

hamishwillee commented Sep 12, 2026 •

Copy link
Copy Markdown
Collaborator Author

@peterbarker Thank you. Absolutely. I've redone the copied bits from scratch in separate commits - created this with the new waypoint and gate commands, then asked it to copy the loiter docs verbatim, then asked it to split them extending them into 4 sections using only existing text and coping the param table text - fetching from XML for anything missing. The last changes is more or less hand coded by me to improve the English and add some placeholders for future support statements.

To reduce the chance of this happening again I'll add a CLAUDE.md to the repo that requires evidence/assertions based on XML or test results for any change, and separate commits.

I'm also writing tests for these, so we'll have a more precise implementation section coming.

Please check again.

PS Another commit added with consistency fixes following running the pr review - to catch inconsistency and assertions that are unproved. I've commented some of those.

| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| 1: Hold | Hold time (ignored by fixed-wing; time to stay at the waypoint for rotary-wing). | s |
| 2: Accept Radius | Acceptance radius — the "reached" trigger described above. | m |
| 3: Pass Radius | 0 to pass through the WP, if > 0 radius to pass by WP. Positive value for clockwise orbit, negative value for counter-clockwise orbit. Allows trajectory control. | m |

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

FYI I need to test how Pass Radius works. Fixed this back to XML and commented out section on this.

@hamishwillee

Copy link
Copy Markdown
Collaborator Author

@peterbarker Any chance of a re-review?

hamishwillee and others added 6 commits November 9, 2026 08:32
Adds the new Mission Item Detail page with the MAV_CMD_NAV_WAYPOINT
and MAV_CMD_CONDITION_GATE sections, and registers the page in
SUMMARY.md. The Loiter commands (currently documented in
mission.md) will be moved across in a follow-up commit.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MGievqkKSBz7ke63mjZXdj
Copies the "Loiter Commands" section from mission.md into
mission_item_detail.md unchanged (still covering all four
MAV_CMD_NAV_LOITER_* commands together), and replaces it in
mission.md with a pointer to the new page. Splitting the section
into one subsection per command follows in a separate commit.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MGievqkKSBz7ke63mjZXdj
Splits the combined Loiter Commands section into a subsection per
MAV_CMD_NAV_LOITER_* command, matching the structure already used
for MAV_CMD_NAV_WAYPOINT and MAV_CMD_CONDITION_GATE.

Per-command param tables reuse the exact original wording where the
old combined tables documented that param (radius/lat/lon/alt for
all four commands; heading required/xtrack for LOITER_TIME and
LOITER_TURNS only, matching the original's stated scope). Where the
original had no table text for a field (LOITER_TIME/TURNS param 1,
LOITER_TO_ALT's params, LOITER_UNLIM's params 1/2/4), the
corresponding MAV_CMD_NAV_LOITER_* description is taken from the
XML-derived message reference instead.

The shared exit-conditions explanation is kept, unchanged, under
LOITER_TIME (its original scope), with LOITER_TURNS linking to it.
No wording is otherwise reworded, corrected, or extended in this
commit - see follow-up discussion for suggested improvements found
while doing this split.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MGievqkKSBz7ke63mjZXdj
- Add "See Exit Conditions" links from LOITER_TO_ALT's Heading
  Required and Xtrack Location params: both fields are defined in
  the XML for this command, so the link is a protocol-level fact
  regardless of whether a given autopilot actually honors them.
- Reformat LOITER_TIME/LOITER_TO_ALT/LOITER_TURNS wording and merge
  the LOITER_TO_ALT NOTE per hand edits.
- Replace the unverified LOITER_TIME/LOITER_TO_ALT Autopilot Support
  claims with a commented-out "Untested" placeholder: none of that
  wording was backed by testing or a source citation, so it
  shouldn't be asserted as fact until it is.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MGievqkKSBz7ke63mjZXdj
Works through the mavlink-command-review skill's report on this
page:

- Fix the Exit Conditions scope contradiction: it now correctly
  names LOITER_TO_ALT alongside LOITER_TIME/TURNS, with anchor
  links to all three headings.
- Revert the LOITER_TURNS "multicopters circle" claim (uncited,
  contradicted the XML and every sibling section) - no vehicle-type
  claim is made in that intro anymore, and its Radius description
  no longer implies an answer either way.
- Comment out claims added by Claude with no supporting evidence
  (NaN-altitude validation, the whole Pass Radius subsection incl.
  its Autopilot Support bullets) rather than publish them as fact.
- Fix a dangling #pass_radius link left over from commenting out
  its target heading, and a "loiter.radius" typo.
- Standardize formatting: Autopilot Support heading capitalization,
  empty-param notation ("-"), min/max/increment notation, added
  Units columns to the WAYPOINT/GATE Params tables, and reworded
  LOITER_UNLIM's intro line to match its siblings.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MGievqkKSBz7ke63mjZXdj
The trigger line was documented and drawn as perpendicular to the
inbound path, anchored at the gate. Source (PX4 mission_block.cpp's
NAV_CMD_CONDITION_GATE branch) shows it's actually perpendicular to
the vector from the gate to the *next waypoint* -- not to the path.
For an off-path gate these differ measurably (confirmed by flight
telemetry against real PX4 SITL), so the diagram's marked crossing
point was geometrically wrong. Redrawn to show the gate->next-waypoint
reference vector and the true perpendicular trigger line, and reworded
the prose and the Geometry param description to match.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017VNs1WcVq23Y3tFbT3bidX
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants