WiringPi

Illustration for WiringPi documentation

Summary

WiringPi is a legacy GPIO library originally designed for Raspberry Pi and adapted for other ARM SBCs. It provided a simplified pin numbering scheme and C/Python bindings for GPIO control. The original project is no longer actively maintained, but many older tutorials and code examples still reference it.

For new projects on LeMaker boards, use modern alternatives (libgpiod, sysfs GPIO, or board-specific libraries) and always verify pin mappings against your board's documentation. This page provides guidance on WiringPi alternatives, pin numbering schemes, and troubleshooting common GPIO issues.

Who this is for

Developers porting old WiringPi-based projects to LeMaker boards, people troubleshooting GPIO issues on Banana Pi/Pro, and anyone needing to understand pin numbering schemes (physical, BCM, WiringPi, SoC naming).

What you'll do

  • Understand why WiringPi is legacy and what alternatives exist.
  • Map pin numbers between physical, BCM, WiringPi, and SoC naming schemes.
  • Verify GPIO access using sysfs or libgpiod tools.
  • Test a minimal GPIO example (LED blink) before building complex projects.
  • Troubleshoot common GPIO issues (permissions, multiplexed pins, wrong numbering).

WiringPi alternatives

libgpiod (recommended for new projects)

Modern Linux GPIO interface using character devices (/dev/gpiochipN). Supported by kernel 4.8+ and provides tools like gpioinfo, gpioget, gpioset.

# Install tools (Debian/Ubuntu)
sudo apt install gpiod

# List all GPIO chips and lines
gpioinfo

# Read pin state (replace gpiochip0 and line number with your values)
gpioget gpiochip0 12

# Set pin high
gpioset gpiochip0 12=1

# Set pin low
gpioset gpiochip0 12=0

Advantages: Kernel ABI stable, no deprecated warnings, works across different boards with consistent interface.

sysfs GPIO (legacy but widely documented)

Older interface using /sys/class/gpio. Deprecated in favor of libgpiod but still works on most kernels.

# Export GPIO pin (example: pin 12)
echo 12 | sudo tee /sys/class/gpio/export

# Set direction
echo out | sudo tee /sys/class/gpio/gpio12/direction

# Set value
echo 1 | sudo tee /sys/class/gpio/gpio12/value  # High
echo 0 | sudo tee /sys/class/gpio/gpio12/value  # Low

# Unexport when done
echo 12 | sudo tee /sys/class/gpio/unexport

Caution: Pin numbers in sysfs are SoC-specific and do not match physical header numbers. Always verify mapping.

Python libraries

  • gpiod (Python bindings for libgpiod): pip install gpiod — Modern, recommended.
  • RPi.GPIO (with compatibility layer): Some images provide RPi.GPIO emulation for Allwinner SoCs. Check if available before assuming compatibility.
  • Adafruit_BBIO: Originally for BeagleBone, sometimes adapted for other boards. Board-specific.

Pin numbering schemes

Physical numbering

Counts pins 1-40 on the GPIO header (or 1-26 for 26-pin headers). Pin 1 is usually marked with a square pad or label. This is the most unambiguous scheme for documentation and wiring diagrams.

BCM (Broadcom) numbering

Used by Raspberry Pi. References GPIO numbers from the Broadcom SoC (e.g., GPIO2, GPIO3). Not directly applicable to Allwinner or other non-Broadcom SoCs without a compatibility mapping layer.

WiringPi numbering

Custom scheme used by the WiringPi library (0-31 for most boards). Designed to simplify code portability but creates confusion when comparing to physical or SoC pin names. Only relevant if running legacy WiringPi code.

SoC naming (Allwinner PA/PB/PC/PD)

Allwinner SoCs use port banks (PA, PB, PC, PD, PE, etc.) with pin numbers (e.g., PA10, PC7). To convert to sysfs GPIO numbers, use the formula:

GPIO number = (bank * 32) + pin
Example: PC7 = (2 * 32) + 7 = 71
(PA=0, PB=1, PC=2, PD=3, PE=4, etc.)

Step-by-step (test GPIO access)

1. Verify GPIO chips are available

ls -l /dev/gpiochip*
# Expected: /dev/gpiochip0, /dev/gpiochip1, etc.

# List all GPIO lines (requires gpiod tools)
gpioinfo

2. Check user permissions

# Check if user is in gpio group
groups

# Add user to gpio group if needed
sudo usermod -aG gpio $USER
# Log out and log back in for group change to take effect

3. Test with a minimal example

Connect an LED (with appropriate resistor, typically 220-330 ohm) between a GPIO pin and ground. Test with gpioset:

# Replace gpiochip0 and line number with your values
# Consult your board's pinout diagram for physical-to-GPIO mapping

# Blink LED (5 cycles)
for i in {1..5}; do
  gpioset gpiochip0 12=1
  sleep 0.5
  gpioset gpiochip0 12=0
  sleep 0.5
done

4. Verify pin is not used by another function

Some pins are multiplexed (can be GPIO, I2C, SPI, UART, etc.). Check device tree to see default assignments:

# Check device tree for pin configuration
ls /sys/firmware/devicetree/base/

# If a pin does not respond to GPIO commands, it may be assigned to I2C/SPI/UART
# Check dmesg for driver messages
dmesg | grep -E "i2c|spi|uart"

Verification checks

After setting up GPIO access, verify with these commands:

gpioinfo                      # List all GPIO lines and their states
ls -l /dev/gpiochip*          # Verify character devices exist
groups                        # Confirm user is in gpio group
dmesg | grep gpio             # Check for GPIO-related kernel messages
cat /sys/kernel/debug/gpio    # Detailed GPIO state (requires root)

