smbus3 Documentation

smbus3 - A drop-in replacement for smbus2/smbus-cffi/smbus-python

class smbus3.SMBus(bus=None, force=False)

The main SMBus class.

__init__(bus=None, force=False)

Initialize and (optionally) open an i2c bus connection.

Parameters:

  • bus (int or str) – i2c bus number (e.g. 0 or 1) or an absolute file path (e.g. /dev/i2c-42). If not given, a subsequent call to open() is required.

  • force (boolean) – force using the slave address even when driver is already using it.

open(bus)

Open a given i2c bus.

Parameters:

bus (int or str) – i2c bus number (e.g. 0 or 1) or an absolute file path (e.g. ‘/dev/i2c-42’).

Raises:

TypeError – if type(bus) is not in (int, str)

Return type:

None

close()

Close the i2c connection.

Raises:

OSError – if the file descriptor in self.fd does not exist

Return type:

None

enable_pec(enable=True)

Enable/Disable PEC (Packet Error Checking) - SMBus 1.1 and later

Parameters:

enable (bool) – Whether to enable PEC or not.

Raises:

IOError – if SMBUS_PEC is not supported.

Return type:

None

property pec

Get and set SMBus PEC. 0 = disabled (default), 1 = enabled.

enable_tenbit(enable=True)

Enable 10 bit addresses if they are supported.

Parameters:

enable (bool) – Whether to enable 10bit addresses or not.

Raises:

IOError – if ADDR_10BIT is not supported.

Return type:

None

property tenbit

Get and set 10bit addressing. 0 = disabled (default), 1 = enabled.

set_timeout(timeout)

Set the timeout in units of 10ms.

Parameters:

timeout (int) – timeout as positive int in units of 10ms.

Return type:

None

property timeout

Get and set I2C timeout in units of 10ms.

set_retries(retries)

Set the retries.

Parameters:

retries (int) – retries as positive int.

Return type:

None

property retries

Get and set I2C retries.

_set_address(address, force=None)

Set i2c slave address to use for subsequent calls. Private.

Parameters:

  • address (int)

  • force (bool) – force using the slave address even when driver is already using it.

Return type:

None

_get_funcs()

Returns a 32-bit value stating supported I2C functions. Private.

Return type:

int

write_quick(i2c_addr, force=None)

Perform quick transaction. Throws IOError if unsuccessful.

Parameters:

  • i2c_addr (int) – i2c address

  • force (bool) – force using the slave address even when driver is already using it.

Raises:

IOError – if write is unsuccessful.

Return type:

None

read_byte(i2c_addr, force=None)

Read a single byte from a device.

Return type:

int

Parameters:

  • i2c_addr (int) – i2c address

  • force (bool) – force using the slave address even when driver is already using it.

Returns:

Read byte value

Return type:

int

write_byte(i2c_addr, value, force=None)

Write a single byte to a device.

Parameters:

  • i2c_addr (int) – i2c address

  • value (int) – value to write

  • force (bool) – force using the slave address even when driver is already using it.

Return type:

None

read_byte_data(i2c_addr, register, force=None)

Read a single byte from a designated register.

Parameters:

  • i2c_addr (int) – i2c address

  • register (int) – Register to read

  • force (bool) – force using the slave address even when driver is already using it.

Returns:

Read byte value

Return type:

int

write_byte_data(i2c_addr, register, value, force=None)

Write a byte to a given register.

Parameters:

  • i2c_addr (int) – i2c address

  • register (int) – Register to write to

  • value (int) – Byte value to transmit

  • force (bool) – force using the slave address even when driver is already using it.

Return type:

None

read_word_data(i2c_addr, register, force=None)

Read a single word (2 bytes) from a given register.

Parameters:

  • i2c_addr (int) – i2c address

  • register (int) – Register to read

  • force (bool) – force using the slave address even when driver is already using it.

Returns:

2-byte word

Return type:

int

write_word_data(i2c_addr, register, value, force=None)

Write a single word (2 bytes) to a given register.

Parameters:

  • i2c_addr (int) – i2c address

  • register (int) – Register to write to

  • value (int) – Word value to transmit

  • force (bool) – force using the slave address even when driver is already using it.

Return type:

None

process_call(i2c_addr, register, value, force=None)

Executes a SMBus Process Call, sending a 16-bit value and receiving a 16-bit response

Parameters:

  • i2c_addr (int) – i2c address

  • register (int) – Register to read/write to

  • value (int) – Word value to transmit

  • force (bool) – force using the slave address even when driver is already using it.

Return type:

int

read_block_data(i2c_addr, register, force=None)

Read a block of up to 32-bytes from a given register.

Parameters:

  • i2c_addr (int) – i2c address

  • register (int) – Start register

  • force (bool) – force using the slave address even when driver is already using it.

Returns:

List of bytes

Return type:

list

write_block_data(i2c_addr, register, data, force=None)

Write a block of byte data to a given register.

Parameters:

  • i2c_addr (int) – i2c address

  • register (int) – Start register

  • data (list) – List of bytes

  • force (bool) – force using the slave address even when driver is already using it.

Raises:

ValueError – if length of data in bytes is > I2C_SMBUS_BLOCK_MAX

