ya_gpio 0.1.0

data/README.md

@@ -0,0 +1,86 @@
+# Yet Another GPIO gem for Raspberry Pi
+
+## But why ?
+
+Because making a new wheel is always fun !
+
+There is already plenty of GPIO libraries for Raspberry Pi :
+
+ - some using plain C : [c_GPIO](https://github.com/hujiko/c_GPIO)
+ - some using the BCM C libs : [rpi_gpio](https://github.com/ClockVapor/rpi_gpio)
+ - some small ones using Sysfs : [ruby-gpio](https://github.com/sausheong/ruby-gpio), [gpio](https://github.com/klappy/gpio), [raspi-gpio-rb](https://github.com/exybore/raspi-gpio-rb)
+ - some big ones based on EventMachine : [pi_piper](https://github.com/jwhitehorn/pi_piper), [em-gpio](https://github.com/railsbob/em-gpio)
+
+But none of them support interruptions to trigger events. I mean proper interruption without pooling within an infinite loop (and sometimes a sleep).
+For example, _rpi-gpio_ gem is very good but the `wait_for_edge()` method is not available (yet).
+
+This implementation is based on the Sysfs interface and so do not support integrated pull-down an pull-up resistors.
+See [official kernel documentation](https://www.kernel.org/doc/Documentation/gpio/sysfs.txt) for more details.
+
+NOTE: The pin number specified in the initializer uses *BCM numbering*.
+
+## Permissions
+
+Please note that lib require read/write access to the GPIO Sysfs subdirectory `/sys/class/gpio/`. If your script is not running as root, add your user to the `gpio` group.
+On most Raspberry Pi compatible distributions, an UDEV event will automatically set proper permissions once the port is exported.
+
+## Using interruptions
+
+The implementation of the interrupt hander is based on Sysfs and uses the select(2) syscall, according to the offical linux kernel documentation. You can find an example in C here : [Attentes passives sur GPIO](https://www.blaess.fr/christophe/2013/04/15/attentes-passives-sur-gpio/).
+
+Another implementation using poll(2) in ruby : [Evented GPIO on Raspberry PI with Ruby](https://tenderlovemaking.com/2017/01/17/evented-gpio-on-raspberry-pi-with-ruby.html)
+
+### Example
+
+```ruby
+require 'ya_gpio'
+
+led     = YaGPIO.new(23, YaGPIO::OUTPUT)
+button1 = YaGPIO.new(22, YaGPIO::INPUT)
+button2 = YaGPIO.new(25, YaGPIO::INPUT)
+
+# Turn the led on when button 1 is pressed and 
+# off when released
+button1.set_interrupt(YaGPIO::EDGE_BOTH) do |high|
+  if high
+    led.high
+  else
+    led.low
+  end
+end
+
+# Stop the wait() loop when button 2 is pressed
+button2.set_interrupt(YaGPIO::EDGE_RISING) do |high|
+  YaGPIO::resume
+end
+
+puts "ready"
+YaGPIO::wait([button1, button2])
+puts "wait() loop terminated"
+
+```
+
+If your application needs to listen to other file descriptors, you can override the `wait()` method to include those FDs in the `select()` call. See `lib/ya_gpio.rb` source file for more information.
+
+
+## Testing
+
+This module is fully tested on Raspberry Pi and has testing with rspec. To run them :
+
+```
+bundle install
+bundle exec rake spec
+```
+
+## API documentation
+
+The API documentation is available in the Yard format. To generate it under the `doc` directory, run :
+
+```
+bundle exec rake yard
+```
+
+## License
+
+Copyleft 2019 - Nicolas AGIUS - GNU GPLv3
+

data/Rakefile

@@ -0,0 +1,11 @@
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+require 'yard'
+
+YARD::Rake::YardocTask.new do |t|
+ t.files   = ['lib/*.rb']
+ t.stats_options = ['--list-undoc']
+end
+
+RSpec::Core::RakeTask.new(:spec)
+

data/lib/ya_gpio.rb

@@ -0,0 +1,242 @@
+# YaGPIO - Yet Another GPIO module for Raspberry Pi
+# Copyleft 2019 - Nicolas AGIUS <nicolas.agius@lps-it.fr>
+
+###########################################################################
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+###########################################################################
+
+# YaGPIO is a simple module to control GPIO port on a Raspberry Pi.
+# It's based on the Sysfs interface.
+#
+# @example Open port 22 as output and set it to high
+#   pin = YaGPIO.new(22, YaGPIO::OUTPUT)
+#   pin.high
+#
+# @example Open port 23 as input and read its state
+#   pin = YaGPIO.new(23, YaGPIO::INPUT)
+#   pp pin.low?
+#
+class YaGPIO
+	# File descriptor to the sysfs entry of the pin. It is not recommended to access the file
+	# directly. Use high() lov() helpers instead.
+	attr_reader :file
+
+	# Direction input
+	INPUT = 'in'
+
+	# Direction output with default low
+	OUTPUT = 'out'
+
+	# Direction output with default high
+	OUTPUT_HIGH = 'high'
+
+	# Interruption on rising edge
+	EDGE_RISING = 'rising'
+
+	# Interruption on falling edge
+	EDGE_FALLING = 'falling'
+
+	# Interruption on rising and falling edge
+	EDGE_BOTH = 'both'
+
+	# Disable interruption
+	EDGE_NONE = 'none'
+
+
+	# Create and configure a new GPIO pin. The pin will be _exported_ via the sysfs interface.
+	# The pin will be _unexported_ and released for other use upon garbage collection.
+	#
+	# @param pin [Integer] Pin number to configure, using the BCM numbering
+	# @param direction [String] The direction if the port. Must be one of INPUT, OUTPUT or OUTPUT_HIGH
+	def initialize(pin, direction)
+		raise 'direction must be one of INPUT, OUTPUT, OUTPUT_HIGH' unless [INPUT, OUTPUT, OUTPUT_HIGH].include?(direction)
+
+		@pin = pin
+		@callback = nil
+		@direction = direction
+
+		export
+		open
+
+		ObjectSpace.define_finalizer(self, self.class.finalize(@pin))
+	end
+
+
+	# Return true if the pin is high
+	#
+	# @return [Boolean] State of the pin
+	def high?
+		read() != 0
+	end
+
+	# Return true if the pin is low
+	#
+	# @return [Boolean] State of the pin
+	def low?
+		read() == 0
+	end
+
+	# Set the pin to high
+	def high
+		write(1)
+	end
+
+	# Set the pin to low
+	def low
+		write(0)
+	end
+
+	# Invert all values and settings. After set to true, HIGH means LOW and LOW means HIGH.
+	# Be prepared to be confused if you're using this feature.
+	#
+	# @param active [Boolean] Feature state
+	def active_low=(active)
+		File.write("/sys/class/gpio/gpio#{@pin}/active_low", active ? '1' : '0')
+	end
+
+	# Return true is active_low feature is enabled
+	#
+	# @return [Boolean] Feature state
+	def active_low?
+		File.read("/sys/class/gpio/gpio#{@pin}/active_low") != '0'
+	end
+
+	# Define a callback to execute when an interruption will be triggered.
+	#
+	# @param edge [String] Edge to trigger interrution. Can be EDGE_RISING, EDGE_FALLING or EDGE_BOTH
+	# @param block [Block] Block to execute as callback
+	def set_interrupt(edge, &block)
+		raise 'interrupt can only be set on input pin' unless @direction == INPUT
+
+		set_edge(edge)	
+		@callback = block
+	end
+
+	# Disable a previously set interruption
+	def clear_interrupt()
+		set_edge(EDGE_NONE)	
+		@callback = nil
+	end
+
+	# Execute the interruption's callback.
+	#
+	# @param active [Boolean] Should be true if the pin is high
+	def trigger(active)
+		if @callback.nil?
+		    puts "No Callback defined for #{@pin}"
+		else
+		    @callback.call(active)
+		end
+	end
+
+	# Release the pin.
+	# The object cannot be used after this method is called as the pin will not be configured anymore.
+	def unexport()
+		@file.close
+		File.write('/sys/class/gpio/unexport', @pin.to_s)
+	end
+
+	alias :close :unexport
+
+	# Wait for an interruption to be trigerred and run the associated callback.
+	# This method will block until the program exits or YaGPIO::resume() is called from a callback.
+	# 
+	# Note that software debounce has not been implemented.
+	# You can use a 1µF capacitor in your setup to fix bounce issues.
+	#
+	# @param gpios [Array] Array of YaGPIO to monitor
+	def self.wait(gpios)
+		# Initial read to clear interrupt triggered during setup 
+		gpios.map{|g| g.high?}
+
+		@@wait = true
+		while @@wait do
+			rs, ws, es = IO.select(nil, nil, gpios.map{|g| g.file})
+
+			es.each do |f|
+				gpio = gpios.select{|g| g.file == f}.first
+				gpio.trigger(gpio.high?)
+			end
+		end
+	end
+
+	# Stop the wait loop, must be run from a callback triggered by YaGPIO::wait()
+	def self.resume
+		@@wait = false
+	end
+
+	private
+
+	MAX_RETRY = 3	# Number of retries when openning the sysfs file
+	@@wait = true	# Flag to enable the wait infinite loop
+
+	def export()
+		begin
+			File.write('/sys/class/gpio/export', @pin.to_s)
+		rescue Errno::EBUSY
+			puts "WARNING: GPIO #{@pin} is already exported, may be in use."
+		end
+	end
+
+	def open
+		begin
+			retries ||= 0
+			case @direction
+				when INPUT
+					@file=File.open("/sys/class/gpio/gpio#{@pin}/value", 'r')
+				else
+					@file=File.open("/sys/class/gpio/gpio#{@pin}/value", 'r+')
+			end
+
+			@file.sync=true	# Auto flush
+			File.write("/sys/class/gpio/gpio#{@pin}/direction", @direction)
+		rescue Errno::EACCES
+			if (retries += 1) <= MAX_RETRY
+				puts "Permission on sysfs not ready yet, retrying (#{retries}/#{MAX_RETRY})..."
+				sleep 0.1
+				retry
+			end
+
+			raise
+		end
+	end
+
+	def set_edge(edge)
+		raise 'edge must be one of EDGE_RISING, EDGE_FALLING, EDGE_BOTH, EDGE_NONE' unless [EDGE_RISING, EDGE_FALLING, EDGE_BOTH, EDGE_NONE].include?(edge)
+
+		File.write("/sys/class/gpio/gpio#{@pin}/edge", edge)
+	end
+
+	def read()
+		@file.seek(0, IO::SEEK_SET)
+		@file.read().to_i
+	end
+
+	def write(value)
+		@file.seek(0, IO::SEEK_SET)
+		@file.write(value)
+	end
+
+	# Unexport the port when the program exits
+	def self.finalize(pin)
+		proc do
+			File.write('/sys/class/gpio/unexport', pin)
+		end
+	end
+
+end
+
+# vim: ts=4:sw=4:ai

data/lib/ya_gpio/version.rb

@@ -0,0 +1,3 @@
+class YaGPIO
+	VERSION = "0.1.0"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,108 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The generated `.rspec` file contains `--require spec_helper` which will cause
+# this file to always be loaded, without a need to explicitly require it in any
+# files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, consider making
+# a separate helper file that requires the additional dependencies and performs
+# the additional setup, and require it from the spec files that actually need
+# it.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+
+require 'bundler/setup'
+Bundler.setup
+
+require 'ya_gpio'
+require 'pp' # Conflict with fakefs, need to be required before fakefs
+require 'fakefs/spec_helpers'
+
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    #     be_bigger_than(2).and_smaller_than(4).description
+    #     # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #     # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+  # This option will default to `:apply_to_host_groups` in RSpec 4 (and will
+  # have no way to turn it off -- the option exists only for backwards
+  # compatibility in RSpec 3). It causes shared context metadata to be
+  # inherited by the metadata hash of host groups and examples, rather than
+  # triggering implicit auto-inclusion in groups with matching metadata.
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+
+# The settings below are suggested to provide a good initial experience
+# with RSpec, but feel free to customize to your heart's content.
+=begin
+  # This allows you to limit a spec run to individual examples or groups
+  # you care about by tagging them with `:focus` metadata. When nothing
+  # is tagged with `:focus`, all examples get run. RSpec also provides
+  # aliases for `it`, `describe`, and `context` that include `:focus`
+  # metadata: `fit`, `fdescribe` and `fcontext`, respectively.
+  config.filter_run_when_matching :focus
+
+  # Allows RSpec to persist some state between runs in order to support
+  # the `--only-failures` and `--next-failure` CLI options. We recommend
+  # you configure your source control system to ignore this file.
+  config.example_status_persistence_file_path = "spec/examples.txt"
+
+  # Limits the available syntax to the non-monkey patched syntax that is
+  # recommended. For more details, see:
+  #   - http://rspec.info/blog/2012/06/rspecs-new-expectation-syntax/
+  #   - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   - http://rspec.info/blog/2014/05/notable-changes-in-rspec-3/#zero-monkey-patching-mode
+  config.disable_monkey_patching!
+
+  # This setting enables warnings. It's recommended, but in some cases may
+  # be too noisy due to issues in dependencies.
+  config.warnings = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = "doc"
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+=end
+end