rpi_gpio 0.3.0 → 0.5.0

checksums.yaml

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

data/LICENSE

@@ -1,7 +1,7 @@
 The MIT License (MIT)
 
-Copyright (c) 2014-2015 Nick Lowery
-Copyright (c) 2013-2014 Ben Croston
+Copyright (c) 2014-2020 Nick Lowery
+Copyright (c) 2012-2014 Ben Croston
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -20,4 +20,3 @@ 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

@@ -1,4 +1,4 @@
-# rpi_gpio v0.3.0
+# rpi_gpio v0.5.0
 
 Ruby conversion of [RPi.GPIO Python module](https://pypi.python.org/pypi/RPi.GPIO)
 
@@ -8,8 +8,9 @@ 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.6.2, so it works on all Raspberry Pi models!
+Up-to-date with RPi.GPIO Python module version 0.7.0, so it works on all Raspberry Pi models!
 
 ## Sample Usage
 
@@ -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
@@ -70,6 +111,13 @@ RPi::GPIO.set_low PIN_NUM
 ```
 to set the pin either high or low.
 
+You can use the additional hash argument `:initialize` to set the pin's initial state like so:
+```ruby
+RPi::GPIO.setup PIN_NUM, :as => :output, :initialize => :high
+# or
+RPi::GPIO.setup PIN_NUM, :as => :output, :initialize => :low
+```
+
 #### PWM (pulse-width modulation)
 
 Pulse-width modulation is a useful tool for controlling things like LED brightness or motor speed. To utilize PWM, first create a PWM object for an [output pin](#output).
@@ -132,7 +180,7 @@ to clean up all pins and to also reset the selected numbering mode.
 
 Original Python code by Ben Croston modified for Ruby by Nick Lowery
 
-Copyright (c) 2014-2015 [Nick Lowery](https://github.com/ClockVapor)
+Copyright (c) 2014-2020 [Nick Lowery](https://github.com/ClockVapor)
 
 View LICENSE for full license.
 

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