dredger-iot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: be57692da679526bf1757f3f76cda63f472b0cbe73767b31d75bb2b1d6b063ca
+  data.tar.gz: 2a888f1d324b99fc306c9fc4fa27d27f3d8b0ef799703faae48843230459ec0c
+SHA512:
+  metadata.gz: 0f257ec33e61e47a21f03e741068909f04cc2c701a6a4dc6d1c06e5268071cdb1887dd2b72183c96178bc3ebb0f80de00b8e62dd02493c3cbb04d4335db86825
+  data.tar.gz: eb57aad72c0629d2bf05ec953b1cc8951e6e51a9e3f80f3af50681015f0439a1f592e5f572b66a5f2c00449b72562c2725b0e8b513c9d4f90b1b44c757fb0d48

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-10-03
+
+### Added
+- Initial release of dredger-iot gem
+- GPIO access via libgpiod FFI backend with simulation fallback
+- I2C access via Linux i2c-dev FFI backend with simulation fallback
+- Auto-selection API for automatic backend detection
+- Beaglebone Black P9_XX pin label mapping for libgpiod
+- Sensor drivers:
+  - DHT22 (GPIO-based temperature/humidity sensor)
+  - BME280 (I2C temperature/humidity/pressure sensor)
+  - DS18B20 (1-Wire temperature sensor via kernel w1-gpio)
+  - BMP180 (I2C barometric pressure/temperature sensor)
+  - MCP9808 (I2C high-accuracy temperature sensor)
+- Provider pattern for sensor abstraction and testability
+- Scheduling utilities:
+  - `periodic_with_jitter` for distributed polling
+  - `exponential_backoff` for retry logic
+- Full RSpec test suite with 100% coverage (excluding hardware providers)
+- RuboCop configuration and compliance
+- Comprehensive documentation and usage examples
+
+[Unreleased]: https://github.com/TheMadBotterINC/dredger-iot/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/TheMadBotterINC/dredger-iot/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 The Mad Botter INC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,521 @@
+```
+                      _______________                              
+                     |  DREDGER-IoT  |                            
+                     |_______________|                            
+                    /|   ___     ___ |\                           
+                   / |  |___|   |___|| \                          
+                  /  |______________|  \                         
+             ====|========================|====                   
+            |    |    |-----------|     |    |                   
+            |    |____|           |_____|    |                   
+         ___|____|                         |____|___             
+    ~~~~{________|_________________________|________}~~~~~~~     
+      ~~      |  \\                     //  |         ~~~        
+              |   \\___________________//   |                    
+              |_____________________________|                    
+         ~~~       \\                 //          ~~~            
+                    \\_______________//                          
+
+       Hardware Integration for Embedded Linux
+```
+
+[![CI](https://github.com/TheMadBotterINC/dredger-iot/workflows/CI/badge.svg)](https://github.com/TheMadBotterINC/dredger-iot/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/dredger-iot.svg)](https://badge.fury.io/rb/dredger-iot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-ruby.svg)](https://www.ruby-lang.org/)
+
+A small, FOSS Ruby library for hardware access on embedded Linux (Beaglebone Black, etc.).
+
+Goals:
+- Generic, device-agnostic hardware integration (no proprietary references)
+- Clean abstractions for GPIO and I2C
+- Pluggable sensor drivers (DHT22, BME280 as starters)
+- Simple scheduling/retry helpers
+- Config-driven pin mapping (Beaglebone P9_XX labels)
+
+License: MIT (c) The Mad Botter INC
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby path=null start=null
+gem 'dredger-iot', git: 'https://github.com/TheMadBotterINC/dredger-iot'
+```
+
+## Backends
+
+Dredger-IoT supports multiple backends per bus:
+- GPIO: Simulation (default), libgpiod (via FFI)
+- I2C: Simulation (default), Linux i2c-dev (via FFI + ioctl)
+
+Backends are not auto-required for portability. Use the Auto API to choose an appropriate backend at runtime.
+
+## Auto-selection API
+
+```ruby path=null start=null
+require 'dredger/iot'
+
+# GPIO
+gpio = Dredger::IoT::Bus::Auto.gpio
+# I2C
+i2c  = Dredger::IoT::Bus::Auto.i2c
+```
+
+Auto rules:
+- GPIO: if /dev/gpiochip0 exists and libgpiod is available → libgpiod; else simulation
+- I2C: if bus path exists (default /dev/i2c-1) and backend is available → linux; else simulation
+
+Environment overrides:
+- `DREDGER_IOT_GPIO_BACKEND`: `simulation` | `libgpiod`
+- `DREDGER_IOT_I2C_BACKEND`: `simulation` | `linux`
+
+## Beaglebone P9_XX label mapping
+
+When the libgpiod backend is selected via Auto, Dredger-IoT resolves Beaglebone labels like `P9_12` to the corresponding `gpiochipN:line` before accessing the GPIO line. A minimal built-in table is provided and can be extended in future releases.
+
+Example:
+
+```ruby path=null start=null
+require 'dredger/iot'
+
+gpio = Dredger::IoT::Bus::Auto.gpio # picks libgpiod on BBB, otherwise simulation
+
+# Works with labels; on BBB this is translated to the correct chip:line
+gpio.set_direction('P9_12', :out)
+gpio.write('P9_12', 1)
+value = gpio.read('P9_12')
+```
+
+If you run on a development host (no /dev/gpiochip0), Auto will default to the simulation backend and still accept labels without error, though they have no hardware effect.
+
+## Sensors
+
+Dredger-IoT includes drivers for popular embedded sensors:
+
+- **DHT22** - GPIO humidity/temperature sensor
+- **BME280** - I2C temperature/humidity/pressure sensor
+- **DS18B20** - 1-Wire digital temperature sensor
+- **BMP180** - I2C barometric pressure/temperature sensor
+- **MCP9808** - I2C high-accuracy temperature sensor
+
+Sensors use a provider pattern for testability and hardware abstraction.
+
+## Usage Examples
+
+### DHT22 Temperature/Humidity Sensor
+
+```ruby path=null start=null
+require 'dredger/iot'
+
+# Set up GPIO bus and DHT22 provider
+gpio = Dredger::IoT::Bus::Auto.gpio
+provider = Dredger::IoT::Sensors::DHT22Provider.new(gpio_bus: gpio)
+
+# Create sensor instance
+sensor = Dredger::IoT::Sensors::DHT22.new(
+  pin_label: 'P9_12',
+  provider: provider,
+  metadata: { location: 'greenhouse' }
+)
+
+# Read measurements
+readings = sensor.readings
+readings.each do |r|
+  puts "#{r.sensor_type}: #{r.value} #{r.unit}"
+end
+# => humidity: 65.2 %
+# => temperature: 22.3 celsius
+```
+
+### BME280 Environmental Sensor
+
+```ruby path=null start=null
+require 'dredger/iot'
+
+# Set up I2C bus and BME280 provider
+i2c = Dredger::IoT::Bus::Auto.i2c
+provider = Dredger::IoT::Sensors::BME280Provider.new(i2c_bus: i2c)
+
+# Create sensor instance (default I2C address 0x76)
+sensor = Dredger::IoT::Sensors::BME280.new(
+  i2c_addr: 0x76,
+  provider: provider,
+  metadata: { location: 'weather_station' }
+)
+
+# Read all measurements
+readings = sensor.readings
+readings.each { |r| puts "#{r.sensor_type}: #{r.value} #{r.unit}" }
+# => temperature: 24.1 celsius
+# => humidity: 40.2 %
+# => pressure: 101.4 kPa
+```
+
+### DS18B20 Waterproof Temperature Sensor
+
+```ruby path=null start=null
+require 'dredger/iot'
+
+# Uses Linux kernel w1-gpio module (no FFI needed)
+provider = Dredger::IoT::Sensors::DS18B20Provider.new
+
+# List available devices
+devices = provider.list_devices
+puts "Found devices: #{devices.inspect}"
+# => ["28-0000056789ab", "28-0000056789cd"]
+
+# Read from specific device
+sensor = Dredger::IoT::Sensors::DS18B20.new(
+  device_id: '28-0000056789ab',
+  provider: provider,
+  metadata: { location: 'tank_a' }
+)
+
+temp = sensor.readings.first
+puts "#{temp.value}°C"
+```
+
+### Multiple Sensors with Scheduled Polling
+
+```ruby path=null start=null
+require 'dredger/iot'
+
+# Set up buses
+gpio = Dredger::IoT::Bus::Auto.gpio
+i2c = Dredger::IoT::Bus::Auto.i2c
+
+# Create multiple sensors
+sensors = [
+  Dredger::IoT::Sensors::DHT22.new(
+    pin_label: 'P9_12',
+    provider: Dredger::IoT::Sensors::DHT22Provider.new(gpio_bus: gpio),
+    metadata: { zone: 'indoor' }
+  ),
+  Dredger::IoT::Sensors::BME280.new(
+    i2c_addr: 0x76,
+    provider: Dredger::IoT::Sensors::BME280Provider.new(i2c_bus: i2c),
+    metadata: { zone: 'outdoor' }
+  )
+]
+
+# Poll sensors with jitter to avoid harmonics
+scheduler = Dredger::IoT::Scheduler.periodic_with_jitter(
+  base_interval: 60.0,
+  jitter_ratio: 0.1
+)
+
+scheduler.each do |interval|
+  sleep interval
+  
+  sensors.each do |sensor|
+    readings = sensor.readings
+    timestamp = Time.now.iso8601
+    
+    readings.each do |r|
+      puts "#{timestamp} [#{r.metadata[:zone]}] #{r.sensor_type}: #{r.value} #{r.unit}"
+    end
+  end
+end
+```
+
+## Scheduling Utilities
+
+### Periodic with Jitter
+
+Avoid harmonic spikes by adding randomized jitter to intervals:
+
+```ruby path=null start=null
+enum = Dredger::IoT::Scheduler.periodic_with_jitter(
+  base_interval: 10.0,
+  jitter_ratio: 0.2
+)
+sleeps = enum.take(3) # => [8.2, 10.4, 11.7] etc.
+```
+
+### Exponential Backoff
+
+Retry failed operations with increasing delays:
+
+```ruby path=null start=null
+backoff = Dredger::IoT::Scheduler.exponential_backoff(
+  base: 1.0,
+  max: 30.0,
+  attempts: 5
+)
+
+backoff.each do |delay|
+  sleep delay
+  break if try_operation # retry until success or attempts exhausted
+end
+```
+
+## Hardware Setup
+
+### Prerequisites
+
+On embedded Linux hardware (Beaglebone, Raspberry Pi, etc.), certain kernel modules and permissions are required.
+
+#### GPIO (libgpiod)
+
+```bash path=null start=null
+# Ensure gpiod tools are installed (optional but useful for testing)
+sudo apt-get install gpiod
+
+# Verify GPIO chips are available
+ls /dev/gpiochip*
+
+# Add user to gpio group for permissions
+sudo usermod -a -G gpio $USER
+# Log out and back in for group changes to take effect
+```
+
+#### I2C
+
+```bash path=null start=null
+# Enable I2C kernel module
+sudo modprobe i2c-dev
+
+# Make it permanent
+echo 'i2c-dev' | sudo tee -a /etc/modules
+
+# Add user to i2c group
+sudo usermod -a -G i2c $USER
+
+# Set permissions (if group doesn't exist)
+sudo chmod 666 /dev/i2c-*
+```
+
+#### DS18B20 (1-Wire)
+
+The DS18B20 sensor requires the kernel w1-gpio module:
+
+```bash path=null start=null
+# Load 1-Wire kernel modules
+sudo modprobe w1-gpio
+sudo modprobe w1-therm
+
+# Make it permanent
+echo 'w1-gpio' | sudo tee -a /etc/modules
+echo 'w1-therm' | sudo tee -a /etc/modules
+
+# Verify devices are detected
+ls /sys/bus/w1/devices/
+# Should show devices like: 28-00000xxxxxx
+```
+
+#### Beaglebone Black Device Tree
+
+For Beaglebone Black, you may need to enable device tree overlays:
+
+```bash path=null start=null
+# Edit /boot/uEnv.txt and enable overlays:
+# For I2C:
+uboot_overlay_addr4=/lib/firmware/BB-I2C1-00A0.dtbo
+
+# For GPIO/1-Wire (if using P9_12 for example):
+uboot_overlay_addr5=/lib/firmware/BB-W1-P9.12-00A0.dtbo
+
+# Reboot after changes
+sudo reboot
+```
+
+## Troubleshooting
+
+### Permission Denied Errors
+
+**Problem:** `Errno::EACCES: Permission denied - /dev/gpiochip0` or `/dev/i2c-1`
+
+**Solution:**
+```bash path=null start=null
+# Add your user to the appropriate group
+sudo usermod -a -G gpio $USER
+sudo usermod -a -G i2c $USER
+
+# Or temporarily change permissions (not recommended for production)
+sudo chmod 666 /dev/gpiochip*
+sudo chmod 666 /dev/i2c-*
+
+# Log out and back in for group changes
+```
+
+### DS18B20 Not Found
+
+**Problem:** `No DS18B20 devices found` or empty `/sys/bus/w1/devices/`
+
+**Solution:**
+```bash path=null start=null
+# Verify modules are loaded
+lsmod | grep w1
+
+# Load if missing
+sudo modprobe w1-gpio
+sudo modprobe w1-therm
+
+# Check dmesg for errors
+sudo dmesg | grep w1
+
+# Verify wiring: DS18B20 requires 4.7kΩ pull-up resistor on data line
+```
+
+### FFI Library Not Found
+
+**Problem:** `LoadError: cannot load such file -- ffi`
+
+**Solution:**
+```bash path=null start=null
+# Install FFI gem
+gem install ffi
+
+# Or ensure it's in your Gemfile
+bundle install
+```
+
+### Sensor Reading Returns Nil or Errors
+
+**Problem:** Sensor readings fail or return nil values
+
+**Solutions:**
+- **Verify wiring:** Double-check sensor connections (VCC, GND, data lines)
+- **Check I2C address:** Use `i2cdetect -y 1` to scan for devices
+- **Timing issues:** DHT22 requires ~2 second intervals between reads
+- **Power supply:** Ensure adequate power for sensors (some require 3.3V, others 5V)
+- **Enable simulation backend** for testing without hardware:
+  ```bash path=null start=null
+  export DREDGER_IOT_GPIO_BACKEND=simulation
+  export DREDGER_IOT_I2C_BACKEND=simulation
+  ```
+
+### I2C Device Not Detected
+
+**Problem:** I2C sensor not responding
+
+**Solution:**
+```bash path=null start=null
+# Install i2c-tools
+sudo apt-get install i2c-tools
+
+# Scan I2C bus (bus 1 is common, try 0 if not found)
+i2cdetect -y 1
+
+# Should show device at its address (e.g., 0x76 for BME280)
+# If not detected:
+# - Check wiring and pull-up resistors (typically 4.7kΩ on SDA/SCL)
+# - Verify I2C is enabled in device tree
+# - Check for bus conflicts
+```
+
+## API Reference
+
+### Core Modules
+
+#### `Dredger::IoT::Bus::Auto`
+
+Automatic backend selection for GPIO and I2C buses.
+
+```ruby path=null start=null
+gpio = Dredger::IoT::Bus::Auto.gpio  # Returns GPIO backend
+i2c = Dredger::IoT::Bus::Auto.i2c    # Returns I2C backend
+```
+
+#### `Dredger::IoT::Bus::GPIOLibgpiod`
+
+FFI-based GPIO access using libgpiod.
+
+**Methods:**
+- `set_direction(pin, direction)` - Set pin as `:in` or `:out`
+- `write(pin, value)` - Write `0` or `1` to output pin
+- `read(pin)` - Read current value from pin (returns `0` or `1`)
+- `close` - Release GPIO resources
+
+#### `Dredger::IoT::Bus::I2CLinux`
+
+FFI-based I2C access using Linux i2c-dev.
+
+**Methods:**
+- `write(addr, data)` - Write bytes to I2C device at address
+- `read(addr, count)` - Read bytes from I2C device
+- `write_read(addr, write_data, read_count)` - Combined write then read
+- `close` - Release I2C bus
+
+### Sensors
+
+All sensors follow a common interface:
+
+```ruby path=null start=null
+sensor = Dredger::IoT::Sensors::SensorClass.new(
+  # Sensor-specific parameters
+  provider: provider_instance,
+  metadata: { custom: 'data' }  # Optional metadata
+)
+
+readings = sensor.readings  # Returns array of Reading objects
+```
+
+#### `Reading` Object
+
+```ruby path=null start=null
+reading.sensor_type  # e.g., 'temperature', 'humidity', 'pressure'
+reading.value        # Numeric value
+reading.unit         # Unit string (e.g., 'celsius', '%', 'kPa')
+reading.metadata     # Hash of custom metadata
+reading.timestamp    # Time object when reading was taken
+```
+
+#### Available Sensors
+
+- **`DHT22`** - Temperature/humidity (GPIO)
+  - Parameters: `pin_label`, `provider`
+  - Returns: temperature (celsius), humidity (%)
+  
+- **`BME280`** - Environmental sensor (I2C)
+  - Parameters: `i2c_addr` (default: `0x76`), `provider`
+  - Returns: temperature (celsius), humidity (%), pressure (kPa)
+  
+- **`DS18B20`** - Waterproof temperature (1-Wire)
+  - Parameters: `device_id`, `provider`
+  - Returns: temperature (celsius)
+  
+- **`BMP180`** - Barometric pressure (I2C)
+  - Parameters: `i2c_addr` (default: `0x77`), `provider`
+  - Returns: temperature (celsius), pressure (kPa)
+  
+- **`MCP9808`** - High-accuracy temperature (I2C)
+  - Parameters: `i2c_addr` (default: `0x18`), `provider`
+  - Returns: temperature (celsius)
+
+### Scheduling
+
+#### `Dredger::IoT::Scheduler.periodic_with_jitter`
+
+Generates intervals with randomized jitter to avoid harmonic patterns.
+
+```ruby path=null start=null
+scheduler = Dredger::IoT::Scheduler.periodic_with_jitter(
+  base_interval: 60.0,   # Base interval in seconds
+  jitter_ratio: 0.1      # ±10% jitter
+)
+
+scheduler.each { |interval| sleep interval; poll_sensors }
+```
+
+#### `Dredger::IoT::Scheduler.exponential_backoff`
+
+Generates exponentially increasing delays for retry logic.
+
+```ruby path=null start=null
+backoff = Dredger::IoT::Scheduler.exponential_backoff(
+  base: 1.0,      # Initial delay
+  max: 30.0,      # Maximum delay
+  attempts: 5     # Number of attempts
+)
+
+backoff.each { |delay| sleep delay; break if retry_operation }
+```
+
+## Notes
+
+- libgpiod and i2c-dev backends are optional and only required on hardware.
+- You can explicitly `require 'dredger/iot/bus/gpio_libgpiod'` or `'dredger/iot/bus/i2c_linux'` when running on target devices.
+- The Auto API will attempt to load these backends if it detects the corresponding device nodes are present.
+- Simulation backends are perfect for development and testing without hardware access.

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Bus
+      module Auto
+        module_function
+
+        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        def gpio(prefer: :auto, chip: 'gpiochip0', active_low: false)
+          pref = prefer_from_env(ENV.fetch('DREDGER_IOT_GPIO_BACKEND', nil), prefer)
+          case pref
+          when :simulation
+            Dredger::IoT::Bus::GPIO.new
+          when :libgpiod
+            begin
+              safe_require('dredger/iot/bus/gpio_libgpiod')
+              safe_require('dredger/iot/bus/gpio_label_adapter')
+              raw = Dredger::IoT::Bus::GpioLibgpiod.new(chip: chip, active_low: active_low)
+              backend = Dredger::IoT::Bus::GPIOLabelAdapter.new(backend: raw)
+              Dredger::IoT::Bus::GPIO.new(backend: backend)
+            rescue LoadError
+              Dredger::IoT::Bus::GPIO.new
+            end
+          else # :auto
+            if File.exist?('/dev/gpiochip0')
+              begin
+                safe_require('dredger/iot/bus/gpio_libgpiod')
+                safe_require('dredger/iot/bus/gpio_label_adapter')
+                raw = Dredger::IoT::Bus::GpioLibgpiod.new(chip: chip, active_low: active_low)
+                backend = Dredger::IoT::Bus::GPIOLabelAdapter.new(backend: raw)
+                return Dredger::IoT::Bus::GPIO.new(backend: backend)
+              rescue LoadError
+                # fallthrough
+              end
+            end
+            Dredger::IoT::Bus::GPIO.new
+          end
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+        # rubocop:disable Metrics/MethodLength
+        def i2c(prefer: :auto, bus_path: '/dev/i2c-1')
+          pref = prefer_from_env(ENV.fetch('DREDGER_IOT_I2C_BACKEND', nil), prefer)
+          case pref
+          when :simulation
+            Dredger::IoT::Bus::I2C.new
+          when :linux
+            begin
+              safe_require('dredger/iot/bus/i2c_linux')
+              backend = Dredger::IoT::Bus::I2cLinux.new(bus_path: bus_path)
+              Dredger::IoT::Bus::I2C.new(backend: backend)
+            rescue LoadError
+              Dredger::IoT::Bus::I2C.new
+            end
+          else # :auto
+            if File.exist?(bus_path)
+              begin
+                safe_require('dredger/iot/bus/i2c_linux')
+                backend = Dredger::IoT::Bus::I2cLinux.new(bus_path: bus_path)
+                return Dredger::IoT::Bus::I2C.new(backend: backend)
+              rescue LoadError
+                # fallthrough
+              end
+            end
+            Dredger::IoT::Bus::I2C.new
+          end
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        def prefer_from_env(env_value, default)
+          case env_value&.downcase
+          when 'simulation' then :simulation
+          when 'libgpiod' then :libgpiod
+          when 'linux' then :linux
+          else default
+          end
+        end
+
+        def safe_require(path)
+          require path
+        end
+      end
+    end
+  end
+end
+# EOF