rgpio 0.1.0 → 0.1.1

data/lib/rgpio/devices/xpt2046.rb

@@ -0,0 +1,294 @@
+module Rgpio
+  # A resistive touch panel read through an XPT2046 (or ADS7843/TSC2046)
+  # controller over SPI — the touch half of the common 2.4"/2.8" ILI9341
+  # modules, on the same bus as the display with a chip select of its own.
+  #
+  #   touch = Rgpio::XPT2046.new(irq: 17, calibration: [...])
+  #   touch.when_touched  { |x, y| puts "#{x}, #{y}" }
+  #   touch.when_released { puts "released" }
+  #   Rgpio.pause
+  #
+  # #raw returns the converter's 12-bit readings. Turning those into screen
+  # coordinates needs a calibration, since the film's resistance and how it is
+  # mounted vary from panel to panel: {.calibration_from} fits one from a few
+  # touches on known screen points. With no calibration, #position is the raw
+  # [x, y].
+  #
+  # T_IRQ (PENIRQ) goes low while the panel is pressed. It is optional: with
+  # it, the watcher thread sleeps on a kernel edge event until a touch; without
+  # it, the watcher samples the pressure every POLL_INTERVAL.
+  class XPT2046
+    DEFAULT_SPEED_HZ = 2_000_000
+
+    # Control byte: start bit, channel (A2..A0), 12-bit mode, differential
+    # reference, and power-down between conversions with PENIRQ enabled.
+    CMD_X = 0xd0
+    CMD_Y = 0x90
+    CMD_Z1 = 0xb0
+    CMD_Z2 = 0xc0
+
+    RESOLUTION = 4096
+
+    # Pressure (on the scale of #raw's z) below which the panel counts as not
+    # touched. Lower it for a light touch, raise it if the panel reports touches
+    # nobody made.
+    DEFAULT_THRESHOLD = 300
+
+    # Readings per coordinate; the median of them is used, which rejects the
+    # odd sample taken while a finger is landing or lifting.
+    SAMPLES = 5
+
+    # How often a held touch is re-read to notice its release, and how often
+    # the pressure is polled with no T_IRQ line.
+    POLL_INTERVAL = 0.02
+
+    # How long a single edge wait blocks before the watcher rechecks whether it
+    # has been asked to stop.
+    WATCH_TIMEOUT = 0.2
+
+    # Fit a calibration from touches on known screen points: a least-squares
+    # affine map, so a panel mounted rotated or mirrored needs nothing extra.
+    # Three points not on one line is the minimum; the four corners and the
+    # centre average out the error of each touch.
+    # @param screen [Array<Array(Numeric, Numeric)>] screen [x, y] of each target
+    # @param raw    [Array<Array(Numeric, Numeric)>] raw [x, y] touched there
+    # @return [Array<Float>] [a, b, c, d, e, f] with x = a*rx + b*ry + c and
+    #   y = d*rx + e*ry + f
+    def self.calibration_from(screen, raw)
+      raise ArgumentError, "calibration needs the same number of screen and raw points" unless screen.size == raw.size
+      raise ArgumentError, "calibration needs at least three points" if screen.size < 3
+
+      rows = raw.map { |rx, ry| [rx.to_f, ry.to_f, 1.0] }
+      solve_least_squares(rows, screen.map { |sx, _| sx.to_f }) +
+        solve_least_squares(rows, screen.map { |_, sy| sy.to_f })
+    end
+
+    # Solve rows * coef ~= targets for three coefficients through the normal
+    # equations.
+    def self.solve_least_squares(rows, targets)
+      matrix = normal_equations(rows, targets)
+      3.times do |col|
+        pivot = (col...3).max_by { |row| matrix[row][col].abs }
+        raise ArgumentError, "calibration points must not all lie on one line" if matrix[pivot][col].abs < 1e-9
+
+        matrix[col], matrix[pivot] = matrix[pivot], matrix[col]
+        (0...3).each do |row|
+          next if row == col
+
+          factor = matrix[row][col] / matrix[col][col]
+          4.times { |k| matrix[row][k] -= factor * matrix[col][k] }
+        end
+      end
+      Array.new(3) { |i| matrix[i][3] / matrix[i][i] }
+    end
+
+    # @return [Array<Array<Float>>] the augmented 3x4 matrix [AᵀA | Aᵀt]
+    def self.normal_equations(rows, targets)
+      Array.new(3) do |i|
+        Array.new(3) { |j| rows.sum { |r| r[i] * r[j] } } + [rows.each_with_index.sum { |r, k| r[i] * targets[k] }]
+      end
+    end
+    private_class_method :solve_least_squares, :normal_equations
+
+    # @param irq         [Integer, nil] GPIO line wired to T_IRQ, or nil to poll
+    # @param calibration [Array<Numeric>, nil] six numbers from {.calibration_from}
+    # @param threshold   [Integer] pressure that counts as a touch
+    # @param bus         [Integer] spidev bus number
+    # @param device      [Integer] chip-select index; CE1 when the display is on CE0
+    # @param speed_hz    [Integer] clock rate
+    # @param spi         [SPI, nil] an open bus device to share, or nil to open one
+    # @param chip        [Chip, nil] chip for the T_IRQ line, or nil to open one
+    # @param consumer    [String] name shown in the kernel's request list
+    def initialize(irq: nil, calibration: nil, threshold: DEFAULT_THRESHOLD, bus: 0, device: 1,
+                   speed_hz: DEFAULT_SPEED_HZ, spi: nil, chip: nil, consumer: "rgpio")
+      self.calibration = calibration
+      @threshold = threshold
+      @callbacks = {}
+      @closed = false
+      @lock = Mutex.new
+      @owns_spi = spi.nil?
+      @spi = spi || SPI.new(bus: bus, device: device, speed_hz: speed_hz, mode: 0)
+      @irq = irq
+      return unless irq
+
+      @owns_chip = chip.nil?
+      @chip = chip || Chip.new
+      # PENIRQ is open drain; the boards have no pull-up of their own.
+      @irq_request = @chip.request_lines(offsets: [irq], direction: :input, edge: :falling, bias: :pull_up,
+                                         consumer: consumer)
+    end
+
+    # @return [SPI] the bus device readings go through
+    attr_reader :spi
+
+    # @return [Array<Float>, nil] the calibration in use
+    attr_reader :calibration
+
+    # @return [Integer] pressure that counts as a touch
+    attr_accessor :threshold
+
+    # @param coefficients [Array<Numeric>, nil] six numbers from {.calibration_from}
+    def calibration=(coefficients)
+      unless coefficients.nil? || (coefficients.is_a?(Array) && coefficients.size == 6 && coefficients.all?(Numeric))
+        raise ArgumentError, "calibration is six numbers from XPT2046.calibration_from, got #{coefficients.inspect}"
+      end
+
+      @calibration = coefficients&.map(&:to_f)&.freeze
+    end
+
+    # @return [Array(Integer, Integer, Integer)] raw x, y (0..4095) and
+    #   pressure z (0 when untouched, larger the harder the press)
+    def raw
+      raise Error, "#{self.class} is closed" if @closed
+
+      sample
+    end
+
+    # @return [Boolean] whether the panel is pressed at least #threshold hard
+    def touched?
+      raw[2] >= @threshold
+    end
+
+    # @return [Array(Integer, Integer), nil] the touch in screen coordinates,
+    #   or nil when untouched
+    def position
+      locate(raw)
+    end
+
+    # @yieldparam x [Integer] screen x of the touch
+    # @yieldparam y [Integer] screen y of the touch
+    def when_touched(&)
+      on(:touched, &)
+    end
+
+    def when_released(&)
+      on(:released, &)
+    end
+
+    # Stop the watcher, then release the T_IRQ line, the bus and the chip as
+    # far as this object opened them.
+    def close
+      return if @closed
+
+      @closed = true
+      @watching = false
+      @watcher&.join
+      @watcher = nil
+      @irq_request&.release
+      @spi.close if @owns_spi
+      @chip.close if @owns_chip
+    end
+
+    def closed?
+      @closed
+    end
+
+    private
+
+    # #raw without the closed check. The watcher reads through this: #close
+    # marks the device closed before it waits for the watcher, and the bus
+    # stays open until that wait is over, so the watcher's last poll is safe.
+    def sample
+      @lock.synchronize do
+        # Pressure is read on both sides of the position and the lower one
+        # kept: a pen landing or lifting part-way through leaves x/y unsettled
+        # (or at the untouched 0/4095), and one of the two pressures reads low.
+        z_before = read_pressure
+        # The first conversion after the drivers switch on is still settling.
+        read_channel(CMD_X)
+        x = median(SAMPLES) { read_channel(CMD_X) }
+        y = median(SAMPLES) { read_channel(CMD_Y) }
+        [x, y, [z_before, read_pressure].min]
+      end
+    end
+
+    # @return [Array(Integer, Integer), nil] screen position of a reading, or
+    #   nil when it is not pressed hard enough
+    def locate(reading)
+      x, y, z = reading
+      z >= @threshold ? to_screen(x, y) : nil
+    end
+
+    # The 12-bit result arrives MSB first after the command byte, left-aligned
+    # with three trailing zero bits.
+    def read_channel(cmd)
+      received = @spi.transfer([cmd, 0x00, 0x00])
+      ((received[1] << 8) | received[2]) >> 3
+    end
+
+    def read_pressure
+      read_channel(CMD_Z1) + (RESOLUTION - 1) - read_channel(CMD_Z2)
+    end
+
+    def median(count, &)
+      Array.new(count, &).sort[count / 2]
+    end
+
+    def to_screen(x, y)
+      return [x, y] unless @calibration
+
+      a, b, c, d, e, f = @calibration
+      [((a * x) + (b * y) + c).round, ((d * x) + (e * y) + f).round]
+    end
+
+    def on(kind, &block)
+      raise ArgumentError, "a callback block is required" unless block
+
+      @callbacks[kind] = block
+      start_watching
+      self
+    end
+
+    def start_watching
+      return if @watcher
+
+      @watching = true
+      @watcher = Thread.new { watch_loop }
+    end
+
+    def watch_loop
+      while @watching
+        touch = wait_for_touch
+        follow_touch(*touch) if touch
+      end
+    rescue StandardError => e
+      warn "rgpio: touch watcher stopped: #{e.class}: #{e.message}"
+    end
+
+    # @return [Array(Integer, Integer), nil] where the panel is pressed, once it is
+    def wait_for_touch
+      if @irq_request
+        return nil if @irq_request.read_edge_events(timeout: WATCH_TIMEOUT).empty?
+      else
+        sleep(POLL_INTERVAL)
+      end
+      locate(sample)
+    end
+
+    # Report a touch, then poll until it lifts. Conversions make PENIRQ drop
+    # again while the pen is down, so the edges queued meanwhile are discarded
+    # rather than read as new touches.
+    def follow_touch(x, y)
+      dispatch(:touched, x, y)
+      sleep(POLL_INTERVAL) while @watching && sample[2] >= @threshold
+      dispatch(:released)
+      drain_edges
+    end
+
+    def drain_edges
+      return unless @irq_request
+
+      nil until @irq_request.read_edge_events(timeout: 0).empty?
+    end
+
+    # A raising callback must not take the watcher down with it.
+    def dispatch(kind, *)
+      callback = @callbacks[kind]
+      return unless callback
+
+      callback.call(*)
+    rescue StandardError => e
+      warn "rgpio: #{self.class} #{kind} callback raised #{e.class}: #{e.message}"
+    end
+  end
+end

