This service is still marked as "work in progress", and should not be relied upon in production.
The Component Information Protocol is a MAVLink service for requesting information from (and about) MAVLink components. It is intended to provide autopilot- and version- independent feature discovery and configuration, allowing a GCS to configure its UI and/or a device without knowing anything about the connected system.
Information shared using this service may include:
- What types of component information are supported (by this component).
- What MAVLink commands are supported (both in missions and in other modes).
- Parameter metadata for parameters supported by the vehicle.
- Metadata about events emitted by the system
- Self-describing configuration UIs (i.e. similar to MAVLink camera configuration files).
- Translations of other metadata.
Component information is specified in approriately formatted JSON files (which may be .xz compressed). The component information protocol is used to request the location of the general metadata file file, which is then parsed to get the location of most other metadata files supported by the component.
Information supplied by the service is assumed to be invariant after boot. There is no mechanism, for example, to provide an update if the set of supported parameters was to change after boot.
|COMPONENT_INFORMATION||Message providing a download url and CRC for the general metadata component information file (and optionally the non-MAVLink peripherals metadata). The message is requested using MAV_CMD_REQUEST_MESSAGE.|
|MAV_CMD_REQUEST_MESSAGE||Use this command to request that a component emit COMPONENT_INFORMATION. Use |
|COMP_METADATA_TYPE||Types of component metadata supported by the protocol - e.g. general information, parameter metadata, supported commands, events, peripherals, etc. The type identifiers are used in the "general" metadata file to identify the sections that provide information about each supported type of metadata.|
Component information files are written in JSON and must conform to the schema definitions found in the folder /component_information. The component information file types and schema are (at time of writing):
|General metadata||COMP_METADATA_TYPE_GENERAL||general.schema.json||General information about the component including hardware/firmware vendor version. This metadata includes information about all the other metadata types are supported by the component and where their metadata files are located. This metadata type must be supported if this protocol is supported and the file must be present on vehicle and delivered by MAVLink FTP. Note however that you never actually need to specify this type!|
|Parameter metadata||COMP_METADATA_TYPE_PARAMETER||parameter.schema.json||Information about parameters supported by the vehicle (on boot).|
|Command protocol metadata||COMP_METADATA_TYPE_COMMANDS||TBD||Information about which commands and command paramters are supported in via the command protocol.|
|Peripheral metadata||COMP_METADATA_TYPE_PERIPHERALS||peripherals.json||Information about non-MAVLink peripherals connected to vehicle (on boot).|
|Event metadata||COMP_METADATA_TYPE_EVENTS||TBD||Information about events interface support by the vehicle.|
All schema files are versioned using a
Schema versions are backwards compatible - i.e. a ground station that was able to populate its UI from a file based on an older schema should be able to do so from a newer version (albeit losing information provided by the newer format).
Generally this means that new versions may add fields but should not delete them, and also that a recipient can ignore fields that it does not understand.
The schema are currently a work in progress and can be modified as needed. Once accepted, they will be under change control (managed in a similar way to standard MAVLink messages).
General metadata files and peripherals metadata files (if supported) must be stored on the device, and will usually be .xz compressed. The location of these files is returned in the COMPONENT_INFORMATION
peripherals_metadata_uri fields, respectively.
Other component information files may be hosted on either the device or on the internet.
Where permitted by memory constraints you should host component information on the device (so that it is always available and cannot get out of sync).
Files on the device are downloaded using MAVLink FTP. The URI format is defined in MAVLink FTP URL Scheme. A typical parameter metadata URI might look like this:
Files on the Internet are downloaded using HTTPS or HTTP via a normal web URL (e.g.
The COMPONENT_INFORMATION message includes
peripherals_metadata_file_crc fields, which contain CRC32 values calculated for the files referenced in fields
peripherals_metadata_uri (respectively). A ground station should cache downloaded component metadata and only update it if the CRC value changes.
Component information files may be .xz compressed (this is recommended for files that are hosted on the device).
The prototype implementation generates and compresses component information files at build time. No compression library is required within the flight stack itself.
Systems that request component information must support extraction of .xz-compressed JSON files.
The Tukaani Project XZ Embedded library is an easy-to-use XZ compression library for embedded systems.
A GCS can broadcast the
param1=395; all components that support the protocol should respond with
A GCS can further discover all components in the system by monitoring the channel for
HEARTBEAT ids, and then send the request to each of them to verify whether the protocol is supported. The broadcast approach is recommended for GCSes that don't track all components on the link.
The component will respond with
COMPONENT_INFORMATION.general_metadata_uri containing a valid URI if the protocol is supported. If the protocol is not supported the component will ACK that the message with
MAV_RESULT_FAILED, or return a
null value in
A component that supports this service must return a general metadata file URI that is hosted on the vehicle (accessed using MAVLink FTP).
The basic sequence is shown below.
- GCS sends
- This is a normal command protocol request with timeouts and resends based on the ACK.
- The component will ACK the command and immediately send the requested
COMPONENT_INFORMATIONmessage (populated with URI and CRC for the general metadata file, and optionally with the URI and CRC for the non-MAVLink peripherals metadata file).
CMD_ACKof anything other than
MAV_RESULT_ACCEPTEDindicates the protocol is not supported (sequence completes).
GCS waits for the
- If not recieved the GCS should resend the request (typically in the application level).
Once information is received:
- the GCS checks if
COMPONENT_INFORMATION.general_metadata_file_crcmatches its cached CRC value. If so, there is no need to download the general metadata file (or other files it references) as it has not changed since the last download.
- the GCS checks if
COMPONENT_INFORMATION.peripherals_metadata_uriif supplied, and (if so) whether the
peripherals_metadata_file_crcfield matches the cached value.
If the cached values do not match the associated files should be downloaded and parsed ....
- the GCS checks if
- GCS downloads the file specified in the
general_metadata_uriusing MAVLink FTP.
- GCS parses the general metadata for other supported metadata locations, and then downloads the files via MAVFTP or HTTP(s). This may be done immediately, or as needed.
- A method for setting/updating the translation file has not yet been determined (if hosted on a server, a component never sees the file, which might be changed any time)
- There is no end-to-end prototype of the translation system, so there may still be other issues.
Schema management has not yet been signed off.
There is a concern that vehicles reliant on internet-hosted component information files may stop working if the hosting ceases.
This can generally be avoided by hosting the files compressed on-vehicle.
We propose that manufacturers that use autopilots with limited flash (1MB or below) and do custom firmware development should host the files in github.