Fix GPIO Read() on output pins + bcm283x driver init bugs

[acanewby]

Summary

Four related fixes for GPIO reliability, discovered while testing across RPi 3B (BCM2837) and RPi 4B (BCM2711) on both RPi OS and Ubuntu 24.04.

Fixes #75 — gpioioctl.GPIOLine.Read() silently reconfigures output pins as input with PullUp
Fixes #76 — bcm283x driverGPIO.Init variable shadowing silently swallows MapGPIO() error

Commits

1. gpioioctl: fix Read() reconfiguring output pins as input with PullUp — Read() called In(PullUp) unconditionally, which reconfigured output pins as input. For any application controlling external hardware via GPIO output pins (relays, motors, LEDs, power switching), this is a safety hazard: reading pin state drives all outputs HIGH. Fix: skip In() when the line is already configured as output; read the current value directly.

2. bcm283x: fix variable shadowing that swallows MapGPIO error — In mapGPIOFallback(), the := on the if p, ok := ... block shadowed the outer p variable, causing the function to silently return the wrong pin and swallow the real error on BCM2837. Fix: extract the type-assertion into a separate function to eliminate the shadowing.

3. bcm283x: make alias registration non-fatal when pin name already exists — When gpioioctl registers hardware pin names (e.g. PWM0_OUT) as real pins, bcm283x later tries to register the same name as an alias. The resulting pinreg.RegisterAlias error aborted bcm283x-gpio driver init entirely, leaving gpioMemory nil. All subsequent Read() calls fell back to ioctl, which failed with "inappropriate ioctl for device" and returned false (LOW) for pins that were actually HIGH. Fix: log alias conflicts and continue rather than aborting init.

4. bcm283x: improve error message when /dev/gpiomem is inaccessible — On Ubuntu 24.04, the kernel module sets /dev/gpiomem to root:root 0600 (vs RPi OS root:gpio 0660). The existing error message ("need more access, try as root") is unhelpful. Fix: suggest a specific udev rule: KERNEL=="gpiomem", GROUP="gpio", MODE="0660".

Testing

All four commits include tests (TDD — failing tests written first, verified failures, then fixes applied):

• gpioioctl/read_test.go — verifies Read() does not call In() on output-configured lines
• bcm283x/map_test.go — verifies mapGPIOFallback returns correct pin without shadowing; verifies alias conflict is non-fatal

Hardware validation

Tested on 3 Raspberry Pi devices:

• RPi 3B (BCM2837) — RPi OS
• RPi 4B (BCM2711) — RPi OS
• RPi 4B (BCM2711) — Ubuntu 24.04

Validation: set GPIO output pins to known states, restart our application, verify Read() returns correct values without altering pin state. All 3 devices PASS.

Ubuntu /dev/gpiomem note

Ubuntu 24.04's kernel module sets /dev/gpiomem permissions to root:root 0600, preventing non-root users from mmap access. RPi OS defaults to root:gpio 0660. Users running on Ubuntu need a udev rule:

KERNEL=="gpiomem", GROUP="gpio", MODE="0660"

This is independent of the code fixes but is important context for users hitting permission errors on Ubuntu.

CLA

Signed 2022-02-02.

[codecov]

Codecov Report

❌ Patch coverage is 19.04762% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 27.9%. Comparing base (9cd28b7) to head (f4a9339).

Files with missing lines	Patch %	Lines
bcm283x/gpio.go	19.0%	15 Missing and 2 partials ⚠️

❌ Your project check has failed because the head coverage (27.9%) is below the target coverage (60.0%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@           Coverage Diff           @@
##            main     #77     +/-   ##
=======================================
+ Coverage   27.2%   27.9%   +0.6%     
=======================================
  Files         96      96             
  Lines      11834    9486   -2348     
=======================================
- Hits        3220    2642    -578     
+ Misses      8479    6707   -1772     
- Partials     135     137      +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[acanewby]

Codecov check context

Two notes on the codecov failures:

Patch coverage (19%): The 17 uncovered lines are in bcm283x/gpio.go — specifically the Init() error-handling paths for /dev/gpiomem permission failures and the alias registration recovery logic. These code paths require real kernel GPIO subsystem state (bcm283x driver init, /dev/gpiomem device node, pinreg alias conflict) that cannot be exercised in unit tests without mocking the entire driver init sequence. We wrote unit tests for everything that can be tested in isolation:

• bcm283x/map_test.go: verifies mapGPIOFallback returns the correct pin without variable shadowing; verifies alias registration conflict is handled non-fatally
• gpioioctl/read_test.go: verifies Read() does not call In() on output-configured lines

The remaining lines were validated through hardware testing on 3 physical devices (RPi 3B + two RPi 4B, RPi OS + Ubuntu 24.04).

Project coverage (27.9% vs 60% target): The base branch (main) is at 27.2%, so our PR actually increases overall project coverage by +0.6%. The project target of 60% is a pre-existing gap unrelated to this change.