piface 0.3.1 → 0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5219d7765054be32e631d3fd3cb1ab59d8f4b11b
-  data.tar.gz: fd6d6999a89eb8c8ad9df17525bc8e3ec31ad006
+  metadata.gz: 62414175fab73d83fa196972a27b8178bc4646af
+  data.tar.gz: 85b434904389380c0574cc7023037eeaec645fdd
 SHA512:
-  metadata.gz: acc2bd5290e6c98cd558511081463bfd7059cd8a094b07d31ff51539929bb8fd5306b5cc6e5db781a6c790b6899b08c6d33e85eeda9f18cb2a807fa06fa029be
-  data.tar.gz: adbc64f4d580b2ac6e53705d8c2c24485bdab28780272a8f6ae2c519730def47d649266c82b555f06977c4d5a88eae6ee83c753c5224c44acc372ca3544eb1aa
+  metadata.gz: 4559d83b88665b759c2de81849bf859e9733bdd80551dbafc54662d7b9587c3348eb7e6f5ccb54d6b2468fe3c48cc5e940001ef9651ec9c9843db727d2d571b5
+  data.tar.gz: 4f1dea3ef063bdb39ef88d70bc1a215ff06a4cbb4e46fdcdf83940b2696c4304ce00c71614b629748c0ae35b42045124167d0b971b040e82b2508421a702169a

data/CHANGELOG.md

@@ -3,6 +3,13 @@
 ## Upcoming v1.0
  - Interrupts (change, high, low)
 
