rgpio 0.1.0

data/lib/rgpio/devices/motor.rb

@@ -0,0 +1,51 @@
+module Rgpio
+  # A DC motor behind a two-input driver such as the DRV8835 or SN754410:
+  # one line drives it forward, the other backward.
+  #
+  #   motor = Rgpio::Motor.new(forward: 2, backward: 14)
+  #   motor.forward
+  #   sleep 5
+  #   motor.backward
+  #   sleep 5
+  #   motor.stop
+  #   motor.close
+  #
+  # Speed control needs PWM on both lines and is not supported yet; the motor
+  # runs at full speed in either direction.
+  class Motor < Device
+    # @param forward  [Integer] GPIO line that drives the motor forward
+    # @param backward [Integer] GPIO line that drives the motor backward
+    # @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(forward:, backward:, chip: nil, consumer: "rgpio")
+      super(chip: chip)
+      @forward = OutputDevice.new(forward, chip: @chip, consumer: consumer)
+      @backward = OutputDevice.new(backward, chip: @chip, consumer: consumer)
+    end
+
+    # Both directions are dropped before one is raised, so the driver is never
+    # asked to source and sink the same output at once.
+    def forward
+      @backward.off
+      @forward.on
+    end
+
+    def backward
+      @forward.off
+      @backward.on
+    end
+
+    def stop
+      @forward.off
+      @backward.off
+    end
+
+    private
+
+    def release_resources
+      stop
+      @forward.close
+      @backward.close
+    end
+  end
+end

data/lib/rgpio/devices/output_device.rb

@@ -0,0 +1,66 @@
+module Rgpio
+  # A single GPIO line driven as an output.
+  #
+  #   out = Rgpio::OutputDevice.new(17)
+  #   out.on
+  #   out.off
+  #   out.close
+  class OutputDevice < Device
+    # @param gpio          [Integer] GPIO line offset (BCM numbering)
+    # @param active_low    [Boolean] when true, #on drives the line low
+    # @param initial_value [Boolean] level to drive as soon as the line is claimed
+    # @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, active_low: false, initial_value: false, chip: nil, consumer: "rgpio")
+      super(chip: chip)
+      @gpio = gpio
+      @request = @chip.request_lines(
+        offsets: [gpio],
+        direction: :output,
+        active_low: active_low,
+        initial_value: initial_value ? :active : :inactive,
+        consumer: consumer
+      )
+    end
+
+    # @return [Integer] the GPIO line offset this device drives
+    attr_reader :gpio
+
+    def on
+      self.value = true
+    end
+
+    def off
+      self.value = false
+    end
+
+    def toggle
+      self.value = !value
+    end
+
+    # @return [Boolean] true when the line is at its active level
+    def value
+      @request.get_value(@gpio) == :active
+    end
+
+    def value=(level)
+      @request.set_value(@gpio, level ? :active : :inactive)
+    end
+
+    alias on? value
+
+    private
+
+    def release_resources
+      @request.release
+    end
+  end
+
+  # An LED on a GPIO line.
+  #
+  #   led = Rgpio::LED.new(4)
+  #   5.times { led.on; sleep 1; led.off; sleep 1 }
+  #   led.close
+  class LED < OutputDevice
+  end
+end

data/lib/rgpio/devices/pwm_channel.rb

@@ -0,0 +1,25 @@
+module Rgpio
+  # Shared by the PWM-backed devices ({PWMOutputDevice}, {Servo}): turns the
+  # `pwm:` option into a channel to drive the line with.
+  #
+  # A symbol means the device opens — and later closes — a channel of its own.
+  # Anything else is a channel the caller owns and keeps, so that several devices
+  # can share one, or a {HardwarePWM} already configured the way they want it.
+  module PWMChannel
+    private
+
+    # @return [Array(Object, Boolean)] the channel, and whether it is ours to close
+    def resolve_pwm(pwm, gpio:, frequency:, chip:, consumer:)
+      return [pwm, false] unless pwm.is_a?(Symbol)
+
+      case pwm
+      when :software
+        [SoftwarePWM.new(gpio, frequency: frequency, chip: chip, consumer: consumer), true]
+      when :hardware
+        [HardwarePWM.new(gpio: gpio).tap { |channel| channel.frequency = frequency }, true]
+      else
+        raise ArgumentError, "pwm must be :software, :hardware or a PWM channel, got #{pwm.inspect}"
+      end
+    end
+  end
+end

