rgpio 0.1.0

data/lib/rgpio/chip.rb

@@ -0,0 +1,271 @@
+module Rgpio
+  # Represents an open GPIO chip (e.g. /dev/gpiochip0).
+  #
+  # Usage (block form — recommended, ensures close on exit):
+  #   # Auto-detect the GPIO controller wired to the 40-pin header
+  #   # (works on Pi 5 / Pi 4 / Pi Zero without code changes):
+  #   Rgpio::Chip.open do |chip|
+  #     request = chip.request_lines(offsets: [17], direction: :output)
+  #     # ...
+  #   end
+  #
+  #   # Or open a specific device explicitly:
+  #   Rgpio::Chip.open("/dev/gpiochip0") { |chip| ... }
+  #
+  # Usage (manual):
+  #   chip = Rgpio::Chip.new        # auto-detect
+  #   # ...
+  #   chip.close
+  class Chip
+    # Glob matching every GPIO character device exposed by the kernel.
+    DEVICE_GLOB = "/dev/gpiochip*".freeze
+
+    # Labels of the GPIO controller wired to the 40-pin header, in detection
+    # priority order (newest SoC first). The label comes from the chip's
+    # info record (gpiod_chip_info_get_label) and is stable per SoC family:
+    #
+    #   pinctrl-rp1     → Raspberry Pi 5 (RP1 I/O controller)
+    #   pinctrl-bcm2711 → Raspberry Pi 4 / 400
+    #   pinctrl-bcm2835 → Pi Zero / Zero W / Zero 2 W / Pi 1 / 2 / 3
+    #
+    # On Pi 5 the SoC also exposes several "gpio-brcmstb@..." chips that are
+    # NOT on the header — matching by label avoids selecting those.
+    HEADER_CHIP_LABELS = %w[
+      pinctrl-rp1
+      pinctrl-bcm2711
+      pinctrl-bcm2835
+    ].freeze
+
+    # @param path [String, nil] path to the GPIO chip device. When nil
+    #   (the default), the header GPIO controller is auto-detected.
+    def initialize(path = nil)
+      Rgpio.assert_available!
+      @path = path || self.class.detect_path
+      @chip_ptr = Native.gpiod_chip_open(@path)
+      return unless @chip_ptr.null?
+
+      raise SystemCallError.new("gpiod_chip_open(#{@path})", Native.errno)
+    end
+
+    # Open a chip, yield it to the block, then close it.
+    # With no path, auto-detects the header GPIO controller.
+    def self.open(path = nil, &block)
+      chip = new(path)
+      block.call(chip)
+    ensure
+      chip&.close
+    end
+
+    # Enumerate every GPIO chip present on the system.
+    #
+    # @return [Array<Hash>] one entry per chip, sorted by device index:
+    #   { path:, name:, label:, num_lines: }
+    def self.list
+      Rgpio.assert_available!
+      Dir.glob(DEVICE_GLOB).sort_by { |p| device_index(p) }.filter_map do |path|
+        chip = new(path)
+        begin
+          { path: path, name: chip.name, label: chip.label, num_lines: chip.num_lines }
+        ensure
+          chip.close
+        end
+      rescue SystemCallError
+        # Skip chips we cannot open (e.g. permissions, races) rather than abort.
+        nil
+      end
+    end
+
+    # Resolve the device path of the GPIO controller wired to the 40-pin
+    # header. Pass `chips` to test the selection logic without hardware.
+    #
+    # @param chips [Array<Hash>] chip records as returned by {.list}
+    # @return [String] device path (e.g. "/dev/gpiochip0")
+    # @raise [NotAvailableError] when no usable GPIO chip is found
+    def self.detect_path(chips = list)
+      if chips.empty?
+        raise NotAvailableError,
+              "No GPIO chips found under #{DEVICE_GLOB}. Is this a Raspberry Pi?"
+      end
+      select_header_chip(chips).fetch(:path)
+    end
+
+    # Pick the header GPIO controller from a list of chip records.
+    # Prefers a known SoC label; falls back to the chip with the most lines
+    # (the header controller is, in practice, the largest one).
+    #
+    # @param chips [Array<Hash>] chip records as returned by {.list}
+    # @return [Hash] the selected chip record
+    def self.select_header_chip(chips)
+      HEADER_CHIP_LABELS.each do |label|
+        match = chips.find { |c| c[:label] == label }
+        return match if match
+      end
+      chips.max_by { |c| c[:num_lines] }
+    end
+
+    # Numeric index of a gpiochip device path ("/dev/gpiochip10" → 10),
+    # so chips sort numerically rather than lexically.
+    def self.device_index(path)
+      File.basename(path).delete_prefix("gpiochip").to_i
+    end
+
+    # @return [String] device path this chip was opened with
+    attr_reader :path
+
+    # @return [String] kernel name of the chip (e.g. "gpiochip0")
+    def name
+      with_info { |info| Native.gpiod_chip_info_get_name(info) }
+    end
+
+    # @return [String] label identifying the GPIO controller
+    #   (e.g. "pinctrl-rp1" on Raspberry Pi 5)
+    def label
+      with_info { |info| Native.gpiod_chip_info_get_label(info) }
+    end
+
+    # @return [Integer] total number of GPIO lines on this chip
+    def num_lines
+      with_info { |info| Native.gpiod_chip_info_get_num_lines(info) }
+    end
+
+    # Request one or more lines for exclusive use.
+    #
+    # @param offsets  [Array<Integer>] GPIO line offsets to request
+    # @param direction [:input, :output] line direction
+    # @param edge      [:none, :rising, :falling, :both] edge detection
+    #                  (only meaningful when direction is :input)
+    # @param bias      [:as_is, :disabled, :pull_up, :pull_down]
+    # @param active_low [Boolean] invert active/inactive logic
+    # @param debounce_us [Integer] kernel-level debounce period in microseconds
+    #                    (0 = disabled). Suppresses bounces shorter than this window.
+    #                    Typical value for mechanical buttons: 5_000 (5 ms).
+    # @param initial_value [:active, :inactive] initial output value
+    #                       (only meaningful when direction is :output)
+    # @param consumer [String] name shown in kernel request list (optional)
+    # @return [LineRequest]
+    def request_lines(offsets:, direction:, edge: :none, bias: :as_is,
+                      active_low: false, debounce_us: 0, initial_value: :inactive, consumer: nil)
+      assert_open!
+
+      settings_ptr = Native.gpiod_line_settings_new
+      raise Error, "gpiod_line_settings_new failed" if settings_ptr.null?
+
+      begin
+        check! Native.gpiod_line_settings_set_direction(settings_ptr, direction_value(direction)),
+               "gpiod_line_settings_set_direction"
+        check! Native.gpiod_line_settings_set_edge_detection(settings_ptr, edge_value(edge)),
+               "gpiod_line_settings_set_edge_detection"
+        check! Native.gpiod_line_settings_set_bias(settings_ptr, bias_value(bias)),
+               "gpiod_line_settings_set_bias"
+        Native.gpiod_line_settings_set_active_low(settings_ptr, active_low)
+        if debounce_us&.positive?
+          check! Native.gpiod_line_settings_set_debounce_period_us(settings_ptr, debounce_us),
+                 "gpiod_line_settings_set_debounce_period_us"
+        end
+        if direction == :output
+          check! Native.gpiod_line_settings_set_output_value(
+            settings_ptr, initial_value == :active ? Native::LINE_VALUE_ACTIVE : Native::LINE_VALUE_INACTIVE
+          ), "gpiod_line_settings_set_output_value"
+        end
+
+        line_config_ptr = Native.gpiod_line_config_new
+        raise Error, "gpiod_line_config_new failed" if line_config_ptr.null?
+
+        begin
+          offsets_arr = Array(offsets)
+          offsets_ptr = Native.uint32_buffer(offsets_arr)
+
+          check! Native.gpiod_line_config_add_line_settings(
+            line_config_ptr, offsets_ptr, offsets_arr.size, settings_ptr
+          ), "gpiod_line_config_add_line_settings"
+
+          req_config_ptr = build_request_config(consumer)
+          begin
+            request_ptr = Native.gpiod_chip_request_lines(@chip_ptr, req_config_ptr, line_config_ptr)
+            raise SystemCallError.new("gpiod_chip_request_lines", Native.errno) if request_ptr.null?
+
+            LineRequest.new(request_ptr, offsets_arr)
+          ensure
+            Native.gpiod_request_config_free(req_config_ptr) unless req_config_ptr.null?
+          end
+        ensure
+          Native.gpiod_line_config_free(line_config_ptr)
+        end
+      ensure
+        Native.gpiod_line_settings_free(settings_ptr)
+      end
+    end
+
+    # Close the chip and release all kernel resources.
+    # Safe to call multiple times.
+    def close
+      return unless @chip_ptr && !@chip_ptr.null?
+
+      Native.gpiod_chip_close(@chip_ptr)
+      @chip_ptr = nil
+    end
+
+    def closed?
+      @chip_ptr.nil?
+    end
+
+    private
+
+    def assert_open!
+      raise Error, "Chip is already closed" if closed?
+    end
+
+    def with_info
+      assert_open!
+      info = Native.gpiod_chip_get_info(@chip_ptr)
+      raise SystemCallError.new("gpiod_chip_get_info", Native.errno) if info.null?
+
+      begin
+        yield info
+      ensure
+        Native.gpiod_chip_info_free(info)
+      end
+    end
+
+    def build_request_config(consumer)
+      ptr = Native.gpiod_request_config_new
+      return Native::NULL if ptr.null?
+
+      Native.gpiod_request_config_set_consumer(ptr, consumer) if consumer
+      ptr
+    end
+
+    def check!(ret, fn_name)
+      raise SystemCallError.new(fn_name, Native.errno) if ret == -1
+    end
+
+    def direction_value(sym)
+      case sym
+      when :as_is  then Native::LINE_DIRECTION_AS_IS
+      when :input  then Native::LINE_DIRECTION_INPUT
+      when :output then Native::LINE_DIRECTION_OUTPUT
+      else raise ArgumentError, "Unknown direction: #{sym.inspect}"
+      end
+    end
+
+    def edge_value(sym)
+      case sym
+      when :none    then Native::LINE_EDGE_NONE
+      when :rising  then Native::LINE_EDGE_RISING
+      when :falling then Native::LINE_EDGE_FALLING
+      when :both    then Native::LINE_EDGE_BOTH
+      else raise ArgumentError, "Unknown edge: #{sym.inspect}"
+      end
+    end
+
+    def bias_value(sym)
+      case sym
+      when :as_is      then Native::LINE_BIAS_AS_IS
+      when :disabled   then Native::LINE_BIAS_DISABLED
+      when :pull_up    then Native::LINE_BIAS_PULL_UP
+      when :pull_down  then Native::LINE_BIAS_PULL_DOWN
+      else raise ArgumentError, "Unknown bias: #{sym.inspect}"
+      end
+    end
+  end
+end

