Struct rppal::i2c::I2c

pub struct I2c { /* fields omitted */ }

Provides access to the Raspberry Pi’s I2C peripheral.

Before using I2c, make sure your Raspberry Pi has the necessary I2C buses enabled. More information can be found here.

Besides basic I2C communication through buffer reads and writes, I2c can also be used with devices that require SMBus (System Management Bus) support. SMBus is based on I2C, and defines more structured message transactions through its various protocols. More details can be found in the latest SMBus specification.

The embedded-hal blocking::i2c::Read, blocking::i2c::Write and blocking::i2c::WriteRead trait implementations for I2c can be enabled by specifying the optional hal feature in the dependency declaration for the rppal crate.

Implementations

impl I2c

pub fn new() -> Result<I2c>

Constructs a new I2c.

new attempts to identify which I2C bus is bound to physical pins 3 (SDA) and 5 (SCL) based on the Raspberry Pi model.

More information on configuring the I2C buses can be found here.

pub fn with_bus(bus: u8) -> Result<I2c>

Constructs a new I2c using the specified bus.

bus indicates the selected I2C bus. You’ll typically want to select the bus that’s bound to physical pins 3 (SDA) and 5 (SCL). On the Raspberry Pi B Rev 1, those pins are tied to bus 0. On every other Raspberry Pi model, they’re connected to bus 1. Additional I2C buses are available on the Raspberry Pi 4 B and 400.

More information on configuring the I2C buses can be found here.

pub fn capabilities(&self) -> Capabilities

Returns information on the functionality supported by the underlying drivers.

The returned Capabilities instance lists the available I2C and SMBus features.

pub fn bus(&self) -> u8

Returns the I2C bus ID.

pub fn clock_speed(&self) -> Result<u32>

Returns the clock frequency in hertz (Hz).

pub fn set_slave_address(&mut self, slave_address: u16) -> Result<()>

Sets a 7-bit or 10-bit slave address.

slave_address refers to the slave device you’re communicating with. The specified address shouldn’t include the R/W bit.

By default, 10-bit addressing is disabled, which means set_slave_address only accepts 7-bit addresses. 10-bit addressing can be enabled with set_addr_10bit. Note that setting a 7-bit address when 10-bit addressing is enabled won’t correctly target a slave device that doesn’t support 10-bit addresses.

pub fn set_timeout(&self, timeout: u32) -> Result<()>

Sets the maximum duration of a transaction in milliseconds (ms).

Transactions that take longer than timeout return an io::ErrorKind::TimedOut error.

timeout has a resolution of 10ms.

pub fn set_addr_10bit(&mut self, addr_10bit: bool) -> Result<()>

Enables or disables 10-bit addressing.

10-bit addressing currently isn’t supported on the Raspberry Pi. set_addr_10bit returns Err(Error::FeatureNotSupported) unless underlying driver support is detected.

By default, addr_10bit is set to false.

pub fn read(&mut self, buffer: &mut [u8]) -> Result<usize>

Receives incoming data from the slave device and writes it to buffer.

read reads as many bytes as can fit in buffer.

Sequence: START → Address + Read Bit → Incoming Bytes → STOP

Returns how many bytes were read.

pub fn write(&mut self, buffer: &[u8]) -> Result<usize>

Sends the outgoing data contained in buffer to the slave device.

Sequence: START → Address + Write Bit → Outgoing Bytes → STOP

Returns how many bytes were written.

pub fn write_read(
    &self,
    write_buffer: &[u8],
    read_buffer: &mut [u8]
) -> Result<()>

Sends the outgoing data contained in write_buffer to the slave device, and then fills read_buffer with incoming data.

Compared to calling write and read separately, write_read doesn’t issue a STOP condition in between the write and read operation. A repeated START is sent instead.

write_read reads as many bytes as can fit in read_buffer. The maximum number of bytes in either write_buffer or read_buffer can’t exceed 8192.

Sequence: START → Address + Write Bit → Outgoing Bytes → Repeated START → Address + Read Bit → Incoming Bytes → STOP

pub fn block_read(&self, command: u8, buffer: &mut [u8]) -> Result<()>

Sends an 8-bit command, and then fills a multi-byte buffer with incoming data.

