mbrtu 0.1.2

no_std, no_alloc parser and encoder for Modbus RTU PDUs
Documentation
//! Function-code-dispatched decoding/encoding of a frame's data into a
//! typed [`ModbusRequest`] or [`ModbusResponse`].
//!
//! Modbus request and response PDUs for the same function code often
//! have different shapes (a Read Holding Registers request is always 4
//! fixed bytes; its response is a byte count followed by variable-length
//! register data), but not always distinguishably so from the bytes
//! alone - a short response can coincidentally be the same length as a
//! request. Direction is protocol context a real Modbus stack always
//! tracks itself (a master decodes a response only after it sent the
//! matching request), not something recoverable from a single PDU in
//! isolation, so decoding is split into two entry points, one per
//! direction, rather than one that guesses.

mod exception;
mod read_coils;
mod read_holding_registers;
mod write_single_register;

pub use exception::{ExceptionCode, ExceptionResponse};
pub use read_coils::{ReadCoilsRequest, ReadCoilsResponse};
pub use read_holding_registers::{ReadHoldingRegistersRequest, ReadHoldingRegistersResponse};
pub use write_single_register::WriteSingleRegister;

use crate::error::MessageError;

/// A decoded Modbus RTU request PDU, one variant per supported function
/// code.
///
/// `#[non_exhaustive]`: more function codes will be added.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum ModbusRequest {
    /// Read Holding Registers (function code 3).
    ReadHoldingRegisters(ReadHoldingRegistersRequest),
    /// Read Coils (function code 1).
    ReadCoils(ReadCoilsRequest),
    /// Write Single Register (function code 6).
    WriteSingleRegister(WriteSingleRegister),
}

impl ModbusRequest {
    /// Decodes a frame's function code and data as a request PDU.
    ///
    /// # Errors
    /// Returns [`MessageError::UnknownFunctionCode`] if `function_code`
    /// isn't one this crate decodes as a request, or another
    /// [`MessageError`] if `data` is malformed for that function code.
    pub fn decode(function_code: u8, data: &[u8]) -> Result<Self, MessageError> {
        match function_code {
            read_holding_registers::FUNCTION_CODE => Ok(Self::ReadHoldingRegisters(
                ReadHoldingRegistersRequest::decode(data)?,
            )),
            read_coils::FUNCTION_CODE => Ok(Self::ReadCoils(ReadCoilsRequest::decode(data)?)),
            write_single_register::FUNCTION_CODE => Ok(Self::WriteSingleRegister(
                WriteSingleRegister::decode(data)?,
            )),
            other => Err(MessageError::UnknownFunctionCode(other)),
        }
    }

    /// This request's function code.
    #[must_use]
    pub const fn function_code(&self) -> u8 {
        match self {
            Self::ReadHoldingRegisters(_) => read_holding_registers::FUNCTION_CODE,
            Self::ReadCoils(_) => read_coils::FUNCTION_CODE,
            Self::WriteSingleRegister(_) => write_single_register::FUNCTION_CODE,
        }
    }

    /// Encodes this request's data (not including the function code) into
    /// `buf`, returning the number of bytes written.
    ///
    /// # Errors
    /// Returns a [`MessageError`] if `buf` is too small.
    pub fn encode(&self, buf: &mut [u8]) -> Result<usize, MessageError> {
        match self {
            Self::ReadHoldingRegisters(m) => m.encode(buf),
            Self::ReadCoils(m) => m.encode(buf),
            Self::WriteSingleRegister(m) => m.encode(buf),
        }
    }
}

/// A decoded Modbus RTU response PDU, one variant per supported function
/// code, plus [`ExceptionResponse`] (which any function code's response
/// may become).
///
/// `#[non_exhaustive]`: more function codes will be added.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum ModbusResponse {
    /// Read Holding Registers (function code 3).
    ReadHoldingRegisters(ReadHoldingRegistersResponse),
    /// Read Coils (function code 1).
    ReadCoils(ReadCoilsResponse),
    /// Write Single Register (function code 6).
    WriteSingleRegister(WriteSingleRegister),
    /// The device rejected the request.
    Exception(ExceptionResponse),
}

impl ModbusResponse {
    /// Decodes a frame's function code and data as a response PDU. A
    /// `function_code` with its high bit set (e.g. `0x83`) always decodes
    /// as [`Self::Exception`], regardless of which function failed.
    ///
    /// # Errors
    /// Returns [`MessageError::UnknownFunctionCode`] if `function_code`
    /// (with its high bit cleared) isn't one this crate decodes as a
    /// response, or another [`MessageError`] if `data` is malformed for
    /// that function code.
    pub fn decode(function_code: u8, data: &[u8]) -> Result<Self, MessageError> {
        if function_code & 0x80 != 0 {
            return Ok(Self::Exception(ExceptionResponse::decode(
                function_code,
                data,
            )?));
        }
        match function_code {
            read_holding_registers::FUNCTION_CODE => Ok(Self::ReadHoldingRegisters(
                ReadHoldingRegistersResponse::decode(data)?,
            )),
            read_coils::FUNCTION_CODE => Ok(Self::ReadCoils(ReadCoilsResponse::decode(data)?)),
            write_single_register::FUNCTION_CODE => Ok(Self::WriteSingleRegister(
                WriteSingleRegister::decode(data)?,
            )),
            other => Err(MessageError::UnknownFunctionCode(other)),
        }
    }