data/lib/rgpio/devices/adt7410.rb

@@ -0,0 +1,116 @@
+module Rgpio
+  # An ADT7410 I2C temperature sensor (Analog Devices).
+  #
+  #   sensor = Rgpio::ADT7410.new
+  #   puts sensor.temperature   # => 24.5  (degrees Celsius)
+  #   sensor.close
+  #
+  # The address is set by the A1/A0 pins: 0x48 with both tied low (the default
+  # on the common breakout boards), through 0x4b with both high.
+  #
+  # The sensor powers up in 13-bit mode, which resolves 0.0625 degC and is what
+  # the datasheet calls the default; 16-bit mode resolves 0.0078 degC and is
+  # selected with `resolution: 16`.
+  class ADT7410
+    DEFAULT_ADDRESS = 0x48
+
+    # Register map (the subset this driver uses).
+    REG_TEMPERATURE = 0x00
+    REG_STATUS = 0x02
+    REG_CONFIG = 0x03
+    REG_ID = 0x0b
+
+    # Configuration register bit 7 selects 16-bit resolution.
+    CONFIG_RESOLUTION_16 = 0x80
+
+    # Upper five bits of the ID register are the manufacturer ID; the lower
+    # three are the silicon revision.
+    MANUFACTURER_ID = 0b11001
+
+    # Counts per degree Celsius, per resolution. In 13-bit mode the three low
+    # bits of the register hold the Tcrit/Thigh/Tlow flags instead of data.
+    COUNTS_PER_DEGREE = { 13 => 16.0, 16 => 128.0 }.freeze
+
+    # The first conversion after power-up takes 240 ms; reading before it has
+    # finished returns the 0 degC reset value rather than an error.
+    CONVERSION_TIME = 0.24
+
+    # @param address    [Integer] 7-bit address, 0x48..0x4b
+    # @param bus        [Integer] i2c-dev bus number
+    # @param resolution [Integer] 13 or 16 bits
+    # @param i2c        [I2C, nil] an open device to share, or nil to open one
+    def initialize(address: DEFAULT_ADDRESS, bus: I2C::DEFAULT_BUS, resolution: 13, i2c: nil)
+      @owns_i2c = i2c.nil?
+      @i2c = i2c || I2C.new(address: address, bus: bus)
+      @closed = false
+      self.resolution = resolution
+    end
+
+    # @return [I2C] the bus device this sensor is read through
+    attr_reader :i2c
+
+    # @return [Integer] 13 or 16
+    attr_reader :resolution
+
+    # @param bits [Integer] 13 or 16
+    def resolution=(bits)
+      raise ArgumentError, "resolution must be 13 or 16, got #{bits.inspect}" unless COUNTS_PER_DEGREE.key?(bits)
+
+      config = @i2c.read_register(REG_CONFIG).first
+      config = bits == 16 ? config | CONFIG_RESOLUTION_16 : config & ~CONFIG_RESOLUTION_16
+      @i2c.write_register(REG_CONFIG, config & 0xff)
+      @resolution = bits
+    end
+
+    # @return [Float] temperature in degrees Celsius
+    def temperature
+      msb, lsb = @i2c.read_register(REG_TEMPERATURE, 2)
+      self.class.convert(msb, lsb, @resolution)
+    end
+
+    alias value temperature
+
+    # @return [Array<Integer>] the raw two temperature bytes, MSB first
+    def raw_temperature
+      @i2c.read_register(REG_TEMPERATURE, 2)
+    end
+
+    # @return [Integer] the ID register: manufacturer ID in bits 7..3,
+    #         silicon revision in bits 2..0
+    def id
+      @i2c.read_register(REG_ID).first
+    end
+
+    # A cheap "is the sensor really there" check for examples and diagnostics.
+    # @return [Boolean] true when the ID register reports Analog Devices
+    def detected?
+      (id >> 3) == MANUFACTURER_ID
+    rescue SystemCallError
+      false
+    end
+
+    # Convert a raw register pair to degrees Celsius. Both resolutions are
+    # two's complement, so a set sign bit means the reading is below 0 degC.
+    # @return [Float]
+    def self.convert(msb, lsb, resolution = 13)
+      counts = COUNTS_PER_DEGREE.fetch(resolution)
+      raw = ((msb << 8) | lsb)
+      raw >>= 3 if resolution == 13
+      sign_bit = resolution == 13 ? 0x1000 : 0x8000
+      raw -= sign_bit * 2 if raw & sign_bit != 0
+      raw / counts
+    end
+
+    # Close the bus device, but only if this sensor opened it.
+    def close
+      return if @closed
+
+      @closed = true
+      @i2c.close if @owns_i2c
+    end
+
+    def closed?
+      @closed
+    end
+  end
+end

