mbrtu 0.1.2

no_std, no_alloc parser and encoder for Modbus RTU PDUs
Documentation
//! A `no_std`, allocation-free parser and encoder for Modbus RTU, the
//! serial-line PDU encoding used by industrial PLCs, sensors, and other
//! field devices.
//!
//! # Layering
//!
//! - [`frame`] parses/encodes the raw address/function-code/data/CRC-16
//!   framing.
//! - [`crc`] is Modbus RTU's CRC-16 checksum.
//! - [`message`] decodes/encodes a frame's data into a typed
//!   [`ModbusRequest`] or [`ModbusResponse`], one variant per supported
//!   function code.
//!
//! # No allocation
//!
//! Nothing in this crate uses `alloc`.
#![no_std]
#![forbid(unsafe_code)]
#![warn(missing_docs)]

pub mod crc;
pub mod error;
pub mod frame;
pub mod message;

pub use error::MbrtuError;
pub use frame::Frame;
pub use message::{ModbusRequest, ModbusResponse};

/// Parses a single frame from `buf` and decodes it as a request PDU (see
/// the [`message`] module docs on why direction is a caller-supplied
/// fact, not something recoverable from the bytes alone).
///
/// # Errors
/// Returns an [`MbrtuError`] if the frame fails to parse/CRC-validate, or
/// its function code isn't one this crate decodes as a request.
pub fn decode_request(buf: &[u8]) -> Result<ModbusRequest, MbrtuError> {
    let frame = Frame::parse(buf)?;
    Ok(ModbusRequest::decode(frame.function_code(), frame.data())?)
}

/// Parses a single frame from `buf` and decodes it as a response PDU.
///
/// # Errors
/// Returns an [`MbrtuError`] if the frame fails to parse/CRC-validate (see
/// [`Frame::parse_response`] for why a broadcast-address frame is one
/// such failure), or its function code isn't one this crate decodes as a
/// response.
pub fn decode_response(buf: &[u8]) -> Result<ModbusResponse, MbrtuError> {
    let frame = Frame::parse_response(buf)?;
    Ok(ModbusResponse::decode(frame.function_code(), frame.data())?)
}

/// Encodes a request PDU into a full frame in `buf`, returning the number
/// of bytes written.
///
/// # Errors
/// Returns an [`MbrtuError`] if the encoded frame doesn't fit in `buf`
/// (size it with [`frame::MAX_FRAME_LEN`] to always be safe).
pub fn encode_request(
    address: u8,
    request: &ModbusRequest,
    buf: &mut [u8],
) -> Result<usize, MbrtuError> {
    let mut data = [0u8; frame::MAX_DATA_LEN];
    let data_len = request.encode(&mut data)?;
    Ok(frame::encode(
        buf,
        address,
        request.function_code(),
        &data[..data_len],
    )?)
}

/// Encodes a response PDU into a full frame in `buf`, returning the
/// number of bytes written.
///
/// # Errors
/// Returns an [`MbrtuError`] if the encoded frame doesn't fit in `buf`
/// (size it with [`frame::MAX_FRAME_LEN`] to always be safe).
pub fn encode_response(
    address: u8,
    response: &ModbusResponse,
    buf: &mut [u8],
) -> Result<usize, MbrtuError> {
    let mut data = [0u8; frame::MAX_DATA_LEN];
    let data_len = response.encode(&mut data)?;
    Ok(frame::encode(
        buf,
        address,
        response.function_code(),
        &data[..data_len],
    )?)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn decodes_a_reference_request_frame() {
        // Cross-checked against pymodbus (the classic Modbus spec
        // example): unit 0x11, Read Holding Registers.
        let buf = [0x11, 0x03, 0x00, 0x6B, 0x00, 0x03, 0x76, 0x87];
        let req = decode_request(&buf).unwrap();
        let ModbusRequest::ReadHoldingRegisters(m) = req else {
            panic!("expected ReadHoldingRegisters");
        };
        assert_eq!(m.starting_address, 0x006B);
        assert_eq!(m.quantity, 3);
    }

    #[test]
    fn encode_round_trips() {
        let original = ModbusRequest::WriteSingleRegister(message::WriteSingleRegister {
            address: 1,
            value: 3,
        });
        let mut buf = [0u8; frame::MAX_FRAME_LEN];
        let n = encode_request(0x01, &original, &mut buf).unwrap();
        assert_eq!(decode_request(&buf[..n]).unwrap(), original);
    }
}