cat24c32_rs/

lib.rs

//! # CAT24C32 EEPROM Driver
//!
//! Platform-agnostic Rust driver for the CAT24C32 EEPROM Serial 32-Kb I2C device
//! using the [`embedded-hal`] traits.
//!
//! The CAT24C32 is an EEPROM Serial 32-Kb I2C device, internally organized as 4096 words of 8 bits each.
//! It features a 32-byte page write buffer and supports the Standard (100 kHz), Fast (400 kHz)
//! and Fast-Plus (1 MHz) I2C protocol.
//!
//! ## Features
//!
//! - Platform-agnostic using embedded-hal traits
//! - Single byte and page write operations
//! - Single byte and sequential read operations
//! - Support for multiple devices on the same bus via address pins
//! - Compatible with embedded-storage traits for ecosystem integration
//!
//! ## Usage
//!
//! ```rust,no_run
//! use cat24c32_rs::{Cat24c32, SlaveAddr};
//! # use linux_embedded_hal::I2cdev;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! #     let dev = I2cdev::new("/dev/i2c-1")?;
//! let mut eeprom = Cat24c32::new(dev, SlaveAddr::Default);
//!
//! // Write a byte
//! let _ = eeprom.write_byte(0x00, 0x42);
//!
//! // Read a byte  
//! let value = eeprom.read_byte(0x00);
//! match value {
//!     Ok(val) => println!("Read value: 0x{:02X}", val),
//!     Err(_) => println!("Read error"),
//! }
//! #     Ok(())
//! # }
//! ```
//!
//! ### Using with embedded-storage
//!
//! The driver implements the `embedded-storage` traits for ecosystem compatibility:
//!
//! ```rust,no_run
//! use cat24c32_rs::{Cat24c32, SlaveAddr};
//! use embedded_storage::nor_flash::NorFlash;
//! # use linux_embedded_hal::I2cdev;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! #     let dev = I2cdev::new("/dev/i2c-1")?;
//! let mut eeprom = Cat24c32::new(dev, SlaveAddr::Default);
//!
//! // Using NorFlash trait (with automatic page write optimization)
//! let data = b"Hello, storage!";
//! let _ = NorFlash::write(&mut eeprom, 0x0000, data);
//! # Ok(())
//! # }
//! ```
//!
//! [`embedded-hal`]: https://github.com/rust-embedded/embedded-hal

#![no_std]
#![doc(html_root_url = "https://docs.rs/cat24c32-rs/0.1.0")]
#![warn(missing_docs)]

use embedded_hal::i2c::I2c;
use embedded_storage::{ReadStorage, Storage};
use embedded_storage::nor_flash::{ErrorType, ReadNorFlash, NorFlash, NorFlashError, NorFlashErrorKind};

// Re-export for convenience
pub use embedded_storage;

/// All possible errors in this crate
#[derive(Debug, Clone, PartialEq)]
pub enum Error<E> {
    /// I²C bus error
    I2C(E),
    /// Too much data passed for a write operation
    ///
    /// This occurs when trying to write more data than fits in a single page,
    /// or when the write operation would cross a page boundary.
    TooMuchData,
    /// Memory address is out of range
    ///
    /// The provided address exceeds the device's memory capacity (0x0000-0x0FFF).
    InvalidAddr,
}

impl<E: core::fmt::Debug> NorFlashError for Error<E> {
    fn kind(&self) -> NorFlashErrorKind {
        match self {
            Error::I2C(_) => NorFlashErrorKind::Other,
            Error::TooMuchData => NorFlashErrorKind::OutOfBounds,
            Error::InvalidAddr => NorFlashErrorKind::OutOfBounds,
        }
    }
}

/// Possible slave addresses for CAT24C32 devices
///
/// The CAT24C32 supports up to 8 devices on the same I2C bus by using
/// different combinations of the A2, A1, and A0 address pins.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SlaveAddr {
    /// Default slave address (0x50)
    ///
    /// This corresponds to A2=A1=A0=0 (all address pins tied to ground).
    Default,
    /// Alternative slave address providing bit values for A2, A1 and A0
    ///
    /// # Arguments
    /// * First bool: A2 pin state (true = VCC, false = GND)
    /// * Second bool: A1 pin state (true = VCC, false = GND)  
    /// * Third bool: A0 pin state (true = VCC, false = GND)
    ///
    /// # Examples
    /// ```
    /// use cat24c32_rs::SlaveAddr;
    ///
    /// // A2=1, A1=0, A0=1 -> address 0x55
    /// let addr = SlaveAddr::Alternative(true, false, true);
    /// ```
    Alternative(bool, bool, bool),
}

