dredger-iot 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84cb846712d4d17f969147389859dfae1bdc8a67fb304e491e857891726d7234
-  data.tar.gz: 5c905f7f6e651692f6eff7145e9b9399357df33e340d4694eceab260f31b1b00
+  metadata.gz: 6710d17818b007805d0634e65fde9048c5fb191b9a11d4c5ac3d09aeccf9483e
+  data.tar.gz: cb7d2e68d335ee490f902b9eaed4b30b6499b8a688336f47678619e862b48cf6
 SHA512:
-  metadata.gz: a0cfe26a32e99b21b3a6ccbddede15162bf85f7a85aac6e32715f34cc8a300218515e358bbd271cd5dd648d9ca6df892eb4fda2cd3bf08761a128c25887142ba
-  data.tar.gz: 179a10159ea14047fa146ed5a03223c2f362591357c39c754fef36718d75c2c35fff7bb0e7facafc9c094e48d0015e5eef0a367ca10cb4f93674e0369f2fa6f8
+  metadata.gz: c14e577283263ea3a3674280cf416bde53ce0c172776fe85c2a9bde00835d7b42fd5badf5bcff6e8dc16b041abae9d810ad7fe510f2afbb86a1c7ffcf0b9d35b
+  data.tar.gz: bb7fc628012d3f9e26d83a792e24fdf20493de7cf984dee32a17658221aa53a7e5b208c49bbd528bb431320354edec09b3dd4506b52fff1b05ae6b4965de1daf

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2025-10-05
+
+### Added
+- Examples: Raspberry Pi GPIO blink script (GPIO17)
+- Docs: Raspberry Pi OS instructions to enable I2C and 1-Wire
+
 ## [0.2.0] - 2025-10-05
 
 ### Added
@@ -64,7 +70,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - RuboCop configuration and compliance
 - Comprehensive documentation and usage examples
 
-[Unreleased]: https://github.com/TheMadBotterINC/dredger-iot/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/TheMadBotterINC/dredger-iot/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/TheMadBotterINC/dredger-iot/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/TheMadBotterINC/dredger-iot/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/TheMadBotterINC/dredger-iot/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/TheMadBotterINC/dredger-iot/compare/v0.1.0...v0.1.1

data/README.md

@@ -70,6 +70,26 @@ Environment overrides:
 - `DREDGER_IOT_GPIO_BACKEND`: `simulation` | `libgpiod`
 - `DREDGER_IOT_I2C_BACKEND`: `simulation` | `linux`
 
+## Raspberry Pi GPIO label mapping
+
+When the libgpiod backend is selected via Auto, Dredger-IoT resolves Raspberry Pi labels to the corresponding chip:line before accessing the GPIO line. Accepted labels:
+- GPIO17 or BCM17 (Broadcom numbering)
+- PIN11 or BOARD11 (header pin numbers)
+
+On most Raspberry Pi boards, GPIO lines are exposed on gpiochip0 and the line offset matches the BCM number. The adapter will translate labels accordingly.
+
+Example:
+
+```ruby path=null start=null
+require 'dredger/iot'
+
+gpio = Dredger::IoT::Bus::Auto.gpio # picks libgpiod on RPi, otherwise simulation
+
+# Use Raspberry Pi labels
+gpio.set_direction('GPIO17', :out)
+gpio.write('GPIO17', 1)
+```
+
 ## 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.
