Language - Ruby

Ruby is an interpreted and object oriented scripting language with simple syntax created by Yukihiro Matsumoto.

Introduction

If this is your first time working with a Phidget, we suggest starting with the Getting Started page for your specific device. This can be found in the user guide for your device. That page will walk you through installing drivers and libraries for your operating system, and will then bring you back here to use Ruby specifically.

Ruby is capable of using the complete Phidget API, including events. We also provide example code in Ruby for all Phidget devices.

Ruby can be developed with Linux and OS X.

You can compare Ruby with our other supported languages.

Just need the Ruby documentation, drivers, libraries, and examples? Here they are:

Documentation

• RubyDoc API Manual

Example Code

• Example Code (@RubyGems)

Libraries and Drivers

• Ruby Libraries (@RubyGems)
• OS X Drivers Installer
• Linux Libraries (Source Code)

Getting started with Ruby

If you are new to writing code for Phidgets, we recommend starting by running, then modifying existing examples. This will allow you to:

• Make sure your libraries are properly linked
• Go from source code to a test application as quickly as possible
• Ensure your Phidget is hooked up properly

Instructions for OS X and Linux are similar, so they will be combined into the same section.

The first step in using Ruby on Mac or Linux is to install the Phidget libraries. Compile and install them as explained on the getting started guide for your device.

The next step is to install the phidgets-ffi gem. This is the library that allows you to program Phidgets with Ruby. For more information, please see phidgets-ffi at RubyGems and GitHub.

Description of Library Files

Ruby programs on OS X and Linux depend on the following files, which the installers put into your system.

If you are using OS X, you will need the:

• Phidget21.framework contains the actual Phidgets library for OS X, which is used at run-time.

If you are using Linux, you will need the:

• libphidget21.so contains the actual Phidgets library for Linux, which is used at run-time.

For both OS X and Linux, you will need the phidgets-ffi gem:

• phidgets-ffi is the Phidgets gem for Ruby. This gem contains the library as well as example code.

Installing phidgets-ffi

The phidgets-ffi gem relies on the ffi gem. So, if you do not already have it installed, please do so. A version of ffi 1.0.9 or greater is needed. Type the following to install ffi:

  gem install ffi

Next, please install the phidgets-ffi gem by typing the following into command line:

  gem install phidgets-ffi

For OS X systems, the gem will be installed into /Library/Ruby/Gems/1.x/phidgets-ffi-x.x.x.

For typical Linux systems, the gem will be installed into var/lib/gems/1.9/gems/phidgets-ffi-x.x.x.

Use Our Examples

Open a command line terminal and navigate to the phidgets-ffi gem directory. cd into the examples folder. Here, you will find all of the examples available for Ruby. If you aren't sure what the software example for your device is called, check the software object listed in the Getting Started guide for your device.

The easiest way to confirm that your environment is set up properly will be to compile and run the HelloWorld Ruby example.

The only thing left to do is to run the examples! Type the following into command line:

  ruby HelloWorld.rb

This program will detect for devices that are attached/detached on the computer. Go ahead, and attach or detach your devices! Here is an example output:

After confirming that the HelloWorld example is working, you can proceed to run the example for your device. If you aren't sure what the software example for your device is called, check the software object listed in the Getting Started Guide for your Device. Please ensure that you have set your start up project to be the one that matches your device before compiling.

Once you have the Ruby examples running, we have a teaching section below to help you follow them.

Write Your Own Code

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your environment to properly link the Phidget Ruby libraries.

Simply, add the following two lines to the beginning of any .rb script to make use of the phidgets-ffi gem

  require 'rubygems'
  require 'phidgets-ffi'

The project now has access to the Phidget21 function calls and you are ready to begin coding.

The same teaching section which describes the examples also has further resources for programming your Phidget.

Follow the Examples

By following the instructions for your operating system and compiler above, you probably now have a working example and want to understand it better so you can change it to do what you want. This teaching section has resources for you to learn from the examples and write your own.

Next, comes our API information. These resources outline the Ruby Phidget functions:

• Ruby API (This is the complete set of functions you have available for all Phidgets)
• Device Specific APIs - The one for your Phidget can be found in its user guide.

To learn the details behind opening, configuring, using, and closing your Phidget, try the General Phidget Programming page. That page also describes using the Phidget in an event-driven manner and in a traditional manner, both of which are available in Ruby.

Example Flow

The Hello World example has this general structure so you can follow along. We also have an in-depth general introduction to writing Phidget code (like open, read data, etc), as well as the Ruby API for specific syntax:

// ----- Event and Other Functions ----- Create any Language-Specific Functions (exception handling) Create General Attach, Detach, and Error Handling Functions: On attach: Print Hello Message On detach: Print Goodbye Message		In Ruby, you can name these event functions whatever you like. You will then pass them as function pointers to the Phidget library below in the Main Code section. This hooks them into the actual events when they occur. In the example code, the event functions common to all Phidgets are called things like AttachHandler() and DetachHandler(), etc. Some event functions will be specific to each device, like when a tag is read on an RFID board, or when a sensor value changes on an Interface Kit. Other functions are given in the examples to show you more detail on using your Phidget. For example, DeviceInitialize() will show what needs to be set up for your Phidget before using it.
// ----- Main Code ----- Create Manager Software Object Hook Event Functions created above to Device Open Device Wait for 'Enter' key character input Handle on-going attach and detach events Print Hello and Goodbye messages Exit upon input Close Device Delete Device		Creating a Phidget software object in Ruby is specific to the Phidget. For a Phidget Spatial, for example, this would involve creating a Spatial object. The examples show how to do this and other API functions. The object provides device specific methods and properties which are available from the API for your specific Phidget.

