smbus2

https://github.com/kplindegaard/smbus2/actions/workflows/python-build-test.yml/badge.svg?branch=master https://img.shields.io/pypi/pyversions/smbus2.svg https://img.shields.io/pypi/v/smbus2.svg

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

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

Main class for I2C and SMBus communication, providing all IO functions for device access.

__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 (bool) – Use 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)

close()

Close the i2c connection.

enable_pec(enable=True)

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

Parameters:

enable (bool)

property pec

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

write_quick(i2c_addr, force=None)

Perform quick transaction. Throws IOError if unsuccessful. :param i2c_addr: i2c address :type i2c_addr: int :param force: Use slave address even when driver is already using it. :type force: bool

read_byte(i2c_addr, force=None)

Read a single byte from a device.

Return type:

int

Parameters:

  • i2c_addr (int) – i2c address

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

Returns:

Read byte value

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) – Use slave address even when driver is already using it.

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) – Use 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) – Use 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) – Use 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) – Use 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) – Use 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) – Use 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) – Use slave address even when driver is already using it.

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) – Use slave address even when driver is already using it.

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) – Use slave address even when driver is already using it.

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) – Use slave address even when driver is already using it.

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

class smbus2.i2c_msg

Represents a single I2C message for read or write operations. This is the expected data container for SMBus.i2c_rdwr().

As defined in i2c.h.

__iter__()

Iterator / Generator

Returns:

iterates over buf

Return type:

generator which returns int values

__str__()

Return str(self).

static read(address, length)

Prepares an i2c read transaction.

Parameters:

  • address (int) – Slave address.

  • length (int) – Number of bytes to read.

Returns:

New i2c_msg instance for read operation.

Return type:

i2c_msg

static write(address, buf)

Prepares an i2c write transaction.

Parameters:

  • address (int) – Slave address.

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

Returns:

New i2c_msg instance for write operation.

Return type:

i2c_msg

class smbus2.I2cFunc(*values)

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

You can test these flags on your smbus.funcs

On newer python versions, I2cFunc is an IntFlag enum, but it falls back to class with a bunch of int constants on older releases.

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