rgpio 0.1.0

data/examples/adc.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+
+# Read all eight channels of an MCP3208 analogue-to-digital converter.
+#
+# Wiring (MCP3208 in a 16-pin DIP, pin 1 at the notch):
+#   pin 1-8   CH0..CH7   -- analogue inputs; a potentiometer's wiper on CH0
+#   pin 9     DGND       -- GND
+#   pin 10    CS/SHDN    -- GPIO8  (pin 24, CE0)
+#   pin 11    DIN        -- GPIO10 (pin 19, MOSI)
+#   pin 12    DOUT       -- GPIO9  (pin 21, MISO)
+#   pin 13    CLK        -- GPIO11 (pin 23, SCLK)
+#   pin 14    AGND       -- GND
+#   pin 15    VREF       -- 3.3 V  (pin 1)
+#   pin 16    VDD        -- 3.3 V
+#
+# A potentiometer to try it with: one end to 3.3 V, the other to GND, the wiper
+# to CH0. A 10k pot is the one to reach for: 1k wastes 3.3 mA across it for no
+# gain in accuracy.
+#
+# Unconnected channels are not faulty and not arbitrary either — they mirror
+# whatever is going on nearby. Measured here: with every channel unconnected they
+# read codes 0-10, and with one channel tied to 3.3 V and sampled repeatedly the
+# floating ones rose to a mean near 15 with excursions past 400.
+#
+# Prerequisite — the header SPI bus must be enabled:
+#   sudo raspi-config nonint do_spi 0     # or: dtparam=spi=on in config.txt
+#
+# Verify:
+#   ls /dev/spidev0.0
+#
+# Run:
+#   ruby examples/adc.rb
+
+require_relative "../lib/rgpio"
+
+INTERVAL = 0.5
+REFERENCE_VOLTAGE = 3.3
+
+$stdout.sync = true
+
+puts "spidev buses: #{Rgpio::SPI.devices.inspect}"
+
+adc = Rgpio::MCP3208.new(reference_voltage: REFERENCE_VOLTAGE)
+puts "MCP3208 on #{adc.spi.path} at #{adc.spi.speed_hz / 1000} kHz. Ctrl-C to stop."
+puts "        #{(0...adc.channels).map { |c| format("%7s", "CH#{c}") }.join}"
+
+begin
+  loop do
+    codes = adc.read_all
+    puts "raw     #{codes.map { |v| format("%7d", v) }.join}"
+    puts "volts   #{codes.map do |v|
+      format("%7.3f", v / (Rgpio::MCP3208::RESOLUTION - 1).to_f * REFERENCE_VOLTAGE)
+    end.join}"
+    sleep INTERVAL
+  end
+rescue Interrupt
+  puts "\nStopped."
+ensure
+  adc.close
+end

data/examples/adc_led.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+
+# Turn a knob, change an LED's brightness: an MCP3208 channel driving a PWMLED.
+#
+# Wiring: the MCP3208 as in examples/adc.rb, plus
+#   potentiometer  -- one end to 3.3 V, the other to GND, wiper to CH0
+#   GPIO4 (pin 7)  -- 1k resistor -- LED anode, LED cathode -- GND
+#
+# Run:
+#   ruby examples/adc_led.rb
+
+require_relative "../lib/rgpio"
+
+KNOB_CHANNEL = 0
+LED_GPIO = 4
+INTERVAL = 0.02
+
+$stdout.sync = true
+
+adc = Rgpio::MCP3208.new
+led = Rgpio::PWMLED.new(LED_GPIO)
+
+puts "Turn the knob on CH#{KNOB_CHANNEL} to dim the LED on GPIO#{LED_GPIO}. Ctrl-C to stop."
+
+begin
+  last_shown = nil
+  loop do
+    level = adc.value(KNOB_CHANNEL)
+    led.value = level
+
+    # Only redraw when it moves, so a still knob does not scroll the terminal.
+    percent = (level * 100).round
+    if percent != last_shown
+      puts format("CH%d = %4.2f  (%3d%%)  %s", KNOB_CHANNEL, level, percent, "#" * (percent / 2))
+      last_shown = percent
+    end
+    sleep INTERVAL
+  end
+rescue Interrupt
+  puts "\nStopped."
+ensure
+  led.close
+  adc.close
+end

