denko-piboard 0.13.1 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. checksums.yaml +4 -4
  2. data/LICENSE +1 -1
  3. data/README.md +162 -132
  4. data/Rakefile +0 -5
  5. data/board_maps/README.md +59 -0
  6. data/board_maps/orange_pi_zero_2w.yml +85 -0
  7. data/board_maps/radxa_zero3.yml +88 -0
  8. data/board_maps/raspberry_pi.yml +95 -0
  9. data/denko_piboard.gemspec +6 -7
  10. data/examples/digital_io/bench_out.rb +22 -0
  11. data/examples/digital_io/rotary_encoder.rb +31 -0
  12. data/examples/display/ssd1306.rb +43 -0
  13. data/examples/i2c/bitbang_aht10.rb +18 -0
  14. data/examples/i2c/bitbang_search.rb +24 -0
  15. data/examples/i2c/bitbang_ssd1306_bench.rb +29 -0
  16. data/examples/i2c/search.rb +24 -0
  17. data/examples/led/blink.rb +10 -0
  18. data/examples/led/fade.rb +22 -0
  19. data/examples/led/ws2812_bounce.rb +36 -0
  20. data/examples/motor/servo.rb +16 -0
  21. data/examples/pi_system_monitor.rb +24 -13
  22. data/examples/pulse_io/buzzer.rb +34 -0
  23. data/examples/pulse_io/infrared.rb +25 -0
  24. data/examples/sensor/aht10.rb +17 -0
  25. data/examples/sensor/dht.rb +24 -0
  26. data/examples/sensor/ds18b20.rb +59 -0
  27. data/examples/sensor/hcsr04.rb +16 -0
  28. data/examples/sensor/neat_tph_readings.rb +32 -0
  29. data/examples/spi/bb_loopback.rb +31 -0
  30. data/examples/spi/loopback.rb +37 -0
  31. data/examples/spi/output_register.rb +38 -0
  32. data/lib/denko/piboard.rb +11 -2
  33. data/lib/denko/piboard_base.rb +18 -64
  34. data/lib/denko/piboard_core.rb +146 -131
  35. data/lib/denko/piboard_core_optimize_lookup.rb +31 -0
  36. data/lib/denko/piboard_hardware_pwm.rb +27 -0
  37. data/lib/denko/piboard_i2c.rb +59 -82
  38. data/lib/denko/piboard_i2c_bb.rb +48 -0
  39. data/lib/denko/piboard_infrared.rb +7 -44
  40. data/lib/denko/piboard_led_array.rb +9 -0
  41. data/lib/denko/piboard_map.rb +121 -38
  42. data/lib/denko/piboard_one_wire.rb +42 -0
  43. data/lib/denko/piboard_pulse.rb +11 -68
  44. data/lib/denko/piboard_servo.rb +8 -7
  45. data/lib/denko/piboard_spi.rb +44 -74
  46. data/lib/denko/piboard_spi_bb.rb +41 -0
  47. data/lib/denko/piboard_tone.rb +15 -26
  48. data/lib/denko/piboard_version.rb +1 -1
  49. data/scripts/99-denko.rules +9 -0
  50. data/scripts/set_permissions.rb +131 -0
  51. metadata +43 -15
  52. data/ext/gpiod/extconf.rb +0 -9
  53. data/ext/gpiod/gpiod.c +0 -179
  54. data/lib/gpiod.rb +0 -6
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 5677a479b94e8352c42dee06a389339b95fe1adcf897fa7ce871a0d7ca394aaf
4
- data.tar.gz: 355ce56cafe97d3511cd60b3cc7f91d75167b3485d06f1e162308347d11471c2
3
+ metadata.gz: 2c16debfc8c34bd8bcca26bc7bfacb260b807d795a36be181c2b9216d8c65da8
4
+ data.tar.gz: 06d80503b03ba7cc4dea13f1737d822ad8b1c8546db57da6a8dad9708232f6c6
5
5
  SHA512:
6
- metadata.gz: d9010b4a8acd2172d1f19c8c666b76c1240b79b9f9cb814d495138235433a588e35e3b3e262d95875e5baedd84f13c40274913adb882cb968bb5637fad811390
7
- data.tar.gz: 3dfc780aa00dbae71df4308f7e73aa721e5fd6cbcc4b70159206115166f21ece1827a337920fead04b6892ab7283378facaed7d0eeae450d6dfa1da0f2e7bc25
6
+ metadata.gz: 4f374de73471722936aebb24831c8bc02f7eace99ca8874ab5a6675554bb593a8b6d79b1617e80dca08e263a60858627214665dfb65f973cda19e4cb3d55a403
7
+ data.tar.gz: c1584302567d48e2f02dac57870b85cd113c8c60ce547853a83fd7945550c2aa67f095ceee1fa3987d168ac05a9456b74fca8565448a6ef61b77d9a05804e0ed
data/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2023 denko-rb
3
+ Copyright (c) 2024 denko-rb
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
data/README.md CHANGED
@@ -1,35 +1,22 @@
1
- # denko-piboard 0.13.1
1
+ # denko-piboard
2
2
 
3
- ### Raspberry Pi GPIO in Ruby
4
-
5
- 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.
6
-
7
- `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.
8
-
9
- **Note:** This is not for the Raspberry Pi Pico (W) / RP2040. That microcontroller works with the main gem.
10
-
11
- ## Example
12
- Create a script, `led_button.rb`:
3
+ Use Linux single-board-computer GPIO in Ruby.
13
4
 
14
5
  ```ruby
6
+ # Turn LED on when a button is held down, off when released.
15
7
  require 'denko/piboard'
16
8
 
17
- # Board instance for the Pi.
18
- board = Denko::PiBoard.new
19
-
20
- # LED connected to GPIO4.
21
- led = Denko::LED.new(board: board, pin: 4)
22
-
23
- # Momentary button connected to GPIO17, using internal pullup.
24
- button = Denko::DigitalIO::Button.new(board: board, pin: 17, pullup: true)
9
+ board = Denko::PiBoard.new
10
+ led = Denko::LED.new(board: board, pin: 260)
11
+ button = Denko::DigitalIO::Button.new(board: board, pin: 259, mode: :input_pullup)
25
12
 
26
- # Callback runs when button is down (0)
13
+ # Callback fires when button is down (0)
27
14
  button.down do
28
15
  puts "Button down"
29
16
  led.on
30
17
  end
31
18
 
32
- # Callback runs when button is up (1)
19
+ # Callback fires when button is up (1)
33
20
  button.up do
34
21
  puts "Button up"
35
22
  led.off
@@ -39,135 +26,178 @@ end
39
26
  sleep