    /// This response's function code, with the high bit set for
    /// [`Self::Exception`].
    #[must_use]
    pub const fn function_code(&self) -> u8 {
        match self {
            Self::ReadHoldingRegisters(_) => read_holding_registers::FUNCTION_CODE,
            Self::ReadCoils(_) => read_coils::FUNCTION_CODE,
            Self::WriteSingleRegister(_) => write_single_register::FUNCTION_CODE,
            Self::Exception(e) => e.function_code | 0x80,
        }
    }

    /// Encodes this response's data (not including the function code)
    /// into `buf`, returning the number of bytes written.
    ///
    /// # Errors
    /// Returns a [`MessageError`] if `buf` is too small.
    pub fn encode(&self, buf: &mut [u8]) -> Result<usize, MessageError> {
        match self {
            Self::ReadHoldingRegisters(m) => m.encode(buf),
            Self::ReadCoils(m) => m.encode(buf),
            Self::WriteSingleRegister(m) => m.encode(buf),
            Self::Exception(m) => m.encode(buf),
        }
    }
}

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

    #[test]
    fn decodes_a_reference_request() {
        let data = [0x00, 0x6B, 0x00, 0x03];
        let req = ModbusRequest::decode(0x03, &data).unwrap();
        assert_eq!(req.function_code(), 0x03);
        assert!(matches!(req, ModbusRequest::ReadHoldingRegisters(_)));
    }

    #[test]
    fn decodes_a_reference_response() {
        let data = [0x06, 0x02, 0x2B, 0x00, 0x00, 0x00, 0x64];
        let resp = ModbusResponse::decode(0x03, &data).unwrap();
        assert_eq!(resp.function_code(), 0x03);
        assert!(matches!(resp, ModbusResponse::ReadHoldingRegisters(_)));
    }

    #[test]
    fn decodes_an_exception_response_regardless_of_which_function_failed() {
        let data = [0x02];
        let resp = ModbusResponse::decode(0x83, &data).unwrap();
        assert_eq!(resp.function_code(), 0x83);
        let ModbusResponse::Exception(exc) = resp else {
            panic!("expected Exception");
        };
        assert_eq!(exc.function_code, 0x03);
    }

    #[test]
    fn rejects_an_unknown_function_code() {
        assert_eq!(
            ModbusRequest::decode(0x2B, &[0, 0, 0, 0]),
            Err(MessageError::UnknownFunctionCode(0x2B))
        );
    }

    #[test]
    fn encode_then_decode_round_trips_a_request() {
        let original = ModbusRequest::WriteSingleRegister(WriteSingleRegister {
            address: 5,
            value: 42,
        });
        let mut buf = [0u8; 4];
        let n = original.encode(&mut buf).unwrap();
        let decoded = ModbusRequest::decode(original.function_code(), &buf[..n]).unwrap();
        assert_eq!(decoded, original);
    }
}

// Fuzzes decode over arbitrary function codes and data of varying length,
// and encode over arbitrary (including out-of-spec) struct field values -
// not just the hand-picked fixtures above. The encode side matters
// separately from decode: every struct here has public fields, so nothing
// stops a caller from constructing one with a count/byte_count that
// doesn't match its backing array's real size, which decode already
// guards against on the way in but encode did not always guard against on
// the way out (see read_holding_registers.rs's and read_coils.rs's
// encode_rejects_a_*_wider_than_the_backing_array regression tests).
#[cfg(test)]
mod proptests {
    extern crate std;

    use proptest::prelude::*;

    use super::{ModbusRequest, ModbusResponse, ReadCoilsResponse, ReadHoldingRegistersResponse};

    proptest! {
        #[test]
        fn request_decode_never_panics(function_code: u8, data in prop::collection::vec(any::<u8>(), 0..260)) {
            let _ = ModbusRequest::decode(function_code, &data);
        }

        #[test]
        fn response_decode_never_panics(function_code: u8, data in prop::collection::vec(any::<u8>(), 0..260)) {
            let _ = ModbusResponse::decode(function_code, &data);
        }

        #[test]
        fn request_decode_never_panics_for_known_function_codes(
            function_code in prop_oneof![Just(1u8), Just(3u8), Just(6u8)],
            data in prop::collection::vec(any::<u8>(), 0..260),
        ) {
            let _ = ModbusRequest::decode(function_code, &data);
        }

        #[test]
        fn response_decode_never_panics_for_known_function_codes(
            function_code in prop_oneof![Just(1u8), Just(3u8), Just(6u8), Just(0x81u8), Just(0x83u8), Just(0x86u8)],
            data in prop::collection::vec(any::<u8>(), 0..260),
        ) {
            let _ = ModbusResponse::decode(function_code, &data);
        }

        #[test]
        fn read_holding_registers_response_encode_never_panics(count: u8) {
            let msg = ReadHoldingRegistersResponse {
                count,
                registers: [0u16; super::read_holding_registers::MAX_REGISTERS],
            };
            let mut buf = [0u8; 1024];
            let _ = msg.encode(&mut buf);
        }

        #[test]
        fn read_coils_response_encode_never_panics(byte_count: u8) {
            let msg = ReadCoilsResponse {
                byte_count,
                bits: [0u8; super::read_coils::MAX_COIL_BYTES],
            };
            let mut buf = [0u8; 1024];
            let _ = msg.encode(&mut buf);
        }
    }
}