Adafruit PureIO

1.1.11 verified Fri Apr 17 auth: no python

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.

pip install adafruit-pureio

Common errors

error FileNotFoundError: [Errno 2] No such file or directory: '/dev/i2c-1' ↓

cause The I2C bus is not enabled or the specified bus ID is incorrect for your hardware.

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*).

error PermissionError: [Errno 13] Permission denied: '/dev/i2c-1' ↓

cause The user running the script does not have read/write permissions for the I2C/SPI device file.

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).

error ImportError: cannot import name 'SMBus' from 'Adafruit_PureIO.smbus' ↓

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.

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).

Warnings

gotcha Accessing hardware I/O devices like I2C or SPI often requires elevated permissions. Without them, your script will fail with a `PermissionError`. ↓

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.

gotcha 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`. ↓

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.

deprecated Older versions (prior to 1.1.7) had compatibility issues with Python 3.9 due to deprecated functions in the Python standard library. ↓

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`.

Imports

SMBus
wrong
```
import smbus
```
correct
```
from Adafruit_PureIO.smbus import SMBus
```
Adafruit PureIO is a replacement for smbus, so it provides its own SMBus class within its namespace.
SPI
wrong
```
import spidev
```
correct
```
from Adafruit_PureIO.spi import SPI
```
Similar to smbus, PureIO provides its own SPI class that mimics the functionality of spidev.

Quickstart

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).

import os
from Adafruit_PureIO.smbus import SMBus

# Most Raspberry Pi boards use I2C bus 1
# On some older devices or specific setups, it might be bus 0
bus_id = int(os.environ.get('I2C_BUS_ID', '1'))
device_address = int(os.environ.get('I2C_DEVICE_ADDRESS', '0x50'), 16) # Example: EEPROM
register_address = int(os.environ.get('I2C_REGISTER_ADDRESS', '0x00'), 16)

try:
    with SMBus(bus_id) as bus:
        # Read a single byte from a device at device_address, register register_address
        data = bus.read_byte_data(device_address, register_address)
        print(f"Successfully read byte 0x{data:02X} from I2C bus {bus_id}, device 0x{device_address:02X}, register 0x{register_address:02X}.")
        
        # Example: Write a byte of data
        # bus.write_byte_data(device_address, register_address, 0x12)
        # print("Wrote 0x12 to device.")

except FileNotFoundError:
    print(f"Error: I2C bus /dev/i2c-{bus_id} not found. Is I2C enabled? (e.g., via raspi-config)")
except PermissionError:
    print(f"Error: Permission denied for /dev/i2c-{bus_id}. Are you in the 'i2c' group or running with sudo?")
except Exception as e:
    print(f"An unexpected error occurred: {e}")