+## v0.4.beta
+ - update ffi runtime dependancy to ~> v1.7
+ - updated README.md
+ - added pfio C library as gem extension
+ - updated pfio C library to allow optional pin setup (false by default)
+ - fixed deinit bug
+
 ## v0.31
  - updated the ffi load paths (bugfix for issue #1)
 

data/README.md

@@ -9,10 +9,10 @@ Ruby method names, as well as other aspects, may change until version 1.0 is rel
 
 The PiFace has 8 inputs and 8 outputs. Both the inputs and outputs are linked to connectors 1-8 respectfully.
 
-Note: The pfio C library will set all outputs to LOW (zero) when first initialized.
+Note: By default, the input and output pins will not be reset when first initialized. To find out more, see [Piface Initialization](https://github.com/blakejakopovic/piface#piface-initialisation).
 
 ### Using Outputs
-Writing to outputs 1 to 8 with all turn on the LEDs. Write to outputs using Piface::LOW (or 0) for off/disable and Piface::HIGH (or 1) for on/enable.
+Writing to outputs 1 to 8 with all turn on the LEDs. Write to outputs using `Piface::LOW` (or 0) for off/disable and `Piface::HIGH` (or 1) for on/enable.
 
 Please note that the PiFace outputs are all open-collectors (meaning that they do not output any voltage). Please read the [PiFace Manual](http://www.farnell.com/datasheets/1684425.pdf) for more information.
 
@@ -43,7 +43,7 @@ Piface.write 1, 0
 ```
 
 ### Using Classes
-Sometimes it's nice to represent an output using a class. One common example is when you want to track the current state of the output.
+Sometimes it's nice to represent an output using a class. One common example is when you want to track the current state of the output. Also see the [Stateless Relay Class](https://github.com/blakejakopovic/piface#stateless-relay-class)
 ```ruby
 require 'piface'
 
@@ -107,6 +107,71 @@ loop do
 end
 ```
 
+## Advanced Usage
+
+### Piface Initialization
+By requiring the gem, your Piface will automatically be initialized. By default, your pins will not be reset and will remain in the existing state. This is useful when running multiple scripts and you don't want to reset the outputs (turning them all off). If you want to setup the pins you can do so by calling the `init` method with `true`.
+```ruby
+require 'piface'
+
+# Initialize the piface (without setting up the pins)
+Piface.init # same as Piface.init(false)
+
+# Initialize Piface and setup the pins
+Piface.init(true)
+```
+
+### Reading Output
+If you need to check whether or not an output is active, you can easily read an output state with the `read_output` method.
+```ruby
+require 'piface'
+
+# Read the current output of pin 8 (when off)
+Piface.read_output 8
+# => 0
+
+# Read the current output of pin 2 (when on)
+Piface.read_output 2
+# => 1
+```
+
+### Stateless Relay class
+If you have multiple scripts running, it can be hard to keep track of output states. By using a stateless class, you can implement a toggle method that reads the current state, instead of using a stored state. Keep in mind that by reading the state is it less effecient.
+```ruby
+require 'piface'
+
+class Relay
+  def initialize(relay_number)
+    @relay_number = relay_number
+  end
+
+  def turn_on
+    Piface.write @relay_number, 1
+  end
+
+  def turn_off
+    Piface.write @relay_number, 0
+  end
+
+  def toggle
+    Piface.write @relay_number, Piface.read_output(1) ^ 1
+  end
+end
+
+relay2 = Relay.new(2)
+relay.toggle # toggle the light without using a stored state
+```
+
+## Examples
+For more examples, check out the `example` directory.
+* led
+* pir sensor
+* relay (same as stateless relay)
+* toggle button
+
+## Example Projects
+* [Siriproxy Piface](https://github.com/elvisimprsntr/siriproxy-piface) - "I used my RPi, PiFace IO board, along with SiriProry as a simple voice controlled garage door opener."
+
 ## Additional Resources
 * [The PiFace Digital PDF Manual](http://www.farnell.com/datasheets/1684425.pdf)
 * [pfio C Library](https://github.com/thomasmacpherson/piface/blob/master/c/)
@@ -114,13 +179,10 @@ end
 
 ## Installation
 
-First install the pfio C Library
-
-[https://github.com/thomasmacpherson/piface](https://github.com/thomasmacpherson/piface)
-
-Enable RaspberryPi's SPI module
+Enable RaspberryPi's SPI module (required on each reboot)
 
-    $ gpio load spi
+    $ sudo modprobe spi_bcm2708
+    $ sudo chown `id -u`.`id -g` /dev/spidev0.*
 
 Add this line to your application's Gemfile:
 

data/examples/led.rb

@@ -0,0 +1,33 @@
+# piface/examples/led.rb
+
+require 'piface'
+
+class LED
+  def initialize(pin_number)
+    @pin_number = pin_number
+  end
+
+  def turn_on
+    Piface.write @pin_number, 1
+  end
+
+  def turn_off
+    Piface.write @pin_number, 0
+  end
+
+  def state
+    Piface.read_output(@pin_number)
+  end
+
+  def toggle
+    new_state = state ^ 1
+    Piface.write @pin_number, new_state
+  end
+
+  def blink(times = 1)
+    0.upto(times * 2) do
+      toggle
+      sleep 0.25
+    end
+  end
+end

data/examples/pir_sensor.rb

@@ -0,0 +1,12 @@
+# piface/examples/pir_sensor.rb
+
+require 'piface'
+
+SENSOR_PIN = 5
+
+puts "Waiting for motion..."
+while Piface.read(SENSOR_PIN) == 1
+  sleep 0.5
+end
+
+puts "MOTION DETECTED"

data/examples/relay.rb

@@ -0,0 +1,29 @@
+# piface/examples/relay.rb
+
+require 'piface'
+
+class Relay
+  def initialize(relay_number)
+    @relay_number = relay_number
+  end
+
+  def turn_on
+    Piface.write @relay_number, 1
+  end
+
+  def turn_off
+    Piface.write @relay_number, 0
+  end
+
+  def state
+    Piface.read_output(@relay_number)
+  end
+
+  def toggle
+    new_state = state ^ 1
+    Piface.write @relay_number, new_state
+  end
+end
+
+relay2 = Relay.new(2)
+relay.toggle # toggle the light without using a stored state

data/examples/toggle_button.rb

@@ -0,0 +1,43 @@
+# piface/examples/toggle_button.rb
+
+require 'piface'
+
+class ToggleButton
+
+  LOW  = 0
+  HIGH = 1
+
+  def initialize(pin_number)
+    @pin_number = pin_number
+    @thread = nil
+  end
+
+  def toggle
+    new_state = Piface.read_output(@pin_number) ^ 1
+    Piface.write(@pin_number, new_state)
+  end
+
+  def read_pin
+    Piface.read(@pin_number)
+  end
+
+  def activate
+    @thread = Thread.new do
+      loop do
+        if read_pin == LOW
+          toggle
+          sleep 0.1 while read_pin == LOW # wait until released
+        end
+
+        sleep 0.05
+      end
+    end
+  end
+
+  def deactivate
+    Thread.kill(@thread) if @thread
+  end
+end
+
+# button = ToggleButton.new(2)
+# button.activate

data/ext/piface/extconf.rb

@@ -0,0 +1,3 @@
+require 'mkmf'
+
+create_makefile('piface/pfio')

data/ext/piface/pfio.c

@@ -0,0 +1,189 @@
+/**
+ * pfio.c
+ * functions for accessing the PiFace add-on for the Raspberry Pi
+ */
+#include "pfio.h"
+
+#undef VERBOSE_MODE
+
+static Spi * spi;
+
+static void spi_transfer(char * txbuffer, char * rxbuffer);
+static void spi_write(char port, char value);
+static char spi_read(char port);
+
+
+// char pfio_init(void)
+char pfio_init(bool setup_pins)
+{
+    if ((spi = malloc(sizeof(Spi))) == NULL)
+        return -1;
+
+    // initialise the spi with some values
+    // create the path string
+    char path[MAXPATH];
+    if (snprintf(path, MAXPATH, "/dev/spidev%d.%d", SPI_BUS, SPI_DEVICE) >= MAXPATH)
+    {
+        fprintf(stderr, "ERROR: Bus and/or device number is invalid.");
+        return -1;
+    }
+
+    // try to open the device
+    if ((spi->fd = open(path, O_RDWR, 0)) < 0)
+    {
+        fprintf(stderr, "ERROR: Can not open device");
+        return -1;
+    }
+
+    // try to control the device
+    char temp;
+    if (ioctl(spi->fd, SPI_IOC_RD_MODE, &temp) < 0)
+    {
+        fprintf(stderr, "ERROR: Can not get spi mode");
+        return -1;
+    }
+    spi->mode = temp;
+
+    // try to get the bits per word
+    if (ioctl(spi->fd, SPI_IOC_RD_BITS_PER_WORD, &temp) < 0)
+    {
+        fprintf(stderr, "ERROR: Can not get bits per word");
+        return -1;
+    }
+    spi->bitsperword = temp;
+
+    // try to get the max speed
+    int maxspeed;
+    if (ioctl(spi->fd, SPI_IOC_RD_MAX_SPEED_HZ, &maxspeed) < 0)
+    {
+        fprintf(stderr, "ERROR: Can not get max speed hz");
+        return -1;
+    }
+    spi->maxspeed = maxspeed;
+
+    if (setup_pins == true) {
+        // set up some ports
+        spi_write(IOCON,  8);    // enable hardware addressing
+        spi_write(IODIRA, 0);    // set port A as outputs
+        spi_write(IODIRB, 0xFF); // set port B as inputs
+        spi_write(GPIOA,  0xFF); // set port A on
+        //spi_write(GPIOB,  0xFF); // set port B on
+        spi_write(GPPUA,  0xFF); // set port A pullups on
+        spi_write(GPPUB,  0xFF); // set port B pullups on
+
+        // initialise all outputs to 0
+        int i;
+        for (i = 1; i <= 8; i++)
+            pfio_digital_write(i, 0);
+    }
+
+    return 0;
+}
+
+char pfio_deinit(void)
+{
+    close(spi->fd);
+    free(spi);
+    return 0;
+}
+
+char pfio_digital_read(char pin_number)
+{
+    char current_pin_values = pfio_read_input();
+    char pin_bit_mask = pfio_get_pin_bit_mask(pin_number);
+    return (current_pin_values & pin_bit_mask) > 0;
+}
+
+void pfio_digital_write(char pin_number, char value)
+{
+    char pin_bit_mask = pfio_get_pin_bit_mask(pin_number);
+    char old_pin_values = pfio_read_output();
+
+    char new_pin_values;
+    if (value > 0)
+        new_pin_values = old_pin_values | pin_bit_mask;
+    else
+        new_pin_values = old_pin_values & ~pin_bit_mask;
+
+#ifdef VERBOSE_MODE
+    printf("digital_write: pin number %d, value %d\n", pin_number, value);
+    printf("pin bit mask: 0x%x\n", pin_bit_mask);
+    printf("old pin values: 0x%x\n", old_pin_values);
+    printf("new pin values: 0x%x\n", new_pin_values);
+    printf("\n");
+#endif
+
+    pfio_write_output(new_pin_values);
+}
+
+char pfio_read_input(void)
+{
+    return spi_read(INPUT_PORT);
+}
+
+char pfio_read_output(void)
+{
+    return spi_read(OUTPUT_PORT);
+}
+
+void pfio_write_output(char value)
+{
+    spi_write(OUTPUT_PORT, value);
+}
+
+char pfio_get_pin_bit_mask(char pin_number)
+{
+    return 1 << (pin_number-1);
+}
+
+char pfio_get_pin_number(char bit_pattern)
+{
+    char pin_number = 1; // assume pin 1
+    while ((bit_pattern & 1) == 0)
+    {
+        bit_pattern >>= 1;
+        if (++pin_number > 8)
+        {
+            pin_number = 0;
+            break;
+        }
+    }
+    return pin_number;
+}
+
+
+static void spi_transfer(char * txbuffer, char * rxbuffer)
+{
+    // set up some transfer information
+    struct spi_ioc_transfer transfer_buffer =
+    {
+        .tx_buf = (unsigned long) txbuffer,
+        .rx_buf = (unsigned long) rxbuffer,
+        .len = TRANSFER_LEN,
+        .delay_usecs = TRANSFER_DELAY,
+        .speed_hz = TRANSFER_SPEED,
+        .bits_per_word = TRANSFER_BPW,
+    };
+
+    // actually do the transfer
+    if (ioctl(spi->fd, SPI_IOC_MESSAGE(1), &transfer_buffer) < 1)
+    {
+        fprintf(stderr, "ERROR: Can not send SPI message");
+        perror(0);
+    }
+}
+
+static void spi_write(char port, char value)
+{
+    char txbuffer[] = {SPI_WRITE_CMD, port, value};
+    char rxbuffer[ARRAY_SIZE(txbuffer)];
+    spi_transfer(txbuffer, rxbuffer);
+}
+
+static char spi_read(char port)
+{
+    char txbuffer[] = {SPI_READ_CMD, port, 0xff};
+    char rxbuffer[ARRAY_SIZE(txbuffer)];
+    spi_transfer(txbuffer, rxbuffer);
+    return rxbuffer[2];
+}

data/ext/piface/pfio.h

@@ -0,0 +1,66 @@
+/**
+ * pfio.h
+ * functions for accessing the PiFace add-on for the Raspberry Pi
+ */
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <linux/spi/spidev.h>
+#include <linux/types.h>
+#include <sys/ioctl.h>
+
+// /dev/spidev<BUS>.<DEVICE>
+#define SPI_BUS    0
+#define SPI_DEVICE 0
+#define MAXPATH    16
+
+#define TRANSFER_LEN   3
+#define TRANSFER_DELAY 5
+#define TRANSFER_SPEED 1000000
+#define TRANSFER_BPW   8
+
+#define SPI_WRITE_CMD 0x40
+#define SPI_READ_CMD 0x41
+
+// Port configuration
+#define IODIRA 0x00 // I/O direction A
+#define IODIRB 0x01 // I/O direction B
+#define IOCON  0x0A // I/O config
+#define GPIOA  0x12 // port A
+#define GPIOB  0x13 // port B
+#define GPPUA  0x0C // port A pullups
+#define GPPUB  0x0D // port B pullups
+#define OUTPUT_PORT GPIOA
+#define INPUT_PORT  GPIOB
+
+#define ARRAY_SIZE(a) (sizeof(a) / sizeof((a)[0]))
+
+
+typedef struct
+{
+    int fd;          // open file descriptor: /dev/spi-X.Y
+    int mode;        // current SPI mode
+    int bitsperword; // current SPI bits per word setting
+    int maxspeed;    // current SPI max speed setting in Hz
+} Spi;
+
+typedef enum { false, true } bool;
+
+// extern char pfio_init(void);
+extern char pfio_init(bool setup_pins);
+extern char pfio_deinit(void);
+extern char pfio_digital_read(char pin_number);
+extern void pfio_digital_write(char pin_number, char value);
+extern char pfio_read_input(void);
+extern char pfio_read_output(void);
+extern void pfio_write_output(char value);
+extern char pfio_get_pin_bit_mask(char pin_number);
+extern char pfio_get_pin_number(char bit_mask);
+
+/*
+static void spi_transfer(char * txbuffer, char * rxbuffer);
+static void spi_write(char port, char value);
+static char spi_read(char port);
+*/

data/lib/piface.rb

@@ -24,12 +24,12 @@ module Piface
   end
 
   private
-  def self.init
-    Native.pfio_init
+  def self.init(setup_pins = false)
+    Native.pfio_init(setup_pins)
   end
 
   def self.deinit
-    Native.pfio_init
+    Native.pfio_deinit
   end
 
   def self.pin_number_to_flag(pin_number)

data/lib/piface/native.rb

@@ -3,9 +3,9 @@ require "ffi"
 module Piface
   module Native
     extend FFI::Library
-    ffi_lib ['libpiface', 'libpiface-1.0', 'libpiface-1.0.so', '/usr/local/lib/libpiface-1.0.so']
+    ffi_lib File.expand_path("../pfio.so", __FILE__)
 
-    attach_function :pfio_init, [], :char
+    attach_function :pfio_init, [ :bool ], :char
     attach_function :pfio_deinit, [], :char
 
     attach_function :pfio_digital_read, [ :char ], :char

data/lib/piface/version.rb

@@ -1,3 +1,3 @@
 module Piface
-  VERSION = "0.3.1"
+  VERSION = "0.4"
 end

data/piface.gemspec

@@ -10,16 +10,15 @@ Gem::Specification.new do |spec|
   spec.email         = ["blake.jakopovic@gmail.com"]
   spec.description   = %q{Ruby gem for using PiFace Extension Board (and Raspberry Pi)}
   spec.summary       = %q{Ruby Bindings for the pfio.c C Library for use with the PiFace Digital extension board and your Raspberry Pi}
-  spec.homepage      = "http://twitter.com/blakejakopovic"
+  spec.homepage      = "https://github.com/blakejakopovic/piface"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.extensions    = ['ext/piface/extconf.rb']
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
 
-  spec.add_dependency "ffi", "~> 1.7.dev"
+  spec.add_dependency "ffi", "~> 1.7"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: piface
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: '0.4'
 platform: ruby
 authors:
 - Blake Jakopovic
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-04 00:00:00.000000000 Z
+date: 2013-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -44,19 +44,20 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 1.7.dev
+        version: '1.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 1.7.dev
+        version: '1.7'
 description: Ruby gem for using PiFace Extension Board (and Raspberry Pi)
 email:
 - blake.jakopovic@gmail.com
 executables: []
-extensions: []
+extensions:
+- ext/piface/extconf.rb
 extra_rdoc_files: []
 files:
 - .gitignore
@@ -65,11 +66,18 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/led.rb
+- examples/pir_sensor.rb
+- examples/relay.rb
+- examples/toggle_button.rb
+- ext/piface/extconf.rb
+- ext/piface/pfio.c
+- ext/piface/pfio.h
 - lib/piface.rb
 - lib/piface/native.rb
 - lib/piface/version.rb
 - piface.gemspec
-homepage: http://twitter.com/blakejakopovic
+homepage: https://github.com/blakejakopovic/piface
 licenses:
 - MIT
 metadata: {}