data/lib/rgpio/i2c.rb

@@ -17,7 +17,7 @@ module Rgpio
   #   i2c.close
   #
   # The I2C bus on the 40-pin header (GPIO2 = SDA, GPIO3 = SCL) is bus 1, and
-  # only appears once it is enabled — see README for the dtparam line.
+  # only appears once it is enabled — see docs/guide.md for the dtparam line.
   class I2C
     # ioctl numbers from <linux/i2c-dev.h>.
     I2C_SLAVE = 0x0703

data/lib/rgpio/pwm.rb

@@ -8,7 +8,7 @@ module Rgpio
   # -----------------------------
   # The RP1 PWM peripheral must be enabled via dtoverlay in
   # /boot/firmware/config.txt before the chip appears in sysfs.
-  # See README.md for the required overlay configuration.
+  # See docs/guide.md for the required overlay configuration.
   #
   # GPIO-to-PWM mapping on Pi 5 (RP1):
   #   GPIO12 → RP1 PWM chip, channel 0
@@ -34,6 +34,10 @@ module Rgpio
   class HardwarePWM
     PWM_SYSFS_ROOT = "/sys/class/pwm".freeze
 
+    # The overlay setup, linked from chip-detection errors. The gem ships no
+    # docs of its own, so the messages point at the guide on GitHub.
+    GUIDE_URL = "https://github.com/lumbermill/rgpio/blob/main/docs/guide.md#hardware-pwm-usage".freeze
+
     # Device-tree model string, used to pick the board's PWM mapping.
     BOARD_MODEL_PATH = "/proc/device-tree/model".freeze
 