data/examples/button.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+
+# React to a switch with the high-level Rgpio::Button device, which runs the
+# callbacks on a background thread. For the same thing written against
+# Chip/LineRequest directly, see examples/lowlevel/button.rb.
+#
+# Wiring — this circuit puts the switch on the 3.3 V side, so the line needs
+# the internal pull-down that Button uses by default:
+#   3.3 V (pin 1) -- switch -- 1 kΩ resistor -- GPIO4 (pin 7)
+#
+# For the other common wiring (switch to GND) pass pull_up: true instead:
+#   button = Rgpio::Button.new(4, pull_up: true)
+#
+# Run:
+#   ruby examples/button.rb
+#
+# Press and release the switch; stop with Ctrl-C.
+
+require_relative "../lib/rgpio"
+
+BUTTON_GPIO = 4
+
+button = Rgpio::Button.new(BUTTON_GPIO)
+
+begin
+  button.when_pressed  { puts "Pressed" }
+  button.when_released { puts "Released" }
+
+  puts "Waiting for GPIO#{BUTTON_GPIO}. Press Ctrl-C to stop."
+  Rgpio.pause
+ensure
+  button.close
+end

data/examples/lcd.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+
+# Print text on an ST7032 character LCD (Akizuki AQM0802 8x2 / AQM1602 16x2).
+#
+# Wiring (module runs on 3.3 V; the Akizuki kit board carries the pull-ups):
+#   3.3V   (pin 1)          -- VDD
+#   GND    (pin 9)          -- GND
+#   GPIO2  (pin 3, SDA)     -- SDA
+#   GPIO3  (pin 5, SCL)     -- SCL
+#
+# Prerequisite — the header I2C bus must be enabled:
+#   sudo raspi-config nonint do_i2c 0     # or: dtparam=i2c_arm=on in config.txt
+#   sudo reboot
+#
+# Verify:
+#   i2cdetect -y 1        # the display answers at 0x3e
+#
+# Run:
+#   ruby examples/lcd.rb
+#
+# A blank display with a sensible-looking backlight is almost always contrast;
+# pass contrast: 0..63 to ST7032.new until the characters appear.
+
+require_relative "../lib/rgpio"
+
+COLUMNS = 8 # 16 for an AQM1602
+
+Rgpio::ST7032.open(columns: COLUMNS) do |lcd|
+  lcd.message = "Hello\nrgpio"
+  sleep 2
+
+  # The cursor addresses each row independently.
+  lcd.clear
+  3.times do |i|
+    lcd.move_to(0, 0)
+    lcd.print("count".ljust(COLUMNS))
+    lcd.move_to(0, 1)
+    lcd.print((i + 1).to_s.ljust(COLUMNS))
+    sleep 1
+  end
+
+  lcd.message = "bye"
+  sleep 1
+  lcd.clear
+end
+
+puts "Done."

data/examples/lcd_thermometer.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+
+# Show the ADT7410's temperature on an ST7032 LCD — the two I2C devices from
+# the book on one bus, each with its own address.
+#
+# Wiring: both modules share the same four header pins.
+#   3.3V   (pin 1)          -- VDD  (sensor and display)
+#   GND    (pin 9)          -- GND  (sensor and display)
+#   GPIO2  (pin 3, SDA)     -- SDA  (sensor and display)
+#   GPIO3  (pin 5, SCL)     -- SCL  (sensor and display)
+#
+# Prerequisite — the header I2C bus must be enabled:
+#   sudo raspi-config nonint do_i2c 0     # or: dtparam=i2c_arm=on in config.txt
+#   sudo reboot
+#
+# Verify:
+#   i2cdetect -y 1        # 0x3e (display) and 0x48 (sensor) both answer
+#
+# Run:
+#   ruby examples/lcd_thermometer.rb
+
+require_relative "../lib/rgpio"
+
+COLUMNS = 8 # 16 for an AQM1602
+INTERVAL = 1.0
+
+$stdout.sync = true # so the readings still appear when piped to a file
+
+sensor = Rgpio::ADT7410.new
+lcd = Rgpio::ST7032.new(columns: COLUMNS)
+
+sleep Rgpio::ADT7410::CONVERSION_TIME
+
+# The label never changes, so write it once.
+lcd.move_to(0, 0)
+lcd.print("Temp".ljust(COLUMNS))
+
+begin
+  loop do
+    celsius = sensor.temperature
+
+    # Overwrite the value in place rather than clearing: a clear blanks the
+    # panel for the width of the next transfer, which reads as a flicker once
+    # a second. Padding to the full row erases the previous, longer value.
+    lcd.move_to(0, 1)
+    lcd.print(format("%.1f C", celsius).rjust(COLUMNS))
+
+    puts format("%.2f degC", celsius)
+    sleep INTERVAL
+  end
+rescue Interrupt
+  puts "\nStopped."
+ensure
+  lcd.clear
+  lcd.close
+  sensor.close
+end

