{"id":9438,"library":"adafruit-pureio","title":"Adafruit PureIO","description":"Adafruit PureIO provides pure Python (i.e., no native extensions) access to Linux IO, specifically for I2C and SPI buses. It serves as a drop-in replacement for the `smbus` and `spidev` modules, making it suitable for embedded systems like Raspberry Pi without requiring compilation. The library is actively maintained by Adafruit, with releases typically focusing on infrastructure updates, bug fixes, and compatibility improvements.","status":"active","version":"1.1.11","language":"en","source_language":"en","source_url":"https://github.com/adafruit/Adafruit_Python_PureIO","tags":["hardware","i2c","spi","raspberry pi","embedded","adafruit"],"install":[{"cmd":"pip install adafruit-pureio","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Adafruit PureIO is a replacement for smbus, so it provides its own SMBus class within its namespace.","wrong":"import smbus","symbol":"SMBus","correct":"from Adafruit_PureIO.smbus import SMBus"},{"note":"Similar to smbus, PureIO provides its own SPI class that mimics the functionality of spidev.","wrong":"import spidev","symbol":"SPI","correct":"from Adafruit_PureIO.spi import SPI"}],"quickstart":{"code":"import os\nfrom Adafruit_PureIO.smbus import SMBus\n\n# Most Raspberry Pi boards use I2C bus 1\n# On some older devices or specific setups, it might be bus 0\nbus_id = int(os.environ.get('I2C_BUS_ID', '1'))\ndevice_address = int(os.environ.get('I2C_DEVICE_ADDRESS', '0x50'), 16) # Example: EEPROM\nregister_address = int(os.environ.get('I2C_REGISTER_ADDRESS', '0x00'), 16)\n\ntry:\n    with SMBus(bus_id) as bus:\n        # Read a single byte from a device at device_address, register register_address\n        data = bus.read_byte_data(device_address, register_address)\n        print(f\"Successfully read byte 0x{data:02X} from I2C bus {bus_id}, device 0x{device_address:02X}, register 0x{register_address:02X}.\")\n        \n        # Example: Write a byte of data\n        # bus.write_byte_data(device_address, register_address, 0x12)\n        # print(\"Wrote 0x12 to device.\")\n\nexcept FileNotFoundError:\n    print(f\"Error: I2C bus /dev/i2c-{bus_id} not found. Is I2C enabled? (e.g., via raspi-config)\")\nexcept PermissionError:\n    print(f\"Error: Permission denied for /dev/i2c-{bus_id}. Are you in the 'i2c' group or running with sudo?\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to initialize an I2C bus using `SMBus` and perform a basic byte read operation. It includes error handling for common issues like bus not found or permission denied. Remember to enable I2C via your system configuration (e.g., `raspi-config` on Raspberry Pi) and ensure the user running the script has appropriate permissions (e.g., belongs to the 'i2c' group)."},"warnings":[{"fix":"Ensure the user running the Python script is part of the `i2c` and/or `spi` groups (e.g., `sudo usermod -aG i2c,spi $USER`) or run the script with `sudo`. Remember to log out and back in for group changes to take effect.","message":"Accessing hardware I/O devices like I2C or SPI often requires elevated permissions. Without them, your script will fail with a `PermissionError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"On Raspberry Pi, ensure I2C/SPI is enabled via `sudo raspi-config` under 'Interface Options'. For other Linux systems, consult documentation on enabling device tree overlays or kernel modules for your specific hardware.","message":"The I2C or SPI bus device files (e.g., `/dev/i2c-1`, `/dev/spi0.0`) might not exist or be enabled on your system, leading to `FileNotFoundError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `adafruit-pureio` version 1.1.7 or newer to ensure full compatibility with Python 3.9+ environments. `pip install --upgrade adafruit-pureio`.","message":"Older versions (prior to 1.1.7) had compatibility issues with Python 3.9 due to deprecated functions in the Python standard library.","severity":"deprecated","affected_versions":"<1.1.7"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Verify the I2C bus is enabled in your system's configuration (e.g., `sudo raspi-config` on Raspberry Pi). Check which bus IDs are available (e.g., by listing `/dev/i2c-*` or `/dev/spi*`).","cause":"The I2C bus is not enabled or the specified bus ID is incorrect for your hardware.","error":"FileNotFoundError: [Errno 2] No such file or directory: '/dev/i2c-1'"},{"fix":"Add the user to the appropriate group (e.g., `i2c`, `spi`) using `sudo usermod -aG i2c $USER` and reboot or log out/in. Alternatively, run the script with `sudo` (though this is generally less secure).","cause":"The user running the script does not have read/write permissions for the I2C/SPI device file.","error":"PermissionError: [Errno 13] Permission denied: '/dev/i2c-1'"},{"fix":"Ensure you have `adafruit-pureio` installed (`pip install adafruit-pureio`) and use the correct import statement: `from Adafruit_PureIO.smbus import SMBus`. If you intended to use the C-extension `smbus` library, install that instead (`pip install smbus-cffi` or similar).","cause":"This error message indicates that you might be trying to import `SMBus` directly from `Adafruit_PureIO.smbus` when you actually only have the system `smbus` installed, or you're using an incorrect import path.","error":"ImportError: cannot import name 'SMBus' from 'Adafruit_PureIO.smbus'"}]}