block_read can read a maximum of 32 bytes.

Although block_read isn’t part of the SMBus protocol, it uses the SMBus functionality to offer this commonly used I2C transaction format. The difference between block_read and smbus_block_read is that the latter also expects a byte count from the slave device.

Sequence: START → Address + Write Bit → Command → Repeated START → Address + Read Bit → Incoming Bytes → STOP

pub fn block_write(&self, command: u8, buffer: &[u8]) -> Result<()>

Sends an 8-bit command followed by a multi-byte buffer.

block_write can write a maximum of 32 bytes. Any additional data contained in buffer is ignored.

Although block_write isn’t part of the SMBus protocol, it uses the SMBus functionality to offer this commonly used I2C transaction format. The difference between block_write and smbus_block_write is that the latter also sends a byte count to the slave device.

Sequence: START → Address + Write Bit → Command → Outgoing Bytes → STOP

pub fn smbus_quick_command(&self, command: bool) -> Result<()>

Sends a 1-bit command in place of the R/W bit.

Sequence: START → Address + Command Bit → STOP

pub fn smbus_receive_byte(&self) -> Result<u8>

Receives an 8-bit value.

Sequence: START → Address + Read Bit → Incoming Byte → STOP

pub fn smbus_send_byte(&self, value: u8) -> Result<()>

Sends an 8-bit value.

Sequence: START → Address + Write Bit → Outgoing Byte → STOP

pub fn smbus_read_byte(&self, command: u8) -> Result<u8>

Sends an 8-bit command, and receives an 8-bit value.

Sequence: START → Address + Write Bit → Command → Repeated START → Address + Read Bit → Incoming Byte → STOP

pub fn smbus_write_byte(&self, command: u8, value: u8) -> Result<()>

Sends an 8-bit command and an 8-bit value.

Sequence: START → Address + Write Bit → Command → Outgoing Byte → STOP

pub fn smbus_read_word(&self, command: u8) -> Result<u16>

Sends an 8-bit command, and receives a 16-bit value.

Based on the SMBus protocol definition, the first byte received is stored as the low byte of the 16-bit value, and the second byte as the high byte. Some devices may require you to swap these bytes. In those cases you can use the convenience method smbus_read_word_swapped instead.

Sequence: START → Address + Write Bit → Command → Repeated START → Address + Read Bit → Incoming Byte Low → Incoming Byte High → STOP

pub fn smbus_read_word_swapped(&self, command: u8) -> Result<u16>

Sends an 8-bit command, and receives a 16-bit value in a non-standard swapped byte order.

smbus_read_word_swapped is a convenience method that works similarly to smbus_read_word, but reverses the byte order of the incoming 16-bit value. The high byte is received first, and the low byte second.

Sequence: START → Address + Write Bit → Command → Repeated START → Address + Read Bit → Incoming Byte High → Incoming Byte Low → STOP

pub fn smbus_write_word(&self, command: u8, value: u16) -> Result<()>

Sends an 8-bit command and a 16-bit value.

Based on the SMBus protocol definition, the first byte sent is the low byte of the 16-bit value, and the second byte is the high byte. Some devices may require you to swap these bytes. In those cases you can use the convenience method smbus_write_word_swapped instead.

Sequence: START → Address + Write Bit → Command → Outgoing Byte Low → Outgoing Byte High → STOP

pub fn smbus_write_word_swapped(&self, command: u8, value: u16) -> Result<()>

Sends an 8-bit command and a 16-bit value in a non-standard swapped byte order.

smbus_write_word_swapped is a convenience method that works similarly to smbus_write_word, but reverses the byte order of the outgoing 16-bit value. The high byte is sent first, and the low byte second.

Sequence: START → Address + Write Bit → Command → Outgoing Byte High → Outgoing Byte Low → STOP

pub fn smbus_process_call(&self, command: u8, value: u16) -> Result<u16>

Sends an 8-bit command and a 16-bit value, and then receives a 16-bit value in response.

Based on the SMBus protocol definition, for both the outgoing and incoming 16-bit value, the first byte transferred is the low byte of the 16-bit value, and the second byte is the high byte. Some devices may require you to swap these bytes. In those cases you can use the convenience method smbus_process_call_swapped instead.

