mavlink/mavlink-devguide

Message Definitions · Add doc on how to add messages

hamishwillee opened this issue · 6 comments

hamishwillee commented

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 commented

  • 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 commented

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 commented

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 commented

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 commented

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 commented

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