40
27
  ```
41
28
 
42
- Run it:
43
- ```shell
44
- ruby led_button.rb
29
+ ## Linux GPIO Features
30
+ - [x] Internal Pull-Up/Down
31
+ - [x] Open Drain/Source
32
+ - [x] Digital Read/Write
33
+ - [x] Digital Listen (Alerts)
34
+ - Interrupt driven, unlike `denko` microcontroller implementation 1ms polling
35
+ - Built in software debounce (1us by default)
36
+ - Alerts are read from a FIFO queue up to 65,536. Oldest alerts are lost first.
37
+ - [ ] Analog Read (ADC)
38
+ - [ ] Analog Write (DAC)
39
+ - [x] Software PWM Out (any pin)
40
+ - [x] Hardware PWM Out (specific pins per board)
41
+ - [x] Tone Out (via Software PWM or Hardware PWM)
42
+ - [x] Servo (via Hardware PWM)
43
+ - [x] Infrared Out (via Hardware PWM)
44
+ - [x] Hardware I2C
45
+ - [x] Multiple interfaces
46
+ - [x] Hardware SPI
47
+ - [x] Multiple interfaces
48
+ - [x] WS2812 addressable LED via SPI MOSI
49
+ - [ ] SPI Listeners from `denko`
50
+ - [ ] UART
51
+ - [x] Ultrasonic Input (for HC-SR04 and similar)
52
+ - [x] Pulse Sequence Input (for DHT enviro sensors and similar)
53
+ - [x] Bit-Bang I2C
54
+ - [x] Bit-Bang SPI
55
+ - [x] Bit-Bang 1-Wire
56
+
57
+ ## Support
58
+
59
+ #### Hardware
60
+
61
+ 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.
62
+
63
+ :green_heart: Known working
64
+ :heart: Awaiting testing
65
+ :question: Might work. No hardware
66
+
67
+ | Chip | Status | Products | Notes |
68
+ | :-------- | :------: | :---------------------- |------ |
69
+ | Allwinner H618 | :green_heart: | Orange Pi Zero 2W | DietPi
70
+ | Rockchip RK3566 | :green_heart: | Radxa Zero 3W/E, Radxa Rock 3C | Armbian
71
+ | BCM2835 | :green_heart: | Raspberry Pi 1, Raspberry Pi Zero (W) | Raspberry Pi OS
72
+ | BCM2836/7 | :question: | Raspberry Pi 2 |
73
+ | BCM2837A0/B0 | :green_heart: | Raspberry Pi 3 | Raspberry Pi OS
74
+ | BCM2711 | :green_heart: | Raspberry Pi 4, Raspberry Pi 400 | Raspberry Pi OS
75
+ | BCM2710A1 | :green_heart: | Raspberry Pi Zero 2W | Raspberry Pi OS
76
+ | BCM2712 | :question: | Raspberry Pi 5 |
77
+
78
+ #### Software
79
+
80
+ - Operating Systems:
81
+ - DietPi (Bookworm)
82
+ - Amrbian (Bookworm)
83
+ - Raspberry Pi OS (Bookworm)
84
+
85
+ - Rubies:
86
+ - Ruby 3.3.5 +YJIT
87
+
88
+ ## Install
89
+
90
+ #### Install the lg C library
91
+ ```console
92
+ # Requirements to install lgpio C
93
+ sudo apt install swig python3-dev python3-setuptools gcc make
94
+
95
+ # Temporary fork of: wget https://github.com/joan2937/lg
96
+ wget https://github.com/vickash/lg/archive/refs/heads/master.zip
97
+
98
+ # Install lgpio C
99
+ unzip master.zip
100
+ cd lg-master
101
+ make
102
+ sudo make install
45
103
  ```
46
104
 
47
- #### More Examples
48
- Pi-specific examples will be in this gem's [examples](examples) folder, but most examples are in the [main gem](https://github.com/denko-rb/denko/tree/master/examples). They must be modified to work with the Pi's GPIO:
105
+ #### Install the denko-piboard gem
106
+ ```console
107
+ # Latest Ruby + YJIT from rbenv works best, but Ruby 3 from apt works too.
108
+ # Install system Ruby anyway to automate permissions startup script.
109
+ sudo apt install ruby ruby-dev
49
110
 
50
- 1. Replace setup code:
51
- ```ruby
52
- # Replace this:
53
- require 'bundler/setup'
54
- require 'denko'
55
- # With this:
56
- require 'denko/piboard'
111
+ sudo gem install denko-piboard
112
+ ```
113
+ **Note:** `sudo` may be needed before `gem install` if using the system Ruby.
57
114
 
58
- # Replace this:
59
- connection = Denko::Connection::Serial.new()
60
- board = Denko::Board.new()
61
- # With this:
62
- board = Denko::PiBoard.new
63
- ```
115
+ ## Enable Hardware
64
116
 
