denko-piboard 0.13.2 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bad42203be8c858270403900ba28c58f7a63eaf616151975e7b5d61a471a472
-  data.tar.gz: ad86f14e2d91a644ea1ccc8f7d599b4bbfa095d55b5f07fc734dd741447811ea
+  metadata.gz: 1e8e869c561c0673bcd8cafbef836a7e0c8fddb369a0b97a0c60a67a99380faf
+  data.tar.gz: 7f84e27065a552ad844c0483c8a5ff23e05fd7a4c2a7a8c5be2c92e99bfe9862
 SHA512:
-  metadata.gz: aceaac910ced26a348b5a22da0d3729c6cf0b91c66c7bac417d0a96877b531407a2ff56e7fa1aa1c30cde3b8709eea7d9a44b2d07cd1628f315591b0c7477594
-  data.tar.gz: ea5a92edc491447c75417b3e9787fcd785a86e7f15e27c18b92e97b4969ff30dcb1c913bc4fc10b81c09ecbe079859b7a5cd10d9cd744865680d1fd643b842fe
+  metadata.gz: aa4600cdd0cd83070610255636ae318a4a3eff654fc7fce96097558a0d4bd673b30a6e206aadba7f26010a17e1aa3615b11d1f3735a4aef2096024bc9409d687
+  data.tar.gz: d9d8d876321f87d4bc47c91913e91159d094a7558353750f16afce38fabe6b5ff50c620cb571c588c715af9dba6f7d469fcc9c665427d488f3f11e85c55c8792

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in denko.gemspec
+gemspec

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 denko-rb
+Copyright (c) 2024 denko-rb
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,33 +1,22 @@
-# denko-piboard 0.13.1
+# denko-piboard
 
-### Raspberry Pi GPIO in Ruby
+Use Linux single-board-computer GPIO in Ruby.
 