data/examples/led.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+
+# Blink an LED with the high-level Rgpio::LED device.
+# For the same thing written against Chip/LineRequest directly, see
+# examples/lowlevel/blink.rb.
+#
+# Wiring:
+#   GPIO4 (pin 7) -- 1 kΩ resistor -- LED anode (long leg)
+#   LED cathode (short leg) -- GND (pin 6 or any GND)
+#
+# Run:
+#   ruby examples/led.rb
+#
+# The LED turns on and off five times at one-second intervals.
+
+require_relative "../lib/rgpio"
+
+LED_GPIO = 4
+
+led = Rgpio::LED.new(LED_GPIO)
+
+begin
+  5.times do
+    led.on
+    sleep 1
+    led.off
+    sleep 1
+  end
+ensure
+  led.close
+end

data/examples/lowlevel/blink.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+
+# Blink an LED connected to GPIO17.
+#
+# Wiring:
+#   Pi 5 pin 11 (GPIO17) --[330 Ω]-- LED anode
+#   LED cathode          -- GND (pin 9 or any GND pin)
+#
+# Run:
+#   ruby examples/lowlevel/blink.rb
+#
+# Ctrl-C to stop.
+
+require_relative "../../lib/rgpio"
+
+GPIO_LED    = 17
+BLINK_DELAY = 0.5 # seconds
+
+puts "libgpiod version: #{Rgpio.version}"
+puts "Blinking GPIO#{GPIO_LED} at #{1.0 / (BLINK_DELAY * 2)} Hz. Press Ctrl-C to stop."
+
+# No path given → auto-detect the header GPIO controller, so the same
+# script runs unchanged on Pi 5 / Pi 4 / Pi Zero.
+Rgpio::Chip.open do |chip|
+  puts "Chip: #{chip.path} #{chip.label} (#{chip.num_lines} lines)"
+
+  request = chip.request_lines(
+    offsets: [GPIO_LED],
+    direction: :output,
+    consumer: "rgpio-blink"
+  )
+
+  begin
+    loop do
+      request.set_value(GPIO_LED, :active)
+      sleep BLINK_DELAY
+      request.set_value(GPIO_LED, :inactive)
+      sleep BLINK_DELAY
+    end
+  rescue Interrupt
+    puts "\nStopped."
+  ensure
+    request.set_value(GPIO_LED, :inactive)
+    request.release
+  end
+end

