mbus-core 0.2.0

//! # Modbus Checksum Utilities
//!
//! This module provides error-detection algorithms used by the Modbus protocol to ensure
//! data integrity across different transport layers.
//!
//! ## Supported Algorithms
//!
//! ### 1. Cyclic Redundancy Check (CRC-16)
//! Used primarily in **Modbus RTU**. It employs the polynomial `0xA001` (the reverse of `0x8005`)
//! with an initial value of `0xFFFF`. This implementation uses a precomputed lookup table
//! to provide high-performance calculations suitable for real-time embedded systems.
//!
//! ### 2. Longitudinal Redundancy Check (LRC)
//! Used primarily in **Modbus ASCII**. It is a simpler 8-bit checksum calculated as the
//! two's complement of the sum of all bytes in the message.
//!
//! ## Usage Examples
//!
//! ```rust
//! use mbus_core::transport::checksum::{crc16, lrc};
//!
//! let rtu_data = [0x01, 0x03, 0x00, 0x6B, 0x00, 0x03];
//! let rtu_checksum = crc16(&rtu_data); // Returns 0x1774
//!
//! let ascii_data = [0x01, 0x03, 0x00, 0x00, 0x00, 0x01];
//! let ascii_checksum = lrc(&ascii_data); // Returns 0xFB
//! ```

// CRC-16-MODBUS lookup table
const CRC16_TABLE: [u16; 256] = [
    0x0000, 0xC0C1, 0xC181, 0x0140, 0xC301, 0x03C0, 0x0280, 0xC241, 0xC601, 0x06C0, 0x0780, 0xC741,
    0x0500, 0xC5C1, 0xC481, 0x0440, 0xCC01, 0x0CC0, 0x0D80, 0xCD41, 0x0F00, 0xCFC1, 0xCE81, 0x0E40,
    0x0A00, 0xCAC1, 0xCB81, 0x0B40, 0xC901, 0x09C0, 0x0880, 0xC841, 0xD801, 0x18C0, 0x1980, 0xD941,
    0x1B00, 0xDBC1, 0xDA81, 0x1A40, 0x1E00, 0xDEC1, 0xDF81, 0x1F40, 0xDD01, 0x1DC0, 0x1C80, 0xDC41,
    0x1400, 0xD4C1, 0xD581, 0x1540, 0xD701, 0x17C0, 0x1680, 0xD641, 0xD201, 0x12C0, 0x1380, 0xD341,
    0x1100, 0xD1C1, 0xD081, 0x1040, 0xF001, 0x30C0, 0x3180, 0xF141, 0x3300, 0xF3C1, 0xF281, 0x3240,
    0x3600, 0xF6C1, 0xF781, 0x3740, 0xF501, 0x35C0, 0x3480, 0xF441, 0x3C00, 0xFCC1, 0xFD81, 0x3D40,
    0xFF01, 0x3FC0, 0x3E80, 0xFE41, 0xFA01, 0x3AC0, 0x3B80, 0xFB41, 0x3900, 0xF9C1, 0xF881, 0x3840,
    0x2800, 0xE8C1, 0xE981, 0x2940, 0xEB01, 0x2BC0, 0x2A80, 0xEA41, 0xEE01, 0x2EC0, 0x2F80, 0xEF41,
    0x2D00, 0xEDC1, 0xEC81, 0x2C40, 0xE401, 0x24C0, 0x2580, 0xE541, 0x2700, 0xE7C1, 0xE681, 0x2640,
    0x2200, 0xE2C1, 0xE381, 0x2340, 0xE101, 0x21C0, 0x2080, 0xE041, 0xA001, 0x60C0, 0x6180, 0xA141,
    0x6300, 0xA3C1, 0xA281, 0x6240, 0x6600, 0xA6C1, 0xA781, 0x6740, 0xA501, 0x65C0, 0x6480, 0xA441,
    0x6C00, 0xACC1, 0xAD81, 0x6D40, 0xAF01, 0x6FC0, 0x6E80, 0xAE41, 0xAA01, 0x6AC0, 0x6B80, 0xAB41,
    0x6900, 0xA9C1, 0xA881, 0x6840, 0x7800, 0xB8C1, 0xB981, 0x7940, 0xBB01, 0x7BC0, 0x7A80, 0xBA41,
    0xBE01, 0x7EC0, 0x7F80, 0xBF41, 0x7D00, 0xBDC1, 0xBC81, 0x7C40, 0xB401, 0x74C0, 0x7580, 0xB541,
    0x7700, 0xB7C1, 0xB681, 0x7640, 0x7200, 0xB2C1, 0xB381, 0x7340, 0xB101, 0x71C0, 0x7080, 0xB041,
    0x5000, 0x90C1, 0x9181, 0x5140, 0x9301, 0x53C0, 0x5280, 0x9241, 0x9601, 0x56C0, 0x5780, 0x9741,
    0x5500, 0x95C1, 0x9481, 0x5440, 0x9C01, 0x5CC0, 0x5D80, 0x9D41, 0x5F00, 0x9FC1, 0x9E81, 0x5E40,
    0x5A00, 0x9AC1, 0x9B81, 0x5B40, 0x9901, 0x59C0, 0x5880, 0x9841, 0x8801, 0x48C0, 0x4980, 0x8941,
    0x4B00, 0x8BC1, 0x8A81, 0x4A40, 0x4E00, 0x8EC1, 0x8F81, 0x4F40, 0x8D01, 0x4DC0, 0x4C80, 0x8C41,
    0x4400, 0x84C1, 0x8581, 0x4540, 0x8701, 0x47C0, 0x4680, 0x8641, 0x8201, 0x42C0, 0x4380, 0x8341,
    0x4100, 0x81C1, 0x8081, 0x4040,
];

