common: extend MISSION_CURRENT

[julianoes]

The message MISSION_CURRENT is a bit limited as it sends the current mission item sequence but no context.

My proposition would be to include the total as well as the status of an ongoing mission.

Related to #1868.

[hamishwillee]

@peterbarker Would appreciate your comment on this.

At the moment you can infer some of the states of the mission from the mode (particularly in ArduPilot where pause is a sub mode of auto). This is not so easy in PX4 where "pause = hold mode" (except after an "autocontinue" pause). I don't think it is easy in either case to know if a mission has actually completed.

So this adds state information to the MISSION_CURRENT, along with the total number of mission items, so a user doesn't need to separately query the mission for that.

[hamishwillee]

Mission states are a little complex and we may need to rethink this to make sure that we're sending the right information. What that information depends on who/how this is consumed. In summary though

Summary, IMO

• States reflect mission engine when it is running: unknown, no-mission, not-started, active, paused, finished.
• If you're in another mode the mission engine is "suspended" - this is a useful distinction or you need to have multiple states to also cover the suspended case. You might infer this from the current mode, but I think we should expose this as a field to avoid the system having to know anything about autopilot modes. It is effectively "not mission mode or submode".

This is a change from having an option "Paused not in auto". There is a difference between saying "Pausing a mission mission moves it into hold mode" and "PX4 implements pause as hold". I THINK we are the former - certainly the mode is advertised as Hold in QGC.

Make sense? There is some useful info about what the systems do below.

---

TLDR;

The "reality" is that we have a mission state machine that might have states "like[+]":

• mission not uploaded
• mission not yet started - mission uploaded and all jump counters[++] reset. But has not yet been started.
• mission running - mission is executing mission items
• mission paused - mission is pausing within the context of the mission mode - ie in a submode.
• mission complete - stopped

[+]: I say "like" because some implementations use the same "state" mission stopped for mission not yet started and complete. Further, plane does not support paused, even in theory.
[++] Jump counters are separate from state.

Then on top of this we have the case where a mission may be suspended - i.e. you're in another mode like "Hold". In this case. The mission is not running at all but the state still exists and might be re-entered.

ArduCopter matches those states precisely (as sub modes).

• so if you are paused you're still in mission mode. If moving you'll move to a graceful stop.
• If you leave the mission to another mode it is suspended. Say you move to hold, you'd immediately hold rather than gracefully stop.
• FYI you can't start mission from the initial state by calling the set mission current
• ArduPilot does not implement autocontinue flag.

ArduPlane does not implement the mission paused state; you cannot pause mission, you can only suspend it by changing mode.

• The pause/continue command is not implemented because it doesn't make sense with this paradigm. Though continue might, if we assumed that this also requires a switch-to-mode.
• If you run out of items in the mission (complete) the internal state changes to mission-stop and the mode is forced to RTL. Sending message to set the current mission item sets the state back to active - you then have to change the mode back to resume.
• The plane never wants to say it is paused.
• The plane state is almost completely inferrable - you're either in mission mode and executing or stopped or you are in some other mode.
• FYI if in auto you calling the set mission current will start the mission. But semantically being in auto means "you're running the mission" on plane, so this is expected.

PX4 does a mix of these two, implementing both pause sub modes and emulating pause-as-switch to mode:

• It has mission sub mode for the pause state when autocontinue=false
• It has mission sub mode for the complete state (right?).
• Pausing a mission is implemented as moving to hold mode. But this is not done using a pause, but using a do_reposition.
• Restarting a mission is implemented as moving back to mission mode.
• Not sure/ do we know how PX4 sees an explicit mode change vs pause when running a mission? i.e. does it think of itself as in hold mode, or does it somehow know that actually it is in a paused mission mode?

So:

• Arduplane might want to output states: unknown, no-mission, not-started, active, complete (internally, both "not started" and "complete" are "stopped").
• ArduCopter and PX4 might want to output states: unknown, no-mission, not-started, active, paused, finished.

[hamishwillee]

@julianoes Do you think this needs to be an enum?

[hamishwillee]

@julianoes @tridge I updated so all fields are 0 for the default "not supported" case.

In addition, have modified the reporting of state in line with the notes above. It now reports state using two fields. The first is the state of the mission state machine. The second is whether or not the mission is suspended (worded as whether it is in mission mode or not). That allows a recipient to absolutely know the what the mission state is.

Is it worth considering also reporting on whether jump counters are reset? If so, would making the last byte into an set of flags that includes suspended and jump counters be a better implementation?

[tridge]

@hamishwillee thanks for the changes, looks much better

This was addressed

[hamishwillee]

As discussed in dev call, this has been reviewed by ArduPilot and PX4 and can be merged.

Note that this:

• adds extension fields to the previous mission in a way such that there is no change for systems that have not updated to emit the new information.
• The previous definition said "emit on changed waypoint" while the new one says "stream". This reflects what both PX4 and ardupilot actually do. It is not inconceivable some other system might have implemented this exactly per the old spec.

Thanks for this @julianoes , and @tridge for helping me understand how ArduPlane works with missions.

[hamishwillee]

FYI @TSC21