Sequence: START → Address + Write Bit → Command → Outgoing Byte Low → Outgoing Byte High → Repeated START → Address + Read Bit → Incoming Byte Low → Incoming Byte High → STOP

pub fn smbus_process_call_swapped(&self, command: u8, value: u16) -> Result<u16>

Sends an 8-bit command and a 16-bit value, and then receives a 16-bit value in response, in a non-standard byte order.

smbus_process_call_swapped is a convenience method that works similarly to smbus_process_call, but reverses the byte order of the outgoing and incoming 16-bit value. The high byte is transferred first, and the low byte second.

Sequence: START → Address + Write Bit → Command → Outgoing Byte High → Outgoing Byte Low → Repeated START → Address + Read Bit → Incoming Byte High → Incoming Byte Low → STOP

pub fn smbus_block_read(&self, command: u8, buffer: &mut [u8]) -> Result<usize>

Sends an 8-bit command, and then receives an 8-bit byte count along with a multi-byte buffer.

smbus_block_read currently isn’t supported on the Raspberry Pi, and returns Err(Error::FeatureNotSupported) unless underlying driver support is detected. You might be able to emulate the smbus_block_read functionality with write_read, block_read or read provided the length of the expected incoming data is known beforehand, or the slave device allows the master to read more data than it needs to send.

smbus_block_read can read a maximum of 32 bytes.

Sequence: START → Address + Write Bit → Command → Repeated START → Address + Read Bit → Incoming Byte Count → Incoming Bytes → STOP

Returns how many bytes were read.

pub fn smbus_block_write(&self, command: u8, buffer: &[u8]) -> Result<()>

Sends an 8-bit command and an 8-bit byte count along with a multi-byte buffer.

smbus_block_write can write a maximum of 32 bytes. Any additional data contained in buffer is ignored.

Sequence: START → Address + Write Bit → Command → Outgoing Byte Count → Outgoing Bytes → STOP

pub fn set_smbus_pec(&self, pec: bool) -> Result<()>

Enables or disables SMBus Packet Error Checking.

Packet Error Checking inserts a CRC-8 Packet Error Code (PEC) byte before each STOP condition for all SMBus protocols, except Quick Command and Host Notify.

The PEC is calculated on all message bytes except the START, STOP, ACK and NACK bits.

By default, pec is set to false.

Trait Implementations

impl Debug for I2c

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Read<u8> for I2c

Read trait implementation for embedded-hal v1.0.0-alpha.5.

type Error = Error

Error type

fn read(&mut self, address: u8, buffer: &mut [u8]) -> Result<(), Self::Error>

Reads enough bytes from slave with address to fill buffer

impl Read<u8> for I2c

Read trait implementation for embedded-hal v0.2.6.

type Error = Error

Error type

fn read(&mut self, address: u8, buffer: &mut [u8]) -> Result<(), Self::Error>

Reads enough bytes from slave with address to fill buffer

impl Write<u8> for I2c

Write trait implementation for embedded-hal v1.0.0-alpha.5.

type Error = Error

Error type

fn write(&mut self, address: u8, bytes: &[u8]) -> Result<(), Self::Error>

Writes bytes to slave with address address

impl Write<u8> for I2c

Write trait implementation for embedded-hal v0.2.6.

type Error = Error

Error type

fn write(&mut self, address: u8, bytes: &[u8]) -> Result<(), Self::Error>

Writes bytes to slave with address address

impl WriteRead<u8> for I2c

WriteRead trait implementation for embedded-hal v1.0.0-alpha.5.

type Error = Error

Error type

fn write_read(
    &mut self,
    address: u8,
    bytes: &[u8],
    buffer: &mut [u8]
) -> Result<(), Self::Error>

Writes bytes to slave with address address and then reads enough bytes to fill buffer in a single transaction

impl WriteRead<u8> for I2c

WriteRead trait implementation for embedded-hal v0.2.6.

type Error = Error

Error type

fn write_read(
    &mut self,
    address: u8,
    bytes: &[u8],
    buffer: &mut [u8]
) -> Result<(), Self::Error>

Writes bytes to slave with address address and then reads enough bytes to fill buffer in a single transaction

impl Send for I2c