Struct Frame

pub struct Frame<V: MaybeVersioned> { /* private fields */ }

MAVLink frame.

Represents MAVLink1 or MAVLink2 packet.

Protocol Version

All MAVLink frames always belong to a specific MAVLink protocol version. However, for the sake of generality, this library provides a way to deal with MAVLink protocol version both explicitly by operating on Frame<V1> / Frame<V2> and implicitly through Frame<Versionless>. The latter can be obtained by Frame::into_versionless and converted into a protocol-specific form through Frame::try_into_versioned. Both versionless and versioned forms of a frame could be correctly decoded into the corresponding MAVLink message.

Encoding / Decoding

Frames can be decoded into the corresponding MAVLink message by the Frame::decode method. This requires an appropriate MAVLink dialect to be generated by mavspec. All autogenerated dialects can be found in the mavio::dialects module.

To encode MAVLink message into a frame, you should use FrameBuilder::message as described in the construction section.

Construction

Since MAVLink frame has a complex internal structure that depends on MavLinkVersion, encoded Message and presence of Signature, there is no a direct constructor for this struct. Frame can be either received as they were sent by remote or built from FrameBuilder.

Use Frame::builder to create new frames via builder and Frame::add_signature (for Frame<V2> only) to sign frames.

Serialization / Deserialization

When you have no other options but to deal with byte representation of MAVLink frames, you can use Frame::serialize / Frame::deserialize.

Implementations

impl Frame<Versionless>

pub fn builder() -> FrameBuilder<Versionless, Unset, Unset, Unset, Unset, Unset, Unset, Unset, Unset>

Instantiates an empty builder for Frame.

impl<V: MaybeVersioned> Frame<V>

pub fn header(&self) -> &Header<V>

Frame Header.

pub fn version(&self) -> MavLinkVersion

MAVLink protocol version defined by Header.

Links

• MavLinkVersion
• Header::version
• MavFrame::version

pub fn payload_length(&self) -> PayloadLength

Payload length.

Indicates length of the following payload section. This may be affected by payload truncation.

Links

• Header::payload_length.
• MavFrame::payload_length.

pub fn sequence(&self) -> Sequence

Packet sequence number.

Used to detect packet loss. Components increment value for each message sent.

Links

• Header::sequence.
• MavFrame::sequence

pub fn system_id(&self) -> SystemId

System ID.

ID of system (vehicle) sending the message. Used to differentiate systems on network.

Note that the broadcast address 0 may not be used in this field as it is an invalid source address.

Links

• Header::system_id.
• MavFrame::system_id.

pub fn component_id(&self) -> ComponentId

Component ID.

ID of component sending the message. Used to differentiate components in a system (e.g. autopilot and a camera). Use appropriate values in MAV_COMPONENT.

Note that the broadcast address MAV_COMP_ID_ALL may not be used in this field as it is an invalid source address.

Links

• Header::component_id.
• MavFrame::component_id.

pub fn message_id(&self) -> MessageId

Message ID.

ID of MAVLink message. Defines how payload will be encoded and decoded.

Links

• Header::message_id.
• MavFrame::message_id.

pub fn payload(&self) -> &Payload

Payload data.

Message data. Content depends on message type (i.e. message_id).

Returns an instance of Payload. If you are interested in payload bytes, use Payload::bytes.

Links

• MavFrame::payload.

pub fn checksum(&self) -> Checksum

MAVLink packet checksum.

CRC-16/MCRF4XX checksum for message (excluding magic byte).

Includes CRC_EXTRA byte.

Checksum is encoded with little endian (low byte, high byte).

Links

• Frame::calculate_crc for implementation.
• MAVLink checksum definition.
• CRC-16/MCRF4XX (PDF).
• MavFrame::checksum

pub fn is_signed(&self) -> bool

Returns true if frame is signed.

Returns true if Frame contains Signature. Correctness of signature is not validated.

For MAVLink 1 frames always returns false.

Links

• MavFrame::is_signed

pub fn signature(&self) -> Option<&Signature>

MAVLink 2 signature.

Returns signature that ensures the link is tamper-proof.

Available only for signed MAVLink 2 frames. For MAVLink 1 always return None.

Links

• Frame::is_signed checks that frame is signed.
• Frame::link_id and Frame::timestamp provide direct access to signature fields (Frame<V2> only).

MavFrame::signature.

• MAVLink 2 message signing.

pub fn remove_signature(&mut self)

