lgpio 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e24e221cb39d27714d3fdd9486c47dd01e33115980d29e5104a455e14fd40890
-  data.tar.gz: 4ffd6e35644bc8dcde49486cd43d8e7ca73ebbfe9b46955a8de89a4ecff49d33
+  metadata.gz: 984afd62543a10d3fc0b6d2a9a581b05b4d9bf7c159d2747f990b2247b59aef1
+  data.tar.gz: d2431adb24613fdd42b9f9f06a428c399fe48be2e215a13463237a798113630c
 SHA512:
-  metadata.gz: 5060a2fd7a5ef20a1de29f01a87aa2ff2639c9d0e9005594de672d7fa011df48e7a65b893ad4310d07d780f9677c1544ccc80018a5bb4794e014513f4864fae4
-  data.tar.gz: 16e6a32af1a358ffcf18c7864d2748527f635a83f42734fc3191ecb6eed7fb50cef3ffe4370651b063fde6e4a28bd2075a12b6adb8d04b3e4646353d973515c3
+  metadata.gz: f32ceb3af8218d26f1f5713302a9891365af498fe76e2a750037f2ae10a437b747b40167e9fd9c5170fc28696d90c9244ce5d9a36269eba0d0c827a79be47fcd
+  data.tar.gz: b167ef512729754b46dd3cd14750dd715c8541987014a254465c72619f1ead5d4ae8ff74bcbb6c9122b331c5f65a159e0f0c9890f9e0ad7a5b582dafe2763e54

data/.gitignore

@@ -23,3 +23,4 @@ tmp
 .ruby-version
 .rvmrc
 .zed
+._*

data/README.md

@@ -1,18 +1,29 @@
 # lgpio
 