impl SlaveAddr {
    /// Get the base I2C address for this slave address configuration
    pub(crate) fn addr(self) -> u8 {
        match self {
            SlaveAddr::Default => 0x50,
            SlaveAddr::Alternative(a2, a1, a0) => {
                0x50 | ((a2 as u8) << 2) | ((a1 as u8) << 1) | (a0 as u8)
            }
        }
    }

    /// Get the device address for a specific memory address
    ///
    /// For CAT24C32, the high bits of the memory address are encoded
    /// in the device address for addressing beyond 256 bytes.
    pub(crate) fn devaddr(self, memory_address: u32, address_bits: u8) -> u8 {
        let base_addr = self.addr();

        if address_bits > 8 {
            // For addresses requiring more than 8 bits, use the high bits
            // in the device address (bits A1 and A0 of device address)
            let high_bits = ((memory_address >> 8) & 0x07) as u8;
            let device_bits = match self {
                SlaveAddr::Default => high_bits,
                SlaveAddr::Alternative(a2, _, _) => {
                    // Preserve A2, use memory high bits for A1,A0
                    ((a2 as u8) << 2) | (high_bits & 0x03)
                }
            };
            0x50 | device_bits
        } else {
            base_addr
        }
    }
}

/// CAT24C32 EEPROM driver
///
/// This struct represents a CAT24C32 EEPROM device connected via I2C.
///
/// # Constants
/// - Memory size: 32 Kb (4096 bytes)
/// - Address range: 0x0000 to 0x0FFF
/// - Page size: 32 bytes
/// - Address size: 2 bytes
#[derive(Debug)]
pub struct Cat24c32<I2C> {
    /// The I²C bus implementation
    i2c: I2C,
    /// The I²C device address configuration
    address: SlaveAddr,
}

impl<I2C> Cat24c32<I2C> {
    /// Create a new CAT24C32 EEPROM driver instance
    ///
    /// # Arguments
    /// * `i2c` - I2C bus implementation
    /// * `address` - Slave address configuration
    ///
    /// # Examples
    /// ```rust,no_run
    /// use cat24c32_rs::{Cat24c32, SlaveAddr};
    /// # use linux_embedded_hal::I2cdev;
    /// # let i2c = I2cdev::new("/dev/i2c-1").unwrap();
    ///
    /// let eeprom = Cat24c32::new(i2c, SlaveAddr::Default);
    /// ```
    pub fn new(i2c: I2C, address: SlaveAddr) -> Self {
        Self { i2c, address }
    }

    /// Destroy driver instance and return the I²C bus
    pub fn destroy(self) -> I2C {
        self.i2c
    }

    /// Get the device I2C address for a specific memory address
    fn get_device_address<E>(&self, memory_address: u32) -> Result<u8, Error<E>> {
        if memory_address > 0x0FFF {
            return Err(Error::InvalidAddr);
        }
        Ok(self.address.devaddr(memory_address, 12))
    }

    /// Return the device's page size in bytes (always 32 for CAT24C32)
    pub fn page_size(&self) -> usize {
        32
    }
}

