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

Mission service - add section on mission execution #529

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open

Mission service - add section on mission execution #529

Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5b7fb1d
Add section on mission execution
hamishwillee Feb 29, 2024
0dafb8b
Apply suggestions from code review
hamishwillee Mar 5, 2024
b3cedb1
Update en/services/mission.md
hamishwillee Mar 5, 2024
8de8ed0
Update en/services/mission.md
hamishwillee Mar 5, 2024
48126d8
Update en/services/mission.md
hamishwillee Mar 5, 2024
7dd38c1
Apply suggestions from code review
hamishwillee Mar 5, 2024
89ef2e2
Restructure so exceptions on resetting can be grouped
hamishwillee Mar 6, 2024
39df0b2
Simplify introduction
hamishwillee Mar 6, 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
49 changes: 49 additions & 0 deletions en/services/mission.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -379,6 +379,55 @@ Note:
- [timeouts](#timeout) are not considered errors.
- Out-of-sequence messages in mission upload/download are recoverable, and are not treated as errors.

## Executing Missions

Following full mission upload, or vehicle restart, or mission reset, all jump counter loops are set to their initial values.
The current mission item is normally reset to one on mission reset or vehicle restart, or on mission upload when the vehicle is landed.
The current mission item may retain its current value if a mission is uploaded in-air or it may be set to the mission item that has `current` set in a mission item (this field is ignored in ArduPilot but respected by PX4).

For a mission to be executed the vehicle must be armed and in the flight stack's mission mode.
There may (or may not) be further requirements to start a mission.
For example PX4 will start as soon as you arm in mission mode, while ArduCopter in its default configuration requires that the throttle is raised.
Similarly, planes that are configured for throttle/hand launch may require a minimum acceleration before the mission is executed.
While executing, the vehicle will progress sequentially through the mission items, looping and jumping in response to jump commands.

The mission can be paused by changing to another flight mode, such as Hold/loiter, and restarted by changing back to mission mode (when armed).
On restart the vehicle will _generally_ continue towards the same waypoint item as when it was paused.
In some cases flight stacks may start from the preceding waypoint, for example, a paused camera survey may restart on the previous waypoint to ensure the whole paused leg is captured.
Note that there is no concept of "stopping" a mission independent of pausing it.

On completion of all mission items the mission will "complete".
At this point some flight stacks will loiter within the mission mode, while others will transition to some other mode (such as "Hold") and not allow you to return to mission mode.
In either case, the mission cannot be restarted unless it is [reset](#resetting-missions) (which usually happens after the vehicle lands and disarms).
hamishwillee marked this conversation as resolved.
Show resolved Hide resolved

While the mission is executing the current mission item can be changed via MAVLink ([MAV_CMD_DO_SET_MISSION_CURRENT](#MAV_CMD_DO_SET_MISSION_CURRENT)).
Note however that this does not reset the jump counters, and if the mission is complete, will not restart the mission.
hamishwillee marked this conversation as resolved.
Show resolved Hide resolved

### Starting Missions

A flight stack will usually run mission checks before allowing a vehicle to enter the mission executing mode (typically checks are run when first executing a mission, but some flight stacks might also check before continuing a paused mission).

Provided the checks pass, you can start a mission by either switching to mission mode and arming, or arming and switching to mission mode.
With mavlink we can change the mode using [MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE) to set the mode and ARM using[MAV_CMD_COMPONENT_ARM_DISARM](../messages/common.md#MAV_CMD_COMPONENT_ARM_DISARM).

If supported the [MAV_CMD_MISSION_START](../messages/common.md#MAV_CMD_MISSION_START) command will both arm the vehicle (if necessary) and switch to the mission mode.
This command also allows you to specify a particular start and end item in the mission.

### Pausing/Stopping Missions
Copy link
Contributor

Choose a reason for hiding this comment

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

I find it very strange that there's no coverage of MAV_CMD_DO_PAUSE_CONTINUE here! That's the more appropriate malvink-ish way of doing this behaviour, I'd think.

Saying "do-set-mode" won't always stop the vehicle from executing waypoints - for example, ArduPlane when you've got a DO_LAND_START. If you switch modes to RTL it's essentially the same thing as changing waypoints - the Plane will jump to its landing sequence.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I find it very strange that there's no coverage of MAV_CMD_DO_PAUSE_CONTINUE here! That's the more appropriate malvink-ish way of doing this behaviour, I'd think.

Doh. That's my brain fade. Thanks. Will fix.

Saying "do-set-mode" won't always stop the vehicle from executing waypoints - for example, ArduPlane when you've got a DO_LAND_START. If you switch modes to RTL it's essentially the same thing as changing waypoints - the Plane will jump to its landing sequence.

@peterbarker This is true on PX4 too but there is a nuance that waypoints are being executed but you're still in Return mode, not mission mode. Is it the same on ArduPlane?

The TLDR here is that PX4 RTL has settings to execute a return mode landing following a mission landing pattern. So you are following waypoints, but you're not in a mission.

Copy link
Contributor

Choose a reason for hiding this comment

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

@peterbarker This is true on PX4 too but there is a nuance that waypoints are being executed but you're still in Return mode, not mission mode. Is it the same on ArduPlane?

I believe so. Unless behaviour has changed the vehicle will briefly appear to go into RTL mode but will then appear to go back to AUTO mode.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@peterbarker What if you're not in auto mode to start with - will it go to RTL mode and still then go to AUTO mode to do the landing? That seems odd if the intent was to RTL.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

In any case, fixed.


Pause and stop missions by changing mode.
In MAVLink this can be done using [MAV_CMD_DO_SET_MODE](../messages/common.md#MAV_CMD_DO_SET_MODE) (generally a vehicle will also support changing modes via an RC controller/joystick too).
hamishwillee marked this conversation as resolved.
Show resolved Hide resolved

### Resetting Missions

Once a mission has started it will iterate through the mission items, jumping and looping as indicated by jump mission items, until it completes.
While the mission is running you can change the current mission item, but this does not by reset the jump counters used for loops, and once the mission is complete, changing the current mission item will not restart it (with an exception outlined below).

The mission will reset after you land and the vehicle disarms.
Copy link
Contributor

Choose a reason for hiding this comment

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

Are you sure?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I thought so. What did you think - only on reboot?

Copy link
Contributor

Choose a reason for hiding this comment

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

On reboot for sure.

Copy link
Contributor

Choose a reason for hiding this comment

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

And on re-upload, or manual reset to 0.

Copy link
Contributor

Choose a reason for hiding this comment

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

ArduPlane will not reset counters if you land the vehicle in auto. It's a bit more complicated because some missions have the vehicle land and disarm, but then be able to resume the mission from where they are in their sequence when they're armed in auto again.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

And on re-upload, or manual reset to 0.

@julianoes Just to be clear,

  • I understand reupload on the ground will reset the counters and the current waypoint.
  • For upload in air the current waypoint does not change right? On PX4 you "finish the previously uploaded waypoint" and then the waypoint number increments and you progress to that waypoint in the newly uploaded mission.

On manual reset to 0

What do you mean by this? Is this the same as ArduPilot - setting mission current to 0 resets the whole mission? If so, that would be good.

ArduPlane will not reset counters if you land the vehicle in auto. It's a bit more complicated because some missions have the vehicle land and disarm, but then be able to resume the mission from where they are in their sequence when they're armed in auto again.

@peterbarker Thanks very much. This caveat is true of all PX4 vehicle too - its a configuration setting or a mission type setting. I will add a comment.

Copy link
Contributor

Choose a reason for hiding this comment

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

For upload in air the current waypoint does not change right? On PX4 you "finish the previously uploaded waypoint" and then the waypoint number increments and you progress to that waypoint in the newly uploaded mission.

This is ground station dependent. I think QGC does that. But if you just upload the whole mission, it will go back to 0.

setting mission current to 0 resets the whole mission? If so, that would be good.

I think so, except things like DO_JUMP counters.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@julianoes

I think so, except things like DO_JUMP counters.

So it will remove the "complete" bit and restart the mission, but with the wrong counters? That's screwed up. Can we make it also reset the counters? (i.e. as part of this protocol) and make not resetting them non-standard.

FYI also @peterbarker my concern here is that we updated MAV_CMD_DO_SET_MISSION_CURRENT to add a reset option because there was not way to reset the counters. Now it seems like setting the mission item to 0 would do this. That's a better approach. So we should standardize.
I.e. I think we'd be best off removing that separate parameter and stating that setting to zero should reset the counters and the complete bit and reset to zero. Thoughts?

Copy link
Contributor

Choose a reason for hiding this comment

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

So it will remove the "complete" bit and restart the mission, but with the wrong counters? That's screwed up. Can we make it also reset the counters? (i.e. as part of this protocol) and make not resetting them non-standard.

That's the way I made it in 2013 or so. It might have been fixed since. You could try it out...

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I doubt it. In any case, Peter commented somewhere here he prefers that counters are reset explicitly. So we probably need to implement that second parameter. I looked at it once but couldn't work out the right place to even add the command.

It is also reset following a vehicle reboot.

[MAV_CMD_DO_SET_MISSION_CURRENT.param2](../messages/common.md#MAV_CMD_DO_SET_MISSION_CURRENT) can also be used to reset the mission, if supported on the flight stack.

## Mission File Formats

The _defacto_ standard file format for exchanging missions/plans is discussed in: [File Formats > Mission Plain-Text File Format](../file_formats/README.md#mission_plain_text_file).
Expand Down