API Reference

I2cDevice

class circuitpython_sensirion_i2c_driver.device.I2cDevice(connection, slave_address)

Base class for all I²C devices. Users should inherit from this class when implementing new I²C device drivers.

The most important functionality of this class is the convenience method execute() which allows derived classes to easily execute an I2cCommand object.

__init__(connection, slave_address)

Create an I²C device instance on a given connection.

Parameters:

• connection (I2cConnection) – The I²C connection used to execute the commands.
• slave_address (byte) – The I²C slave address of the device.

connection

Get the used I²C connection.

Returns:The used I²C connection. Return type:I2cConnection

slave_address

Get the I²C slave address.

Returns:The I²C slave address. Return type:byte

execute(command)

Execute an I²C command on this device.

Parameters:command (I2cCommand) – The command to be executed. Returns:The interpreted response of the executed command. Return type:Depends on the executed command.

I2cConnection

class circuitpython_sensirion_i2c_driver.connection.I2cConnection(transceiver)

I²C connection class to allow executing I²C commands with a higher-level, transceiver-independent API.

The connection supports two different modes of operation: Single channel and multi channel. See Single/Multi-Channel Mode for details.

__init__(transceiver)

Creates an I²C connection object.

Parameters:transceiver – An I²C transceiver object of any API version (type depends on the used hardware).

always_multi_channel_response

Set this to True to enforce the behaviour of a multi-channel connection, even if a single-channel transceiver is used. In particular, it makes the method execute() always returning a list, without throwing an exception in case of communication errors. This might be useful for applications where both, single-channel and multi-channel communication is needed.

Type:Bool

is_multi_channel

Check whether execute() will return a single-channel or multi-channel response.

A multi-channel response is returned if either always_multi_channel_response is set to True, or the underlying transceiver is multi-channel.

Returns:True if multi-channel, False if single-channel. Return type:Bool

execute(slave_address, command, wait_post_process=True)

Perform write and read operations of an I²C command and wait for the post processing time, if needed.

Note

The response data type of this method depends on whether this is a single-channel or multi-channel connection. This can be determined by reading the property is_multi_channel.

Parameters:

• slave_address (byte) – The slave address of the device to communicate with.
• command (I2cCommand) – The command to execute.
• wait_post_process (bool) – If True and the passed command needs some time for post processing, this method waits until post processing is done.

Returns:

• In single channel mode: The interpreted data of the command.
• In multi-channel mode: A list containing either interpreted data of the command (on success) or an Exception object (on error) for every channel.

Raise:

In single-channel mode, an exception is raised in case of communication errors.

I2cTransceiver V1

class circuitpython_sensirion_i2c_driver.transceiver_v1.I2cTransceiverV1

Interface to be implemented by every I²C transceiver with API version 1.

API_VERSION = 1

API version (accessed by I2cConnection)

STATUS_OK = 0

Status code for “transceive operation succeeded”.

STATUS_CHANNEL_DISABLED = 1

Status code for “channel disabled error”.

STATUS_NACK = 2

Status code for “not acknowledged error”.

STATUS_TIMEOUT = 3

Status code for “timeout error”.

STATUS_UNSPECIFIED_ERROR = 4

Status code for “unspecified error”.

__init__()

Initialize self. See help(type(self)) for accurate signature.

description

Description of the transceiver (for logging/debugging purposes). Should be a short one-line string.

Returns:Description. Return type:str

channel_count

Channel count of this transceiver. This is needed by I2cConnection to determine whether this is a single-channel or multi-channel transceiver, and how many channels it has (in case of multi-channel).

Returns:The channel count if it’s a multi-channel transceiver, or None if it’s a single-channel transceiver. Return type:int/None

transceive(slave_address, tx_data, rx_length, read_delay, timeout)

Transceive an I²C frame synchronously.

Parameters:

• slave_address (byte) – The I²C address of the slave to communicate with.
• tx_data (bytes/None) – The data to send. If empty, only the write header (without data) is sent. If None, no write header is sent at all.
• rx_length (int/None) – Number of bytes to read. If zero, only the read header is sent, without reading any data. If None, no read header is sent at all.
• read_delay (float) – Delay before sending the read header in Seconds.
• timeout (float) – Timeout (for clock stretching) in Seconds. If the clock gets stretched longer than this time, the transceive operation is aborted with timeout error.

