frankenpins 0.2.1 → 0.3.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NjJiYmEyZmVlNjc5NjVmMmFlYmVlZTkwODY0N2YyNWQ2N2VkN2I2NQ==
+    Y2QzZWE0ZWFkNTYwMDYyMTZlMjRiNTExOTg0MWY0MjlhNTVkZmU0ZQ==
   data.tar.gz: !binary |-
-    MTRmMGZiYjNiMDhmMDY4MmMzNDUyMjc3NDhjM2IyODA1ZDI3YjQzNg==
+    YzBlYzczNGIxNjlkNDQxNzQzMDRmNWFkMGVkYWU0ZDQ1NWRjOWVmMw==
 SHA512:
   metadata.gz: !binary |-
-    ZDc4MGNjNDUyOTE3NjNkY2RiYTI2NTk5MThlMTQ2ZTYyZmU2NjJhZDBlZmUx
-    NWY1NjVkNjUzZDQ3ZjlkZmE0ZTczMDJhNTZlYjM4N2RhMGI2YjU2YWI4MmE4
-    OGI0NWFlYjYwNjdhMDk3MmExMzBmYmM5MjhmODY3ZjkxM2M2YjM=
+    MGFlODJlNmJkMGVlOWUwNjFhMjVkNGI0M2NkNGFjMGUwZDI4MjUxNzlmNmYx
+    OTEwZjYyNGY4ZGFkOWRlNWE4NTUyYTYxOTFlMjIzNGEyNGY1NzU2N2ZlNTgw
+    ZjIyOTNjNzA2ZDg3Nzc2NmM0Y2ViYmQ0YjcyYTZlZGI5ZGM4MGI=
   data.tar.gz: !binary |-
-    YjE1NzdkYjI5YTExZTgxMzM4MjUxZDg1Y2ZhMWM4ZGRiOThjZDU1N2RiMjlk
-    ZDViZGNhMzU4ZjRlMDY0Njk5MGViZjc3MGVlMTI1MTExNGIyOWY4NTc0MTc4
-    YmFhOTE3MTQ3YTRhYzQzY2NhYmI3MDczN2MyMzkzZWMzM2NkNjQ=
+    NjMxNGU3N2U0YmU3ZDEzZjAyZmE4YTM1ODc2YjI5YmJjY2MzOThkOGFmZDFh
+    ZDA2N2I1MmQxMDBkN2Y5MmI3NTU3OGQzNTU4MjUxOWQwNTFmMzYxMDY2YTM1
+    ZmU1NWE3MzUzMDRhZDc0YmFjZjg3YWUwZmNkZGVhMzUxODViNDQ=

data/README.md

