dredger-iot 0.1.0

data/lib/dredger/iot/bus/gpio.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Bus
+      # Simple GPIO bus with pluggable backend. Defaults to Simulation.
+      class GPIO
+        def initialize(backend: nil)
+          @backend = backend || Simulation.new
+        end
+
+        def set_direction(pin_label, direction)
+          @backend.set_direction(pin_label, direction)
+        end
+
+        def write(pin_label, value)
+          @backend.write(pin_label, value)
+        end
+
+        def read(pin_label)
+          @backend.read(pin_label)
+        end
+
+        # Simulation backend for tests/development
+        class Simulation
+          def initialize
+            @values = Hash.new(0)
+            @directions = {}
+          end
+
+          def set_direction(pin_label, direction)
+            raise ArgumentError, 'direction must be :in or :out' unless %i[in out].include?(direction)
+
+            @directions[pin_label] = direction
+          end
+
+          def write(pin_label, value)
+            raise ArgumentError, 'value must be 0 or 1' unless [0, 1, true, false].include?(value)
+            raise 'pin not configured for :out' unless @directions[pin_label] == :out
+
+            @values[pin_label] = [1, true].include?(value) ? 1 : 0
+          end
+
+          def read(pin_label)
+            # If configured as input, just return last seen value (or default 0)
+            @values[pin_label]
+          end
+
+          # Helpers for test injection
+          def inject_input(pin_label, value)
+            raise ArgumentError, 'value must be 0 or 1' unless [0, 1, true, false].include?(value)
+
+            @values[pin_label] = [1, true].include?(value) ? 1 : 0
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dredger/iot/bus/gpio_label_adapter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Bus
+      # Adapts label strings (e.g. 'P9_12') to PinRef with chip:line for libgpiod backends
+      class GPIOLabelAdapter
+        def initialize(backend:, mapper: Dredger::IoT::Pins::Beaglebone)
+          @backend = backend
+          @mapper = mapper
+        end
+
+        def set_direction(pin, direction)
+          @backend.set_direction(resolve(pin), direction)
+        end
+
+        def write(pin, value)
+          @backend.write(resolve(pin), value)
+        end
+
+        def read(pin)
+          @backend.read(resolve(pin))
+        end
+
+        private
+
+        def resolve(pin)
+          # Already a PinRef with line
+          return pin if pin.respond_to?(:line) && !pin.line.nil?
+          # Numeric line
+          return Integer(pin) if pin.is_a?(Integer) || pin.to_s =~ /^\d+$/
+          # Beaglebone-style label
+          return @mapper.resolve_label_to_pinref(pin) if @mapper.respond_to?(:resolve_label_to_pinref)
+
+          raise ArgumentError, 'Unsupported pin format'
+        end
+      end
+    end
+  end
+end
+# EOF

data/lib/dredger/iot/bus/gpio_libgpiod.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+module Dredger
+  module IoT
+    module Bus
+      # GPIO backend using libgpiod ctxless helpers. Requires chip name and line offset.
+      class GpioLibgpiod
+        module Lib
+          extend FFI::Library
+
+          ffi_lib %w[gpiod libgpiod]
+
+          # int gpiod_ctxless_get_value(const char *device, unsigned int offset, bool active_low,
+          #                             const char *consumer);
+          attach_function :gpiod_ctxless_get_value, %i[string uint bool string], :int
+
+          # int gpiod_ctxless_set_value(const char *device, unsigned int offset, int value, bool active_low,
+          #                             const char *consumer);
+          attach_function :gpiod_ctxless_set_value, %i[string uint int bool string], :int
+        end
+
+        CONSUMER = 'dredger-iot'
+
+        def initialize(chip: 'gpiochip0', active_low: false)
+          @chip = chip
+          @active_low = !!active_low
+        end
+
+        # pin can be Integer line offset, or a PinRef with :line
+        def read(pin)
+          line = line_from(pin)
+          val = Lib.gpiod_ctxless_get_value(@chip, line, @active_low, CONSUMER)
+          raise IOError, 'gpiod get failed' if val.negative?
+
+          val
+        end
+
+        def write(pin, value)
+          line = line_from(pin)
+          int_val = [1, true].include?(value) ? 1 : 0
+          rc = Lib.gpiod_ctxless_set_value(@chip, line, int_val, @active_low, CONSUMER)
+          raise IOError, 'gpiod set failed' if rc.negative?
+
+          rc
+        end
+
+        # no-op; ctxless helpers configure as needed per call
+        def set_direction(_pin, _direction); end
+
+        private
+
+        def line_from(pin)
+          return pin.line if pin.respond_to?(:line) && !pin.line.nil?
+          return Integer(pin) if pin.is_a?(Integer) || pin.to_s =~ /^\d+$/
+
+          raise ArgumentError, 'pin must be Integer line offset or PinRef with line'
+        end
+      end
+    end
+  end
+end