/// Computes the Modbus CRC16 checksum for the given data using a lookup table.
///
/// The CRC is calculated using the standard Modbus polynomial (0xA001) and an initial
/// value of 0xFFFF. The resulting CRC is returned as a u16 value. In Modbus RTU,
/// this value is transmitted in little-endian byte order.
///
/// # Arguments
///
/// * `data` - A slice of bytes for which to calculate the CRC.
///
/// # Returns
///
/// A `u16` representing the calculated CRC16 checksum.
pub fn crc16(data: &[u8]) -> u16 {
    let mut crc = 0xFFFF;
    for &byte in data {
        let index = (crc ^ byte as u16) & 0xFF;
        crc = (crc >> 8) ^ CRC16_TABLE[index as usize];
    }
    crc
}

/// Computes the Longitudinal Redundancy Check (LRC) for the given data.
///
/// The LRC is calculated as the two's complement of the sum of all bytes in the data,
/// ignoring overflows. This is used for error checking in Modbus ASCII mode.
///
/// # Arguments
///
/// * `data` - A slice of bytes for which to calculate the LRC.
///
/// # Returns
///
/// A `u8` representing the calculated LRC.
pub fn lrc(data: &[u8]) -> u8 {
    let sum = data.iter().fold(0u8, |acc, &x| acc.wrapping_add(x));
    sum.wrapping_neg()
}

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

    /// Test case: `crc16` with a known request PDU from Modbus specification examples.
    /// Request: Read Holding Registers (FC 0x03) from slave 1, address 0x006B, quantity 3.
    /// PDU: 01 03 00 6B 00 03
    /// Expected CRC: 7B E4
    /// The CRC is transmitted little-endian, so E4 7B. The calculation returns a u16.
    /// The value 0x1774 should be returned.
    #[test]
    fn test_crc16_read_holding_registers() {
        let data = [0x01, 0x03, 0x00, 0x6B, 0x00, 0x03];
        // The CRC is transmitted little-endian (LSB first), so the bytes are E4 7B.
        // The u16 value is 0x1774.
        assert_eq!(crc16(&data), 0x1774);
    }

    /// Test case: `crc16` with another known request PDU.
    /// Request: Write Single Coil (FC 0x05) to slave 1, address 0x00AC, value ON (FF00).
    /// PDU: 01 05 00 AC FF 00
    /// Expected CRC: 0x1B4C
    #[test]
    fn test_crc16_write_single_coil() {
        let data = [0x01, 0x05, 0x00, 0xAC, 0xFF, 0x00];
        // The CRC is transmitted little-endian (LSB first), so the bytes are 4B C2.
        // The u16 value is 0x1B4C.
        assert_eq!(crc16(&data), 0x1B4C);
    }

    /// Test case: `crc16` with a response PDU.
    /// Response for Read Holding Registers (FC 0x03) from slave 1.
    /// PDU: 01 03 06 AE 41 56 52 43 40
    /// Expected CRC: 6D 84
    #[test]
    fn test_crc16_read_holding_registers_response() {
        let data = [0x01, 0x03, 0x06, 0xAE, 0x41, 0x56, 0x52, 0x43, 0x40];
        // The CRC is transmitted little-endian (LSB first).
        // The calculated u16 value is 0x6D84 (28036).
        assert_eq!(crc16(&data), 0x6D84);
    }

    /// Test case: `crc16` with the user provided frame.
    /// Request: Read Holding Registers (FC 0x03) from slave 1, address 0x0001, quantity 2.
    /// PDU: 01 03 00 01 00 02
    /// Expected CRC: CB 95 (transmitted as 95 CB)
    #[test]
    fn test_crc16_read_holding_registers_small_range() {
        let data = [0x01, 0x03, 0x00, 0x01, 0x00, 0x02];
        assert_eq!(crc16(&data), 0xCB95);
    }

    /// Test case: `lrc` with a known request from Modbus ASCII examples.
    /// Request: Read Holding Registers from slave 1, address 0x0000, quantity 1.
    /// Message fields: 01 03 00 00 00 01
    /// Sum = 0x01 + 0x03 + 0x00 + 0x00 + 0x00 + 0x01 = 0x05.
    /// LRC = two's complement of 0x05 = 0xFB.
    #[test]
    fn test_lrc_read_holding_registers() {
        let data = [0x01, 0x03, 0x00, 0x00, 0x00, 0x01];
        assert_eq!(lrc(&data), 0xFB);
    }

    /// Test case: `lrc` with another known request.
    /// Request: Write Single Register to slave 1, address 0x0001, value 0x0003.
    /// Message fields: 01 06 00 01 00 03
    /// Sum = 0x01 + 0x06 + 0x00 + 0x01 + 0x00 + 0x03 = 0x0B.
    /// LRC = two's complement of 0x0B = 0xF5.
    #[test]
    fn test_lrc_write_single_register() {
        let data = [0x01, 0x06, 0x00, 0x01, 0x00, 0x03];
        assert_eq!(lrc(&data), 0xF5);
    }

    /// Test case: `lrc` with a response.
    /// Response for Write Single Register.
    /// Message fields: 01 06 00 01 00 03
    /// Sum = 0x01 + 0x06 + 0x00 + 0x01 + 0x00 + 0x03 = 0x0B.
    /// LRC = two's complement of 0x0B = 0xF5.
    #[test]
    fn test_lrc_write_single_register_response() {
        let data = [0x01, 0x06, 0x00, 0x01, 0x00, 0x03];
        assert_eq!(lrc(&data), 0xF5);
    }

    /// Test case: `lrc` with a sum that wraps around.
    /// Data: [0xFF, 0x02]
    /// Sum = 0xFF + 0x02 = 0x101. The wrapped sum is 0x01.
    /// LRC = two's complement of 0x01 = 0xFF.
    #[test]
    fn test_lrc_wrapping_sum() {
        let data = [0xFF, 0x02];
        assert_eq!(lrc(&data), 0xFF);
    }
}