data/lib/rgpio/devices/device.rb

@@ -0,0 +1,41 @@
+module Rgpio
+  # Base class for the high-level device API (LED, Button, MotionSensor, Motor).
+  #
+  # A device either borrows a Chip given by the caller or opens its own. Only a
+  # chip the device opened itself is closed by #close, so several devices can
+  # share one chip handle:
+  #
+  #   chip  = Rgpio::Chip.new
+  #   red   = Rgpio::LED.new(17, chip: chip)
+  #   green = Rgpio::LED.new(27, chip: chip)
+  class Device
+    # @param chip [Chip, nil] chip to drive this device on; nil opens (and
+    #             later closes) a chip of its own via auto-detection
+    def initialize(chip: nil)
+      @owns_chip = chip.nil?
+      @chip = chip || Chip.new
+      @closed = false
+    end
+
+    # @return [Chip] the chip this device is driven on
+    attr_reader :chip
+
+    # Release the device's lines, and the chip too if this device opened it.
+    # Safe to call multiple times.
+    def close
+      return if @closed
+
+      @closed = true
+      release_resources
+      @chip.close if @owns_chip
+    end
+
+    def closed?
+      @closed
+    end
+
+    private
+
+    def release_resources; end
+  end
+end

data/lib/rgpio/devices/input_device.rb

