Crate mavlink_core

Expand description

The MAVLink message set.

§Message sets and the `Message` trait

Each message set has its own module with corresponding data types, including a MavMessage enum that represents all possible messages in that message set. The Message trait is used to represent messages in an abstract way, and each MavMessage enum implements this trait (for example, ardupilotmega::MavMessage). This is then monomorphized to the specific message set you are using in your application at compile-time via type parameters. If you expect ArduPilotMega-flavored messages, then you will need a MavConnection<ardupilotmega::MavMessage> and you will receive ardupilotmega::MavMessages from it.

Some message sets include others. For example, most message sets include the common message set. These included values are not differently represented in the MavMessage enum: a message in the common message set received on an ArduPilotMega connection will just be an ardupilotmega::MavMessage.

If you want to enable a given message set, you do not have to enable the feature for the message sets that it includes. For example, you can use the ardupilotmega feature without also using the uavionix, icarous, common features.

§Read Functions

The read_* functions can be used to read a MAVLink message for a PeakReader wrapping a [Read]er.

They follow the pattern read_(v1|v2|any|versioned)_(raw_message|msg)[_async][_signed]<M, _>(..). All read functions check for a valid STX marker of the corresponding MAVLink version and verify that the message CRC checksum is correct. They attempt to read until either a whole MAVLink message is read or an error occurrs. While doing so data without STX marker, with an invalid CRC chechsum or invalid signature (if applicable) is discarded. To determine for which dialect the message CRC should be verified it must be specified by using the Message enum of the dialect as the generic M.

Unless further specified all combinations of the function name components exist. The components are described bellow:

v1 functions read only MAVLink 1 messages
v2 functions read only MAVLink 2 messages
any functions read messages of either MAVLink version
versioned functions read messages of the version specified in an aditional version parameter
raw_message functions return an unparsed message as MAVLinkV1MessageRaw, MAVLinkV2MessageRaw or MAVLinkMessageRaw
msg functions return a parsed message as a tupel of MavHeader and the Message of the specified dialect
_async functions, which are only enabled with the tokio-1 feature, are async and read from an AsyncPeakReader instead.
_signed functions, which are only enabled with the signing feature, have an Option<&SigningData> parameter that allows the use of MAVLink 2 message signing. MAVLink 1 exclusive functions do not have a _signed variant and functions that allow both MAVLink 1 and 2 messages treat MAVLink 1 messages as unsigned. When an invalidly signed message is received it is ignored.

§Read Errors

All read_ functions return Result<_, MessageReadError>.

All functions will return MessageReadError::Io of UnexpectedEof when EOF is encountered before a message could be read.
All functions will return MessageReadError::Io when an error occurs on the underlying Reader or AsyncReader.
Functions that parse the received message will return MessageReadError::Parse when the read data could not be parsed as a MAVLink message

§Write Functions

The write_ functions are used to write a MAVLink to a Writer. They follow the pattern write_(v1|v2|versioned)_msg[_async][_signed](..):

v1 functions write messages using MAVLink 1 serialisation
v2 functions write messages using MAVLink 2 serialisation
versioned functions write messages using the version specified in an aditional version parameter
_async functions, which are only enabled with the tokio-1 feature, are async and write from an [tokio::io::AsyncWrite]r instead.
_signed functions, which are only enabled with the signing feature, have an Option<&SigningData> parameter that allows the use of MAVLink 2 message signing.

§Write errors

All write_ functions return Result<_, MessageWriteError>.

When an error occurs on the underlying Writeer or AsyncWriteer other then Interrupted the function returns MessageWriteError::Io
When attempting to serialize a message with an ID over 255 with MAVLink 1 a MessageWriteError::MAVLink2Only is returned

Modules§

async_peek_readertokio-1: This module implements a buffered/peekable reader using async I/O.
error
peek_reader: This module implements a buffered/peekable reader.
utils: Utilities for processing MAVLink messages

Structs§

FileConfigstd: MAVLink connection address for a file input
MAVLinkV1MessageRaw: Byte buffer containing the raw representation of a MAVLink 1 message beginning with the STX marker.
MAVLinkV2MessageRaw: Byte buffer containing the raw representation of a MAVLink 2 message beginning with the STX marker.
MavFrame: Encapsulation of the MAVLink message and the header, important to preserve information about the sender system and component id.
MavHeader: Metadata from a MAVLink packet header
SerialConfigdirect-serial: MAVLink address for a serial connection
SigningConfigsigning: Configuration used for MAVLink 2 messages signing as defined in https://mavlink.io/en/guide/message_signing.html.
SigningDatasigning: MAVLink 2 message signing data
TcpConfigtcp: MAVLink connection address for a TCP server or client
UdpConfigudp: MAVLink address for a UDP server client or broadcast connection

Enums§

ConnectionAddressstd or tokio-1: A parsed MAVLink connection address
MAVLinkMessageRaw: Raw byte representation of a MAVLink message of either version
MavlinkVersion: Versions of the MAVLink protocol that we support
ReadVersion: MAVLink Version selection when attempting to read
TcpModetcp: Type of TCP connection
UdpModeudp: Type of UDP connection

Constants§

