rgpio 0.1.0

data/lib/rgpio/software_pwm.rb

@@ -0,0 +1,290 @@
+module Rgpio
+  # PWM generated in Ruby on any GPIO line, for the pins the hardware PWM
+  # peripheral cannot reach.
+  #
+  # {HardwarePWM} is jitter-free but needs a dtoverlay in config.txt and only
+  # reaches GPIO12/13/18/19, two channels at a time on the 40-pin header. This
+  # class needs no configuration at all and works on every line, at the cost of
+  # timing accuracy — the same trade-off Python's gpiozero makes, which drives
+  # all of its PWM through `lgpio.tx_pwm` ("software timed PWM").
+  #
+  # Usage (block form — recommended):
+  #   Rgpio::SoftwarePWM.open(18) do |pwm|
+  #     pwm.frequency  = 100
+  #     pwm.duty_cycle = 0.25
+  #     pwm.enable
+  #     sleep 2
+  #   end
+  #
+  # Accuracy: the generating thread sleeps until shortly before each edge and
+  # then spins for the last {#spin_us} microseconds, because a bare `sleep`
+  # overshoots a microsecond-scale deadline badly — with no spin at all, a 50 Hz
+  # 1500 us pulse measured on a Pi 5 spread over 72..6756 us. Spinning holds the
+  # GVL, so it is a tax on the main thread, capped at {MAX_SPIN_FRACTION} of the
+  # period per edge.
+  #
+  # Nothing can fix the other direction: while the main thread holds the GVL in
+  # a long computation, this thread cannot wake at all. Python has the same
+  # limitation with the GIL.
+  class SoftwarePWM
+    # gpiozero's default for PWMLED, and fast enough that an LED does not
+    # visibly flicker.
+    DEFAULT_FREQUENCY = 100
+
+    # How long before each edge to stop sleeping and start spinning. Measured
+    # on a Pi 5 at 50 Hz: 0 us gives a 386 us standard deviation and pulses as
+    # long as 6.7 ms, 100 us gives 29 us, 300 us gives 13 us, and 1000 us is no
+    # better than 300.
+    DEFAULT_SPIN_US = 300
+
+    # Cap on the spin as a fraction of the period, per edge. Spinning holds the
+    # GVL, so a fixed 300 us would cost 60% of a core at 1 kHz; this keeps the
+    # tax at 10% of one core whatever the frequency, and a frequency that high
+    # is driving an LED, where a few microseconds of edge placement is invisible.
+    MAX_SPIN_FRACTION = 0.05
+
+    # The range lgpio accepts, for parity. Above roughly 1 kHz the duty cycle
+    # of a Ruby-generated waveform stops being accurate — measure before
+    # trusting it.
+    FREQUENCY_RANGE = (0.1..10_000)
+
+    # Open a channel, yield it, then close it.
+    # @return [SoftwarePWM, Object] the channel, or the block's value
+    def self.open(gpio, **)
+      pwm = new(gpio, **)
+      return pwm unless block_given?
+
+      begin
+        yield pwm
+      ensure
+        pwm.close
+      end
+    end
+
+    # @param gpio       [Integer] GPIO line offset (BCM numbering)
+    # @param frequency  [Numeric] Hz
+    # @param duty_cycle [Float] 0.0..1.0
+    # @param spin_us    [Integer] microseconds to spin before each edge
+    # @param chip       [Chip, nil] chip to share, or nil to open one
+    # @param consumer   [String] name shown in the kernel's request list
+    def initialize(gpio, frequency: DEFAULT_FREQUENCY, duty_cycle: 0.0, spin_us: DEFAULT_SPIN_US,
+                   chip: nil, consumer: "rgpio")
+      @gpio = gpio
+      @spin = validate_spin(spin_us) / 1_000_000.0
+      @mutex = Mutex.new
+      @frequency = validate_frequency(frequency)
+      @duty = validate_duty(duty_cycle)
+      @running = false
+      @closed = false
+      @owns_chip = chip.nil?
+      @chip = chip || Chip.new
+      @request = @chip.request_lines(
+        offsets: [gpio],
+        direction: :output,
+        initial_value: :inactive,
+        consumer: consumer
+      )
+    end
+
+    # @return [Integer] the GPIO line this channel drives
+    attr_reader :gpio
+
+    # @return [Numeric] frequency in Hz
+    attr_reader :frequency
+
+    # @return [Float] duty cycle as a ratio, 0.0..1.0
+    def duty_cycle
+      @duty
+    end
+
+    # Alias for parity with {HardwarePWM}, which calls it duty_ratio.
+    alias duty_ratio duty_cycle
+
+    # @return [Integer] microseconds spent spinning before each edge
+    def spin_us
+      (@spin * 1_000_000).round
+    end
+
+    def frequency=(hz)
+      hz = validate_frequency(hz)
+      @mutex.synchronize { @frequency = hz }
+      hz
+    end
+
+    def duty_cycle=(ratio)
+      ratio = validate_duty(ratio)
+      @mutex.synchronize { @duty = ratio }
+      ratio
+    end
+
+    # Set the high time directly, the way a servo is addressed.
+    # @param us [Numeric] pulse width in microseconds
+    def pulse_width_us=(us)
+      raise ArgumentError, "pulse width must not be negative, got #{us}" if us.negative?
+
+      self.duty_cycle = us / period_us
+    end
+
+    # @return [Float] current pulse width in microseconds
+    def pulse_width_us
+      @duty * period_us
+    end
+
+    # Start generating. Safe to call when already running.
+    def enable
+      raise Error, "SoftwarePWM on GPIO#{@gpio} is closed" if @closed
+      return self if @running
+
+      @running = true
+      @thread = Thread.new { generate }
+      self
+    end
+
+    # Stop generating and leave the line inactive.
+    def disable
+      return self unless @running
+
+      @running = false
+      @thread&.join
+      @thread = nil
+      @request.set_value(@gpio, :inactive)
+      self
+    end
+
+    def enabled?
+      @running
+    end
+
+    # Stop, release the line, and close the chip if this channel opened it.
+    # Safe to call multiple times.
+    def close
+      return if @closed
+
+      disable
+      @closed = true
+      @request.release
+      @chip.close if @owns_chip
+    end
+
+    def closed?
+      @closed
+    end
+
+    def inspect
+      format("#<%s gpio=%d frequency=%gHz duty_cycle=%.3f%s>",
+             self.class, @gpio, @frequency, @duty, @running ? " running" : "")
+    end
+
+    private
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def period_us
+      1_000_000.0 / @frequency
+    end
+
+    # The generating loop. Deadlines are absolute so that a late wake-up does
+    # not push every later edge back by the same amount.
+    #
+    # The settings are re-read after the falling edge rather than before the
+    # rising one: any work done between the deadline and the rising edge is
+    # taken straight out of the high time, and reading them under the mutex
+    # cost a measurable 17 us of every pulse when it sat there.
+    def generate
+      period = high = nil
+      read_settings do |p, h|
+        period = p
+        high = h
+      end
+      spin = effective_spin(period)
+      deadline = now
+
+      while @running
+        # A line that is fully on or fully off needs no edges at all, and
+        # toggling it anyway would put a one-cycle glitch in the output.
+        if high <= 0 || high >= period
+          @request.set_value(@gpio, high <= 0 ? :inactive : :active)
+        else
+          # Time the high phase from the edge that actually happened, not from
+          # the nominal deadline: the rise lands a little after it (waking from
+          # the long low phase overshoots), and measuring from the deadline took
+          # that lateness straight out of the pulse — a measured 15 us of every
+          # one. The period stays locked to the absolute deadline below, so only
+          # the falling edge's phase drifts, which nothing can observe.
+          #
+          # The clock is read *before* each set_value so that the call's own
+          # latency cancels: it delays both edges by the same amount.
+          # Warm the call path with a write of the level the line already holds:
+          # the first set_value after waking from the long low phase is both slow
+          # and erratic (cold cache, possibly another core), and that lands
+          # entirely inside the pulse. Paying it before the clock read leaves the
+          # real edge to a warm path.
+          @request.set_value(@gpio, :inactive)
+          rise = now
+          @request.set_value(@gpio, :active)
+          wait_until(rise + high, spin)
+          @request.set_value(@gpio, :inactive)
+        end
+
+        deadline += period
+        read_settings do |p, h|
+          period = p
+          high = h
+        end
+        # If the thread was starved for longer than a whole cycle, catching up
+        # would mean running with no waits at all. Give up the lost cycles.
+        deadline = now if deadline < now - period
+        spin = effective_spin(period)
+        wait_until(deadline, spin)
+      end
+    rescue StandardError => e
+      warn "rgpio: SoftwarePWM on GPIO#{@gpio} stopped: #{e.class}: #{e.message}"
+    ensure
+      @running = false
+    end
+
+    # The spin is capped relative to the period so that a high frequency cannot
+    # turn the generating thread into a busy loop.
+    def effective_spin(period)
+      [@spin, period * MAX_SPIN_FRACTION].min
+    end
+
+    # Yield the period and high time in seconds. Kept allocation-free: building
+    # a two-element array here showed up as jitter.
+    def read_settings
+      @mutex.synchronize { yield 1.0 / @frequency, @duty / @frequency }
+    end
+
+    # Sleep for the bulk of the wait, then spin: sleep alone overshoots a
+    # microsecond-scale deadline by more than the pulse widths we are aiming for.
+    def wait_until(target, spin)
+      coarse = target - now - spin
+      sleep coarse if coarse.positive?
+      nil while now < target
+    end
+
+    def validate_frequency(hz)
+      unless hz.is_a?(Numeric) && FREQUENCY_RANGE.cover?(hz)
+        raise ArgumentError, "frequency must be in #{FREQUENCY_RANGE} Hz, got #{hz.inspect}"
+      end
+
+      hz
+    end
+
+    def validate_duty(ratio)
+      unless ratio.is_a?(Numeric) && (0.0..1.0).cover?(ratio)
+        raise ArgumentError, "duty cycle must be in 0.0..1.0, got #{ratio.inspect}"
+      end
+
+      ratio.to_f
+    end
+
+    def validate_spin(us)
+      raise ArgumentError, "spin_us must not be negative, got #{us}" unless us.is_a?(Numeric) && !us.negative?
+
+      us
+    end
+  end
+end