impl<I2C, E> Cat24c32<I2C>
where
    I2C: I2c<Error = E>,
{
    /// Write a single byte to a specific address
    ///
    /// After writing a byte, the EEPROM enters an internally-timed write cycle
    /// to the nonvolatile memory. During this time all inputs are disabled and
    /// the EEPROM will not respond until the write is complete (typically 5ms).
    ///
    /// # Arguments
    /// * `address` - Memory address to write to (0x0000 to 0x0FFF)
    /// * `data` - The byte value to write
    ///
    /// # Errors
    /// Returns `Error::InvalidAddr` if the address is out of range,
    /// or `Error::I2C` if there's an I2C communication error.
    pub fn write_byte(&mut self, address: u32, data: u8) -> Result<(), Error<E>> {
        let devaddr = self.get_device_address(address)?;
        let payload = [(address >> 8) as u8, address as u8, data];
        self.i2c.write(devaddr, &payload).map_err(Error::I2C)
    }

    /// Read a single byte from a specific address
    ///
    /// # Arguments
    /// * `address` - Memory address to read from (0x0000 to 0x0FFF)
    ///
    /// # Returns
    /// The byte value at the specified address.
    ///
    /// # Errors
    /// Returns `Error::InvalidAddr` if the address is out of range,
    /// or `Error::I2C` if there's an I2C communication error.
    pub fn read_byte(&mut self, address: u32) -> Result<u8, Error<E>> {
        let devaddr = self.get_device_address(address)?;
        let memaddr = [(address >> 8) as u8, address as u8];
        let mut data = [0u8; 1];
        self.i2c
            .write_read(devaddr, &memaddr, &mut data)
            .map_err(Error::I2C)?;
        Ok(data[0])
    }

    /// Read multiple bytes starting from a specific address
    ///
    /// This performs a sequential read operation, automatically incrementing
    /// the address for each byte read.
    ///
    /// # Arguments
    /// * `address` - Starting memory address (0x0000 to 0x0FFF)
    /// * `data` - Buffer to fill with read data
    ///
    /// # Errors
    /// Returns `Error::InvalidAddr` if the address is out of range,
    /// or `Error::I2C` if there's an I2C communication error.
    pub fn read_data(&mut self, address: u32, data: &mut [u8]) -> Result<(), Error<E>> {
        let devaddr = self.get_device_address(address)?;
        let memaddr = [(address >> 8) as u8, address as u8];
        self.i2c
            .write_read(devaddr, &memaddr, data)
            .map_err(Error::I2C)
    }

    /// Read from the current address pointer
    ///
    /// This reads the contents of the last address accessed during the last read
    /// or write operation, _incremented by one_. This feature may not be available
    /// on all I2C implementations.
    ///
    /// # Returns
    /// The byte value at the current address pointer.
    ///
    /// # Errors
    /// Returns `Error::I2C` if there's an I2C communication error.
    pub fn read_current_address(&mut self) -> Result<u8, Error<E>> {
        let mut data = [0u8; 1];
        self.i2c
            .read(self.address.addr(), &mut data)
            .map_err(Error::I2C)?;
        Ok(data[0])
    }

    /// Write up to one page of data starting at a specific address
    ///
    /// The CAT24C32 has a 32-byte page write buffer. Data written in a single
    /// page write operation must not cross page boundaries. If too much data is passed
    /// or if the write would cross a page boundary, `Error::TooMuchData` will be returned.
    ///
    /// After writing, the EEPROM enters an internally-timed write cycle
    /// to the nonvolatile memory. During this time all inputs are disabled and
    /// the EEPROM will not respond until the write is complete (typically 5ms).
    ///
    /// # Arguments
    /// * `address` - Starting memory address for the write
    /// * `data` - Data to write (must not exceed 32 bytes or cross page boundaries)
    ///
    /// # Errors
    /// * `Error::TooMuchData` - If data exceeds page size or crosses page boundary
    /// * `Error::InvalidAddr` - If the address is out of range
    /// * `Error::I2C` - If there's an I2C communication error
    pub fn write_page(&mut self, address: u32, data: &[u8]) -> Result<(), Error<E>> {
        if data.is_empty() {
            return Ok(());
        }

        if data.len() > 32 {
            return Err(Error::TooMuchData);
        }

        // Check page boundary (32-byte pages)
        let page_boundary = address | 31; // 32-byte page boundary
        if address + data.len() as u32 > page_boundary + 1 {
            return Err(Error::TooMuchData);
        }

        let devaddr = self.get_device_address(address)?;
        let mut payload = [0u8; 34]; // 2 bytes address + 32 bytes max data
        payload[0] = (address >> 8) as u8;
        payload[1] = address as u8;
        payload[2..2 + data.len()].copy_from_slice(data);

        self.i2c
            .write(devaddr, &payload[..2 + data.len()])
            .map_err(Error::I2C)
    }
}