data/examples/lowlevel/button.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+
+# Read a button connected to GPIO27.
+# Prints a line each time the button is pressed or released.
+#
+# Wiring (active-low with internal pull-up):
+#   Pi 5 pin 13 (GPIO27) -- one leg of button
+#   Button other leg     -- GND (pin 14 or any GND pin)
+#
+# Run:
+#   ruby examples/lowlevel/button.rb
+#
+# Ctrl-C to stop.
+
+require_relative "../../lib/rgpio"
+
+GPIO_BUTTON = 27
+DEBOUNCE_S  = 0.050   # 50 ms安定でイベント確定
+POLL_S      = 0.005   # エッジイベント待ちのタイムアウト（＝ポーリング間隔）
+
+puts "libgpiod version: #{Rgpio.version}"
+puts "Watching GPIO#{GPIO_BUTTON} for button events. Press Ctrl-C to stop."
+
+# No path given → auto-detect the header GPIO controller (Pi 5 / 4 / Zero).
+Rgpio::Chip.open do |chip|
+  puts "Chip: #{chip.path} #{chip.label}"
+
+  request = chip.request_lines(
+    offsets: [GPIO_BUTTON],
+    direction: :input,
+    edge: :both, # エッジ検出を有効にしてカーネルが値を更新し続けるようにする
+    bias: :pull_up,
+    active_low: true,
+    consumer: "rgpio-button"
+  )
+
+  # エッジイベントで「変化があった」と気付き、get_valueで「実際の状態」を読む。
+  # イベントのtype（:rising/:falling）は使わない。
+  # これによりクロック差・イベント順序・ノイズ問題を全て回避する。
+  stable          = request.get_value(GPIO_BUTTON)
+  candidate       = stable
+  candidate_since = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+  begin
+    loop do
+      # エッジイベントが来たら即座に、なければ POLL_S 後に抜ける
+      # バッファを読み切ることで溢れを防ぐ（イベント内容は捨てる）
+      request.read_edge_events(timeout: POLL_S)
+
+      current = request.get_value(GPIO_BUTTON)
+      now     = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      if current != candidate
+        # 状態が変わった → タイマーリセット
+        candidate       = current
+        candidate_since = now
+      elsif current != stable && (now - candidate_since) >= DEBOUNCE_S
+        # DEBOUNCE_S 間ずっと同じ → 確定して報告
+        stable = current
+        label  = stable == :active ? "PRESSED " : "RELEASED"
+        puts "[#{now.round(3)} s] GPIO#{GPIO_BUTTON} #{label}"
+      end
+    end
+  rescue Interrupt
+    puts "\nStopped."
+  ensure
+    request.release
+  end
+end

data/examples/lowlevel/servo.rb

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+
+# Drive a standard RC servo motor via hardware PWM on GPIO12.
+#
+# Wiring:
+#   GPIO12 (pin 32, RP1 PWM channel 0) -- servo signal wire (usually yellow/orange)
+#   5 V    (pin 2 or 4)                -- servo power (red)
+#   GND    (pin 6 or any GND)          -- servo ground (brown/black)
+#
+# Prerequisites — GPIO12 must be routed to RP1 PWM0. Two options:
+#
+#   (A) No reboot, NOT persistent (gone after reboot) — apply at runtime:
+#         sudo dtoverlay pwm pin=12 func=4
+#       Undo with: sudo dtoverlay -r pwm
+#
+#   (B) Persistent — add to /boot/firmware/config.txt and reboot:
+#         dtoverlay=pwm,pin=12,func=4
+#
+# Verify either way:
+#   pinctrl get 12        # should show "a0" / PWM0_CHAN0, not "none"
+#   ls /sys/class/pwm/    # a second pwmchip (RP1 PWM0) appears
+#
+# Run:
+#   sudo ruby examples/servo.rb
+#
+# The servo sweeps from minimum to maximum position and back, three times.
+
+require_relative "../lib/rgpio"
+
+SERVO_GPIO     = 12
+FREQUENCY_HZ   = 50      # Standard servo frequency (20 ms period)
+PULSE_MIN_US   = 500     # 0.5 ms — full counter-clockwise (varies by servo)
+PULSE_CENTER_US = 1500   # 1.5 ms — center position
+PULSE_MAX_US   = 2500    # 2.5 ms — full clockwise (varies by servo)
+STEP_US        = 10      # microseconds per step
+STEP_DELAY     = 0.005   # seconds between steps
+
+def sweep(pwm, from_us, to_us, step_us, delay)
+  steps = ((to_us - from_us) / step_us.to_f).ceil.abs
+  direction = to_us > from_us ? 1 : -1
+  steps.times do |i|
+    pwm.pulse_width_us = from_us + (direction * i * step_us)
+    sleep delay
+  end
+  pwm.pulse_width_us = to_us
+  sleep delay
+end
+
+puts "libgpiod version: #{Rgpio.version}"
+puts "Available PWM chips: #{Rgpio::HardwarePWM.available_chips.inspect}"
+puts "Driving servo on GPIO#{SERVO_GPIO} at #{FREQUENCY_HZ} Hz."
+
+Rgpio::HardwarePWM.open(gpio: SERVO_GPIO) do |pwm|
+  puts "Using pwmchip#{pwm.chip_num}, channel #{pwm.channel}"
+  pwm.frequency  = FREQUENCY_HZ
+  pwm.duty_cycle = 0.0 # start with duty=0 before enabling
+  pwm.enable
+
+  # Move to center first
+  pwm.pulse_width_us = PULSE_CENTER_US
+  sleep 0.5
+
+  3.times do |run|
+    puts "Sweep #{run + 1}/3: min → max → min"
+    sweep(pwm, PULSE_CENTER_US, PULSE_MAX_US, STEP_US, STEP_DELAY)
+    sweep(pwm, PULSE_MAX_US, PULSE_MIN_US, STEP_US, STEP_DELAY)
+    sweep(pwm, PULSE_MIN_US, PULSE_CENTER_US, STEP_US, STEP_DELAY)
+    sleep 0.3
+  end
+
+  puts "Done. Returning to center."
+  pwm.pulse_width_us = PULSE_CENTER_US
+  sleep 0.5
+end
+
+puts "PWM disabled and unexported."

