lgpio 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 984afd62543a10d3fc0b6d2a9a581b05b4d9bf7c159d2747f990b2247b59aef1
-  data.tar.gz: d2431adb24613fdd42b9f9f06a428c399fe48be2e215a13463237a798113630c
+  metadata.gz: 175af29acc6f0bb362dc017458e1ca9948f5d0c73ac0693f4a06b2e4e64f2842
+  data.tar.gz: c7eebe2b025a40e98c3e7fc7574eb1f7572e7c147a88a32d7b4a9bfdb0cb0882
 SHA512:
-  metadata.gz: f32ceb3af8218d26f1f5713302a9891365af498fe76e2a750037f2ae10a437b747b40167e9fd9c5170fc28696d90c9244ce5d9a36269eba0d0c827a79be47fcd
-  data.tar.gz: b167ef512729754b46dd3cd14750dd715c8541987014a254465c72619f1ead5d4ae8ff74bcbb6c9122b331c5f65a159e0f0c9890f9e0ad7a5b582dafe2763e54
+  metadata.gz: e3f5bfc169dfeb319fdfc06c4de1058682e9bee1f547a9eebecc1eb9ad2d50403bda912a67aef171e66b828d22740b04925b83c0e3494204c73c0b32dbbe7931
+  data.tar.gz: f3d17767bf96c7af4631945ac0a7812628698cb483634fc0c1a45513a8ac5107bc613799be32b95b2c4b251e51a4c95c253f107691767d5351b8b1e073f5d965

data/README.md

@@ -1,39 +1,52 @@
 # lgpio
 
