rgpio 0.1.0

data/lib/rgpio/devices/st7032.rb

@@ -0,0 +1,234 @@
+module Rgpio
+  # A character LCD driven by a Sitronix ST7032 controller over I2C — the
+  # module in the Akizuki AQM0802 (8x2) and AQM1602 (16x2) boards.
+  #
+  #   lcd = Rgpio::ST7032.new
+  #   lcd.message = "Hello\nrgpio"
+  #   lcd.close
+  #
+  # Every transfer is a control byte followed by payload: 0x00 for an
+  # instruction, 0x40 for display data.
+  #
+  # The boost converter and contrast settings below are the 3.3 V values. The
+  # controller has no way to read the panel back, so a blank display with the
+  # backlight on is almost always contrast: raise or lower it with #contrast=.
+  class ST7032
+    DEFAULT_ADDRESS = 0x3e
+
+    # Control byte: instruction vs. display data.
+    CONTROL_COMMAND = 0x00
+    CONTROL_DATA = 0x40
+
+    # Instruction set (IS = 0).
+    CMD_CLEAR = 0x01
+    CMD_HOME = 0x02
+    CMD_ENTRY_MODE = 0x06        # increment cursor, no display shift
+    CMD_DISPLAY_OFF = 0x08
+    CMD_DISPLAY_ON = 0x0c        # display on, cursor off, blink off
+    CMD_FUNCTION_SET = 0x38      # 8-bit bus, 2 lines, normal instructions
+    CMD_SET_DDRAM = 0x80
+
+    # Extended instruction set (IS = 1).
+    CMD_FUNCTION_SET_EXT = 0x39
+    CMD_OSC_FREQUENCY = 0x14     # 1/5 bias, 183 kHz internal oscillator
+    CMD_FOLLOWER_ON = 0x6c       # follower on, amplifier ratio 4
+    CMD_CONTRAST_LOW = 0x70      # | C3..C0
+    CMD_POWER_CONTRAST_HIGH = 0x50 # | Ion << 3 | Bon << 2 | C5..C4
+    BOOSTER_ON = 0x04
+
+    # Contrast is 6 bits split across two instructions. 0x20 suits 3.3 V panels.
+    CONTRAST_RANGE = (0..0x3f)
+    DEFAULT_CONTRAST = 0x20
+
+    # DDRAM address of each row's first column.
+    ROW_OFFSETS = [0x00, 0x40].freeze
+
+    # Instructions need 26.3 us to execute; clear and home need 1.08 ms. The
+    # follower circuit needs time to stabilise before the panel is driven.
+    EXECUTION_DELAY = 0.000_05
+    CLEAR_DELAY = 0.002
+    POWER_DELAY = 0.2
+
+    # Open a display, yielding it and closing it afterwards when a block is given.
+    # @return [ST7032, 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 address  [Integer] 7-bit address; the ST7032 is fixed at 0x3e
+    # @param bus      [Integer] i2c-dev bus number
+    # @param columns  [Integer] characters per row (8 for AQM0802, 16 for AQM1602)
+    # @param rows     [Integer] number of rows
+    # @param contrast [Integer] 0..63
+    # @param booster  [Boolean] enable the internal boost converter (needed at 3.3 V)
+    # @param i2c      [I2C, nil] an open device to share, or nil to open one
+    def initialize(address: DEFAULT_ADDRESS, bus: I2C::DEFAULT_BUS, columns: 8, rows: 2,
+                   contrast: DEFAULT_CONTRAST, booster: true, i2c: nil)
+      raise ArgumentError, "rows must be 1 or 2, got #{rows}" unless (1..ROW_OFFSETS.size).cover?(rows)
+
+      @owns_i2c = i2c.nil?
+      @i2c = i2c || I2C.new(address: address, bus: bus)
+      @columns = columns
+      @rows = rows
+      @contrast = validate_contrast(contrast)
+      @booster = booster
+      @closed = false
+      reset
+    end
+
+    # @return [I2C] the bus device this display is written through
+    attr_reader :i2c
+
+    # @return [Integer] characters per row
+    attr_reader :columns
+
+    # @return [Integer] number of rows
+    attr_reader :rows
+
+    # @return [Integer] current contrast setting, 0..63
+    attr_reader :contrast
+
+    # Run the power-on initialisation sequence. Called by .new; call it again
+    # after the panel has been power-cycled behind the driver's back.
+    def reset
+      command(CMD_FUNCTION_SET)
+      command(CMD_FUNCTION_SET_EXT)
+      command(CMD_OSC_FREQUENCY)
+      apply_contrast
+      command(CMD_FOLLOWER_ON)
+      sleep POWER_DELAY
+      command(CMD_FUNCTION_SET)
+      command(CMD_DISPLAY_ON)
+      command(CMD_ENTRY_MODE)
+      clear
+      self
+    end
+
+    # Blank the display and return the cursor to the top left.
+    def clear
+      command(CMD_CLEAR, delay: CLEAR_DELAY)
+      @col = 0
+      @row = 0
+      self
+    end
+
+    # Return the cursor to the top left, leaving the contents alone.
+    def home
+      command(CMD_HOME, delay: CLEAR_DELAY)
+      @col = 0
+      @row = 0
+      self
+    end
+
+    # Move the cursor. Out-of-range positions raise rather than wrapping, since
+    # the DDRAM address they would land on is rarely what the caller meant.
+    # @param col [Integer] 0-based column
+    # @param row [Integer] 0-based row
+    def move_to(col, row = 0)
+      raise ArgumentError, "column must be in 0...#{@columns}, got #{col}" unless (0...@columns).cover?(col)
+      raise ArgumentError, "row must be in 0...#{@rows}, got #{row}" unless (0...@rows).cover?(row)
+
+      command(CMD_SET_DDRAM | (ROW_OFFSETS[row] + col))
+      @col = col
+      @row = row
+      self
+    end
+
+    alias set_cursor move_to
+
+    # Write text at the cursor. A newline moves to the start of the next row;
+    # text that would run past the last column of a row is dropped, as the
+    # controller would otherwise scatter it into the other row's DDRAM.
+    def print(text)
+      text.to_s.split("\n", -1).each_with_index do |line, index|
+        if index.positive?
+          break if @row + 1 >= @rows
+
+          move_to(0, @row + 1)
+        end
+        write_data(line)
+      end
+      self
+    end
+
+    # Replace the whole display with +text+ (clear, then print).
+    def message=(text)
+      clear
+      print(text)
+    end
+
+    def display_on
+      command(CMD_DISPLAY_ON)
+      self
+    end
+
+    def display_off
+      command(CMD_DISPLAY_OFF)
+      self
+    end
+
+    # @param value [Integer] 0..63
+    def contrast=(value)
+      @contrast = validate_contrast(value)
+      command(CMD_FUNCTION_SET_EXT)
+      apply_contrast
+      command(CMD_FUNCTION_SET)
+      value
+    end
+
+    # Send a raw instruction byte.
+    def command(byte, delay: EXECUTION_DELAY)
+      @i2c.write(CONTROL_COMMAND, byte)
+      sleep delay
+      self
+    end
+
+    # Send display data (a String is taken as its bytes — the ST7032 character
+    # ROM is ASCII in 0x20..0x7d, so non-ASCII text needs a custom mapping).
+    def write_data(text)
+      bytes = text.is_a?(String) ? text.b.bytes : Array(text)
+      bytes = bytes.first(@columns - @col)
+      return self if bytes.empty?
+
+      @i2c.write(CONTROL_DATA, bytes)
+      @col += bytes.size
+      sleep EXECUTION_DELAY
+      self
+    end
+
+    # Close the bus device, but only if this display opened it. The panel keeps
+    # showing whatever was written last.
+    def close
+      return if @closed
+
+      @closed = true
+      @i2c.close if @owns_i2c
+    end
+
+    def closed?
+      @closed
+    end
+
+    private
+
+    def validate_contrast(value)
+      raise ArgumentError, "contrast must be in 0..63, got #{value}" unless CONTRAST_RANGE.cover?(value)
+
+      value
+    end
+
+    # Both halves of the contrast value live in the extended instruction set,
+    # so the caller must have selected it first.
+    def apply_contrast
+      command(CMD_CONTRAST_LOW | (@contrast & 0x0f))
+      command(CMD_POWER_CONTRAST_HIGH | (@booster ? BOOSTER_ON : 0) | ((@contrast >> 4) & 0x03))
+    end
+  end
+end