@@ -0,0 +1,150 @@
+module Rgpio
+  # A single GPIO line read as an input, with optional edge callbacks.
+  #
+  # Callbacks run on a background thread that waits on kernel edge events, so
+  # the main thread is free (see {Rgpio.pause}). The thread is started by the
+  # first callback registration and stopped by #close.
+  class InputDevice < Device
+    # How long a single edge wait blocks before the watcher rechecks whether it
+    # has been asked to stop.
+    WATCH_TIMEOUT = 0.2
+
+    # @param gpio        [Integer] GPIO line offset (BCM numbering)
+    # @param pull_up     [Boolean, nil] internal bias: true = pull-up (wire the
+    #                    switch to GND), false = pull-down (wire it to 3.3 V),
+    #                    nil = no bias (external resistor)
+    # @param active_low  [Boolean] when true, a low line reads as active
+    # @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(gpio, pull_up: false, active_low: false, debounce_us: 0, chip: nil, consumer: "rgpio")
+      super(chip: chip)
+      @gpio = gpio
+      @callbacks = {}
+      @request = @chip.request_lines(
+        offsets: [gpio],
+        direction: :input,
+        edge: :both,
+        bias: bias_for(pull_up),
+        active_low: active_low,
+        debounce_us: debounce_us,
+        consumer: consumer
+      )
+    end
+
+    # @return [Integer] the GPIO line offset this device reads
+    attr_reader :gpio
+
+    # @return [Boolean] true when the line is at its active level
+    def value
+      @request.get_value(@gpio) == :active
+    end
+
+    alias active? value
+
+    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
+
+    # Register +block+ for the transition to :active or :inactive, and make sure
+    # the watcher thread is running.
+    def on_edge(state, &block)
+      raise ArgumentError, "a callback block is required" unless block
+
+      @callbacks[state] = block
+      start_watching
+      self
+    end
+
+    def start_watching
+      return if @watcher
+
+      @watching = true
+      @watcher = Thread.new { watch_loop }
+    end
+
+    def watch_loop
+      while @watching
+        @request.read_edge_events(timeout: WATCH_TIMEOUT).each do |event|
+          dispatch(event[:type] == :rising ? :active : :inactive)
+        end
+      end
+    rescue StandardError => e
+      warn "rgpio: edge watcher for GPIO#{@gpio} stopped: #{e.class}: #{e.message}"
+    end
+
+    # A raising callback must not take the watcher down with it, or the device
+    # would go quiet with no indication why.
+    def dispatch(state)
+      callback = @callbacks[state]
+      return unless callback
+
+      callback.call
+    rescue StandardError => e
+      warn "rgpio: #{self.class} callback for GPIO#{@gpio} 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
+
+  # A push button or switch.
+  #
+  #   button = Rgpio::Button.new(4)
+  #   button.when_pressed  { puts "Pressed" }
+  #   button.when_released { puts "Released" }
+  #   Rgpio.pause
+  #
+  # The default pull-down bias suits a switch wired between the GPIO line and
+  # 3.3 V. Pass pull_up: true for a switch wired to GND instead.
+  class Button < InputDevice
+    # Mechanical contacts bounce for a few milliseconds; without this one press
+    # fires the callback several times.
+    DEBOUNCE_US = 5_000
+
+    def initialize(gpio, pull_up: false, active_low: false, debounce_us: DEBOUNCE_US, chip: nil, consumer: "rgpio")
+      super
+    end
+
+    def when_pressed(&)
+      on_edge(:active, &)
+    end
+
+    def when_released(&)
+      on_edge(:inactive, &)
+    end
+
+    alias pressed? value
+  end
+
+  # A PIR motion sensor. Its output is a clean digital signal, so no debounce
+  # is applied.
+  #
+  #   sensor = Rgpio::MotionSensor.new(4)
+  #   sensor.when_motion { puts "motion detected!" }
+  #   Rgpio.pause
+  class MotionSensor < InputDevice
+    def when_motion(&)
+      on_edge(:active, &)
+    end
+
+    def when_no_motion(&)
+      on_edge(:inactive, &)
+    end
+
+    alias motion_detected? value
+  end
+end