Return type:

None

block_process_call(i2c_addr, register, data, force=None)

Executes a SMBus Block Process Call, sending a variable-size data block and receiving another variable-size response

Parameters:

  • i2c_addr (int) – i2c address

  • register (int) – Register to read/write to

  • data (list) – List of bytes

  • force (bool) – force using the slave address even when driver is already using it.

Raises:

ValueError – if length of data in bytes is > I2C_SMBUS_BLOCK_MAX

Returns:

List of bytes

Return type:

list

read_i2c_block_data(i2c_addr, register, length, force=None)

Read a block of byte data from a given register.

Parameters:

  • i2c_addr (int) – i2c address

  • register (int) – Start register

  • length (int) – Desired block length

  • force (bool) – force using the slave address even when driver is already using it.

Raises:

ValueError – if length (in bytes) is > I2C_SMBUS_BLOCK_MAX

Returns:

List of bytes

Return type:

list

write_i2c_block_data(i2c_addr, register, data, force=None)

Write a block of byte data to a given register.

Parameters:

  • i2c_addr (int) – i2c address

  • register (int) – Start register

  • data (list) – List of bytes

  • force (bool) – force using the slave address even when driver is already using it.

Raises:

ValueError – if length of data in bytes is > I2C_SMBUS_BLOCK_MAX

Return type:

None

i2c_rdwr(*i2c_msgs)

Combine a series of i2c read and write operations in a single transaction (with repeated start bits but no stop bits in between).

This method takes i2c_msg instances as input, which must be created first with i2c_msg.read() or i2c_msg.write().

Parameters:

i2c_msgs (i2c_msg) – One or more i2c_msg class instances.

Return type:

None

i2c_rd(i2c_addr, length, flags=1)

Perform a single i2c read operation, given an i2c_addr and length.

Parameters:

  • i2c_addr (int) – i2c address for the read operation.

  • length (int) – length of read.

  • flags (int) – bitflags to pass (default: I2C_M_RD)

Return type:

i2c_msg

i2c_wr(i2c_addr, buf, flags=0)

Perform a single i2c write operation, given an i2c_addr and a buffer to copy.

Parameters:

  • i2c_addr (int) – i2c address for the write operation.

  • buf (list) – buffer to write.

  • flags (int) – bitflags to pass (default: I2C_M_WR)

Return type:

i2c_msg

class smbus3.i2c_msg

As defined in i2c.h.

Variables:

  • addr (c_uint16) – i2c address

  • flags (c_uint16) – bit flags

  • len (c_uint16) – length

  • buf (POINTER(c_char)) – data buffer

__iter__()

Iterator / Generator

Returns:

iterates over buf

Return type:

generator which returns int values

__repr__()

Return repr(self).

__str__()

Return a string, discarding non decodable bytes.

Returns:

string of i2c_msg.__bytes__()

Return type:

str

static read(address, length, flags=1)

Prepares an i2c read transaction.

Parameters:

  • address – Slave address.

  • length – Number of bytes to read.

  • flags (int) – bitflags to pass (default: I2C_M_RD)

Type:

address: int

Type:

length: int

Returns:

New i2c_msg instance for read operation.

Return type:

i2c_msg

static write(address, buf, flags=0)

Prepares an i2c write transaction.

Parameters:

  • address (int) – Slave address.

  • buf (list) – Bytes to write. Either list of values or str.

  • flags (int) – bitflags to pass (default: I2C_M_WR)

Returns:

New i2c_msg instance for write operation.

Return type:

i2c_msg

class smbus3.I2cFunc(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

These flags identify the operations supported by an I2C/SMBus device.

You can test these flags on your smbus.funcs

I2C = 1
ADDR_10BIT = 2
PROTOCOL_MANGLING = 4
SMBUS_PEC = 8
NOSTART = 16
SLAVE = 32
SMBUS_BLOCK_PROC_CALL = 32768
SMBUS_QUICK = 65536
SMBUS_READ_BYTE = 131072
SMBUS_WRITE_BYTE = 262144
SMBUS_READ_BYTE_DATA = 524288
SMBUS_WRITE_BYTE_DATA = 1048576
SMBUS_READ_WORD_DATA = 2097152
SMBUS_WRITE_WORD_DATA = 4194304
SMBUS_PROC_CALL = 8388608
SMBUS_READ_BLOCK_DATA = 16777216
SMBUS_WRITE_BLOCK_DATA = 33554432
SMBUS_READ_I2C_BLOCK = 67108864
SMBUS_WRITE_I2C_BLOCK = 134217728
SMBUS_HOST_NOTIFY = 268435456
SMBUS_BYTE = 393216
SMBUS_BYTE_DATA = 1572864
SMBUS_WORD_DATA = 6291456
SMBUS_BLOCK_DATA = 50331648
SMBUS_I2C_BLOCK = 201326592
SMBUS_EMUL = 251592712
class smbus3.I2C_M_Bitflag(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

These flags identify the operations to perform with a specific i2c_msg.

I2C_M_RD = 1
I2C_M_WR = 0
I2C_M_TEN = 16
I2C_M_RD_TEN = 17
I2C_M_WR_TEN = 16