Returns:

• A status code of the transceive operation
• In case of errors, the underlying (transceiver-dependent) exception
• The received data from the read operation

Return type:

• If single-channel: tuple(int, Exception, bytes)
• If multi-channel: list(tuple(int, Exception, bytes))

Raises:

Only raises a (transceiver-specific) exception if the operation could not be executed at all. If the operation was executed but failed with NACK or timeout, no exception is raised. These errors are reported by the returned status code instead.

LinuxI2cTransceiver

class circuitpython_sensirion_i2c_driver.linux_i2c_transceiver.LinuxI2cTransceiver(device_file, do_open=True)

Transceiver for the Linux I²C kernel driver, for example to use the I²C pins of a Raspberry Pi.

Note

This class can be used in a “with”-statement, and it’s recommended to do so as it automatically closes the device file after using it.

API_VERSION = 1

API version (accessed by I2cConnection)

STATUS_OK = 0

Status code for “transceive operation succeeded”.

STATUS_CHANNEL_DISABLED = 1

Status code for “channel disabled error”.

STATUS_NACK = 2

Status code for “not acknowledged error”.

STATUS_TIMEOUT = 3

Status code for “timeout error”.

STATUS_UNSPECIFIED_ERROR = 4

Status code for “unspecified error”.

__init__(device_file, do_open=True)

Create a transceiver for a given I²C device file and (optionally) open it for read/write access.

Parameters:

• device_file (str) – Path to the I²C device file, for example “/dev/i2c-1”.
• do_open (bool) – Whether the file should be opened immediately or not. If False, you will have to call open() manually before using the transceiver. Defaults to True.

open()