@@ -30,6 +30,11 @@ Frankenpins uses the WiringPi convention for pin numbering. The wiring pi set ha
 
 ![wiring pi pin numbering chart](http://wiringpi.com/wp-content/uploads/2013/03/gpio1.png)
 
+Examples
+---
+
+There is demo code in the `examples` folder showing how to use of each of the components.
+
 Buttons
 ---
 
@@ -38,7 +43,7 @@ Frankenpins is event-based.
     require 'frankenpins'
 
     button = Frankenpins::Button.new(:pin => 0, :pull => :up)
-    button.on :pressed do
+    button.when :pressed do
       puts "Button pressed"
     end
 
@@ -50,7 +55,7 @@ First we create a new button, telling the library that the button is on wiring p
 
 Then we register a block of code to be called whenever the button is pressed down:
 
-    button.on :pressed do
+    button.when :pressed do
       puts "Button pressed"
     end
 
@@ -64,6 +69,93 @@ Finally, we tell Frankenpins to keep the program running until we quit it. Other
 
     Frankenpins.wait
 
+
+LEDs
+---
+
+You can control a Light Emitting Diode (LED) connected to WiringPi pin 5 as follows:
+
+    require 'frankenpins'
+
+    led = Frankenpins::LED.new(:pin => 5)
+    led.on
+    sleep(3)
+    led.off
+
+### Brightness
+
+You can specify the brightness of the LED. Brightness can be between `0` (off) and `100` (on) and must be an integer.
+
+    require 'frankenpins'
+
+    led = Frankenpins::LED.new(:pin => 5)
+    led.on
+    led.brightness(50) # 50% brightness
+
+### Transitions
+
+Turning an LED on and off is good, but Frankenpins can do better. It allows you to fade the LED over a set duration. `on`, `off` and `brightness` all take a `:duration` option that specifies the number of seconds to fade over. This example fades the LED on over 1 second, fades to 50% brightness over 1 second and then off over 2 seconds.
+
+    require 'frankenpins'
+
+    led = Frankenpins::LED.new(:pin => 5)
+    led.on(:duration => 1)
+    led.brightness(50, :duration => 1)
+    led.off(:duration => 2)
+
+
+
+You can set a `default_transition` in seconds which will apply to all calls. This example makes the LED to fade on over 2 seconds and then off over 2 seconds:
+
+    require 'frankenpins'
+
+    led = Frankenpins::LED.new(:pin => 5)
+    led.default_duration = 2
+    led.on
+    led.off
+
+
+### A note about transitions
+
+The transitions are all queued up but don't stop your code from running. So, if you have:
+
+    led.on(:duration => 10)
+    led.off(:duration => 1)
+
+Your code won't stop for 11 seconds until the transitions have finished, the transitions will happen in the background. This means your main programme may finish before the transitions do, to avoid that use `Frankenpins.wait` to keep your main code running:
+
+    led.on(:duration => 10)
+    led.off(:duration => 1)
+    Frankenpins.wait
+
+RGB LEDs
+---
+
+These work in the same way as LEDs above, except that the LED has 4 legs. A common ground and 1 for each colour.
+
+Connect each leg to a pin and tell Frankenpins about it. You can then use them in much the same way as a normal LED, except instead of specifying on overall brightness, you specify a colour to change the LED to.
+
+    require 'frankenpins'
+
+    led = Frankenpins::RGBLED.new(:pins => { :green => 5, :red => 4, :blue => 1 })
+    led.on
+    led.rgb([255, 0, 0])
+
+`rgb([r, g, b])` requires a value for red, green, blue from 0-255 where 0 is off and 255 is full brightness.
+
+`percentage([r, g, b])` requires a value from 0-100 for each colour where 0 if off and 100 if full brightness.
+
+RGB LEDs also support transitions too, so the following works. This example will make the RGB transition to purple over 2 seconds and then turn off over 1 second.
+
+    require 'frankenpins'
+
+    led = Frankenpins::RGBLED.new(:pins => { :green => 5, :red => 4, :blue => 1 })
+    led.default_duration = 2
+    led.on
+    led.rgb([0, 255, 255])
+    led.off(:duration => 1)
+
+
 Pins
 ---
 

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.pattern = "test/**/*_test.rb"
+end
+
+task :default => [:test]

data/examples/button.rb

@@ -6,15 +6,15 @@ require_relative '../lib/frankenpins'
 # as an option
 button = Frankenpins::Button.new(:pin => 0)
 
-button.on :pressed do
+button.when :pressed do
   puts "Button pressed"
 end
 
-button.on :released do
+button.when :released do
   puts "Button released"
 end
 
-button.on :changed do
+button.when :changed do
   puts "Button changed"
 end
 

data/examples/led.rb

@@ -0,0 +1,42 @@
+require_relative '../lib/frankenpins'
+
+# Create a new LED attached to Wiring Pi pin #6.
+led = Frankenpins::LED.new(:pin => 6)
+
+# Simple LED examples
+
+puts "Turning LED on"
+led.on
+
+# Do nothing for 2 seconds
+sleep(2)
+
+puts "Turning LED off"
+led.off
+
+sleep(2)
+
+# Variable brightness using PWM
+
+puts "Turning to the LED to 20% brightness"
+led.brightness(20)
+led.on
+sleep(2)
+
+puts "Turning to the LED to 40% brightness"
+led.brightness(40)
+sleep(2)
+
+puts "Turning to the LED to 60% brightness"
+led.brightness(60)
+sleep(2)
+
+puts "Turning to the LED to 80% brightness"
+led.brightness(80)
+
+sleep(2)
+
+puts "Turn LED off"
+led.off
+
+Frankenpins.wait

data/examples/led_fade.rb

@@ -0,0 +1,53 @@
+require_relative '../lib/frankenpins'
+
+# Create a new LED attached to Wiring Pi pin #6.
+led = Frankenpins::LED.new(:pin => 6)
+
+led.off
+
+puts "1. Turn on/off over 1s"
+led.on(:duration => 1)
+sleep(2)
+led.off(:duration => 1)
+
+sleep(2)
+
+puts "2. Turn on to brightness 10 over 1s"
+led.brightness(10)
+led.on(:duration => 1)
+puts "   Turn off immediately"
+sleep(1)
+led.off
+
+sleep(2)
+
+puts "3. Turn to brightness 10 immediately"
+led.brightness(10)
+led.on
+puts "   then transition to brightness 80 over 3s"
+sleep(1)
+led.brightness(80, :duration => 3)
+puts "   then transition to brightness 10 over 3s"
+sleep(1)
+led.brightness(10, :duration => 3)
+puts "   then turn off over 1s"
+sleep(1)
+led.off(:duration => 1)
+
+sleep(2)
+
+puts "4. Always transition over 2s"
+led.default_duration = 2
+puts "   on"
+led.on  # over 2s
+sleep(1)
+puts "   20% brightness"
+led.brightness(20)
+sleep(1)
+puts "   off"
+led.off # over 2s
+
+puts "Finished!"
+
+Frankenpins.wait
+

data/examples/rgb_led.rb

@@ -0,0 +1,36 @@
+require_relative '../lib/frankenpins'
+
+# Create a new LED attached to Wiring Pi pin #6.
+led = Frankenpins::RGBLED.new(:pins => { :green => 5, :red => 4, :blue => 1 })
+
+colours = {
+  :purple => [80 , 0  , 80   ],
+  :red    => [255, 0  , 0    ],
+  :green  => [0  , 255, 0    ],
+  :blue   => [0  , 0  , 255  ],
+  :yellow => [255, 255, 0    ],
+  :aqua   => [0  , 255, 255  ],
+  :indigo => [0x4B, 0x0, 0x82] # Hex colour
+}
+
+led.on
+
+puts "Change colours"
+colours.each do |name, rgb|
+  puts "#{name.to_s}  #{rgb}"
+  led.rgb(rgb)
+  sleep(2)
+end
+
+puts "Fade between colours"
+colours.each do |name, rgb|
+  puts "#{name.to_s}  #{rgb}"
+  led.rgb(rgb, :duration => 2)
+  sleep(2)
+end
+
+led.off(:duration => 2)
+
+puts "Finished"
+
+Frankenpins.wait

data/examples/rotary_encoder.rb

@@ -7,14 +7,14 @@ require_relative '../lib/frankenpins'
 # option :pull => :none
 encoder = Frankenpins::RotaryEncoder.new(:pin_a => 4, :pin_b => 5)
 
-encoder.on :changed do |pos, direction|
+encoder.when :changed do |pos, direction|
   puts "position: #{pos}, direction: #{direction}"
 end
 
 # Use the Button class to watch the switch part of the
 # encoder, push down to activate
 button = Frankenpins::Button.new(:pin => 1)
-button.on :pressed do
+button.when :pressed do
   puts "Button pressed"
 end
 

data/frankenpins.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = 'frankenpins'
-  s.version     = '0.2.1'
+  s.version     = '0.3.0'
   s.date        = '2013-08-28'
   s.summary     = "Connect buttons etc to your Rapsberry Pi"
   s.description = "Connect buttons etc to your Rapsberry Pi"

data/lib/frankenpins.rb

@@ -4,6 +4,8 @@ require_relative 'frankenpins/wiring_pi_singleton'
 require_relative 'frankenpins/pin'
 require_relative 'frankenpins/button'
 require_relative 'frankenpins/rotary_encoder'
+require_relative 'frankenpins/led'
+require_relative 'frankenpins/rgb_led'
 
 module Frankenpins
   include Utils

data/lib/frankenpins/button.rb

@@ -24,7 +24,7 @@ module Frankenpins
       end
     end
 
-    def on(event_name, &block)
+    def when(event_name, &block)
       send(event_name).register(&block)
     end
   end

data/lib/frankenpins/led.rb

@@ -0,0 +1,77 @@
+require 'ostruct'
+require 'thread'
+Thread.abort_on_exception = true
+
+require_relative './led_transition'
+require_relative './transition_queue'
+
+module Frankenpins
+  class LED
+
+    attr_reader :default_duration
+    attr_writer :default_duration
+
+    def initialize(options={})
+      options[:direction] = :out
+      @pin = Frankenpins::Pin.new(options)
+
+      @using_pwm = false
+      @pwm_max   = 100
+
+      @is_on = false
+      @brightness = 0
+
+      # TODO: Should be 0?
+      @default_duration = nil
+
+      @queue = TransitionQueue.new
+      @queue.start!
+    end
+
+    def on(opts={})
+      brightness(100, opts)
+      @is_on = true
+    end
+
+    def off(opts={})
+      brightness(0, opts)
+      @is_on = false
+    end
+
+    def brightness(value, opts={})
+
+      duration = opts[:duration] || @default_duration
+
+      if value != 100 || value != 0 || duration
+        use_pwm!
+      end
+
+      props = { :pin => @pin }
+
+      if duration
+        props[:type]     = :pwm
+        props[:from]     = @brightness
+        props[:to]       = value
+        props[:duration] = duration
+      elsif @using_pwm
+        props[:type]  = :pwm
+        props[:value] = value
+      else
+        props[:type]  = :digital
+        props[:value] = false if @brightness == 0
+        props[:value] = true  if @brightness == 100
+      end
+
+      @queue.push(LEDTransition.new(props))
+      @brightness = value
+    end
+
+    private
+    def use_pwm!
+      if @using_pwm == false
+        @pin.io.soft_pwm_create(@pin.wiring_pin, 0, @pwm_max)
+        @using_pwm = true
+      end
+    end
+  end
+end

data/lib/frankenpins/led_transition.rb

@@ -0,0 +1,47 @@
+module Frankenpins
+  # A transition of the brightness of
+  # the LED.
+  # Transitions encode all the info
+  # necessary to change the state
+  class LEDTransition < OpenStruct
+
+    def perform!
+      if type == :digital
+        digital_write(value)
+      elsif duration
+        transition!
+      elsif type == :pwm
+        pwm_write(value)
+      end
+    end
+
+    def transition!
+      duration_in_secs = duration
+      from_value       = from
+      to_value         = to
+      increment_time_in_sec = 0.01
+
+      range = to_value - from_value
+
+      increment = increment_time_in_sec.to_f / duration_in_secs.to_f
+      steps = (duration_in_secs.to_f / increment_time_in_sec.to_f).to_i
+
+      brightness_value = from_value
+
+      steps.times.each do
+        brightness_value = brightness_value + (increment * range)
+        pwm_write(brightness_value)
+        sleep(increment_time_in_sec)
+      end
+    end
+
+    def digital_write(value)
+      pin.write(value)
+    end
+
+    def pwm_write(value)
+      # puts "pwm_write(#{pin.wiring_pin}, #{value.to_i})"
+      pin.io.soft_pwm_write(pin.wiring_pin, value.to_i)
+    end
+  end
+end

data/lib/frankenpins/pin.rb

@@ -14,7 +14,7 @@ module Frankenpins
     PUD_DOWN = 1
     PUD_UP = 2
 
-    attr_reader :pin, :last_value, :value, :direction, :invert
+    attr_reader :io, :pin, :wiring_pin, :last_value, :value, :direction, :invert
 
     def wiring_to_gpio(pin)
       @io.wpi_pin_to_gpio(pin)
@@ -109,6 +109,11 @@ module Frankenpins
       @value = invert ? (val ^ 1) : val
     end
 
+    def write(value)
+      value = value ? "1" : "0"
+      File.open(value_file, 'w') {|f| f.write(value) } if direction == :out
+    end
+
     private
     def value_file
       "/sys/class/gpio/gpio#{pin}/value"

data/lib/frankenpins/rgb_led.rb

@@ -0,0 +1,62 @@
+module Frankenpins
+  class RGBLED
+
+    attr_reader :default_duration
+    attr_writer :default_duration
+
+    def initialize(options={})
+      @is_on = false
+      @pin_nums = options.delete(:pins)
+      @red   = LED.new( config_for_pin(@pin_nums[:red], options) )
+      @green = LED.new( config_for_pin(@pin_nums[:green], options) )
+      @blue  = LED.new( config_for_pin(@pin_nums[:blue], options) )
+
+      @default_duration = nil
+    end
+
+    def on(opts={})
+      [@red, @green, @blue].map { |led| led.on(opts) }
+      rgb(opts[:rgb]) if opts[:rgb]
+      percentage(opts[:percent]) if opts[:percent]
+      @is_on = true
+    end
+
+    def off(opts={})
+      [@red, @green, @blue].map { |led| led.off(opts) }
+      @is_off = true
+    end
+
+    def rgb(rgb, opts={})
+      write_colours(*rgb.map { |val| rgb_val_to_brightness(val) }, opts)
+    end
+
+    def percentage(rgb, opts={})
+      write_colours(*rgb, opts)
+    end
+
+    private
+    def rgb_val_to_brightness(val)
+      scale(val, 255, 100).to_i
+    end
+
+    def config_for_pin(num, options)
+      opts = options.clone
+      opts[:pin] = num
+      opts
+    end
+
+    def write_colours(r, g, b, opts={})
+      duration = opts[:duration] || @default_duration
+      @red.brightness(r, :duration => duration)
+      @green.brightness(g, :duration => duration)
+      @blue.brightness(b, :duration => duration)
+    end
+
+    # e.g. 30/255 -> ?/100
+    #      = scale(30, 255, 100)
+    #      = 11.764705882
+    def scale(val, domain, range)
+      (val.to_f/domain.to_f) * range.to_f
+    end
+  end
+end

data/lib/frankenpins/rotary_encoder.rb

@@ -38,7 +38,7 @@ module Frankenpins
       @last_val = encoded
     end
 
-    def on(event_name, &block)
+    def when(event_name, &block)
       send(event_name).register(&block)
     end
 

data/lib/frankenpins/transition_queue.rb

@@ -0,0 +1,26 @@
+module Frankenpins
+  # A transition queue
+  # Items added to the queue are
+  # executed in order
+  class TransitionQueue
+    def initialize
+      @queue = Queue.new
+      @debug = false
+    end
+
+    def push(transition)
+      puts "E: #{transition.type} #{transition}" if @debug
+      @queue.push(transition)
+    end
+
+    def start!
+      Thread.new do
+        loop do
+          transition = @queue.pop
+          puts "D: #{transition.type} #{transition}" if @debug
+          transition.perform!
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: frankenpins
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Andrew Nicolaou
@@ -49,14 +49,22 @@ files:
 - Gemfile
 - Gemfile.lock
 - README.md
+- Rakefile
 - examples/button.rb
+- examples/led.rb
+- examples/led_fade.rb
 - examples/raw_pin.rb
+- examples/rgb_led.rb
 - examples/rotary_encoder.rb
 - frankenpins.gemspec
 - lib/frankenpins.rb
 - lib/frankenpins/button.rb
+- lib/frankenpins/led.rb
+- lib/frankenpins/led_transition.rb
 - lib/frankenpins/pin.rb
+- lib/frankenpins/rgb_led.rb
 - lib/frankenpins/rotary_encoder.rb
+- lib/frankenpins/transition_queue.rb
 - lib/frankenpins/utils.rb
 - lib/frankenpins/wiring_pi_singleton.rb
 - scratch/button-wiring.rb