Struct mavio::Frame

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

MAVLink frame.

Represents MAVLink1 or MAVLink2 packet.

Protocol Version

All MAVLink frames are 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 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 Frame::decode method. This requires 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 construction section.

Construction

Since MAVLink frames has a complex internal structure that depends on MavLinkVersion, encoded Message and presence of Signature, there are is direct no 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.

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 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 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 frame into a message of particular MAVLink dialect.

Performs Frame::checksum validation before returning 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 result over available dialect messages
match frame.decode().unwrap() {
    Minimal::ProtocolVersion(_) => {}
    Minimal::Heartbeat(_) => {}
}

Errors

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

Links

• Frame::validate_checksum_with_crc_extra performs checksum validation.
• SpecError contains errors related to MAVLink dialect specification and message encoding/decoding.
• Frame::decode

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

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

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

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 copy 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> 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.