Troubleshooting

GPIO pin does not respond to commands

  • Symptoms: gpioset or sysfs writes succeed but pin state does not change; LED does not light.
  • Common causes: Wrong pin number, pin assigned to another function (I2C/SPI), hardware issue.
  • Steps:
    1. Double-check pin mapping. Verify physical pin number, BCM number, and SoC naming match your board's pinout diagram.
    2. Use a multimeter to test voltage on the pin. Should read ~3.3V when high, ~0V when low.
    3. Check device tree configuration: ls /sys/firmware/devicetree/base/. Some pins default to I2C/SPI and require device tree changes for GPIO use.
    4. Test a different pin known to work (consult board documentation for safe GPIO pins).
    5. If using an LED, verify polarity and resistor value (220-330 ohm typical for 3.3V GPIO).

Permission denied when accessing GPIO

  • Symptoms: gpioset fails with "Permission denied" or sysfs writes fail.
  • Common causes: User not in gpio group, incorrect file permissions on /dev/gpiochipN.
  • Steps:
    1. Add user to gpio group: sudo usermod -aG gpio $USER
    2. Log out and log back in (or run newgrp gpio in current shell).
    3. Verify group membership: groups should list "gpio".
    4. Check device permissions: ls -l /dev/gpiochip*. Should show group ownership "gpio" or "root".
    5. If using sysfs, ensure /sys/class/gpio is writable: ls -ld /sys/class/gpio.

Wrong pin numbering causes unexpected behaviour

  • Symptoms: Script controls wrong pins; conflicts with I2C/SPI; nothing happens.
  • Common causes: Mixing physical, BCM, WiringPi, and SoC numbering schemes.
  • Steps:
    1. Identify which numbering scheme your library/script uses. Check documentation or library source.
    2. Consult your board's official pinout diagram. Confirm physical pin number, SoC naming (e.g., PA10), and GPIO number.
    3. For Allwinner SoCs, calculate sysfs GPIO number: (bank * 32) + pin. Example: PC7 = 71.
    4. Test with a known-safe pin (check board docs for pins guaranteed to be GPIO-only, not multiplexed).
    5. If porting Raspberry Pi code, do not assume BCM numbers work directly. Verify mapping for your board.

WiringPi library not found or outdated

  • Symptoms: gpio command not found; library compile errors; deprecated warnings.
  • Common causes: WiringPi not installed, using incompatible fork, kernel version mismatch.
  • Steps:
    1. For new projects, migrate to libgpiod instead: sudo apt install gpiod.
    2. If you must use WiringPi, check for board-specific forks (e.g., WiringNP for NanoPi, WiringBP for Banana Pi).
    3. Verify kernel version: uname -r. WiringPi works best with older kernels (3.x, early 4.x).
    4. For modern kernels (5.x+), use libgpiod or Python gpiod bindings instead.
    5. Check GitHub for maintained forks: WiringPi/WiringPi (archival), board-specific forks may have recent updates.

FAQ

Should I use WiringPi for a new project?

No. WiringPi is no longer actively maintained. Use libgpiod (C/Python) for new projects. It provides a stable kernel ABI and works across different boards without custom pin mapping layers.

How do I convert physical pin numbers to GPIO numbers?

Consult your board's pinout diagram. For Allwinner SoCs, use the formula: GPIO number = (bank * 32) + pin. Example: PC7 = (2 * 32) + 7 = 71. For other SoCs, check the datasheet or board documentation.

Can I use Raspberry Pi GPIO tutorials on LeMaker boards?

Partially. Userspace tools and libraries (Python, SSH config) often work. However, pin numbering differs completely. Do not assume BCM numbers or physical pin functions match. Always verify pinout against LeMaker board documentation.

What is the safest way to test GPIO without risking hardware damage?

Use an LED with a 220-330 ohm resistor between GPIO and ground. Start with a pin documented as GPIO-only (not multiplexed with I2C/SPI). Test with gpioset to confirm the LED lights. Never connect GPIO directly to 5V or short pins together.

Why do some pins not work for GPIO?

Many pins are multiplexed (can be GPIO, I2C, SPI, UART, PWM). The device tree or boot configuration determines the default function. To use a multiplexed pin as GPIO, you may need to modify the device tree and recompile. Check your board's documentation for GPIO-dedicated pins.

How do I enable GPIO on a pin currently used by I2C?

You must modify the device tree to disable I2C and enable GPIO mode for those pins. This requires decompiling the DTB, editing the DTS source, recompiling, and updating the boot partition. Not recommended unless you understand device tree syntax. Use dedicated GPIO pins instead.

What voltage level should I use for GPIO?

LeMaker boards (Banana Pi, Banana Pro, HiKey) use 3.3V logic levels. Do not connect 5V signals directly to GPIO pins without a level shifter. Exceeding 3.3V can damage the SoC. Use a multimeter to verify voltage before connecting external circuits.

Can I use interrupts with GPIO pins?

Yes, both sysfs GPIO and libgpiod support edge detection (rising, falling, both). Use gpiomon from gpiod tools or set up interrupt handling in your code. Check your board's documentation for which pins support interrupts (most do, but verify).

Where can I find my board's pinout diagram?

Check the Main Page and navigate to your board's hub (Banana Pi/Pro, HiKey960, LeMaker Guitar). Pinout diagrams are typically in the GPIO or hardware documentation section. For Banana Pi/Pro, also check the GPIO library page.

References

Concrete example (check gpiochip devices)

ls -l /dev/gpiochip*

Author: LeMaker Documentation Team
Last updated: 2026-01-11