-This gem adds support for the Raspberry Pi GPIO interface to the [`denko`](https://github.com/denko-rb/denko) gem. Unlike the main gem, which requires an external microcontroller, this lets you to connect peripherals directly to the Pi.
-
-`Denko::PiBoard` is a drop-in replacement for `Denko::Board`, which would represent a connected micrcontroller. Everything maps to the Pi's built-in GPIO pins instead, and Ruby runs on the Pi itself.
-
-**Note:** This is not for the Raspberry Pi Pico (W) / RP2040. That microcontroller works with the main gem.
-
-## Example
 ```ruby
+# Turn LED on when a button is held down, off when released.
 require 'denko/piboard'
 
-# Board instance for the Pi.
-board = Denko::PiBoard.new
-
-# LED connected to GPIO4.
-led = Denko::LED.new(board: board, pin: 4)
+board  = Denko::PiBoard.new
+led    = Denko::LED.new(board: board, pin: 260)
+button = Denko::DigitalIO::Button.new(board: board, pin: 259, mode: :input_pullup)
 
-# Momentary button connected to GPIO17, using internal pullup.
-button = Denko::DigitalIO::Button.new(board: board, pin: 17, pullup: true)
-
-# Callback runs when button is down (0)
+# Callback fires when button is down (0)
 button.down do
   puts "Button down"
   led.on
 end
 
-# Callback runs when button is up (1)
+# Callback fires when button is up (1)
 button.up do
   puts "Button up"
   led.off
@@ -37,145 +26,205 @@ end
 sleep
 ```
 
-#### More Examples
-Pi-specific examples are in this gem's [examples](examples) folder, but examples from the [main gem](https://github.com/denko-rb/denko/tree/master/examples) can be modified to work on the Pi:
-
-1. Replace setup code:
-  ```ruby
-    # Replace this:
-    require 'bundler/setup'
-    require 'denko'
-    # With this:
-    require 'denko/piboard'
-
-    # Replace this:
-    connection = Denko::Connection::Serial.new()
-    board = Denko::Board.new()
-    # With this:
-    board = Denko::PiBoard.new
-  ```
-
-2. Update GPIO/pin numbers as needed. Raspberry Pi pinouts can be found [here](https://pinout.xyz/).
-  
-**Note:** Not all features from all examples are implemented yet, nor can be implemented. See [Features](#features) below.
+## Linux GPIO Features
+- [x] Internal Pull-Up/Down
+- [x] Open Drain/Source
+- [x] Digital Read/Write
+- [x] Digital Listen (Alerts)
+  - Interrupt driven, unlike `denko` microcontroller implementation 1ms polling
+  - Built in software debounce (1us by default)
+  - Alerts are read from a FIFO queue up to 65,536. Oldest alerts are lost first.
+- [ ] Analog Read (ADC)
+- [ ] Analog Write (DAC)
+- [x] Software PWM Out (any pin)
+- [x] Hardware PWM Out (specific pins per board)
+- [x] Tone Out (via Software PWM or Hardware PWM)
+- [x] Servo (via Hardware PWM)
+- [x] Infrared Out (via Hardware PWM)
+- [x] Hardware I2C
+  - [x] Multiple interfaces
+- [x] Hardware SPI
+  - [x] Multiple interfaces
+  - [x] WS2812 addressable LED via SPI MOSI
+  - [ ] SPI Listeners from `denko`
+- [ ] UART
+- [x] Ultrasonic Input (for HC-SR04 and similar)
+- [x] Pulse Sequence Input (for DHT enviro sensors and similar)
+- [x] Bit-Bang I2C
+- [x] Bit-Bang SPI
+- [x] Bit-Bang 1-Wire
 
 ## Support
 
 #### Hardware
 
-:green_heart: Support verified
-:question: Should work, but not verified
+In theory, this should work on any SBC, running Linux, with drivers for the relevant GPIO/I2C/SPI/PWM subsystems available on the system-on-chip (SoC). This is just a list of chips and products confirmed working.
+
+:green_heart: Known working
+:heart: Awaiting testing
+:question: Might work. No hardware
 
-|    Chip        | Status          | Products              | Notes |
-| :--------      | :------:        | :---------------      |------ |
-| BCM2835        | :green_heart:   | Pi 1, Pi Zero (W)     |
-| BCM2836/7      | :question:      | Pi 2                  |
-| BCM2837A0/B0   | :green_heart:   | Pi 3                  |
-| BCM2711        | :green_heart:   | Pi 4, Pi 400          |
-| BCM2710A1      | :question:      | Pi Zero 2W            |
+| Chip              | Status          | Products                               | Notes |
+| :--------         | :------:        | :----------------------                |------ |
+| Allwinner H618    | :green_heart:   | Orange Pi Zero 2W                      | DietPi
+| Rockchip RK3566   | :green_heart:   | Radxa Zero 3W/E, Radxa Rock 3C         | Armbian
+| BCM2835           | :green_heart:   | Raspberry Pi 1, Raspberry Pi Zero (W)  | Raspberry Pi OS
+| BCM2836/7         | :question:      | Raspberry Pi 2                         |
+| BCM2837A0/B0      | :green_heart:   | Raspberry Pi 3                         | Raspberry Pi OS
+| BCM2711           | :green_heart:   | Raspberry Pi 4, Raspberry Pi 400       | Raspberry Pi OS
+| BCM2710A1         | :green_heart:   | Raspberry Pi Zero 2W                   | Raspberry Pi OS
+| BCM2712           | :question:      | Raspberry Pi 5                         |
+| AML-S905X-CC      | :green_heart:   | Libre Computer Le Potato               | Libre Computer Debian 12
 
 #### Software
 
 - Operating Systems:
-  - Raspberry Pi OS
-  - DietPi
-  
-  Note: Both with kernel version 6.1 or higher.
+  - DietPi (Bookworm)
+  - Armbian (Bookworm)
+  - Raspberry Pi OS (Bookworm)
 
 - Rubies:
-  - Ruby 2.7.4 (system Ruby on some Raspberry Pi OS installs)
-  - Ruby 3.2.2 (with and without YJIT)
-  - TruffleRuby 22.3.1 :man_shrugging: (Not available on ARMv6 Pis: Zero W, Pi 1. Not recommended in general)
+  - Ruby 3.3.5 +YJIT
+
+## Install
+
+#### Install the lg C library
+```console
+# Requirements to install lgpio C
+sudo apt install swig python3-dev python3-setuptools gcc make
+
+# Temporary fork of: wget https://github.com/joan2937/lg
+wget https://github.com/vickash/lg/archive/refs/heads/master.zip
+
+# Install lgpio C
+unzip master.zip
+cd lg-master
+make
+sudo make install
+```
+
+#### Install the denko-piboard gem
+```console
+# Latest Ruby + YJIT from rbenv works best, but Ruby 3 from apt works too.
+# Install system Ruby anyway to automate permissions startup script.
+sudo apt install ruby ruby-dev
+
+sudo gem install denko-piboard
+```
+**Note:** `sudo` may be needed before `gem install` if using the system Ruby.
 
-#### Dependencies
+## Enable Hardware
 
-- [pigpio](https://github.com/joan2937/pigpio)
-- [libgpiod](https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git)
-- [pigpio gem](https://github.com/nak1114/ruby-extension-pigpio) (Ruby bindings for pigpio)
-- [denko](https://github.com/denko-rb/denko) (peripheral implementations from main gem)
+**Note:** These are simplified instructions for a few SBCs, to get you going quickly. denko-piboard uses standard Linux interfaces, so should work for many. See [the board maps readme](board_maps/README.md).
 
-## Installation
+### Orange Pi Zero 2W
+- For DietPi OS specifically
+- 2 PWMs on GPIO 226 and 227 (not matching the docs) are enabled without any setup.
+- Save the [default map](board_maps/orange_pi_zero_2w.yml) as `~/.denko_piboard_map.yml` on your Zero2W.
+- Add/edit the lines below in `/boot/dietpiEnv.txt`, and reboot.
 
-#### 1. Install pigpio and libgpiod packages
-```shell
-sudo apt install pigpio libgpiod-dev
+```
+# /dev/i2c-3 (I2C3) @ 100 kHz
+# /dev/spidev1.0 (SPI1) with first chip select (CS0) enabled
+overlay_prefix=sun50i-h616
+overlays=i2c1-pi spidev1_0
 ```
 
-#### 2. Install denko-piboard gem
-```shell
-gem install denko-piboard
+### Radxa Zero3W/E
+- For Armbian OS specifically. Newer and performs better than latest Radxa OS or DietPi available.
+- Unfortunately, Armbian does not package all device tree overlays for the RK3566. I built binaries for this default config, on kernel `6.1.75-vendor-rk35xx`, and made them available [here](https://github.com/vickash/linux-sbc-overlays/tree/master/radxa/rockchip). To use, download the `.dtbo` files into `/boot/dtb/rockchip/overlay` on your Zero3. Make sure your kernel version matches.
+
+If you rather build the overlays yourself, that repo contains the script too. On the Zero3:
+```console
+sudo apt install device-tree-compiler
+ruby rk3568_denko_overlay_install.rb
+```
+
+- Save the [default map](board_maps/radxa_zero3.yml) as `~/.denko_piboard_map.yml` on your Zero3.
+- Add/edit the lines below in `/boot/armbianEnv.txt`, and reboot.
+
+```
+# /dev/i2c-3 (I2C3) @ 100 kHz
+# /dev/spidev3.0 (SPI3) with first chip select (CS0) enabled
+# 2 PWMs on GPIO 105 and 106
+overlay_prefix=rk3568
+overlays=i2c3-m0 spi3-m1-cs0-spidev pwm8-m0 pwm9-m0
 ```
-This automatically installs dependency gems: `denko` and `pigpio`.
 
-**Note:** `sudo` may be needed before `gem install` if using the Pi's system ruby.
+**Note:** The Radxa docs are missing `I2C3_SDA_M0` and `I2C3_SCL_M0` in the function columns for GPIOs 32 and 33 respectively. This is an error. I2C3 works on these pins.
 
-## Pi Setup
+### Raspberry Pi 4 and Lower
+- For Raspberry Pi OS specifically
+- Save the [default map](board_maps/raspberry_pi.yml) as `~/.denko_piboard_map.yml` on your Raspberry Pi.
+- Add the lines below to `/boot/config.txt`, and reboot.
 
-#### pigpiod
-The `pigpio` package installs `pigpiod`, which must run in the background (as root) for Ruby scripts to work. You should only need to start it once per boot. Automate it, or start manually with:
-```shell
-sudo pigpiod -s 10
 ```
-**Note:** `-s 10` sets tick interval to 10 microseconds, lowering CPU use. Valid values are: 1, 2, 4, 5, 8, 10 (5 default).
+# 2 PWMS on GPIO 12 and 13
+dtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4
+# /dev/i2c-1 (I2C1) @ 400 kHz
+dtparam=i2c_arm=on
+dtparam=i2c_arm_baudrate=400000
+# /dev/spidev0.0 (SPI0) with first chip select (CS0) enabled
+dtoverlay=spi0-1cs
+```
 
-#### libgpiod
-Depending on your Pi and OS, `libgpiod` may limit GPIO access. If this happens, some scripts will fail. It is only used for digital read/write operations, so test with a simple script like blinking an LED. To get permission, add your user account to the `gpio` group:
+### Raspberry Pi 5
+- Instructions are same as Pi <= 4, but use the [Pi 5 map](board_maps/raspberry_pi5.yml) instead.
+- NOTE: This is based on Raspberry Pi docs, but untested in hardware. If you notice anything that should be fixed, please open a PR.
+
+### Libre Computer Le Potato
+- Use [Libre Computer Debian 12](https://distro.libre.computer/ci/debian/12/debian-12-base-arm64%2Baml-s905x-cc.img.xz)
+- Save the [default map](board_maps/le_potato.yml) as `~/.denko_piboard_map.yml` on your Le Potato.
+- Fix invalid signatures for apt:
+```console
+wget https://deb.libre.computer/repo/pool/main/libr/libretech-keyring/libretech-keyring_2024.05.19_all.deb
+sudo dpkg -i libretech-keyring_2024.05.19_all.deb
+sudo apt update
+```
+- Install the Libre Computer Wiring Tool:
+```console
+sudo apt install libretech-gpio libretech-dtoverlay
 ```
-sudo usermod -a -G gpio $(whoami)
+- Enable the default overlays for PWM, I2C and SPI:
+```console
+# 1 PWM on GPIO 95
+# 1 I2C (/dev/i2c-0) on GPIO 4 (SCL) and GPIO 5 (SDA)
+# 1 SPI (/dev/spidev0.0) on GPIO 90 (CLK), GPIO 87 (MOSI), GPIO 88 (MISO), GPIO 98 (CS)
+sudo ldto merge pwm-e i2c-ao spicc spicc-spidev
 ```
+- Reboot to enable overlays
 
-#### Enable Features
-I2C, SPI and the hardware UART may be disabled on the Pi by default. Enable them with the built-in utility:
-```shell
-# On Raspberry Pi OS:
-sudo raspi-config
+## Get Permissions
+By default, only the Linux `root` user can use GPIO / I2C / SPI / PWM. If you have a default board map at `~/.denko_piboard_map.yml`, save [this script](scripts/set_permissions.rb) to your SBC, then run it:
 
-# On DietPi:
-sudo dietpi-config
+```console
+ruby set_permissions.rb
 ```
-Select "Interfacing Options" (Raspberry Pi OS), or "Advanced Options" (DietPi) and enable features as needed.
-
-## Features
-
-### Already Implemented
-  - Internal Pull Down/Up
-  - Digital Out
-  - Digital In
-    - Listeners are polled in a thread, similar to a microcontroller, but always at 1ms.
-    - `pigpio` supports even faster polling (1-10 microseconds), but events are not received in a consistent order across pins. Won't work for MultiPin components, but may implement for SinglePin.
-  - PWM Out
-  - Servo
-  - Tone Out
-  - Infrared Out
-  - DHT Class Temperature + Humidity Sensors
-  - I2C
-    - Always uses I2C1 interface.
-    - Must enable before use. Instructions [here](https://learn.adafruit.com/adafruits-raspberry-pi-lesson-4-gpio-setup/configuring-i2c).
-    - I2C clock cannot be set dynamically. It is set at boot time from `/boot/config.txt`. Default is 100 kHz. 400 kHz is recommended if higher data rate is needed, eg. using OLED screen. Instructions [here](https://www.raspberrypi-spy.co.uk/2018/02/change-raspberry-pi-i2c-bus-speed/).
-
-### Partially Implemented
-- SPI
-  - Always uses SPI1 interface.
-  - Must enable before use. Instructions [here](https://learn.adafruit.com/adafruits-raspberry-pi-lesson-4-gpio-setup/configuring-spi).
-  - Does not bind CE pins according to GPIO pinout. Any pin can be used for chip enable.
-  - SPI modes 1 and 3 may not work.
-  - No listeners yet.
-
-### Feature Exclusivity
-- PWM Out / Servo Out
-  - Using either of these on **any** pin disables the Pi's PCM audio output globally.
-
-- Tone Out / Infrared Out
-  - Both of these use pigpio's wave interface, which only has a single instance. Calling either on **any** pin automatically stops any running instance that exists. Both features can co-exist in a script, but cannot happen at the same time.
-
-### To Be Implemented
-  - OneWire
-  - Hardware UART
-  - BitBang I2C
-  - BitBang SPI 
-  - BitBang UART
-  - WS2812
-
-### Incompatible
-  - EEPROM (Use the filesystem for persistence instead)
-  - Analog IO (No analog pins on Raspberry Pi. Use ADC or DAC over I2C or SPI)
+
+It will load load the default board map, then:
+- Create any necessary Linux groups
+- Add your user to the relevant groups
+- Change ownership and permissions for devices in the map, so you can read/write them
+
+**Note:** `sudo` is required.
+
+**Note:** If you automate this script to run at boot (recommended), it will run as root. Set the `USERNAME` constant to your Linux user's name as a String literal. This ensures the map loads from your home, and changes are applied to your user, not root.
+
+## Modifying Examples From Main Gem
+Some [examples](examples) are included in this gem, but the [main denko gem](https://github.com/denko-rb/denko/tree/master/examples) is more comprehensive. Those are written for connected microcontrollers, `Denko::Board`, but can be modified for `Denko::PiBoard`:
+
+1. Replace setup code:
+  ```ruby
+    # Replace this:
+    require 'bundler/setup'
+    require 'denko'
+    # With this:
+    require 'denko/piboard'
+
+    # Replace this:
+    board = Denko::Board.new(Denko::Connection::Serial.new)
+    # With this:
+    board = Denko::PiBoard.new
+  ```
+
+2. Change pin numbers and I2C/SPI device indices as needed.

data/Rakefile

@@ -1,5 +0,0 @@
-require "rake/extensiontask"
-
-Rake::ExtensionTask.new "gpiod" do |ext|
-  ext.lib_dir = "lib/gpiod"
-end

data/board_maps/README.md

@@ -0,0 +1,59 @@
+# Creating Custom Board Maps
+
+You will need:
+- Your SBC, running a recent (5.10 kernel or later) Linux distribution
+- A working understanding of how to enable/disable device tree overlays in Linux
+- Documentation for your board, specifically:
+  - Its pinout, with "friendly" GPIO numbers
+  - Which GPIO numbers correspond to which device tree overlays
+
+## Overlays
+
+The physical pins on your SBC can internally connect to diffent hardware devices within the SoC. The default is regular GPIO. To use hardware PWM, I2C and SPI, Linux device tree overlays tell the kernel to reserve pins, disconnected them from GPIO, and connect them to the other hardware instead.
+
+This happens at boot, so there are side-effects:
+- Pins reserved by I2C or SPI can't be used for GPIO, unless the interface is disabled, and the SBC rebooted.
+- With some asbraction tricks, a PWM can work as a regular GPIO, but **for digital output only**, and it's slower.
+- I2C frequency can only be changed at boot time, not on a per-transmission basis.
+
+There are a couple other issues too:
+- One SoC may have GPIOs on multiple `/dev/gpiochip*`s, with non-unque line numbers.
+- PWM is called by its `pwmchip*` and `pwm*` channel, not GPIO number.
+- I2C and SPI are called by index (N) from `/dev/i2c-N` or `/dev/spidev-N.0`, not GPIO numbers.
+
+To deal with this complexity, and standardize the user interface, denko-piboard uses board maps.
+
+## Board Maps
+
+A board map is a YAML file, defining all the GPIO, PWM, I2C and SPI resources enabled on the SBC.
+
+It follows these conventons:
+- `Denko::PiBoard.new` will raise unless it finds a board map
+- It accepts a board map file path as its only argument
+- If that isn't given, it looks for `.denko_piboard_map.yml`, in the user's home directory.
+- In the map, individual GPIOs are referred to (keyed by) their "friendly" or human-readable" numbers
+  - Theoretically arbitrary, but rule of thumb is: "unique numbers from the SBC's documentation"
+  - These are NOT physical pin numbers from the pinout
+  - These might match, but are NOT necessarily `/dev/gpiochip*` line numbers. Those can be non-unique, if multiple gpiochips.
+- Each GPIO number declares its:
+  - Linux gpiochip
+  - Line on that gpiochip
+  - Physical number on the SBC's pinout (optional)
+- Each PWM declares:
+  - Which GPIO number it reserves when enabled (this is its key)
+  - Its Linux pwmchip
+  - Its pwm channel on that chip
+- Each I2C or SPI interface declares:
+  - Its index, N from `/dev/i2c-N` or `/dev/spidev-N.0` (this is its key)
+  - All the GPIO numbers it reserves, keyed to their names. Eg. `miso:`, `sda:` etc.
+
+This information enables denko-piboard to:
+- Refer to GPIOs by a single, user-friendly, unique number (rather than a tuple of gpiochip and line)
+- Refer to PWMs by the GPIO number they multiplex with (rather than a tuple of pwmchip and channel)
+- Refer to I2C and SPI by their Linux device indices
+- Raise errors if you try to use any reserved pin. This fails silently otherwise, which is confusing.
+
+There are pre-made maps for some boards [here](./), which can be followed as templates. In general, these enable:
+- 2 PWM pins
+- 1 I2C interface (on physical pins 3,5 when possible)
+- 1 SPI interface (on physical pins 19,21,23 when possible)

data/board_maps/le_potato.yml

@@ -0,0 +1,89 @@
+#
+# Tested on:
+#   - Libre Computer Le Potato AML-S905X-CC, using Libre Computing's official Debian 12 (2024-01-25), with kernel 6.1.92-15907-gf36fd2695db3
+#
+# Based on https://docs.google.com/spreadsheets/d/1U3z0Gb8HUEfCIMkvqzmhMpJfzRqjPXq7mFLC-hvbKlE
+# Uses "Linux" GPIO numbers from that table
+#
+---
+pins:
+  # Left side (odd numbered physical pins)
+  # PIN 1 is 3V3
+  5: { phy: 3, chip: 0, line: 5 }
+  4: { phy: 5, chip: 0, line: 4 }
+  98: { phy: 7, chip: 1, line: 98 }
+  # PIN 9 is GND
+  8: { phy: 11, chip: 0, line: 8 }
+  9: { phy: 13, chip: 0, line: 9 }
+  10: { phy: 15, chip: 0, line: 10 }
+  # PIN 17 is 3V3
+  87: { phy: 19, chip: 1, line: 87 }
+  88: { phy: 21, chip: 1, line: 88 }
+  90: { phy: 23, chip: 1, line: 90 }
+  # PIN 25 is GND
+  75: { phy: 27, chip: 1, line: 75 }
+  96: { phy: 29, chip: 1, line: 96 }
+  97: { phy: 31, chip: 1, line: 97 }
+  85: { phy: 33, chip: 1, line: 85 }
+  86: { phy: 35, chip: 1, line: 86 }
+  84: { phy: 37, chip: 1, line: 84 }
+  # PIN 39 is GND
+
+  # Right side (even numbered physical pins)
+  # PIN 2 is 5V
+  # PIN 4 is 5V
+  # PIN 6 is GND
+  91: { phy: 8, chip: 1, line: 91 }
+  92: { phy: 10, chip: 1, line: 92 }
+  6: { phy: 12, chip: 0, line: 6 }
+  # PIN 14 is GND
+  93: { phy: 16, chip: 1, line: 93 }
+  94: { phy: 18, chip: 1, line: 94 }
+  # PIN 20 is GND
+  79: { phy: 22, chip: 1, line: 79 }
+  89: { phy: 24, chip: 1, line: 89 }
+  80: { phy: 26, chip: 1, line: 80 }
+  76: { phy: 28, chip: 1, line: 76 }
+  # PIN 30 is GND
+  95: { phy: 32, chip: 1, line: 95 }
+  # PIN 34 is GND
+  81: { phy: 36, chip: 1, line: 81 }
+  82: { phy: 38, chip: 1, line: 82 }
+  83: { phy: 40, chip: 1, line: 83 }
+
+pwms:
+  # Overlay:        pwm-e
+  # Enable on boot: sudo ldto merge pwm-e
+  # Device:         /sys/class/pwm/pwmchip0/pwm0
+  #
+  95:
+    pwmchip: 0
+    channel: 0
+
+i2cs:
+  # Overlay:        i2c-ao
+  # Enable on boot: sudo ldto merge i2c-ao
+  # Device:         /dev/i2c-0
+  #
+  0:
+    scl: 4
+    sda: 5
+
+  # Overlay:        i2c-b
+  # Enable on boot: sudo ldto merge i2c-b
+  # Device:         /dev/i2c-0 (if enabled alone), /dev/i2c-1 (if enabled with i2c-ao)
+  #
+  # 1:
+  #   scl: 76
+  #   sda: 75
+
+spis:
+  # Overlays:       spicc, spicc-spidev
+  # Enable on boot: sudo ldto merge spicc spicc-spidev
+  # Device:         /dev/spidev0.0
+  #
+  0:
+    clk: 90
+    mosi: 87
+    miso: 88
+    cs0: 89

data/board_maps/orange_pi_zero_2w.yml

@@ -0,0 +1,85 @@
+#
+# Tested on Orange Pi Zero 2W, running DietPi, Kernel 6.6.31-current-sunxi64
+# Note: PWM channels 1 and 2 work without an overlay.
+#
+---
+pins:
+  # Left side (odd numbered)
+  # PIN 1 is 3V3
+  264: { phy: 3, chip: 0, line: 264 }
+  263: { phy: 5, chip: 0, line: 263 }
+  269: { phy: 7, chip: 0, line: 269 }
+  # PIN 9 is GND
+  226: { phy: 11, chip: 0, line: 226 }
+  227: { phy: 13, chip: 0, line: 227 }
+  261: { phy: 15, chip: 0, line: 261 }
+  # PIN 17 is 3V3
+  231: { phy: 19, chip: 0, line: 231 }
+  232: { phy: 21, chip: 0, line: 232 }
+  230: { phy: 23, chip: 0, line: 230 }
+  # PIN 25 is GND
+  266: { phy: 27, chip: 0, line: 266 }
+  256: { phy: 29, chip: 0, line: 256 }
+  271: { phy: 31, chip: 0, line: 271 }
+  268: { phy: 33, chip: 0, line: 268 }
+  258: { phy: 35, chip: 0, line: 258 }
+  272: { phy: 37, chip: 0, line: 272 }
+  # PIN 39 is GND
+
+  # Right side (even numbered)
+  # PIN 2 is 5V
+  # PIN 4 is 5V
+  # PIN 6 is GND
+  224: { phy: 8, chip: 0, line: 224 }
+  225: { phy: 10, chip: 0, line: 225 }
+  257: { phy: 12, chip: 0, line: 257 }
+  # PIN 14 is GND
+  270: { phy: 16, chip: 0, line: 270 }
+  228: { phy: 18, chip: 0, line: 228 }
+  # PIN 20 is GND
+  262: { phy: 22, chip: 0, line: 262 }
+  229: { phy: 24, chip: 0, line: 229 }
+  233: { phy: 6, chip: 0, line: 233 }
+  265: { phy: 28, chip: 0, line: 265 }
+  # PIN 30 is GND
+  267: { phy: 32, chip: 0, line: 267 }
+  # PIN 34 is GND
+  76: { phy: 36, chip: 0, line: 76 }
+  260: { phy: 38, chip: 0, line: 260 }
+  259: { phy: 40, chip: 0, line: 259 }
+
+pwms:
+  #
+  # Works without overlays in /boot/dietpiEnv.txt
+  # NOTE: These DO NOT match the official Orange Pi documentation.
+  #
+  227:
+    pwmchip: 0
+    channel: 1
+  226:
+    pwmchip: 0
+    channel: 2
+
+i2cs:
+  #
+  # Add to overlays= line in /boot/dietpiEnv.txt
+  #   i2c1-pi
+  #
+  # To get 400kHz, save this alternate overlay to the /boot/dtb/allwinner/overlay directory:
+  #   https://github.com/vickash/linux-sbc-overlays/blob/master/orangepi/sun50i-h616-i2c1-pi_400k.dtbo
+  #
+  # Then, in /boot/dietpiEnv.txt, use instead:
+  #   i2c1-pi_400k
+  3:
+    scl: 263
+    sda: 264
+
+spis:
+  #
+  # Add to overlays= line in /boot/dietpiEnv.txt
+  #   spidev1_0
+  1:
+    clk: 230
+    mosi: 231
+    miso: 232
+    cs0: 229