data/lib/dredger/iot/bus/i2c.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Bus
+      # Minimal I2C abstraction. Defaults to Simulation backend.
+      class I2C
+        def initialize(backend: nil)
+          @backend = backend || Simulation.new
+        end
+
+        # Write bytes to device address starting at optional register
+        def write(addr, bytes, register: nil)
+          @backend.write(addr, bytes, register: register)
+        end
+
+        # Read length bytes from device address optionally starting at register
+        def read(addr, length, register: nil)
+          @backend.read(addr, length, register: register)
+        end
+
+        # Simulation backend keeps a per-address register map
+        class Simulation
+          def initialize
+            @devices = Hash.new { |h, k| h[k] = Hash.new(0) }
+          end
+
+          def write(addr, bytes, register: nil)
+            raise ArgumentError, 'bytes must be an Array of integers' unless bytes.is_a?(Array) && bytes.all?(Integer)
+
+            if register.nil?
+              # Treat as sequential write starting at register 0
+              bytes.each_with_index { |b, i| @devices[addr][i] = b & 0xFF }
+            else
+              bytes.each_with_index { |b, i| @devices[addr][register + i] = b & 0xFF }
+            end
+            bytes.length
+          end
+
+          def read(addr, length, register: nil)
+            raise ArgumentError, 'length must be positive' unless length.positive?
+
+            start = register || 0
+            (0...length).map { |i| @devices[addr][start + i] & 0xFF }
+          end
+
+          # For tests to seed device registers
+          def seed(addr, register, bytes)
+            bytes.each_with_index { |b, i| @devices[addr][register + i] = b & 0xFF }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dredger/iot/bus/i2c_linux.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+module Dredger
+  module IoT
+    module Bus
+      # Linux I2C backend using i2c-dev via ioctl
+      class I2cLinux
+        module LibC
+          extend FFI::Library
+
+          ffi_lib FFI::Library::LIBC
+          attach_function :ioctl, %i[int ulong ulong], :int
+        end
+
+        I2C_SLAVE = 0x0703
+
+        def initialize(bus_path: '/dev/i2c-1')
+          @bus_path = bus_path
+        end
+
+        def write(addr, bytes, register: nil)
+          raise ArgumentError, 'bytes must be an Array of integers' unless bytes.is_a?(Array) && bytes.all?(Integer)
+
+          File.open(@bus_path, 'r+b') do |f|
+            set_slave(f, addr)
+            data = register.nil? ? bytes : [register] + bytes
+            f.write(data.pack('C*'))
+          end
+        end
+
+        def read(addr, length, register: nil)
+          raise ArgumentError, 'length must be positive' unless length.positive?
+
+          File.open(@bus_path, 'r+b') do |f|
+            set_slave(f, addr)
+            f.write([register].pack('C')) unless register.nil?
+            f.read(length).unpack('C*')
+          end
+        end
+
+        private
+
+        def set_slave(file, addr)
+          rc = LibC.ioctl(file.fileno, I2C_SLAVE, addr)
+          raise IOError, 'ioctl(I2C_SLAVE) failed' if rc.negative?
+        end
+      end
+    end
+  end
+end

data/lib/dredger/iot/bus.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'bus/gpio'
+require_relative 'bus/i2c'
+require_relative 'bus/auto'

data/lib/dredger/iot/pins/beaglebone.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Pins
+      # Beaglebone header label mapping placeholder.
+      class Beaglebone
+        # Provides validation and PinRef objects.
+        # Chip:line resolution is done at runtime by the agent or a backend.
+        PinRef = Struct.new(:label, :chip, :line, keyword_init: true) do
+          def to_s
+            chip && line ? "#{label}(chip#{chip}:#{line})" : label.to_s
+          end
+        end
+
+        KNOWN_LABELS = (
+          (0..46).map { |n| "P8_#{n}" } + (0..46).map { |n| "P9_#{n}" }
+        ).freeze
+
+        # Minimal built-in mapping for common pins. This can be extended.
+        # Mapping format: 'P9_12' => [chip_number, line_offset]
+        MAP = {
+          'P9_12' => [1, 28],
+          'P9_14' => [1, 18]
+        }.freeze
+
+        def self.valid_label?(label)
+          KNOWN_LABELS.include?(label.to_s)
+        end
+
+        def self.resolve(label)
+          raise ArgumentError, "Unknown pin label: #{label}" unless valid_label?(label)
+
+          PinRef.new(label: label.to_s, chip: nil, line: nil)
+        end
+
+        # Returns [chip_name, line] or raises if unknown
+        def self.chip_line_for(label)
+          normalized = label.to_s.upcase
+          raise ArgumentError, "Unknown pin label: #{label}" unless valid_label?(normalized)
+
+          pair = MAP[normalized]
+          raise ArgumentError, "No mapping for label: #{label}" if pair.nil?
+
+          ["gpiochip#{pair[0]}", pair[1]]
+        end
+
+        # Returns PinRef with chip and line resolved (raises if unknown)
+        def self.resolve_label_to_pinref(label)
+          chip, line = chip_line_for(label)
+          PinRef.new(label: label.to_s, chip: chip.sub('gpiochip', '').to_i, line: line)
+        end
+      end
+    end
+  end
+end