Code Snippets

Specific calls in Ruby will differ in syntax from those on the General Phidget Programming page, but the concepts stay the same.

It may help to have the General Phidget Programming page and this section open at the same time, because they parallel each other and you can refer to the Ruby syntax. However, many additional concepts are covered on the General Phidget Programming page on a high level, such as using multiple Phidgets, handling errors, and different styles of programming.

For example, if we were using a Phidget Interface Kit as our device, the general calls would look like this:

Step One: Initialize and Open

The Phidget constructor method will need to be called to create the Phidget object. There are two methods or programming a Phidget in Ruby: with and without a block.

  # Without a block
    device = Phidgets::InterfaceKit.new

  # With a block
    Phidgets::InterfaceKit.new do |device|
      ..
    end

The object name for any type of Phidget is listed in the API manual. Every type of Phidget also inherits functionality from the Phidget base class. In the above example, InterfaceKit represents the PhidgetInterfaceKit. For simplicity in explaining the programming concepts, the remainder of the code snippet section will use the InterfaceKit object.

For the most part, the two methods behave the same, but there are some subtle differences, which will be explained in the next section.

Step Two: Wait for Attachment (plugging in) of the Phidget

The program needs to try and connect to the Phidget. Options can be added to the InterfaceKit constructor to connect to the first Phidget it finds, based on its serial number, label, or even connect across the network. Rubydocs API Documentation lists all of the available modes that the constructor provides.

For example, the following will try to connect to the first Phidget it finds:

  device= Phidgets::InterfaceKit.new

The following will try to connect to a Phidget over the Phidget WebService with a serial number of 99999, and a server id of myserver:

  options = {:serial_number => 99999, :server_id => ‘myserver’, :password => nil}
  device= Phidgets::InterfaceKit.new(options)

One important thing to remember is that when working with Phidgets, a local connection will reserve the device until closed. This prevents any other instances from retrieving data from the Phidget, including other programs. The one connection per device limit does not apply when exclusively using the Phidget WebService.

Phidgets::InterfaceKit.new will tell the program to continuously try to connect to a Phidget, based on the options given(if any), even trying to reconnect if it gets disconnected.

Non Block Programming

For the non block programming method, simply calling the constructor does not guarantee you can use the Phidget immediately. We can handle this by using event driven programming and tracking the on_attach and on_detach events, or by calling: wait_for_attachment. wait_for_attachment will block indefinitely until a connection is made to the Phidget, or an optional timeout is exceeded.

  device= Phidgets::InterfaceKit.new
  device.wait_for_attachment 2000 #halt the program for up 2000 milliseconds or until the Phidget is connected

Please also remember to call close at the end or the program to free any locks on the Phidget

  device.close

Block Programming

If you are programming inside a block, wait_for_attachment is automatically called. By default, it will halt the program and try to connect to the Phidget for up to 1000 milliseconds. Afterwards, the block will yield. Finally, close is not needed as it is automatically called once the block has yield.

  options = {:timeout => 2000)
  Phidgets::InterfaceKit.new(options) do |device|
    ... 
  end

Sometimes, it makes more sense to handle the attachment via an event. This would be in instances where the Phidget is being plugged and unplugged, and you want to handle these incidents. Or, when you want to use event-driven programming because you have a GUI-driven program. In these cases, an event-driven code snippet to handle the attachment might look something like this:

  device.on_attach  do |device, obj|
    puts "Id: #{device.id}"
    puts "Serial number: #{device.serial_number}"
  end

Step Three: Do Things with the Phidget

You can read data and interact with your Phidget both by polling it for its current state (or to set a state), or by catching events that trigger when the data changes.

For our Phidget Interface Kit, the polling method of getting the current sensor state and setting an output state looks something like this:

# Get a data point from Analog Port 0
puts "Sensor value[0]: #{device.sensors[0].to_i}" 

# Set digital output port 0 to be on
device.outputs[0].state = true

To catch data changes via events, you would use something like this:

  device.on_sensor_change do |device, input, value, obj|
    puts "Sensor #{input.index}'s value has changed to #{value}"
  end

Step Four: Close

If you are using the block programming method, you do not need to worry about closing the Phidget. It is already taken care of when the block ends. However, if you are using the non block programming method, then you will need take special consideration that the Phidget is closed.

At the end of your program, don’t forget to call close to free any locks on the Phidget that the Phidget constructor call put in place!

  device.close

The complete set of functions you have available for all Phidgets can be found in the Ruby API. You can also find more description on any device-specific function either in the Device API page for calls available only on your specific Phidget.

Raw FFI

As an alternative to programming with the method as outlined in this document, you can also program making straight C calls through FFI. Please refer to the files in Ruby Gems Directory/phidgets-ffi-x.x.x/lib/phidgets-ffi/ffi to see a list of available methods, and the [1] for usage. There are raw ffi examples in Ruby Gems directory/phidgets-ffi-x.x.x/examples/raw-ffi.

Common Problems and Solutions/Workarounds

Here you can put various frequent problems and our recommended solutions.