65
- 2. Update GPIO/pin numbers as needed. Raspberry Pi pinouts can be found [here](https://pinout.xyz/).
66
-
67
- **Note:** Not all features from all examples are implemented yet, nor can be implemented. See [Features](#features) below.
117
+ **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).
68
118
 
69
- ## Installation
119
+ ### Orange Pi Zero 2W
120
+ - For DietPi OS specifically
121
+ - 2 PWMs on GPIO 226 and 227 (not matching the docs) are enabled without any setup.
122
+ - Save the [default map](board_maps/orange_pi_zero_2w.yml) as `~/.denko_piboard_map.yml` on your Zero2W.
123
+ - Add/edit the lines below in `/boot/dietpiEnv.txt`, and reboot.
70
124
 
71
- #### System Requirements
72
- - Tested on a Pi Zero W and Pi 3B, but should work on others.
73
- - Tested on DietPi and Raspberry Pi OS, both based on Debian 11 (Bullseye), with kernel version 6.1 or higher.
74
- - Tested Ruby versions:
75
- - Ruby 2.7.4 (incldued with OS)
76
- - Ruby 3.2.2+YJIT
77
- - TruffleRuby 22.3.1 :man_shrugging: (Not available on ARMv6 Pis: Zero W, Pi 1. Not recommended in general)
125
+ ```
126
+ # /dev/i2c-3 (I2C3) @ 100 kHz
127
+ # /dev/spidev1.0 (SPI1) with first chip select (CS0) enabled
128
+ overlay_prefix=sun50i-h616
129
+ overlays=i2c1-pi spidev1_0
130
+ ```
78
131
 
79
- #### Dependencies
80
- This gem depends on [pigpio](https://github.com/joan2937/pigpio), the [pigpio gem](https://github.com/nak1114/ruby-extension-pigpio) to provide Ruby bindings, and [libgpiod](https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git).
132
+ ### Radxa Zero3W/E
133
+ - For Armbian OS specifically. Newer and performs better than latest Radxa OS or DietPi available.
134
+ - Unfortunately, Armbian does not package all device tree overlays for the RK3566. I built binaries for this default config, on kernel `6.6.31-current-sunxi64`, 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.
81
135
 
82
- #### 1. Install pigpio and libgpiod packages
83
- ```shell
84
- sudo apt install pigpio libgpiod-dev
136
+ If you rather build the overlays yourself, that repo contains the script too. On the Zero3:
137
+ ```console
138
+ sudo apt install device-tree-compiler
139
+ ruby rk3568_denko_overlay_install.rb
85
140
  ```
86
141
 
87
- #### 2. Install pigpio gem
88
- A bug in the current `pigpio` gem release prevents it from installing on Ruby 3.2+. You can safely ignore this step if using a lower Ruby version, or install it from [this fork](https://github.com/vickash/ruby-extension-pigpio) until fixes are merged and released:
89
- ```shell
90
- git clone https://github.com/denko-rb/ruby-extension-pigpio.git
91
- cd ruby-extension-pigpio
92
- gem build
93
- gem install ruby-extension-pigpio-0.1.11.gem
94
- ```
142
+ - Save the [default map](board_maps/radxa_zero3.yml) as `~/.denko_piboard_map.yml` on your Zero3.
143
+ - Add/edit the lines below in `/boot/armbianEnv.txt`, and reboot.
95
144
 
96
- #### 3. Install denko-piboard gem
97
- ```shell
98
- gem install denko-piboard
99
145
  ```
100
- This will automatically install the main `denko` gem and any other dependencies.
101
-
102
- **Note:** `sudo` may be needed before `gem install` if using the preinstalled Ruby on a Pi.
146
+ # /dev/i2c-3 (I2C3) @ 100 kHz
147
+ # /dev/spidev3.0 (SPI3) with first chip select (CS0) enabled
148
+ # 2 PWMs on GPIO 105 and 106
149
+ overlay_prefix=rk3568
150
+ overlays=i2c3-m0 spi3-m1-cs0-spidev pwm8-m0 pwm9-m0
151
+ ```
103
152
 
104
- ## Pi Setup
153
+ **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.
105
154
 
106
- #### pigpiod
107
- The `pigpio` package installs `pigpiod`, which needs to be running 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:
108
- ```shell
109
- sudo pigpiod -s 10
110
- ```
111
- **Note:** `-s 10` sets tick interval to 10 microseconds, lowering CPU use. Valid values are: 1, 2, 4, 5, 8, 10 (5 default).
155
+ ### Raspberry Pi 4 and Lower
156
+ - For Raspberry Pi OS specifically
157
+ - Save the [default map](board_maps/raspberry_pi.yml) as `~/.denko_piboard_map.yml` on your Raspberry Pi.
158
+ - Add the lines below to `/boot/config.txt`, and reboot.
112
159
 
113
- #### libgpiod
114
- Depending on your Pi and OS, `libgpiod` may limit GPIO access. If this is the case, some scripts will fail with a `libgpiod` error. It is only used for low-level digital read/write operations, so check using a simple script like blinking an LED. To get `libgpiod` permission, add your user account to the `gpio` group:
115
160
  ```
116
- sudo usermod -a -G gpio $(whoami)
161
+ # 2 PWMS on GPIO 12 and 13
162
+ dtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4
163
+ # /dev/i2c-1 (I2C1) @ 400 kHz
164
+ dtparam=i2c_arm=on
165
+ dtparam=i2c_arm_baudrate=400000
166
+ # /dev/spidev0.0 (SPI0) with first chip select (CS0) enabled
167
+ dtoverlay=spi0-1cs
117
168
  ```
118
169
 
119
- #### Features
120
- I2C, SPI and the hardware UART may be disabled on the Pi by default. Enable them with the built-in utility:
121
- ```shell
122
- # On Raspberry Pi OS:
123
- sudo raspi-config
170
+ ## Get Permissions
171
+ 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:
124
172
 
125
- # On DietPi:
126
- sudo dietpi-config
173
+ ```console
174
+ ruby set_permissions.rb
127
175
  ```
128
- Select "Interfacing Options" (Raspberry Pi OS), or "Advanced Options" (DietPi) and enable features as needed.
129
-
130
- ## Features
131
-
132
- ### Already Implemented
133
- - Internal Pull Down/Up
134
- - Digital Out
135
- - Digital In
136
- - Listeners are polled in a thread, similar to a microcontroller, but always at 1ms.
137
- - `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.
138
- - PWM Out
139
- - Servo
140
- - Tone Out
141
- - Infrared Out
142
- - DHT Class Temperature + Humidity Sensors
143
- - I2C
144
- - Always uses I2C1 interface.
145
- - Must enable before use. Instructions [here](https://learn.adafruit.com/adafruits-raspberry-pi-lesson-4-gpio-setup/configuring-i2c).
146
- - 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/).
147
-
148
- ### Partially Implemented
149
- - SPI
150
- - Always uses SPI1 interface.
151
- - Must enable before use. Instructions [here](https://learn.adafruit.com/adafruits-raspberry-pi-lesson-4-gpio-setup/configuring-spi).
152
- - Does not bind CE pins according to GPIO pinout. Any pin can be used for chip enable.
153
- - SPI modes 1 and 3 may not work.
154
- - No listeners yet.
155
-
156
- ### Feature Exclusivity
157
- - PWM Out / Servo Out
158
- - Using either of these on **any** pin disables the Pi's PCM audio output globally.
159
-
160
- - Tone Out / Infrared Out
161
- - 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.
162
-
163
- ### To Be Implemented
164
- - OneWire
165
- - Hardware UART
166
- - BitBang I2C
167
- - BitBang SPI
168
- - BitBang UART
169
- - WS2812
170
-
171
- ### Incompatible
172
- - EEPROM (Use the filesystem for persistence instead)
173
- - Analog IO (No analog pins on Raspberry Pi. Use ADC or DAC over I2C or SPI)
176
+
177
+ It will load load the default board map, then:
178
+ - Create any necessary Linux groups
179
+ - Add your user to the relevant groups
180
+ - Change ownership and permissions for devices in the map, so you can read/write them
181
+
182
+ **Note:** `sudo` is required.
183
+
184
+ **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.
185
+
186
+ ## Modifying Examples From Main Gem
187
+ 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`:
188
+
189
+ 1. Replace setup code:
190
+ ```ruby
191
+ # Replace this:
192
+ require 'bundler/setup'
193
+ require 'denko'
194
+ # With this:
195
+ require 'denko/piboard'
196
+
197
+ # Replace this:
198
+ board = Denko::Board.new(Denko::Connection::Serial.new)
199
+ # With this:
200
+ board = Denko::PiBoard.new
201
+ ```
202
+
203
+ 2. Change pin numbers and I2C/SPI device indices as needed.
data/Rakefile CHANGED
@@ -1,5 +0,0 @@
1
- require "rake/extensiontask"
2
-
3
- Rake::ExtensionTask.new "gpiod" do |ext|
4
- ext.lib_dir = "lib/gpiod"
5
- end
@@ -0,0 +1,59 @@
1
+ # Creating Custom Board Maps
2
+
3
+ You will need:
4
+ - Your SBC, running a recent (5.10 kernel or later) Linux distribution
5
+ - A working understanding of how to enable/disable device tree overlays in Linux
6
+ - Documentation for your board, specifically:
7
+ - Its pinout, with "friendly" GPIO numbers
8
+ - Which GPIO numbers correspond to which device tree overlays
9
+
10
+ ## Overlays
11
+
12
+ 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.
13
+
14
+ This happens at boot, so there are side-effects:
15
+ - Pins reserved by I2C or SPI can't be used for GPIO, unless the interface is disabled, and the SBC rebooted.
16
+ - With some asbraction tricks, a PWM can work as a regular GPIO, but **for digital output only**, and it's slower.
17
+ - I2C frequency can only be changed at boot time, not on a per-transmission basis.
18
+
19
+ There are a couple other issues too:
20
+ - One SoC may have GPIOs on multiple `/dev/gpiochip*`s, with non-unque line numbers.
21
+ - PWM is called by its `pwmchip*` and `pwm*` channel, not GPIO number.
22
+ - I2C and SPI are called by index (N) from `/dev/i2c-N` or `/dev/spidev-N.0`, not GPIO numbers.
23
+
24
+ To deal with this complexity, and standardize the user interface, denko-piboard uses board maps.
25
+
26
+ ## Board Maps
27
+
28
+ A board map is a YAML file, defining all the GPIO, PWM, I2C and SPI resources enabled on the SBC.
29
+
30
+ It follows these conventons:
31
+ - `Denko::PiBoard.new` will raise unless it finds a board map
32
+ - It accepts a board map file path as its only argument
33
+ - If that isn't given, it looks for `.denko_piboard_map.yml`, in the user's home directory.
34
+ - In the map, individual GPIOs are referred to (keyed by) their "friendly" or human-readable" numbers
35
+ - Theoretically arbitrary, but rule of thumb is: "unique numbers from the SBC's documentation"
36
+ - These are NOT physical pin numbers from the pinout
37
+ - These might match, but are NOT necessarily `/dev/gpiochip*` line numbers. Those can be non-unique, if multiple gpiochips.
38
+ - Each GPIO number declares its:
39
+ - Linux gpiochip
40
+ - Line on that gpiochip
41
+ - Physical number on the SBC's pinout (optional)
42
+ - Each PWM declares:
43
+ - Which GPIO number it reserves when enabled (this is its key)
44
+ - Its Linux pwmchip
45
+ - Its pwm channel on that chip
46
+ - Each I2C or SPI interface declares:
47
+ - Its index, N from `/dev/i2c-N` or `/dev/spidev-N.0` (this is its key)
48
+ - All the GPIO numbers it reserves, keyed to their names. Eg. `miso:`, `sda:` etc.
49
+
50
+ This information enables denko-piboard to:
51
+ - Refer to GPIOs by a single, user-friendly, unique number (rather than a tuple of gpiochip and line)
52
+ - Refer to PWMs by the GPIO number they multiplex with (rather than a tuple of pwmchip and channel)
53
+ - Refer to I2C and SPI by their Linux device indices
54
+ - Raise errors if you try to use any reserved pin. This fails silently otherwise, which is confusing.
55
+
56
+ There are pre-made maps for some boards [here](board_maps), which can be followed as templates. In general, these enable:
57
+ - 2 PWM pins
58
+ - 1 I2C interface (on physical pins 3,5 when possible)
59
+ - 1 SPI interface (on physical pins 19,21,23 when possible)
@@ -0,0 +1,85 @@
1
+ #
2
+ # Tested on Orange Pi Zero 2W, running DietPi, Kernel 6.6.31-current-sunxi64
3
+ # Note: PWM channels 1 and 2 work without an overlay.
4
+ #
5
+ ---
6
+ pins:
7
+ # Left side (odd numbered)
8
+ # PIN 1 is 3V3
9
+ 264: { phy: 3, chip: 0, line: 264 }
10
+ 263: { phy: 5, chip: 0, line: 263 }
11
+ 269: { phy: 7, chip: 0, line: 269 }
12
+ # PIN 9 is GND
13
+ 226: { phy: 11, chip: 0, line: 226 }
14
+ 227: { phy: 13, chip: 0, line: 227 }
15
+ 261: { phy: 15, chip: 0, line: 261 }
16
+ # PIN 17 is 3V3
17
+ 231: { phy: 19, chip: 0, line: 231 }
18
+ 232: { phy: 21, chip: 0, line: 232 }
19
+ 230: { phy: 23, chip: 0, line: 230 }
20
+ # PIN 25 is GND
21
+ 266: { phy: 27, chip: 0, line: 266 }
22
+ 256: { phy: 29, chip: 0, line: 256 }
23
+ 271: { phy: 31, chip: 0, line: 271 }
24
+ 268: { phy: 33, chip: 0, line: 268 }
25
+ 258: { phy: 35, chip: 0, line: 258 }
26
+ 272: { phy: 37, chip: 0, line: 272 }
27
+ # PIN 39 is GND
28
+
29
+ # Right side (even numbered)
30
+ # PIN 2 is 5V
31
+ # PIN 4 is 5V
32
+ # PIN 6 is GND
33
+ 224: { phy: 8, chip: 0, line: 224 }
34
+ 225: { phy: 10, chip: 0, line: 225 }
35
+ 257: { phy: 12, chip: 0, line: 257 }
36
+ # PIN 14 is GND
37
+ 270: { phy: 16, chip: 0, line: 270 }
38
+ 228: { phy: 18, chip: 0, line: 228 }
39
+ # PIN 20 is GND
40
+ 262: { phy: 22, chip: 0, line: 262 }
41
+ 229: { phy: 24, chip: 0, line: 229 }
42
+ 233: { phy: 6, chip: 0, line: 233 }
43
+ 265: { phy: 28, chip: 0, line: 265 }
44
+ # PIN 30 is GND
45
+ 267: { phy: 32, chip: 0, line: 267 }
46
+ # PIN 34 is GND
47
+ 76: { phy: 36, chip: 0, line: 76 }
48
+ 260: { phy: 38, chip: 0, line: 260 }
49
+ 259: { phy: 40, chip: 0, line: 259 }
50
+
51
+ pwms:
52
+ #
53
+ # Works without overlays in /boot/dietpiEnv.txt
54
+ # NOTE: These DO NOT match the official Orange Pi documentation.
55
+ #
56
+ 227:
57
+ pwmchip: 0
58
+ channel: 1
59
+ 226:
60
+ pwmchip: 0
61
+ channel: 2
62
+
63
+ i2cs:
64
+ #
65
+ # Add to overlays= line in /boot/dietpiEnv.txt
66
+ # i2c1-pi
67
+ #
68
+ # To get 400kHz, save this alternate overlay to the /boot/dtb/allwinner/overlay directory:
69
+ # https://github.com/vickash/linux-sbc-overlays/blob/master/orangepi/sun50i-h616-i2c1-pi_400k.dtbo
70
+ #
71
+ # Then, in /boot/dietpiEnv.txt, use instead:
72
+ # i2c1-pi_400k
73
+ 3:
74
+ scl: 263
75
+ sda: 264
76
+
77
+ spis:
78
+ #
79
+ # Add to overlays= line in /boot/dietpiEnv.txt
80
+ # spidev1_0
81
+ 1:
82
+ clk: 230
83
+ mosi: 231
84
+ miso: 232
85
+ cs0: 229
@@ -0,0 +1,88 @@
1
+ #
2
+ # Tested on Radxa Zero 3W, running Armbian, Kernel 6.1.75-vendor-rk35xx
3
+ #
4
+ # Note: Overlays are not packaged with Armbian for some reason. Hopefully this changes soon,
5
+ # but I've built the .dtbo files for the kernel given above, and made them available here:
6
+ # https://github.com/vickash/linux-sbc-overlays/tree/master/radxa/rockchip
7
+ # To use them, save all the .dtbo files into:
8
+ # /boot/dtb/rockchip/overlay
9
+ #
10
+ ---
11
+ pins:
12
+ # Left side (odd numbered)
13
+ # PIN 1 is 3V3
14
+ 32: { phy: 3, chip: 1, line: 0 }
15
+ 33: { phy: 5, chip: 1, line: 1 }
16
+ 116: { phy: 7, chip: 3, line: 20 }
17
+ # PIN 9 is GND
18
+ 97: { phy: 11, chip: 3, line: 1 }
19
+ 98: { phy: 13, chip: 3, line: 2 }
20
+ 104: { phy: 15, chip: 3, line: 8 }
21
+ # PIN 17 is 3V3
22
+ 147: { phy: 19, chip: 4, line: 19 }
23
+ 149: { phy: 21, chip: 4, line: 21 }
24
+ 146: { phy: 23, chip: 4, line: 18 }
25
+ # PIN 25 is GND
26
+ 138: { phy: 27, chip: 4, line: 10 }
27
+ 107: { phy: 29, chip: 3, line: 11 }
28
+ 108: { phy: 31, chip: 3, line: 12 }
29
+ 115: { phy: 33, chip: 3, line: 19 }
30
+ 100: { phy: 35, chip: 3, line: 4 }
31
+ 36: { phy: 37, chip: 1, line: 4 }
32
+ # PIN 39 is GND
33
+
34
+ # Right side (even numbered)
35
+ # PIN 2 is 5V
36
+ # PIN 4 is 5V
37
+ # PIN 6 is GND
38
+ 24: { phy: 8, chip: 0, line: 24 }
39
+ 25: { phy: 10, chip: 0, line: 25 }
40
+ 99: { phy: 12, chip: 3, line: 3 }
41
+ # PIN 14 is GND
42
+ 105: { phy: 16, chip: 3, line: 9 }
43
+ 106: { phy: 18, chip: 3, line: 10 }
44
+ # PIN 20 is GND
45
+ 113: { phy: 22, chip: 3, line: 17 }
46
+ 150: { phy: 24, chip: 4, line: 22 }
47
+ # PIN 26 is NC
48
+ 139: { phy: 28, chip: 4, line: 11 }
49
+ # PIN 30 is GND
50
+ 114: { phy: 32, chip: 3, line: 18 }
51
+ # PIN 34 is GND
52
+ 103: { phy: 36, chip: 3, line: 7 }
53
+ 102: { phy: 38, chip: 3, line: 6 }
54
+ 101: { phy: 40, chip: 3, line: 5 }
55
+
56
+ pwms:
57
+ #
58
+ # Add to overlays= line in /boot/amrbianEnv.txt
59
+ # pwm8-m0 pwm9-m0
60
+ 105:
61
+ pwmchip: 0
62
+ channel: 0
63
+ overlay: pwm8-m0
64
+ 106:
65
+ pwmchip: 1
66
+ channel: 0
67
+ overlay: pwm9-m0
68
+
69
+ i2cs:
70
+ #
71
+ # Add to overlays= line in /boot/amrbianEnv.txt
72
+ # i2c3-m0
73
+ 3:
74
+ scl: 33
75
+ sda: 32
76
+ reserved_addresses: [0x22]
77
+ overlay: i2c3-m0
78
+
79
+ spis:
80
+ #
81
+ # Add to overlays= line in /boot/amrbianEnv.txt
82
+ # ispi3-m1-cs0-spidev
83
+ 3:
84
+ clk: 146
85
+ mosi: 147
86
+ miso: 149
87
+ cs0: 150
88
+ overlay: spi3-m1-cs0-spidev