rpi_gpio 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf2e5fe321ddea6602db36bf081dcdd9b16d1248a584c9fe2156cf3b1cc8764b
-  data.tar.gz: aea0df6d2ce23b6b60ffdd35a1a856c09920fda38dfdcc197f4d38b417129935
+  metadata.gz: c751d8fda46ee296e1df93542416ba668f7f6d9d05142f7647ce63310be42873
+  data.tar.gz: 471e4e0dc50ed6b265c9f9dd3ff01a4cb332ac288c8210b161c4bd69ee9cd4d1
 SHA512:
-  metadata.gz: e2d50e340b0d24349c291b4927fa4bc03e3c477862659a4b6a4f81c5a6c10a94e612e70acef98299627fc299f53cad68f15606b9795b610af1e82d559face6d3
-  data.tar.gz: f6495cbea95ddfe0348bd9be92d716d4929329414ef49d6d6649a373f87af4a62346d1fe74631771de24a066b3b7bfcb1335efda76bda8dbd934e5d1eab644de
+  metadata.gz: 00ef0c4360e5f9c41aec4cf7274249c7dae11fcadc06ad54e27b474a2ea95397fb6727a1a8360e8261fe88f3aa765d904739314da8bc5b1730cc8319c5db2042
+  data.tar.gz: 76a6df3e90bfc0ab0ee47030c1c18cb36098b981b72ac5ff855ca5e5abc424a9c5e7452a8e8f1c47507dc846db6ee694de6a49d06fe7bd10bae4529b7c98a9cf

data/README.md

