Message Definitions · Add doc on how to add messages

[hamishwillee]

Message Definitions · MAVLink Developer Guide

Answer questions "what are the requirements for adding messages"/ how do we do it.

In mavlink/mavlink#942 (comment) I suggested:

1. Create a Git PR to put it into https://github.com/mavlink/mavlink/tree/master/message_definitions/v1.0
2. We'd expect the xml file to successfully build (i.e. be compliant with the DTD) and have comment/description about the platform it supports as a comment (ideally with platform URL/contacts).
3. Sensible file name - ie one you can instantly guess platform

Any other requirements?

Todo:

• Add links to instructions in PX4 and in ArduPilot docs for creating a custom message.
  • PX4
  • Ardupilot (?)

[hamishwillee]

• What are the rules for adding new messages in a dialect - ie to avoid clashing with IDs used for common.xml

• What happens if a dialect talks to another dialect? Do they just handle the messages they understand?

[okalachev]

What happens if a dialect talks to another dialect? Do they just handle the messages they understand?

I far as I know, MAVLink works this way by design (because messages have hashes, based on their field names).

[hamishwillee]

Thanks @okalachev - That makes sense if all fields, including the id are hashed. It would mean that if there are id clashes the dialect would understand the message but a library based on common.xml would not.

[hamishwillee]

Also to answer:

When should dialect be created and when should messages just be added to an existing dialect (e.g. common.xml

Confirm:

• PX4 only takes common.xml into core codelines
• Dialect fine for experimentation
• You don't have to share dialect back to the project - when would you do this? I suspect when you want others to be able to write libraries to talk to your extensions, and for convenience with working with the project.
• You go into common.xml if you can get changes into core PX4 - ie generally useful common changes.
• you go into ardupilot.xml (initially on the fork) if you want in ardupilot but can't get into common.xml.

[hamishwillee]

We also need information about how to create new messages, including

• Style guide (e.g. for punctuation). Not including units in the text. Naming params etc. I wonder if we can astyle this?
• Units - what they are.
• General comments about message format/schema, and in particular about the allowed units: https://github.com/ArduPilot/pymavlink/blob/master/generator/mavschema.xsd#L58
• Avoiding "conditionals" - ideally a field should have just one unit, not multiple. So we can specify them.
• Have place for wip and deprecated info.

This might be a new document, or as part of Message Definitions - but either way should be linked from message definitions.

We might also try auto-import the XML via gitbook.

Discussion on this started here: mavlink/mavlink#914 (comment)

[hamishwillee]

This is now answered, except does not have links to docs on updating the autopilot side