@@ -251,7 +255,7 @@ module Rgpio
       chips = self.class.available_chips
       if chips.empty?
         raise PWMError, "No PWM chips found under #{PWM_SYSFS_ROOT}. " \
-                        "Is the dtoverlay configured? See README.md."
+                        "Is the dtoverlay configured? See #{GUIDE_URL}"
       end
 
       profile = PWM_CHIP_PROFILE[@board]
@@ -273,7 +277,7 @@ module Rgpio
       chip_list = chips.map { |c| "pwmchip#{c[:chip]}(npwm=#{c[:npwm]})" }.join(", ")
       raise PWMError,
             "Cannot auto-detect the header PWM chip for board #{@board.inspect}. " \
-            "Available: #{chip_list}. Pass chip: <number> explicitly (see README.md)."
+            "Available: #{chip_list}. Pass chip: <number> explicitly (see #{GUIDE_URL})."
     end
 
     def export_channel

data/lib/rgpio/spi.rb

@@ -16,7 +16,7 @@ module Rgpio
   # {#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
+  # CE0, GPIO7 = CE1), and only appears once it is enabled — see docs/guide.md for the
   # dtparam line.
   class SPI
     # ioctl numbers from <linux/spi/spidev.h>. They are built here rather than
@@ -39,6 +39,22 @@ module Rgpio
     # Clock polarity and phase, as the kernel numbers them.
     MODE_RANGE = (0..3)
 
