Alert.png

Notice: This page contains information for the legacy Phidget21 Library.

Phidget21 is out of support. Bugfixes may be considered on a case by case basis.

Phidget21 does not support VINT Phidgets, or new USB Phidgets released after 2020. We maintain a selection of legacy devices for sale that are supported in Phidget21.

We recommend that new projects be developed against the Phidget22 Library.


Click on the 2phidget22.jpg button in the menu bar to go to the Phidget22 version of this page.

Alert.png

Language - Ruby: Difference between revisions

From Phidgets Legacy Support
No edit summary
 
(76 intermediate revisions by 6 users not shown)
Line 1: Line 1:
[[Category:Language]]
[[Category:Language]]
[[File:Icon-Ruby.png|64x64px||link=|alt=]]Ruby is an interpreted and object oriented scripting language with simple syntax created by Yukihiro Matsumoto.
{{OSLang|[[File:Icon-Ruby.png|64x64px|link=|alt=]]|Ruby is an interpreted and object oriented scripting language with simple syntax created by [http://en.wikipedia.org/wiki/Yukihiro_Matsumoto Yukihiro Matsumoto].}}


__TOC__
__TOC__
Line 6: Line 6:
==Introduction==
==Introduction==


{{LanguageSupport|Ruby|the complete Phidget API, including events|all Phidget devices.|Linux and Mac OS X|}}
{{LanguageSupport|Ruby|the complete Phidget API, including events|all Phidget devices.|Linux and OS X|}}


==Quick Downloads==
==Quick Downloads==


Just need the Ruby documentation, drivers, libraries, and examples?  Here they are:
{{QuickDownloads|Ruby|
{{APIQuickDownloads|http://www.rubydoc.info/gems/phidgets-ffi/frames RubyDoc}}|
{{ExampleQuickDownloads|http://rubygems.org/gems/phidgets-ffi| (on RubyGems Server)}}|
{{ExtraLibraryQuickDownloads|http://rubygems.org/gems/phidgets-ffi|Ruby| (on RubyGems Server)}}
{{MacQuickDownloads}}
{{LinuxQuickDownloads}}}}


API Documentation:
===3rd Party Library===
*[http://www.phidgets.com/documentation/rubydoc API Manual]
The following library was submitted by a user and is an alternative means for using Phidgets in Ruby. It is only suitable for the Spatial, GPS, Interface Kit, and Advanced Servo product lines but more may follow.


Library and Example Code:
*[https://github.com/brighton36/phidgets_native Link]


*[http://www.phidgets.com/downloads/examples/rubylib_2.1.8.0.html phidgets-ffi @ RubyGems]
Please note that this is not Phidgets' official library and we take no responsibility for issues stemming from its use nor are we able to support the library ourselves. We are merely making this available for users who wish for an alternative to our own libraries.
 
Drivers:
*[http://www.phidgets.com/downloads/libraries/libphidget_2.1.8.20111028.tar.gz Linux Source]
*[http://www.phidgets.com/downloads/libraries/Phidget_2.1.8.20111103.dmg General Mac OS X Drivers Installer]


==Getting started with Ruby==
==Getting started with Ruby==
Line 28: Line 29:
{{ExampleCodeReasons}}
{{ExampleCodeReasons}}


Instructions are divided up by operating system. Choose:
Instructions for OS X and Linux are similar, so they are combined [[#OS X and Linux|into the same section]].
*[[#Windows(2000/XP/Vista/7)|Windows 2000 / XP / Vista / 7]]
'''Although Ruby can run on Windows, we do not offer official support for the Phidgets libraries using Ruby on Windows.'''
*[[#Mac OS X |Mac OS X]]
*[[#Linux | Linux]] (including PhidgetSBC)


==Windows(2000/XP/Vista/7)==
==OS X and Linux==


===Description of Library Files===
Here, we walk you through installing the libraries both on your operating system and within Ruby, and then we walk through examples and writing code from scratch.
C# programs on Windows depend on the following files, which the installers above put onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidgets library, which is used at run-time.  By default, it is placed in {{Code|C:\Windows\System32}}.
You will also need one of the following two files, depending on the .NET framework version you are targeting:
* <b>{{Code|/lib}}</b> is the Phidgets library for .NET framework <i><b>2.0</b></i> or higher. Your compiler has to know where this file is. By default, it is placed into {{Code|C:\Program Files\Phidgets}}. You can either point your compiler to that location, or copy and link to it in a directory for your project workspace.
* <b>{{Code|examples}}</b> is the Phidgets library for .NET framework <i><b>1.1</b></i>. Your compiler has to know where this file is. By default, is is placed into {{Code|C:\Program Files\Phidgets}}. You can either point your compiler to that location, or copy and link to it in a directory for your project workspace.  


If you do not want to use our installer, you can download the five [http://www.phidgets.com/downloads/libraries/Phidget21-windevel_2.1.8.20111220.zip file files].
===Install the Phidget drivers and libraries===


The first step in using Ruby on OS X or Linux is to install the Phidget libraries.  The best way to do this is to go through the ''Getting Started'' guide for your device. This guide can be found in the [[:Category:UserGuide|user guide]].


Running the examples and writing your own code can be fairly compiler-specific, so we include instructions for each compiler below.
This process of installing will put the Phidget libraries on your system. Ruby programs on OS X and Linux depend on the following files from the Phidget libraries:


===Visual Studio 2005/2008/2010===
If you are using OS X:
* <b>{{Code|Phidget21.framework}}</b> contains the actual Phidgets library for OS X, which is used at run-time. 


Microsoft makes free versions of Visual Studio available known as Express Editions.  The Express editions are suitable for most applications, but are limited in features for more complex applications. Please see [http://www.microsoft.com/visualstudio Microsoft Visual Studio] for more information.
If you are using Linuxe:
* <b>{{Code|libphidget21.so}}</b> contains the actual Phidgets library for Linux, which is used at run-time.
 
===Install phidgets-ffi===
 
For both OS X and Linux, you will need the ffi and phidgets-ffi Ruby gems to run Phidgets.  This requires that you have RubyGems set up so that you can download and install gems (i.e. third-party software) to plug into Ruby and use.  The phidgets-ffi gem contains the Ruby library for Phidgets, and Phidgets example code.
 
For more information, please see phidgets-ffi at [http://rubygems.org/gems/phidgets-ffi RubyGems] and [https://github.com/kreynolds/phidgets-ffi GitHub].
 
Both Ruby and RubyGems are part of the Debian Linux repository.  Both Ruby and RubyGems are a part of Mac OS X 10.5 and higher.
 
RubyGems will give you the command line program {{Code|gem}}.  This is the program you can use to install the phidgets-ffi and ffi gems.  First use it to install the [http://rubygems.org/gems/ffi ffi gem]:
 
<div class="source">
<syntaxhighlight lang=bash>
  gem install ffi
</syntaxhighlight>
</div>


=====Use Our Examples=====
Note that this should be run using '''{{Code|sudo}}''' on Linux.  A version of ffi 1.0.9 or greater is needed. Next, please install the phidgets-ffi gem by typing the following into the command line:


Please start by downloading the [http://www.phidgets.com/downloads/examples/CSharp_2.1.8.20110615.zip examples] and unpack them into a foler.  While these examples were written in Visual Studio 2005 and 2008, Visual Studio 2010 will easily open and upgrade them. To load all projects in Visual Studio, go to File &rarr; Open &rarr; Project, and open {{Code|AllExamples/AllExamples.sln}} or {{Code|AllExamples/AllExamples_vs2008.sln}} for Visual Studio 2005 and 2008, respectively.
<div class="source">
<syntaxhighlight lang=bash>
  gem install phidgets-ffi
</syntaxhighlight>
</div>


If you are opening the Phidget examples in Visual Studio 2010, you will need to go through the Visual Studio Conversion Wizard to convert the 2005 or 2008 project.  
Note that this should be run using '''{{Code|sudo}}''' on Linux.  For OS X systems, the gem will be installed into {{Code|/Library/Ruby/Gems/1.x/phidgets-ffi-x.x.x}}.  For typical Linux systems, the gem will be installed into {{Code|var/lib/gems/1.x/gems/phidgets-ffi-x.x.x}}.
[[File:VS2005 Conversion Wizard.PNG|link=|alt=Conversion Wizard]]


This will load all of the examples available for C#, and then you can set your main project to be the one that matches your device.  If you aren't sure what the software example for your device is called, check the software object listed in the [[Device List | Getting Started guide for your device]].
===Use Our Examples===


The only thing left to do is to run the examples! Click on Debug &rarr; Start Debugging. Please note that the projects, by default try to find the {{Code|Phidget21.NET.dll}} in the {{Code|C:\Program Files\Phidgets}}. If you have it installed in another location, please change the path to the file's location accordingly. If you are receiving an error message regarding that the namespace Phidgets cannot be found, please re-add the reference to {{Code|Phidget21.NET.dll}}. Please see the [[#Write Your Own Code | Write Your Own Code ]] section for details.
Open a command line terminal and navigate to the phidgets-ffi gem directory. {{Code|cd}} into the {{Code|examples}} folder. Here, you will find all of the examples available for Ruby, including a Hello World example that will work with any Phidget.  You will also find source code examples specifically designed for each Phidget.  {{FindYourDevice}}


[[File:CSharp VS2005 Run.PNG|link=|alt=Run‎]]
The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} Ruby example.


Once you have the C# examples running, we have a [[#Follow the Examples|teaching]] section below to help you follow them.
The only thing left to do is to run the examples! Type the following into command line:


=====Write Your Own Code=====
<div class="source">
<syntaxhighlight lang=bash>
  ruby HelloWorld.rb
</syntaxhighlight>
</div>


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 C# libraries. To begin:
Note that, on Linux, unless you have your [[OS_-_Linux#Setting_udev_Rules|udev rules set]], you will need to run Phidgets programs using '''{{Code|sudo}}'''.


1. Generate a new Visual C# Windows Applications project with a descriptive name such as PhidgetTest.  
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:


[[File:CSharp VS2005 New Project.PNG|link=|alt=New Project]]
[[File:Ruby Linux HelloWorld Output.PNG|link=|alt=HelloWorld Output]]


2. Add a reference to the .NET Phidgets library.
After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}


[[File:CSharp VS2005 Add Reference.PNG|link=|alt=Add Reference]]
Once you have the Ruby examples running, we have a [[#Follow the Examples|teaching]] section below to help you follow them.


3. Under the .NET tab, select {{Code|Phidget21.NET.dll}}.
===Write Your Own Code===
If you used our installer, these files are installed in {{Code|C:\Program Files\Phidgets}}, by default. If it does not appear in this list, then you can browse to the Phidget Framework installation directory and add the file.


[[File:CSharp VS2005 Add Reference 2.PNG|link=|alt=Add Reference]]
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.


4. Then, in your code, you will need to include the Phidget library:
Simply, add the following two lines to the beginning of any {{Code|.rb}} script to make use of the phidgets-ffi gem


<div class="source">
<div class="source">
<syntaxhighlight lang=csharp>
<syntaxhighlight lang=ruby>
   using Phidgets;
   require 'rubygems'
   using Phidgets.Events;
   require 'phidgets-ffi'
</syntaxhighlight>
</syntaxhighlight>
</div>
</div>


The project now has access to the Phidget21 function calls and you are ready to begin coding.
The project now has access to the Phidget21 function calls and you are ready to begin coding.
Line 97: Line 115:
The same [[#Follow the Examples|teaching ]] section which describes the examples also has further resources for programming your Phidget.
The same [[#Follow the Examples|teaching ]] section which describes the examples also has further resources for programming your Phidget.


===Visual Studio 2003===
==Follow the Examples==


=====Use Our 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.


1. Download the [http://www.phidgets.com/downloads/examples/CSharp_2.1.8.20110615.zip examples] and unpack them into a folder. Here, you can find example programs for all the devices. If you are not sure what the software example for your device is called, check the software object listed in the [[Device List | Getting Started guide for your device]]. As the examples were written in newer versions of Visual Studio, Visual Studio 2003 is not able to open the examples. Fortunately, you can import the simple examples to a Visual Studio 2003 project. It will be difficult to import the full examples as you will need to recreate the GUI components. In the [[#Use Our Examples 2 | Use Our Examples]] section, it will be assumed that the simple examples are used. You will need this example source code to be copied into your C# project later on.
Your main reference for writing Ruby code will be our Ruby API information, with syntax for all of our functions:


2. Next, a new project will need to be created. Generate a new Visual C# console application project with a descriptive name such as PhidgetTest.
{{UsingAPhidgetInCodeGeneral|both of which are available in Ruby|[http://www.rubydoc.info/gems/phidgets-ffi/frames Ruby API]}}


[[File:CSharp_VS2003 New Project.PNG|link=|alt=New Project]]
===Example Flow===


3. Add a reference to the .NET Phidgets library.
{{ExamplePseudocode|In Ruby, you catch these events thrown by Phidgets (on a sensor data change, for example) by using the '''do''' command.  There are many events for each Phidget, such as device.on_attach, where device is your Interface Kit, Temperature Sensor, etc, etc.  <br>
Some event functions will be common to all Phidgets (attach and detach), and some 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.
|Creating a Phidget software object in Ruby is specific to the Phidget. For a Phidget Spatial, for example, this would involve creating a {{Code|Spatial}} object.  The examples show how to do this and other API functions.<br><br>
The object provides device specific methods and properties which are available from the API for your specific Phidget.|
[http://www.rubydoc.info/gems/phidgets-ffi/frames Ruby API]}}
 
===Code Snippets===


[[File:CSharp_VS2003 Add Reference 1.PNG|link=|alt=Add Reference]]
Specific calls in Ruby will differ in syntax from those on the [[General Phidget Programming]] page, but the concepts stay the same. 


4. Under the .NET tab, select {{Code|Phidget21.NET1.1.dll}}. If you used our installer, by default, this file is placed in {{Code|C:\Program Files\Phidgets}}. If it is in another location, please change the path to the file's location accordingly.  
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.


[[File:CSharp_VS2003 Add Reference 2.PNG|link=|alt=Add Reference]]
For example, if we were using a [{{SERVER}}/products.php?product_id=1018 Phidget Interface Kit] as our device, our code snippets would look something like those shown here.


5. To import the simple example program into your project, please: open up {{Code|Class1.cs}}.
====Step One: Initialize and Open====


6. Traverse to the example in Windows Explorer and locate the {{Code|Program.cs}} file.
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.  


[[File:CSharp VS2003 Source Code.PNG|link=|alt=Source Code]]
=====Block Programming=====


7. Copy and paste the contents from that file into {{Code|Class1.cs}}.
To initialize and open a Phidget with a block of code following, for example, use this structure:


8. Comment out the following line as it is not supported in .NET 1.1:
<div class="source">
<div class="source">
<syntaxhighlight lang=csharp>
<syntaxhighlight lang=ruby>
   using System.Collections.Generic;
   Phidgets::InterfaceKit.new do |device|
    ..
  end
</syntaxhighlight>
</syntaxhighlight>
</div>
</div>


[[File:CSharp VS2003 Source Code 2.PNG|link=|alt=Source Code]]
Note that with block programming, the block between '''do....end''' is your entire program. As described in detail in the [[#Step Two: Wait for Attachment (plugging in) of the Phidget|next code snippet]], a block of code will automatically wait for the Phidget to finish opening and attaching, and will automatically call close on the Phidget at the end of the block.  
 
9. Now, you can run the example. Click on Debug &rarr; Start.
 
[[File:CSharp VS2003 Run.PNG|link=|alt=Run]]
 
Once you have the C# examples running, we have a [[#Follow the Examples|teaching ]] section below to help you follow them.


=====Write Your Own Code=====
=====Non Block Programming=====


When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget C# libraries. Please see the [[#Use Our Examples 2 | Use Our Examples ]] section for instructions.
To simply create and open a Phidget of a certain type - in this case an Interface Kit - use this structure:


Then, in your code, you will need to include the Phidget library:
<div class="source">
<div class="source">
<syntaxhighlight lang=csharp>
<syntaxhighlight lang=ruby>
   using Phidgets;
   device = Phidgets::InterfaceKit.new
  using Phidgets.Events;
</syntaxhighlight>
</syntaxhighlight>
</div>
</div>


The project now has access to the Phidget21 function calls and you are ready to begin coding.
The object name for any type of Phidget is listed in the API manual. Here we use the Phidget Interface Kit (the Phidget with digital inputs, outputs, and analog sensor ports), but if you have a different Phidget like a Motor Controller, or a Temperature Sensor, or a Spatial, you would use the software object for your specific Phidget.  Every type of Phidget also inherits functionality from the Phidget base class.  


The same [[#Follow the Examples|teaching]] section which describes the examples also has further resources for programming your Phidget.
=====Options for Open=====


===Mono===
Options can be added to the Open constructor to connect to the first Phidget (of a certain type) that it finds, based on its serial number, label, or even connect across the network. [http://rubydoc.info/gems/phidgets-ffi/0.1.1/frames Rubydocs API documentation] lists all of the available modes that the constructor provides.


This section will provide instructions on how to compile using the {{Code|mcs}} compiler. Other compilers such as {{Code|gmcs}}, {{Code|smcs}}, and {{Code|dmcs}} all work in the same way. Start by downloading the C# Examples.
For example, the following will try to connect to the first Phidget it finds:


=====Use Our Examples=====
Download the [http://www.phidgets.com/downloads/examples/CSharp_2.1.8.20110615.zip examples] and unpack them into a folder. Here, you can find example programs for all the devices. If you aren't sure what the software example for your device is called, check the software object listed in the [[Device List | Getting Started guide for your device]]. Please only use the simple examples. The full examples uses Windows Forms, which Mono and the Gtk# toolkit are not completely compatible with. Locate the {{Code|Program.cs}} file as this contains the example source code. Copy the file into your working directory, and rename it to {{Code|example.cs}}.
<br/>
To compile and build an executable, run:
<div class="source">
<div class="source">
<syntaxhighlight lang=bash>
<syntaxhighlight lang=ruby>
mcs /out:example.exe /lib:"C:\Program Files\Phidgets" /r:phidget21.NET.dll example.cs
  device= Phidgets::InterfaceKit.new
</syntaxhighlight>
</syntaxhighlight>
</div>
</div>


If you have the {{Code|Phidget21.NET.dll}} installed in another location, please change the path to the file's location accordingly.
The following will try to connect to a Phidget over the Phidget WebService with a serial number of {{Code|99999}}, and a server id of {{Code|myserver}}:  
 
Afterwards, you will have an executable named {{Code|example.exe}} that you can run. Place the {{Code|Phidget21.NET.dll}} in the same directory as the executable and type the following to run the program:
<div class="source">
<div class="source">
<syntaxhighlight lang=bash>
<syntaxhighlight lang=ruby>
mono example.exe
  options = {:serial_number => 99999, :server_id => ‘myserver’, :password => nil}
  device= Phidgets::InterfaceKit.new(options)
</syntaxhighlight>
</syntaxhighlight>
</div>
</div>


Once you have the C# examples running, we have a [[#Follow the Examples|teaching]] section below to help you follow them.
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]].
 
{{Code|Phidgets::InterfaceKit.new}} will tell the program to continuously try to connect to a Phidget, based on the options given (if any), and will even try to reconnect if it gets disconnected.  


=====Write Your Own Code=====
====Step Two: Wait for Attachment (plugging in) of the Phidget====  


When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget C# libraries. Please see the [[#Use Our Examples 3 | Use Our Example ]] section for instructions.
To use the Phidget, it must be plugged in (attached).  Like the create ("new") call above, there are blocking and non-blocking methods of detecting and handling attachment.  Attachment in software must be handled for all Phidgets. We can handle it by using event driven programming and tracking the {{Code|on_attach}} and {{Code|on_detach}} events, or by calling: {{Code|wait_for_attachment}}.


In your code, you will need to include the Phidget library:
=====Block Programming=====
 
If you are programming inside a block, {{Code|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 finished.


<div class="source">
<div class="source">
<syntaxhighlight lang=csharp>
<syntaxhighlight lang=ruby>
   using Phidgets;
   options = {:timeout => 2000)
   using Phidgets.Events;
   Phidgets::InterfaceKit.new(options) do |device|
    ...  
  end
</syntaxhighlight>
</syntaxhighlight>
</div>
</div>


=====Non Block Programming=====


The project now has access to the Phidget21 function calls and you are ready to begin coding.
For the non block programming method, simply calling the constructor does not guarantee you can use the Phidget immediately. The {{Code|wait_for_attachment}} call will block indefinitely until a connection is made to the Phidget, or an optional timeout is exceeded.


The same [[#Follow the Examples|teaching]] section which describes the examples also has further resources for programming your Phidget.
<div class="source">
<syntaxhighlight lang=ruby>
  device= Phidgets::InterfaceKit.new
  device.wait_for_attachment 2000 #halt the program for up 2000 milliseconds or until the Phidget is connected
</syntaxhighlight>
</div>


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


=====Use Our Examples=====
<div class="source">
<syntaxhighlight lang=ruby>
  device.close
</syntaxhighlight>
</div>


Download the [http://www.phidgets.com/downloads/examples/CSharp_2.1.8.20110615.zip examples] and unpack them into a folder. Here, you can find example programs for all the devices. These examples were written in Visual Studio 2005 and 2008, but are also compatible with MonoDevelop.
=====Event Programming=====


To load all projects in MonoDevelop, go to File &rarr; Open, and open {{Code|AllExamples/AllExamples.sln}}
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, you would use the non-blocking method of creating and opening the Phidget ("new"), and use an event driven function to handle the attach event when thrown. An event-driven code snippet to handle the attachment might look something like this:


This will load all of the examples available for C#, and then you can set your main project to be the one that matches your device.  If you aren't sure what the software example for your device is called, check the software object listed in the [[Device List | Getting Started guide for your device]]. If you are running under the .NET framework, you can use either the full or simple examples. Otherwise, if you are running under the Mono framework, please only use the simple examples. The full examples uses Windows Forms, which is not completely compatible with Mono's Gtk#.
<div class="source">
<syntaxhighlight lang=ruby>
  device.on_attach do |device, obj|
    puts "Id: #{device.id}"
    puts "Serial number: #{device.serial_number}"
  end
</syntaxhighlight>
</div>


[[File:CSharp MonoDevelop Win Start Up.PNG|link=|alt=Start Up Project]]
====Step Three: Do Things with the Phidget====


The only thing left to do is to run the examples! Right click the project, and click on {{Code|Run With}} and select the target framework. Please note that the projects, by default try to find the {{Code|Phidget21.NET.dll}} in the {{Code|C\Program Files\Phidgets}}. If you have it installed in another location, please change the path to the file's location accordingly. If you are receiving an error message regarding that the namespace Phidgets cannot be found, please re-add the reference to {{Code|Phidget21.NET.dll}}. Please see the [[#Write Your Own Code 4 | Write Your Own Code]] section for details.  
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.


[[File:CSharp MonoDevelop Win Run As.PNG|link=|alt=Run As]]
For our [{{SERVER}}/products.php?product_id=1018 Phidget Interface Kit], the polling method of getting the current sensor state and setting an output state looks something like this:


Once you have the C# examples running, we have a [[#Follow the Examples|teaching]] section below to help you follow them.
<div class="source">
<syntaxhighlight lang=ruby>


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


When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your  development environment to properly link the Phidget C# libraries. To begin:
# Set digital output port 0 to be on
device.outputs[0].state = true


1. Create a new C# empty project with a descriptive name such as PhidgetTest.
</syntaxhighlight>
</div>


[[File:CSharp MonoDevelop Win New Project.PNG|link=|alt=New Project]]
To catch data changes via events, you would use something like this:


2. Add a reference to the .NET library.
<div class="source">
 
<syntaxhighlight lang=ruby>
[[File:CSharp MonoDevelop Win Reference.PNG|link=|alt=Add Reference]]
  device.on_sensor_change do |device, input, value, obj|
    puts "Sensor #{input.index}'s value has changed to #{value}"
  end
</syntaxhighlight>
</div>


3. Select {{Code|Phidget21.NET.dll}}. If you used our installer, by default, this file is placed in {{Code|C:\Program Files\Phidgets}}. If it is in another location, please change the path to the file's location accordingly.
====Step Four: Close====
 
[[File:CSharp MonoDevelop Win Reference 2.PNG|link=|alt=Add Reference]]
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 ensure that the Phidget is closed. At the end of your program, call {{Code|close}} to free any locks on the Phidget that the Phidget constructor call put in place!
 
4. Then, in your code, you will need to include the Phidget library:


<div class="source">
<div class="source">
<syntaxhighlight lang=csharp>
<syntaxhighlight lang=ruby>
   using Phidgets;
   device.close
  using Phidgets.Events;
</syntaxhighlight>
</syntaxhighlight>
</div>
</div>


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


The same [[#Follow the Examples|teaching]] section which describes the examples also has further resources for programming your Phidget.
The ''complete'' set of functions you have available for all Phidgets can be found in the [http://rubydoc.info/gems/phidgets-ffi/0.1.1/frames Ruby API]. You can also find more description on any device-specific function in the Device API page for your specific Phidget, which can be found in its [[:Category:UserGuide|user guide]].


==Mac OS X==
====Raw FFI====
 
C# has excellent support on Mac OS X through the Mono framework.
 
The first step in using C# on Mac is to install the Phidget libraries.  Compile and install them as explained on the [[Device List|getting started guide for your device]].  Then, the [[OS - Mac OS X]] page also describes the different Phidget files, their installed locations, and their roles....
 
==Linux==
 
C# has support on Linux through the Mono framework. 
 
The first step in using C# on Linux is to install the Phidget libraries.  Compile and install them as explained on the main [[OS - Linux | Linux page]].  That Linux page also describes the different Phidget files, their installed locations, and their roles.
 
==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 C# Phidget functions:
 
{{UsingAPhidgetInCodeGeneral|both of which are available in C#|[http://www.phidgets.com/documentation/Phidget21.NET.zip C# API]}}
 
===Example Flow===
 
{{ExamplePseudocode|In C#, 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. <br>
In the example code, the event functions common to all Phidgets are called things like '''AttachHandler()''' and '''DetachHandler()''', etc.<br><br>
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.
|Creating a Phidget software object in C# is specific to the Phidget.  For a Phidget Spatial, for example, this would involve creating a {{Code|Spatial}} object.  The examples show how to do this and other API functions.<br><br>
The object provides device specific methods and properties which are available from the API for your specific Phidget.|
[http://www.phidgets.com/documentation/Phidget21.NET.zip C# API]}}


==Code Snippets==
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 {{Code|Ruby Gems Directory/phidgets-ffi-x.x.x/lib/phidgets-ffi/ffi}} to see a list of available methods, and the [{{SERVER}}/documentation/Phidget21_C_Doc.zip C API] for usage. There are raw ffi examples in {{Code|Ruby Gems directory/phidgets-ffi-x.x.x/examples/raw-ffi}}.


==Common Problems and Solutions/Workarounds==
==Common Problems and Solutions/Workarounds==


Here you can put various frequent problems and our recommended solutions.
None at this time.

Latest revision as of 13:43, 8 June 2017

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.

Quick Downloads

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

Documentation

Example Code

Libraries and Drivers

3rd Party Library

The following library was submitted by a user and is an alternative means for using Phidgets in Ruby. It is only suitable for the Spatial, GPS, Interface Kit, and Advanced Servo product lines but more may follow.

Please note that this is not Phidgets' official library and we take no responsibility for issues stemming from its use nor are we able to support the library ourselves. We are merely making this available for users who wish for an alternative to our own libraries.

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 are combined into the same section. Although Ruby can run on Windows, we do not offer official support for the Phidgets libraries using Ruby on Windows.

OS X and Linux

Here, we walk you through installing the libraries both on your operating system and within Ruby, and then we walk through examples and writing code from scratch.

Install the Phidget drivers and libraries

The first step in using Ruby on OS X or Linux is to install the Phidget libraries. The best way to do this is to go through the Getting Started guide for your device. This guide can be found in the user guide.

This process of installing will put the Phidget libraries on your system. Ruby programs on OS X and Linux depend on the following files from the Phidget libraries:

If you are using OS X:

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

If you are using Linuxe:

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

Install phidgets-ffi

For both OS X and Linux, you will need the ffi and phidgets-ffi Ruby gems to run Phidgets. This requires that you have RubyGems set up so that you can download and install gems (i.e. third-party software) to plug into Ruby and use. The phidgets-ffi gem contains the Ruby library for Phidgets, and Phidgets example code.

For more information, please see phidgets-ffi at RubyGems and GitHub.

Both Ruby and RubyGems are part of the Debian Linux repository. Both Ruby and RubyGems are a part of Mac OS X 10.5 and higher.

RubyGems will give you the command line program gem. This is the program you can use to install the phidgets-ffi and ffi gems. First use it to install the ffi gem:

  gem install ffi

Note that this should be run using sudo on Linux. A version of ffi 1.0.9 or greater is needed. Next, please install the phidgets-ffi gem by typing the following into the command line:

  gem install phidgets-ffi

Note that this should be run using sudo on Linux. 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.x/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, including a Hello World example that will work with any Phidget. You will also find source code examples specifically designed for each Phidget. The source file will be named the same as the software object for your device. If you are not sure what the software object for your device is, find your Phidget on our webpage, and then check the API documentation for it.

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

Note that, on Linux, unless you have your udev rules set, you will need to run Phidgets programs using sudo.

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:

HelloWorld Output

After confirming that the HelloWorld example is working, you can proceed to run the example for your device. The source file will be named the same as the software object for your device. If you are not sure what the software object for your device is, find your Phidget on our webpage, and then check the API documentation for it.

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.

Your main reference for writing Ruby code will be our Ruby API information, with syntax for all of our 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 catch these events thrown by Phidgets (on a sensor data change, for example) by using the do command. There are many events for each Phidget, such as device.on_attach, where device is your Interface Kit, Temperature Sensor, etc, etc.
Some event functions will be common to all Phidgets (attach and detach), and some 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.

// ----- 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, our code snippets would look something like those shown here.

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.

Block Programming

To initialize and open a Phidget with a block of code following, for example, use this structure:

  Phidgets::InterfaceKit.new do |device|
    ..
  end

Note that with block programming, the block between do....end is your entire program. As described in detail in the next code snippet, a block of code will automatically wait for the Phidget to finish opening and attaching, and will automatically call close on the Phidget at the end of the block.

Non Block Programming

To simply create and open a Phidget of a certain type - in this case an Interface Kit - use this structure:

  device = Phidgets::InterfaceKit.new

The object name for any type of Phidget is listed in the API manual. Here we use the Phidget Interface Kit (the Phidget with digital inputs, outputs, and analog sensor ports), but if you have a different Phidget like a Motor Controller, or a Temperature Sensor, or a Spatial, you would use the software object for your specific Phidget. Every type of Phidget also inherits functionality from the Phidget base class.

Options for Open

Options can be added to the Open constructor to connect to the first Phidget (of a certain type) that 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), and will even try to reconnect if it gets disconnected.

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

To use the Phidget, it must be plugged in (attached). Like the create ("new") call above, there are blocking and non-blocking methods of detecting and handling attachment. Attachment in software must be handled for all Phidgets. We can handle it by using event driven programming and tracking the on_attach and on_detach events, or by calling: wait_for_attachment.

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 finished.

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

For the non block programming method, simply calling the constructor does not guarantee you can use the Phidget immediately. The wait_for_attachment call 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
Event Programming

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, you would use the non-blocking method of creating and opening the Phidget ("new"), and use an event driven function to handle the attach event when thrown. 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 ensure that the Phidget is closed. At the end of your program, call close to free any locks on the Phidget that the Phidget constructor call put in place!

  device.close

More How-To's

The General Phidget Programming page gives more information about:

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 in the Device API page for your specific Phidget, which can be found in its user guide.

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 C API for usage. There are raw ffi examples in Ruby Gems directory/phidgets-ffi-x.x.x/examples/raw-ffi.

Common Problems and Solutions/Workarounds

None at this time.