data/lib/rgpio/devices/pwm_output_device.rb

@@ -0,0 +1,109 @@
+module Rgpio
+  # A GPIO line driven by a PWM channel, so it has a level between off and on
+  # rather than just the two.
+  #
+  # The channel is {SoftwarePWM} unless asked otherwise. It needs no dtoverlay
+  # and works on every line, where {HardwarePWM} needs a config.txt entry and
+  # reaches two header pins at a time — see PLAN.md for the measurements behind
+  # that default. Pass `pwm: :hardware` on GPIO12/13/18/19 to use the peripheral,
+  # or pass a channel object to share one.
+  class PWMOutputDevice
+    include PWMChannel
+
+    # Fast enough that an LED does not visibly flicker, and gpiozero's default.
+    DEFAULT_FREQUENCY = 100
+
+    # @param gpio          [Integer] GPIO line offset (BCM numbering)
+    # @param frequency     [Numeric] Hz; ignored when `pwm:` is a channel object,
+    #                      which the caller has already configured
+    # @param initial_value [Float] 0.0..1.0, applied before the channel starts
+    # @param active_low    [Boolean] when true, 1.0 drives the line low — the
+    #                      wiring of a common-anode LED
+    # @param pwm           [:software, :hardware, Object] channel to drive the
+    #                      line with, or one to borrow
+    # @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, initial_value: 0.0, active_low: false,
+                   pwm: :software, chip: nil, consumer: "rgpio")
+      @gpio = gpio
+      @active_low = active_low
+      @closed = false
+      @pwm, @owns_pwm = resolve_pwm(pwm, gpio: gpio, frequency: frequency, chip: chip, consumer: consumer)
+      self.value = initial_value
+      @pwm.enable
+    end
+
+    # @return [Integer] the GPIO line this device drives
+    attr_reader :gpio
+
+    # @return [Object] the PWM channel behind this device
+    attr_reader :pwm
+
+    # @return [Float] current level, 0.0..1.0
+    attr_reader :value
+
+    # @param ratio [Float] 0.0 = off, 1.0 = full on
+    def value=(ratio)
+      raise Error, "#{self.class} on GPIO#{@gpio} is closed" if @closed
+      unless ratio.is_a?(Numeric) && (0.0..1.0).cover?(ratio)
+        raise ArgumentError, "value must be in 0.0..1.0, got #{ratio.inspect}"
+      end
+
+      @value = ratio.to_f
+      @pwm.duty_cycle = @active_low ? 1.0 - @value : @value
+    end
+
+    def on
+      self.value = 1.0
+    end
+
+    def off
+      self.value = 0.0
+    end
+
+    # Invert the level, so a half-lit LED stays half-lit the other way about.
+    def toggle
+      self.value = 1.0 - @value
+    end
+
+    # @return [Boolean] true when the line is not fully off
+    def on?
+      @value.positive?
+    end
+
+    alias active? on?
+
+    # @return [Numeric] the channel's frequency in Hz
+    def frequency
+      @pwm.frequency
+    end
+
+    def frequency=(hz)
+      @pwm.frequency = hz
+    end
+
+    # Stop the channel, and release it if this device opened it.
+    # Safe to call multiple times.
+    def close
+      return if @closed
+
+      @closed = true
+      @owns_pwm ? @pwm.close : @pwm.disable
+    end
+
+    def closed?
+      @closed
+    end
+  end
+
+  # An LED whose brightness can be set, not just its state.
+  #
+  #   led = Rgpio::PWMLED.new(4)
+  #   led.value = 0.25           # a quarter bright
+  #   10.times { |i| led.value = i / 9.0; sleep 0.1 }
+  #   led.close
+  class PWMLED < PWMOutputDevice
+    alias brightness value
+    alias brightness= value=
+  end
+end

data/lib/rgpio/devices/rgb_led.rb