+    # Where spidev publishes the most it accepts in one message, and what that
+    # is when the parameter cannot be read.
+    BUFSIZ_PATH = "/sys/module/spidev/parameters/bufsiz".freeze
+    DEFAULT_BUFSIZ = 4096
+
+    # @return [Integer] the largest message spidev accepts, in bytes. A module
+    #   parameter (spidev.bufsiz=), so it is the same for every bus.
+    def self.max_transfer_size
+      @max_transfer_size ||= begin
+        size = File.read(BUFSIZ_PATH).to_i
+        size.positive? ? size : DEFAULT_BUFSIZ
+      rescue SystemCallError
+        DEFAULT_BUFSIZ
+      end
+    end
+
     # @return [Integer] the ioctl request for a message of `count` transfers
     def self.message_ioctl(count)
       ioctl_number(IOC_WRITE, 0, TRANSFER_SIZE * count)
@@ -178,6 +194,28 @@ module Rgpio
       transfer(bytes).size
     end
 
+    # Send a block of any length, ignoring what comes back — for a display's
+    # pixel data, where a frame is many times what spidev takes in one message.
+    # The block goes out in messages of at most {.max_transfer_size} bytes, so
+    # chip select is released between them; a controller that keys on chip
+    # select rather than on a command (the ILI9341 does not) needs #transfer.
+    # Nothing is unpacked on the way back, which keeps a frame cheap.
+    # @param data [String] bytes to send
+    # @return [Integer] number of bytes sent
+    def send_bytes(data)
+      data = data.b
+      chunk = self.class.max_transfer_size
+      @tx_buffer ||= Fiddle::Pointer.malloc(chunk, Fiddle::RUBY_FREE)
+      (0...data.bytesize).step(chunk) do |offset|
+        part = data.byteslice(offset, chunk)
+        @tx_buffer[0, part.bytesize] = part
+        message = self.class.pack_transfer(@tx_buffer.to_i, 0, part.bytesize, @speed_hz,
+                                           bits_per_word: @bits_per_word)
+        @io.ioctl(self.class.message_ioctl(1), message)
+      end
+      data.bytesize
+    end
+
     # Clock in `count` bytes, sending zeros.
     # @return [Array<Integer>]
     def read(count)

