dredger-iot 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84cb846712d4d17f969147389859dfae1bdc8a67fb304e491e857891726d7234
-  data.tar.gz: 5c905f7f6e651692f6eff7145e9b9399357df33e340d4694eceab260f31b1b00
+  metadata.gz: 701ad99dd1f271df310ba3dffbb3295084b54e64689f4d3ed77f9b6ab9e31df5
+  data.tar.gz: e9b5ba95c4d2af83b529e6f66af5c81fb83c43f3f679e89e894209661651f93e
 SHA512:
-  metadata.gz: a0cfe26a32e99b21b3a6ccbddede15162bf85f7a85aac6e32715f34cc8a300218515e358bbd271cd5dd648d9ca6df892eb4fda2cd3bf08761a128c25887142ba
-  data.tar.gz: 179a10159ea14047fa146ed5a03223c2f362591357c39c754fef36718d75c2c35fff7bb0e7facafc9c094e48d0015e5eef0a367ca10cb4f93674e0369f2fa6f8
+  metadata.gz: 5362ae41f8f92d403809728857c139b00e3d8141e8f83725a3cc302eb7e7ace2c32b8bd7306fba5e83c2ee197e42c633b7beaeb9a84b9b77f1d95299e80aad1d
+  data.tar.gz: 220b5834cd302cef375c3922211c055788855d4b516b7260aa952d13fc312a3f9c028248863906e93a38badbd32839d2083783bb1431ba5fd1ada0b4df92bca5

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+
+## [0.3.0] - 2025-10-06
+
+### Added
+- New sensors for industrial IoT applications:
+  - **ADXL345** - I2C 3-axis accelerometer for vibration monitoring (±2g, ±4g, ±8g, ±16g ranges)
+  - **SCD30** - I2C NDIR CO2 sensor with integrated temperature and humidity (400-10,000 ppm range)
+  - **YF-S201** - GPIO hall effect flow meter for liquid flow measurement (1-30 L/min range)
+  - **NEO-6M** - UART/Serial GPS module with NMEA 0183 parsing for location tracking
+- README: comprehensive usage examples for all new sensors
+- README: organized sensor list by category (Environmental, Light & Motion, Industrial)
+
+## [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 +82,9 @@ 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.3.0...HEAD
+[0.3.0]: https://github.com/TheMadBotterINC/dredger-iot/compare/v0.2.1...v0.3.0
+[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.
@@ -93,15 +113,24 @@ If you run on a development host (no /dev/gpiochip0), Auto will default to the s
 
 Dredger-IoT includes drivers for popular embedded sensors:
 
+**Environmental 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
 - **SHT31** - I2C temperature/humidity sensor
+- **DS18B20** - 1-Wire digital temperature sensor
+- **SCD30** - I2C NDIR CO2/temperature/humidity sensor (NEW)
+
+**Light & Motion Sensors:**
 - **BH1750** - I2C ambient light sensor (lux)
 - **TSL2561** - I2C ambient light sensor (lux)
+- **ADXL345** - I2C 3-axis accelerometer (vibration monitoring) (NEW)
+
+**Industrial Sensors:**
 - **INA219** - I2C bus voltage/current monitor
+- **YF-S201** - GPIO hall effect flow meter (liquid flow) (NEW)
+- **NEO-6M** - UART/Serial GPS module (location tracking) (NEW)
 
 Sensors use a provider pattern for testability and hardware abstraction.
 
@@ -225,6 +254,101 @@ temp = sensor.readings.first
 puts "#{temp.value}°C"
 ```
 
+### ADXL345 Accelerometer (Vibration Monitoring)
+
+```ruby path=null start=null
+require 'dredger/iot'
+
+# Set up I2C bus and ADXL345 provider
+i2c = Dredger::IoT::Bus::Auto.i2c
+provider = Dredger::IoT::Sensors::ADXL345Provider.new(i2c_bus: i2c, range: 2) # ±2g
+
+# Create sensor instance (default I2C address 0x53)
+sensor = Dredger::IoT::Sensors::ADXL345.new(
+  i2c_addr: 0x53,
+  provider: provider,
+  metadata: { location: 'motor_mount' }
+)
+
+readings = sensor.readings
+readings.each { |r| puts "#{r.sensor_type}: #{r.value} #{r.unit}" }
+# => acceleration_x: 0.024 g
+# => acceleration_y: -0.012 g
+# => acceleration_z: 0.980 g
+```
+
+### SCD30 CO2 Sensor
+
+```ruby path=null start=null
+require 'dredger/iot'
+
+# Set up I2C bus and SCD30 provider
+i2c = Dredger::IoT::Bus::Auto.i2c
+provider = Dredger::IoT::Sensors::SCD30Provider.new(i2c_bus: i2c, interval: 2)
+
+# Create sensor instance (default I2C address 0x61)
+sensor = Dredger::IoT::Sensors::SCD30.new(
+  i2c_addr: 0x61,
+  provider: provider,
+  metadata: { location: 'greenhouse' }
+)
+
+readings = sensor.readings
+readings.each { |r| puts "#{r.sensor_type}: #{r.value} #{r.unit}" }
+# => co2: 412.5 ppm
+# => temperature: 23.45 celsius
+# => humidity: 45.2 %
+```
+
+### YF-S201 Flow Meter
+
+```ruby path=null start=null
+require 'dredger/iot'
+
+# Set up GPIO bus and flow meter provider
+gpio = Dredger::IoT::Bus::Auto.gpio
+provider = Dredger::IoT::Sensors::YFS201Provider.new(gpio_bus: gpio, calibration_factor: 7.5)
+
+# Create sensor instance
+sensor = Dredger::IoT::Sensors::YFS201.new(
+  pin_label: 'P9_12',
+  provider: provider,
+  sample_duration: 1.0, # Count pulses for 1 second
+  metadata: { location: 'main_line' }
+)
+
+readings = sensor.readings
+flow = readings.first
+puts "Flow: #{flow.value} #{flow.unit}"
+puts "Pulses: #{flow.metadata[:pulses]}"
+# => Flow: 5.25 L/min
+# => Pulses: 656
+```
+
+### NEO-6M GPS Module
+
+```ruby path=null start=null
+require 'dredger/iot'
+
+# Set up GPS provider
+provider = Dredger::IoT::Sensors::NEO6MProvider.new(baud_rate: 9600, timeout: 5)
+
+# Create sensor instance
+sensor = Dredger::IoT::Sensors::NEO6M.new(
+  device: '/dev/ttyAMA0', # Serial device
+  provider: provider,
+  metadata: { vehicle: 'truck_1' }
+)
+
+readings = sensor.readings
+readings.each { |r| puts "#{r.sensor_type}: #{r.value} #{r.unit}" }
+# => latitude: 37.774929 degrees
+# => longitude: -122.419418 degrees
+# => altitude: 52.4 m
+# => speed: 12.5 km/h
+# => gps_quality: 8 satellites
+```
+
 ### Multiple Sensors with Scheduled Polling
 
 ```ruby path=null start=null
@@ -353,6 +477,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:
@@ -553,6 +700,25 @@ reading.timestamp    # Time object when reading was taken
     dredger read ina219 0x40 --shunt 0.1
     ```
 
+- **`ADXL345`** - 3-axis accelerometer (I2C)
+  - Parameters: `i2c_addr` (default: `0x53`), `provider`
+  - Returns: acceleration_x (g), acceleration_y (g), acceleration_z (g)
+  - Ranges: ±2g, ±4g, ±8g, ±16g (configurable in provider)
+  
+- **`SCD30`** - NDIR CO2 sensor (I2C)
+  - Parameters: `i2c_addr` (default: `0x61`), `provider`
+  - Returns: co2 (ppm), temperature (celsius), humidity (%)
+  - Range: 400-10,000 ppm CO2
+  
+- **`YFS201`** - Hall effect flow meter (GPIO)
+  - Parameters: `pin_label`, `provider`, `sample_duration` (default: `1.0`)
+  - Returns: flow_rate (L/min)
+  - Range: 1-30 L/min
+  
+- **`NEO6M`** - GPS module (UART/Serial)
+  - Parameters: `device` (default: `'/dev/ttyAMA0'`), `provider`
+  - Returns: latitude (degrees), longitude (degrees), altitude (m), speed (km/h), gps_quality (satellites)
+
 ### Scheduling
 
 #### `Dredger::IoT::Scheduler.periodic_with_jitter`

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/sensors/adxl345.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Sensors
+      # ADXL345 3-axis digital accelerometer sensor (I2C/SPI)
+      # Measures acceleration/vibration in x, y, z axes
+      # Uses a provider interface to allow simulation in tests and hardware backends in production.
+      class ADXL345 < BaseSensor
+        # provider must respond to :read_measurements(i2c_addr) -> { x_g:, y_g:, z_g: }
+        def initialize(i2c_addr: 0x53, provider:, metadata: {})
+          super(metadata: metadata)
+          @i2c_addr = i2c_addr
+          @provider = provider
+        end
+
+        def readings
+          sample = @provider.read_measurements(@i2c_addr)
+          [
+            reading(sensor_type: 'acceleration_x', value: sample[:x_g], unit: 'g'),
+            reading(sensor_type: 'acceleration_y', value: sample[:y_g], unit: 'g'),
+            reading(sensor_type: 'acceleration_z', value: sample[:z_g], unit: 'g')
+          ]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Sensors
+      # Hardware provider for ADXL345 3-axis accelerometer over I2C.
+      # Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/ADXL345.pdf
+      #
+      # Key features:
+      # - ±2g, ±4g, ±8g, ±16g selectable measurement ranges
+      # - 10-bit to 13-bit resolution
+      # - I2C (up to 400 kHz) or SPI interface
+      # - Default I2C address: 0x53 (ALT address: 0x1D if SDO/ALT pulled high)
+      #
+      # Key registers:
+      # - 0x00: DEVID (should be 0xE5)
+      # - 0x2D: POWER_CTL (power modes)
+      # - 0x31: DATA_FORMAT (range and resolution)
+      # - 0x32-0x37: DATAX0, DATAX1, DATAY0, DATAY1, DATAZ0, DATAZ1 (acceleration data)
+      class ADXL345Provider
+        DEVID_REG = 0x00
+        DEVID_EXPECTED = 0xE5
+        POWER_CTL_REG = 0x2D
+        DATA_FORMAT_REG = 0x31
+        DATAX0_REG = 0x32
+
+        # Measurement mode bit (POWER_CTL register)
+        MEASURE_BIT = 0x08
+
+        # i2c_bus: an I2C bus interface (e.g., Dredger::IoT::Bus::Auto.i2c)
+        # range: measurement range in g (2, 4, 8, or 16)
+        def initialize(i2c_bus:, range: 2)
+          @i2c = i2c_bus
+          @range = range
+          @scale_factor = calculate_scale_factor(range)
+        end
+
+        # Read acceleration measurements from the ADXL345 at the given I2C address.
+        # Returns { x_g: Float, y_g: Float, z_g: Float }
+        def read_measurements(addr)
+          # Verify device ID
+          dev_id = @i2c.read(addr, 1, register: DEVID_REG).first
+          raise IOError, "ADXL345 not found (devid=0x#{dev_id.to_s(16)})" unless dev_id == DEVID_EXPECTED
+
+          # Configure sensor (one-time setup)
+          configure_sensor(addr)
+
+          # Read 6 bytes of acceleration data (X, Y, Z as 16-bit signed integers)
+          raw = @i2c.read(addr, 6, register: DATAX0_REG)
+
+          # Parse 16-bit signed values (little-endian)
+          x_raw = to_signed16(raw[0] | (raw[1] << 8))
+          y_raw = to_signed16(raw[2] | (raw[3] << 8))
+          z_raw = to_signed16(raw[4] | (raw[5] << 8))
+
+          # Convert to g units using scale factor
+          {
+            x_g: (x_raw * @scale_factor).round(3),
+            y_g: (y_raw * @scale_factor).round(3),
+            z_g: (z_raw * @scale_factor).round(3)
+          }
+        end
+
+        private
+
+        # Configure sensor for measurement mode with specified range
+        def configure_sensor(addr)
+          # Set data format: range bits [1:0]
+          # ±2g: 0b00, ±4g: 0b01, ±8g: 0b10, ±16g: 0b11
+          range_bits = case @range
+                       when 2 then 0b00
+                       when 4 then 0b01
+                       when 8 then 0b10
+                       when 16 then 0b11
+                       else raise ArgumentError, "Invalid range: #{@range}g (must be 2, 4, 8, or 16)"
+                       end
+          @i2c.write(addr, [range_bits], register: DATA_FORMAT_REG)
+
+          # Enable measurement mode
+          @i2c.write(addr, [MEASURE_BIT], register: POWER_CTL_REG)
+
+          # Wait for sensor to stabilize
+          sleep(0.01)
+        end
+
+        # Calculate scale factor for converting raw values to g
+        # ADXL345 uses 10-bit resolution in full resolution mode
+        # Scale factor: range / 512 (for 10-bit)
+        def calculate_scale_factor(range)
+          # In full resolution mode, scale is ~3.9 mg/LSB regardless of range
+          # In fixed 10-bit mode, scale depends on range
+          # Using simplified calculation: range / 512
+          range / 512.0
+        end
+
+        # Convert unsigned 16-bit to signed 16-bit
+        def to_signed16(val)
+          val > 32_767 ? val - 65_536 : val
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Sensors
+      # NEO-6M GPS module (UART/Serial)
+      # Provides location, altitude, speed, and satellite information
+      # Uses a provider interface to allow simulation in tests and hardware backends in production.
+      class NEO6M < BaseSensor
+        # provider must respond to :read_position(device) -> { latitude:, longitude:, altitude:, speed:, satellites: }
+        def initialize(device: '/dev/ttyAMA0', provider:, metadata: {})
+          super(metadata: metadata)
+          @device = device
+          @provider = provider
+        end
+
+        def readings
+          sample = @provider.read_position(@device)
+          [
+            reading(sensor_type: 'latitude', value: sample[:latitude], unit: 'degrees'),
+            reading(sensor_type: 'longitude', value: sample[:longitude], unit: 'degrees'),
+            reading(sensor_type: 'altitude', value: sample[:altitude], unit: 'm'),
+            reading(sensor_type: 'speed', value: sample[:speed], unit: 'km/h'),
+            reading(
+              sensor_type: 'gps_quality',
+              value: sample[:satellites],
+              unit: 'satellites',
+              metadata: { fix_quality: sample[:fix_quality] }
+            )
+          ]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'io/wait'
+
+module Dredger
+  module IoT
+    module Sensors
+      # Hardware provider for NEO-6M GPS module via UART/Serial with NMEA parsing.
+      # Datasheet: https://www.u-blox.com/sites/default/files/products/documents/NEO-6_DataSheet_(GPS.G6-HW-09005).pdf
+      #
+      # Key features:
+      # - 50-channel GPS receiver
+      # - UART interface (default: 9600 baud, 8N1)
+      # - NMEA 0183 protocol output
+      # - Update rate: 1-5 Hz (default: 1 Hz)
+      # - Cold start: ~27s, Warm start: ~1s
+      #
+      # NMEA Sentences:
+      # - $GPGGA: Global Positioning System Fix Data (position, altitude, satellites)
+      # - $GPRMC: Recommended Minimum Navigation Information (position, speed, date/time)
+      # - $GPGSA: GPS DOP and Active Satellites
+      # - $GPGSV: GPS Satellites in View
+      class NEO6MProvider
+        # baud_rate: serial baud rate (default: 9600)
+        # timeout: read timeout in seconds (default: 5)
+        def initialize(baud_rate: 9600, timeout: 5)
+          @baud_rate = baud_rate
+          @timeout = timeout
+        end
+
+        # Read GPS position by parsing NMEA sentences from the serial device.
+        # Returns { latitude: Float, longitude: Float, altitude: Float, speed: Float, satellites: Integer, fix_quality: Integer }
+        #
+        # @param device [String] Serial device path (e.g., '/dev/ttyAMA0', '/dev/ttyUSB0')
+        def read_position(device)
+          File.open(device, 'r+') do |serial|
+            configure_serial(serial)
+
+            # Read NMEA sentences until we have both GGA and RMC (or timeout)
+            gga_data = nil
+            rmc_data = nil
+            start_time = Time.now
+
+            while (gga_data.nil? || rmc_data.nil?) && (Time.now - start_time < @timeout)
+              line = read_line(serial, @timeout)
+              next unless line
+
+              if line.start_with?('$GPGGA') || line.start_with?('$GNGGA')
+                gga_data = parse_gga(line)
+              elsif line.start_with?('$GPRMC') || line.start_with?('$GNRMC')
+                rmc_data = parse_rmc(line)
+              end
+            end
+
+            raise IOError, 'GPS timeout: no valid NMEA sentences received' if gga_data.nil? && rmc_data.nil?
+
+            # Merge data from both sentences (GGA has altitude/satellites, RMC has speed)
+            {
+              latitude: gga_data&.dig(:latitude) || rmc_data&.dig(:latitude) || 0.0,
+              longitude: gga_data&.dig(:longitude) || rmc_data&.dig(:longitude) || 0.0,
+              altitude: gga_data&.dig(:altitude) || 0.0,
+              speed: rmc_data&.dig(:speed) || 0.0,
+              satellites: gga_data&.dig(:satellites) || 0,
+              fix_quality: gga_data&.dig(:fix_quality) || 0
+            }
+          end
+        end
+
+        private
+
+        # Configure serial port (Linux termios settings)
+        def configure_serial(serial)
+          # Set raw mode, no echo, baud rate
+          # This would typically use `stty` or `termios` gem
+          # For simplicity, assuming device is already configured
+          # In production, use: system("stty -F #{device} #{@baud_rate} raw -echo")
+        end
+
+        # Read a line from serial with timeout
+        def read_line(serial, timeout)
+          return nil unless serial.wait_readable(timeout)
+
+          serial.gets&.chomp
+        end
+
+        # Parse $GPGGA sentence: Global Positioning System Fix Data
+        # Format: $GPGGA,hhmmss.ss,llll.ll,a,yyyyy.yy,a,x,xx,x.x,x.x,M,x.x,M,x.x,xxxx*hh
+        # Example: $GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47
+        def parse_gga(sentence)
+          parts = sentence.split(',')
+          return nil if parts.size < 15 || parts[6].to_i.zero? # Check fix quality
+
+          {
+            latitude: parse_coordinate(parts[2], parts[3]),
+            longitude: parse_coordinate(parts[4], parts[5]),
+            fix_quality: parts[6].to_i,
+            satellites: parts[7].to_i,
+            altitude: parts[9].to_f
+          }
+        end
+
+        # Parse $GPRMC sentence: Recommended Minimum Navigation Information
+        # Format: $GPRMC,hhmmss.ss,A,llll.ll,a,yyyyy.yy,a,x.x,x.x,ddmmyy,x.x,a*hh
+        # Example: $GPRMC,123519,A,4807.038,N,01131.000,E,022.4,084.4,230394,003.1,W*6A
+        def parse_rmc(sentence)
+          parts = sentence.split(',')
+          return nil if parts.size < 12 || parts[2] != 'A' # Check if data is valid
+
+          {
+            latitude: parse_coordinate(parts[3], parts[4]),
+            longitude: parse_coordinate(parts[5], parts[6]),
+            speed: parts[7].to_f * 1.852 # Convert knots to km/h
+          }
+        end
+
+        # Parse NMEA coordinate format (ddmm.mmmm) to decimal degrees
+        # @param coord_str [String] Coordinate string (e.g., "4807.038")
+        # @param direction [String] Direction (N/S for latitude, E/W for longitude)
+        def parse_coordinate(coord_str, direction)
+          return 0.0 if coord_str.nil? || coord_str.empty?
+
+          # Determine if latitude or longitude based on length
+          # Latitude: ddmm.mmmm (2 digit degrees)
+          # Longitude: dddmm.mmmm (3 digit degrees)
+          degree_digits = coord_str.length >= 5 && coord_str[4] == '.' ? 2 : 3
+
+          degrees = coord_str[0, degree_digits].to_f
+          minutes = coord_str[degree_digits..-1].to_f
+
+          decimal_degrees = degrees + (minutes / 60.0)
+
+          # Apply direction (negative for South and West)
+          decimal_degrees *= -1 if %w[S W].include?(direction)
+
+          decimal_degrees.round(6)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Sensors
+      # SCD30 NDIR CO2 sensor with integrated temperature and humidity sensor
+      # Measures CO2 concentration, temperature, and humidity
+      # Uses a provider interface to allow simulation in tests and hardware backends in production.
+      class SCD30 < BaseSensor
+        # provider must respond to :read_measurements(i2c_addr) -> { co2_ppm:, temperature_c:, humidity: }
+        def initialize(i2c_addr: 0x61, provider:, metadata: {})
+          super(metadata: metadata)
+          @i2c_addr = i2c_addr
+          @provider = provider
+        end
+
+        def readings
+          sample = @provider.read_measurements(@i2c_addr)
+          [
+            reading(sensor_type: 'co2', value: sample[:co2_ppm], unit: 'ppm'),
+            reading(sensor_type: 'temperature', value: sample[:temperature_c], unit: 'celsius'),
+            reading(sensor_type: 'humidity', value: sample[:humidity], unit: '%')
+          ]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Sensors
+      # Hardware provider for SCD30 CO2, temperature, and humidity sensor over I2C.
+      # Datasheet: https://sensirion.com/media/documents/4EAF6AF8/61652C3C/Sensirion_CO2_Sensors_SCD30_Datasheet.pdf
+      #
+      # Key features:
+      # - NDIR CO2 sensor (400-10,000 ppm range)
+      # - Integrated SHT31 temperature and humidity sensor
+      # - I2C interface (default address: 0x61)
+      # - Automatic self-calibration
+      # - Measurement interval: 2-1800 seconds
+      #
+      # Key commands:
+      # - 0x0010: Start continuous measurement
+      # - 0x0104: Stop continuous measurement
+      # - 0x0202: Set measurement interval
+      # - 0x0300: Data ready status
+      # - 0x0027: Read measurement (18 bytes: CO2, temp, humidity)
+      class SCD30Provider
+        CMD_START_MEASUREMENT = 0x0010
+        CMD_STOP_MEASUREMENT = 0x0104
+        CMD_SET_INTERVAL = 0x0202
+        CMD_DATA_READY = 0x0300
+        CMD_READ_MEASUREMENT = 0x0027
+
+        # i2c_bus: an I2C bus interface (e.g., Dredger::IoT::Bus::Auto.i2c)
+        # interval: measurement interval in seconds (2-1800)
+        # ambient_pressure: ambient pressure compensation in mBar (700-1400, 0=disable)
+        def initialize(i2c_bus:, interval: 2, ambient_pressure: 0)
+          @i2c = i2c_bus
+          @interval = interval
+          @ambient_pressure = ambient_pressure
+          @initialized = false
+        end
+
+        # Read measurements from the SCD30 at the given I2C address.
+        # Returns { co2_ppm: Float, temperature_c: Float, humidity: Float }
+        def read_measurements(addr)
+          # Initialize sensor on first read
+          initialize_sensor(addr) unless @initialized
+
+          # Wait for data ready
+          wait_for_data_ready(addr)
+
+          # Read 18 bytes of measurement data
+          # Format: [CO2_MSB, CO2_LSB, CO2_CRC] [CO2_MSB, CO2_LSB, CO2_CRC] [T_MSB, T_LSB, T_CRC] [T_MSB, T_LSB, T_CRC] [H_MSB, H_LSB, H_CRC] [H_MSB, H_LSB, H_CRC]
+          # Actually: 3 float32 values (4 bytes each + CRC after every 2 bytes = 6 bytes per value)
+          @i2c.write(addr, [CMD_READ_MEASUREMENT >> 8, CMD_READ_MEASUREMENT & 0xFF])
+          sleep(0.01) # Wait for response
+          raw = @i2c.read(addr, 18)
+
+          # Parse float32 values with CRC validation
+          co2_ppm = parse_float32_with_crc(raw, 0)
+          temp_c = parse_float32_with_crc(raw, 6)
+          humidity = parse_float32_with_crc(raw, 12)
+
+          {
+            co2_ppm: co2_ppm.round(1),
+            temperature_c: temp_c.round(2),
+            humidity: humidity.round(1)
+          }
+        end
+
+        private
+
+        # Initialize sensor with measurement interval and start continuous measurement
+        def initialize_sensor(addr)
+          # Set measurement interval
+          write_command_with_arg(addr, CMD_SET_INTERVAL, @interval)
+          sleep(0.01)
+
+          # Start continuous measurement with optional pressure compensation
+          write_command_with_arg(addr, CMD_START_MEASUREMENT, @ambient_pressure)
+          sleep(0.02)
+
+          @initialized = true
+        end
+
+        # Wait for data to be ready (poll data ready status)
+        def wait_for_data_ready(addr, timeout: 2.0)
+          start_time = Time.now
+          loop do
+            @i2c.write(addr, [CMD_DATA_READY >> 8, CMD_DATA_READY & 0xFF])
+            sleep(0.01)
+            status = @i2c.read(addr, 3)
+            # Data ready when bit 0 of word is 1
+            data_ready = (status[1] & 0x01) == 1
+            return if data_ready
+
+            raise IOError, 'SCD30 data ready timeout' if Time.now - start_time > timeout
+
+            sleep(0.1)
+          end
+        end
+
+        # Write a command with a 16-bit argument and CRC
+        def write_command_with_arg(addr, command, arg)
+          cmd_msb = command >> 8
+          cmd_lsb = command & 0xFF
+          arg_msb = arg >> 8
+          arg_lsb = arg & 0xFF
+          crc = calculate_crc8([arg_msb, arg_lsb])
+          @i2c.write(addr, [cmd_msb, cmd_lsb, arg_msb, arg_lsb, crc])
+        end
+
+        # Parse a float32 value from 6 bytes (4 data + 2 CRC)
+        # Format: [MSB0, LSB0, CRC0, MSB1, LSB1, CRC1]
+        def parse_float32_with_crc(data, offset)
+          # Verify CRCs
+          crc0 = calculate_crc8([data[offset], data[offset + 1]])
+          crc1 = calculate_crc8([data[offset + 3], data[offset + 4]])
+          raise IOError, 'SCD30 CRC error' unless crc0 == data[offset + 2] && crc1 == data[offset + 5]
+
+          # Combine bytes into uint32 and convert to float32
+          bytes = [
+            data[offset],
+            data[offset + 1],
+            data[offset + 3],
+            data[offset + 4]
+          ].pack('C4').unpack1('N')
+          [bytes].pack('L>').unpack1('g')
+        end
+
+        # Calculate CRC-8 checksum (polynomial: 0x31, init: 0xFF)
+        def calculate_crc8(data)
+          crc = 0xFF
+          data.each do |byte|
+            crc ^= byte
+            8.times do
+              crc = (crc & 0x80) != 0 ? ((crc << 1) ^ 0x31) : (crc << 1)
+              crc &= 0xFF
+            end
+          end
+          crc
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Sensors
+      # YF-S201 water flow sensor (hall effect pulse counter)
+      # Measures liquid flow rate by counting pulses from hall effect sensor
+      # Uses a provider interface to allow simulation in tests and hardware backends in production.
+      class YFS201 < BaseSensor
+        # provider must respond to :read_flow_rate(pin_label, duration) -> { flow_rate_lpm: Float, pulses: Integer }
+        def initialize(pin_label:, provider:, sample_duration: 1.0, metadata: {})
+          super(metadata: metadata)
+          @pin_label = pin_label
+          @provider = provider
+          @sample_duration = sample_duration
+        end
+
+        def readings
+          sample = @provider.read_flow_rate(@pin_label, @sample_duration)
+          [
+            reading(
+              sensor_type: 'flow_rate',
+              value: sample[:flow_rate_lpm],
+              unit: 'L/min',
+              metadata: { pulses: sample[:pulses], duration: @sample_duration }
+            )
+          ]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Dredger
+  module IoT
+    module Sensors
+      # Hardware provider for YF-S201 water flow sensor via GPIO pulse counting.
+      # Datasheet: https://www.hobbytronics.co.uk/download/YF-S201.pdf
+      #
+      # Key features:
+      # - Hall effect sensor with digital output
+      # - Flow rate range: 1-30 L/min
+      # - Pulse frequency: ~4.5 * flow_rate (L/min)
+      # - Working voltage: 5V DC
+      # - Thread size: G1/2" (DN15)
+      #
+      # Calibration:
+      # - Frequency (Hz) = 7.5 * flow rate (L/min) (official spec)
+      # - In practice: F = K * Q where K ≈ 4.5-7.5 depending on unit
+      # - Default calibration factor: 7.5 (pulses per liter)
+      class YFS201Provider
+        # gpio_bus: a GPIO bus interface (e.g., Dredger::IoT::Bus::Auto.gpio)
+        # calibration_factor: pulses per liter (default: 7.5 for YF-S201)
+        def initialize(gpio_bus:, calibration_factor: 7.5)
+          @gpio = gpio_bus
+          @calibration_factor = calibration_factor
+        end
+
+        # Read flow rate by counting pulses over the specified duration.
+        # Returns { flow_rate_lpm: Float, pulses: Integer }
+        #
+        # @param pin_label [String] GPIO pin label (e.g., 'P9_12', 'GPIO17')
+        # @param duration [Float] Sampling duration in seconds
+        def read_flow_rate(pin_label, duration)
+          # Configure pin as input
+          @gpio.set_direction(pin_label, :in)
+
+          # Count rising edge pulses over the duration
+          pulses = count_pulses(pin_label, duration)
+
+          # Calculate flow rate in L/min
+          # pulses_per_second = pulses / duration
+          # liters_per_second = pulses_per_second / calibration_factor
+          # liters_per_minute = liters_per_second * 60
+          flow_rate_lpm = (pulses / duration / @calibration_factor * 60.0).round(2)
+
+          {
+            flow_rate_lpm: flow_rate_lpm,
+            pulses: pulses
+          }
+        end
+
+        private
+
+        # Count rising edge transitions on the pin over the specified duration.
+        # This is a simplified implementation - production code should use:
+        # - Hardware interrupts (kernel module or pigpio daemon)
+        # - Edge detection via sysfs GPIO (epoll)
+        # - High-priority thread for accurate timing
+        def count_pulses(pin_label, duration)
+          pulses = 0
+          last_state = @gpio.read(pin_label)
+          start_time = Time.now
+
+          # Poll GPIO at high frequency to detect edges
+          # Note: This is CPU-intensive and timing-dependent
+          # For production, use hardware interrupts or kernel GPIO edge detection
+          while Time.now - start_time < duration
+            current_state = @gpio.read(pin_label)
+            
+            # Detect rising edge (0 -> 1 transition)
+            if current_state == 1 && last_state == 0
+              pulses += 1
+            end
+            
+            last_state = current_state
+            
+            # Small sleep to reduce CPU usage
+            # Trade-off: Higher sleep = lower CPU, but may miss pulses
+            # For accurate counting, use interrupts instead
+            sleep(0.0001) # 0.1ms
+          end
+
+          pulses
+        end
+      end
+    end
+  end
+end

data/lib/dredger/iot/sensors.rb

@@ -17,3 +17,11 @@ require_relative 'sensors/tsl2561'
 require_relative 'sensors/tsl2561_provider'
 require_relative 'sensors/ina219'
 require_relative 'sensors/ina219_provider'
+require_relative 'sensors/adxl345'
+require_relative 'sensors/adxl345_provider'
+require_relative 'sensors/scd30'
+require_relative 'sensors/scd30_provider'
+require_relative 'sensors/yf_s201'
+require_relative 'sensors/yf_s201_provider'
+require_relative 'sensors/neo6m'
+require_relative 'sensors/neo6m_provider'

data/lib/dredger/iot/version.rb

@@ -2,6 +2,6 @@
 
 module Dredger
   module IoT
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   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.3.0
 platform: ruby
 authors:
 - The Mad Botter INC
@@ -49,9 +49,12 @@ 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
+- lib/dredger/iot/sensors/adxl345.rb
+- lib/dredger/iot/sensors/adxl345_provider.rb
 - lib/dredger/iot/sensors/base_sensor.rb
 - lib/dredger/iot/sensors/bh1750.rb
 - lib/dredger/iot/sensors/bh1750_provider.rb
@@ -65,10 +68,16 @@ files:
 - lib/dredger/iot/sensors/ina219.rb
 - lib/dredger/iot/sensors/ina219_provider.rb
 - lib/dredger/iot/sensors/mcp9808.rb
+- lib/dredger/iot/sensors/neo6m.rb
+- lib/dredger/iot/sensors/neo6m_provider.rb
+- lib/dredger/iot/sensors/scd30.rb
+- lib/dredger/iot/sensors/scd30_provider.rb
 - lib/dredger/iot/sensors/sht31.rb
 - lib/dredger/iot/sensors/sht31_provider.rb
 - lib/dredger/iot/sensors/tsl2561.rb
 - lib/dredger/iot/sensors/tsl2561_provider.rb
+- lib/dredger/iot/sensors/yf_s201.rb
+- lib/dredger/iot/sensors/yf_s201_provider.rb
 - lib/dredger/iot/version.rb
 homepage: https://github.com/TheMadBotterINC/dredger-iot
 licenses:
@@ -97,7 +106,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.3.0\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