data/lib/dredger/iot/pins.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'pins/beaglebone'

data/lib/dredger/iot/reading.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    # Immutable, normalized sensor reading
+    Reading = Struct.new(
+      :sensor_type, :value, :unit, :recorded_at, :calibrated, :accuracy, :metadata,
+      keyword_init: true
+    ) do
+      def initialize(**kwargs)
+        super
+        freeze
+      end
+
+      def to_h
+        {
+          sensor_type: sensor_type,
+          value: value,
+          unit: unit,
+          recorded_at: recorded_at,
+          calibrated: calibrated,
+          accuracy: accuracy,
+          metadata: metadata
+        }
+      end
+    end
+  end
+end

data/lib/dredger/iot/scheduler.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Scheduler
+      module_function
+
+      # Returns an Enumerator yielding next sleep seconds with jitter each cycle
+      # base_interval: Float seconds
+      # jitter_ratio: 0.0..1.0 (fraction of base interval)
+      def periodic_with_jitter(base_interval:, jitter_ratio: 0.1)
+        raise ArgumentError, 'base_interval must be > 0' unless base_interval.positive?
+        raise ArgumentError, 'jitter_ratio must be between 0.0 and 1.0' unless jitter_ratio.between?(0.0, 1.0)
+
+        Enumerator.new do |y|
+          loop do
+            jitter = ((rand * 2) - 1) * (base_interval * jitter_ratio)
+            y << [base_interval + jitter, 0.0].max
+          end
+        end
+      end
+
+      # Exponential backoff enumerator with max backoff and max attempts (or infinite if nil)
+      def exponential_backoff(initial:, factor: 2.0, max: 60.0, attempts: nil)
+        raise ArgumentError, 'initial must be > 0' unless initial.positive?
+        raise ArgumentError, 'factor must be >= 1.0' unless factor >= 1.0
+        raise ArgumentError, 'max must be >= initial' unless max >= initial
+
+        Enumerator.new do |y|
+          i = 0
+          current = initial
+          loop do
+            break if attempts && i >= attempts
+
+            y << current
+            current = [current * factor, max].min
+            i += 1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dredger/iot/sensors/base_sensor.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Sensors
+      class BaseSensor
+        def initialize(metadata: {})
+          @metadata = metadata
+        end
+
+        def readings
+          raise NotImplementedError
+        end
+
+        private
+
+        def reading(sensor_type:, value:, unit:, **opts)
+          Dredger::IoT::Reading.new(
+            sensor_type: sensor_type,
+            value: value,
+            unit: unit,
+            recorded_at: opts.fetch(:recorded_at, Time.now.utc),
+            calibrated: opts.fetch(:calibrated, true),
+            accuracy: opts[:accuracy],
+            metadata: @metadata.merge(opts.fetch(:metadata, {}))
+          )
+        end
+      end
+    end
+  end
+end