data/lib/rgpio/version.rb

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

data/lib/rgpio.rb

@@ -10,6 +10,7 @@ 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/rotary_encoder"
 require_relative "rgpio/devices/motor"
 require_relative "rgpio/devices/pwm_channel"
 require_relative "rgpio/devices/pwm_output_device"
@@ -18,6 +19,10 @@ require_relative "rgpio/devices/servo"
 require_relative "rgpio/devices/adt7410"
 require_relative "rgpio/devices/st7032"
 require_relative "rgpio/devices/mcp3208"
+require_relative "rgpio/devices/rgb565"
+require_relative "rgpio/devices/font5x7"
+require_relative "rgpio/devices/ili9341"
+require_relative "rgpio/devices/xpt2046"
 
 # Ruby bindings for libgpiod v2 (Linux GPIO character device), bound through
 # the stdlib `fiddle`. Targets Debian Trixie (libgpiod >= 2.1) on Raspberry Pi.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rgpio
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - ITO Yosei
@@ -70,10 +70,10 @@ description: 'Control a Raspberry Pi''s hardware from Ruby. GPIO goes through li
   interface. PWM is either the hardware peripheral through sysfs or timed in Ruby
   on any line; I2C and SPI are ioctl calls on /dev/i2c-N and /dev/spidev, needing
   no libgpiod at all. On top sits a gpiozero-style device layer: LED, Button, Motor,
-  PWMLED, RGBLED, Servo, and drivers for the ADT7410 temperature sensor, ST7032 character
-  LCD and MCP3208 ADC. Bound through the stdlib `fiddle`, which is built with the
-  interpreter and so matches any Pi''s architecture, unlike the precompiled `ffi`
-  gem.'
+  PWMLED, RGBLED, Servo, RotaryEncoder, and drivers for the ADT7410 temperature sensor,
+  ST7032 character LCD, MCP3208 ADC, ILI9341 colour TFT and XPT2046 touch panel. Bound
+  through the stdlib `fiddle`, which is built with the interpreter and so matches
+  any Pi''s architecture, unlike the precompiled `ffi` gem.'
 email:
 - y-itou@lumber-mill.co.jp
 executables: []
@@ -82,7 +82,6 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
-- PLAN.md
 - README.md
 - examples/adc.rb
 - examples/adc_led.rb
@@ -100,22 +99,32 @@ files:
 - examples/pwm_led.rb
 - examples/rgb_balance.rb
 - examples/rgb_led.rb
+- examples/rotary_encoder.rb
+- examples/ruby_stack.rb
 - examples/servo.rb
 - examples/temperature.rb
+- examples/tft.rb
+- examples/touch_calibration.rb
+- examples/touch_paint.rb
 - lib/rgpio.rb
 - lib/rgpio/bytes.rb
 - lib/rgpio/chip.rb
 - lib/rgpio/devices/adt7410.rb
 - lib/rgpio/devices/device.rb
+- lib/rgpio/devices/font5x7.rb
+- lib/rgpio/devices/ili9341.rb
 - lib/rgpio/devices/input_device.rb
 - lib/rgpio/devices/mcp3208.rb
 - lib/rgpio/devices/motor.rb
 - lib/rgpio/devices/output_device.rb
 - lib/rgpio/devices/pwm_channel.rb
 - lib/rgpio/devices/pwm_output_device.rb
+- lib/rgpio/devices/rgb565.rb
 - lib/rgpio/devices/rgb_led.rb
+- lib/rgpio/devices/rotary_encoder.rb
 - lib/rgpio/devices/servo.rb
 - lib/rgpio/devices/st7032.rb
+- lib/rgpio/devices/xpt2046.rb
 - lib/rgpio/i2c.rb
 - lib/rgpio/line_request.rb
 - lib/rgpio/native.rb
@@ -128,6 +137,7 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/lumbermill/rgpio
+  documentation_uri: https://github.com/lumbermill/rgpio/blob/main/docs/guide.md
   changelog_uri: https://github.com/lumbermill/rgpio/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/lumbermill/rgpio/issues
   rubygems_mfa_required: 'true'
@@ -145,7 +155,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.23
 specification_version: 4
 summary: GPIO, PWM, I2C and SPI on Raspberry Pi, via libgpiod v2 and the Linux character
   devices