WiringPi
On this page
Summary
Historical LeMaker GPIO documentation. Original WiringPi history, the maintained Raspberry Pi WiringPi fork and Banana Pi-specific library ports are separate projects. Raspberry Pi maintenance does not establish support for an Allwinner board or identical pin numbering.
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 and the character-device interface
Use the tool version supplied by the exact maintained OS, its matching manual and the board-specific pin map. Current libgpiod syntax differs from older examples; no arbitrary chip/line number or output-toggle command is supplied here.
Historical sysfs interface
Old global GPIO-number/export examples are archival and are not a portable modern pin map. Do not write to a line based on this historical numbering.
Language bindings
Check bindings, kernel ABI and exact board support independently. A maintained Raspberry Pi library does not establish Banana Pi compatibility.
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)
Start with exact board/revision, pinout, kernel device tree and locally installed library version. Keep attached loads disconnected while identifying lines. Read gpioget --version and gpioget --help before using examples: libgpiod v1 and v2 command syntax differs. The current upstream gpioget manual uses a chip option for offsets. Do not apply a Raspberry Pi BCM number, physical header position or old global GPIO number as an interchangeable chip/line offset. This page supplies no unverified output-toggle command.
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:
gpiosetor 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:
- Double-check pin mapping. Verify physical pin number, BCM number, and SoC naming match your board's pinout diagram.
- Use a multimeter to test voltage on the pin. Should read ~3.3V when high, ~0V when low.
- Check device tree configuration:
ls /sys/firmware/devicetree/base/. Some pins default to I2C/SPI and require device tree changes for GPIO use. - Test a different pin known to work (consult board documentation for safe GPIO pins).
- If using an LED, verify polarity and resistor value (220-330 ohm typical for 3.3V GPIO).
Permission denied when accessing GPIO
- Symptoms:
gpiosetfails with "Permission denied" or sysfs writes fail. - Common causes: User not in gpio group, incorrect file permissions on
/dev/gpiochipN. - Steps:
- Add user to gpio group:
sudo usermod -aG gpio $USER - Log out and log back in (or run
newgrp gpioin current shell). - Verify group membership:
groupsshould list "gpio". - Check device permissions:
ls -l /dev/gpiochip*. Should show group ownership "gpio" or "root". - If using sysfs, ensure
/sys/class/gpiois writable:ls -ld /sys/class/gpio.
- Add user to gpio group:
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:
- Identify which numbering scheme your library/script uses. Check documentation or library source.
- Consult your board's official pinout diagram. Confirm physical pin number, SoC naming (e.g., PA10), and GPIO number.
- For Allwinner SoCs, calculate sysfs GPIO number:
(bank * 32) + pin. Example: PC7 = 71. - Test with a known-safe pin (check board docs for pins guaranteed to be GPIO-only, not multiplexed).
- If porting Raspberry Pi code, do not assume BCM numbers work directly. Verify mapping for your board.
WiringPi library not found or outdated
- Symptoms:
gpiocommand not found; library compile errors; deprecated warnings. - Common causes: WiringPi not installed, using incompatible fork, kernel version mismatch.
- Steps:
- For new projects, migrate to libgpiod instead:
sudo apt install gpiod. - If you must use WiringPi, check for board-specific forks (e.g., WiringNP for NanoPi, WiringBP for Banana Pi).
- Verify kernel version:
uname -r. WiringPi works best with older kernels (3.x, early 4.x). - For modern kernels (5.x+), use libgpiod or Python gpiod bindings instead.
- Check GitHub for maintained forks: WiringPi/WiringPi (archival), board-specific forks may have recent updates.
- For new projects, migrate to libgpiod instead:
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
- WiringPi on GitHub (archival)
- BananaPro/Pi: GPIO library
- Wiki Main Page ' Board-specific hubs and documentation
- Linux kernel GPIO documentation
Concrete example (check gpiochip devices)
Read-only discovery: use the installed tool’s help/version and its matching manual to inspect available chips and lines. Line metadata is not a verified pinout and does not establish that a line is electrically safe, unused or an input. GPIO access can affect hardware: confirm the exact mapping and disconnect sensitive loads before any request.
Related guides
Author: LeMaker Documentation Team
Last updated: 2026-01-11