@@ -353,6 +373,29 @@ ls /sys/bus/w1/devices/
 # Should show devices like: 28-00000xxxxxx
 ```
 
+#### Raspberry Pi OS: Enable I2C and 1-Wire
+
+On Raspberry Pi OS you can enable I2C and 1-Wire via raspi-config or by editing /boot/config.txt.
+
+Option A: raspi-config (recommended)
+```bash path=null start=null
+sudo raspi-config
+# Interface Options → I2C → Enable
+# Interface Options → 1-Wire → Enable
+sudo reboot
+```
+
+Option B: edit /boot/config.txt
+```bash path=null start=null
+# Enable I2C
+sudo sed -i 's/^#\?dtparam=i2c_arm=.*/dtparam=i2c_arm=on/' /boot/config.txt
+# Enable 1-Wire on default BCM4 (PIN7)
+echo 'dtoverlay=w1-gpio,gpiopin=4' | sudo tee -a /boot/config.txt
+sudo reboot
+```
+
+Note: Dredger-IoT accepts Raspberry Pi labels like GPIO17, BCM17, and PIN11.
+
 #### Beaglebone Black Device Tree
 
 For Beaglebone Black, you may need to enable device tree overlays:

data/bin/dredger

@@ -32,6 +32,8 @@ class DredgerCLI
       test_i2c
     when 'info'
       show_info
+    when 'doctor'
+      doctor
     else
       puts parser
       exit 1
@@ -53,6 +55,7 @@ class DredgerCLI
       opts.separator '  read SENSOR [OPTIONS]  Read from a sensor'
       opts.separator '  test-gpio PIN          Test GPIO pin'
       opts.separator '  test-i2c               Scan I2C bus'
+      opts.separator '  doctor                 Check system prerequisites'
       opts.separator '  info                   Show system information'
       opts.separator ''
       opts.separator 'Options:'
@@ -270,6 +273,51 @@ class DredgerCLI
     puts "  DREDGER_IOT_I2C_BACKEND:  #{ENV['DREDGER_IOT_I2C_BACKEND'] || '(not set)'}"
   end
 
+  def doctor
+    puts 'Doctor: checking system prerequisites...'
+    puts
+    check_device_node('/dev/gpiochip0', 'GPIO (libgpiod) device')
+    check_device_node('/dev/i2c-1', 'I2C device (bus 1)')
+    check_path('/sys/bus/w1/devices', '1-Wire bus (DS18B20) directory')
+
+    puts
+    puts 'Kernel modules:'
+    mods = read_proc_modules
+    puts "  i2c-dev: #{mods.include?('i2c_dev') ? 'loaded' : 'missing'}"
+    puts "  w1-gpio: #{mods.include?('w1_gpio') ? 'loaded' : 'missing'}"
+    puts "  w1-therm: #{mods.include?('w1_therm') ? 'loaded' : 'missing'}"
+
+    puts
+    puts 'Recommendations:'
+    puts "  sudo apt-get install gpiod i2c-tools"
+    puts "  sudo usermod -a -G gpio $USER  # for GPIO access"
+    puts "  sudo usermod -a -G i2c $USER   # for I2C access"
+    puts "  sudo modprobe i2c-dev"
+    puts "  sudo modprobe w1-gpio; sudo modprobe w1-therm"
+  end
+
+  def check_device_node(path, desc)
+    if File.exist?(path)
+      puts "  ✔ #{desc}: present (#{path})"
+    else
+      puts "  ✖ #{desc}: missing (#{path})"
+    end
+  end
+
+  def check_path(path, desc)
+    if Dir.exist?(path)
+      puts "  ✔ #{desc}: present (#{path})"
+    else
+      puts "  ✖ #{desc}: missing (#{path})"
+    end
+  end
+
+  def read_proc_modules
+    File.read('/proc/modules')
+  rescue StandardError
+    ''
+  end
+
   def setup_backends
     case @options[:backend]
     when 'simulation'

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

@@ -5,9 +5,11 @@ module Dredger
     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)
+        # mapper can be a single mapper module/class or an Array of them.
+        # Defaults to both Beaglebone and RaspberryPi mappers.
+        def initialize(backend:, mapper: [Dredger::IoT::Pins::Beaglebone, Dredger::IoT::Pins::RaspberryPi])
           @backend = backend
-          @mapper = mapper
+          @mappers = Array(mapper)
         end
 
         def set_direction(pin, direction)
@@ -24,16 +26,24 @@ module Dredger
 
         private
 
+        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         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)
+
+          # Try all mappers in order
+          @mappers.each do |m|
+            if m.respond_to?(:resolve_label_to_pinref) && m.respond_to?(:valid_label?) && m.valid_label?(pin)
+              return m.resolve_label_to_pinref(pin)
+            end
+          end
 
           raise ArgumentError, 'Unsupported pin format'
         end
+        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       end
     end
   end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Pins
+      # Raspberry Pi header/BCM label mapping.
+      # Supports labels like:
+      # - GPIO17, BCM17
+      # - PIN11 (a.k.a. BOARD11)
+      class RaspberryPi
+        PinRef = Struct.new(:label, :chip, :line, keyword_init: true) do
+          def to_s
+            chip && line ? "#{label}(chip#{chip}:#{line})" : label.to_s
+          end
+        end
+
+        # Subset of BOARD pin to BCM mapping for common usable GPIOs on 40-pin header
+        BOARD_TO_BCM = {
+          3 => 2, 5 => 3, 7 => 4, 8 => 14, 10 => 15, 11 => 17, 12 => 18, 13 => 27,
+          15 => 22, 16 => 23, 18 => 24, 19 => 10, 21 => 9, 22 => 25, 23 => 11,
+          24 => 8, 26 => 7, 29 => 5, 31 => 6, 32 => 12, 33 => 13, 35 => 19,
+          36 => 16, 37 => 26, 38 => 20, 40 => 21
+        }.freeze
+
+        # Accept variants like GPIO17, BCM17, PIN11, BOARD11
+        def self.valid_label?(label)
+          s = label.to_s.upcase
+          return true if s.match?(/^(GPIO|BCM)\d+$/)
+          return true if s.match?(/^(PIN|BOARD)\d+$/)
+
+          false
+        end
+
+        def self.resolve_label_to_pinref(label)
+          s = label.to_s.upcase
+          if s =~ /^(GPIO|BCM)(\d+)$/
+            bcm = Regexp.last_match(2).to_i
+            return PinRef.new(label: label.to_s, chip: 0, line: bcm)
+          end
+
+          if s =~ /^(PIN|BOARD)(\d+)$/
+            board = Regexp.last_match(2).to_i
+            bcm = BOARD_TO_BCM[board]
+            raise ArgumentError, "Unknown/unsupported board pin: #{label}" if bcm.nil?
+
+            return PinRef.new(label: label.to_s, chip: 0, line: bcm)
+          end
+
+          raise ArgumentError, "Unknown Raspberry Pi pin label: #{label}"
+        end
+      end
+    end
+  end
+end

data/lib/dredger/iot/pins.rb

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

data/lib/dredger/iot/version.rb

@@ -2,6 +2,6 @@
 
 module Dredger
   module IoT
-    VERSION = '0.2.0'
+    VERSION = '0.2.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dredger-iot
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - The Mad Botter INC
@@ -49,6 +49,7 @@ files:
 - lib/dredger/iot/bus/i2c_linux.rb
 - lib/dredger/iot/pins.rb
 - lib/dredger/iot/pins/beaglebone.rb
+- lib/dredger/iot/pins/raspberry_pi.rb
 - lib/dredger/iot/reading.rb
 - lib/dredger/iot/scheduler.rb
 - lib/dredger/iot/sensors.rb
@@ -97,7 +98,7 @@ post_install_message: "\n    ═════════════════
   \  |                    \n              |_____________________________|                    \n
   \        ~~~       \\                 //          ~~~            \n                    \\_______________//
   \                         \n    ═══════════════════════════════════════════════════════════════════\nHardware
-  Integration for Embedded Linux v0.2.0\n    ═══════════════════════════════════════════════════════════════════\n\n
+  Integration for Embedded Linux v0.2.1\n    ═══════════════════════════════════════════════════════════════════\n\n
   \   \U0001F389 Thanks for installing!\n\n    \U0001F4DA Hardware Setup (kernel modules
   & permissions):\n       https://github.com/TheMadBotterINC/dredger-iot#hardware-setup\n\n
   \   \U0001F680 Quick Start:\n       require 'dredger/iot'\n       gpio = Dredger::IoT::Bus::Auto.gpio\n