// Embedded Storage trait implementations
impl<I2C, E> Storage for Cat24c32<I2C>
where
    I2C: I2c<Error = E>,
    E: core::fmt::Debug,
{
    fn write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), <Self as ReadStorage>::Error> {
        NorFlash::write(self, offset, bytes)
    }
}

impl<I2C, E> ReadStorage for Cat24c32<I2C>
where
    I2C: I2c<Error = E>,
    E: core::fmt::Debug,
{
    type Error = Error<E>;

    /// Read data from the EEPROM starting at the specified address
    ///
    /// # Arguments
    /// * `offset` - Memory address to read from (0x0000 to 0x0FFF)
    /// * `bytes` - Buffer to fill with read data
    ///
    /// # Errors
    /// Returns `Error::InvalidAddr` if the address is out of range,
    /// or `Error::I2C` if there's an I2C communication error.
    fn read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Self::Error> {
        self.read_data(offset, bytes)
    }

    /// Get the capacity of the storage device in bytes
    ///
    /// Returns 4096 bytes (4KB) for the CAT24C32.
    fn capacity(&self) -> usize {
        4096
    }
}

// ErrorType implementation for nor_flash traits
impl<I2C, E> ErrorType for Cat24c32<I2C>
where
    I2C: I2c<Error = E>,
    E: core::fmt::Debug,
{
    type Error = Error<E>;
}

// Note: CAT24C32 is EEPROM, not NOR flash, but we can implement similar traits
// for compatibility with embedded-storage ecosystem
impl<I2C, E> ReadNorFlash for Cat24c32<I2C>
where
    I2C: I2c<Error = E>,
    E: core::fmt::Debug,
{
    const READ_SIZE: usize = 1; // Can read individual bytes

    /// Read data from the EEPROM
    fn read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Self::Error> {
        self.read_data(offset, bytes)
    }

    /// Get the capacity of the storage device
    fn capacity(&self) -> usize {
        4096
    }
}

impl<I2C, E> NorFlash for Cat24c32<I2C>
where
    I2C: I2c<Error = E>,
    E: core::fmt::Debug,
{
    const WRITE_SIZE: usize = 1; // Can write individual bytes
    const ERASE_SIZE: usize = 1; // EEPROM doesn't need explicit erase, smallest unit is 1 byte

    /// Write data to the EEPROM
    ///
    /// For optimal performance, try to write complete pages (32 bytes) when possible.
    /// This implementation will automatically use page writes when the data fits
    /// within a single page boundary.
    fn write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), Self::Error> {
        if bytes.is_empty() {
            return Ok(());
        }

        // For writes that fit within a single page, use page write for efficiency
        if bytes.len() <= 32 {
            let page_boundary = offset | 31; // 32-byte page boundary
            if offset + bytes.len() as u32 <= page_boundary + 1 {
                return self.write_page(offset, bytes);
            }
        }

        // For larger writes or writes that cross page boundaries, write byte by byte
        for (i, &byte) in bytes.iter().enumerate() {
            self.write_byte(offset + i as u32, byte)?;
        }
        Ok(())
    }

    /// EEPROM doesn't require explicit erase - data can be overwritten directly
    ///
    /// This is a no-op since EEPROM cells can be written directly without erasing.
    fn erase(&mut self, _from: u32, _to: u32) -> Result<(), Self::Error> {
        // EEPROM doesn't need explicit erase operation
        Ok(())
    }
}

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

    #[test]
    fn test_slave_address_default() {
        let addr = SlaveAddr::Default;
        assert_eq!(addr.addr(), 0x50);
    }

    #[test]
    fn test_slave_address_alternative() {
        let addr = SlaveAddr::Alternative(true, false, true);
        assert_eq!(addr.addr(), 0x55); // 0x50 | 0x04 | 0x01
    }

    #[test]
    fn test_page_boundary_calculation() {
        // Test that page boundary checks work correctly
        let boundary_32 = 0x00 | 31; // Should be 31 (0x1F)
        assert_eq!(boundary_32, 31);

        let boundary_64 = 0x40 | 31; // Should be 95 (0x5F)
        assert_eq!(boundary_64, 95);
    }
}