data/lib/dredger/iot/sensors/bme280.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Sensors
+      # BME280 temperature/pressure/humidity over I2C
+      # Provider must respond to :read_measurements(addr) -> { temperature_c:, humidity:, pressure_kpa: }
+      class BME280 < BaseSensor
+        def initialize(i2c_addr:, provider:, metadata: {})
+          super(metadata: metadata)
+          @i2c_addr = i2c_addr
+          @provider = provider
+        end
+
+        def readings
+          m = @provider.read_measurements(@i2c_addr)
+          [
+            reading(sensor_type: 'temperature', value: m[:temperature_c], unit: 'celsius'),
+            reading(sensor_type: 'humidity', value: m[:humidity], unit: '%'),
+            reading(sensor_type: 'pressure', value: m[:pressure_kpa], unit: 'kPa')
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/dredger/iot/sensors/bme280_provider.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Sensors
+      # Hardware provider for BME280 temperature/humidity/pressure sensor over I2C.
+      # Datasheet: https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bme280-ds002.pdf
+      #
+      # Key registers:
+      # - 0xD0: chip_id (should be 0x60 for BME280)
+      # - 0xF4: ctrl_meas (mode, oversampling)
+      # - 0xF5: config (standby, filter)
+      # - 0xF7-0xFE: measurement data (pressure, temp, humidity)
+      # - 0x88-0xA1, 0xE1-0xE7: calibration coefficients
+      class BME280Provider
+        CHIP_ID_REG = 0xD0
+        CHIP_ID_EXPECTED = 0x60
+        CTRL_MEAS_REG = 0xF4
+        CONFIG_REG = 0xF5
+        DATA_REG = 0xF7
+
+        # Calibration coefficient registers
+        CALIB_00_REG = 0x88 # dig_T1..dig_H1 start
+        CALIB_26_REG = 0xE1 # dig_H2..dig_H6 start
+
+        # i2c_bus: an I2C bus interface (e.g., Dredger::IoT::Bus::Auto.i2c)
+        def initialize(i2c_bus:)
+          @i2c = i2c_bus
+        end
+
+        # Read measurements from the BME280 at the given I2C address.
+        # Returns { temperature_c: Float, humidity: Float, pressure_kpa: Float }
+        def read_measurements(addr)
+          # Verify chip ID
+          chip_id = @i2c.read(addr, 1, register: CHIP_ID_REG).first
+          raise IOError, "BME280 not found (chip_id=0x#{chip_id.to_s(16)})" unless chip_id == CHIP_ID_EXPECTED
+
+          # Read calibration coefficients (needed for compensating raw data)
+          calib = read_calibration(addr)
+
+          # Configure sensor: forced mode, oversampling x1 for all
+          # ctrl_meas: osrs_t[7:5]=001, osrs_p[4:2]=001, mode[1:0]=01 (forced)
+          @i2c.write(addr, [0b00100101], register: CTRL_MEAS_REG)
+
+          # Wait for measurement (typical 8ms for this config)
+          sleep(0.01)
+
+          # Read raw data: 8 bytes from 0xF7
+          raw = @i2c.read(addr, 8, register: DATA_REG)
+
+          # Parse raw values (20-bit pressure, 20-bit temp, 16-bit humidity)
+          press_raw = (raw[0] << 12) | (raw[1] << 4) | (raw[2] >> 4)
+          temp_raw = (raw[3] << 12) | (raw[4] << 4) | (raw[5] >> 4)
+          hum_raw = (raw[6] << 8) | raw[7]
+
+          # Compensate using calibration (simplified integer math from datasheet)
+          temp_c = compensate_temperature(temp_raw, calib)
+          humidity = compensate_humidity(hum_raw, calib, temp_c)
+          pressure_pa = compensate_pressure(press_raw, calib, temp_c)
+
+          {
+            temperature_c: temp_c,
+            humidity: humidity,
+            pressure_kpa: pressure_pa / 1000.0
+          }
+        end
+
+        private
+
+        # Read calibration coefficients from sensor
+        def read_calibration(addr)
+          # Read 26 bytes from 0x88-0xA1 (dig_T1..dig_P9, dig_H1)
+          calib1 = @i2c.read(addr, 26, register: CALIB_00_REG)
+          # Read 7 bytes from 0xE1-0xE7 (dig_H2..dig_H6)
+          calib2 = @i2c.read(addr, 7, register: CALIB_26_REG)
+
+          # Parse calibration data (see datasheet for layout)
+          {
+            dig_t1: u16(calib1, 0),
+            dig_t2: s16(calib1, 2),
+            dig_t3: s16(calib1, 4),
+            dig_p1: u16(calib1, 6),
+            dig_p2: s16(calib1, 8),
+            dig_p3: s16(calib1, 10),
+            dig_p4: s16(calib1, 12),
+            dig_p5: s16(calib1, 14),
+            dig_p6: s16(calib1, 16),
+            dig_p7: s16(calib1, 18),
+            dig_p8: s16(calib1, 20),
+            dig_p9: s16(calib1, 22),
+            dig_h1: calib1[25],
+            dig_h2: s16(calib2, 0),
+            dig_h3: calib2[2],
+            dig_h4: (calib2[3] << 4) | (calib2[4] & 0x0F),
+            dig_h5: (calib2[5] << 4) | (calib2[4] >> 4),
+            dig_h6: s8(calib2[6])
+          }
+        end
+
+        # Compensate temperature (returns °C, also sets @t_fine for other compensations)
+        def compensate_temperature(adc_t, calib)
+          var1 = (((adc_t / 16_384.0) - (calib[:dig_t1] / 1024.0)) * calib[:dig_t2])
+          var2 = ((((adc_t / 131_072.0) - (calib[:dig_t1] / 8192.0))**2) * calib[:dig_t3])
+          @t_fine = (var1 + var2).to_i
+          @t_fine / 5120.0
+        end
+
+        # Compensate humidity (returns %)
+        def compensate_humidity(adc_h, calib, _temp_c)
+          return 0.0 if @t_fine.nil?
+
+          var_h = @t_fine - 76_800.0
+          var_h = (adc_h - ((calib[:dig_h4] * 64.0) + (calib[:dig_h5] / 16_384.0 * var_h))) *
+                  (calib[:dig_h2] / 65_536.0 * (1.0 + (calib[:dig_h6] / 67_108_864.0 * var_h *
+                  (1.0 + (calib[:dig_h3] / 67_108_864.0 * var_h)))))
+          var_h *= (1.0 - (calib[:dig_h1] * var_h / 524_288.0))
+          var_h = 0.0 if var_h < 0.0
+          var_h = 100.0 if var_h > 100.0
+          var_h
+        end
+
+        # Compensate pressure (returns Pa)
+        def compensate_pressure(adc_p, calib, _temp_c)
+          var1 = (@t_fine / 2.0) - 64_000.0
+          var2 = var1 * var1 * calib[:dig_p6] / 32_768.0
+          var2 += var1 * calib[:dig_p5] * 2.0
+          var2 = (var2 / 4.0) + (calib[:dig_p4] * 65_536.0)
+          var1 = ((calib[:dig_p3] * var1 * var1 / 524_288.0) + (calib[:dig_p2] * var1)) / 524_288.0
+          var1 = (1.0 + (var1 / 32_768.0)) * calib[:dig_p1]
+          return 0.0 if var1.zero?
+
+          pressure = 1_048_576.0 - adc_p
+          pressure = (pressure - (var2 / 4096.0)) * 6250.0 / var1
+          var1 = calib[:dig_p9] * pressure * pressure / 2_147_483_648.0
+          var2 = pressure * calib[:dig_p8] / 32_768.0
+          pressure + ((var1 + var2 + calib[:dig_p7]) / 16.0)
+        end
+
+        # Helper: read unsigned 16-bit from byte array
+        def u16(bytes, offset)
+          bytes[offset] | (bytes[offset + 1] << 8)
+        end
+
+        # Helper: read signed 16-bit from byte array
+        def s16(bytes, offset)
+          val = u16(bytes, offset)
+          val > 32_767 ? val - 65_536 : val
+        end
+
+        # Helper: read signed 8-bit
+        def s8(byte)
+          byte > 127 ? byte - 256 : byte
+        end
+      end
+    end
+  end
+end

data/lib/dredger/iot/sensors/bmp180.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Sensors
+      # BMP180 barometric pressure/temperature sensor over I2C
+      # Provider must respond to :read_measurements(addr) -> { temperature_c:, pressure_pa: }
+      class BMP180 < BaseSensor
+        def initialize(i2c_addr:, provider:, metadata: {})
+          super(metadata: metadata)
+          @i2c_addr = i2c_addr
+          @provider = provider
+        end
+
+        def readings
+          m = @provider.read_measurements(@i2c_addr)
+          [
+            reading(sensor_type: 'temperature', value: m[:temperature_c], unit: 'celsius'),
+            reading(sensor_type: 'pressure', value: m[:pressure_pa] / 1000.0, unit: 'kPa')
+          ]
+        end
+      end
+    end
+  end
+end
+# EOF

data/lib/dredger/iot/sensors/dht22.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Sensors
+      # DHT22 humidity/temperature sensor (1-wire like GPIO)
+      # Uses a provider interface to allow simulation in tests and hardware backends in production.
+      class DHT22 < BaseSensor
+        # provider must respond to :sample(pin_label) -> { humidity: Float, temperature_c: Float }
+        def initialize(pin_label:, provider:, metadata: {})
+          super(metadata: metadata)
+          @pin_label = pin_label
+          @provider = provider
+        end
+
+        def readings
+          sample = @provider.sample(@pin_label)
+          [
+            reading(sensor_type: 'humidity', value: sample[:humidity], unit: '%'),
+            reading(sensor_type: 'temperature', value: sample[:temperature_c], unit: 'celsius')
+          ]
+        end
+      end
+    end
+  end
+end