Protocol-level discovery which mission items / commands are supported by an autopilot

[LorenzMeier]

Currently there is no formal way on the protocol level to establish which commands are supported by an autopilot, which makes it hard for a GCS to e.g. hide commands from the UI that are not implemented. A draft is being worked on in this document:

https://docs.google.com/document/d/1wETCft5N7IN4iR9NhfG9cI_fMvlG1PvCXXOPwxSEwGE/edit#heading=h.t3uczm564nmc

@julianoes @hamishwillee Let's have the discussion on the content here and comment in the doc only on implementation specifics.

[DonLakeFlyer]

I would like to see this tie into a higher level concept of asking the vehicle for all of it's known information. Something like:

• Ask a component for it's known information
• There is mavlink spec for the various parts of that which are standard:
  • Supported commands
  • Detailed command information such that gcs can generate ui
  • Flight dynamics
  • Parameter meta data
• The file formats for these things are spec'ed. Json, binary, whatever.
• A gcs can then pull the information from the vehicle through an FTP URL or maybe even a web based url as appropriate
• And there needs to be some caching mechanism for each such that a gcs can know it already has up to date info in it's own cache or not

I see the higher level umbrella support as important to work through such that it can then support any sort of vehicle factoid with supported commands being only a single example.

[DonLakeFlyer]

• Detailed command information such that gcs can generate ui

FYI: The QGC implementation of this is doc'ed here: https://dev.qgroundcontrol.com/en/plan/MissionCommandTree.html. All of which should be mavlink spec somehow, since it doesn't make sense for a gcs to have this level of metadata hardcoded into it.

[DonLakeFlyer]

Quick and dirty explanation of top level metadata query mechanism.

Each metadata type format is spec'ed out as part of the mavlink spec:

COMPONENT_METADATA_TYPE enum
	AVAILABLE_TYPES: List of types which the vehicle can provide. FTP download only.
	SUPPORTED_COMMANDS_TYPE: Above thing
	PARAMETER_METADATA_TYPE
        COMMAND_UI_INFO_TYPE: This stuff https://dev.qgroundcontrol.com/en/plan/MissionCommandTree.html
        ...

Ask the vehicle for some metadata:

REQUEST_COMPONENT_METADATA
	type: COMPONENT_METADATA_TYPE

Vehicle responds with:

COMPONENT_METADATA
	type: COMPONENT_METADATA_TYPE
	url:  ftp://foo pull from vehicle, http://foo pull from web
        id:   Hash/CRC whatever id we can be used to check if gcs cached data is stale

So a GCS would first ask for AVAILABLE_TYPES to understand what is available. It would then query specific information.

This isn't meant to be even remotely close to complete. It is just meant to explain the concept of a possible high level metadata discovery mechanism.

[hamishwillee]

@julianoes @LorenzMeier When you look at it this way, then the proposal becomes a component definition file returned by COMPONENT_INFORMATION. I like that more because then when we get a new information type we're discussing what information is useful, not what mechanisms are used to get it.

To make this work as @DonLakeFlyer indicates we would need to add support for

• requesting a particular type of information
• a hash for that type of requested information.

Looking at that message I also wonder if we should future proof the size of the capability_flags - perhaps by having the metadata in the returned component file instead.

Then the first XML type definition might be as discussed with @julianoes (shown in JSON, but we need to agree formats)

"mission_items": 
{
"version": "1.0"
	{
	"21": {
		"supported_params": 8
	},
	"22": {
		"supported_params": 8
	},
       ...
}

Don, I can see this helping us with getting some of those other defaults we talked about like default cruise speed. However it isn't a full solution because some things like default yaw in missions can change dynamically without a reboot. So for those we will still need a mechanism to be able to query explicitly and be notified on change.

[olliw42]

I'm glad to see that COMPONENT_INFORMATION is being mentioned here. In fact, I was trying to promote this mechanism (and failed). It would be great if it's potential would be started to be exploited. ;)

The same mechanism could be used e.g. for

• retrieving meta data on parameters
• retrieving which mission items/commands are supported/available
• retrieving which flight modes are supported/available
• retrieving which prearm states are supported/available
• .....

and all this info could be used by a GCS in a generic way to be displayed and handled in a generic way.

Don't reinvent a new wheel for each problem which conceptually are of similar nature. One good wheel is more worth than many not so good wheels :)

[DonLakeFlyer]

Don, I can see this helping us with getting some of those other defaults we talked about like default cruise speed. However it isn't a full solution because some things like default yaw in missions can change dynamically without a reboot. So for those we will still need a mechanism to be able to query explicitly and be notified on change.

This is correct.

[hamishwillee]

@julianoes Worth checking #1339 (comment) to see if we need more than just the supported parameters captured.

I am pretty sure that we do not - the vehicle specific parameter stuff will be captured by what we are doing. The other metadata like labels, defaults etc is already in the XML definitions - it is just up to GCS to start using it.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. Thank you for your contributions.

[hamishwillee]

@julianoes In another discussion it came up that we don't know whether a flight stack supports terrain following for mission items with positional information. More generally we don't know anything about any of the frames.

