Adafruit Blinka

Common errors

• ModuleNotFoundError: No module named 'libgpiod_pin'

  cause The underlying C library `libgpiod` or its Python bindings `python3-libgpiod` are not installed or correctly linked.
  fix Install `libgpiod-dev` and `python3-libgpiod`: `sudo apt-get install -y libgpiod-dev python3-libgpiod`.

• RuntimeError: Failed to initialize PINS: No pins found for board 'YourBoardName'

  cause Blinka could not automatically identify your board, or the board definition is missing/incorrect, or the required JSON configuration files were not installed.
  fix Ensure you are on `adafruit-blinka>=9.0.2`. If the issue persists, explicitly set the board with an environment variable (e.g., `export BLINKA_BOARD=RASPBERRY_PI_ZERO`) and check your board's specific Blinka setup guide.

• PermissionError: [Errno 13] Permission denied: '/dev/gpiomem'

  cause Your user account does not have the necessary permissions to access GPIO hardware.
  fix Add your user to the `gpio` group: `sudo usermod -a -G gpio $(whoami)` and then reboot the system (`sudo reboot`).

• AttributeError: module 'board' has no attribute 'D18'

  cause The specific pin name (e.g., `D18`) is not recognized or available for the board Blinka believes it's running on, or Blinka failed to correctly initialize board support.
  fix Verify the pin name against your board's official pinout and Blinka's documentation for that board. Ensure your board is correctly identified (see `BLINKA_BOARD` environment variable in warnings). If using a custom board, check its JSON definition.

Warnings

• gotcha Blinka requires system-level dependencies for GPIO access, such as `libgpiod-dev` and `python3-libgpiod`, and build tools like `build-essential` and `python3-dev`. These are not installed by `pip` and must be manually installed using your system's package manager (e.g., `apt-get` on Debian/Ubuntu).
  Fix: Install required packages: `sudo apt-get update && sudo apt-get install -y python3-pip libgpiod-dev python3-libgpiod build-essential python3-dev` (for Debian/Ubuntu based systems).
• gotcha Accessing GPIO pins typically requires elevated permissions. Running as root (`sudo`) is one way, but a safer approach is to add your user to the `gpio` group and reboot. Without correct permissions, you'll encounter `PermissionError`.
  Fix: Add your user to the `gpio` group: `sudo usermod -a -G gpio $(whoami)` then reboot your system (`sudo reboot`).
• breaking Version 9.0.0 introduced a significant restructure by moving board and microcontroller definitions to JSON files instead of Python modules. While core API usage (`import board; board.D4`) largely remains the same, users developing custom board support or relying on introspection of `board` as a Python module might experience issues. Initial releases (9.0.0, 9.0.1) also had packaging issues where these JSON files were not included.
  Fix: For general users, ensure you are on `9.0.2` or newer to resolve packaging issues. For custom board developers, consult the Blinka GitHub repository for updated guidelines on board definitions.
• gotcha Pin names and availability are highly board-specific. Using a pin name (e.g., `board.D4`) that is not supported or incorrectly configured for your specific board will lead to `AttributeError` or `RuntimeError`. Blinka relies on correctly identifying your board, sometimes via environment variables (`BLINKA_BOARD`).
  Fix: Consult your board's specific Blinka setup guide (e.g., on learn.adafruit.com). Ensure `export BLINKA_BOARD=<YourBoardName>` is set if required for your board (e.g., `BLINKA_BOARD=RASPBERRY_PI_ZERO`). Double-check the pinout for your hardware.

Install

• pip install adafruit-blinka Install with pip

Imports

• board

  import board

• digitalio

  import digitalio

• busio

  import busio

• microcontroller

  import microcontroller

Quickstart

This quickstart demonstrates how to blink an LED using Blinka's CircuitPython-like API. It initializes a digital output pin and toggles its state. Users must ensure Blinka is properly set up for their specific single-board computer, including installing necessary system dependencies and configuring user permissions for GPIO access. The `LED_PIN` variable must be adjusted to a valid pin name for the target board.

import board
import digitalio
import time

# Blinka requires an initial setup for your specific board.
# On a Raspberry Pi, ensure you've run the setup script or installed dependencies.
# Example: curl -sL https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/raspi-blinka.py | sudo python3

# Choose a pin appropriate for your board. For Raspberry Pi, GPIO4 (physical pin 7) is common.
# Refer to your board's pinout or Blinka documentation for available pins.
# Common options: board.D4, board.D18, board.D21
LED_PIN = board.D4 # IMPORTANT: Adjust this to a valid GPIO pin for your specific board

try:
    # Initialize the digital output pin
    led = digitalio.DigitalInOut(LED_PIN)
    led.direction = digitalio.Direction.OUTPUT

    print(f"Blinking LED on pin {LED_PIN} (adjust pin for your board). Press Ctrl+C to exit.")
    while True:
        led.value = True  # Turn LED on
        time.sleep(0.5)
        led.value = False # Turn LED off
        time.sleep(0.5)
except AttributeError as e:
    print(f"Error accessing pin '{LED_PIN}': {e}")
    print("Ensure Blinka is correctly configured for your board and the pin exists.")
    print("Example: For Raspberry Pi, run 'export BLINKA_BOARD=RASPBERRY_PI_ZERO' before execution.")
except RuntimeError as e:
    print(f"Runtime error: {e}")
    print("This often indicates missing system dependencies or incorrect permissions.")
    print("Ensure libgpiod-dev, python3-libgpiod are installed and your user is in the 'gpio' group.")
    print("Try: 'sudo usermod -a -G gpio $(whoami)' and reboot.")
except KeyboardInterrupt:
    print("\nBlinking stopped.")
finally:
    # Clean up GPIO if necessary (DigitalInOut handles this on exit but explicit is good)
    if 'led' in locals() and isinstance(led, digitalio.DigitalInOut):
        led.deinit()