data/lib/rgpio/devices/mcp3208.rb

@@ -0,0 +1,104 @@
+module Rgpio
+  # An MCP3208 analogue-to-digital converter: eight 12-bit channels over SPI.
+  #
+  #   adc = Rgpio::MCP3208.new
+  #   adc.read(0)      # => 0..4095, the raw code
+  #   adc.voltage(0)   # => volts, against the reference
+  #   adc.close
+  #
+  # Wiring is SPI plus a reference: VDD and VREF to 3.3 V, AGND and DGND to
+  # ground, CLK/DOUT/DIN to SCLK/MISO/MOSI, CS to CE0.
+  #
+  # The MCP3204 is the same part with four channels and the same protocol, so it
+  # works through this class with `channels: 4`.
+  #
+  # Clock rate matters for correctness, not just speed: the datasheet allows
+  # 1 MHz at 2.7 V and 2 MHz at 5 V, and a converter clocked past its sampling
+  # rate returns values that look plausible and are wrong. The 1 MHz default is
+  # inside the envelope for a 3.3 V supply.
+  class MCP3208
+    DEFAULT_CHANNELS = 8
+
+    # 12 bits, so 4096 codes: code 4095 means the input is at the reference.
+    RESOLUTION = 4096
+
+    DEFAULT_REFERENCE_VOLTAGE = 3.3
+    DEFAULT_SPEED_HZ = 1_000_000
+
+    # First command byte: a start bit, then SGL/DIFF, then the top channel bit.
+    START_SINGLE = 0x06
+    START_DIFFERENTIAL = 0x04
+
+    # @param channels          [Integer] 8 for an MCP3208, 4 for an MCP3204
+    # @param reference_voltage [Float] volts on the VREF pin
+    # @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
+    def initialize(channels: DEFAULT_CHANNELS, reference_voltage: DEFAULT_REFERENCE_VOLTAGE,
+                   bus: 0, device: 0, speed_hz: DEFAULT_SPEED_HZ, spi: nil)
+      @channels = channels
+      @reference_voltage = reference_voltage.to_f
+      @owns_spi = spi.nil?
+      @spi = spi || SPI.new(bus: bus, device: device, speed_hz: speed_hz, mode: 0)
+      @closed = false
+    end
+
+    # @return [SPI] the bus device readings go through
+    attr_reader :spi
+
+    # @return [Integer] how many input channels this part has
+    attr_reader :channels
+
+    # @return [Float] volts on the VREF pin
+    attr_reader :reference_voltage
+
+    # Read one channel.
+    # @param channel      [Integer] 0...channels
+    # @param differential [Boolean] measure the channel pair rather than the
+    #                     single input: 0/1, 2/3, 4/5, 6/7, with the even channel
+    #                     as IN+ when `channel` is even
+    # @return [Integer] the raw code, 0..4095
+    def read(channel, differential: false)
+      raise Error, "MCP3208 is closed" if @closed
+      unless channel.is_a?(Integer) && (0...@channels).cover?(channel)
+        raise ArgumentError, "channel must be in 0...#{@channels}, got #{channel.inspect}"
+      end
+
+      start = differential ? START_DIFFERENTIAL : START_SINGLE
+      received = @spi.transfer([start | ((channel & 0x04) >> 2), (channel & 0x03) << 6, 0x00])
+      # The conversion arrives across the last two bytes: four null bits, then
+      # the twelve data bits, most significant first.
+      ((received[1] & 0x0f) << 8) | received[2]
+    end
+
+    # @return [Float] the channel as a fraction of the reference, 0.0..1.0
+    def value(channel, differential: false)
+      read(channel, differential: differential) / (RESOLUTION - 1).to_f
+    end
+
+    # @return [Float] the channel in volts
+    def voltage(channel, differential: false)
+      value(channel, differential: differential) * @reference_voltage
+    end
+
+    # Read every channel in turn. Not simultaneous — the part has one converter
+    # behind a multiplexer, so these are consecutive samples.
+    # @return [Array<Integer>] raw codes, channel 0 first
+    def read_all
+      Array.new(@channels) { |channel| read(channel) }
+    end
+
+    # Close the bus device, but only if this converter opened it.
+    def close
+      return if @closed
+
+      @closed = true
+      @spi.close if @owns_spi
+    end
+
+    def closed?
+      @closed
+    end
+  end
+end