-Ruby bindings for the [lgpio (lg)](https://github.com/joan2937/lg) Linux library, running on single board computers (SBCs), like Raspberry Pi.
+Ruby gem with bindings for the [lgpio (lg)](https://github.com/joan2937/lg) C library. This is for single-board-computers (SBCs) running Linux, such as Orange Pi, Raspberry Pi, etc. It provides low-level access to the GPIO, I2C, SPI, and PWM subsytems.
+
+## Standard LGPIO Features
 
-## Mapped LGPIO Features
 - [x] GPIO Read/Write
 - [x] GPIO Group Read/Write
-- [x] GPIO Alerts / Callbacks
-  - lg generates alerts at high speed in a separate thread. You can read them from a queue in Ruby, as part of your application loop.
-- [x] Software PWM Out
-  - Software timed (not 100% precise), on any pin
-  - Not recommended for servo motors
+- [x] GPIO Alerts
+  - Alerts are generated by a separate thread, and can be read from a queue in Ruby.
+  - No real "callback" functionality.
+- [x] Software PWM Output
+  - Timing not 100% precise, but works on any GPIO.
+  - Not recommended for servo motors, will jitter.
 - [x] Wave
-  - Software timed on any pin, as with PWM.
-- [x] I2C
-- [x] SPI
+  - Software timed on any pin(s), as with PWM.
+- [x] Hardware I2C
+- [x] Hardware SPI
+
+## Extra Features (Built on LGPIO)
+
+- [x] `LGPIO.gpio_read_ultrasonic` sends a pulse on a `trigger` pin, then measures a single pulse on a separate `echo` pin. Used for HC-SR04 or similar. See `examples/hcsr04.rb`.
+- [x] `LGPIO.gpio_read_pulses_us` outputs a reset pulse on a pin, then polls for a sequence of input pulses. Used for DHT enviro sensors or similar. See `examples/dht.rb`.
+- [x] Bit Bang I2C
+- [x] Bit Bang SPI
+- [x] Bit Bang 1-Wire
+- [x] WS2812 addressable LEDs over hardware SPI
+  - Outputs on MOSI/PICO pin
+  - Must be able to set SPI clock frequency to 2.4 MHz
+
+## Hardware PWM Features
+
+These use the sysfs PWM interface, not lgpio C, but are a good fit for this gem.
 
-## Extra Features, based on LGPIO
-- [x] WS2812 over SPI
-  - Only outputs on a SPI MOSI pin. Must be able to set SPI clock frequency to 2.4 MHz.
-- [ ] Bit Bang SPI
-- [ ] Bit Bang I2C
+- [x] Hardware PWM Output
+- [x] Servo (based on hardware PWM)
+- [x] On-off Keying (OOK) Modulated Waves
+  - Carrier generated by hardware PWM. Software modulated with monotonic clock timing.
+  - Useful for sending infrared signals at 38kHz, for example.
 
-## Sysfs PWM Interface Features
-- [x] Hardware PWM Out (specific pins per chip)
-- [x] Servo
+**Note:** Once hardware PWM is used on a pin, it stays PWM until reboot. The associated GPIO won't work.
 
 ## Installation
 On Debian-based Linuxes (RaspberryPi OS, Armbian, DietPi etc.):
 ```bash
 sudo apt install swig python3-dev python3-setuptools
 
-# NOTE: There's a bug with GPIO numbers > 255.
-# If you need to use those, wget the second URL instead, until that fix is merged.
-wget https://github.com/joan2937/lg/archive/master.zip
-# wget https://github.com/vickash/lg/archive/refs/heads/master.zip
+# Temporary fork of: wget https://github.com/joan2937/lg/archive/master.zip
+wget https://github.com/vickash/lg/archive/refs/heads/master.zip
 
 unzip master.zip
 cd lg-master
@@ -44,17 +57,18 @@ gem install lgpio
 ```
 
 ## Enabling Hardware & Permissions
-Depending on your SBC and Linux distro/version, you may need to manually enable I2C and SPI hardware. You should use the setup or config tool that came with your distro for that.
+Depending on your SBC and Linux distro/version, you may need to manually enable hardware I2C, SPI, and PWM. You should use the config tool that came with your distro for that, if possible.
 
-You may also not have permission to access the GPIO and peripherals. To run without `sudo`, you need read+write permission to some or all of the following devices:
+Even when these are enabled, you may not have permission to access them. To run without `sudo`, you need read+write permission to some or all of the following:
 ```
-/dev/gpiochip* (For GPIO, example: /dev/gpiochip0)
-/dev/i2c-*     (For I2C,  example: /dev/i2c-1)
-/dev/spidev*   (For SPI,  example: /dev/spidev-0.1)
+/dev/gpiochip*          (For GPIO, example: /dev/gpiochip0)
+/dev/i2c-*              (For I2C,  example: /dev/i2c-1)
+/dev/spidev*            (For SPI,  example: /dev/spidev0.1)
+/sys/class/pwm/pwmchip* (For PWM,  example: /sys/class/pwm/pwmchip0)
 ```
 
 ## Documentation
-- See examples folder for demos of every implemented interface.
+- See examples folder for demos of everything implemented.
   - Development was done on an Orange Pi Zero 2W. Your GPIO numbers may be different, so change them.
 - For more info, see the [lgpio C API docs.](https://abyz.me.uk/lg/lgpio.html)
 - As much as possible, the Ruby methods closely follow the C API functions, except:

data/examples/dht.rb

@@ -0,0 +1,47 @@
+require 'lgpio'
+
+GPIO_CHIP = 0
+DHT_PIN   = 267
+chip_handle = LGPIO.chip_open(GPIO_CHIP)
+#
+# Read a series of pulses input to a GPIO, with an (optional) reset output pulse at start.
+# Arguments in order are:
+#   gpiochip handle
+#   GPIO number
+#   Starting (reset) output pulse time in microseconds (0 for no reset)
+#   Reset pulse level (0 or 1)
+#   Maximum number of pulses to read
+#   Timeout in milliseconds
+#
+data = LGPIO.gpio_read_pulses_us(chip_handle, DHT_PIN, 20_000, 0, 84, 100)
+
+# Handle errors.
+raise "error: DHT sensor not connected" unless data
+raise "LGPIO error: #{data}" if data.class == Integer
+
+# Discard unneeded pulses
+data = data.last(81)
+raise "error: incomplete DHT data" unless data.length == 81
+data = data.first(80)
+
+# Convert to bytes
+bytes = []
+data.each_slice(16) do |b|
+  byte = 0b00000000
+  b.each_slice(2) do |x,y|
+    bit = (y<x) ? 0 : 1
+    byte = (byte << 1) | bit
+  end
+  bytes << byte
+end
+
+# CRC
+crc = bytes[0..3].reduce(0, :+) & 0xFF == bytes[4]
+raise "error: DHT CRC check failed" unless crc
+
+# Convert and display
+temperature = ((bytes[2] << 8) | bytes[3]).to_f / 10
+humidity    = ((bytes[0] << 8) | bytes[1]).to_f / 10
+
+puts "DHT Temperature: #{temperature} \xC2\xB0C"
+puts "DHT Humidity:    #{humidity}  %"

data/examples/{bench_in.rb → gpio_bench_in.rb}

@@ -1,7 +1,7 @@
 require 'lgpio'
 
 GPIO_CHIP = 0
-PIN       = 258
+PIN       = 260
 COUNT     = 1000000
 
 chip_handle = LGPIO.chip_open(GPIO_CHIP)

data/examples/{bench_out.rb → gpio_bench_out.rb}

@@ -1,7 +1,7 @@
 require 'lgpio'
 
 GPIO_CHIP = 0
-PIN       = 260
+PIN       = 272
 COUNT     = 1000000
 
 chip_handle = LGPIO.chip_open(GPIO_CHIP)

data/examples/{blink.rb → gpio_blink.rb}

@@ -1,7 +1,7 @@
 require 'lgpio'
 
 GPIO_CHIP = 0
-LED       = 260
+LED       = 272
 INTERVAL  = 0.25
 
 chip_handle = LGPIO.chip_open(GPIO_CHIP)

data/examples/{group_in.rb → gpio_group_in.rb}

@@ -2,8 +2,8 @@
 require 'lgpio'
 
 GPIO_CHIP   = 0
-BUTTONS     = [258, 256]
-LEDS        = [260, 267]
+BUTTONS     = [259, 267]
+LEDS        = [272, 258]
 INIT_STATE  = [0, 0]
 
 chip_handle = LGPIO.chip_open(GPIO_CHIP)

data/examples/{group_out.rb → gpio_group_out.rb}

@@ -1,7 +1,7 @@
 require 'lgpio'
 
 GPIO_CHIP   = 0
-LEDS        = [260, 267]
+LEDS        = [272, 258]
 INIT_STATE  = [0, 0]
 INTERVAL    = 250_000 # 250ms
 TIMES       = 10

data/examples/{momentary.rb → gpio_momentary.rb}

@@ -1,8 +1,8 @@
 require 'lgpio'
 
 GPIO_CHIP = 0
-BUTTON    = 258
-LED       = 260
+BUTTON    = 259
+LED       = 272
 
 chip_handle = LGPIO.chip_open(GPIO_CHIP)
 LGPIO.gpio_claim_input(chip_handle, LGPIO::SET_PULL_UP, BUTTON)

data/examples/{reports.rb → gpio_reports.rb}

@@ -1,7 +1,7 @@
 require 'lgpio'
 
 GPIO_CHIP = 0
-PIN       = 76
+PIN       = 259
 
 chip_handle = LGPIO.chip_open(GPIO_CHIP)
 

data/examples/{rotary_encoder.rb → gpio_rotary_encoder.rb}

@@ -5,9 +5,9 @@
 require 'lgpio'
 
 GPIO_CHIP = 0
-PIN_A     = 76
-PIN_B     = 228
-PIN_SW    = 226
+PIN_A     = 260
+PIN_B     = 76
+PIN_SW    = 259
 
 # Encoder state
 position = 0

data/examples/{rotary_encoder_led.rb → gpio_rotary_encoder_led.rb}

@@ -5,10 +5,10 @@
 require 'lgpio'
 
 GPIO_CHIP = 0
-PIN_A     = 76
-PIN_B     = 228
+PIN_A     = 260
+PIN_B     = 76
 
-PIN_LED     = 260
+PIN_LED     = 272
 PWM_FREQ    = 500
 PWM_OFFSET  = 0
 PWM_CYCLES  = 0    # 0 = infinite
@@ -44,7 +44,7 @@ loop do
     elsif report[:gpio] == PIN_B
       delta = (report[:level] == state_a) ? -1 : 1
       state_b = report[:level]
-      
+
       led_duty += delta
       led_duty = 0 if led_duty < 0
       led_duty = 100 if led_duty > 100

data/examples/{wave.rb → gpio_wave.rb}

@@ -1,7 +1,7 @@
 require 'lgpio'
 
 GPIO_CHIP   = 0
-LEDS        = [260, 267]
+LEDS        = [272, 258]
 INIT_STATE  = [0, 0]
 INTERVAL    = 250_000 # 250ms
 TIMES       = 10

data/examples/hcsr04.rb

@@ -0,0 +1,32 @@
+#
+# Example showing an HC-S04 ultrasonic distance sensor.
+#
+# NOTE: Some versions of this sensor require 5V power to function properly.
+# If using one of these, use a 5V to 3.3V level shifter between your board and
+# the sensor, at least on the echo pin.
+#
+require 'lgpio'
+
+GPIO_CHIP       = 0
+ECHO_PIN        = 228
+TRIGGER_PIN     = 270
+SPEED_OF_SOUND  = 343.0
+
+chip_handle = LGPIO.chip_open(GPIO_CHIP)
+
+loop do
+  # Arguments in order are:
+  #   chip handle, trigger pin, echo pin, trigger time (us)
+  #
+  # HC-SR04 uses 10 microseconds for trigger. Some others use 20us.
+  #
+  microseconds = LGPIO.gpio_read_ultrasonic(chip_handle, TRIGGER_PIN, ECHO_PIN, 10)
+
+  if microseconds
+    mm = (microseconds / 2000.0) * SPEED_OF_SOUND
+    puts "Distance: #{mm.round} mm"
+  else
+    puts "Cound not read HC-SR04 sensor"
+  end
+  sleep 0.5
+end

data/examples/i2c_bb_aht10.rb

@@ -0,0 +1,40 @@
+require 'lgpio'
+
+POWER_ON_DELAY      = 0.100
+RESET_DELAY         = 0.020
+COMMAND_DELAY       = 0.010
+MEASURE_DELAY       = 0.080
+DATA_LENGTH         = 6
+SOFT_RESET          = [0xBA]
+INIT_AND_CALIBRATE  = [0xE1, 0x08, 0x00]
+START_MEASUREMENT   = [0xAC, 0x33, 0x00]
+
+GPIO_CHIP = 0
+SCL_PIN   = 228
+SDA_PIN   = 270
+ADDRESS   = 0x38
+
+chip_handle = LGPIO.chip_open(GPIO_CHIP)
+i2c_bb = LGPIO::I2CBitBang.new(chip_handle, SCL_PIN, SDA_PIN)
+
+# Startup sequence
+sleep(POWER_ON_DELAY)
+i2c_bb.write(ADDRESS, SOFT_RESET)
+sleep(RESET_DELAY)
+i2c_bb.write(ADDRESS, INIT_AND_CALIBRATE)
+sleep(COMMAND_DELAY)
+
+# Read and close
+i2c_bb.write(ADDRESS, START_MEASUREMENT)
+sleep(MEASURE_DELAY)
+bytes = i2c_bb.read(ADDRESS, DATA_LENGTH)
+
+# Humidity uses the upper 4 bits of the shared byte as its lowest 4 bits.
+h_raw = ((bytes[1] << 16) | (bytes[2] << 8) | (bytes[3])) >> 4
+humidity = (h_raw.to_f / 2**20) * 100
+
+# Temperature uses the lower 4 bits of the shared byte as its highest 4 bits.
+t_raw = ((bytes[3] & 0x0F) << 16) | (bytes[4] << 8) | bytes[5]
+temperature = (t_raw.to_f / 2**20) * 200 - 50
+
+puts "#{Time.now.strftime '%Y-%m-%d %H:%M:%S'} - Temperature: #{temperature.round(2)} \xC2\xB0C | Humidity: #{humidity.round(2)} %"

data/examples/i2c_bb_search.rb

@@ -0,0 +1,19 @@
+require 'lgpio'
+
+GPIO_CHIP = 0
+SCL_PIN   = 228
+SDA_PIN   = 270
+
+chip_handle = LGPIO.chip_open(GPIO_CHIP)
+i2c_bb = LGPIO::I2CBitBang.new(chip_handle, SCL_PIN, SDA_PIN)
+devices = i2c_bb.search
+
+if devices.empty?
+  puts "No devices found on I2C bus"
+else
+  puts "I2C device addresses found:"
+  devices.each do |address|
+    # Print as hexadecimal.
+    puts "0x#{address.to_s(16).upcase}"
+  end
+end

data/examples/i2c_bb_ssd1306_bench.rb

@@ -0,0 +1,35 @@
+require 'lgpio'
+
+INIT_ARRAY  = [0, 168, 63, 211, 0, 64, 161, 200, 218, 18, 164, 166, 213, 128, 219, 32, 217, 241, 141, 20, 32, 0, 175]
+START_ARRAY = [0, 33, 0, 127, 34, 0, 7]
+PATTERN_1   = [64] + Array.new(1024) { 0b00110011 }
+PATTERN_2   = [64] + Array.new(1024) { 0b11001100 }
+
+GPIO_CHIP = 0
+SCL_PIN   = 228
+SDA_PIN   = 270
+ADDRESS   = 0x3C
+
+chip_handle = LGPIO.chip_open(GPIO_CHIP)
+i2c_bb = LGPIO::I2CBitBang.new(chip_handle, SCL_PIN, SDA_PIN)
+
+i2c_bb.write(ADDRESS, INIT_ARRAY)
+FRAME_COUNT = 400
+
+start = Time.now
+(FRAME_COUNT / 2).times do
+  i2c_bb.write(ADDRESS, START_ARRAY)
+  i2c_bb.write(ADDRESS, PATTERN_1)
+  i2c_bb.write(ADDRESS, START_ARRAY)
+  i2c_bb.write(ADDRESS, PATTERN_2)
+end
+finish = Time.now
+
+LGPIO.chip_close(chip_handle)
+
+fps = FRAME_COUNT / (finish - start)
+# Also calculate C calls per second, using roughly 23 calls per byte written.
+cps = (START_ARRAY.length + ((PATTERN_1.length + PATTERN_2.length) / 2) + 2) * 23 * fps
+cps = (cps / 1000.0).round
+
+puts "SSD1306 benchmark result: #{fps.round(2)} fps | #{cps}k C calls/s"

data/examples/{i2c_aht10.rb → i2c_hw_aht10.rb}

@@ -1,6 +1,7 @@
 require 'lgpio'
 
 I2C_DEV             = 3
+ADDRESS             = 0x38
 POWER_ON_DELAY      = 0.100
 RESET_DELAY         = 0.020
 COMMAND_DELAY       = 0.010
@@ -10,7 +11,7 @@ SOFT_RESET          = [0xBA]
 INIT_AND_CALIBRATE  = [0xE1, 0x08, 0x00]
 START_MEASUREMENT   = [0xAC, 0x33, 0x00]
 
-aht10_handle = LGPIO.i2c_open(I2C_DEV, 0x38, 0)
+aht10_handle = LGPIO.i2c_open(I2C_DEV, ADDRESS, 0)
 
 # Startup sequence
 sleep(POWER_ON_DELAY)

data/examples/{i2c_aht10_zip.rb → i2c_hw_aht10_zip.rb}

@@ -1,6 +1,7 @@
 require 'lgpio'
 
 I2C_DEV             = 3
+ADDRESS             = 0x38
 POWER_ON_DELAY      = 0.100
 RESET_DELAY         = 0.020
 COMMAND_DELAY       = 0.010
@@ -10,7 +11,7 @@ INIT_AND_CALIBRATE  = [5, 3, 0xE1, 0x08, 0x00, 0]
 START_MEASUREMENT   = [5, 3, 0xAC, 0x33, 0x00, 0]
 READ_SIX            = [4, 6, 0]
 
-aht10_handle = LGPIO.i2c_open(I2C_DEV, 0x38, 0)
+aht10_handle = LGPIO.i2c_open(I2C_DEV, ADDRESS, 0)
 
 # Startup sequence
 sleep(POWER_ON_DELAY)

data/examples/{i2c_ssd1306_bench.rb → i2c_hw_ssd1306_bench.rb}

@@ -1,21 +1,22 @@
 require 'lgpio'
 
 I2C_DEV     = 3
+ADDRESS     = 0x3C
 INIT_ARRAY  = [0, 168, 63, 211, 0, 64, 161, 200, 218, 18, 164, 166, 213, 128, 219, 32, 217, 241, 141, 20, 32, 0, 175]
 START_ARRAY = [0, 33, 0, 127, 34, 0, 7]
-BLANK_ARRAY = [64] + Array.new(1024) { 0 }
-FILL_ARRAY  = [64] + Array.new(1024) { 255 }
+PATTERN_1   = [64] + Array.new(1024) { 0b00110011 }
+PATTERN_2   = [64] + Array.new(1024) { 0b11001100 }
 
-ssd1306_handle = LGPIO.i2c_open(I2C_DEV, 0x3C, 0)
+ssd1306_handle = LGPIO.i2c_open(I2C_DEV, ADDRESS, 0)
 LGPIO.i2c_write_device(ssd1306_handle, INIT_ARRAY)
 FRAME_COUNT = 100
 
 start = Time.now
 (FRAME_COUNT / 2).times do
   LGPIO.i2c_write_device(ssd1306_handle, START_ARRAY)
-  LGPIO.i2c_write_device(ssd1306_handle, FILL_ARRAY)
+  LGPIO.i2c_write_device(ssd1306_handle, PATTERN_1)
   LGPIO.i2c_write_device(ssd1306_handle, START_ARRAY)
-  LGPIO.i2c_write_device(ssd1306_handle, BLANK_ARRAY)
+  LGPIO.i2c_write_device(ssd1306_handle, PATTERN_2)
 end
 finish = Time.now
 

data/examples/infrared.rb

@@ -0,0 +1,22 @@
+require 'lgpio'
+
+FREQUENCY   = 38_000
+
+# NEC Raw-Data=0xF708FB04. LSBFIRST, so the binary for each hex digit below is backward.
+CODE =  [ 9000, 500,                                  # Start bit
+          560, 560, 560, 560, 560, 1690, 560, 560,    # 0010 0x4 command
+          560, 560, 560, 560, 560, 560, 560, 560,     # 0000 0x0 command
+          560, 1690, 560, 1690, 560,560, 560, 1690,   # 1101 0xB command inverted
+          560, 1690, 560, 1690, 560, 1690, 560, 1690, # 1111 0xF command inverted
+          560, 560, 560, 560, 560, 560, 560, 1690,    # 0001 0x8 address
+          560, 560, 560, 560, 560, 560, 560, 560,     # 0000 0x0 address
+          560, 1690, 560, 1690, 560, 1690, 560, 560,  # 1110 0x7 address inverted
+          560, 1690, 560, 1690, 560, 1690, 560, 1690, # 1111 0xF address inverted
+          560]                                        # Stop bit
+
+infrared = LGPIO::Infrared.new(0, 2, frequency: FREQUENCY)
+
+loop do
+  infrared.transmit(CODE)
+  sleep 1
+end

data/examples/one_wire_ds18b20.rb

@@ -0,0 +1,30 @@
+require 'lgpio'
+
+GPIO_CHIP = 0
+PIN       = 256
+PARASITE  = false
+
+chip_handle = LGPIO.chip_open(GPIO_CHIP)
+one_wire = LGPIO::OneWire.new(chip_handle, PIN)
+
+one_wire.reset
+# Skip ROM
+one_wire.write([LGPIO::OneWire::SKIP_ROM], parasite: PARASITE)
+# Start conversion
+one_wire.write([LGPIO::OneWire::CONVERT_T], parasite: PARASITE)
+# Wait for conversion
+sleep(1)
+# Reset
+one_wire.reset
+# Skip ROM
+one_wire.write([LGPIO::OneWire::SKIP_ROM], parasite: PARASITE)
+# Read 9 bytes from scratchpad
+one_wire.write([LGPIO::OneWire::READ_SCRATCH], parasite: PARASITE)
+bytes = one_wire.read(9)
+
+# Temperature is the first 16 bits (2 bytes of 9 read).
+# It's a signed, 2's complement, little-endian decimal. LSB = 2 ^ -4.
+#
+temperature = bytes[0..1].pack('C*').unpack('s<')[0] * (2.0 ** -4)
+
+puts "DS18B20 reading: #{temperature} \xC2\xB0C"

data/examples/one_wire_search.rb

@@ -0,0 +1,15 @@
+require 'lgpio'
+
+GPIO_CHIP = 0
+PIN       = 256
+
+chip_handle = LGPIO.chip_open(GPIO_CHIP)
+one_wire = LGPIO::OneWire.new(chip_handle, PIN)
+one_wire.search
+
+puts; puts "Found these 1-wire addresss (HEX) on the bus:"; puts
+
+one_wire.found_addresses.each do |address|
+  puts address.to_s(16)
+end
+puts

data/examples/pwm_hw_bench.rb

@@ -0,0 +1,20 @@
+require 'lgpio'
+#
+# Writing directly to a hardware PWM channel.
+# Arguments in order are:
+#   pwmchip index (X in /sys/class/pwm/pwmchipX/)
+#   PWM channel on the chip (Y in /sys/class/pwm/pwmchipX/pwmY)
+#   period: given in nanoseconds
+#   OR frequency: given in Hz
+#
+pwm_out = LGPIO::HardwarePWM.new(0, 1, period: 20_000_000)
+
+RUNS = 250_000
+start = Time.now
+RUNS.times do
+  pwm_out.duty_us = 1000
+end
+finish = Time.now
+
+wps = RUNS / (finish - start)
+puts "Hardware PWM writes per second: #{wps.round(2)}"

data/examples/{pwm.rb → pwm_sw.rb}

@@ -1,7 +1,7 @@
 require 'lgpio'
 
 GPIO_CHIP   = 0
-LED         = 260
+LED         = 272
 PWM_FREQ    = 500
 PWM_OFFSET  = 0
 PWM_CYCLES  = 0    # 0 = infinite

data/examples/spi_bb_loopback.rb

@@ -0,0 +1,25 @@
+require 'lgpio'
+
+GPIO_CHIP   = 0
+CLOCK_PIN   = 22
+INPUT_PIN   = 17
+OUTPUT_PIN  = 27
+
+MODES       = [0, 1, 2, 3]
+ORDERS      = [:msbfirst, :lsbfirst]
+TX_BYTES    = [0, 1, 2, 3, 4, 5, 6, 7]
+
+chip_handle = LGPIO.chip_open(GPIO_CHIP)
+spi_bb      = LGPIO::SPIBitBang.new(handle: chip_handle, clock: CLOCK_PIN, input: INPUT_PIN, output: OUTPUT_PIN)
+
+puts "TX bytes => #{TX_BYTES.inspect}"
+
+# Connect (loop back) INPUT_PIN to OUTPUT_PIN to see received bytes.
+ORDERS.each do |order|
+  MODES.each do |mode|
+    rx_bytes = spi_bb.transfer(write: TX_BYTES, read: TX_BYTES.length, order: order, mode: mode)
+    puts "RX (order: #{order}, mode: #{mode}) => #{rx_bytes.inspect}"
+  end
+end
+
+LGPIO.chip_close(chip_handle)

data/examples/spi_bb_sim_bench.rb

@@ -0,0 +1,48 @@
+require 'lgpio'
+
+GPIO_CHIP   = 0
+CLOCK_PIN   = 17
+INPUT_PIN   = 22
+OUTPUT_PIN  = 27
+
+# Emulate data sent over I2C to a SSD1306 OLED, prepending its write address.
+START_ARRAY = [0x3C << 1] + [0, 33, 0, 127, 34, 0, 7]
+PATTERN_1   = [0x3C << 1] + [64] + Array.new(1179) { 0b00110011 }
+PATTERN_2   = [0x3C << 1] + [64] + Array.new(1179) { 0b11001100 }
+FRAME_COUNT = 400
+
+chip_handle = LGPIO.chip_open(GPIO_CHIP)
+spi_bb      = LGPIO::SPIBitBang.new(handle: chip_handle, clock: CLOCK_PIN, input: INPUT_PIN, output: OUTPUT_PIN)
+
+start = Time.now
+(FRAME_COUNT / 2).times do
+  spi_bb.transfer(write: START_ARRAY)
+  spi_bb.transfer(write: PATTERN_1)
+  spi_bb.transfer(write: START_ARRAY)
+  spi_bb.transfer(write: PATTERN_2)
+end
+finish = Time.now
+
+LGPIO.chip_close(chip_handle)
+
+fps = FRAME_COUNT / (finish - start)
+#
+# We want to calculate how many C calls were made per second, to compare with I2C:
+#  - SPI bytes are 8 bits on the wire, while I2C are 9 (8 data bits + ACK bit).
+#  - The I2C ACK should do 4 C API calls, while data bits on both buses need 3 calls.
+#  - This isn't always true. Because of the "lazy" optimization when setting the data pin
+#    in both protocols, and the line pattern being used, where the first bit of
+#    each byte is the inverse of the last bit of the previous byte, two things change:
+#    - Each I2C ACK is effecitvely 3 C calls. The data bit either before or after is always 1,
+#      eliminating a write to SDA.
+#    - For both buses, the "2 on, 2 off" patern means 8 data bits are only 20 C calls total.
+#  - So SPI is 20 for all pixel bytes, and I2C is 23 for all pixel bytes.
+#  - Ignores bit changes in the address and start bytes.
+#  - Ignore 10 calls per frame for I2C start/stop, and 2 calls per frame for SPI clock idle.
+#  - These are only 1% of total calls, so should be negligible.
+#  - Changing the line pattern WILL break this calculation.
+#
+cps = (START_ARRAY.length + ((PATTERN_1.length + PATTERN_2.length) / 2)) * 20 * fps
+cps = (cps / 1000.0).round
+
+puts "SSD1306 sim result: #{fps.round(2)} fps | #{cps}k C calls/s"