rgpio 0.1.0

data/examples/pwm_jitter.rb

@@ -0,0 +1,139 @@
+#!/usr/bin/env ruby
+
+# Measure how accurate a PWM waveform really is, using the kernel's own edge
+# timestamps. A diagnostic, not a demo — nothing here is part of the gem's API.
+#
+# Wiring: one jumper between two header pins.
+#   GPIO23 (pin 16, output) ---- GPIO24 (pin 18, input)
+#
+# Driving a GPIO output straight into a GPIO input is safe; no resistor needed.
+#
+# Run (Ruby SoftwarePWM, generated in a forked process so the measuring loop
+# does not compete with it for the GVL):
+#   ruby examples/pwm_jitter.rb --hz 50 --duty 0.075 --seconds 5
+#
+# Run (measure something else driving the pin — e.g. Python gpiozero, or
+# HardwarePWM wired from GPIO12):
+#   ruby examples/pwm_jitter.rb --external --seconds 5
+#
+# What the numbers mean: `pulse` is the high time a servo reads as its position
+# (1 us is about 0.09 degrees on a 180-degree servo), `period` is the frame
+# rate. Spread matters more than the mean — a mean that is 3 us off is a fixed
+# offset you can calibrate out, while a 200 us spread is visible twitching.
+
+require_relative "../lib/rgpio"
+
+options = {
+  out: 23, in: 24, hz: 50.0, duty: 0.075, seconds: 5.0,
+  spin: Rgpio::SoftwarePWM::DEFAULT_SPIN_US, external: false,
+}
+
+ARGV.each_with_index do |arg, i|
+  case arg
+  when "--out" then options[:out] = ARGV[i + 1].to_i
+  when "--in" then options[:in] = ARGV[i + 1].to_i
+  when "--hz" then options[:hz] = ARGV[i + 1].to_f
+  when "--duty" then options[:duty] = ARGV[i + 1].to_f
+  when "--seconds" then options[:seconds] = ARGV[i + 1].to_f
+  when "--spin" then options[:spin] = ARGV[i + 1].to_i
+  when "--external" then options[:external] = true
+  when "--help", "-h"
+    puts File.read(__FILE__).lines.grep(/^#/).join
+    exit 0
+  end
+end
+
+def stats(samples)
+  return nil if samples.empty?
+
+  sorted = samples.sort
+  mean = samples.sum / samples.size.to_f
+  variance = samples.sum { |v| (v - mean)**2 } / samples.size
+  {
+    n: samples.size, mean: mean, sd: Math.sqrt(variance),
+    min: sorted.first, p50: sorted[sorted.size / 2],
+    p99: sorted[(sorted.size * 0.99).floor], max: sorted.last,
+  }
+end
+
+def report(label, target_us, samples)
+  s = stats(samples)
+  return puts("#{label}: no samples") unless s
+
+  errors = samples.map { |v| (v - target_us).abs }
+  e = stats(errors)
+  puts format("%-7s target %8.1f us   n=%d", label, target_us, s[:n])
+  puts format("          measured  mean %8.1f   sd %6.1f   min %8.1f   p50 %8.1f   max %8.1f",
+              s[:mean], s[:sd], s[:min], s[:p50], s[:max])
+  puts format("          |error|   mean %8.1f   p50 %6.1f   p99 %8.1f   max %8.1f",
+              e[:mean], e[:p50], e[:p99], e[:max])
+end
+
+# Collect edge events for `seconds`, then report pulse widths and periods.
+def measure(gpio, seconds, target_period_us, target_pulse_us)
+  events = []
+  Rgpio::Chip.open do |chip|
+    request = chip.request_lines(offsets: [gpio], direction: :input, edge: :both,
+                                 bias: :disabled, consumer: "pwm_jitter")
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+    while Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+      events.concat(request.read_edge_events(timeout: 0.05, capacity: 64))
+    end
+    request.release
+  end
+
+  pulses = []
+  periods = []
+  last_rise = nil
+  events.each do |event|
+    if event[:type] == :rising
+      periods << ((event[:timestamp_ns] - last_rise) / 1000.0) if last_rise
+      last_rise = event[:timestamp_ns]
+    elsif last_rise
+      pulses << ((event[:timestamp_ns] - last_rise) / 1000.0)
+    end
+  end
+
+  puts "edges: #{events.size}"
+  report("pulse", target_pulse_us, pulses)
+  report("period", target_period_us, periods)
+
+  dropped = periods.count { |p| p > target_period_us * 1.5 }
+  puts format("dropped/late cycles (period > 1.5x target): %d of %d", dropped, periods.size)
+end
+
+period_us = 1_000_000.0 / options[:hz]
+pulse_us = period_us * options[:duty]
+
+puts "libgpiod #{Rgpio.version}  |  measuring GPIO#{options[:in]}, #{options[:seconds]} s"
+
+if options[:external]
+  puts "generator: external (not driven by this script)"
+  measure(options[:in], options[:seconds], period_us, pulse_us)
+else
+  puts format("generator: Rgpio::SoftwarePWM on GPIO%d, %g Hz, duty %.4f, spin_us %d (forked)",
+              options[:out], options[:hz], options[:duty], options[:spin])
+  ready_r, ready_w = IO.pipe
+
+  pid = fork do
+    ready_r.close
+    pwm = Rgpio::SoftwarePWM.new(options[:out], frequency: options[:hz], duty_cycle: options[:duty],
+                                                spin_us: options[:spin], consumer: "pwm_jitter_gen")
+    pwm.enable
+    ready_w.puts "ready"
+    ready_w.close
+    sleep options[:seconds] + 1.5
+    pwm.close
+  end
+
+  ready_w.close
+  ready_r.gets
+  ready_r.close
+  sleep 0.2 # let the first few cycles settle before sampling
+
+  begin
+    measure(options[:in], options[:seconds], period_us, pulse_us)
+  ensure
+    Process.waitpid(pid)
+  end
+end

data/examples/pwm_led.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+
+# Fade an LED up and down with PWM, on any GPIO line.
+#
+# Wiring (the same as examples/led.rb):
+#   GPIO4 (pin 7) -- 1k resistor -- LED anode (long leg)
+#   LED cathode (short leg) -- GND (pin 6)
+#
+# No dtoverlay and no config.txt entry: the brightness comes from
+# Rgpio::SoftwarePWM, which drives any line. On GPIO12/13/18/19 you can pass
+# pwm: :hardware instead for a peripheral-timed waveform.
+#
+# Run:
+#   ruby examples/pwm_led.rb
+
+require_relative "../lib/rgpio"
+
+LED_GPIO = 4
+STEPS = 50
+STEP_DELAY = 0.02
+HOLD = 3
+
+# Say what the LED is doing as it happens, so the terminal and the bench agree.
+$stdout.sync = true
+
+led = Rgpio::PWMLED.new(LED_GPIO)
+puts "LED on GPIO#{LED_GPIO}, #{led.frequency} Hz. Ctrl-C to stop."
+
+begin
+  puts "1) fading up and down, three times"
+  3.times do
+    (0..STEPS).each do |i|
+      led.value = i / STEPS.to_f
+      sleep STEP_DELAY
+    end
+    (0..STEPS).reverse_each do |i|
+      led.value = i / STEPS.to_f
+      sleep STEP_DELAY
+    end
+  end
+
+  puts "2) holding fixed levels for #{HOLD} s each — one call per level, no loop"
+  [0.05, 0.25, 0.5, 1.0, 0.5].each do |level|
+    puts format("   value = %.2f  (%.0f%% duty)", level, level * 100)
+    led.value = level
+    sleep HOLD
+  end
+
+  puts "3) off"
+  led.off
+  sleep 1
+rescue Interrupt
+  puts "\nStopped."
+ensure
+  led.close
+end

data/examples/rgb_balance.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+
+# Find the per-channel balance that makes an RGB LED's white look white.
+#
+# The three dies are not equally bright for equal duty — red drops about 1.9 V
+# against 3.1 V for green and blue, so on a 3.3 V line with equal resistors the
+# channels get very different currents, and the white ends up tinted. This walks
+# through candidate scales with the LED showing white, prints each one, and waits
+# for Enter so you can look before it moves on.
+#
+# Wiring: the same as examples/rgb_led.rb.
+#   GPIO17 (pin 11) -- 1k -- red, GPIO27 (pin 13) -- 1k -- green,
+#   GPIO22 (pin 15) -- 1k -- blue, common leg -- GND (pin 9)
+#
+# Run:
+#   ruby examples/rgb_balance.rb
+#
+# Note the scale that looks neutral and pass it from then on:
+#   Rgpio::RGBLED.new(red: 17, green: 27, blue: 22, balance: [0.7, 1.0, 0.6])
+#
+# Only reducing is possible: whichever channel is weakest stays at 1.0 and the
+# others come down to meet it, so a tinted white costs some brightness.
+
+require_relative "../lib/rgpio"
+
+RED_GPIO = 17
+GREEN_GPIO = 27
+BLUE_GPIO = 22
+
+# Each step keeps the weakest-looking channel at full and pulls one or two of the
+# others down. Green is usually the weak one on 3.3 V, which reads as a blue or
+# magenta white; the later rows dim red and blue further.
+CANDIDATES = [
+  [1.0, 1.0, 1.0],
+  [0.8, 1.0, 0.8],
+  [0.7, 1.0, 0.7],
+  [0.6, 1.0, 0.6],
+  [0.5, 1.0, 0.5],
+  [0.7, 1.0, 0.5],
+  [0.5, 1.0, 0.7],
+  [1.0, 0.8, 0.8],
+].freeze
+
+$stdout.sync = true
+
+led = Rgpio::RGBLED.new(red: RED_GPIO, green: GREEN_GPIO, blue: BLUE_GPIO)
+led.color = :white
+
+puts "The LED is showing white. Press Enter to try the next balance, Ctrl-C to stop."
+puts
+
+begin
+  CANDIDATES.each_with_index do |balance, i|
+    led.balance = balance
+    puts format("%d/%d  balance = %s", i + 1, CANDIDATES.size, balance.inspect)
+    $stdin.gets
+  end
+
+  puts "Through all of them. Re-run to compare the ones you liked."
+rescue Interrupt
+  puts "\nStopped."
+ensure
+  led.off
+  led.close
+end

data/examples/rgb_led.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+
+# Cycle a full-colour LED through the corners of the colour cube, then mix.
+#
+# Wiring (common cathode: the long leg is the common one and goes to GND):
+#   GPIO17 (pin 11) -- 1k resistor -- red leg
+#   GPIO27 (pin 13) -- 1k resistor -- green leg
+#   GPIO22 (pin 15) -- 1k resistor -- blue leg
+#   common leg      -- GND (pin 9)
+#
+# For a common-anode LED, tie the common leg to 3.3 V and pass active_low: true.
+#
+# White comes out tinted unless the channels are scaled to match — see BALANCE
+# below and examples/rgb_balance.rb.
+#
+# GPIO2/3/4 work just as well (the pins the book uses) as long as the I2C bus is
+# not enabled, since GPIO2/3 are SDA/SCL. Three software PWM channels need no
+# dtoverlay; the hardware PWM peripheral could not do this at all, because the
+# 40-pin header exposes only two of its channels.
+#
+# Run:
+#   ruby examples/rgb_led.rb
+
+require_relative "../lib/rgpio"
+
+RED_GPIO = 17
+GREEN_GPIO = 27
+BLUE_GPIO = 22
+HOLD = 2
+
+# Per-channel scale that makes white look white. This is the value the LED used
+# for verification wanted — red at full, green and blue trimmed 20% — and it is
+# a property of the part, not of the gem: run examples/rgb_balance.rb to find
+# yours. [1.0, 1.0, 1.0] is the gem's default, i.e. no correction.
+BALANCE = [1.0, 0.8, 0.8].freeze
+
+# Say what the device is doing as it happens, so the terminal and the bench agree.
+$stdout.sync = true
+
+# Walk from one colour to another, a step at a time.
+def fade(led, from, to, steps: 50, delay: 0.02)
+  (0..steps).each do |i|
+    position = i / steps.to_f
+    led.color = from.zip(to).map { |a, b| a + ((b - a) * position) }
+    sleep delay
+  end
+end
+
+led = Rgpio::RGBLED.new(red: RED_GPIO, green: GREEN_GPIO, blue: BLUE_GPIO, balance: BALANCE)
+puts "RGB LED on GPIO#{RED_GPIO} (red) / #{GREEN_GPIO} (green) / #{BLUE_GPIO} (blue). Ctrl-C to stop."
+puts "1) each named colour for #{HOLD} s"
+
+begin
+  Rgpio::RGBLED::COLORS.each_key do |name|
+    next if name == :off
+
+    puts "  #{name}"
+    led.color = name
+    sleep HOLD
+  end
+
+  puts "2) fading red into blue and back, twice"
+  2.times do
+    fade(led, Rgpio::RGBLED::COLORS[:red], Rgpio::RGBLED::COLORS[:blue])
+    fade(led, Rgpio::RGBLED::COLORS[:blue], Rgpio::RGBLED::COLORS[:red])
+  end
+rescue Interrupt
+  puts "\nStopped."
+ensure
+  led.off
+  led.close
+end

data/examples/servo.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+
+# Sweep an RC servo, positioned by value (-1..1) and by angle.
+#
+# Wiring:
+#   GPIO4 (pin 7)             -- servo signal (usually yellow or orange)
+#   5 V   (pin 2 or 4)        -- servo power (red)
+#   GND   (pin 6 or any GND)  -- servo ground (brown or black)
+#
+# A servo under load draws more than the Pi's 5 V rail likes to give; if the Pi
+# reboots mid-sweep, power the servo from its own supply with a common ground.
+#
+# No dtoverlay and no config.txt entry: the pulses come from Rgpio::SoftwarePWM,
+# which measured 6 us of spread at this frame rate on an idle Pi 5 — about half a
+# degree. On GPIO12/13/18/19 you can pass pwm: :hardware for a peripheral-timed
+# pulse instead. examples/lowlevel/servo.rb drives the peripheral directly.
+#
+# Pulse widths vary by servo. 1000..2000 us is the range every hobby servo
+# understands; widen it only as far as the datasheet allows, since a servo driven
+# past its travel buzzes and heats up.
+#
+# Run:
+#   ruby examples/servo.rb
+
+require_relative "../lib/rgpio"
+
+SERVO_GPIO = 4
+
+# Say what the device is doing as it happens, so the terminal and the bench agree.
+$stdout.sync = true
+
+servo = Rgpio::Servo.new(SERVO_GPIO, min_pulse_us: 1000, max_pulse_us: 2000)
+puts "Servo on GPIO#{SERVO_GPIO}, #{servo.pwm.frequency} Hz frames. Ctrl-C to stop."
+
+begin
+  puts "centre (#{servo.pulse_width_us.round} us)"
+  sleep 1
+
+  2.times do
+    puts "one end"
+    servo.min
+    sleep 1
+    puts "the other"
+    servo.max
+    sleep 1
+  end
+
+  servo.mid
+  sleep 0.5
+
+  puts "sweeping by angle"
+  2.times do
+    (-90..90).step(2) do |degrees|
+      servo.angle = degrees
+      sleep 0.01
+    end
+    (-90..90).step(2).reverse_each do |degrees|
+      servo.angle = degrees
+      sleep 0.01
+    end
+  end
+
+  puts "detaching — the horn goes limp and the servo stops drawing current"
+  servo.detach
+  sleep 1
+rescue Interrupt
+  puts "\nStopped."
+ensure
+  servo.close
+end

data/examples/temperature.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+
+# Read the ambient temperature from an ADT7410 I2C sensor once a second.
+#
+# Wiring (the sensor breakout runs on 3.3 V):
+#   3.3V   (pin 1)          -- VDD
+#   GND    (pin 9)          -- GND
+#   GPIO2  (pin 3, SDA)     -- SDA
+#   GPIO3  (pin 5, SCL)     -- SCL
+#
+# Prerequisite — the header I2C bus must be enabled:
+#   sudo raspi-config nonint do_i2c 0     # or: dtparam=i2c_arm=on in config.txt
+#   sudo reboot
+#
+# Verify:
+#   ls /dev/i2c-1
+#   i2cdetect -y 1        # the sensor answers at 0x48 (0x49..0x4b if A0/A1 are high)
+#
+# Run:
+#   ruby examples/temperature.rb
+
+require_relative "../lib/rgpio"
+
+ADDRESS = 0x48
+INTERVAL = 1.0
+
+$stdout.sync = true # so the readings still appear when piped to a file
+
+puts "I2C buses: #{Rgpio::I2C.buses.inspect}"
+
+sensor = Rgpio::ADT7410.new(address: ADDRESS)
+
+unless sensor.detected?
+  warn format("No ADT7410 at 0x%02x (ID register read back 0x%02x).", ADDRESS, sensor.id)
+  warn "Check the wiring and `i2cdetect -y 1`."
+  exit 1
+end
+
+puts format("ADT7410 at 0x%02x, ID 0x%02x, %d-bit mode. Ctrl-C to stop.", ADDRESS, sensor.id, sensor.resolution)
+
+# The first conversion after power-up is still running for ~240 ms.
+sleep Rgpio::ADT7410::CONVERSION_TIME
+
+begin
+  loop do
+    puts format("%.4f degC", sensor.temperature)
+    sleep INTERVAL
+  end
+rescue Interrupt
+  puts "\nStopped."
+ensure
+  sensor.close
+end

data/lib/rgpio/bytes.rb

@@ -0,0 +1,12 @@
+module Rgpio
+  # Turning argument lists into the bytes that go on a bus. Shared by {I2C} and
+  # {SPI} so that `write(0x40, "Hi")` and `write(0x40, 0x48, 0x69)` mean the same
+  # thing on both.
+  module Bytes
+    # @param bytes [Array<Integer, String, Array>]
+    # @return [String] binary string
+    def self.pack(bytes)
+      Array(bytes).flatten.map { |b| b.is_a?(String) ? b.b : [b].pack("C") }.join
+    end
+  end
+end