This chapter describes the MAVLink commands and messages that facilitate data exchange between the operator's equipment and the on-board UAVCAN nodes. The primary motivation is to enable the user to configure, monitor, and control the on-board UAVCAN nodes via the existing MAVLink connection.
The general description and specification of UAVCAN is available at http://uavcan.org.
The text below will be referring to the following terms:
- Bridge node - the piece of on-board equipment that bridges the on-board UAVCAN bus and the MAVLink connection. This function is often performed by the flight management unit, e.g. Pixhawk.
- Remote equipment - the other end of the MAVLink channel, e.g. the ground control station.
Every UAVCAN node has a bus-unique identifier referred to as "node ID". The node ID is an integer in the interval [1, 127], where the value 1 is typically used by the autopilot or some other kind of central controlling unit, and the values 126 and 127 are typically used by debugging or monitoring equipment.
Each unit that is capable of communicating via MAVLink and UAVCAN must use the same number for its MAVLink Component ID and the UAVCAN Node ID, otherwise serious inconsistencies may arise. Typically, if there is a single non-redundant autopilot, its UAVCAN Node ID and the MAVLink component ID will be set to 1 (one).
Every outgoing/incoming MAVLink message/command pertaining to a given UAVCAN node will have its field Component ID set to the same value as the Node ID of the referred UAVCAN node.
In UAVCAN, the abstract node status information is represented by the standard message type
uavcan.protocol.NodeStatus. Its MAVLink counterpart is
The bridge node should emit the MAVLink message
UAVCAN_NODE_STATUS every time it receives a UAVCAN node status message. The bridge node is allowed to decimate the stream of node status messages in order to avoid congestion of the MAVLink channel, but the resulting frequency of status message emission should not be lower than 1 Hz per node.
The remote equipment can monitor which UAVCAN nodes are online by means of tracking the amount of time that passed since the last reception of the node status message for each online node. The remote equipment should consider the node to be offline if its last status message has arrived more than 5 seconds ago.
UAVCAN nodes are typically able to report some static information that identifies their type, purpose, vendor, revision, and such, via the standard service type
uavcan.protocol.GetNodeInfo. In this context, "static" means that the data is not changing while the node is running. This information can be crucial for many important use cases.
The corresponding MAVLink message is
UAVCAN_NODE_INFO. Its fields are direct mappings of the corresponding fields in the service type
The bridge node must emit the message
UAVCAN_NODE_INFO in the following cases:
- Reception of a service response of type
uavcan.protocol.GetNodeInfo. In turn, this service must be invoked when the following conditions are observed on the bus (please read the UAVCAN specification for a more detailed description of the principles of bus monitoring):
- A new node has appeared online.
- A known node has restarted.
- Reception of the MAVLink command
MAV_CMD_UAVCAN_GET_NODE_INFO. In this case, the bridge node is required to emit
UAVCAN_NODE_INFOonce for every known node.
- It is also allowed, but not required, to unconditionally emit messages
UAVCAN_NODE_INFOat a very low rate, in order to guarantee that the remote equipment always has a valid model of the on-board UAVCAN bus.
UAVCAN defines a set of standard service types that facilitate the management of configuration parameters on UAVCAN nodes. The respective data type definitions can be found in the namespace
The UAVCAN-MAVLink bridge does not define any additional messages for configuration parameter management. Instead, the following standard messages are used in the regular way:
PARAM_REQUEST_LIST- used to request the list of configuration parameters from the specified UAVCAN node. Remember that the UAVCAN node is specified via the field Component ID.
PARAM_VALUE- used by the bridge node to report the value of a configuration parameter. The node ID is reflected in the field Component ID.
PARAM_SET- used by the remote equipment to set the value of a configuration parameter. The node ID is reflected in the field Component ID.
Note that the maximum length of a configuration parameter name is defined differently in UAVCAN and MAVLink. In MAVLink, the maximum length is 16 characters, whereas in UAVCAN the limit is 92 characters. Should the bridge node encounter long configuration parameter names that exceed the MAVLink's limit, it should exercise its best effort to reduce the name length presented on the MAVLink side while avoiding ambiguity. Designers of UAVCAN nodes, on their part, should avoid using configuration parameter names more than 16 characters long, until this deficiency of the MAVLink protocol is fixed.
UAVCAN defines a set of standard messages that facilitate communication between UAVCAN nodes and remote hosts on the Internet or LAN. The tentative specification can be viewed on GitHub. In the future, the set of MAVLink messages should be extended to allow forwarding of data packets between the bridge node and the Internet via the remote equipment (e.g. ground control station). If you're interested in this feature, please report to the UAVCAN mailing list.