neotrellis 0.1.0

data/README.md

@@ -0,0 +1,113 @@
+# Neotrellis
+
+Neotrellis is a ruby driver for Adafruit's NeoTrellis keypad. This device uses an I2C bus to control both the keypad and the RGB led array.
+
+[Neotrelliis](datasheets/neotrellis.jpg)
+
+See https://www.adafruit.com/product/3954 for more details on this device.
+
+This ruby gem is mainly compose of two classes :
+ - Neotrellis::Neopixels to control the leds behind each keys.
+ - Neotrellis::Keypad to execute code when a key is pressed or released on the keypad
+
+The Keypad class provide two modes to react to key events: using pooling with a loop or using interruption handler. The pooling mode require only the I2C communication to be set up. For the interruption mode to work, the pin INT on the keypad need to be connected to a GPIO input supporting hardware interruption on your computer. A common use case are the pins 15 or 16 of the Raspberry Pi GPIO header. See Raspberry Pi documentation for more details.
+
+The support of hardware interruption is done by the [YaGPIO](https://github.com/nagius/ya_gpio) gem based on Sysfs interface. It has been designed for Raspberry Pi but should work with any GPIO systems supported by the Sysfs kernel driver.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'neotrellis'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install neotrellis
+
+## Usage
+
+We will suppose here that you are using a Rasberry Pi B+ to control the Neotrellis device. Adapt the I2C device name and pin numbers for other boards.
+
+First, connect the pins SDA and SLC of the keypad to GPIO pins 3 and 5. The device will appear on the second I2C bus of the Raspberry Pi `/dev/i2c-1`. Te I2C port need to be enabled in the linux kenel to operate. Refer to Raspberry Pi documentation to do so.
+
+If you want to use the interruption mode also connect the INT pin to the GPIO pin 15 (GPIO22).
+
+### Example 1: Print a message when key #3 is pressed using polling
+
+```ruby
+seesaw = Neotrellis::Seesaw.new(device: "/dev/i2c-1", addr: 0x2E)
+keypad = Neotrellis::Keypad.new(seesaw)
+keypad.set_event(2, event: Neotrellis::Keypad::KEY_PRESSED) { |event|
+    puts "Key #{event.key} pressed"
+}
+loop do 
+    sleep(1)
+    puts "Processing pending events"
+    keypad.sync
+end
+```
+
+### Example 2:  Print a message when key #3 is released using interruption
+
+```ruby
+seesaw = Neotrellis::Seesaw.new(device: "/dev/i2c-1", addr: 0x2E)
+keypad = Neotrellis::Keypad.new(seesaw)
+keypad.set_event(2, event: Neotrellis::Keypad::KEY_RELEASED) { |event|
+    puts "Key #{event.key}"
+    puts event.edge == Neotrellis::Keypad::KEY_PRESSED ? "pressed" : "released"
+}
+keypad.enable_interrupt(22)
+keypad.wait_for_event
+```
+
+### Example 3: Turn on led #2 in red for 2 seconds
+
+```ruby
+seesaw = Neotrellis::Seesaw.new(device: "/dev/i2c-1", addr: 0x2E)
+pixels = Neotrellis::Neopixel.new(seesaw)
+pixels.set(1, Neotrellis::Neopixel::RED)
+sleep 2
+pixels.set(1, Neotrellis::Neopixel::OFF)
+```
+
+### Example 4: Turn on the pressed key with a random color
+
+```ruby
+seesaw = Neotrellis::Seesaw.new(device: "/dev/i2c-1", addr: 0x2E)
+keypad = Neotrellis::Keypad.new(seesaw, interrupt_pin: 22)
+pixels = Neotrellis::Neopixel.new(seesaw)
+
+Neotrellis::Neopixel::DEFAULT_PIXEL_NUMBER.times do |key|
+  keypad.set_event(key) do |event|
+    if event.edge == Neotrellis::Keypad::KEY_PRESSED
+      pixels.set(event.key, Neotrellis::Neopixel::Color.new(rand(255), rand(255), rand(255)))
+    else
+      pixels.set(event.key, Neotrellis::Neopixel::OFF)
+    end
+  end
+end
+keypad.wait_for_event
+```
+
+### API documentation
+
+The API documentation is available in the Yard format. To generate it under the `doc` directory, run :
+
+```
+bundle exec rake yard
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nagius/neotrellis.
+
+## License
+
+Copyleft 2019 - Nicolas AGIUS - GNU GPLv3
+

data/Rakefile

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

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "neotrellis"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/neotrellis.rb

@@ -0,0 +1,3 @@
+require 'neotrellis/seesaw'
+require 'neotrellis/neopixel'
+require 'neotrellis/keypad'

data/lib/neotrellis/keypad.rb

@@ -0,0 +1,230 @@
+# Neotrellis - Driver for Adafruit's NeoTrellis keypad
+# 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/>.
+#
+###########################################################################
+
+require 'ya_gpio'
+
+module Neotrellis
+	# Driver for the Neotrellis 4x4 keypad.
+	#
+	# @example Print a message when key #3 is pressed
+	#   seesaw = Neotrellis::Seesaw.new(device: "/dev/i2c-1", addr: 0x2E)
+	#   keypad = Neotrellis::Keypad.new(seesaw)
+	#   keypad.set_event(2, event: Neotrellis::Keypad::KEY_PRESSED) { |event|
+	#   	puts "Key #{event.key} pressed"
+	#	}
+	#   loop do
+	#   	sleep(1)
+	#   	puts "Processing pending events"
+	#   	keypad.sync
+	#   end
+	#
+	# @example Print a message when key #3 is released using interruption on GPIO pin 22
+	#   seesaw = Neotrellis::Seesaw.new(device: "/dev/i2c-1", addr: 0x2E)
+	#   keypad = Neotrellis::Keypad.new(seesaw)
+	#   keypad.set_event(2, event: Neotrellis::Keypad::KEY_RELEASED) { |event|
+	#   	puts "Key #{event.key}"
+	#		puts event.edge == Neotrellis::Keypad::KEY_PRESSED ? "pressed" : "released"
+	#	}
+	#   keypad.enable_interrupt(22)
+	#   keypad.wait_for_event
+	#
+	# @example Stop waiting for events when key #4 is pressed
+	#   seesaw = Neotrellis::Seesaw.new(device: "/dev/i2c-1", addr: 0x2E)
+	#   keypad = Neotrellis::Keypad.new(seesaw, interrupt_pin: 22)
+	#   keypad.set_event(3, event: Neotrellis::Keypad::KEY_PRESSED) {
+	#   	keypad.resume
+	#	}
+	#   keypad.wait_for_event
+	#   puts "loop ended"
+	class Keypad
+
+		private
+			# Internal SeeSaw registers
+			KEYPAD_BASE = 0x10
+
+			KEYPAD_STATUS = 0x00
+			KEYPAD_EVENT = 0x01
+			KEYPAD_INTENSET = 0x02
+			KEYPAD_INTENCLR = 0x03
+			KEYPAD_COUNT = 0x04
+			KEYPAD_FIFO = 0x10
+
+		public
+
+		KEY_HIGH = 0     # Key is pressed
+		KEY_LOW = 1      # Key is released
+		KEY_RELEASED = 2 # Key is falling edge
+		KEY_PRESSED = 3  # Key is rising edge
+		KEY_BOTH = 4     # Key is rising edge or falling edge
+
+		# Initialize the keypad driven by a Seesaw chip.
+		#
+		# @param seesaw [Neotrellis::SeeSaw] Seesaw driver
+		# @param interrupt_pin [Integer] GPIO pin used by the interruption handler. If false, the interruption mode will be disabled.
+		# @param debug [Boolean] Enable debug ouput on stdout
+		def initialize(seesaw, interrupt_pin: false, debug: false)
+			@seesaw = seesaw
+			@debug = debug
+			@callbacks = {}
+
+			enable_interrupt(interrupt_pin) if interrupt_pin
+		end
+
+		# Get the number of events (key pressed or released) waiting to be processed in the Seesaw buffer.
+		#
+		# @return [Integer] Number of events
+		def count_events
+			@seesaw.read_byte(KEYPAD_BASE, KEYPAD_COUNT)
+		end
+
+		# Register a callback to execute when a key's event is processed.
+		#
+		# @param key [Integer] ID of the key. Must be between 0 and 15 (for the 4x4 keypad)
+		# @param event [Neotrellis::Keypad::KEY_PRESSED|Neotrellis::Keypad::KEY_RELEASED|Neotrellis::Keypad::KEY_BOTH] Type of event to react to.
+		# @param enabled [Boolean] If false, the callback will be disabled.
+		# @param block [Block] Code to execute when the event is trigerred. A Neotrellis::Keypad::KeyEvent will be passed as argument to the block.
+		def set_event(key, event: KEY_BOTH, enabled: true, &block)
+			if event == KEY_BOTH
+				set_event(key, event: KEY_PRESSED, enabled: enabled, &block)
+				set_event(key, event: KEY_RELEASED, enabled: enabled, &block)
+			else
+				raise "event must be one of KEY_PRESSED, KEY_RELEASED" unless [KEY_PRESSED, KEY_RELEASED].include? event
+				raise "enabled must be a boolean" unless [true, false].include? enabled
+
+				# Convert data to SeeSaw's binary registers
+				key_b = (key/4)*8 + (key%4)
+				edge_b = (1 << (event+1)) | ( enabled ? 1 : 0 )
+
+				@seesaw.write(KEYPAD_BASE, KEYPAD_EVENT, key_b, edge_b)
+				@callbacks[KeyEvent.new(key, event)] = block
+			end
+		end
+
+		# Trigger the callback for each event waiting to be processed.
+		# This method will be automatically called when the interruption mode is enabled.
+		def sync
+			count = count_events()
+			if count >0
+				read_events(count).each do |event|
+					trigger_event(event)
+				end
+			end
+		end
+
+		# Enable the interruption mode.
+		# In this mode, the `sync()`  method will be automatically called when an interruption is triggered by the Seesaw device.
+		# The INT ligne of the keypad need to be connected to this GPIO pin.
+		#
+		# @param pin [Integer] GPIO pin to configure for interruption on. Pin number is in the BCM numbering, as reported by Sysfs.
+		def enable_interrupt(pin)
+			raise "pin must be an integer" unless pin.is_a? Integer
+
+			@interrupt_enabled=true
+			@seesaw.write(KEYPAD_BASE, KEYPAD_INTENSET, 0x01)
+
+			@gpio = YaGPIO.new(pin, YaGPIO::INPUT)
+			@gpio.set_interrupt(YaGPIO::EDGE_FALLING) do 
+				puts "DEBUG Interrupt received." if @debug
+				sync
+			end
+		end
+
+		# Tell if the interruption mode is enabled.
+		#
+		# @return [Boolean] True if interruption mode is enabled.
+		def interrupt?
+			@interrupt_enabled
+		end
+
+		# Disable interruption mode and release the GPIO pin.
+		def disable_interrupt
+			@interrupt_enabled=false
+			@seesaw.write(KEYPAD_BASE, KEYPAD_INTENCLR, 0x01)
+			@gpio.close
+		end
+
+		# Wait for an interruption and process all pending event.
+		# The interruption mode must be enabled for this method to work.
+		# This is a blocking method. Use `resume()` inside a callback to stop waiting.
+		def wait_for_event
+			raise "Interrupt is not enabled. Setup enable_interrupt() first" unless interrupt?
+			YaGPIO::wait([@gpio])
+		end
+
+		# Stop waiting for an event in the interruption mode.
+		# This need to be run from a callback triggered by `wait_for_event()`.
+		def resume
+			YaGPIO::resume
+		end
+
+		# Represent an event attached to a key
+		class KeyEvent
+			attr_reader :key  # Key ID
+			attr_reader :edge # Event type
+
+			# Create a new event.
+			#
+			# @param key [Integer] Key ID related to the event
+			# @param edge [Neotrellis::Keypad::KEY_PRESSED|Neotrellis::Keypad::KEY_RELEASED] Type of event
+			def initialize(key, edge)
+				@key = key
+				@edge = edge
+			end
+
+			def to_s
+				"Event-#{key}-#{edge}"
+			end
+
+			def ==(other)
+				@key == other.key && @edge == other.edge
+			end
+
+			alias eql? ==
+
+			def hash
+				@key.hash ^ @edge.hash # XOR
+			end
+		end
+
+		private
+
+		def read_events(count)
+			@seesaw.read_bytes(count, KEYPAD_BASE, KEYPAD_FIFO).map do |raw|
+				# Convert raw event into key number
+				val = (raw >> 2) & 0x3F
+				key = (val/8)*4 + (val%8)
+				edge = raw & 0x3
+
+				KeyEvent.new(key, edge)
+			end
+		end
+
+		def trigger_event(event)
+			callback = @callbacks[event]
+			if callback.nil?
+				puts "WARNING: No callback defined for #{event}"
+			else
+				callback.call(event)
+			end
+		end
+	end
+end
+
+# vim: ts=4:sw=4:ai

data/lib/neotrellis/neopixel.rb

@@ -0,0 +1,198 @@
+# Neotrellis - Driver for Adafruit's NeoTrellis keypad
+# 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/>.
+#
+###########################################################################
+
+
+# Neotrellis is a ruby driver for Adafruit's NeoTrellis keypad
+module Neotrellis
+
+	# Neopixel is the driver of the RGB led array on the Neotrellis device.
+	#
+	# @example Turn on led #2 in red for 2 seconds with debug output
+	#   seesaw = Neotrellis::Seesaw.new(device: "/dev/i2c-1", addr: 0x2E, debug: true)
+	#   pixels = Neotrellis::Neopixel.new(seesaw)
+	#   pixels.set(1, Neotrellis::Neopixel::RED)
+	#   sleep 2
+	#   pixels.set(1, Neotrellis::Neopixel::OFF)
+	#
+	# @example Turn on all leds with color #b5f115 for 2 seconds
+	#   seesaw = Neotrellis::Seesaw.new(device: "/dev/i2c-1", addr: 0x2E)
+	#   pixels = Neotrellis::Neopixel.new(seesaw)
+	#   pixels.fill(Neotrellis::Neopixel::Color.new(181, 241, 21))
+	#   sleep 2
+	#   pixels.off
+	#
+	# @example Display white columns
+	#   seesaw = Neotrellis::Seesaw.new(device: "/dev/i2c-1", addr: 0x2E)
+	#   pixels = Neotrellis::Neopixel.new(seesaw, autoshow: false)
+	#   Neotrellis::Neopixel::DEFAULT_PIXEL_NUMBER.times { |i|
+	#   	pixels.set(i, Neotrellis::Neopixel::WHITE) unless i%2 == 0
+	#   }
+	#   pixels.show
+	class Neopixel
+		attr_reader :brightness   # Get the brightness of the leds.
+		attr_accessor :autoshow   # Enable autoshow feature. Automatically call `show()` after each update.
+
+		DEFAULT_PIXEL_NUMBER = 16 # Default number of leds on the neotrellis 4x4 keypad
+
+		private
+
+			NEOPIXEL_BASE = 0x0E
+
+			NEOPIXEL_STATUS = 0x00
+			NEOPIXEL_PIN = 0x01
+			NEOPIXEL_SPEED = 0x02
+			NEOPIXEL_BUF_LENGTH = 0x03
+			NEOPIXEL_BUF = 0x04
+			NEOPIXEL_SHOW = 0x05
+
+		public
+
+		# Initialize a neopixel array driven by a seesaw chip.
+		#
+		# @param seesaw [Neotrellis::SeeSaw] Seesaw driver
+		# @param size [Integer] Number of leds on the array
+		# @param autoshow [Boolean] Automatically call `show()` after each update
+		# @param brightness [Float] Brightness of the leds. Must be between 0.0 and 1.0
+		def initialize(seesaw, size: DEFAULT_PIXEL_NUMBER, autoshow: true, brightness: 1.0)
+			@seesaw = seesaw
+			@pin = 3				# NeoPixel bus is on SeeSaw's pin 3
+			@n = size 				# Number of NeoPixels on the bus
+			@bpp = 3				# 3 bytes per pixel
+			@autoshow = autoshow	# Automaticaly display data in buffer
+			@brightness = [[brightness, 0.0].max, 1.0].min
+
+			# Size of RGB buffer, 2 bytes for Unsigned Int Big Endian
+			buf_length = [@n*@bpp].pack('S>').unpack('C*')
+
+			@seesaw.write(NEOPIXEL_BASE, NEOPIXEL_PIN, @pin)
+			@seesaw.write(NEOPIXEL_BASE, NEOPIXEL_BUF_LENGTH, *buf_length)
+		end
+
+		# Set the brightness of the leds
+		#
+		# @param brightness [Float] Brightness of the leds. Must be between 0.0 and 1.0
+		#
+		# @return [Float] New brightness value
+		def brightness=(brightness)
+			@brightness = [[brightness, 0.0].max, 1.0].min
+		end
+
+		# Set the color of one pixel.
+		# If `autoshow` is false nothing will be displayed until you call the `show()` method.
+		#
+		# @param pixel [Integer] ID of the pixel in the array. Must be between 0 and `size`-1
+		# @param color [Neotrellis::Neopixel::Color] Color to display by the pixel
+		def set(pixel, color)
+			raise "pixel out of range" unless pixel.between?(0, @n-1)
+
+			@seesaw.write(NEOPIXEL_BASE, NEOPIXEL_BUF, *([pixel*@bpp].pack('S>').unpack('C*')), *color.to_b(brightness))
+			show if @autoshow
+		end
+
+		# Render the data already written in the Seesaw buffer.
+		# If `autoshow` is true, this method is called automatically by `set()` and `fill()`
+		def show
+			@seesaw.write(NEOPIXEL_BASE, NEOPIXEL_SHOW)
+		end
+
+		# Set the same color for all pixels of the array.
+		# If `autoshow` is false nothing will be displayed until you call the `show()` method.
+		#
+		# @param color [Neotrellis::Neopixel::Color] Color to display by the pixels
+		def fill(color)
+			# Disable auto show while filling the buffer
+			current_autoshow = @autoshow
+			@autoshow=false
+
+			@n.times do |pixel|
+				set(pixel, color)
+			end
+
+			@autoshow = current_autoshow
+			show if @autoshow
+		end
+
+		# Set a different random color for every pixels of the array.
+		# If `autoshow` is false nothing will be displayed until you call the `show()` method.
+		def fill_random()
+			# Disable auto show while filling the buffer
+			current_autoshow = @autoshow
+			@autoshow=false
+
+			@n.times do |pixel|
+				set(pixel, Color.new(rand(255), rand(255), rand(255)))
+			end
+
+			@autoshow = current_autoshow
+			show if @autoshow
+		end
+
+		# Swtich off all pixels of the array.
+		# If `autoshow` is false nothing will be displayed until you call the `show()` method.
+		def off()
+			fill(OFF)
+		end
+
+		# Define a color to be set on a pixel
+		class Color
+			attr_reader :r, :g, :b  # R G B components
+
+			# Create a new color.
+			# R G B values must be between 0 and 255
+			#
+			# @param r [Integer] Red component
+			# @param g [Integer] Green component
+			# @param b [Integer] Blue component
+			def initialize(r, g, b)
+				@r = within_range(r)
+				@g = within_range(g)
+				@b = within_range(b)
+			end
+
+			# Apply a brightness to the color.
+			#
+			# @param brightness [Float] Brightness of the color. Must be between 0.0 and 1.0
+			#
+			# @return [Array] Color values as integer in the order GRB
+			def to_b(brightness = 1.0)
+				# Order is GRB
+				[(@g*brightness).to_i, (@r*brightness).to_i, (@b*brightness).to_i]
+			end
+
+			private
+
+			def within_range(byte)
+				[[byte, 0].max, 255].min
+			end
+		end
+
+		# Default common colors
+		OFF 	= Color.new(0, 0, 0)
+		RED 	= Color.new(255, 0, 0)
+		YELLOW 	= Color.new(255, 150, 0)
+		GREEN 	= Color.new(0, 255, 0)
+		CYAN 	= Color.new(0, 255, 255)
+		BLUE 	= Color.new(0, 0, 255)
+		PURPLE 	= Color.new(180, 0, 255)
+		WHITE   = Color.new(255, 255, 255)
+	end
+end
+
+# vim: ts=4:sw=4:ai