data/examples/motion_sensor.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+
+# Report movement from a PIR sensor with Rgpio::MotionSensor.
+#
+# Sensor: a D-SUN PIR module — the HC-SR501 layout, with a BISS0001 controller,
+# a white dome, two trimmers and a three-pin mode jumper. It runs on 5 V and
+# not on 3.3 V (the onboard regulator needs the headroom), and its OUT pin
+# swings 0/3.3 V because the BISS0001 sits behind that regulator, so it drives
+# a GPIO line directly.
+#
+# Some clones drive OUT to VCC instead, and 5 V on a GPIO pin damages the Pi.
+# With an unfamiliar module, leave OUT disconnected, power the sensor, wave at
+# it and measure OUT against GND: 3.3 V is safe to wire up, 5 V needs a divider
+# (OUT -- 10 kΩ -- GPIO4 -- 20 kΩ -- GND) or a level shifter.
+#
+# Wiring (PIR sensor):
+#   VCC -- 5 V (pin 2)
+#   GND -- GND (pin 6)
+#   OUT -- GPIO4 (pin 7)
+#
+# Run:
+#   ruby examples/motion_sensor.rb
+#
+# Move in front of the sensor; stop with Ctrl-C. Use the two trimmers on the
+# sensor to adjust sensitivity and hold time while this is running — which
+# trimmer is which varies by batch, so turn one and watch whether the length of
+# a detection changes.
+#
+# Two things about the module shape what this prints. It settles for up to a
+# minute after power-on and fires at random until it has, so detections inside
+# the warm-up window are reported but left out of the count. And OUT stays high
+# for the hold time after a detection, so continuous movement counts once per
+# hold period rather than once per movement. Both timings come from resistors
+# and capacitors on the board and vary between clones: the hold time bottoms
+# out at 0.9 s on the D-SUN board this was written against, where the HC-SR501
+# datasheet says 5 s. Measure rather than assume.
+#
+# These modules also trigger on power-rail noise as readily as on movement —
+# the BISS0001 front end has a lot of gain and the Pi's 5 V pin is a switching
+# regulator's output. If detections arrive with nothing moving, put 100 µF and
+# 0.1 µF across VCC/GND at the sensor and turn the sensitivity down.
+
+require_relative "../lib/rgpio"
+
+SENSOR_GPIO = 4
+WARMUP_SECONDS = 60
+
+sensor = Rgpio::MotionSensor.new(SENSOR_GPIO)
+
+begin
+  # CLOCK_MONOTONIC, not Time.now: a Pi has no RTC, so the wall clock can jump
+  # by hours the moment NTP answers — often within a minute of boot.
+  started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  count = 0
+
+  # Only the watcher thread runs this block, so the counter needs no lock.
+  sensor.when_motion do
+    if Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at < WARMUP_SECONDS
+      puts "motion detected! (warming up...)"
+    else
+      count += 1
+      puts "motion detected! #{count}"
+    end
+  end
+
+  puts "Watching GPIO#{SENSOR_GPIO}, counting after #{WARMUP_SECONDS} s of warm-up. Press Ctrl-C to stop."
+  Rgpio.pause
+ensure
+  sensor.close
+end