Removes MAVLink 2 signature from frame.

Applicable only for MAVLink 2 frames. MAVLink 1 frames will be kept untouched.

Links

MavFrame::remove_signature

pub fn size(&self) -> usize

Frame size in bytes when serialized.

Note that the size of a deserialized frame is not equal to the occupied memory.

Links

• Header::size returns header size in bytes when serialized.
• Frame::body_length returns frame body length in bytes.

pub fn body_length(&self) -> usize

Body length.

Returns the length of the entire Frame body. The frame body consist of Payload::bytes, Checksum, and optional Signature (for MAVLink 2 protocol).

Links

• Header::body_length.
• MavFrame::body_length.

pub fn calculate_crc(&self, crc_extra: CrcExtra) -> Checksum

Calculates CRC for frame within crc_extra.

Provided crc_extra depends on a dialect and contains a digest of message XML definition.

Links

• Frame::checksum.
• MavFrame::calculate_crc.
• MAVLink checksum definition.
• CRC-16/MCRF4XX (PDF).

pub fn validate_checksum<D: Dialect>(&self) -> Result<()>

Validates frame in the context of specific dialect.

Receives dialect specification in dialect_spec, ensures that message with such ID exists in this dialect, and compares checksums using EXTRA_CRC.

Errors

• Returns Error::Spec if message discovery failed.
• Returns FrameError::Checksum (wrapped by Error) if checksum validation failed.

Links

• Dialect for dialect specification.
• Frame::calculate_crc for CRC implementation details.
• MavFrame::validate_checksum.

pub fn validate_checksum_with_crc_extra( &self, crc_extra: CrcExtra, ) -> Result<(), ChecksumError>

Validates frame’s checksum using provided crc_extra.

Errors

Returns ChecksumError if checksum validation failed.

Links

• Frame::calculate_crc for CRC implementation details.
• MavFrame::validate_checksum_with_crc_extra.

pub fn matches_version<Version: Versioned>(&self, version: Version) -> bool

Checks that frame has MAVLink version equal to the provided one.

Links

MavFrame::matches_version

pub fn try_into_versioned<Version: MaybeVersioned>( self, ) -> Result<Frame<Version>, VersionError>

Attempts to transform frame into its versioned form.

This method never changes the internal MAVLink protocol version. It will return an error, if conversion is not possible.

pub fn try_to_versioned<Version: MaybeVersioned>( &self, ) -> Result<Frame<Version>, VersionError>

Attempts to create frame of specified version from the existing one.

This method never changes the internal MAVLink protocol version. It will return an error, if conversion is not possible.

pub fn into_versionless(self) -> Frame<Versionless>

Forget about the frame’s version transforming it into a Versionless variant.

pub fn to_versionless(&self) -> Frame<Versionless>

Forget about frame’s version transforming it into a Versionless variant.

pub fn into_mav_frame(self) -> MavFrame

Converts this frame into a dynamic MavFrame.

pub fn decode<D: Dialect>(&self) -> Result<D>

Decodes the frame into a message of a particular MAVLink dialect.

Performs Frame::checksum validation before returning the decoded message.

Usage

use mavio::dialects::minimal;
use mavio::dialects::minimal::Minimal;
use mavio::Frame;

let frame = // ... obtain a frame

// Decode the frame within `minimal` dialect and match the result over available dialect messages
match frame.decode().unwrap() {
    Minimal::Heartbeat(message) => {
        /* process heartbeat message */
    }
    _ => unreachable!()
}

This function is useful when you are expecting to receive any message withing a particular dialect into an option of the dialect enum (such as Minimal). This introduces a slight memory overhead due to the way how Rust enums are stored. If instead, you want to decode a particular message directly, use Frame::decode_message.

Errors

• Returns FrameError::Checksum if checksum validation failed.
• Returns Error::Spec if the frame can’t be correctly decoded to the provided Dialect (generic type argument).

Links

• Frame::decode_message decodes the frame into a particular message directly.
• Frame::validate_checksum_with_crc_extra performs checksum validation.
• SpecError contains errors related to MAVLink dialect specification and message encoding/decoding.

