pub struct Frame<V: MaybeVersioned> { /* private fields */ }
Expand description
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§
source§impl Frame<Versionless>
impl Frame<Versionless>
source§impl<V: MaybeVersioned> Frame<V>
impl<V: MaybeVersioned> Frame<V>
sourcepub fn version(&self) -> MavLinkVersion
pub fn version(&self) -> MavLinkVersion
sourcepub fn payload_length(&self) -> PayloadLength
pub fn payload_length(&self) -> PayloadLength
Payload length.
Indicates length of the following payload
section. This may be affected by payload truncation.
§Links
sourcepub fn sequence(&self) -> Sequence
pub fn sequence(&self) -> Sequence
Packet sequence number.
Used to detect packet loss. Components increment value for each message sent.
§Links
sourcepub fn system_id(&self) -> SystemId
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
sourcepub fn component_id(&self) -> ComponentId
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
sourcepub fn message_id(&self) -> MessageId
pub fn message_id(&self) -> MessageId
sourcepub fn payload(&self) -> &Payload
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
sourcepub fn checksum(&self) -> Checksum
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
sourcepub fn is_signed(&self) -> bool
pub fn is_signed(&self) -> bool
sourcepub fn signature(&self) -> Option<&Signature>
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
andFrame::timestamp
provide direct access to signature fields (Frame<V2>
only).
§MavFrame::signature
.
sourcepub fn remove_signature(&mut self)
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
sourcepub fn body_length(&self) -> usize
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
sourcepub fn calculate_crc(&self, crc_extra: CrcExtra) -> Checksum
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
sourcepub fn validate_checksum<D: Dialect>(&self) -> Result<()>
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 byError
) if checksum validation failed.
§Links
Dialect
for dialect specification.Frame::calculate_crc
for CRC implementation details.MavFrame::validate_checksum
.
sourcepub fn validate_checksum_with_crc_extra(
&self,
crc_extra: CrcExtra
) -> Result<(), ChecksumError>
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
.
sourcepub fn matches_version<Version: Versioned>(&self, version: Version) -> bool
pub fn matches_version<Version: Versioned>(&self, version: Version) -> bool
sourcepub fn try_into_versioned<Version: MaybeVersioned>(
self
) -> Result<Frame<Version>, VersionError>
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.
sourcepub fn try_to_versioned<Version: MaybeVersioned>(
&self
) -> Result<Frame<Version>, VersionError>
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.
sourcepub fn into_versionless(self) -> Frame<Versionless>
pub fn into_versionless(self) -> Frame<Versionless>
Forget about frame’s version transforming it into a Versionless
variant.
sourcepub fn to_versionless(&self) -> Frame<Versionless>
pub fn to_versionless(&self) -> Frame<Versionless>
Forget about frame’s version transforming it into a Versionless
variant.
sourcepub fn into_mav_frame(self) -> MavFrame
pub fn into_mav_frame(self) -> MavFrame
Converts this frame into a dynamic MavFrame
.
sourcepub fn decode<D: Dialect>(&self) -> Result<D>
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 providedDialect
(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
sourcepub fn upgrade_with_crc_extra(&mut self, crc_extra: CrcExtra)
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.
source§impl<V: Versioned> Frame<V>
impl<V: Versioned> Frame<V>
sourcepub fn to_builder(
&self
) -> FrameBuilder<V, HasPayloadLen, Sequenced, HasSysId, HasCompId, HasMsgId, HasPayload, Unset, Unset>
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.
source§impl Frame<V2>
impl Frame<V2>
sourcepub fn incompat_flags(&self) -> IncompatFlags
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).
sourcepub fn compat_flags(&self) -> CompatFlags
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).
sourcepub fn link_id(&self) -> Option<SignedLinkId>
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 whichSignature
can be obtained. The former contains all signature-related fields (if applicable).- MAVLink 2 message signing.
sourcepub fn timestamp(&self) -> Option<MavTimestamp>
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 whichSignature
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.
sourcepub fn add_signature(
&mut self,
signer: &mut dyn Sign,
conf: &SigningConf
) -> &mut Self
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.
sourcepub fn validate_signature(
&self,
signer: &mut dyn Sign,
key: &SecretKey
) -> Result<(), SignatureError>
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§
source§impl<'de, V> Deserialize<'de> for Frame<V>where
V: Deserialize<'de> + MaybeVersioned,
impl<'de, V> Deserialize<'de> for Frame<V>where
V: Deserialize<'de> + MaybeVersioned,
source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
source§impl<V: MaybeVersioned> TryFrom<MavFrame> for Frame<V>
impl<V: MaybeVersioned> TryFrom<MavFrame> for Frame<V>
§type Error = VersionError
type Error = VersionError
source§impl<V: MaybeVersioned> TryUpdateFrom<&MavFrame> for Frame<V>
impl<V: MaybeVersioned> TryUpdateFrom<&MavFrame> for Frame<V>
§type Error = VersionError
type Error = VersionError
source§fn check_try_update_from(&self, value: &&MavFrame) -> Result<(), Self::Error>
fn check_try_update_from(&self, value: &&MavFrame) -> Result<(), Self::Error>
⚠
Checks, that update is possible. Read moresource§unsafe fn update_from_unchecked(&mut self, value: &MavFrame)
unsafe fn update_from_unchecked(&mut self, value: &MavFrame)
⚠
Performs the update without checking, whether update is possible. Read moresource§impl<V: MaybeVersioned> TryUpdateFrom<&dyn Message> for Frame<V>
impl<V: MaybeVersioned> TryUpdateFrom<&dyn Message> for Frame<V>
source§fn try_update_from(&mut self, value: &dyn Message) -> Result<(), Self::Error>
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:
⚠ This method will strip Frame::signature
. Make sure, that you know, how to sign
the updated frame afterward.
source§fn check_try_update_from(&self, value: &&dyn Message) -> Result<(), Self::Error>
fn check_try_update_from(&self, value: &&dyn Message) -> Result<(), Self::Error>
⚠
Checks, that update is possible. Read moresource§unsafe fn update_from_unchecked(&mut self, value: &dyn Message)
unsafe fn update_from_unchecked(&mut self, value: &dyn Message)
⚠
Performs the update without checking, whether update is possible. Read more