{"id":7896,"library":"adafruit-blinka","title":"Adafruit Blinka","description":"Adafruit Blinka provides CircuitPython APIs for non-CircuitPython versions of Python, primarily CPython on Linux. It allows users to run CircuitPython code on single-board computers like the Raspberry Pi, Jetson Nano, and others. The library is actively maintained with frequent releases (multiple per month) to add support for new boards, fix board-specific import paths, and address underlying system library interactions. The current version is 9.0.4.","status":"active","version":"9.0.4","language":"en","source_language":"en","source_url":"https://github.com/adafruit/Adafruit_Blinka","tags":["hardware","gpio","circuitpython","embedded","raspberrypi","linux","adafruit"],"install":[{"cmd":"pip install adafruit-blinka","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for GPIO access on Linux-based systems.","package":"libgpiod-dev","optional":false},{"reason":"Python bindings for libgpiod, essential for GPIO operations.","package":"python3-libgpiod","optional":false},{"reason":"Required for compiling some underlying C components.","package":"build-essential","optional":false},{"reason":"Required for Python header files necessary for building extensions.","package":"python3-dev","optional":false}],"imports":[{"symbol":"board","correct":"import board"},{"symbol":"digitalio","correct":"import digitalio"},{"symbol":"busio","correct":"import busio"},{"symbol":"microcontroller","correct":"import microcontroller"}],"quickstart":{"code":"import board\nimport digitalio\nimport time\n\n# Blinka requires an initial setup for your specific board.\n# On a Raspberry Pi, ensure you've run the setup script or installed dependencies.\n# Example: curl -sL https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/raspi-blinka.py | sudo python3\n\n# Choose a pin appropriate for your board. For Raspberry Pi, GPIO4 (physical pin 7) is common.\n# Refer to your board's pinout or Blinka documentation for available pins.\n# Common options: board.D4, board.D18, board.D21\nLED_PIN = board.D4 # IMPORTANT: Adjust this to a valid GPIO pin for your specific board\n\ntry:\n    # Initialize the digital output pin\n    led = digitalio.DigitalInOut(LED_PIN)\n    led.direction = digitalio.Direction.OUTPUT\n\n    print(f\"Blinking LED on pin {LED_PIN} (adjust pin for your board). Press Ctrl+C to exit.\")\n    while True:\n        led.value = True  # Turn LED on\n        time.sleep(0.5)\n        led.value = False # Turn LED off\n        time.sleep(0.5)\nexcept AttributeError as e:\n    print(f\"Error accessing pin '{LED_PIN}': {e}\")\n    print(\"Ensure Blinka is correctly configured for your board and the pin exists.\")\n    print(\"Example: For Raspberry Pi, run 'export BLINKA_BOARD=RASPBERRY_PI_ZERO' before execution.\")\nexcept RuntimeError as e:\n    print(f\"Runtime error: {e}\")\n    print(\"This often indicates missing system dependencies or incorrect permissions.\")\n    print(\"Ensure libgpiod-dev, python3-libgpiod are installed and your user is in the 'gpio' group.\")\n    print(\"Try: 'sudo usermod -a -G gpio $(whoami)' and reboot.\")\nexcept KeyboardInterrupt:\n    print(\"\\nBlinking stopped.\")\nfinally:\n    # Clean up GPIO if necessary (DigitalInOut handles this on exit but explicit is good)\n    if 'led' in locals() and isinstance(led, digitalio.DigitalInOut):\n        led.deinit()\n","lang":"python","description":"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."},"warnings":[{"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).","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add your user to the `gpio` group: `sudo usermod -a -G gpio $(whoami)` then reboot your system (`sudo reboot`).","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":">=9.0.0, particularly 9.0.0, 9.0.1"},{"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.","message":"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`).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `libgpiod-dev` and `python3-libgpiod`: `sudo apt-get install -y libgpiod-dev python3-libgpiod`.","cause":"The underlying C library `libgpiod` or its Python bindings `python3-libgpiod` are not installed or correctly linked.","error":"ModuleNotFoundError: No module named 'libgpiod_pin'"},{"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.","cause":"Blinka could not automatically identify your board, or the board definition is missing/incorrect, or the required JSON configuration files were not installed.","error":"RuntimeError: Failed to initialize PINS: No pins found for board 'YourBoardName'"},{"fix":"Add your user to the `gpio` group: `sudo usermod -a -G gpio $(whoami)` and then reboot the system (`sudo reboot`).","cause":"Your user account does not have the necessary permissions to access GPIO hardware.","error":"PermissionError: [Errno 13] Permission denied: '/dev/gpiomem'"},{"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.","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.","error":"AttributeError: module 'board' has no attribute 'D18'"}]}