Does it make sense to include this in the metadata?

"mission_items": 
{
"version": "1.0"
	{
	"21": {
		"supported_params": 8,
		"supported_frames": "1, 3 ,4"
	},
	"22": {
		"supported_params": 6,
		"supported_frames": "1, 4, 6"
	},
       ...
}

Though perhaps systems generally only support all of a particular set so we could have a default "supported_frames" that gets over-ridden.

"mission_items": 
{
"version": "1.0"
	{
        "supported_frames": "1, 3 ,4",
	"21": {
		"supported_params": 8
	},
	"22": {
		"supported_params": 6,
		"supported_frames": "1, 4, 6"
	},
       ...
}

Or more generally, how would you solve this problem Don and Julian

[DonLakeFlyer]

I don't think you can add this to the metadata. The metadata can only support information which is constant. For example in ArduPilot terrain support is turned on/off through a parameter. Or at least it won't solve the terrain frame problem.

[hamishwillee]

@DonLakeFlyer Is that parameter something that requires a reboot? If so then that does not invalidate this approach.

If it does, then that concerns me. We assume that following a reboot we can trust the metadata to be correct for what is supported by the vehicle. Though I guess that is not entirely true - you didn't see the value of tracking mode support for command protocol metadata, and that is a clear case where we say something is supported, but in a particular mode it might not be.

Anyway, my gut feeling is that it is useful for the GCS to know that a set of frames is supported/not supported by the autopilot "in general" so that it doesn't try things that are definitely not supported. What do you think?

For the terrain problem then we might emit a (new) message when the parameter changes.

[DonLakeFlyer]

Is that parameter something that requires a reboot?

Not according to the meta data. Which in turn makes a capability bit for it useless as well since those are only queried at initial connect/

[julianoes]

I think the GCS should be able to determine whether terrain following is possible by looking at MAV_PROTOCOL_CAPABILITY_TERRAIN. I know that's not the same data source but at least it makes the current problem easier.

Also, in case a mission is uploaded with a wrong frame, this can be nacked with MAV_MISSION_UNSUPPORTED_FRAME.

[DonLakeFlyer]

whether terrain following is possible

Which means what in terms of mavlink spec?

• Terrain frame is supported?
  or
• Terrain tile upload is supported?
  or
• Both?

[hamishwillee]

I interpret the spec right now as MAV_PROTOCOL_CAPABILITY_TERRAIN meaning "terrain frame using tiles/terrain protocol (only) is supported. However if this is not set the terrain frame may still be supported - ie by a distance sensor. @DonLakeFlyer , I will need your help to clarify what the protocol is in mavlink/mavlink-devguide#259

What I would "like" to do here is re-define the meaning of MAV_PROTOCOL_CAPABILITY_TERRAIN to mean "Terrain frame is supported" and find some other way to indicate that the terrain protocol is supported - e.g. microservices protocol.

Alternatively, maybe add MAV_CAPABILITY_FRAME. Though I still hate that this can't be part of the mission metadata information.

[julianoes]

Ok my bad, I misunderstood the capability flag.

[hamishwillee]

@DonLakeFlyer Discussed in the dev call. Decided we won't change the meaning of MAV_PROTOCOL_CAPABILITY_TERRAIN.

My understanding of your requirement is to be able to know if a vehicle supports the "terrain following frame", irrespective of whether it does this using tiles or distance sensor or whatever.

Some options:

1. What about if we accept that the terrain frame type support might change after boot? So assume we use the XML mission metadata and we see that the frame is not supported. Then the user enables the distance sensor. They still can't do terrain following until they reboot. OR they do have the distance sensor, terrain frame is enabled, and then after they disable it. What will happen?
2. What if we still use metadata but provide an update message when anything in the metadata changed, so the GCS knows it needs to get file again to check this.
3. Dedicated message that can be requested to check the terrain following status, and whenever the status changes.

I think the last option is the most practical, but I really like using metadata, because generally most flight stacks only support a couple of frames, and it makes sense to me that people should be able to easily find that out.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. Thank you for your contributions.

[hamishwillee]

Now the component information infrastructure exists, do we still think the idea of metadata indicating supported MAV_CMDs in missions/commands is a good idea?

• IMO the downside of this is that it is documentation : it would be very easy to make a mistake when creating this data in the first place, and even easier to forget to update "the docs" when you fix it.
• Is slightly wrong information better or worse than no documentation - in particular when a ground station is working with an FC it does not understand?

What are our other options?

• Auditing/test tools that can auto generate the component info
• Add a way to test commands without side effects -so that a command acks with unsupported, approved, or denied (wrong params) but does not do the main action. This might be done by creating a test mode. On an individual basis you might just use an unused param to indicate "test this".
• Similar with mission commands. Define a standard feasibility checker that at least spits out the unsupport mission commands.
• Simplified version that just provides supported or not supported, and not the detail of which params are supported.
• Minimal profiles - agree standard command/mission set and mechanism to determine that it is supported compatibly - then publish that. At least a GCS can rely on this bit to be compatible.

Thoughts?

[stale]

This issue has been automatically marked as stale because it has not had recent activity. Thank you for your contributions.