pub fn decode_message<'a, M: MessageSpecStatic + TryFrom<&'a Payload, Error = SpecError>>( &'a self, ) -> Result<M>

Decodes the frame into a particular MAVLink message.

Performs Frame::checksum validation before returning the decoded message.

Usage

use mavio::dialects::minimal;
use mavio::Frame;
use minimal::messages::Heartbeat;

let frame = // ... obtain a frame

// Decode the frame into a specific type based on its `ID`
match frame.message_id() {
    Heartbeat::ID => {
        let message = frame.decode_message::<Heartbeat>().unwrap();
    }
    _ => unreachable!()
}

This function is useful when you know exactly what message you want to decode. You may also want to consider using Frame::decode that decodes any valid message into a dialect enum.

Errors

• Returns FrameError::Checksum if checksum validation failed.
• Returns Error::Spec if the frame can’t be correctly decoded to the desired message.

Links

• Frame::decode decodes the frame into a message as on option of the particular dialect enum.
• Frame::validate_checksum_with_crc_extra performs checksum validation.
• SpecError contains errors related to MAVLink dialect specification and message encoding/decoding.

pub fn upgrade_with_crc_extra(&mut self, crc_extra: CrcExtra)

Upgrades the frame in-place to MAVLink 2 protocol version using provided CRC_EXTRA.

The opposite is not possible since we need to know the exact payload length.

pub fn serialize(&self, buf: &mut [u8]) -> Result<usize, FrameError>

Serializes the frame into a sequence of bytes.

Accepts a mutable buffer and writes the frame into it, returning the number of bytes written.

The buffer should be large enough, otherwise FrameError::FrameBufferIsTooSmall error will be returned.

Errors

Returns FrameError::FrameBufferIsTooSmall if the provided buffer is too small.

Links

• Frame::deserialize to deserialize a frame from a buffer.
• Frame::size returns frame size in bytes.

pub unsafe fn deserialize(buf: &[u8]) -> Result<Frame<V>, FrameError>

Deserializes a frame from a sequence of bytes.

This function is marked as unsafe since construction of frames from an arbitrary sequence of bytes is considered as a potentially risky practice. Yet the implementation contains only a sound and safe Rust code.

The buffer should have a sufficient size and should start from a magic byte. Otherwise, an error will be returned.

Errors

• Returns FrameError::InvalidHeader if the sequence doesn’t start with a valid header.
• Returns FrameError::FrameBufferIsTooSmall if the buffer does not contain an exact representation of a frame.

Links

• Frame::serialize to serialize a frame into a buffer.

impl<V: Versioned> Frame<V>

pub fn to_builder( &self, ) -> FrameBuilder<V, HasPayloadLen, Sequenced, HasSysId, HasCompId, HasMsgId, HasPayload, Unset, Unset>

Create FrameBuilder populated with current frame data.

It is not possible to simply change a particular frame field since MAVLink frame data is tightly packed together, covered by CRC, and, in the case of MAVLink 2 protocol, is potentially signed. Moreover, to alter a frame correctly we need a CrcExtra byte which is a part of a dialect, not the frame itself.

This method provides a limited capability to alter frame data by creating a FrameBuilder populated with data of the current frame. For MAVLink 2 frames this will drop frame’s signature and IncompatFlags::MAVLINK_IFLAG_SIGNED in incompat_flags rendering frame unsigned. This process also requires from caller to provide a CrcExtra value to encoded message since checksum will be dropped as well and the information required to its this recalculation is not stored within MAVLink frame itself.

It is not possible to rebuild Versionless frames since MAVLink 2 Payload may contain extension fields and its trailing zero bytes are truncated which means it is not possible to reconstruct MAVLink 1 payload_length when downgrading frame protocol version.

impl Frame<V2>

pub fn incompat_flags(&self) -> IncompatFlags

Incompatibility flags for MAVLink 2 header.

Flags that must be understood for MAVLink compatibility (implementation discards packet if it does not understand flag).

See: MAVLink 2 incompatibility flags.

pub fn compat_flags(&self) -> CompatFlags

Compatibility flags for MAVLink 2 header.

Flags that can be ignored if not understood (implementation can still handle packet even if it does not understand flag).

See: MAVLink 2 compatibility flags.

pub fn link_id(&self) -> Option<SignedLinkId>

MAVLink 2 signature link_id, an 8-bit identifier of a MAVLink channel.

Peers may have different semantics or rules for different links. For example, some links may have higher priority over another during routing. Or even different secret keys for authorization.

Available only for signed MAVLink 2 frame. For MAVLink 1 always return None.

Links

• Self::signature from which Signature can be obtained. The former contains all signature-related fields (if applicable).
• MAVLink 2 message signing.

pub fn timestamp(&self) -> Option<MavTimestamp>

MAVLink 2 signature MavTimestamp, a 48-bit value that specifies the moment when message was sent.

The unit of measurement is the number of millisecond * 10 since MAVLink epoch (1st January 2015 GMT).

According to MAVLink protocol, the sender must guarantee that the next timestamp is greater than the previous one.

Available only for signed MAVLink 2 frame. For MAVLink 1 always return None.

Links

• Self::signature from which Signature can be obtained. The former contains all signature-related fields (if applicable).
• MavTimestamp type which has utility function for converting from and into Unix timestamp.
• Timestamp handling in MAVLink documentation.

pub fn add_signature( &mut self, signer: &mut dyn Sign, conf: &SigningConf, ) -> &mut Self

Adds signature to MAVLink 2 frame.

Signs MAVLink 2 frame with provided instance of signer that implements Sign trait and signature configuration specified as SigningConf.

Links

• Sign trait.
• Signature struct which contains frame signature.
• MAVLink 2 message signing.

pub fn validate_signature( &self, signer: &mut dyn Sign, key: &SecretKey, ) -> Result<(), SignatureError>

Validates frame signature using a signer and a secret key.

Returns SignatureError if frame missing a signature or have an incorrect one.

Trait Implementations

impl<V: Clone + MaybeVersioned> Clone for Frame<V>

fn clone(&self) -> Frame<V>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<V: Debug + MaybeVersioned> Debug for Frame<V>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, V> Deserialize<'de> for Frame<V>

where V: Deserialize<'de> + MaybeVersioned,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<V: MaybeVersioned> From<Frame<V>> for MavFrame

fn from(value: Frame<V>) -> Self

Converts to this type from the input type.

impl<V> NamedType for Frame<V>

where V: Type + MaybeVersioned,

fn sid() -> SpectaID

fn named_data_type( type_map: &mut TypeCollection, generics: &[DataType], ) -> NamedDataType

this is equivalent to Type::inline but returns a NamedDataType instead.

fn definition_named_data_type(type_map: &mut TypeCollection) -> NamedDataType

this is equivalent to [Type::definition] but returns a NamedDataType instead.

impl<V> Serialize for Frame<V>

where V: Serialize + MaybeVersioned,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<V: MaybeVersioned> TryFrom<MavFrame> for Frame<V>

type Error = VersionError

The type returned in the event of a conversion error.

fn try_from(value: MavFrame) -> Result<Self, VersionError>

Performs the conversion.

impl<V: MaybeVersioned> TryUpdateFrom<&MavFrame> for Frame<V>

type Error = VersionError

Error, that may be thrown during update.

fn check_try_update_from(&self, value: &&MavFrame) -> Result<(), Self::Error>

^⚠ Checks, that update is possible.

unsafe fn update_from_unchecked(&mut self, value: &MavFrame)

^⚠ Performs the update without checking, whether update is possible.

fn try_update_from(&mut self, value: T) -> Result<(), Self::Error>

^⚠ Performs the update.

impl<V: MaybeVersioned> TryUpdateFrom<&dyn Message> for Frame<V>

fn try_update_from(&mut self, value: &dyn Message) -> Result<(), Self::Error>

^⚠ Updates a frame with the data from the provided message.

Replaces the following fields, that are guaranteed to be correct:

• Frame::message_id
• Frame::payload_length
• Frame::payload
• Frame::checksum

⚠ This method will strip Frame::signature. Make sure, that you know, how to sign the updated frame afterward.

type Error = SpecError

Error, that may be thrown during update.

fn check_try_update_from(&self, value: &&dyn Message) -> Result<(), Self::Error>

^⚠ Checks, that update is possible.

unsafe fn update_from_unchecked(&mut self, value: &dyn Message)

^⚠ Performs the update without checking, whether update is possible.

impl<V> Type for Frame<V>

where V: Type + MaybeVersioned,

fn inline(type_map: &mut TypeCollection, generics: Generics<'_>) -> DataType

Returns the definition of a type using the provided generics.

fn reference(type_map: &mut TypeCollection, generics: &[DataType]) -> Reference

Generates a datatype corresponding to a reference to this type, as determined by its category. Getting a reference to a type implies that it should belong in the type map (since it has to be referenced from somewhere), so the output of definition will be put into the type map.

impl<V> Flatten for Frame<V>

where V: Type + MaybeVersioned,