@@ -0,0 +1,175 @@
+module Rgpio
+  # A full-colour LED: three {PWMLED} channels behind one object.
+  #
+  #   led = Rgpio::RGBLED.new(red: 2, green: 3, blue: 4)
+  #   led.color = :magenta
+  #   led.color = [1.0, 0.4, 0.0]   # amber
+  #   led.off
+  #   led.close
+  #
+  # The default wiring is common cathode: each line sources current through its
+  # own resistor and the common leg goes to GND. For a common-anode part, tie the
+  # common leg to 3.3 V and pass `active_low: true`.
+  #
+  # Three software PWM channels means three generating threads, each spinning
+  # briefly around its edges (see {SoftwarePWM}). At the default 100 Hz that is
+  # some 16% of one core, and the threads occasionally collide, which shifts an
+  # edge by microseconds — invisible in an LED's brightness.
+  class RGBLED
+    # Corners of the colour cube, for the common case of naming a colour.
+    COLORS = {
+      off: [0.0, 0.0, 0.0],
+      red: [1.0, 0.0, 0.0],
+      green: [0.0, 1.0, 0.0],
+      blue: [0.0, 0.0, 1.0],
+      yellow: [1.0, 1.0, 0.0],
+      cyan: [0.0, 1.0, 1.0],
+      magenta: [1.0, 0.0, 1.0],
+      white: [1.0, 1.0, 1.0],
+    }.freeze
+
+    # @param red        [Integer] GPIO line of the red channel
+    # @param green      [Integer] GPIO line of the green channel
+    # @param blue       [Integer] GPIO line of the blue channel
+    # @param frequency  [Numeric] Hz, for all three channels
+    # @param active_low [Boolean] true for a common-anode LED
+    # @param balance    [Array<Float>] per-channel scale, 0.0..1.0 each, applied
+    #                   on top of every level asked for
+    # @param pwm        [:software, :hardware, Hash] channel kind, or a
+    #                   {red:, green:, blue:} hash of channels to borrow
+    # @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(red:, green:, blue:, frequency: PWMOutputDevice::DEFAULT_FREQUENCY,
+                   active_low: false, balance: [1.0, 1.0, 1.0], pwm: :software, chip: nil, consumer: "rgpio")
+      @owns_chip = chip.nil? && pwm == :software
+      @chip = @owns_chip ? Chip.new : chip
+      @closed = false
+      @balance = validate_triple(balance, "balance")
+      @color = [0.0, 0.0, 0.0]
+      lines = { red: red, green: green, blue: blue }
+      # One channel per colour: handing the same channel object to all three
+      # would have them overwrite each other's duty cycle.
+      channels = pwm.is_a?(Hash) ? pwm : {}
+      @channels = lines.to_h do |colour, gpio|
+        channel = PWMLED.new(gpio,
+                             frequency: frequency, active_low: active_low,
+                             pwm: channels.fetch(colour, pwm), chip: @chip, consumer: consumer)
+        [colour, channel]
+      end
+    end
+
+    # @return [Hash{Symbol=>PWMLED}] the three channels, by colour
+    attr_reader :channels
+
+    # The colour that was asked for, not the duty cycles it became — {#balance}
+    # and `active_low` both sit between the two.
+    # @return [Array<Float>] red, green, blue in 0.0..1.0
+    attr_reader :color
+
+    # @param value [Array<Float>, Symbol] an r,g,b triple, or a name from {COLORS}
+    def color=(value)
+      triple = value.is_a?(Symbol) ? named_color(value) : value
+      unless triple.is_a?(Array) && triple.size == 3
+        raise ArgumentError, "color must be a three-element array or one of #{COLORS.keys.inspect}, " \
+                             "got #{value.inspect}"
+      end
+
+      @color = validate_triple(triple, "color")
+      apply
+    end
+
+    # @return [Array<Float>] the per-channel scale in force
+    attr_reader :balance
+
+    # Re-scale the channels, keeping the colour that was asked for. Setting this
+    # while white is showing is how the calibration example works.
+    def balance=(triple)
+      @balance = validate_triple(triple, "balance")
+      apply
+    end
+
+    def red
+      @color[0]
+    end
+
+    def green
+      @color[1]
+    end
+
+    def blue
+      @color[2]
+    end
+
+    def red=(level)
+      self.color = [level, green, blue]
+    end
+
+    def green=(level)
+      self.color = [red, level, blue]
+    end
+
+    def blue=(level)
+      self.color = [red, green, level]
+    end
+
+    # Full brightness on all three channels, which is white.
+    def on
+      self.color = :white
+    end
+
+    def off
+      self.color = :off
+    end
+
+    # Invert every channel, so a dimmed colour comes back as its complement.
+    def toggle
+      self.color = @color.map { |level| 1.0 - level }
+    end
+
+    # @return [Boolean] true when any channel is lit
+    def on?
+      @color.any?(&:positive?)
+    end
+
+    alias active? on?
+
+    # Stop all three channels, and close the chip if this LED opened it.
+    # Safe to call multiple times.
+    def close
+      return if @closed
+
+      @closed = true
+      @channels.each_value(&:close)
+      @chip.close if @owns_chip
+    end
+
+    def closed?
+      @closed
+    end
+
+    private
+
+    # Push the requested colour out through the balance. The channels hold the
+    # scaled levels; #color keeps reporting what was asked for.
+    def apply
+      @channels.values.each_with_index do |channel, i|
+        channel.value = @color[i] * @balance[i]
+      end
+    end
+
+    def validate_triple(triple, what)
+      unless triple.is_a?(Array) && triple.size == 3 &&
+             triple.all? { |v| v.is_a?(Numeric) && (0.0..1.0).cover?(v) }
+        raise ArgumentError, "#{what} must be three numbers in 0.0..1.0, got #{triple.inspect}"
+      end
+
+      triple.map(&:to_f)
+    end
+
+    def named_color(name)
+      COLORS.fetch(name) do
+        raise ArgumentError, "unknown colour #{name.inspect}; known: #{COLORS.keys.inspect}"
+      end
+    end
+  end
+end