data/examples/motor.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+# Drive a DC motor forward and backward with Rgpio::Motor through a DRV8835
+# two-input motor driver.
+#
+# Wiring (DRV8835):
+#   VM, GND    -- motor power supply (+ / -)
+#   VCC        -- 3.3 V (pin 1)
+#   AOUT1/2    -- motor A terminals
+#   AIN1       -- GPIO2  (forward)
+#   AIN2       -- GPIO14 (backward)
+#
+# GPIO2 is used for forward rather than GPIO4, which can already be claimed by
+# another consumer and then fails the request as busy.
+#
+# Run:
+#   ruby examples/motor.rb
+#
+# The motor runs forward for five seconds, then backward, until Ctrl-C.
+
+require_relative "../lib/rgpio"
+
+motor = Rgpio::Motor.new(forward: 2, backward: 14)
+
+begin
+  loop do
+    puts "forward"
+    motor.forward
+    sleep 5
+    puts "backward"
+    motor.backward
+    sleep 5
+  end
+rescue Interrupt
+  puts "\nStopping."
+ensure
+  motor.close
+end

data/examples/pwm_info.rb

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+
+# Non-destructive hardware-PWM diagnostic.
+#
+# Prints the detected board, the PWM chips present in sysfs (with their device
+# address and channel count), and — WITHOUT exporting anything — which chip and
+# channel each header GPIO would resolve to. Handy for validating board support
+# (e.g. Pi 4) before driving a real signal.
+#
+# Run (no root needed — it only reads sysfs):
+#   ruby examples/pwm_info.rb
+
+require_relative "../lib/rgpio"
+
+HW = Rgpio::HardwarePWM
+
+# Read-only preview of HardwarePWM#detect_pwm_chip! — never exports a channel.
+def resolve_chip(board, chips)
+  profile = HW::PWM_CHIP_PROFILE[board]
+  if profile
+    by_address = chips.find do |c|
+      (File.readlink(c[:path]) rescue "").include?(profile[:address])
+    end
+    return [by_address[:chip], "address #{profile[:address]}"] if by_address
+
+    by_npwm = chips.find { |c| c[:npwm] == profile[:npwm] }
+    return [by_npwm[:chip], "npwm==#{profile[:npwm]}"] if by_npwm
+  end
+  return [chips.first[:chip], "only chip"] if chips.size == 1
+
+  [nil, "ambiguous — pass chip: explicitly"]
+end
+
+puts "libgpiod:      #{Rgpio.available? ? Rgpio.version : "not available"}"
+puts "board model:   #{HW.board_model.inspect}"
+
+board = HW.detect_board
+puts "detected board: #{board.inspect}"
+puts
+
+chips = HW.available_chips
+if chips.empty?
+  puts "No PWM chips under #{HW::PWM_SYSFS_ROOT}. Enable the PWM dtoverlay first."
+  exit 1
+end
+
+puts "PWM chips:"
+chips.each do |c|
+  link = File.readlink(c[:path]) rescue "(not a symlink)"
+  puts "  pwmchip#{c[:chip]}  npwm=#{c[:npwm]}  ->  #{link}"
+end
+puts
+
+chip_num, why = resolve_chip(board, chips)
+puts "chip auto-detection for #{board.inspect}: " \
+     "#{chip_num ? "pwmchip#{chip_num}" : "FAILED"} (#{why})"
+puts
+
+table = HW::GPIO_TO_PWM_CHANNEL[board]
+if table
+  puts "header GPIO -> channel (#{board.inspect}):"
+  table.each do |gpio, channel|
+    puts "  GPIO#{gpio}  ->  pwmchip#{chip_num || "?"}, channel #{channel}"
+  end
+else
+  puts "No header GPIO -> channel mapping for board #{board.inspect}. " \
+       "Pass board: :pi5/:pi4 or chip:/channel: explicitly."
+end