data/lib/rgpio/i2c.rb

@@ -0,0 +1,175 @@
+require "fiddle"
+
+module Rgpio
+  # An I2C device on a Linux i2c-dev bus (/dev/i2c-N).
+  #
+  # No libgpiod involved: the kernel exposes the whole bus through a character
+  # device, so this works even where Rgpio.available? is false.
+  #
+  # Usage (block form — recommended):
+  #   Rgpio::I2C.open(address: 0x48) do |i2c|
+  #     msb, lsb = i2c.read_register(0x00, 2)
+  #   end
+  #
+  # Usage (manual):
+  #   i2c = Rgpio::I2C.new(address: 0x3e)
+  #   i2c.write(0x00, 0x38)
+  #   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.
+  class I2C
+    # ioctl numbers from <linux/i2c-dev.h>.
+    I2C_SLAVE = 0x0703
+    I2C_SLAVE_FORCE = 0x0706
+    I2C_RDWR = 0x0707
+
+    # i2c_msg flag: this message is a read (from <linux/i2c.h>).
+    I2C_M_RD = 0x0001
+
+    # The 40-pin header bus. Bus 0 exists on some boards but is reserved for
+    # HAT EEPROMs and camera/display peripherals.
+    DEFAULT_BUS = 1
+
+    # Valid 7-bit addressing range: below 0x08 and above 0x77 is reserved.
+    ADDRESS_RANGE = (0x08..0x77)
+
+    # struct i2c_msg is { __u16 addr; __u16 flags; __u16 len; __u8 *buf; }:
+    # three shorts, then the pointer on its natural alignment (offset 8 on both
+    # 32- and 64-bit ARM, since the shorts are padded out to it).
+    MSG_BUF_OFFSET = 8
+    MSG_SIZE = MSG_BUF_OFFSET + Fiddle::SIZEOF_VOIDP
+
+    # struct i2c_rdwr_ioctl_data is { struct i2c_msg *msgs; __u32 nmsgs; },
+    # rounded up to pointer alignment.
+    RDWR_SIZE = Fiddle::SIZEOF_VOIDP * 2
+
+    # Pack a struct i2c_msg. Kept at class level so the layout can be checked
+    # without a bus present.
+    # @param buf_addr [Integer] address of the message's data buffer
+    # @return [String]
+    def self.pack_msg(address, flags, len, buf_addr)
+      [address, flags, len].pack("SSS").ljust(MSG_BUF_OFFSET, "\0") + [buf_addr].pack("J")
+    end
+
+    # Pack a struct i2c_rdwr_ioctl_data pointing at `count` messages.
+    # @param msgs_addr [Integer] address of the message array
+    # @return [String]
+    def self.pack_rdwr(msgs_addr, count)
+      ([msgs_addr].pack("J") + [count].pack("L")).ljust(RDWR_SIZE, "\0")
+    end
+
+    # @return [Array<Integer>] bus numbers with a /dev/i2c-N node, ascending
+    def self.buses
+      Dir.glob("/dev/i2c-*").filter_map { |path| path[%r{/dev/i2c-(\d+)\z}, 1]&.to_i }.sort
+    end
+
+    # Open a device, yielding it and closing it afterwards when a block is given.
+    # @return [I2C, Object] the device, or the block's value
+    def self.open(address:, bus: DEFAULT_BUS)
+      i2c = new(address: address, bus: bus)
+      return i2c unless block_given?
+
+      begin
+        yield i2c
+      ensure
+        i2c.close
+      end
+    end
+
+    # @param address [Integer] 7-bit device address (e.g. 0x48)
+    # @param bus     [Integer] i2c-dev bus number; 1 is the 40-pin header
+    # @param force   [Boolean] claim the address even if a kernel driver holds it
+    def initialize(address:, bus: DEFAULT_BUS, force: false)
+      unless ADDRESS_RANGE.cover?(address)
+        raise ArgumentError,
+              format("address must be in 0x%02x..0x%02x, got 0x%02x", ADDRESS_RANGE.first, ADDRESS_RANGE.last, address)
+      end
+
+      @address = address
+      @bus = bus
+      @path = "/dev/i2c-#{bus}"
+      unless File.exist?(@path)
+        raise I2CError,
+              "#{@path} not found. Enable the header bus with `dtparam=i2c_arm=on` in /boot/firmware/config.txt"
+      end
+
+      @io = File.open(@path, "r+b")
+      @io.ioctl(force ? I2C_SLAVE_FORCE : I2C_SLAVE, @address)
+      @closed = false
+    end
+
+    # @return [Integer] 7-bit device address
+    attr_reader :address
+
+    # @return [Integer] i2c-dev bus number
+    attr_reader :bus
+
+    # @return [String] path of the bus character device
+    attr_reader :path
+
+    # Write bytes in a single transaction.
+    # @param bytes [Array<Integer>, String] byte values, or a packed String
+    # @return [Integer] number of bytes written
+    def write(*bytes)
+      @io.syswrite(Bytes.pack(bytes))
+    end
+
+    # Read bytes in a single transaction.
+    # @param count [Integer] how many bytes to read
+    # @return [Array<Integer>]
+    def read(count)
+      @io.sysread(count).unpack("C*")
+    end
+
+    # Write, then read without releasing the bus (repeated START). Devices with
+    # an address pointer need this: a STOP between the two halves lets another
+    # master move the pointer in between.
+    # @param bytes [Array<Integer>, String] bytes to write first
+    # @param count [Integer] how many bytes to read back
+    # @return [Array<Integer>]
+    def write_read(bytes, count)
+      out = Bytes.pack(bytes)
+      raise ArgumentError, "write_read needs at least one byte to write" if out.empty?
+      raise ArgumentError, "count must be positive, got #{count}" unless count.positive?
+
+      wbuf = buffer(out)
+      rbuf = Fiddle::Pointer.malloc(count, Fiddle::RUBY_FREE)
+      msgs = buffer(self.class.pack_msg(@address, 0, out.bytesize, wbuf.to_i) +
+                    self.class.pack_msg(@address, I2C_M_RD, count, rbuf.to_i))
+      @io.ioctl(I2C_RDWR, self.class.pack_rdwr(msgs.to_i, 2))
+      rbuf[0, count].unpack("C*")
+    end
+
+    # Read `count` bytes from a register, addressing it with a repeated START.
+    # @return [Array<Integer>]
+    def read_register(register, count = 1)
+      write_read([register], count)
+    end
+
+    # Write bytes to a register in one transaction.
+    # @return [Integer] number of bytes written
+    def write_register(register, *bytes)
+      write(register, *bytes)
+    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/line_request.rb