@@ -1,4 +1,4 @@
-# rpi_gpio v0.4.0
+# rpi_gpio v0.5.0
 
 Ruby conversion of [RPi.GPIO Python module](https://pypi.python.org/pypi/RPi.GPIO)
 
@@ -8,6 +8,7 @@ Manipulate your Raspberry Pi's GPIO pins from Ruby!
 
 - Boolean input/output
 - Software-driven PWM (written in C for speed)
+- Event-driven input (blocking and non-blocking)
 
 Up-to-date with RPi.GPIO Python module version 0.7.0, so it works on all Raspberry Pi models!
 
@@ -38,9 +39,20 @@ RPi::GPIO.set_numbering :bcm
 To receive input from a GPIO pin, you must first initialize it as an input pin:
 ```ruby
 RPi::GPIO.setup PIN_NUM, :as => :input
+# or
+RPi::GPIO.setup [PIN1_NUM, PIN2_NUM, ...], :as => :input
 ```
 The pin number will differ based on your selected numbering system and which pin you want to use.
 
+You can use the additional hash argument `:pull` to apply a pull-up or pull-down resistor to the input pin like so:
+```ruby
+RPi::GPIO.setup PIN_NUM, :as => :input, :pull => :down
+# or
+RPi::GPIO.setup PIN_NUM, :as => :input, :pull => :up
+# or (not necessary; :off is the default value)
+RPi::GPIO.setup PIN_NUM, :as => :input, :pull => :off
+```
+
 Now you can use the calls
 ```ruby
 RPi::GPIO.high? PIN_NUM
@@ -48,13 +60,40 @@ RPi::GPIO.low? PIN_NUM
 ```
 to receive either `true` or `false`.
 
-You can use the additional hash argument `:pull` to apply a pull-up or pull-down resistor to the input pin like so:
+If you prefer to use a callback when a pin edge is detected, you can use the `watch` method:
 ```ruby
-RPi::GPIO.setup PIN_NUM, :as => :input, :pull => :down
-# or
-RPi::GPIO.setup PIN_NUM, :as => :input, :pull => :up
-# or (not necessary; :off is the default value)
-RPi::GPIO.setup PIN_NUM, :as => :input, :pull => :off
+RPi::GPIO.watch PIN_NUM, :on => :rising do |pin, value| # :on supports :rising, :falling, and :both
+  ...
+end
+```
+
+`watch` also supports the optional `bounce_time` parameter found in the Python module to prevent duplicate events from firing:
+```ruby
+RPi::GPIO.watch PIN_NUM, :on => :falling, :bounce_time => 200 do |pin, value|
+  ...
+end
+```
+
+To stop watching a pin, use `stop_watching`:
+```ruby
+RPi::GPIO.stop_watching PIN_NUM
+```
+
+If you want to block execution until a pin edge is detected, there's `wait_for_edge`:
+```ruby
+puts 'Waiting to start...'
+RPi::GPIO.wait_for_edge PIN_NUM, :rising # :rising, :falling, and :both are also supported here
+puts 'Here we go!'
+```
+
+`wait_for_edge` accepts optional `bounce_time` and `timeout` arguments too:
+```ruby
+puts 'Waiting to start...'
+value = RPi::GPIO.wait_for_edge PIN_NUM, :falling, :bounce_time => 200, :timeout => 5000
+if value.nil? # nil is returned if the timeout is reached
+  print 'You took too long. '
+end
+puts 'Here we go!'
 ```
 
 #### Output
@@ -62,6 +101,8 @@ RPi::GPIO.setup PIN_NUM, :as => :input, :pull => :off
 To send output to a GPIO pin, you must first initialize it as an output pin:
 ```ruby
 RPi::GPIO.setup PIN_NUM, :as => :output
+# or
+RPi::GPIO.setup [PIN1_NUM, PIN2_NUM, ...], :as => :output
 ```
 Now you can use the calls
 ```ruby

data/Rakefile

@@ -1,3 +1,5 @@
 require 'rake/extensiontask'
 
-Rake::ExtensionTask.new('rpi_gpio')
+Rake::ExtensionTask.new('rpi_gpio') do |ext|
+  ext.lib_dir = 'lib/rpi_gpio'
+end

data/ext/rpi_gpio/extconf.rb

@@ -1,5 +1,3 @@
 require 'mkmf'
 
-extension_name = 'rpi_gpio'
-dir_config(extension_name)
-create_makefile(extension_name)
+create_makefile 'rpi_gpio/rpi_gpio'

data/lib/rpi_gpio.rb

@@ -0,0 +1,329 @@
+require 'rpi_gpio/rpi_gpio'
+require 'epoll'
+
+module RPi
+  module GPIO
+    def self.watch(channel, on:, bounce_time: nil, &block) 
+      gpio = get_gpio_number(channel)
+      ensure_gpio_input(gpio)
+      validate_edge(on)
+      if bounce_time && bounce_time <= 0
+        raise ArgumentError, "`bounce_time` must be greater than 0; given #{bounce_time}"
+      end
+      add_edge_detect(gpio, on, bounce_time)
+      add_callback(gpio, &block)
+    end
+
+    def self.stop_watching(channel)
+      gpio = get_gpio_number(channel)
+      ensure_gpio_input(gpio)
+      remove_edge_detect(gpio)
+      remove_callbacks(gpio)
+    end
+
+    def self.wait_for_edge(channel, edge, bounce_time: nil, timeout: -1)
+      gpio = get_gpio_number(channel)
+      if callback_exists(gpio)
+        raise RuntimeError, "conflicting edge detection already enabled for GPIO #{gpio}"
+      end
+
+      ensure_gpio_input(gpio)
+      validate_edge(edge)
+      was_gpio_new = false
+      current_edge = get_event_edge(gpio)
+      if current_edge == edge
+        g = get_gpio(gpio)
+        if g.bounce_time && g.bounce_time != bounce_time
+          raise RuntimeError, "conflicting edge detection already enabled for GPIO #{gpio}"
+        end
+      elsif current_edge.nil?
+        was_gpio_new = true
+        g = new_gpio(gpio)
+        set_edge(gpio, edge)
+        g.edge = edge
+        g.bounce_time = bounce_time
+      else
+        g = get_gpio(gpio)
+        set_edge(gpio, edge)
+        g.edge = edge
+        g.bounce_time = bounce_time
+        g.initial_wait = 1
+      end
+
+      if @@epoll_blocking.nil?
+        @@epoll_blocking = Epoll.create
+      end
+      @@epoll_blocking.add(g.value_file, Epoll::PRI)
+
+      initial_edge = true
+      the_value = nil
+      timed_out = false
+      begin
+        while the_value.nil? && !timed_out do
+          events = @@epoll_blocking.wait(timeout)
+          if events.empty?
+            timed_out = true
+          end
+          events.each do |event|
+            if event.events & Epoll::PRI != 0
+              event.data.seek(0, IO::SEEK_SET)
+              value = event.data.read.chomp.to_i
+              if event.data == g.value_file
+                if initial_edge # ignore first epoll trigger
+                  initial_edge = false
+                else
+                  now = Time.now.to_f
+                  if g.bounce_time.nil? || g.last_call == 0 || g.last_call > now ||
+                     (now - g.last_call) * 1000 > g.bounce_time then
+                    g.last_call = now
+                    the_value = value
+                  end
+                end
+              end
+            end
+          end
+        end
+
+        if the_value
+          return the_value
+        end
+      ensure
+        @@epoll_blocking.del(g.value_file)
+        if was_gpio_new
+          delete_gpio(gpio)
+        end
+      end
+    end
+
+    private
+      @@callbacks = []
+      @@gpios = []
+      @@epoll = nil
+      @@epoll_thread = nil
+      @@epoll_blocking = nil
+  
+      def self.export(gpio)
+        unless File.exist?("/sys/class/gpio/gpio#{gpio}")
+          File.open("/sys/class/gpio/export", 'w') do |file|
+            file.write(gpio.to_s)
+          end
+        end
+      end
+
+      def self.unexport(gpio)
+        File.open("/sys/class/gpio/unexport", 'w') do |file|
+          file.write(gpio.to_s)
+        end
+      end
+
+      def self.set_direction(gpio, direction)
+        validate_direction(direction)
+        tries = 0
+        begin
+          File.open("/sys/class/gpio/gpio#{gpio}/direction", 'w') do |file|
+            file.write(direction.to_s)
+          end
+        rescue
+          raise if tries > 5
+          sleep 0.1
+          tries += 1
+          retry
+        end
+      end
+
+      def self.set_edge(gpio, edge)
+        validate_edge(edge)
+        tries = 0
+        begin
+          File.open("/sys/class/gpio/gpio#{gpio}/edge", 'w') do |file|
+            file.write(edge.to_s)
+          end
+        rescue
+          raise if tries > 5
+          sleep 0.1
+          tries += 1
+          retry
+        end
+      end
+
+      def self.open_value_file(gpio)
+        File.open("/sys/class/gpio/gpio#{gpio}/value", 'r')
+      end
+
+      def self.new_gpio(gpio)
+        g = GPIO.new
+        g.gpio = gpio
+        export(gpio)
+        g.exported = true
+        set_direction(gpio, :in)
+        begin
+          g.value_file = open_value_file(gpio)
+        rescue
+          unexport(gpio)
+          raise
+        end
+        g.initial_thread = true
+        g.initial_wait = true
+        g.bounce_time = nil
+        g.last_call = 0
+        g.thread_added = false
+        @@gpios << g
+        g
+      end
+
+      def self.delete_gpio(gpio)
+        @@gpios.delete_if { |g| g.gpio == gpio }
+      end
+
+      def self.get_gpio(gpio)
+        @@gpios.find { |g| g.gpio == gpio }
+      end
+
+      def self.get_gpio_by_value_file(value_file)
+        @@gpios.find { |g| g.value_file == value_file }
+      end
+
+      def self.get_event_edge(gpio) # gpio_event_added in python library
+        g = @@gpios.find { |g| g.gpio == gpio }
+        if g
+          return g.edge
+        end
+      end
+
+      def self.add_edge_detect(gpio, edge, bounce_time = nil)
+        current_edge = get_event_edge(gpio)
+        if current_edge.nil?
+          g = new_gpio(gpio)
+          set_edge(gpio, edge)
+          g.edge = edge
+          g.bounce_time = bounce_time
+        elsif current_edge == edge
+          g = get_gpio(gpio)
+          if (bounce_time && g.bounce_time != bounce_time) || g.thread_added
+            raise RuntimeError, "conflicting edge detection already enabled for GPIO #{gpio}"
+          end
+        else
+          raise RuntimeError, "conflicting edge detection already enabled for GPIO #{gpio}"
+        end
+
+        if @@epoll.nil?
+          @@epoll = Epoll.create
+        end
+
+        begin
+          @@epoll.add(g.value_file, Epoll::PRI)
+        rescue
+          remove_edge_detect(gpio)
+          raise
+        end
+
+        g.thread_added = true
+        if @@epoll_thread.nil? || !@@epoll_thread.alive?
+          @@epoll_thread = Thread.new { poll_thread }
+        end
+      end
+
+      def self.remove_edge_detect(gpio)
+        g = get_gpio(gpio)
+        if g and @@epoll
+          @@epoll.del(g.value_file)
+          set_edge(gpio, :none)
+          g.edge = :none
+          g.value_file.close
+          unexport(gpio)
+          delete_gpio(gpio)
+        end
+      end
+
+      def self.poll_thread
+        loop do
+          begin
+            events = @@epoll.wait
+          rescue IOError # empty interest list
+            break
+          end
+          events.each do |event|
+            if event.events & Epoll::PRI != 0
+              event.data.seek(0, IO::SEEK_SET)
+              g = get_gpio_by_value_file(event.data)
+              value = event.data.read.chomp.to_i
+              if g.initial_thread # ignore first epoll trigger
+                g.initial_thread = false
+              else
+                now = Time.now.to_f
+                if g.bounce_time.nil? || g.last_call == 0 || g.last_call > now ||
+                   (now - g.last_call) * 1000 > g.bounce_time then
+                  g.last_call = now
+                  run_callbacks(g.gpio, value)
+                end
+              end
+            end
+          end
+        end
+      end
+
+      def self.event_cleanup(gpio)
+        @@gpios.map { |g| g.gpio }.each do |gpio_|
+          if gpio.nil? || gpio_ == gpio
+            remove_edge_detect(gpio_)
+          end
+        end
+
+        if @@gpios.empty? && @@epoll_thread
+          @@epoll_thread.terminate
+        end
+      end
+
+      def self.event_cleanup_all
+        event_cleanup(nil)
+      end
+
+      def self.add_callback(gpio, &block)
+        @@callbacks << Callback.new(gpio, &block)
+      end
+
+      def self.remove_callbacks(gpio)
+        @@callbacks.delete_if { |g| g.gpio == gpio }
+      end
+
+      def self.callback_exists(gpio)
+        @@gpios.find { |g| g.gpio == gpio } != nil
+      end
+
+      def self.run_callbacks(gpio, value)
+        @@callbacks.each do |callback|
+          if callback.gpio == gpio
+            callback.block.call(channel_from_gpio(gpio), value)
+          end
+        end
+      end
+
+      def self.validate_direction(direction)
+        direction = direction.to_s
+        if direction != 'in' && direction != 'out'
+          raise ArgumentError, "`direction` must be 'in' or 'out'; given '#{direction}'"
+        end
+      end
+
+      def self.validate_edge(edge)
+        edge = edge.to_s
+        if edge != 'rising' && edge != 'falling' && edge != 'both' && edge != 'none'
+          raise ArgumentError, "`edge` must be 'rising', 'falling', 'both', or 'none'; given '#{edge}'"
+        end
+      end
+
+      class GPIO
+        attr_accessor :gpio, :exported, :value_file, :initial_thread, :initial_wait, :bounce_time, :last_call,
+          :thread_added, :edge
+      end
+
+      class Callback
+        attr_accessor :gpio, :block
+
+        def initialize(gpio, &block)
+          @gpio = gpio
+          @block = block
+        end
+      end
+  end
+end

metadata

@@ -1,43 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: rpi_gpio
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Nick Lowery
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-21 00:00:00.000000000 Z
+date: 2020-08-09 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: epoll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: rake-compiler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.6'
 description: Ruby conversion of RPi.GPIO Python module
 email: nick.a.lowery@gmail.com
 executables: []
@@ -46,27 +60,12 @@ extensions:
 extra_rdoc_files: []
 files:
 - Gemfile
-- Gemfile.lock
 - LICENSE
 - README.md
 - Rakefile
-- ext/rpi_gpio/c_gpio.c
-- ext/rpi_gpio/c_gpio.h
-- ext/rpi_gpio/common.c
-- ext/rpi_gpio/common.h
-- ext/rpi_gpio/cpuinfo.c
-- ext/rpi_gpio/cpuinfo.h
-- ext/rpi_gpio/event_gpio.c
-- ext/rpi_gpio/event_gpio.h
 - ext/rpi_gpio/extconf.rb
-- ext/rpi_gpio/rb_gpio.c
-- ext/rpi_gpio/rb_gpio.h
-- ext/rpi_gpio/rb_pwm.c
-- ext/rpi_gpio/rb_pwm.h
-- ext/rpi_gpio/rpi_gpio.c
-- ext/rpi_gpio/rpi_gpio.h
-- ext/rpi_gpio/soft_pwm.c
-- ext/rpi_gpio/soft_pwm.h
+- lib/rpi_gpio.rb
+- lib/rpi_gpio/rpi_gpio.so
 homepage: https://github.com/ClockVapor/rpi_gpio
 licenses:
 - MIT