rgpio 0.1.0 → 0.1.1

data/lib/rgpio/devices/ili9341.rb

@@ -0,0 +1,338 @@
+require "monitor"
+
+module Rgpio
+  # A 240x320 colour TFT driven by an Ilitek ILI9341 over SPI — the 2.4"/2.8"
+  # modules with an XPT2046 touch controller on the same board.
+  #
+  #   lcd = Rgpio::ILI9341.new(dc: 24, reset: 25, backlight: 18)
+  #   lcd.fill(:black)
+  #   lcd.fill_rect(10, 10, 100, 50, :red)
+  #   lcd.text(10, 80, "Hello", color: :white, scale: 2)
+  #   lcd.close
+  #
+  # The controller tells a command byte from its parameters by the D/C line —
+  # low for a command, high for data — so D/C (and RESET, if wired) are GPIO
+  # outputs alongside the SPI bus. Pixels are 16-bit RGB565, high byte first.
+  #
+  # Colours are anything {RGB565.from} takes: a name such as :red, an
+  # [r, g, b] triple of 0..255, or an RGB565 Integer. Drawing is clipped to the
+  # screen.
+  #
+  # Text is drawn by {Font5x7::Drawing#text}.
+  #
+  # Every drawing call is one command sequence (window, then pixel data) held
+  # under a lock, so a touch callback on another thread can draw too.
+  class ILI9341
+    include Font5x7::Drawing
+
+    NATIVE_WIDTH = 240
+    NATIVE_HEIGHT = 320
+
+    # The Pi 5's SPI divides a 200 MHz clock by an even number, so this runs at
+    # 20 MHz (32 MHz would be 25 MHz, which garbled full-screen fills on jumper
+    # wires). Pi 4 dividers differ; pass speed_hz: to go faster on short wires.
+    DEFAULT_SPEED_HZ = 24_000_000
+
+    # Command set (datasheet section 8).
+    CMD_SWRESET = 0x01
+    CMD_SLPOUT = 0x11
+    CMD_INVOFF = 0x20
+    CMD_INVON = 0x21
+    CMD_GAMMASET = 0x26
+    CMD_DISPON = 0x29
+    CMD_CASET = 0x2a
+    CMD_PASET = 0x2b
+    CMD_RAMWR = 0x2c
+    CMD_MADCTL = 0x36
+    CMD_PIXFMT = 0x3a
+    CMD_FRMCTR1 = 0xb1
+    CMD_DFUNCTR = 0xb6
+    CMD_PWCTR1 = 0xc0
+    CMD_PWCTR2 = 0xc1
+    CMD_VMCTR1 = 0xc5
+    CMD_VMCTR2 = 0xc7
+    CMD_GMCTRP1 = 0xe0
+    CMD_GMCTRN1 = 0xe1
+
+    # Power, VCOM, frame rate and gamma for the common 2.4"/2.8" panels. These
+    # are the values the widely used Adafruit driver ships.
+    INIT_SEQUENCE = [
+      [CMD_PWCTR1, 0x23],
+      [CMD_PWCTR2, 0x10],
+      [CMD_VMCTR1, 0x3e, 0x28],
+      [CMD_VMCTR2, 0x86],
+      [CMD_PIXFMT, 0x55],                       # 16 bits per pixel
+      [CMD_FRMCTR1, 0x00, 0x18],                # 79 Hz
+      [CMD_DFUNCTR, 0x08, 0x82, 0x27],
+      [CMD_GAMMASET, 0x01],
+      [CMD_GMCTRP1, 0x0f, 0x31, 0x2b, 0x0c, 0x0e, 0x08, 0x4e, 0xf1,
+       0x37, 0x07, 0x10, 0x03, 0x0e, 0x09, 0x00,],
+      [CMD_GMCTRN1, 0x00, 0x0e, 0x14, 0x03, 0x11, 0x07, 0x31, 0xc1,
+       0x48, 0x08, 0x0f, 0x0c, 0x31, 0x36, 0x0f,],
+    ].freeze
+
+    # MADCTL bits: row/column order and exchange, and the panel's colour order.
+    MADCTL_MY = 0x80
+    MADCTL_MX = 0x40
+    MADCTL_MV = 0x20
+    MADCTL_BGR = 0x08
+
+    # Rotation in degrees => MADCTL. 0 is portrait with the FPC at the bottom.
+    ROTATIONS = {
+      0 => MADCTL_MX,
+      90 => MADCTL_MV,
+      180 => MADCTL_MY,
+      270 => MADCTL_MX | MADCTL_MY | MADCTL_MV,
+    }.freeze
+
+    # Reset pulse, and the waits the datasheet asks for after reset and
+    # sleep-out before the next command.
+    RESET_PULSE = 0.01
+    RESET_DELAY = 0.12
+    SLEEP_OUT_DELAY = 0.12
+
+    # Open a display, yielding it and closing it afterwards when a block is given.
+    # @return [ILI9341, Object] the display, or the block's value
+    def self.open(**)
+      lcd = new(**)
+      return lcd unless block_given?
+
+      begin
+        yield lcd
+      ensure
+        lcd.close
+      end
+    end
+
+    # @param dc            [Integer] GPIO line wired to D/C (sometimes DC/RS)
+    # @param reset         [Integer, nil] GPIO line wired to RESET, or nil when
+    #                      it is tied high; a software reset is sent either way
+    # @param backlight     [Integer, nil] GPIO line wired to LED, or nil when it
+    #                      is tied to 3.3 V
+    # @param backlight_pwm [Boolean] drive the backlight with SoftwarePWM so
+    #                      #backlight= takes a level, not just on/off
+    # @param rotation      [Integer] 0, 90, 180 or 270
+    # @param bgr           [Boolean] the panel's colour order; true for nearly
+    #                      every module, false if red and blue come out swapped
+    # @param bus           [Integer] spidev bus number
+    # @param device        [Integer] chip-select index
+    # @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 GPIO lines, or nil to open one
+    # @param consumer      [String] name shown in the kernel's request list
+    def initialize(dc:, reset: nil, backlight: nil, backlight_pwm: false, rotation: 0, bgr: true,
+                   bus: 0, device: 0, speed_hz: DEFAULT_SPEED_HZ, spi: nil, chip: nil, consumer: "rgpio")
+      validate_rotation(rotation)
+      @bgr = bgr
+      @lock = Monitor.new
+      @closed = false
+      @owns_spi = spi.nil?
+      @spi = spi || SPI.new(bus: bus, device: device, speed_hz: speed_hz, mode: 0)
+      @owns_chip = chip.nil?
+      @chip = chip || Chip.new
+      @dc = dc
+      @dc_request = @chip.request_lines(offsets: [dc], direction: :output, initial_value: :inactive,
+                                        consumer: consumer)
+      @dc_level = :inactive
+      @reset = reset
+      @reset_request = reset && @chip.request_lines(offsets: [reset], direction: :output,
+                                                    initial_value: :active, consumer: consumer)
+      @backlight = backlight && open_backlight(backlight, backlight_pwm, consumer)
+      @rotation = rotation
+      reset!
+      self.backlight = true if @backlight
+    end
+
+    # @return [SPI] the bus device pixels go through
+    attr_reader :spi
+
+    # @return [Integer] 0, 90, 180 or 270
+    attr_reader :rotation
+
+    # @return [Integer] screen width at the current rotation
+    def width
+      (@rotation % 180).zero? ? NATIVE_WIDTH : NATIVE_HEIGHT
+    end
+
+    # @return [Integer] screen height at the current rotation
+    def height
+      (@rotation % 180).zero? ? NATIVE_HEIGHT : NATIVE_WIDTH
+    end
+
+    # Reset the controller (by the RESET line when wired, and by command) and
+    # bring it up again. The screen content is lost.
+    def reset!
+      synchronize do
+        if @reset_request
+          @reset_request.set_value(@reset, :inactive)
+          wait(RESET_PULSE)
+          @reset_request.set_value(@reset, :active)
+        end
+        command(CMD_SWRESET)
+        wait(RESET_DELAY)
+        INIT_SEQUENCE.each { |cmd, *params| command(cmd, *params) }
+        command(CMD_MADCTL, madctl)
+        command(CMD_SLPOUT)
+        wait(SLEEP_OUT_DELAY)
+        command(CMD_DISPON)
+      end
+      self
+    end
+
+    # Turn the drawing coordinates. What is already on screen stays where it
+    # is; only what is drawn next follows the new orientation.
+    def rotation=(degrees)
+      validate_rotation(degrees)
+      synchronize do
+        @rotation = degrees
+        command(CMD_MADCTL, madctl)
+      end
+    end
+
+    # Swap every colour for its complement — some panels sold as ILI9341 need
+    # this to show colours the right way round.
+    def invert=(on)
+      synchronize { command(on ? CMD_INVON : CMD_INVOFF) }
+    end
+
+    # @param level [Boolean, Float] on/off, or 0.0..1.0 with backlight_pwm: true
+    def backlight=(level)
+      raise Error, "no backlight line was given to #{self.class}" unless @backlight
+
+      if @backlight.is_a?(PWMOutputDevice)
+        @backlight.value = { true => 1.0, false => 0.0 }.fetch(level, level)
+      elsif [true, false].include?(level)
+        @backlight.value = level
+      else
+        raise ArgumentError, "a backlight level needs backlight_pwm: true; use true or false"
+      end
+    end
+
+    # Fill the whole screen.
+    def fill(color)
+      fill_rect(0, 0, width, height, color)
+    end
+
+    # Fill a rectangle; the part off screen is skipped.
+    def fill_rect(x, y, w, h, color)
+      x0, y0, x1, y1 = clip(x, y, w, h)
+      return self unless x0
+
+      pixel = [RGB565.from(color)].pack("n")
+      synchronize do
+        set_window(x0, y0, x1, y1)
+        write_pixels(pixel * ((x1 - x0 + 1) * (y1 - y0 + 1)))
+      end
+      self
+    end
+
+    def pixel(x, y, color)
+      fill_rect(x, y, 1, 1, color)
+    end
+
+    # Copy a block of raw RGB565 pixels (two bytes each, high byte first, row by
+    # row) to the screen. The part off screen is skipped.
+    # @param data [String] w * h * 2 bytes
+    def blit(x, y, w, h, data)
+      data = data.b
+      unless data.bytesize == w * h * 2
+        raise ArgumentError, "blit of #{w}x#{h} needs #{w * h * 2} bytes, got #{data.bytesize}"
+      end
+
+      x0, y0, x1, y1 = clip(x, y, w, h)
+      return self unless x0
+
+      row_bytes = (x1 - x0 + 1) * 2
+      visible = (y0..y1).map { |row| data.byteslice((((row - y) * w) + (x0 - x)) * 2, row_bytes) }.join
+      synchronize do
+        set_window(x0, y0, x1, y1)
+        write_pixels(visible)
+      end
+      self
+    end
+
+    # Release the GPIO lines, and the bus and chip if this display opened them.
+    # The panel keeps showing its last picture while it has power.
+    def close
+      return if @closed
+
+      @closed = true
+      @backlight&.close
+      @reset_request&.release
+      @dc_request.release
+      @spi.close if @owns_spi
+      @chip.close if @owns_chip
+    end
+
+    def closed?
+      @closed
+    end
+
+    private
+
+    def synchronize(&)
+      raise Error, "#{self.class} is closed" if @closed
+
+      @lock.synchronize(&)
+    end
+
+    def validate_rotation(degrees)
+      return if ROTATIONS.key?(degrees)
+
+      raise ArgumentError, "rotation must be one of #{ROTATIONS.keys.join(", ")}, got #{degrees.inspect}"
+    end
+
+    def open_backlight(gpio, pwm, consumer)
+      pwm ? PWMLED.new(gpio, chip: @chip, consumer: consumer) : LED.new(gpio, chip: @chip, consumer: consumer)
+    end
+
+    def madctl
+      ROTATIONS.fetch(@rotation) | (@bgr ? MADCTL_BGR : 0)
+    end
+
+    # @return [Array(Integer, Integer, Integer, Integer), nil] the visible
+    #   corners x0, y0, x1, y1 (inclusive), or nil when nothing is visible
+    def clip(x, y, w, h)
+      x0 = [x, 0].max
+      y0 = [y, 0].max
+      x1 = [x + w, width].min - 1
+      y1 = [y + h, height].min - 1
+      return nil if x1 < x0 || y1 < y0
+
+      [x0, y0, x1, y1]
+    end
+
+    def set_window(x0, y0, x1, y1)
+      command(CMD_CASET, x0 >> 8, x0 & 0xff, x1 >> 8, x1 & 0xff)
+      command(CMD_PASET, y0 >> 8, y0 & 0xff, y1 >> 8, y1 & 0xff)
+      command(CMD_RAMWR)
+    end
+
+    def command(cmd, *params)
+      dc(:inactive)
+      @spi.write(cmd)
+      return if params.empty?
+
+      dc(:active)
+      @spi.write(*params)
+    end
+
+    def write_pixels(data)
+      dc(:active)
+      @spi.send_bytes(data)
+    end
+
+    # D/C only changes between a command and its data, so skip the ioctl when
+    # it is already where it needs to be.
+    def dc(level)
+      return if @dc_level == level
+
+      @dc_request.set_value(@dc, level)
+      @dc_level = level
+    end
+
+    def wait(seconds)
+      sleep(seconds)
+    end
+  end
+end

