{"id":5061,"library":"smbus2","title":"smbus2","description":"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.","status":"active","version":"0.6.1","language":"en","source_language":"en","source_url":"https://github.com/kplindegaard/smbus2","tags":["i2c","smbus","raspberry-pi","embedded-systems","hardware-interface","linux"],"install":[{"cmd":"pip install smbus2","lang":"bash","label":"Install smbus2"}],"dependencies":[],"imports":[{"symbol":"SMBus","correct":"from smbus2 import SMBus"},{"note":"The SMBusWrapper class was deprecated and removed in version 0.4.0. Users should now instantiate SMBus directly.","wrong":"from smbus2 import SMBusWrapper","symbol":"SMBusWrapper","correct":"from smbus2 import SMBus"},{"note":"Used for combined read/write transactions with SMBus.i2c_rdwr().","symbol":"i2c_msg","correct":"from smbus2 import i2c_msg"}],"quickstart":{"code":"import os\nfrom smbus2 import SMBus\n\n# Example: Read a byte from an I2C device (e.g., at address 0x27, register 0x00)\n# Replace `1` with the correct I2C bus number for your system (e.g., 0 for older Raspberry Pis, 1 for newer)\n# Replace `0x27` with your device's I2C address\n# Replace `0x00` with the register to read from\n\nI2C_BUS_NUMBER = int(os.environ.get('I2C_BUS_NUMBER', '1')) # Default to bus 1\nDEVICE_ADDRESS = int(os.environ.get('I2C_DEVICE_ADDRESS', '0x27'), 16)\nREGISTER_ADDRESS = int(os.environ.get('I2C_REGISTER_ADDRESS', '0x00'), 16)\n\ntry:\n    # Using 'with' statement ensures the bus is properly closed\n    with SMBus(I2C_BUS_NUMBER) as bus:\n        byte_data = bus.read_byte_data(DEVICE_ADDRESS, REGISTER_ADDRESS)\n        print(f\"Read byte 0x{byte_data:02X} from device 0x{DEVICE_ADDRESS:02X}, register 0x{REGISTER_ADDRESS:02X} on bus {I2C_BUS_NUMBER}.\")\n\n        # Example: Write a byte to the same device/register\n        write_value = 0xAA # Example value to write\n        bus.write_byte_data(DEVICE_ADDRESS, REGISTER_ADDRESS, write_value)\n        print(f\"Written byte 0x{write_value:02X} to device 0x{DEVICE_ADDRESS:02X}, register 0x{REGISTER_ADDRESS:02X} on bus {I2C_BUS_NUMBER}.\")\n\nexcept FileNotFoundError:\n    print(f\"Error: I2C bus {I2C_BUS_NUMBER} not found. Ensure I2C is enabled and the bus number is correct.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Replace `from smbus2 import SMBusWrapper` with `from smbus2 import SMBus`, and update any `SMBusWrapper()` calls to `SMBus()`.","message":"The `SMBusWrapper` class was removed in version 0.4.0. Direct instantiation of `SMBus` should be used instead.","severity":"breaking","affected_versions":">=0.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (hardware-dependent)"},{"fix":"Upgrade to smbus2 version 0.6.0 or newer to prevent potential buffer overflow issues.","message":"Version 0.6.0 fixed a buffer overflow issue that could occur when using Python 3.14 on 64-bit systems.","severity":"breaking","affected_versions":"<0.6.0 with Python 3.14 (64-bit)"},{"fix":"Migrate to Python 3.6 or newer for continued support and access to the latest smbus2 features and fixes.","message":"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.","severity":"deprecated","affected_versions":">=0.4.3"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}