@@ -0,0 +1,184 @@
+module Rgpio
+  # Holds an active kernel line request returned by Chip#request_lines.
+  # Must be released when done via #release (or the block form of Chip.open).
+  #
+  # Example — output:
+  #   request = chip.request_lines(offsets: [17], direction: :output)
+  #   request.set_value(17, :active)
+  #   request.release
+  #
+  # Example — input with edge detection (blocking):
+  #   request = chip.request_lines(offsets: [27], direction: :input,
+  #                                edge: :both, bias: :pull_up)
+  #   loop do
+  #     events = request.read_edge_events(timeout: 5.0)
+  #     events.each { |e| puts "#{e[:type]} on offset #{e[:offset]}" }
+  #   end
+  #   request.release
+  class LineRequest
+    # @param request_ptr [Fiddle::Pointer] raw gpiod_line_request*
+    # @param offsets     [Array<Integer>] offsets included in this request
+    def initialize(request_ptr, offsets)
+      @request_ptr = request_ptr
+      @offsets = offsets.freeze
+    end
+
+    attr_reader :offsets
+
+    # Read the current value of a single line.
+    #
+    # @param offset [Integer] GPIO line offset (must be in #offsets)
+    # @return [:active, :inactive]
+    # @raise [SystemCallError] on error
+    def get_value(offset)
+      assert_active!
+      result = Native.gpiod_line_request_get_value(@request_ptr, offset)
+      case result
+      when Native::LINE_VALUE_ACTIVE   then :active
+      when Native::LINE_VALUE_INACTIVE then :inactive
+      else
+        raise SystemCallError.new("gpiod_line_request_get_value(offset=#{offset})", Native.errno)
+      end
+    end
+
+    # Set the output value of a single line.
+    #
+    # @param offset [Integer] GPIO line offset
+    # @param value  [:active, :inactive, 1, 0] desired output level
+    # @raise [SystemCallError] on error
+    def set_value(offset, value)
+      assert_active!
+      v = normalize_value(value)
+      ret = Native.gpiod_line_request_set_value(@request_ptr, offset, v)
+      raise SystemCallError.new("gpiod_line_request_set_value(offset=#{offset})", Native.errno) if ret == -1
+    end
+
+    # Read several lines atomically in a single ioctl.
+    #
+    # @param offsets [Array<Integer>] offsets to read; defaults to every offset
+    #                in this request. Must be a subset of #offsets.
+    # @return [Hash{Integer=>Symbol}] offset => :active / :inactive, in the
+    #                order given
+    # @raise [SystemCallError] on error
+    def get_values(offsets = @offsets)
+      assert_active!
+      offs = Array(offsets)
+      return {} if offs.empty?
+
+      offsets_ptr = Native.uint32_buffer(offs)
+      values_ptr  = Native.int_output_buffer(offs.size)
+      ret = Native.gpiod_line_request_get_values_subset(@request_ptr, offs.size, offsets_ptr, values_ptr)
+      raise SystemCallError.new("gpiod_line_request_get_values_subset", Native.errno) if ret == -1
+
+      raw = Native.read_int_buffer(values_ptr, offs.size)
+      offs.zip(raw).to_h { |offset, value| [offset, decode_value(value, offset)] }
+    end
+
+    # Set several output lines atomically in a single ioctl.
+    #
+    # @param values [Hash{Integer=>Object}] offset => desired level
+    #               (:active/:inactive/1/0/true/false). Offsets must be a subset
+    #               of #offsets.
+    # @raise [ArgumentError] when values is not a Hash
+    # @raise [SystemCallError] on error
+    def set_values(values)
+      assert_active!
+      raise ArgumentError, "set_values expects a Hash of offset => value, got #{values.class}" unless values.is_a?(Hash)
+      return if values.empty?
+
+      offs = values.keys
+      vals = values.values.map { |v| normalize_value(v) }
+      offsets_ptr = Native.uint32_buffer(offs)
+      values_ptr  = Native.int_buffer(vals)
+      ret = Native.gpiod_line_request_set_values_subset(@request_ptr, offs.size, offsets_ptr, values_ptr)
+      raise SystemCallError.new("gpiod_line_request_set_values_subset", Native.errno) if ret == -1
+    end
+
+    # Wait for edge events on any line in this request.
+    #
+    # @param timeout [Float, nil] seconds to wait; nil = block indefinitely;
+    #                             0 = non-blocking poll
+    # @return [Boolean] true if at least one event is ready
+    # @raise [SystemCallError] on error
+    def wait_edge_events(timeout: nil)
+      assert_active!
+      timeout_ns = if timeout.nil?
+                     -1
+                   else
+                     (timeout * 1_000_000_000).to_i
+                   end
+      ret = Native.gpiod_line_request_wait_edge_events(@request_ptr, timeout_ns)
+      raise SystemCallError.new("gpiod_line_request_wait_edge_events", Native.errno) if ret == -1
+
+      ret == 1
+    end
+
+    # Read pending edge events into an array.
+    # Typically called after #wait_edge_events returns true.
+    #
+    # @param timeout [Float, nil] wait up to this many seconds before reading
+    # @param capacity [Integer] maximum events to read per call
+    # @return [Array<Hash>] array of event hashes:
+    #   { type: :rising | :falling, offset: Integer, timestamp_ns: Integer }
+    def read_edge_events(timeout: nil, capacity: 16)
+      assert_active!
+      return [] unless wait_edge_events(timeout: timeout)
+
+      buf = nil
+      begin
+        buf = Native.gpiod_edge_event_buffer_new(capacity)
+        raise Error, "gpiod_edge_event_buffer_new failed" if buf.null?
+
+        n = Native.gpiod_line_request_read_edge_events(@request_ptr, buf)
+        raise SystemCallError.new("gpiod_line_request_read_edge_events", Native.errno) if n == -1
+
+        Array.new(n) do |i|
+          ev = Native.gpiod_edge_event_buffer_get_event(buf, i)
+          type_int = Native.gpiod_edge_event_get_event_type(ev)
+          {
+            type: type_int == Native::EDGE_EVENT_RISING_EDGE ? :rising : :falling,
+            offset: Native.gpiod_edge_event_get_line_offset(ev),
+            timestamp_ns: Native.gpiod_edge_event_get_timestamp_ns(ev),
+          }
+        end
+      ensure
+        Native.gpiod_edge_event_buffer_free(buf) if buf && !buf.null?
+      end
+    end
+
+    # Release the kernel line request. Safe to call multiple times.
+    def release
+      return unless @request_ptr && !@request_ptr.null?
+
+      Native.gpiod_line_request_release(@request_ptr)
+      @request_ptr = nil
+    end
+
+    def released?
+      @request_ptr.nil?
+    end
+
+    private
+
+    def assert_active!
+      raise Error, "LineRequest has already been released" if released?
+    end
+
+    def normalize_value(value)
+      case value
+      when :active,   1, true  then Native::LINE_VALUE_ACTIVE
+      when :inactive, 0, false then Native::LINE_VALUE_INACTIVE
+      else raise ArgumentError, "Unknown line value: #{value.inspect}"
+      end
+    end
+
+    def decode_value(int, offset)
+      case int
+      when Native::LINE_VALUE_ACTIVE   then :active
+      when Native::LINE_VALUE_INACTIVE then :inactive
+      else
+        raise SystemCallError.new("gpiod_line_request_get_values_subset(offset=#{offset})", Native.errno)
+      end
+    end
+  end
+end