Open the I²C port (only needs to be called if do_open in __init__() was set to False.

close()

Close (release) the device file.

description

Description of the transceiver.

For details (e.g. return value documentation), please refer to description.

channel_count

Channel count of this transceiver.

For details (e.g. return value documentation), please refer to channel_count.

transceive(slave_address, tx_data, rx_length, read_delay, timeout)

Transceive an I²C frame in single-channel mode.

For details (e.g. parameter documentation), please refer to transceive().

Note

The timeout parameter is not supported (i.e. ignored) since we can’t specify the clock stretching timeout. It depends on the underlying hardware whether clock stretching is supported at all or not, and what timeout value is used.

I2cCommand

class circuitpython_sensirion_i2c_driver.command.I2cCommand(tx_data, rx_length, read_delay, timeout, post_processing_time=0.0)

Base class for all I²C commands.

__init__(tx_data, rx_length, read_delay, timeout, post_processing_time=0.0)

Constructs a new I²C command.

Parameters:

• tx_data (bytes-like/list/None) – Bytes to be sent to the I²C device. None means that no write header will be sent at all. An empty list/bytes object means to send the write header, but without data following it.
• rx_length (int/None) – Number of bytes to be read from the I²C device. None means that no read header is sent at all. Zero means to send the read header, but without reading any data.
• read_delay (float) – Delay (in Seconds) to be inserted between the end of the write operation and the beginning of the read operation. This is needed if the device needs some time to prepare the RX data, e.g. if it has to perform a measurement. Set to 0.0 to indicate that no delay is needed, i.e. the device does not need any processing time.
• timeout (float) – Timeout (in Seconds) to be used in case of clock stretching. If the device stretches the clock longer than this value, the transceive operation will be aborted with a timeout error. Set to 0.0 to indicate that the device will not stretch the clock for this command.
• post_processing_time (float) – Maximum time in seconds the device needs for post processing of this command until it is ready to receive the next command. For example after a device reset command, the device might need some time until it is ready again. Usually this is 0.0s, i.e. no post processing is needed.

rx_length

Number of bytes to be read from the device (int/None).

read_delay

Delay in Seconds between write and read operation (float).

timeout

Timeout in Seconds for clock stretching (float).

post_processing_time

Time in Seconds how long the post processing takes (float).

interpret_response(data)

Interprets the raw response from the device and returns it in the proper data type.

Note

This implementation returns the data as-is, or as None if there is no data received. Derived classes may override this method to convert the data to the proper data types.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The received raw bytes, or None if there is no data received. Return type:bytes or None

SensirionI2cCommand

class circuitpython_sensirion_i2c_driver.sensirion_command.SensirionI2cCommand(command, tx_data, rx_length, read_delay, timeout, crc, command_bytes=2, post_processing_time=0.0)

Base class for Sensirion-specific I²C commands as used in most Sensirion sensor devices. This class extends the base class I2cCommand with following functionality:

• Splitting TX data into command ID and payload data
• Transparently inserts CRCs into TX data after every 2nd payload byte
• Transparently verifies and removes CRCs from RX data after every 2nd byte

__init__(command, tx_data, rx_length, read_delay, timeout, crc, command_bytes=2, post_processing_time=0.0)

Constructs a new Sensirion I²C command.

Parameters:

• command (int/None) – The command ID to be sent to the device. None means that no command will be sent, i.e. only tx_data (if not None) will be sent. No CRC is added to these bytes since the command ID usually already contains a CRC.
• tx_data (bytes-like/list/None) – Bytes to be extended with CRCs and then sent to the I²C device. None means that no write header will be sent at all (if command is None too). An empty list means to send the write header (even if command is None), but without data following it.
• rx_length (int/None) – Number of bytes to be read from the I²C device, including CRC bytes. None means that no read header is sent at all. Zero means to send the read header, but without reading any data.
• read_delay (float) – Delay (in Seconds) to be inserted between the end of the write operation and the beginning of the read operation. This is needed if the device needs some time to prepare the RX data, e.g. if it has to perform a measurement. Set to 0.0 to indicate that no delay is needed, i.e. the device does not need any processing time.
• timeout (float) – Timeout (in Seconds) to be used in case of clock stretching. If the device stretches the clock longer than this value, the transceive operation will be aborted with a timeout error. Set to 0.0 to indicate that the device will not stretch the clock for this command.
• crc (calleable) – A CrcCalculator object to calculate the CRC of the transceived data, or any other calleable object or function which takes a bytearray as parameter and returns its CRC as an integer. If the command does not contain CRC bytes, pass None to disable it.
• command_bytes (int) – Number of command bytes. Most Sensirion sensors use a 2-byte command (thus it is the default), but there are also sensors using only one byte for the command.
• post_processing_time (float) – Maximum time in seconds the device needs for post processing of this command until it is ready to receive the next command. For example after a device reset command, the device might need some time until it is ready again. Usually this is 0.0s, i.e. no post processing is needed.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the data with all CRCs removed.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The received bytes, or None if there is no data received. Return type:bytes or None Raises:I2cChecksumError – If a received CRC was wrong.

CrcCalculator

class circuitpython_sensirion_i2c_driver.crc_calculator.CrcCalculator(width, polynomial, init_value=0, final_xor=0)

Helper class to calculate arbitrary CRCs. An instance of this class can be called like a function to calculate the CRC of the passed data.

Note

This class is not used within this package, its purpose is to help users writing drivers for I²C devices which protect the transferred data with CRCs.

__init__(width, polynomial, init_value=0, final_xor=0)

Constructs a calculator object with the given CRC parameters.

Parameters:

• width (int) – Number of bits of the CRC (e.g. 8 for CRC-8).
• polynomial (int) – The polynomial of the CRC, without leading ‘1’ (e.g. 0x31 for the polynomial x^8 + x^5 + x^4 + 1).
• init_value (int) – Initialization value of the CRC. Defaults to 0.
• final_xor (int) – Final XOR value of the CRC. Defaults to 0.

__call__(data)

Calculate the CRC of the given data.

Parameters:data (iterable) – The input data (iterable with values of given bit width, e.g. list of 8-bit integers). Returns:The calculated CRC. Return type:int

Exceptions

digraph inheritanceb4c67c9966 { rankdir=LR; size="8.0, 12.0"; "circuitpython_sensirion_i2c_driver.errors.I2cChannelDisabledError" [URL="#circuitpython_sensirion_i2c_driver.errors.I2cChannelDisabledError",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="I2C channel disabled error."]; "circuitpython_sensirion_i2c_driver.errors.I2cTransceiveError" -> "circuitpython_sensirion_i2c_driver.errors.I2cChannelDisabledError" [arrowsize=0.5,style="setlinewidth(0.5)"]; "circuitpython_sensirion_i2c_driver.errors.I2cChecksumError" [URL="#circuitpython_sensirion_i2c_driver.errors.I2cChecksumError",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="I2C checksum error."]; "circuitpython_sensirion_i2c_driver.errors.I2cError" -> "circuitpython_sensirion_i2c_driver.errors.I2cChecksumError" [arrowsize=0.5,style="setlinewidth(0.5)"]; "circuitpython_sensirion_i2c_driver.errors.I2cError" [URL="#circuitpython_sensirion_i2c_driver.errors.I2cError",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="I2C error base exception."]; "circuitpython_sensirion_i2c_driver.errors.IOError" -> "circuitpython_sensirion_i2c_driver.errors.I2cError" [arrowsize=0.5,style="setlinewidth(0.5)"]; "circuitpython_sensirion_i2c_driver.errors.I2cNackError" [URL="#circuitpython_sensirion_i2c_driver.errors.I2cNackError",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="I2C transceive NACK error."]; "circuitpython_sensirion_i2c_driver.errors.I2cTransceiveError" -> "circuitpython_sensirion_i2c_driver.errors.I2cNackError" [arrowsize=0.5,style="setlinewidth(0.5)"]; "circuitpython_sensirion_i2c_driver.errors.I2cTimeoutError" [URL="#circuitpython_sensirion_i2c_driver.errors.I2cTimeoutError",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="I2C transceive timeout error."]; "circuitpython_sensirion_i2c_driver.errors.I2cTransceiveError" -> "circuitpython_sensirion_i2c_driver.errors.I2cTimeoutError" [arrowsize=0.5,style="setlinewidth(0.5)"]; "circuitpython_sensirion_i2c_driver.errors.I2cTransceiveError" [URL="#circuitpython_sensirion_i2c_driver.errors.I2cTransceiveError",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="I2C transceive error."]; "circuitpython_sensirion_i2c_driver.errors.I2cError" -> "circuitpython_sensirion_i2c_driver.errors.I2cTransceiveError" [arrowsize=0.5,style="setlinewidth(0.5)"]; "circuitpython_sensirion_i2c_driver.errors.IOError" [URL="#circuitpython_sensirion_i2c_driver.errors.IOError",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top"]; }

exception circuitpython_sensirion_i2c_driver.errors.IOError

__init__

Initialize self. See help(type(self)) for accurate signature.

errno

POSIX exception code

filename

exception filename

filename2

second exception filename

strerror

exception strerror

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception circuitpython_sensirion_i2c_driver.errors.I2cError(received_data=None, message='I2C error.')

I2C error base exception.

__init__(received_data=None, message='I2C error.')

Initialize self. See help(type(self)) for accurate signature.

errno

POSIX exception code

filename

exception filename

filename2

second exception filename

strerror

exception strerror

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception circuitpython_sensirion_i2c_driver.errors.I2cChecksumError(received_checksum, expected_checksum, received_data)

I2C checksum error.

__init__(received_checksum, expected_checksum, received_data)

Initialize self. See help(type(self)) for accurate signature.

errno

POSIX exception code

filename

exception filename

filename2

second exception filename

strerror

exception strerror

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception circuitpython_sensirion_i2c_driver.errors.I2cTransceiveError(transceiver_error, received_data, message='Unknown error.')

I2C transceive error.

__init__(transceiver_error, received_data, message='Unknown error.')

Initialize self. See help(type(self)) for accurate signature.

errno

POSIX exception code

filename

exception filename

filename2

second exception filename

strerror

exception strerror

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception circuitpython_sensirion_i2c_driver.errors.I2cChannelDisabledError(transceiver_error, received_data)

I2C channel disabled error.

__init__(transceiver_error, received_data)

Initialize self. See help(type(self)) for accurate signature.

errno

POSIX exception code

filename

exception filename

filename2

second exception filename

strerror

exception strerror

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception circuitpython_sensirion_i2c_driver.errors.I2cNackError(transceiver_error, received_data)

I2C transceive NACK error.

__init__(transceiver_error, received_data)

Initialize self. See help(type(self)) for accurate signature.

errno

POSIX exception code

filename

exception filename

filename2

second exception filename

strerror

exception strerror

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception circuitpython_sensirion_i2c_driver.errors.I2cTimeoutError(transceiver_error, received_data)

I2C transceive timeout error.

__init__(transceiver_error, received_data)

Initialize self. See help(type(self)) for accurate signature.

errno

POSIX exception code

filename

exception filename

filename2

second exception filename

strerror

exception strerror

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.