smbus2

0.6.1 · active · verified Sun Apr 12

smbus2 is a pure Python implementation of the `python-smbus` package, designed as a drop-in replacement for `smbus-cffi` or `smbus-python`. It provides an interface for I2C and SMBus communication on Linux-based systems, offering enhanced features like SMBus Packet Error Checking (PEC), support for context managers for robust resource handling, and improved error management. Actively maintained, the library is currently at version 0.6.1, with a regular release cadence addressing bug fixes and minor improvements, making it a recommended choice for embedded I2C communication, particularly on platforms like Raspberry Pi.

Warnings

breaking The `SMBusWrapper` class was removed in version 0.4.0. Direct instantiation of `SMBus` should be used instead.
Fix: Replace `from smbus2 import SMBusWrapper` with `from smbus2 import SMBus`, and update any `SMBusWrapper()` calls to `SMBus()`.
gotcha Frequent consecutive block read/write operations, especially on Raspberry Pi Zero W, can lead to `[Errno 121] Remote I/O error`. This often indicates bus congestion or timing issues.
Fix: Introduce small delays between successive calls, or consider using the `SMBus.i2c_rdwr()` method for combined transactions, which uses repeated start bits instead of stop bits between transfers.
breaking Version 0.6.0 fixed a buffer overflow issue that could occur when using Python 3.14 on 64-bit systems.
Fix: Upgrade to smbus2 version 0.6.0 or newer to prevent potential buffer overflow issues.
deprecated Testing for Python 2.7, 3.4, and 3.5 was officially dropped in version 0.4.3. While the code might still function, these versions are no longer actively supported or tested.
Fix: Migrate to Python 3.6 or newer for continued support and access to the latest smbus2 features and fixes.
gotcha smbus2 is not a literal 'drop-in replacement' in terms of import statements for the original `smbus` (or `python-smbus`). Attempting `import smbus` when only `smbus2` is installed will result in a `ModuleNotFoundError`.
Fix: Always use `from smbus2 import SMBus` (or other smbus2 specific imports). The 'drop-in replacement' refers to API compatibility once the `SMBus` object is instantiated, not the module name itself.
gotcha The `force` parameter in many I2C/SMBus functions (e.g., `read_byte_data`) instructs the Linux kernel to reuse a slave address even if it's already in use by a driver. This can mask underlying hardware or driver configuration issues and should be used cautiously.
Fix: Only use `force=True` if you explicitly understand its implications and require it for specific scenarios. In most cases, if an address conflict occurs, it indicates a configuration problem that should be resolved at the system or driver level rather than bypassed with `force`.

Install

pip install smbus2 Install smbus2

Imports

SMBus
```
from smbus2 import SMBus
```
SMBusWrapper
```
from smbus2 import SMBus
```
The SMBusWrapper class was deprecated and removed in version 0.4.0. Users should now instantiate SMBus directly.
i2c_msg
```
from smbus2 import i2c_msg
```
Used for combined read/write transactions with SMBus.i2c_rdwr().

Quickstart

This quickstart demonstrates basic I2C read and write operations using the `SMBus` class with a context manager, ensuring proper resource cleanup. It also shows how to set I2C bus, device address, and register address, with placeholders for actual values and environment variables for safer execution.

import os
from smbus2 import SMBus

# Example: Read a byte from an I2C device (e.g., at address 0x27, register 0x00)
# Replace `1` with the correct I2C bus number for your system (e.g., 0 for older Raspberry Pis, 1 for newer)
# Replace `0x27` with your device's I2C address
# Replace `0x00` with the register to read from

I2C_BUS_NUMBER = int(os.environ.get('I2C_BUS_NUMBER', '1')) # Default to bus 1
DEVICE_ADDRESS = int(os.environ.get('I2C_DEVICE_ADDRESS', '0x27'), 16)
REGISTER_ADDRESS = int(os.environ.get('I2C_REGISTER_ADDRESS', '0x00'), 16)

try:
    # Using 'with' statement ensures the bus is properly closed
    with SMBus(I2C_BUS_NUMBER) as bus:
        byte_data = bus.read_byte_data(DEVICE_ADDRESS, REGISTER_ADDRESS)
        print(f"Read byte 0x{byte_data:02X} from device 0x{DEVICE_ADDRESS:02X}, register 0x{REGISTER_ADDRESS:02X} on bus {I2C_BUS_NUMBER}.")

        # Example: Write a byte to the same device/register
        write_value = 0xAA # Example value to write
        bus.write_byte_data(DEVICE_ADDRESS, REGISTER_ADDRESS, write_value)
        print(f"Written byte 0x{write_value:02X} to device 0x{DEVICE_ADDRESS:02X}, register 0x{REGISTER_ADDRESS:02X} on bus {I2C_BUS_NUMBER}.")

except FileNotFoundError:
    print(f"Error: I2C bus {I2C_BUS_NUMBER} not found. Ensure I2C is enabled and the bus number is correct.")
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →