mavwire 0.1.0

no_std, no_alloc parser and encoder for MAVLink v1/v2 telemetry messages
Documentation
//! Error types for the frame and message layers.

use core::fmt;

/// Errors from parsing a raw `MAVLink` v1/v2 frame.
///
/// Checksum verification is deliberately not a `FrameError`: `MAVLink`'s CRC
/// includes a per-message `crc_extra` byte (see [`crate::crc`]), which the
/// frame layer doesn't know (only the message layer, once it has looked up
/// the message ID, does) - see [`crate::frame::Frame::verify_checksum`].
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FrameError {
    /// The buffer was shorter than the minimal frame this magic byte/header
    /// promises (header + declared payload length + 2-byte checksum, plus
    /// a 13-byte signature if the signing incompatibility flag is set).
    TooShort {
        /// Bytes required, per the header's own declared payload length.
        needed: usize,
        /// Bytes actually available in the buffer.
        got: usize,
    },
    /// The first byte wasn't a recognized `MAVLink` magic byte (`0xFE` for
    /// v1, `0xFD` for v2).
    UnknownMagicByte(u8),
    /// The v2 signing incompatibility flag was set; this crate doesn't
    /// verify (or produce) `MAVLink` v2 message signatures.
    SigningNotSupported,
    /// A payload passed to the v2 encoder exceeded the 255-byte length a
    /// `MAVLink` frame's length field can represent.
    PayloadTooLong {
        /// Maximum representable payload length (always 255).
        max: usize,
        /// Actual payload length given.
        got: usize,
    },
}

impl fmt::Display for FrameError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::TooShort { needed, got } => {
                write!(f, "frame needs {needed} bytes, buffer has {got}")
            }
            Self::UnknownMagicByte(b) => write!(f, "unrecognized magic byte: {b:#04x}"),
            Self::SigningNotSupported => write!(f, "signed v2 frames are not supported"),
            Self::PayloadTooLong { max, got } => {
                write!(f, "payload of {got} bytes exceeds the {max}-byte maximum")
            }
        }
    }
}

impl core::error::Error for FrameError {}

/// Errors from decoding a frame's payload into a typed [`crate::message::MavMessage`].
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MessageError {
    /// The frame's message ID didn't match any message this crate decodes.
    UnknownMessageId(u32),
    /// The frame's checksum didn't match the one computed using this
    /// message's `crc_extra` byte.
    ChecksumMismatch,
}

impl fmt::Display for MessageError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::UnknownMessageId(id) => write!(f, "unknown/undecoded message id: {id}"),
            Self::ChecksumMismatch => write!(f, "checksum mismatch"),
        }
    }
}

impl core::error::Error for MessageError {}

/// Top-level error type composing every layer, for `?`-based error
/// propagation.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MavError {
    /// Error in the frame layer (magic byte, length, signing).
    Frame(FrameError),
    /// Error in the message layer (unknown message ID, checksum mismatch).
    Message(MessageError),
}

impl fmt::Display for MavError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Frame(e) => write!(f, "{e}"),
            Self::Message(e) => write!(f, "{e}"),
        }
    }
}

impl core::error::Error for MavError {}

impl From<FrameError> for MavError {
    fn from(e: FrameError) -> Self {
        Self::Frame(e)
    }
}

impl From<MessageError> for MavError {
    fn from(e: MessageError) -> Self {
        Self::Message(e)
    }
}