data/lib/rgpio/spi.rb

@@ -0,0 +1,208 @@
+require "fiddle"
+
+module Rgpio
+  # A device on a Linux spidev bus (/dev/spidevB.D).
+  #
+  # Like {I2C}, this is ioctl work on a character device, so it needs no
+  # libgpiod and works even where Rgpio.available? is false.
+  #
+  # Usage (block form — recommended):
+  #   Rgpio::SPI.open(bus: 0, device: 0, speed_hz: 1_000_000) do |spi|
+  #     rx = spi.transfer([0x06, 0x00, 0x00])
+  #   end
+  #
+  # SPI is full duplex: every transfer clocks the same number of bytes in each
+  # direction, so {#transfer} always answers with as many bytes as it was given.
+  # {#write} and {#read} are that same transfer with one direction ignored.
+  #
+  # The header bus is SPI0 (GPIO10 = MOSI, GPIO9 = MISO, GPIO11 = SCLK, GPIO8 =
+  # CE0, GPIO7 = CE1), and only appears once it is enabled — see README for the
+  # dtparam line.
+  class SPI
+    # ioctl numbers from <linux/spi/spidev.h>. They are built here rather than
+    # written out so the derivation stays checkable: direction in bits 30-31,
+    # payload size in 16-29, a 'k' magic in 8-15, and the request in 0-7.
+    IOC_MAGIC = 0x6b
+    IOC_WRITE = 1
+    IOC_READ = 2
+
+    # struct spi_ioc_transfer is { __u64 tx_buf; __u64 rx_buf; __u32 len;
+    # __u32 speed_hz; __u16 delay_usecs; __u8 bits_per_word, cs_change,
+    # tx_nbits, rx_nbits, word_delay_usecs, pad; } — exactly 32 bytes, and the
+    # header promises the same layout in 32- and 64-bit userspace. The two
+    # buffer fields are __u64 even where a pointer is 32 bits wide.
+    TRANSFER_SIZE = 32
+
+    DEFAULT_SPEED_HZ = 1_000_000
+    DEFAULT_BITS_PER_WORD = 8
+
+    # Clock polarity and phase, as the kernel numbers them.
+    MODE_RANGE = (0..3)
+
+    # @return [Integer] the ioctl request for a message of `count` transfers
+    def self.message_ioctl(count)
+      ioctl_number(IOC_WRITE, 0, TRANSFER_SIZE * count)
+    end
+
+    # @return [Integer] an encoded ioctl request
+    def self.ioctl_number(direction, request, size)
+      (direction << 30) | (size << 16) | (IOC_MAGIC << 8) | request
+    end
+
+    IOC_WR_MODE = ioctl_number(IOC_WRITE, 1, 1)
+    IOC_RD_MODE = ioctl_number(IOC_READ, 1, 1)
+    IOC_WR_LSB_FIRST = ioctl_number(IOC_WRITE, 2, 1)
+    IOC_WR_BITS_PER_WORD = ioctl_number(IOC_WRITE, 3, 1)
+    IOC_RD_BITS_PER_WORD = ioctl_number(IOC_READ, 3, 1)
+    IOC_WR_MAX_SPEED_HZ = ioctl_number(IOC_WRITE, 4, 4)
+    IOC_RD_MAX_SPEED_HZ = ioctl_number(IOC_READ, 4, 4)
+
+    # Pack a struct spi_ioc_transfer. Kept at class level so the layout can be
+    # checked without a bus present.
+    # @return [String]
+    def self.pack_transfer(tx_addr, rx_addr, len, speed_hz, bits_per_word: DEFAULT_BITS_PER_WORD,
+                           delay_us: 0, cs_change: false)
+      # "Q", not "J": the two address fields are __u64 even where a pointer is
+      # only 32 bits wide.
+      [tx_addr, rx_addr].pack("Q2") +
+        [len, speed_hz].pack("LL") +
+        [delay_us].pack("S") +
+        [bits_per_word, cs_change ? 1 : 0, 0, 0, 0, 0].pack("C6")
+    end
+
+    # @return [Array<Array(Integer, Integer)>] [bus, device] of every spidev node
+    def self.devices
+      Dir.glob("/dev/spidev*").filter_map do |path|
+        match = path.match(%r{/dev/spidev(\d+)\.(\d+)\z})
+        [match[1].to_i, match[2].to_i] if match
+      end.sort
+    end
+
+    # Open a device, yielding it and closing it afterwards when a block is given.
+    # @return [SPI, Object] the device, or the block's value
+    def self.open(**)
+      spi = new(**)
+      return spi unless block_given?
+
+      begin
+        yield spi
+      ensure
+        spi.close
+      end
+    end
+
+    # @param bus           [Integer] spidev bus number; 0 is the 40-pin header
+    # @param device        [Integer] chip-select index on that bus
+    # @param speed_hz      [Integer] clock rate
+    # @param mode          [Integer] 0..3, clock polarity and phase
+    # @param bits_per_word [Integer] word size in bits
+    def initialize(bus: 0, device: 0, speed_hz: DEFAULT_SPEED_HZ, mode: 0,
+                   bits_per_word: DEFAULT_BITS_PER_WORD)
+      @bus = bus
+      @device = device
+      @path = "/dev/spidev#{bus}.#{device}"
+      unless File.exist?(@path)
+        raise SPIError,
+              "#{@path} not found. Enable the header bus with `dtparam=spi=on` in /boot/firmware/config.txt"
+      end
+
+      @io = File.open(@path, "r+b")
+      @closed = false
+      self.mode = mode
+      self.bits_per_word = bits_per_word
+      self.speed_hz = speed_hz
+    end
+
+    # @return [Integer] spidev bus number
+    attr_reader :bus
+
+    # @return [Integer] chip-select index
+    attr_reader :device
+
+    # @return [String] path of the bus character device
+    attr_reader :path
+
+    # @return [Integer] clock rate in Hz
+    attr_reader :speed_hz
+
+    # @return [Integer] 0..3
+    attr_reader :mode
+
+    # @return [Integer] word size in bits
+    attr_reader :bits_per_word
+
+    def speed_hz=(hz)
+      raise ArgumentError, "speed_hz must be positive, got #{hz.inspect}" unless hz.is_a?(Integer) && hz.positive?
+
+      @io.ioctl(IOC_WR_MAX_SPEED_HZ, [hz].pack("L"))
+      @speed_hz = hz
+    end
+
+    def mode=(value)
+      raise ArgumentError, "mode must be in #{MODE_RANGE}, got #{value.inspect}" unless MODE_RANGE.cover?(value)
+
+      @io.ioctl(IOC_WR_MODE, [value].pack("C"))
+      @mode = value
+    end
+
+    def bits_per_word=(bits)
+      unless bits.is_a?(Integer) && bits.positive?
+        raise ArgumentError,
+              "bits_per_word must be positive, got #{bits.inspect}"
+      end
+
+      @io.ioctl(IOC_WR_BITS_PER_WORD, [bits].pack("C"))
+      @bits_per_word = bits
+    end
+
+    # Clock bytes out and in at the same time.
+    # @param bytes    [Array<Integer>, String] bytes to send
+    # @param speed_hz [Integer, nil] override the clock for this transfer only
+    # @param delay_us [Integer] hold the chip select this long afterwards
+    # @return [Array<Integer>] the bytes that came back, one per byte sent
+    def transfer(bytes, speed_hz: nil, delay_us: 0)
+      out = Bytes.pack(bytes)
+      raise ArgumentError, "transfer needs at least one byte" if out.empty?
+
+      tx = buffer(out)
+      rx = Fiddle::Pointer.malloc(out.bytesize, Fiddle::RUBY_FREE)
+      message = self.class.pack_transfer(tx.to_i, rx.to_i, out.bytesize, speed_hz || @speed_hz,
+                                         bits_per_word: @bits_per_word, delay_us: delay_us)
+      @io.ioctl(self.class.message_ioctl(1), message)
+      rx[0, out.bytesize].unpack("C*")
+    end
+
+    # Send bytes, ignoring what comes back.
+    # @return [Integer] number of bytes sent
+    def write(*bytes)
+      transfer(bytes).size
+    end
+
+    # Clock in `count` bytes, sending zeros.
+    # @return [Array<Integer>]
+    def read(count)
+      raise ArgumentError, "count must be positive, got #{count}" unless count.positive?
+
+      transfer([0] * count)
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      @io.close
+    end
+
+    def closed?
+      @closed
+    end
+
+    private
+
+    def buffer(str)
+      ptr = Fiddle::Pointer.malloc(str.bytesize, Fiddle::RUBY_FREE)
+      ptr[0, str.bytesize] = str
+      ptr
+    end
+  end
+end