data/lib/rgpio/devices/rgb565.rb

@@ -0,0 +1,61 @@
+module Rgpio
+  # 16-bit colour as colour TFT controllers take it: 5 bits red, 6 green,
+  # 5 blue, sent high byte first.
+  #
+  #   Rgpio::RGB565.from(:orange)         # => 0xfb20
+  #   Rgpio::RGB565.from([255, 128, 0])   # => 0xfc00
+  #   Rgpio::RGB565.from(0x07e0)          # => 0x07e0
+  module RGB565
+    COLORS = {
+      black: 0x0000,
+      white: 0xffff,
+      red: 0xf800,
+      green: 0x07e0,
+      blue: 0x001f,
+      yellow: 0xffe0,
+      cyan: 0x07ff,
+      magenta: 0xf81f,
+      orange: 0xfb20, # [255, 100, 0]: 255,165,0 looks yellow on these panels
+      gray: 0x8410,
+      navy: 0x0010,
+      maroon: 0x8000,
+      olive: 0x8400,
+      purple: 0x8010,
+      teal: 0x0410,
+      dark_green: 0x0400,
+    }.freeze
+
+    # @return [Integer] 8-bit red, green and blue packed as RGB565; the low
+    #   bits that do not fit are dropped
+    def self.pack(red, green, blue)
+      [red, green, blue].each do |c|
+        next if c.is_a?(Integer) && c.between?(0, 255)
+
+        raise ArgumentError, "colour components must be in 0..255, got #{c.inspect}"
+      end
+      ((red & 0xf8) << 8) | ((green & 0xfc) << 3) | (blue >> 3)
+    end
+
+    # @param value [Symbol, String, Array<Integer>, Integer] a name from
+    #   {COLORS}, an [r, g, b] triple of 0..255, or an RGB565 Integer
+    # @return [Integer] the colour as RGB565
+    def self.from(value)
+      case value
+      when Symbol, String
+        COLORS.fetch(value.to_sym) do
+          raise ArgumentError, "unknown colour #{value.inspect}; one of #{COLORS.keys.join(", ")}"
+        end
+      when Array
+        raise ArgumentError, "a colour array is [r, g, b], got #{value.inspect}" unless value.size == 3
+
+        pack(*value)
+      when Integer
+        raise ArgumentError, "an RGB565 colour is in 0..0xffff, got #{value}" unless value.between?(0, 0xffff)
+
+        value
+      else
+        raise ArgumentError, "colour must be a name, [r, g, b] or an RGB565 Integer, got #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/rgpio/devices/rotary_encoder.rb