data/lib/rgpio/devices/servo.rb

@@ -0,0 +1,161 @@
+module Rgpio
+  # An RC servo, positioned by the width of a pulse repeated every 20 ms.
+  #
+  #   servo = Rgpio::Servo.new(12)
+  #   servo.max                  # one end of its travel
+  #   servo.mid                  # centre
+  #   servo.angle = 45           # or by angle
+  #   servo.detach               # stop holding the position
+  #   servo.close
+  #
+  # Pulse widths vary by servo: 1000..2000 us is the safe range every hobby
+  # servo understands, and many reach further (500..2500 us). A servo driven past
+  # its travel buzzes and heats up, so widen the range only as far as the part's
+  # datasheet allows, and by measuring rather than by trusting.
+  #
+  # Accuracy: the default {SoftwarePWM} channel places the pulse within about
+  # 6 us on an idle Pi 5, which is half a degree of travel; a busy machine can
+  # push an occasional pulse 30-80 us out (see PLAN.md). `pwm: :hardware` on
+  # GPIO12/13/18/19 removes that entirely, at the cost of a config.txt entry.
+  class Servo
+    include PWMChannel
+
+    # The frame rate every hobby servo expects.
+    DEFAULT_FREQUENCY = 50
+
+    DEFAULT_MIN_PULSE_US = 1000
+    DEFAULT_MAX_PULSE_US = 2000
+
+    # @param gpio          [Integer] GPIO line offset (BCM numbering)
+    # @param min_pulse_us  [Numeric] pulse width at value -1.0
+    # @param max_pulse_us  [Numeric] pulse width at value +1.0
+    # @param frequency     [Numeric] frame rate in Hz; ignored when `pwm:` is a
+    #                      channel object, which the caller has already configured
+    # @param min_angle     [Numeric] angle reported at value -1.0
+    # @param max_angle     [Numeric] angle reported at value +1.0
+    # @param initial_value [Float, nil] -1.0..1.0 to start there, nil to start
+    #                      detached (no pulses, so the horn is free)
+    # @param pwm           [:software, :hardware, Object] channel to drive with
+    # @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, min_pulse_us: DEFAULT_MIN_PULSE_US, max_pulse_us: DEFAULT_MAX_PULSE_US,
+                   frequency: DEFAULT_FREQUENCY, min_angle: -90, max_angle: 90,
+                   initial_value: 0.0, pwm: :software, chip: nil, consumer: "rgpio")
+      raise ArgumentError, "max_pulse_us must exceed min_pulse_us" unless max_pulse_us > min_pulse_us
+
+      @gpio = gpio
+      @min_pulse_us = min_pulse_us.to_f
+      @max_pulse_us = max_pulse_us.to_f
+      @min_angle = min_angle.to_f
+      @max_angle = max_angle.to_f
+      @value = nil
+      @closed = false
+      @pwm, @owns_pwm = resolve_pwm(pwm, gpio: gpio, frequency: frequency, chip: chip, consumer: consumer)
+      self.value = initial_value
+      @pwm.enable
+    end
+
+    # @return [Integer] the GPIO line this servo is driven from
+    attr_reader :gpio
+
+    # @return [Object] the PWM channel behind this servo
+    attr_reader :pwm
+
+    # @return [Float, nil] -1.0..1.0, or nil when detached
+    attr_reader :value
+
+    # @return [Float] pulse width at value -1.0
+    attr_reader :min_pulse_us
+
+    # @return [Float] pulse width at value +1.0
+    attr_reader :max_pulse_us
+
+    # @param position [Float, nil] -1.0..1.0, or nil to detach
+    def value=(position)
+      raise Error, "Servo on GPIO#{@gpio} is closed" if @closed
+
+      if position.nil?
+        detach
+      else
+        unless position.is_a?(Numeric) && (-1.0..1.0).cover?(position)
+          raise ArgumentError, "value must be in -1.0..1.0 or nil, got #{position.inspect}"
+        end
+
+        @value = position.to_f
+        @pwm.pulse_width_us = @min_pulse_us + ((@max_pulse_us - @min_pulse_us) * ((@value + 1.0) / 2.0))
+      end
+    end
+
+    def min
+      self.value = -1.0
+    end
+
+    def mid
+      self.value = 0.0
+    end
+
+    def max
+      self.value = 1.0
+    end
+
+    # @return [Float, nil] the current position in degrees, or nil when detached
+    def angle
+      return nil if @value.nil?
+
+      @min_angle + ((@max_angle - @min_angle) * ((@value + 1.0) / 2.0))
+    end
+
+    # @param degrees [Numeric, nil] between min_angle and max_angle
+    def angle=(degrees)
+      if degrees.nil?
+        detach
+      else
+        low, high = [@min_angle, @max_angle].minmax
+        unless degrees.is_a?(Numeric) && (low..high).cover?(degrees)
+          raise ArgumentError, "angle must be in #{low}..#{high} degrees or nil, got #{degrees.inspect}"
+        end
+
+        self.value = (((degrees - @min_angle) / (@max_angle - @min_angle)) * 2.0) - 1.0
+      end
+    end
+
+    # @return [Float, nil] the pulse width currently being sent, or nil when detached
+    def pulse_width_us
+      @value.nil? ? nil : @pwm.pulse_width_us
+    end
+
+    # Drive a pulse width directly, for calibrating a servo's real travel.
+    def pulse_width_us=(us)
+      raise ArgumentError, "pulse width must be positive, got #{us}" unless us.is_a?(Numeric) && us.positive?
+
+      @pwm.pulse_width_us = us
+      # The position no longer follows from #value, so stop claiming it does.
+      @value = nil
+    end
+
+    # Stop sending pulses. The servo stops holding its position and can be
+    # turned by hand — and stops drawing current fighting a load.
+    def detach
+      @pwm.duty_cycle = 0.0
+      @value = nil
+    end
+
+    # @return [Boolean] true while pulses are being sent
+    def attached?
+      !@value.nil?
+    end
+
+    # Stop the channel, and release it if this servo opened it.
+    # Safe to call multiple times.
+    def close
+      return if @closed
+
+      @closed = true
+      @owns_pwm ? @pwm.close : @pwm.disable
+    end
+
+    def closed?
+      @closed
+    end
+  end
+end