data/lib/rgpio/version.rb

@@ -0,0 +1,3 @@
+module Rgpio
+  VERSION = "0.1.0".freeze
+end

data/lib/rgpio.rb

@@ -0,0 +1,99 @@
+require_relative "rgpio/version"
+require_relative "rgpio/native"
+require_relative "rgpio/chip"
+require_relative "rgpio/line_request"
+require_relative "rgpio/pwm"
+require_relative "rgpio/software_pwm"
+require_relative "rgpio/bytes"
+require_relative "rgpio/i2c"
+require_relative "rgpio/spi"
+require_relative "rgpio/devices/device"
+require_relative "rgpio/devices/output_device"
+require_relative "rgpio/devices/input_device"
+require_relative "rgpio/devices/motor"
+require_relative "rgpio/devices/pwm_channel"
+require_relative "rgpio/devices/pwm_output_device"
+require_relative "rgpio/devices/rgb_led"
+require_relative "rgpio/devices/servo"
+require_relative "rgpio/devices/adt7410"
+require_relative "rgpio/devices/st7032"
+require_relative "rgpio/devices/mcp3208"
+
+# Ruby bindings for libgpiod v2 (Linux GPIO character device), bound through
+# the stdlib `fiddle`. Targets Debian Trixie (libgpiod >= 2.1) on Raspberry Pi.
+#
+# Quick start — GPIO output:
+#   Rgpio::Chip.open do |chip|
+#     req = chip.request_lines(offsets: [17], direction: :output, consumer: "led")
+#     req.set_value(17, :active)
+#     sleep 1
+#     req.set_value(17, :inactive)
+#     req.release
+#   end
+#
+# Quick start — Hardware PWM (servo):
+#   Rgpio::HardwarePWM.open(gpio: 18) do |pwm|
+#     pwm.frequency  = 50
+#     pwm.duty_cycle = 0.075
+#     pwm.enable
+#     sleep 2
+#   end
+#
+# Quick start — high-level devices:
+#   led = Rgpio::LED.new(4)
+#   led.on
+#
+#   button = Rgpio::Button.new(17)
+#   button.when_pressed { puts "Pressed" }
+#   Rgpio.pause
+#
+# Quick start — I2C devices:
+#   puts Rgpio::ADT7410.new.temperature
+#
+#   lcd = Rgpio::ST7032.new
+#   lcd.message = "Hello\nrgpio"
+module Rgpio
+  # Raised for gem-level errors not covered by stdlib Errno classes.
+  class Error < StandardError; end
+
+  # Raised when libgpiod shared library cannot be loaded on the current system.
+  class NotAvailableError < Error; end
+
+  # Raised for PWM-related errors.
+  class PWMError < Error; end
+
+  # Raised for I2C-related errors not reported as an Errno by the kernel.
+  class I2CError < Error; end
+
+  # Raised for SPI-related errors not reported as an Errno by the kernel.
+  class SPIError < Error; end
+
+  # @return [Boolean] whether the libgpiod shared library is loaded
+  def self.available?
+    Native::LIBRARY_AVAILABLE
+  end
+
+  # Raise NotAvailableError unless libgpiod is loaded.
+  def self.assert_available!
+    return if available?
+
+    raise NotAvailableError,
+          "libgpiod shared library not found. " \
+          "Install on Debian/Raspbian: sudo apt install libgpiod3"
+  end
+
+  # @return [String, nil] libgpiod version string (e.g. "2.1.3"), or nil if unavailable
+  def self.version
+    return nil unless available?
+
+    Native.gpiod_api_version
+  end
+
+  # Block the main thread until Ctrl-C, letting device callbacks run.
+  # The Ruby counterpart of Python's signal.pause().
+  def self.pause
+    sleep
+  rescue Interrupt
+    nil
+  end
+end