@@ -0,0 +1,202 @@
+module Rgpio
+  # A quadrature rotary encoder such as the KY-040 module.
+  #
+  #   encoder = Rgpio::RotaryEncoder.new(a: 17, b: 18, max_steps: 16)
+  #   encoder.when_rotated_clockwise         { puts "CW  #{encoder.steps}" }
+  #   encoder.when_rotated_counter_clockwise { puts "CCW #{encoder.steps}" }
+  #   Rgpio.pause
+  #
+  # Both phases are claimed in one request so a single watcher thread reads
+  # their edges from one kernel queue, in timestamp order. Unlike Button the
+  # watcher starts at once: steps are counted whether or not a callback is set.
+  #
+  # Each edge is decoded through the Gray-code transition table into +1 or -1,
+  # and a step is counted only when the phases come back to rest four
+  # transitions on. Contact bounce moves the phases back and forth, so its
+  # transitions cancel out and never reach a full detent. Rest is both high
+  # with pull_up: true or nil (the KY-040 has its own pull-ups), both low with
+  # pull_up: false. Clockwise is A changing before B; if a knob counts
+  # backwards, swap a: and b:.
+  #
+  # The push switch on the shaft is a separate contact: use Rgpio::Button.
+  class RotaryEncoder < Device
+    # How long a single edge wait blocks before the watcher rechecks whether it
+    # has been asked to stop.
+    WATCH_TIMEOUT = 0.2
+
+    # Direction of each move between two phase states, indexed by
+    # (previous << 2) | current with a state of (A << 1) | B. Clockwise runs
+    # 00 -> 10 -> 11 -> 01 -> 00; no change and two-bit jumps are 0.
+    TRANSITIONS = [
+      0, -1, 1, 0,
+      1, 0, 0, -1,
+      -1, 0, 0, 1,
+      0, 1, -1, 0,
+    ].freeze
+
+    # Transitions per detent.
+    TRANSITIONS_PER_STEP = 4
+
+    # @param a           [Integer] GPIO line of phase A (CLK on a KY-040)
+    # @param b           [Integer] GPIO line of phase B (DT on a KY-040)
+    # @param max_steps   [Integer] bound of #steps in either direction; 0 for none
+    # @param wrap        [Boolean] past a bound, continue from the other end
+    #                    instead of stopping there
+    # @param pull_up     [Boolean, nil] internal bias, as for InputDevice
+    # @param debounce_us [Integer] kernel debounce window in microseconds
+    # @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(a:, b:, max_steps: 16, wrap: false, pull_up: true, debounce_us: 0, chip: nil, consumer: "rgpio")
+      unless max_steps.is_a?(Integer) && max_steps >= 0
+        raise ArgumentError, "max_steps must be a non-negative Integer, got #{max_steps.inspect}"
+      end
+
+      bias = bias_for(pull_up)
+      super(chip: chip)
+      @a = a
+      @b = b
+      @max_steps = max_steps
+      @wrap = wrap
+      @rest = pull_up == false ? 0b00 : 0b11
+      @steps = 0
+      @partial = 0
+      @callbacks = {}
+      @lock = Mutex.new
+      @request = @chip.request_lines(
+        offsets: [a, b],
+        direction: :input,
+        edge: :both,
+        bias: bias,
+        debounce_us: debounce_us,
+        consumer: consumer
+      )
+      @state = (level(@a) << 1) | level(@b)
+      start_watching
+    end
+
+    # @return [Integer] GPIO lines of phase A and phase B
+    attr_reader :a, :b
+
+    # @return [Integer] the bound of #steps, or 0 when unbounded
+    attr_reader :max_steps
+
+    # @return [Integer] detents turned since start, clockwise positive
+    def steps
+      @lock.synchronize { @steps }
+    end
+
+    # Set the count, bounded (or wrapped) like rotation is.
+    def steps=(value)
+      raise ArgumentError, "steps must be an Integer, got #{value.inspect}" unless value.is_a?(Integer)
+
+      @lock.synchronize { @steps = bound(value) }
+    end
+
+    # @return [Float] #steps / #max_steps in -1.0..1.0, or 0.0 when unbounded
+    def value
+      return 0.0 if @max_steps.zero?
+
+      steps.fdiv(@max_steps)
+    end
+
+    def wrap?
+      @wrap
+    end
+
+    # Callbacks fire once per detent, also at a bound where #steps stays put.
+
+    def when_rotated(&)
+      on(:rotated, &)
+    end
+
+    def when_rotated_clockwise(&)
+      on(:clockwise, &)
+    end
+
+    def when_rotated_counter_clockwise(&)
+      on(:counter_clockwise, &)
+    end
+
+    private
+
+    def bias_for(pull_up)
+      case pull_up
+      when true then :pull_up
+      when false then :pull_down
+      when nil then :disabled
+      else raise ArgumentError, "pull_up must be true, false or nil, got #{pull_up.inspect}"
+      end
+    end
+
+    def level(offset)
+      @request.get_value(offset) == :active ? 1 : 0
+    end
+
+    def on(kind, &block)
+      raise ArgumentError, "a callback block is required" unless block
+
+      @callbacks[kind] = block
+      self
+    end
+
+    def bound(value)
+      return value if @max_steps.zero?
+      return value.clamp(-@max_steps, @max_steps) unless @wrap
+
+      span = (2 * @max_steps) + 1
+      ((value + @max_steps) % span) - @max_steps
+    end
+
+    def start_watching
+      @watching = true
+      @watcher = Thread.new { watch_loop }
+    end
+
+    def watch_loop
+      @request.read_edge_events(timeout: WATCH_TIMEOUT).each { |event| handle(event) } while @watching
+    rescue StandardError => e
+      warn "rgpio: edge watcher for GPIO#{@a}/GPIO#{@b} stopped: #{e.class}: #{e.message}"
+    end
+
+    # Fold one edge into the phase state, and count a step once the phases are
+    # back at rest. Each edge changes one bit, so the net at rest is 0 (a half
+    # turn and back, or bounce) or a full detent either way. A repeated edge
+    # for a line already at that level changes nothing and reads as 0.
+    def handle(event)
+      bit = event[:offset] == @a ? 0b10 : 0b01
+      current = event[:type] == :rising ? @state | bit : @state & ~bit
+      @partial += TRANSITIONS[(@state << 2) | current]
+      @state = current
+      return unless current == @rest
+
+      direction = @partial.abs >= TRANSITIONS_PER_STEP ? @partial <=> 0 : 0
+      @partial = 0
+      rotate(direction) unless direction.zero?
+    end
+
+    def rotate(direction)
+      @lock.synchronize { @steps = bound(@steps + direction) }
+      dispatch(direction.positive? ? :clockwise : :counter_clockwise)
+      dispatch(:rotated)
+    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} callback for GPIO#{@a}/GPIO#{@b} raised #{e.class}: #{e.message}"
+    end
+
+    # Stop the watcher before releasing the request: a wait in progress holds a
+    # pointer into the request that libgpiod would free underneath it.
+    def release_resources
+      @watching = false
+      @watcher&.join
+      @watcher = nil
+      @request.release
+    end
+  end
+end