MAV_STX: Message framing marker for MAVLink 1
MAV_STX_V2: Message framing marker for MAVLink 2
MAX_FRAME_SIZE: Maximum size of any MAVLink frame in bytes.

Traits§

AsyncConnectabletokio-1: A MAVLink connection address that can be connected to, establishing an AsyncMavConnection
AsyncMavConnectiontokio-1: An async MAVLink connection
Connectablestd: A MAVLink connection address that can be connected to, establishing a MavConnection
MavConnectionstd: A MAVLink connection
Message: A MAVLink message payload
MessageData

Functions§

calculate_crc: Calculates the CRC checksum of a messages header, payload and the CRC_EXTRA byte.
connectstd: Connect to a MAVLink node by address string.
connect_asynctokio-1: Connect asynchronously to a MAVLink node by address string.
read_any_msg: Read and parse a MAVLink 1 or 2 message from a PeekReader.
read_any_msg_asynctokio-1: Asynchronously read and parse a MAVLink 1 or 2 message from a AsyncPeekReader.
read_any_msg_async_signedtokio-1 and signing: Asynchronously read and parse a MAVLink 1 or 2 message from a AsyncPeekReader with signing support.
read_any_msg_signedsigning: Read and parse a MAVLink 1 or 2 message from a PeekReader with signing support.
read_any_raw_message: Read a raw MAVLink 1 or 2 message from a PeekReader.
read_any_raw_message_asynctokio-1: Asynchronously read a raw MAVLink 1 or 2 message from a AsyncPeekReader.
read_any_raw_message_async_signedtokio-1 and signing: Asynchronously read a raw MAVLink 1 or 2 message from a AsyncPeekReader with signing support.
read_any_raw_message_signedsigning: Read a raw MAVLink 1 or 2 message from a PeekReader with signing support.
read_v1_msg: Read and parse a MAVLink 1 message from a PeekReader.
read_v1_msg_asynctokio-1: Asynchronously read and parse a MAVLink 1 message from a AsyncPeekReader.
read_v1_raw_message: Read a raw MAVLink 1 message from a PeekReader.
read_v1_raw_message_asynctokio-1: Asynchronously read a raw MAVLink 1 message from a AsyncPeekReader.
read_v2_msg: Read and parse a MAVLink 2 message from a PeekReader.
read_v2_msg_asynctokio-1: Asynchronously read and parse a MAVLink 2 message from a AsyncPeekReader.
read_v2_msg_async_signedtokio-1 and signing: Asynchronously read and parse a MAVLink 2 message with signing support from a AsyncPeekReader.
read_v2_msg_signedsigning: Read and parse a MAVLink 2 message from a PeekReader.
read_v2_raw_message: Read a raw MAVLink 2 message from a PeekReader.
read_v2_raw_message_asynctokio-1: Asynchronously read a raw MAVLink 2 message from a AsyncPeekReader.
read_v2_raw_message_async_signedtokio-1 and signing: Asynchronously read a raw MAVLink 2 message with signing support from a AsyncPeekReader
read_v2_raw_message_signedsigning: Read a raw MAVLink 2 message with signing support from a PeekReader.
read_versioned_msg: Read and parse a MAVLink message of the specified version from a PeekReader.
read_versioned_msg_asynctokio-1: Asynchronously read and parse a MAVLink message of the specified version from a AsyncPeekReader.
read_versioned_msg_async_signedtokio-1 and signing: Asynchronously read and parse a MAVLink message of the specified version from a AsyncPeekReader with signing support.
read_versioned_msg_signedsigning: Read and parse a MAVLink message of the specified version from a PeekReader with signing support.
read_versioned_raw_message: Read and parse a MAVLink message of the specified version from a PeekReader.
read_versioned_raw_message_asynctokio-1: Asynchronously read and parse a MAVLinkMessageRaw of the specified version from a AsyncPeekReader.
read_versioned_raw_message_async_signedtokio-1 and signing: Asynchronously read and parse a MAVLinkMessageRaw of the specified version from a AsyncPeekReader with signing support.
read_versioned_raw_message_signedsigning: Read and parse a MAVLinkMessageRaw of the specified version from a PeekReader with signing support.
write_v1_msg: Write a MAVLink 1 message to a Writer.
write_v1_msg_asynctokio-1: Asynchronously write a MAVLink 1 message to a [AsyncWrite]r.
write_v2_msg: Write a MAVLink 2 message to a Writer.
write_v2_msg_asynctokio-1: Asynchronously write a MAVLink 2 message to a [AsyncWrite]r.
write_v2_msg_async_signedsigning and tokio-1: Write a MAVLink 2 message to a [AsyncWrite]r with signing support.
write_v2_msg_signedsigning: Write a MAVLink 2 message to a Writer with signing support.
write_versioned_msg: Write a MAVLink message using the given mavlink version to a Writer.
write_versioned_msg_asynctokio-1: Asynchronously write a MAVLink message using the given MAVLink version to a [AsyncWrite]r.
write_versioned_msg_async_signedtokio-1 and signing: Asynchronously write a MAVLink message using the given MAVLink version to a [AsyncWrite]r with signing support.
write_versioned_msg_signedsigning: Write a MAVLink message using the given mavlink version to a Writer with signing support.