-Ruby bindings for the [lgpio (lg)](https://github.com/joan2937/lg) C library, for Linux on single board computers (SBCs), like the Raspberry Pi and its competitors.
-
-## Features
-- GPIO Read/Write
-- GPIO Group Read/Write
-- GPIO Alerts / Callbacks
-  - lg generates alerts at high speed, in a separate thread. In Ruby they can be read from a queue as part of your application loop.
-- PWM Output
-  - Software timed on any pin. No interface for hardware PWM yet.
-- Wave
+Ruby bindings for the [lgpio (lg)](https://github.com/joan2937/lg) Linux library, running on single board computers (SBCs), like Raspberry Pi.
+
+## 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] Wave
   - Software timed on any pin, as with PWM.
-- I2C
-- SPI
+- [x] I2C
+- [x] SPI
+
+## 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
+
+## Sysfs PWM Interface Features
+- [x] Hardware PWM Out (specific pins per chip)
+- [x] Servo
 
 ## Installation
 On Debian-based Linuxes (RaspberryPi OS, Armbian, DietPi etc.):
@@ -33,9 +44,9 @@ 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 may 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 I2C and SPI hardware. You should use the setup or config tool that came with your distro for that.
 
-You may also not have permission to access some or all of the GPIO and peripherals. To run without `sudo`, you will need read+write permission to some or all of the following devices:
+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:
 ```
 /dev/gpiochip* (For GPIO, example: /dev/gpiochip0)
 /dev/i2c-*     (For I2C,  example: /dev/i2c-1)
@@ -44,11 +55,11 @@ You may also not have permission to access some or all of the GPIO and periphera
 
 ## Documentation
 - See examples folder for demos of every implemented interface.
-  - Development was done on an Orange Pi Zero 2W. Your GPIO numbers will be different, so change them.
+  - 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:
   - Snake case instead of camel case names for methods.
   - Method names have the leading `lg` removed, since inside the `LGPIO` class.
   - Constants have leading `LG_` removed, as above.
   - "count" or "length" arguments associated with array args are not needed.
-- Check the return values of your method calls. On failure, they return negative values values, matching the `LG_` error codes at the bottom of the C API doc page.
+- Check the return values of your method calls. On failure, they return negative values, matching the `LG_` error codes at the bottom of the C API doc page.

data/examples/i2c_aht10.rb

@@ -1,6 +1,6 @@
 require 'lgpio'
 
-I2C_DEV = 2
+I2C_DEV             = 3
 POWER_ON_DELAY      = 0.100
 RESET_DELAY         = 0.020
 COMMAND_DELAY       = 0.010

data/examples/i2c_aht10_zip.rb

@@ -1,6 +1,6 @@
 require 'lgpio'
 
-I2C_DEV = 2
+I2C_DEV             = 3
 POWER_ON_DELAY      = 0.100
 RESET_DELAY         = 0.020
 COMMAND_DELAY       = 0.010

data/examples/i2c_ssd1306_bench.rb

@@ -1,6 +1,6 @@
 require 'lgpio'
 
-I2C_DEV = 2
+I2C_DEV     = 3
 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 }

data/examples/servo.rb

@@ -0,0 +1,36 @@
+require 'lgpio'
+#
+# Writing directly to a hardware PWM channel to control a servo.
+# 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
+#
+servo = LGPIO::HardwarePWM.new(0, 1, period: 20_000_000)
+#
+# Duty cycle is given in nanoseconds by default. Extra setter methods
+# are provided for microseconds, and percent.
+#
+# servo.duty_percent = 2.5
+# servo.duty_us = 500
+servo.duty = 500_000
+
+#
+# Using the Servo class instead.
+# Arguments in order are:
+#   pwmchip index (X in /sys/class/pwm/pwmchipX/)
+#   PWM channel on the chip (Y in /sys/class/pwm/pwmchipX/pwmY)
+#   Minimum servo duty cycle in microseconds
+#   Maximum servo duty cicle in microseconds
+#   Minimum servo angle
+#   Maximum servo angle
+#
+servo = LGPIO::PositionalServo.new(0, 1, 500, 2500, 0, 180)
+
+angles = [0, 30, 60, 90, 120, 150, 180, 150, 120, 90, 60, 30]
+
+angles.cycle do |angle|
+  servo.angle = angle
+  sleep 1
+end

data/examples/spi_ws2812.rb

@@ -1,42 +1,15 @@
 #
-# 2.4 MHz SPI method for writing WS2812 addressable LEDs
-# Based on:https://learn.adafruit.com/dma-driven-neopixels/overview
+# 2.4 MHz SPI method for writing WS2812 addressable LEDs.
+# Based on: https://learn.adafruit.com/dma-driven-neopixels/overview
 #
 require 'lgpio'
 
-# WS2812 Constants
-NP_ONE   = 0b110
-NP_ZERO  = 0b100
-NP_START = [0]
-NP_END   = Array.new(90) { 0 }
-BITS     = (0..7).to_a.reverse
-
 # SPI Config
 SPI_DEV  = 1
 SPI_CHAN = 0
 SPI_MODE = 0
 SPI_BAUD = 2_400_000
 
-# Map array of pixel values (3 bytes each) to raw SPI bytes (1bit -> 3 bits).
-def pixel_to_raw_spi_bytes(pixel_arr)
-  raw_spi_bytes = []
-  pixel_arr.flatten.each do |byte|
-    long = 0b0
-    for i in BITS do
-      long = long << 3
-      if byte[i] == 0
-        long |= NP_ZERO
-      else
-        long |= NP_ONE
-      end
-    end
-    # Pack as big-endian uint32, then unpack to bytes, taking lowest 24 bits only.
-    long = [long].pack('L>')
-    raw_spi_bytes << long.unpack('C*')[1..3]
-  end
-  return raw_spi_bytes.flatten
-end
-
 # 4 pixels: RGBW. Data order per pixel is GRB.
 pixels_on = [
   0, 255, 0,
@@ -44,17 +17,14 @@ pixels_on = [
   0, 0, 255,
   255, 255, 255,
 ]
-data_on = NP_START + pixel_to_raw_spi_bytes(pixels_on) + NP_END
-
 # 4 pixels, all off.
 pixels_off = Array.new(12) { 0 }
-data_off = NP_START + pixel_to_raw_spi_bytes(pixels_off) + NP_END
 
 spi_handle = LGPIO.spi_open(SPI_DEV, SPI_CHAN, SPI_BAUD, SPI_MODE)
 
 loop do
-  LGPIO.spi_write(spi_handle, data_on)
+  LGPIO.spi_ws2812_write(spi_handle, pixels_on)
   sleep 0.5
-  LGPIO.spi_write(spi_handle, data_off)
+  LGPIO.spi_ws2812_write(spi_handle, pixels_off)
   sleep 0.5
 end

data/examples/spi_ws2812_bounce.rb

@@ -0,0 +1,44 @@
+#
+# 2.4 MHz SPI method for writing WS2812 addressable LEDs.
+# Based on: https://learn.adafruit.com/dma-driven-neopixels/overview
+#
+require 'lgpio'
+
+# SPI config
+SPI_DEV  = 1
+SPI_CHAN = 0
+SPI_MODE = 0
+SPI_BAUD = 2_400_000
+
+PIXEL_COUNT = 8
+COLORS = [
+  [255, 255, 255],
+  [0, 255, 0],
+  [255, 0, 0],
+  [0, 0, 255],
+  [255, 255, 0],
+  [255, 0, 255],
+  [0, 255, 255]
+]
+
+# Move along the strip and back, one pixel at a time.
+POSITIONS = (0..PIXEL_COUNT-1).to_a + (1..PIXEL_COUNT-2).to_a.reverse
+
+pixels = Array.new(PIXEL_COUNT) { [0, 0, 0] }
+spi_handle = LGPIO.spi_open(SPI_DEV, SPI_CHAN, SPI_BAUD, SPI_MODE)
+
+loop do
+  COLORS.each do |color|
+    POSITIONS.each do |index|
+      # Clear and write.
+      (0..PIXEL_COUNT-1).each { |i| pixels[i] = [0, 0, 0] }
+      LGPIO.spi_ws2812_write(spi_handle, pixels.flatten)
+
+      # Set one pixel and write.
+      pixels[index] = color
+      LGPIO.spi_ws2812_write(spi_handle, pixels.flatten)
+
+      sleep 0.05
+    end
+  end
+end

data/ext/lgpio/lgpio.c

@@ -302,6 +302,42 @@ static VALUE spi_xfer(VALUE self, VALUE handle, VALUE txArray){
   return retArray;
 }
 
+static VALUE spi_ws2812_write(VALUE self, VALUE handle, VALUE pixelArray){
+  int count = RARRAY_LEN(pixelArray);
+
+  // Pull low for at least one byte at 2.4 Mhz before data, and 90 after.
+  int zeroesBefore = 1;
+  int zeroesAfter  = 90;
+  int txBufLength  = zeroesBefore + (count*3) + zeroesAfter;
+  uint8_t txBuf[txBufLength];
+  for (int i=0; i<txBufLength; i++) { txBuf[i] = 0; }
+
+  VALUE    currentByte_rb;
+  uint8_t  currentByte;
+  uint8_t  currentBit;
+  uint32_t temp;
+
+  for (int i=0; i<count; i++){
+    temp = 0;
+    currentByte_rb = rb_ary_entry(pixelArray, i);
+    Check_Type(currentByte_rb, T_FIXNUM);
+    currentByte = NUM2CHR(currentByte_rb);
+
+    for (int i=7; i>=0; i--) {
+      currentBit = (currentByte & (1 << i));
+      temp = temp << 3;
+      temp = (currentBit == 0) ? (temp | 0b100) : (temp | 0b110);
+    }
+
+    txBuf[zeroesBefore+(i*3)]   = (temp >> 16) & 0xFF;
+    txBuf[zeroesBefore+(i*3)+1] = (temp >> 8) & 0xFF;
+    txBuf[zeroesBefore+(i*3)+2] = temp & 0xFF;
+  }
+
+  int result = lgSpiWrite(NUM2INT(handle), txBuf, txBufLength);
+  return INT2NUM(result);
+}
+
 void Init_lgpio(void) {
   // Modules
   VALUE mLGPIO = rb_define_module("LGPIO");
@@ -360,4 +396,5 @@ void Init_lgpio(void) {
   rb_define_singleton_method(mLGPIO, "spi_read",           spi_read,          2);
   rb_define_singleton_method(mLGPIO, "spi_write",          spi_write,         2);
   rb_define_singleton_method(mLGPIO, "spi_xfer",           spi_xfer,          2);
+  rb_define_singleton_method(mLGPIO, "spi_ws2812_write",   spi_ws2812_write,  2);
 }

data/lib/lgpio/hardware_pwm.rb

@@ -0,0 +1,70 @@
+module LGPIO
+  class HardwarePWM
+    NS_PER_S  = 1_000_000_000
+    NS_PER_US = 1_000
+    SYS_FS_PWM_PATH = "/sys/class/pwm/"
+
+    attr_reader :period, :duty, :enabled
+
+    def initialize(chip, channel, frequency: nil, period: nil)
+      @chip    = chip
+      @channel = channel
+
+      # Accept either frequency (in Hz) or period in nanoseconds.
+      if (frequency && period) || (!frequency && !period)
+        raise "either period: or frequency: is required, but not both"
+      end
+
+      period ? self.period = period : self.frequency = frequency
+      enable
+    end
+
+    def path
+      @path ||= "#{SYS_FS_PWM_PATH}pwmchip#{@chip}/pwm#{@channel}/"
+    end
+
+    def frequency=(freq)
+      self.period = (NS_PER_S / freq.to_f).round
+    end
+
+    def period=(p)
+      old_period = File.read("#{path}period").strip.to_i
+      unless (old_period == 0)
+        File.open("#{path}duty_cycle", 'w') { |f| f.write("0") }
+      end
+      File.open("#{path}period", 'w')     { |f| f.write(p)   }
+      @period = p
+    end
+
+    def duty_percent
+      (duty / period.to_f) * 100.0
+    end
+
+    def duty_percent=(d)
+      raise "duty_cycle: #{d} % cannot be more than 100%" if d > 100
+      d_ns = ((d / 100.0) * @period.to_i).round
+      self.duty = d_ns
+    end
+
+    def duty_us=(d_us)
+      d_ns = (d_us * NS_PER_US).round
+      self.duty = d_ns
+    end
+
+    def duty=(d_ns)
+      raise "duty cycle: #{d_ns} ns cannot be longer than period: #{period} ns" if d_ns > period
+      File.open("#{path}duty_cycle", 'w') { |f| f.write(d_ns) }
+      @duty = d_ns
+    end
+
+    def disable
+      File.open("#{path}enable", 'w') { |f| f.write("0") }
+      @enabled = false
+    end
+
+    def enable
+      File.open("#{path}enable", 'w') { |f| f.write("1") }
+      @enabled = true
+    end
+  end
+end

data/lib/lgpio/positional_servo.rb

@@ -0,0 +1,28 @@
+module LGPIO
+  class PositionalServo < HardwarePWM
+    FREQUENCY = 50
+
+    attr_reader :angle
+
+    def initialize(chip, channel, min_us, max_us, min_angle, max_angle)
+      super(chip, channel, frequency: FREQUENCY)
+
+      raise "min_us: #{min_us} cannot be lower than max_us: #{max_us}" if max_us < min_us
+      @min_us = min_us
+      @max_us = max_us
+      @us_range = @max_us - @min_us
+
+      @min_angle = min_angle
+      @max_angle = max_angle
+    end
+
+    def angle=(a)
+      ratio = (a - @min_angle).to_f / (@max_angle - @min_angle)
+      raise "angle: #{a} outside servo range" if (ratio < 0) || (ratio > 1)
+
+      d_us = (@us_range * ratio) + @min_us
+      self.duty_us = d_us
+      @angle = a
+    end
+  end
+end

data/lib/lgpio/version.rb

@@ -1,3 +1,3 @@
 module LGPIO
-  VERSION = "0.1.3"
+  VERSION = "0.1.5"
 end

data/lib/lgpio.rb

@@ -1,4 +1,7 @@
 require_relative 'lgpio/lgpio'
+require_relative 'lgpio/version'
+require_relative 'lgpio/hardware_pwm'
+require_relative 'lgpio/positional_servo'
 
 module LGPIO
   LOW = 0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lgpio
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - vickash
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-03 00:00:00.000000000 Z
+date: 2024-08-17 00:00:00.000000000 Z
 dependencies: []
 description: Use GPIO / PWM / I2C / SPI / UART on Linux SBCs in Ruby
 email: mail@vickash.com
@@ -34,14 +34,18 @@ files:
 - examples/reports.rb
 - examples/rotary_encoder.rb
 - examples/rotary_encoder_led.rb
+- examples/servo.rb
 - examples/spi_loopback.rb
 - examples/spi_read.rb
 - examples/spi_ws2812.rb
+- examples/spi_ws2812_bounce.rb
 - examples/wave.rb
 - ext/lgpio/extconf.rb
 - ext/lgpio/lgpio.c
 - lgpio.gemspec
 - lib/lgpio.rb
+- lib/lgpio/hardware_pwm.rb
+- lib/lgpio/positional_servo.rb
 - lib/lgpio/version.rb
 homepage: https://github.com/denko-rb/lgpio
 licenses: