Phidgets Support - User contributions [en]

Software Overview

2012-06-29T21:58:25Z

Cora:

[[Category:Overview]]
__NOTOC__
Phidgets’ philosophy is that you do not have to be an electrical engineer in order to do projects that use devices like sensors, motors, motor controllers, and interface boards. All you need to know is how to program.

We have developed a complete set of Application Programming Interfaces (API) that are supported for many different [[#Operating System Support|operating systems]], and which can be used through many different [[#Language Support | programming languages]].

{| style="border:1px solid darkgray;" cellpadding="5px;"
|-
| We suggest starting with the '''Getting Started''' guide for your device, which can be found on its product page on [{{SERVER}} our main website]. This will help you run a basic example to check your hardware and drivers.
|-
|Have you been there but want more introduction? We have overview pages - with lots of explanatory images - for some of our high-level topics:
|-
|
* [[What is a Phidget?]]
|-
|
* [[Phidget WebService]]
* [[Phidget Manager]]
* [[Phidget Dictionary]]
|}

After that, you'll need to dive right in and write code.

From the Getting Started Guide, you'll have already chosen your [[#Operating System Support|operating system below]], and from the operating system page you'll be directed to [[#Language Support|choose a language]].

So if you're here, you probably want:
* An overview of our language and operating system support (in which case, just scroll down)
* A quick link to our programming overview with lots of code snippets, called the '''[[General Phidget Programming|General Phidget Programming Guide]]'''
* The API with syntax and function calls for your device - which you can find on the [[#Language Support | page for your language]]
* Or, information about your product, which can be found on its product page on [{{SERVER}} our main website].

We try to make our documentation as complete as possible - which means there is a lot of it! Browse around, try the search bar, and if you can't find what you need, please [[Contact Us]].

== Operating System Support ==

These operating system pages provide drivers for using Phidgets. They help you set up your system after following the '''Getting Started''' guide for your device. The operating systems links below are also on every ''Getting Started'' guide, so if you have not yet read the one for your device, head straight to the product page for your device on [{{SERVER}} our main website] where you can find it and follow it.

Phidgets can be run either ''directly'' through USB or ''remotely'' over a network via the [[Phidget WebService]]. Most operating systems below can run Phidgets directly, but a few can only control them over a network. Phidgets can also probably be run on other operating systems that have support for compiling C code, and either a standard network connection for running a Phidget over a network, or a USB host controller for direct control. We don't offer support directly for these additional operating systems, but you may find the installation and setup instructions for [[OS - Linux|Linux]] useful because compiling and custom toolchains are discussed.

Phidgets can run either directly or over a network on these operating systems:

{| style="border:1px solid darkgray;" cellpadding="7px;"
|-style="background: #f0f0f0" align=center
! Operating System || Drivers and Libraries || Direct Control || Remote Network Control || Supported Version
|-

|'''Desktop OSes'''
|-

|[[Image:Icon-Windows.png|alt=OS - Windows|24x24px|link=OS - Windows]][[OS - Windows|Windows]]
|style="background: #f0f0ff" align=center| [[OS - Windows#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
| 2000 or Newer
|-

|[[Image:Icon-Mac-OS.png|alt=OS - OS X|24x24px|link=OS - OS X]][[OS - OS X|OS X]]
|style="background: #f0f0ff" align=center| [[OS - OS X#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
| OS X 10.4 or newer
|-

|[[Image:Icon-Linux.png|alt=OS - Linux|24x24px|link=OS - Linux]][[OS - Linux|Linux]]
|style="background: #f0f0ff" align=center| [[OS - Linux#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
| Kernel 2.6 or newer
|-

|'''Mobile/Wireless OSes'''
|-

|[[Image:Icon-Linux.png|alt=OS - Phidget SBC|24x24px|link=OS - Phidget SBC]][[OS - Phidget SBC|Phidget SBC]]
|style="background: #f0f0ff" align=center| [[OS - Phidget SBC#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
| All versions
|-

|[[Image:Icon-Android_Honeycomb.png|alt=OS - Android|24x24px|link=OS - Android]][[OS - Android|Android]]
|style="background: #f0f0ff" align=center| [[OS - Android#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
| 3.1 and newer, with USB port
|-

|[[Image:Icon-Android.png|alt=OS - Android|link=OS - Android|24x24px|link=OS - Android]][[OS - Android|Android]]
|style="background: #f0f0ff" align=center| [[OS - Android#Quick Downloads|Quick Downloads]]
|style="background: #E28585" align=center| X
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
| 1.5 to 3.0
|-

|[[Image:Icon-iOS.png|alt=OS - iOS|link=OS - iOS|24x24px|link=OS - iOS]][[OS - iOS|iOS]]
|style="background: #f0f0ff" align=center| [[OS - iOS#Quick Downloads|Quick Downloads]]
|style="background: #E28585" align=center| X
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
| 3.0 or newer
|-

|[[Image:Icon-Windows CE.png|alt=OS - Windows CE|24x24px|link=OS - Windows CE]][[OS - Windows CE|Windows CE]]
|style="background: #f0f0ff" align=center| [[OS - Windows CE#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
| 5.0 or newer
|}

== Language Support ==

We provide a variety of supported languages for using Phidgets. Each language has its own ''libraries'', which may be found on the language pages below, along with code examples and an in-depth API.

Many languages also depend on the ''core drivers'' being installed as well. These drivers can be found on the [[#Operating System Support|operating system pages]] above.

Phidgets supports the following languages. If you have some flexibility in what language to use, we recommend using a '''Core Language''':

{| style="border:1px solid darkgray;" cellpadding="7px;"
|-style="background: #f0f0f0" align=center
! Language || Libraries || API || Code Samples<sup>&dagger;</sup> || [[General Phidget Programming#Event Driven Code|Events]] || [[General Phidget Programming#Logic Code|Logic Code]] || Use via Direct USB* || [[Phidget WebService]] || Native Library** || Phidget User Base
|-

|'''Core Languages'''
|-

|[[Image:Icon-CSharp.png|alt=C Sharp|24x24px|link=Language - C Sharp]] [[Language - C Sharp|C#]]
|style="background: #f0f0ff" align=center| [[Language - C Sharp#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-10.png|link=|alt=Extensive]]
|-

|[[Image:Icon-C++.png|alt=C/C++|24x24px|link=Language - C/C++]] [[Language - C/C++|C/C++]]
|style="background: #f0f0ff" align=center| [[Language - C/C++#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-10.png|link=|alt=Extensive]]
|-

|[[Image:Icon-Java.png|alt=Java|24x24px|link=Language - Java]] [[Language - Java|Java]]
|style="background: #f0f0ff" align=center| [[Language - Java#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-10.png|link=|alt=Extensive]]
|-

|[[Image:Icon-Python.png|alt=Python|24x24px|link=Language - Python]] [[Language - Python|Python]]
|style="background: #f0f0ff" align=center| [[Language - Python#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-10.png|link=|alt=Extensive]]
|-

|[[Image:Icon-Cocoa.png|alt=Cocoa|24x24px|link=Language - Cocoa]] [[Language - Cocoa|Cocoa]]
|style="background: #f0f0ff" align=center| [[Language - Cocoa#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-10.png|link=|alt=Extensive]]
|-

|[[Image:Icon-Visual Basic.png|alt=Visual Basic 6.0|24x24px|link=Language - Visual Basic 6.0]] [[Language - Visual Basic 6.0|Visual Basic 6.0]]
|style="background: #f0f0ff" align=center| [[Language - Visual Basic 6.0#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-10.png|link=|alt=Extensive]]
|-

|[[Image:Icon-Visual Basic Net.png|alt=Visual Basic .NET|24x24px|link=Language - Visual Basic .NET]] [[Language - Visual Basic .NET|Visual Basic .NET]]
|style="background: #f0f0ff" align=center| [[Language - Visual Basic .NET#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-10.png|link=|alt=Extensive]]
|-

|'''Mobile Languages'''
|-

|[[Image:Icon-iOS.png|alt=iOS|24x24px|link=Language - iOS]] [[Language - iOS|iOS]]
|style="background: #f0f0ff" align=center| [[Language - iOS#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #EFE973" align=center| InterfaceKit Only
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #E28585" align=center| X
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-06.png|link=|alt=Moderate]]
|-

|[[Image:Icon-Android.png|alt=Android Java|24x24px|link=Language - Android Java]] [[Language - Android Java|Android Java]]
|style="background: #f0f0ff" align=center| [[Language - Android Java#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #EFE973" align=center| InterfaceKit Only
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #E28585" align=center| X
|style="background: #FFC17F" align=center| Some Devices [[Image:Icon-Android_Honeycomb.png|24px|link=Software_Overview#Honeycomb|alt=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-06.png|link=|alt=Moderate]]
|-

|'''Scripting'''
|-

|[[Image:Icon-Applescript.png|alt=Applescript|24x24px|link=Language - Applescript]] [[Language - Applescript|Applescript]]
|style="background: #f0f0ff" align=center| [[Language - Applescript#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-06.png|link=|alt=Moderate]]
|-

|[[Image:Icon-Autoit.png|alt=AutoIt|24x24px|link=Language - AutoIt]] [[Language - AutoIt|AutoIt]]
|style="background: #f0f0ff" align=center| [[Language - AutoIt#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #E28585" align=center| None
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-01.png|link=|alt=Small]]
|-

|[[Image:Icon-Ruby.png|alt=Ruby|24x24px|link=Language - Ruby]] [[Language - Ruby|Ruby]]
|style="background: #f0f0ff" align=center| [[Language - Ruby#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-01.png|link=|alt=Small]]
|-

|'''Science and Math'''
|-

|[[Image:Icon-LabVIEW.png|alt=LabVIEW|24x24px|link=Language - LabVIEW]] [[Language - LabVIEW|LabVIEW]]
|style="background: #f0f0ff" align=center| [[Language - LabVIEW#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-06.png|link=|alt=Moderate]]
|-

|[[Image:Icon-Matlab.png|alt=MATLAB|24x24px|link=Language - MATLAB]] [[Language - MATLAB|MATLAB]]
|style="background: #f0f0ff" align=center| [[Language - MATLAB#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #FFC17F" align=center| Some Devices
|style="background: #E28585" align=center| X
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #E28585" align=center| X
|style="background: #ade6ab" align=center| [[Image:Level-06.png|link=|alt=Moderate]]
|-

|[[Image:Icon-Simulink.png|alt=Simulink|24x24px|link=Language - Simulink]] [[Language - Simulink|Simulink]]
|style="background: #f0f0ff" align=center| [[Language - Simulink#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #EFE973" align=center| InterfaceKit Only
|style="background: #E28585" align=center| X
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #E28585" align=center| X
|style="background: #ade6ab" align=center| [[Image:Level-01.png|link=|alt=Small]]
|-

|'''Multimedia'''
|-

|[[Image:Icon-Adobe Director.png|alt=Adobe Director|24x24px|link=Language - Adobe Director]] [[Language - Adobe Director|Adobe Director]]
|style="background: #f0f0ff" align=center| [[Language - Adobe Director#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| InterfaceKit Only
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-01.png|link=|alt=Small]]
|-

|[[Image:Icon-Flash AS3.png|alt=Flash AS3|24x24px|link=Language - Flash AS3]] [[Language - Flash AS3|Flash AS3]]
|style="background: #f0f0ff" align=center| [[Language - Flash AS3#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-10.png|link=|alt=Extensive]]
|-

|[[Image:Icon-LiveCode.png|alt=LiveCode|24x24px|link=Language - LiveCode]] [[Language - LiveCode|LiveCode]]
|style="background: #f0f0ff" align=center| [[Language - LiveCode#Quick Downloads|Quick Downloads]]
|style="background: #EFE973" align=center| InterfaceKit Only
|style="background: #EFE973" align=center| InterfaceKit Only
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #E28585" align=center| X
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-01.png|link=|alt=Small]]
|-

|[[Image:Icon-MaxMSP.png|24x24px|alt=Max/MSP|link=Language - Max/MSP]] [[Language - Max/MSP|Max/MSP]]
|style="background: #f0f0ff" align=center| [[Language - Max/MSP#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| All Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-06.png|link=|alt=Moderate]]
|-

|'''Other Languages'''
|-

|[[Image:Icon-CSharp.png|24x24px|alt=C Sharp (.NET Compact Framework)|link=Language - C Sharp (.NET Compact Framework)]] [[Language - C Sharp (.NET Compact Framework)|C# (.NET Compact)]]
|style="background: #f0f0ff" align=center| [[Language - C Sharp (.NET Compact Framework)#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #FFC17F" align=center| Some Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-01.png|link=|alt=Small]]
|-

|[[Image:Icon-Visual Basic Net.png|24x24px|alt=Visual Basic (.NET Compact Framework)|link=Visual Basic (.NET Compact Framework)]] [[Language - Visual Basic (.NET Compact Framework)|Visual Basic<br> (.NET Compact Framework)]]
|style="background: #f0f0ff" align=center| [[Language - Visual Basic (.NET Compact Framework)#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #FFC17F" align=center| Some Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-01.png|link=|alt=Small]]
|-

|[[Image:Icon-Visual Basic for Applications.png|alt=Visual Basic for Applications|24x24px|link=Language - Visual Basic for Applications]] [[Language - Visual Basic for Applications|Visual Basic for Apps]]
|style="background: #f0f0ff" align=center| [[Language - Visual Basic for Applications#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #FFC17F" align=center| Some Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-01.png|link=|alt=Small]]
|-

|[[Image:Icon-Visual Basic Script.png|alt=Visual Basic Script|24x24px|link=Language - Visual Basic Script]] [[Language - Visual Basic Script|Visual Basic Script]]
|style="background: #f0f0ff" align=center| [[Language - Visual Basic Script#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #FFC17F" align=center| Some Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-01.png|link=|alt=Small]]
|-

|[[Image:Icon-Delphi.png|alt=Delphi|24x24px|link=Language - Delphi]] [[Language - Delphi|Delphi]]
|style="background: #f0f0ff" align=center| [[Language - Delphi#Quick Downloads|Quick Downloads]]
|style="background: #ade6ab" align=center| All Devices
|style="background: #FFC17F" align=center| Some Devices
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Checkmark.png|link=]]
|style="background: #ade6ab" align=center| [[Image:Level-01.png|link=|alt=Small]]
|-

|}
<nowiki>*</nowiki> A direct USB connection would be plugging the Phidget into a USB port and using it locally. This is the typical way to use a Phidget. However, some platforms (such as the iPhone platform) do not have USB ports and hence can only use a Phidget over a network, via the [[Phidget WebService]].

<nowiki>**</nowiki> Native library support means that the calls you make to a Phidget in this language are in the language as well. If the calls are non-native, the use of Phidgets is through an external library linker, such as callib() in MATLAB, for example. The core Phidget library is written in C, and most other languages use this library as their core, but a 'Native' interface cleanly hides this detail.

<sup>&dagger;</sup> Most languages have code samples for all Phidgets, but some have only some devices (visit the language page to learn which ones), and some only have an Interface Kit example. The Phidget Interface Kit is a common Phidget with provides an interface with analog sensors, digital input, and digital output. So, when we choose which examples to write, the Interface Kit is often at the top of our customer's lists.

<span id="Honeycomb">[[Image:Icon-Android_Honeycomb.png|24px|link=]]</span>Android Honeycomb Version 3.1 or Higher Only

==Third Party Support==

{{GentleAlert|'''These products must be purchased directly from these companies and all support calls must be directed to them'''}}

Some third party companies also offer and support software programs that work with Phidgets boards. Phidgets does not have a certification program and does not make any warranty about these products.

In alphabetical order:

{| style="border:1px solid darkgray;" cellpadding="7px;"
|-style="background: #f0f0f0" align=center
! Company
! Product
! Runs On
! Website
! style="width:50%;" | Synopsis
! Product Information
|-

|'''24U'''
|24U Phidgets Plug-in 1.0
|Mac, Windows
|[http://www.24usoftware.com/plugins.php Website]
|24U Phidgets Plug-In lets you connect different kind of phidgets (www.phidgets.com) to your computer's USB port and interact with them directly from FileMaker Pro.
|[[Image:Pdficon_small.gif|link={{SERVER}}/documentation/ThirdPartyInfo/ThirdPartySoftware/24U.pdf]]
|-

|'''DSPRobotics'''
|Flowstone
|Windows 2000/XP/Vista/7/Embedded
|[http://www.dsprobotics.com/ Website]
|Graphical Programming Language aimed at real-time Digital Signal Processing.(DSP), Robotics and Embedded applications. FlowStone is a drag and drop environment where you combine high-level and low-level modules to build real time applications.
|[[Image:Pdficon_small.gif|link={{SERVER}}/documentation/ThirdPartyInfo/ThirdPartySoftware/FlowStone.pdf]]
|-

|'''MANIPIL'''
|Visual Domotique
|Windows XP/Vista/7
|[http://www.manipil.ch/cms1/vd/tutoriels/setup-and-to-use-a-phidget-module.html Website]
|Visual Domotique is a Graphical I/O programming for Windows XP/Vista/7. Various components allow you to draw electrical schema and control panel. No need to know how to program to use this software. Varied uses are possible: Home automation, security, hobby, Control process education... Available in French.
|[[Image:Pdficon_small.gif|link={{SERVER}}/documentation/ThirdPartyInfo/ThirdPartySoftware/Manipil_en.pdf]]
|-

|'''PCRBOX'''
|PCR Automation
|Windows XP/Vista/7 (32 & 64bit)
|[http://www.pcrbox.com/en/ Website]
|PCR Automation is an easy to use software that works immediately without the need for any programming. It interfaces with the 1018, 1070 and 1072. Several interfaces can be opened simultaneously, each in a different window. Each input / output can be customized (label, sensor, offset, units, sensitivity, recording ...). The log files can be automatically sent by E-mail. Users can add their own sensors to the library of thirty Phidgets sensors.
|[[Image:Pdficon_small.gif|link={{SERVER}}/documentation/ThirdPartyInfo/ThirdPartySoftware/pcr-automation-en.pdf]]
|-

|'''PiXCL Automation Technologies'''
|PiXCL Advanced Imaging 10.2
|Windows XP/Vista/7
|[http://www.pixcl.com/Using_Phidgets_with_PiXCL.htm Website]
|PiXCL is a powerful and easy-to-learn event driven interpreted language for the fast creation of image acquisition, processing and advanced analysis applications. The suite includes a compiler and development studio with context sensitive help and plenty of sample code. V10.1 provides you with the tools to create applications that combine Phidget devices with digital cameras and scanners.
|[[Image:Pdficon_small.gif|link={{SERVER}}/documentation/ThirdPartyInfo/ThirdPartySoftware/PiXCL.pdf]]
|-

|'''SoapBox Automation'''
|SoapBox Snap
|Windows XP/Vista/7
|[http://soapboxautomation.com/products/soapbox-snap/ Website]
|SoapBox Snap is a free and open source PC-based automation platform. It includes a ladder logic editor and a “soft” runtime right out of the box.
|[[Image:Pdficon_small.gif|link={{SERVER}}/documentation/ThirdPartyInfo/ThirdPartySoftware/SoapBox.pdf]]
|-

|'''UACh - Universida Austral de Chile'''
|monoBOTICS-icarus
|Linux
|[http://www.monobotics.ic.uach.cl/ Website]
|The monoBOTICS project aims to become an OpenSource Framework, to facilitate the tasks of design, simulation and implementation of solutions for areas of Robotics and Automation, both for people with basic knowledge of programming, as for more advanced developers.
|[[Image:Pdficon_small.gif|link={{SERVER}}/documentation/ThirdPartyInfo/ThirdPartySoftware/monoBOTICS.pdf]]
|-
|}

==Legacy Languages==

Legacy languages are languages which we supported in the past; however, we no longer actively develop or support them. We provide this software page information for the limited existing users:

{| style="border:1px solid darkgray;" cellpadding="7px;"
|-style="background: #f0f0f0" align=center
! Language

|-
|[[Image:Icon-REALBasic.png|alt=REALBasic|24x24px|link=Language - REALBasic]] [[Language - REALBasic|REALBasic]]
|-

|[[Image:Icon-Flex AS3.png|alt=Flex AS3|24x24px|link=Language - Flex AS3]] [[Language - Flex AS3|Flex AS3]]
|-

|[[Image:Icon-Robot Studio.png|alt=Robotics Studio|24x24px|link=Language - Microsoft Robotics Studio]] [[Language - Microsoft Robotics Studio|Microsoft Robotics Studio]]
|-

|}

If you have an existing code base in these languages and the legacy status of these languages is a serious inconvenience, please [[Contact Us]].

{{CreativeCommons}}

Solid State Relay Guide

2012-06-29T21:55:43Z

Cora:

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[Image:SSR.jpg]]
| [[Image:3052.jpg|200px]]
|}

==Introduction==

[[Image:SSR.jpg|thumb|A "hockey puck" SSR, so named because of its thick shape and black color. They are specifically designed to switch either AC loads or DC loads, but never both.]]

Solid state relays (SSRs) turn on or off the power being supplied to other devices, in a similar fashion as a physical [[Switch Primer|switch]]. However, instead of being switched by human interaction like a physical switch, SSRs are switched electronically.
With SSRs, you can control high-current devices such as lights or appliances with low-current signals, like a standard DC signal from a [[Digital Output Primer|Digital Output]]. Most SSRs will switch on with a voltage of 3V or higher. This makes them perfect for use with Phidget [[Interface Kits]], or any device with a digital output.

SSRs perform the same job as [[Mechanical Relay Primer|Mechanical Relays]], but have the following advantages:
* SSRs produce less electromagnetic interference than mechanical relays during operation. This is mostly due to the absence of a phenomenon called [[Mechanical Relay Primer#Arcing, Interference, and Sticking|contact arcing]] only present in mechanical relays, where the physical contacts of the relay tend to spark internally while switching. The reduced interference can also be attributed to the fact that SSRs do not use electromagnets to switch.
* The switch contacts of a mechanical relay will eventually wear down from arcing. An SSR will have a longer life because its internals are purely digital. Properly used, they will last for millions of cycles.
* SSRs turn on and off faster than mechanical relays (≈1ms compared to ≈10ms).
* SSRs are less susceptible to physical vibrations than mechanical relays.
* Since the switch inside an SSR isn't a mechanical switch, it does not suffer from [[Switch Primer#Bounce|contact bounce]] and operates silently.

However, compared to Mechanical Relays, SSRs:
* Are more expensive.
* Will dissipate more energy in the form of heat (1-2% of the energy intended to power the load).

==How SSRs Work==

[[Image:SSR_Internals.png|thumb|A conceptual diagram of the insides of an SSR.]]

The control inputs are connected internally to an LED, which shines across an air gap to light sensors.
The light sensor is connected to the transistors which open or close, supplying the relay's load with power.
When a transistor is '''closed''', current can flow freely through the relay, causing the load and power supply to be connected.
When a transistor is '''open''', almost all current is blocked, causing the load to become disconnected from the power supply.
The pairing of an LED with light sensors is called an optocoupler, and is a common technique to link two parts of a circuit without a direct electrical connection.

===Basic Use===

Controlling an SSR is no more complicated than turning an LED on and off. Switch it on, switch it off, it is that easy (see the [[Digital Output Primer|Digital Output Primer]], or our [{{SERVER}}/products.php?product_id=1031 specific LED controller] for more).

The ability of an SSR to switch a load is very similar to a [[Mechanical Relay Primer|mechanical relay]] or simple switch.
By turning the digital output controlling the relay on and off, you control whether or not the load is connected to its power supply.

The challenge is to pick an appropriate type of SSR for your application. There is no single SSR perfect for all applications. To choose an SSR for your particular application, please follow the [[#Choosing an SSR|Choosing an SSR]] section.

===Safety===

Since relays switch high currents and voltages, standard precautions apply. Make sure you never touch the terminals while the relay is powered. If your SSR came with a plastic cover, use it. Even when the SSR is switched off, a very small amount of current will flow.

When an SSR fails, it most often fails permanently closed. This is because when the transistor inside fails due to excessive current or heat, it will usually short out, allowing current to pass through unimpeded.
This means that as long as the power supply remains on, the load will be powered, possibly creating a fire or safety hazard.

==Choosing an SSR==

===Identify your voltage===

First, determine whether you need to switch AC or DC voltage. The electrical grid, and thus your wall outlet, runs AC, whereas batteries and most small power supplies are DC.

Next, determine the maximum number of volts you will be switching. If you are switching DC, particularly with batteries, assume your voltage is at least 25% more than what your battery is rated for. Even larger fluctuations occur on AC, but AC SSRs are designed to handle these surges. Typical AC voltage from a wall socket in North America is 110VAC, whereas in Europe it is usually 220VAC. If you are switching AC voltage from a wall socket, check which standard your country uses, and use that number as your voltage.

===Identify your current===

The current drawn by your load when turned on affects how large of an SSR you need, and how hot it will be when it is in use. If you know how much current, on average, your load draws, this is what we call '''Average Load Current'''. If you don't know the average current, but you know the wattage (power rating) of your load, you can calculate Average Load Current by:

<math>
\text{Average Load Current} =\frac{\text{Watts}}{\text{Operating Voltage}}
</math>

Next, you need to know the current drawn by your load when it is first turned on. Many loads demand a huge inrush of current when the load is first turned on. This places a significant amount of stress on the electronics inside the SSR. If you've ever noticed the lights dimming in the house for a second when the furnace starts up, this is caused by the fan motor starting up. In the same way that it takes a lot of force to move a heavy object from rest, it initially takes a lot of current to power up a fan or incandescent bulb. It's very difficult to measure the '''Surge Current''' itself, so we use a multiplier based on your device type. Surge Current is also referred to as '''inrush current'''.

{|border=1
|+'''Surge Current Multiplier'''
! Application
! Multiplier
|-
| Incandescent Light Bulbs || 6x
|-
| Motors || 6x
|-
| LEDs || 1x
|-
| Complex Electronics i.e., Motor Controllers, Phidgets || 6x
|-
| Fluorescent Light Fixtures (AC Only) || 10x
|-
| Transformers || 20x
|-
| Heaters || 1x
|-
|}

Multiply your Average Load Current by the multiplier for your device type to calculate the Surge Current.

===I need to switch AC===

Most AC applications will be switching 110 to 240 Volt power coming from the grid. If that's you, go to the [[#Mains Voltage (110 to 240V AC)|Mains Voltage (110 to 240V AC)]] section.

We also cover low voltage AC applications - 28 VAC (Volts AC) or less. For more information, visit the [[#AC/DC SSRs|AC/DC SSRs]] section.

===I need to switch DC===

If you only need to switch a small amount of current - 9 Amps or less, consider our compact, cost effective [[#AC/DC SSRs|AC/DC SSRs]].

If you need to switch more than 9 Amps, you need a serious [[#DC SSRs|DC SSR]].

If you need to switch up to 16 small loads of 2 Amps or less, you can use the open collector (externally powered) digital outputs on a [{{SERVER}}/products.php?product_id=10121012 PhidgetInterfaceKit 0/16/16], which can be wired to behave similarly to relays.

==I need Gradual Dimming==

Instead of simply turning the load on/off, if you want to dim it gradually, you can use a proportional control SSR. They are able to reduce the average power to the load gradually, in proportion to the strength of the input signal. For more information, you can visit the [[#Proportional Control SSR|Proportional Control SSR Section]].

==Mains Voltage (110 to 240V AC)==

We sell AC SSRs for 120 VAC or 240 VAC operation. If you are unsure what voltages you could eventually need to switch, the 240 VAC relays can be used to switch 120 VAC with no problems. Please note we are very conservative in how we rate SSRs - our 120 VAC relays are rated by the manufacturer for 240 VAC, and the 240 VAC for 480 VAC. We strongly recommend against using them to the manufacturer rated voltage. To understand why, read the [[#AC SSR Protection|AC SSR Protection]] section.

===Load Type - Inductive vs. Resistive===

[[Image:zero cross.png|right|thumb|300px|This graph shows the difference between zero-cross and random turn-on. The blue line represents the oscillating voltage of an AC load, and the shaded areas represent the sections when the relay is turned on and letting current pass through. As you can see, the random turn-on SSR immediately opens when activated, while the zero-cross turn-on SSR waits until the voltage crosses zero before opening.]]

If your load is inductive, you need to choose a '''Random Turn On''' relay. If your load is resistive, choose a '''Zero Crossing''' relay.

Your Load will probably be inductive if it is built around a large coil of wire - motors and transformers are typical examples. A load considered resistive may also have loops of wire - for instance, hair dryers, toasters, incandescent bulbs use twisted wire elements to generate the heat. An inductive load will have thousands of loops of wire - it's a matter of scale. There is no such thing as a perfectly resistive load - but a load has to be very inductive to cause the zero crossing SSRs to malfunction.

SSRs are designed to either turn on immediately ('''Random Turn On'''), or wait until the next 'alternation' of the voltage ('''Zero Crossing'''). Zero Crossing SSRs create less electromagnetic 'noise' when they turn on. They are best used with resistive loads - Zero Crossing SSRs are not able to turn off some inductive loads. It's very difficult to determine which inductive loads will create problems - well beyond the scope of this document. If your load is inductive, we recommend buying the '''Random Turn On''' SSRs.

{|border=1
|+ '''Inductive and Resistive Loads'''
! Application
! Load Type
|-
| Incandescent Light Bulbs || Resistive
|-
| Fluorescent Light Fixtures || Inductive or Resistive <font size=4>'''*'''</font>
|-
| Motors || Inductive
|-
| Transformers || Inductive
|-
| Heaters || Resistive
|-
| Computer / Electronics || Resistive
|-
| AC/DC power supplies (brick heavy type) || Inductive
|-
|AC/DC Power supplies (lightweight switchers) || Resistive
|}

<font size=4>'''<nowiki>*</nowiki>'''</font> ''For fluorescent light fixtures, older units (magnetic ballast) may be inductive, and newer units are often resistive (electronic ballast).''

===Choosing your AC SSR===

Now that you have identified your Operating Voltage, Average and Surge Current, and your load type (inductive or resistive), you can create a short list of relays whose
* '''Maximum Load Voltage''' are greater than or equal to your operating voltage,
* '''Maximum Surge Current''' are greater than or equal to your surge current, and
* '''Load type''' matches what you chose for random turn on/zero crossing.

<font color=green> < Table: +ac_ssr > </font>

{|border=1
! Phidgets Product #
! Manufacturer Part #
! Current Type
! Turn-on Type
! Control Voltage (V)
! Max. Load Voltage (V)
! Max. Load Current Without Heatsink (A)
! Max. Load Current with 3955 Heatsink (A)
! Max. Load Current with 3956 Heatsink (A)
! Max. Surge Current (A)
! Output Type
|-
| 3953_0 || HFS34/D-240A20PS-Y || AC || Random Turn-on || 3-32VDC || 120 || 8 || 15 || 20 || 255 || SCR
|-
| 3954_0 || HFS34/D-240A80PS-Y || AC || Random Turn-on || 3-32VDC || 120 || 10 || 20 || 50 || 800 || SCR
|}

Now compare the '''Max. Load Current without Heatsink''' value for the SSRs on your list to your Average Load Current. If your Average Load Current is greater, you may need a heatsink. For selecting a heatsink, please consult [[#Picking a heatsink|Picking a Heatsink]]. Alternatively, look at other SSRs on your list - there may be an SSR that can handle your average load current with no heatsink.

At this point, you know the SSR you need.

Instead of simply turning the load on/off, if you want to dim it gradually, you can use a proportional control SSR. They are able to reduce the average power to the load gradually, in proportion to the strength of the input signal. For more information, you can visit the [[#Proportional Control SSR|Proportional Control SSR Section]].

If you are interested in learning more about SSRs in general, check out our [[#Did you know?|"Did you know?"]] section.

===AC SSR Protection===

[[Image:MOV.jpg|thumb|An MOV, which comes packaged with our AC "Hockey Puck" relays. ]]

Your AC SSR from Phidgets comes with a circular disc with two legs (pictured). This is a Metal Oxide Varistor (MOV) and should be installed across the load (larger) terminals of your SSR. MOVs are the classic surge protector - an inexpensive component that absorbs high voltage spikes. High voltage spikes are caused by inductive loads when they are turned off, and also happen very often on the electrical grid, as nearby devices are operated. Even if your load is resistive, use an MOV to protect the SSR.

Matching an MOV to an SSR is not easy - this is why we include an MOV with your SSR. If an MOV is chosen for too low of a voltage spike, it will wear out quickly. If it is chosen for too high of a voltage spike, it will not protect the SSR adequately. To balance SSR protection against MOV lifetime, we have found it necessary to use SSRs built for 240 VAC in 120 VAC applications, and SSRs built for 480 VAC in 240 VAC applications. If you must operate our AC SSRs on higher voltages than we recommend, do not use the included MOV.

As MOVs wear out from use, they will become more sensitive to common voltage spikes, causing them to wear out quicker. When they entirely fail, they will become a short circuit, potentially creating a fire hazard. The MOV included with your SSR has a fuse built in which will disable the MOV when it becomes a hazard. To be on the safe side, avoid mounting your SSR near any flammable material.

===Proportional Control SSR===

Proportional Control Relays (often simply called "Control Relays") are SSRs you can use to control the amount of power to the load. Rather than reduce the voltage, or somehow limit the current - which would be very expensive solutions, the Proportional SSR reduces power by turning the load on/off quickly, feeding full power in short pulses.

Proportional SSRs are controlled by a variable voltage - as the control voltage increases, more power is available to the load. Our PhidgetAnalog product can be used to control Proportional SSRs, since an [[Analog Output Primer|analog output]] can output various amounts of voltage, as opposed to a digital output, which only has two states- high and low. We don't sell Proportional SSRs - but they can be purchased from [http://www.digikey.com Digikey], where they are called AC Linear Controlled SSRs.

A quick and dirty solution for dimming with Phidgets is to use an {{LinksNeeded|RC Servo Motor|[[Servo Motor and Controller Primer|RC Servo Motor]]}} with a PhidgetAdvancedServo controller to rotate the knob on a light dimmer. From software, the RC Servo Motor is rotated to the desired position, cranking the knob as it turns. While this may seem like a roundabout way of achieving proportional control, dimmers tend to be much less expensive because they are less specialized and are manufactured in greater quantity.

===Example circuits with AC SSRs===

[[Image:AC SSR Load.png|right|thumb|300px|Schematic of an AC SSR switching a generic load. A metal oxide varistor is added across the load to protect the SSR.]]

When wiring up an AC circuit, particularly for long term installation, you may find it helpful to buy a book on residential wiring from your local hardware store. There are many wiring conventions (and often legal codes) which will help you plan your project, and the legal codes are often a great source of wisdom.

<br clear="all">

==DC SSRs (0 to 50V DC)==

We sell DC SSRs for that switch a maximum load of 50 volts. If you are unsure what voltages you could be switching in the future, higher voltage DC SSRs can be used to switch lower voltages. Common engineering practice would be to purchase an SSR rated for 50-100% higher voltage than the voltage you plan to be switching. For instance, if you are switching 24V, a 50V SSR is reasonable.

===Choosing your DC SSR===

Now that you have identified your Operating Voltage, Average and Surge Current, you can create a short list of relays whose
* Maximum Load Voltage are greater than or equal to your operating voltage,
* Maximum Surge Current are greater than or equal to your surge current, and
* Maximum Average Current is greater than or equal to your Average current.

<font color=green> < Table: +dc_ssr > </font>

{|border=1
! Phidgets Product #
! Manufacturer Part #
! Current Type
! Turn-on Type
! Control Voltage (V)
! Max. Load Voltage (V)
! Max. Load Current Without Heatsink (A)
! Max. Load Current with 3955 Heatsink (A)
! Max. Load Current with 3956 Heatsink (A)
! Max. Surge Current (A)
! Output Type
|-
| 3950_0 || HFS33/D-30D50M || DC || N/A || 3-32VDC || 30 || 18 || 50 || 50 || 120 || MOSFET
|-
| 3951_0 || HFS33/D-50D80M || DC || N/A || 3-32VDC || 50 || 20 || 40 || 80 || 200 || MOSFET
|-
| 3952_0 || HFS33/D-30D100M || DC || N/A || 3-32VDC || 30 || 25 || 50 || 100 || 240 || MOSFET
|-
|}

Now compare the '''Max. Load Current without Heatsink''' value for the SSRs on your list to your Average Load Current. If your Average Load Current is greater, you may need a heatsink. For selecting a heatsink, please consult [[#Picking a Heatsink|Picking a Heatsink]]. Alternatively, look at other SSRs on your list - there may be an SSR that can handle your average load current without a heatsink. SSRs rated for a larger load than the load you're using will be more efficient (meaning less energy lost in the form of heat) than an SSR that's being operated at its maximum load.

At this point, you know the SSR you need.

If you are interested in learning more about SSRs in general, check out our [[#Did you know?|"Did you know?"]] section.

===DC SSR Protection===

[[Image:Diode.jpg|thumb| A diode, included with our DC "hockey puck" SSRs. The cathode is marked with a line. The blue symbol shows circuit diagram equivalent of the diode.]]

[[Image:relaymotor.jpg|thumb| A DC SSR switching an electric motor. The 1018 Phidget InterfaceKit controls the SSR using its digital outputs. A diode is shown installed across the motor, and a fuse is hooked up between the power supply and the rest of the circuit.]]

Your DC SSR from Phidgets comes with a diode. This diode should be installed across your load, with the Cathode installed towards the positive terminal of the power supply (as shown in the diagram).

If the diode is installed backwards, as soon as the SSR is turned on, the load will be shorted out, likely destroying the diode, or the SSR, or your power supply.
A fuse protecting your power supply is always a good idea. You can place the fuse in between the positive terminal of the power supply and the positive terminal of the load side of the SSR.

The diode protects the SSR from powerful residual currents after the SSR is turned off. While your load is being driven, inductance builds up magnetic fields around the wiring.
Every load is inductive to some degree, and when the SSR turns off, the magnetic fields will ram current against the now open SSR, easily damaging it. The diode allows these currents to recirculate in the load until they have lost their energy.

<br clear="all">

===Example circuits with DC SSRs===

[[Image:DC SSR Load.png|right|thumb|300px|Schematic of an DC SSR switching a generic load, which is protected by a diode connected in parallel. The circuit is protected by a fuse in series after the power supply.]]

The electrical isolation built into a DC SSR allows them to be placed within a circuit just like a switch. Since it is isolated, you don't have to worry about grounding or voltage offsets.

With a DC SSR, always make sure the positive load terminal (labeled +) is facing towards the positive terminal of the power supply. If the load terminals are reversed, your load will immediately turn on. There is a diode inside of the SSR that allows current to flow freely through it when the SSR is connected incorrectly. This feature is included because this sort of wiring mistake would destroy the transistor in the DC SSR otherwise.

The DC SSR can be installed on either side of the load, and it will work properly, but there is an advantage to installing the SSR between the power supply and the load. If the load is connected to the power supply, it will always have a potentially dangerous voltage on it, even when it is not operating.

<br clear="all">

==AC/DC SSRs (0 to 40V DC / 0 to 28V AC)==

[[Image:AC_DC_SSR.png|thumb|A small, versatile AC/DC SSR mounted on a Phidgets board for easy pin access.]]

Our AC/DC SSRs are built on a small PCB, making them physically smaller than the large "hockey puck" SSRs, and less expensive. They are limited to lower currents, and cannot be mounted on a heatsink.

We sell AC/DC SSRs that can switch up to 40 Volts DC or 28 Volts AC. This is indicated on the SSR Product pages under the Maximum Load Voltage specification. There is no lower limit on the voltages that the AC/DC SSRs can switch. If your voltage is close - be conservative. For instance, a 36 Volt system built from 3 Lead Acid batteries can reach 45 volts when charging.

===Picking your AC/DC SSR===

Now that you have identified your Operating Voltage, Average and Surge Current, you can create a short list of relays whose
* Maximum Load Voltage are greater than or equal to your operating voltage,
* Maximum Surge Current are greater than or equal to your surge current, and
* Maximum Average Current is greater than or equal to your Average current.

<font color=green> < Table: +versatile_ssr > </font>

{|border=1
! Phidgets Product #
! Manufacturer Part #
! Current Type
! Turn-on Type
! Control Voltage (V)
! Max. Load Voltage (V)
! Max. Load Current Without Heatsink (A)
! Max. Load Current with 3955 Heatsink (A)
! Max. Load Current with 3956 Heatsink (A)
! Max. Surge Current (A)
! Output Type
|-
| 3052_0 || N/A || AC/DC || N/A || ??? || 40DC or 28AC || 2.5 || N/A || N/A || 5 || MOSFET
|-
| 3053_0 || N/A || AC/DC || N/A || ??? || 40DC or 28AC || 9 || N/A || N/A || ??? || MOSFET
|}

If you are interested in minimum cost, you will likely choose the cheapest option that meets these criteria. If you are interested in high efficiency operation and less heat generation, consider buying an SSR with higher current rating.

Your AC/DC SSR from Phidgets has built in protection from static electricity, and dangerous residual currents after the SSR is turned off. If the load you are switching is powered by a DC source, installing a diode across the load will offer even more protection. Refer to the [[#DC SSR Protection|DC SSR Protection]] section for more information.

To learn more about SSRs in general, visit the [[#Did you know?|"Did you know?"]] section.

<br clear="all">

===Example circuits with AC/DC SSRs===

[[Image:Versatile SSR DC Load.png|thumb|A versatile AC/DC SSR switching a DC load. The load terminals are bidirectional, so it doesn't matter which way you hook them up. The optional diode can be added to help protect the SSR when switching DC loads.]]
[[Image:Versatile SSR AC Load.png|thumb|A versatile AC/DC SSR switching an AC load.]]

The electrical isolation built into a AC/DC SSR allows them to be placed within a circuit just like a switch. Circuits without electrical isolation require a lot more care - proper grounding, careful consideration of voltage offsets.

<br clear="all">

==Using heatsinks with Hockey Puck SSRs==

[[Image:3950_0 Accessories Web.jpg|thumb|A "hockey puck" SSR with plastic cover (left), a thermal pad (right). All hockey puck SSRs sold at Phidgets come with both of these accessories plus a diode or varistor to protect the SSR.]]
[[Image:3955_0 Functional Web.jpg|thumb|A "hockey puck" SSR mounted on a [[3955]] heatsink by two screws. The thermal pad is pressed between the SSR and the heatsink.]]

SSRs will only achieve their promise of reliability and long life if they are kept cool. Cool is relative, of course, but a good rule of thumb is to keep the metal base of the SSR at less than 85°C (185°F). A [[Thermocouple Primer|thermocouple]] can be used to precisely measure the temperature of the metal base.

Excess heat usually comes from too much current and too little heatsinking. A lot of heat can also be generated by frequently turning the relay on and off. If your relay is operated for brief periods of time, you may not need as large of a heatsink - provided the relay is never accidentally left on for extended periods. Unless space is a concern, it's better to err on the side of caution.

Before buying a heatsink, consider if you actually need it. If your application is running at room temperature, and your average current is less than the '''Max. Load Current without Heatsink''' specification of your SSR, then you don't need a heatsink. Alternatively, if your project has a large metal chassis that the SSR can bolt to, this can be used as your heatsink.

Each SSR suitable for use with heatsinks will include a specification of how much current it can switch with each heatsink we sell. This specification assumes a reasonable airflow over the heatsink, and that the flowing air is at room temperature. Our SSRs have a sheet of metal underneath, where the heat is concentrated - this is also where the heat is measured to tell if the SSR is too hot. Phidgets includes a grey thermal pad with our Hockey Puck SSRs (see pictured). You place this pad under an SSR when mounting it on a heatsink, or on large metal surfaces that can dissipate heat. The pad performs the same function as thermal grease - it helps conduct heat between the base of the SSR and the heatsink. If you prefer to use thermal grease, you can use it instead of the pad. Our heatsinks include screws for mounting SSRs. Use a good size screwdriver when tightening the SSR down on the heatsink to ensure good conduction.

{|border=1
! Phidgets Product #
! Product Name
! Manufacturer Part #
! Dimensions (mm)
! Thermal Resistance (C/W)
|-
| 3955_0 || Small Heatsink for SSR || HF92B-80 || 50x50x80 || 2.4
|-
| 3956_0 || Large Heatsink for SSR || HF92B-150A || 55x142x150 || 0.6
|-
|}

<br clear="all">

==Hooking up wires to the Hockey Puck SSR==

[[Image:relay_mov.jpg|thumb|An AC SSR with the wires attached normally and an MOV installed across the load side.]]
[[Image:lugs.jpg|thumb|TRM6 wiring lugs connected to a DC SSR.]]

When wiring your load to the SSR, the wire is looped clockwise around the terminal, so when the screw is tightened down, it will draw the wire in tighter. We recommend using wires up to 10 AWG in size - any larger, and the screws will not have enough thread left to tighten down, and they will strip. Larger wires can be attached using a wiring lug. The lug is clamped under the SSR screw, and the wire attaches to the lug.

Loose wire connections can generate a lot of heat - use a large enough screwdriver when clamping down the load wires to ensure that the screws are on tight enough.

For the current ratings of various wires sizes, please see [[Page on Wire Sizes]].

<br clear="all">

==Did you know?==

* Mains Voltage '''AC SSRs''' cannot switch DC. They will never turn the load off. AC SSRs turn off twice per AC Cycle, when the current changes direction and is momentarily zero. For example, AC is 60 Hz in North America, so the AC SSR has 120 opportunities per second to turn off (the SSR will only '''stay''' off if the control signal is low). If the SSR is operating from DC, the current will flow continuously, and the load will not turn off, even when the control input is off.

* An '''AC SSR''' turns off automatically every time the load current reaches zero. It will turn back on almost immediately as long as the signal controlling the SSR is high. An AC SSR will actually have a low, non-zero current value that it regards as 'zero'. This specification is usually called "Minimum Load Current" in the data sheet. If your load requires less than this minimum current, your SSR will never turn on, or will not reliably turn on. The simplest solution to this problem is to connect another load in parallel with the first, increasing the Current required by the load.

* SSR Manufacturers have started adding a simple circuit inside '''AC SSRs''', across the load terminals, called a snubber. The snubber absorbs very fast electrical changes that could normally cause an '''AC SSR''' to turn on accidentally. When the AC SSR is turned on, there is little voltage difference between the terminals, so the snubber has very little effect. When the AC SSR is turned off, the snubber is actively protecting the SSR - but at a cost, as it allows a small current through the SSR, which is wasted.

* An '''AC SSR''' uses bipolar transistors - an old technology that has been replaced by CMOS transistors in modern digital circuits. Bipolar transistors are still superior for handling high voltages. Bipolar transistors, and the more complex transistors built from them, will lose a constant voltage as current flows through them. The collection of transistors in your SSR will lose about 1.7 volts - so on a 120 VAC system, you will lose about 1.5% to the SSR. This energy converts to heat inside the SSR, and the heating from these transistors is the reason SSRs often need heatsinks.

* SSRs, and semiconductors in general, usually fail as a short circuit. A short circuit is a circuit whose internals have been damaged such that current can flow through it freely. This means your load will probably turn on permanently (until you disconnect the power source) - make sure this doesn't cause a safety hazard. For instance, Sauna Heaters have a simple thermally-triggered mechanical shutdown to protect them if control electronics fails.

* '''DC SSRs''' (at least the units we sell) use Metal Oxide Semiconductor Field Effect Transistors (MOSFETs). MOSFETs do not lose a constant voltage - instead, when they turn on, they act as a very slight restriction to the flow of current - a resistor. At low currents, the slight restriction wastes very little power, giving high efficiency and often not requiring a heatsink. This efficiency is lost as the current increases - a doubling of current quadruples the production of heat.

* Normally, a MOSFET can only block current in one direction - as soon as the voltage reverses, the current flows through a diode run in parallel to the MOSFET. If a MOSFET were used to switch AC, the load would be turned on half the time. A common solution is to use two MOSFETs back to back - which is what we do with our '''AC/DC SSRs'''.

Electricity Primer

2012-06-29T21:52:32Z

Cora: /* Affected Products */

[[Category: Primer]]

==Introduction==

Design of reliable systems is really, really hard. The main challenge is the design of reliable building blocks - i.e. circuit and board layouts - from which to create your system. Phidgets does the majority of this work for you. And, once you have reliable building blocks, designing a reliable system from them is much easier.

However, you can still make an unreliable system out of Phidgets. In fact, if you are building a more complex system than the common examples we show through our documentation, and you have limited experience in complex electrical design, you will probably - and unintentionally - introduce design flaws that will make your system unreliable.

There are two reasons why you should read this primer:
# You want to build a complex system, more complex than we illustrate in our documentation. To succeed, you need to understand concepts.
# You understand how to make your system work, and you want to ensure it is well designed for maximum reliability and/or precision.

==The Basics==

To understand our discussion of potential problems and their solutions below, you'll need to be familiar with the basics. For this page, 'being familiar' means more than simply having heard of voltage, amperage, and power. You will need to have a working, conceptual model in your head, so that you can apply that model to your own system and examine it for problems. This section is all about giving the tools to build that mental model.

First, some terminology. We introduce it by analogy. If a circuit is a water system,
* The '''voltage''' is the ''pressure'' in the system
* The '''power supply''' is the ''pump'' creating the pressure
* The '''amperage''', also known as current, is the amount of ''flow''
* The '''load''' is the ''faucet'' - adjusting your load will adjust the flow
* The '''resistance''' is an attribute of the load - how tight or loose the faucet is
* The '''ground''' is the return path from load to pump.

The basic concepts for all of these terms are presented below.

===Load===

We start with the load, because the load is the purpose of your entire system.

In simple, USB-only Phidget systems, the load is the Phidget itself. The USB port is ready to provide power, but it does not (and cannot) until a load is applied (i.e. the Phidget is attached) and the circuit is completed.

Without a load that connects in a loop, it is like attaching a closed pipe to your pump. Initially, water will fill the pipe, and pressurize it, but once the pipe fills the system as a whole will do nothing more. To allow the pump to drive the load, and the flow to supply the load, we need to have a completed circuit, like this:

[[Image:elec_flow.png|150px]]

The load and the pump must '''match'''. If the load lets too much flow through, the pump will work too hard and burn itself out. This is what happens when you short circuit a power supply. The load is then simply a wire, which basically opens the flood gates and drains your power supply pump. The load must not let too much flow through, which it does by '''resistance'''. Likewise, the pump cannot push too hard on the load, or the load will break. This is discussed in-depth as part of [[#Voltage and Amperage|Voltage and Amperage]] below.

===Voltage and Amperage===

Within the flow concept [[#Load|above]], voltage is pressure. Specifically, it is the ''difference'' in pressure between the flow and the return. Voltage is measured in volts, and is denoted by '''V'''.

Amperage - also known as current - is the flow, or the amount of water that moves. At the pump, the amount of current out and the amount of current in are equal. The pressure might vary widely (highly pressurized pipes out, low pressure pipes back) but the ''amount'' of current is always the same. Amperage is measured in Amps, and is denoted by '''A'''.

To match a pump to a load, the voltage and amperage of the power (supply) and load (sink) must line up. We discuss picking a power supply - whether [[#Wall Power|wall mains]], or [[#Battery Power|batteries]] - in the [[#Power Needs|Power Needs section]] farther along in the document, but we need a few more concepts before we get there.

Power supplies - whether wall power or batteries - are usually rated based on voltage and amperage. Voltage is the specification to be the most careful with for circuits. Too much voltage is the same as overpressurizing your pipes - they will burst. In the case of electronics, you device will break.

This can be counterintuitive - in reference to safety (for humans) around electronics, you may have heard "It is not the voltage that will kill you, it is the amperage". Because of this, it may be tempting to think that too high of an amperage will harm your device, but this is not true. Our hearts are very susceptible to amperage but not voltage, hence amperage is considered dangerous for us whereas voltage is not. But a circuit is not like a human body - in a circuit trying to handle a power supply it is the voltage that matters most.

====Set Voltage (No Control)====

Most loads do no power regulation of their own. They simply take the voltage given to them and do useful things with it. You can tell that a pre-designed load (like a Phidget) falls into this category because it gives its voltage need ''as an exact value''. For example, most Phdigets use exactly 5 V of USB power. These loads will also tell you their amperage, which is a flow need that must be met or exceeded. A load will only use as much amperage as it needs.

====Controlled Power====

Some loads change the voltage or current they receive. This can be with the intent to either (a) keep a constant amount of power flowing from a draining power source like batteries, or (b) to modify a common power source (i.e. 12 V at 1 A) into an uncommon power source (i.e. 1 V at 12 A). This process is called '''regulation'''.

You can tell that a pre-designed load (like a Phidget) falls into this "power-regulated device" category because it gives its voltage need ''as a range''. For example, the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer (SBC)] can take 6 V to 15 V.

To understand how this works, take the example of a flywheel. Flywheels are designed to be heavy and to take work in order to get them spinning at speed. But once you have them spinning, you can extract that work later at a more consistent rate:

[[Image:elec_flywheel.png]]

Flywheels can either make amperage or voltage be the more consistent blue line over time. The most common one in Phidgets is for stable amperage. Regulated amperage is also how LED lights can stay consistently bright for any length of time when using batteries. Stable voltage design is usually applied when the voltage is too low to begin with (such as any device that runs on a single AA battery), and the flywheel must amplify and stabilize it over time.

For those readers trying to envision how this works electrically, in practice the flywheel is an inductor (or, a transformer utilizing its inductor properties). For both voltage and amperage regulation, one way relief valves (diodes) must be added. And, in amperage regulation a reservoir (capacitor) must be added to offset the current drop by pulling ''more'' amperage as a battery drains. Then, a controller is needed to measure and then correspondingly enable and disable the flywheel system as the voltage or amperage drops from the supply.

But with those details in place, the inductor (and capacitor, in the case of amperage regulation) can effectively take the variety of voltages from, say, a draining battery, and still allow the board to run. Some devices even do this naturally. For example, motors often can take a variety of voltages because their construction (i.e. wire wrapping) naturally creates inductance.

These regulated systems often list the power they need directly, using a type of power rating called '''watts'''. Watts are voltage and amperage together (i.e. power):

<math>
\text{Amperage} =\frac{\text{Watts}}{\text{Voltage}}
</math>

Watts can be a handy way to describe flow and pressure together for these regulated devices. Rather than separating voltage and amperage like the unregulated devices do (i.e. this load needs exactly 12 V, or this load will draw exactly 2 A), the unit of watts will allow different value combinations of volts and amps as long as the wattage remains the same. For example, a 12 watt device with a voltage range of 5 to 12 volts can run on 6 V at 2 A, or 12 V at 1 A. Either will work. Amperage for all values in the device's range of 5 to 12 V can be found with the equation above. Because of this, watts are often preferred when trying to match a power supply to a regulated load.

===Ground===

All circuits have a '''ground'''. This is simply the return pipe to the pump. In a circuit, it is denoted by an upside-down triangle:

[[Image:ground.png]]

When drawing a circuit diagram, the symbol is placed on the wires that return to the pump:

[[Image:elec_flow_ground.png|170px]]

This electric ground provides a voltage reference throughout the circuit. Ground is always '''0''' volts as far as the circuit is concerned. (Remember, voltage is the ''difference'' between the flow and return pipes at the pump.) Ground is important because it provides a reference from which all the parts of the circuit can speak the same "voltage language" to each other, which matters a lot when a certain voltage means "1" and a certain voltage means "0".

There is only one '''absolute''' ground, and that is the Earth, which is taken to be 0 volts as an absolute value. Circuits not well-grounded to the Earth (of which there are many - your cell phone, car, etc) operate at a '''relative''' voltage. The upside-down triangle above denotes a ''relative'' ground.

With relative voltage, only the difference between local ground and the local high voltage matters. For example, a cell phone might operate as a 3 volt device, which means relative to its ground it always operates between 0 and 3 volts. But if that cell phone were compared carefully to Earth ground, its absolute voltage could be, say, between 10 and 13 volts. Until comparison, the device doesn't "feel" charged. This is the same as how you don't "feel" charged after skidding your feet in socks across a carpeted floor. But, when you "compare" yourself to Earth ground by touching some well-grounded metal, you receive a static electricity shock.

The same thing can happen when you combine two different power supplies, as we discuss [[#Projects With Different Power Sources|below]].

===Power===

There can be different types of pumps, and at this point we should supplant our heart symbol with some actual power supply pump symbols. For example, this is the symbol for a direct current (DC) battery:

[[Image:elec_battery_basic.png|200px]]

The + end is on the out flow, and the - end is on the return (ground). Batteries are usually listed with their voltages. This is because the resistance of the load will determine how much amperage is drawn, but too much voltage and you will harm your load.

This is the symbol for alternating current (AC) that you would get directly from the wall:

[[Image:elec_wall_basic.png|200px]]

Again, this is listed using voltage for the same reasons as DC. A relative ground symbol is still used on the return line here. AC devices can still operate on relative voltage if they do not use Earth ground (the third prong on a wall plug in North America). This is how some loads have AC cords with only two prongs - they operate on a relative voltage and relative ground. And relative AC voltage, having significantly more voltage (pressure) behind it, can really hit a device hard when two power supplies meet across it.

This connecting of multiple power supplies is quite a complex subject, and is described further in both [[#Power Needs|picking different power supplies]] and [[#One Powered Phidget|connecting different power supplies]] later on in this Primer.

===Emissions and Wires===

To talk about emissions, it is worth speaking more precisely about what a load is. The typical, simple Phidget setup is receiving 5 V direct current (DC) from the computer over the USB port. Let's model this as coming from a battery so that we can examine all parts of the system. From the point of view of the battery, the Phidget load is not just the green board with the circuitry on it. The load ''also'' includes the power cable (i.e. two wires in the USB cable), and anything else on the path out or back from the circuitry to the battery itself:

[[Image:elec_phidget_basic.png|200px]]

This is important because the wires play a role in the voltage that eventually makes it to the Phidget. This is true all the time, even when the Phidget is attached to a computer instead of a battery. All wires have some resistance, and so they are, in a way, in and of themselves circuits. Therefore, because of their resistance, the wires 'use' some of the 5 V heading out to the Phidget circuit board. This is discussed more below, but essentially longer cables have more resistance and at some point the voltage will drop so much over the length that the Phidget will not turn on.

To conceptually separate the wires from the Phidget in terms of the load, we can now start drawing the wires themselves in our circuit diagram, instead of the curved concept arrows indicating flow and return:

[[Image:elec_phidget_wires.png|200px]]

When talking about the 5V relative ground in this system, we are in fact talking about the ground ''right at the battery'' so we move the ground symbol to the battery itself.

Then, the resistance on these wires creates a possible problem - the emission of electromagnetic radiation as the wires naturally drop the voltage:

[[Image:elec_phidget_emissions.png|200px]]

These emissions are at a set frequency determined by the length of the wire:
* Long wires create low frequencies (harmful interference)
* Short wires create high frequencies (less harmful interference)

This can be minimized by having the flow and return wires be the same length and sit right next to each other. This way, the emissions somewhat cancel each other out from the flow and return going in opposite directions. This is partially how USB cables minimize emissions.

So, the way you design your connections (i.e. the resistance and placement of your wire) will have a direct affect on:
# The voltage that reaches the Phidget
# The emissions that your system produces

With all this talk of emissions, you might be tempted to try to shield parts or all of your system from emissions that either your system or external systems create.

Keep in mind that shielding is actually really hard to do correctly. Especially when grounding your shielding, with ad-hoc design you have a high chance of having an interfering signal (that has traveled out to the shield and traveled back via ground) creating a larger problem than not having a shield at all. Rather than shielding, it is easier to simply keep your cables short and with as low a resistance as possible throughout your system to minimize your emissions in the first place.

Identification of and solutions to these (and other more complex) problems are discussed in detail in the [[#Selecting Cables|section on choosing cables]] and the [[#Hooking Up The Pieces|section on connecting the pieces]] below.

===Multiple Loads===

The easiest way to hook up multiple Phidgets is in parallel, where the voltage stays the same but they share the amperage. Here the DC supply is two USB ports, each at 5 V and 0.5 A:

[[Image:elec_phidget_parallel.png|250px]]

However, the length of your wires comes into play again, because the voltage that actually reaches the Phidgets above is somewhat less than 5 V. So if your wires are long, or mismatched, the voltage may not match and will give you strange results. The voltage is both affected on the way out, and on the way back. Assuming the wires are the same length:

[[Image:elec_phidget_wire_drop.png|350px]]

In this way, you can create difficult-to-debug problems within a complex system, where one Phidget works but others mysteriously fail.

==Power Needs==

Now that you've understood the basics, it is time to actually talk about decisions and design. This section will help you choose a power supply for your Phidget. Let's say you want to run the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer] off of a battery. Or you want to run a motor controller with a power supply you bought from the hobby store. What do you need to buy? Will one you already have work? It is worth it to spend a moment with pencil and paper to work through this section and identify your power needs.

As described [[#Voltage and Amperage|earlier]], voltage is pressure. Too much pressure behind your faucet, and the water mains or faucet will break. Likewise, if you have too much voltage from a power supply, your circuit will break. You should choose a supply with voltage that ''matches the range the Phidget can accept''. The voltage cannot be over the maximum (otherwise, like pressure in a pipe, the pipe will burst), and the voltage cannot be under the minimum (otherwise, like pressure in a pipe, no flow will occur). Also, generally, a device (like a motor controller) will perform better at its maximum rated voltage if a range is available.

But the faucet doesn't care whether there is a big reservoir or small reservoir feeding the system, as long as the pressure is managed. Likewise, you can choose a power supply with more amperage than you need (a big reservoir to draw from) as long as the voltage matches. In the same way that a faucet restricts water by design, loads draw and allow only the amperage that they need. However, the amperage cannot be less than the Phidget needs. In that case, you will either overextend (and break) your power supply, or the circuit simply will not turn on at all.

The specification [[#Device List|for your specific device]] will list its power needs. For most devices, the external power supply needs will simply be listed in voltage and amperage. USB power is 5V at up to 500 mA (0.5 Amps). Most Phidgets will draw less than this - if you need precision, you can check the specification for your particular Phidget. And, if it is an Interface Kit, you can add the draw of each analog sensor and digital in/out from their specifications.

However, some Phidgets (e.g. motors, and the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer]) do not have a straight amperage and voltage specification. Instead, their power draw will be listed in watts, for which you [[#Voltage and Amperage|saw a relation earlier]] to convert to the values you need.

===Wall Power===

Wall power sources usually take the alternating current (AC) from the wall and convert it into a direct current (DC). These power supplies often take your familiar two-or-three prong wall connector and put power out via a barrel plug-type connector. AC power (typically 110 or 240 volts, depending where you live in the world) goes in the typical wall plug, and DC power (typically 5 to 24 volts) comes out the barrel plug. Most power supplies of this type list the conversion explicitly, such as: 110-240 Volts to 12 Volts at 2 Amps. You'll want to match your Phidget's needs against the 12 Volts at 2 Amps.

*The voltage must match exactly
**If the Phidget takes a range of voltages, the supply must fall within the range
*The amperage can be equal to or greater than the Phidget needs

A wall power supply is essentially an inexhaustible supply of current, so you don't need to worry about it running out like you would with batteries.

===Battery Power===

If you intend to use a battery bank (even of only one battery) to power your Phidget, you probably want to know what type of battery to purchase.

====Battery Chemistries====
The first thing that sets batteries apart is the type of materials used in their construction. The following table shows several of the more common battery chemistries as well as the voltage per cell they produce and the specific energy of the chemistry.

{| border = 1
| align="center" style="background:#f0f0f0;"|'''Chemistry'''
| align="center" style="background:#f0f0f0;"|'''Nominal Cell Voltage'''
| align="center" style="background:#f0f0f0;"|'''Specific Energy (MJ/kg)'''
| align="center" style="background:#f0f0f0;"|'''Description'''
|-
| align = "center" colspan = 4|Primary Batteries
|-
| Alkaline||1.5||0.4||These are the most common form of battery. Many commercially available AA and AAA batteries are alkaline.
|-
| Lithium (LiMnO2)||3||0.83-1.01||These are used in high drain devices or devices with a long shelf life as they have a very low self discharge rate.
|-
| Silver-oxide||1.55||0.47||Only used in small button cells as these are quite expensive.
|-
| align = "center" colspan = 4|Secondary Batteries
|-
| NiCd||1.2||0.14||Older technology, suffers from [[Electricity Primer#Memory Effect|memory effect]]. Capable of very high discharge rates with no ill effects. Moderate self discharge rate.
|-
| Lead-acid||2.1||0.14||Not particularly good with high discharge rate. Moderate rate of self discharge.
|-
| NiMH||1.2||0.36||Very heavy. Good performance in high drain devices. Very high energy density naturally, at the cost of a high self discharge rate. Newer versions are able to get rid of some of the self discharge though they suffer ~25% lower energy densities as a result.
|-
| Lithium Ion||3.6||0.46||Expensive to produce but very high energy density. Very low self discharge rate. Safety hazard as short circuiting can yield explosive or fiery results.
|}

====Choosing a Battery====
Batteries are chosen first by their voltage (V). Match the voltage exactly to the voltage the Phidget needs. Over or under this value, you could harm the board or have it simply fail to turn on.

Next, choose a battery that has adequate amperage to feed your device for the time you need. The lifespan of the battery will usually be listed in Amp-Hours (or Ah). For example, a double wide 12 V lantern battery will have usually around 7-8 amp hours. This means if you drew one amp from it for seven to eight hours, the battery would be totally drained. Or you could draw two amps from it and drain it in 3.5-4 hours. This does not mean however, that you can draw 36A for 15 minutes. It is important to understand that there is a limit at which more power simply cannot be drawn from the battery. Effectively, high drain devices will decrease the rated Ah. The amount differs from battery to battery so to be sure it is recommended to check the data sheets for the battery you are using. If the battery did not come with a data sheet they can usually be found on the manufacturers website. The data sheets should have a graph that shows the relationship between current draw (usually in mA) and capacity (Ah or mAh). Another useful thing that can be gathered from the datasheets is the batteries response to temperature. Batteries tend to not work as well in cold environments, most manufacturers will provide graphs of how the batteries lifespans will shorten at different temperatures. This is often very significant, causing the battery to last a fraction of its normal lifespan at temperatures below -10°C.

Finding the amperage or voltage sometimes needs to be done indirectly by using a specification of watts. The relationship between amperage, voltage, and watts is given above in the [[#Voltage and Amperage|voltage and amperage section]].

For an example, let us say you want to use battery power to run the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer]. The specifications say that it uses 1.2 watts as a base value. The specifications also say that it can take 12 V DC power. If we choose to use a 12 V battery, at 1.2 watts it will use 0.1 amps according to the equation [[#Voltage and Amperage|shown earlier]]. Going by amp-hours alone, if our battery is a double-wide lantern type 12 V battery, with 7 amp hours, with 0.1 amp draw it will last 70 hours, or almost three days.

<math>
\text{Maximum Running Days} =\frac{\text{Battery Amp Hours}}{\text{Device Amps} * \text{24}}
</math>

However, to estimate ''average'' running time (rather than maximum running time possible), amp-hours cannot be used so directly. Over time, batteries decrease in voltage as their power is used up. Practically speaking, this means one of two things for your load. For loads that do not regulate voltage or current, the amperage will also decrease over time. The classic example is an LED light source that grows dimmer and dimmer as the batteries are used up.

You should usually only count on about 60% of the stated amp hour rating to apply before expecting to run into problems from escalated drain due to battery voltage drop. This is especially true for deep cycle rechargeable batteries left in an installation, where draining more than 60% could also harm the battery.

Then, for lead-acid batteries, a typical battery is tested from full to complete drain over 20 hours by the manufacturer to obtain the advertised amp-hour rating. Draining a battery at a faster rate than this will result in even more reduction in capacity, by 10% or even more. This due to [http://en.wikipedia.org/wiki/Peukert%27s_law Peukert's Law].

There are plenty of [http://www.google.ca/search?&q=battery+calculator battery calculators] around the Internet which take most or all of these additional factors into account when recommending an amp-hour rating. For longer-term installations, the solar power online community has some excellent resources.

====Setting up Multiple Batteries====
You can hook up multiple batteries in series to get more voltage at the same amperage. The amperage is additive. For example, you can hook up two single-wide 6 V lantern batteries in series to produce 12 V. Or two 12 V batteries in series to produce 24 volts. This system would still only have the amp hours of ''one'' of the lantern batteries, because you will be essentially using them both at once:

[[Image:elec_battery_series.png|250px]]

The upside down triangle (ground) is explained above in a [[#Ground|section of its own]].

Or, you can hook up multiple batteries in parallel to get more amperage at the same voltage. For example, you could hook up two 12 V deep cycle batteries in parallel to provide more amperage at 12 V, which is like having a deeper reservoir of power for your device to use:

[[Image:elec_battery_parallel.png|250px]]

====Heat====
*all batteries have some sort of internal resistance
*can be found on the battery's data sheet
*the more power you pull from the battery the more heat is going to build up as a consequence of the internal resistance.
*larger internal resistances will cause heat to build up faster.
*when charging a battery you are not just limited to the power in the battery. nothing stops you from dumping energy into the battery past the point where it is fully charged
**this is why charging batteries is a bit of a tricky business.
**many batteries come with custom chargers that have control systems to prevent this type of overcharging.

====Weight====
Finally, weight matters - a car battery is much heavier than a lantern battery. Batteries vary widely by weight per amperage. Lithium batteries are usually very light for their power, followed by alkaline, followed by lead acid. This may not seem important at first, but if you are building a mobile robot it is worth calculating in the work of carting around a battery. You may find that, for the length of time you want it to run, your battery requires some system redesign.

==Selecting Cables==

===USB Cables===

In general, use the shortest cables possible. There are many reasons for this [[#Emissions and Wires|described above]], but as a summary:

; Long cables reduce the voltage that reaches the Phidget.
: This happens in both directions. So, for every unit cable length added, the voltage decreases by twice the electrical resistance of that length of cable. With especially long cables the Phidget may drop below its 4.6 volt threshold and simply never turn on.

; Long cables increase the width of your circuit.
:All circuits act as emitting antennas for the resonance frequency of the circuit structure. The longer the wires in the circuit, the lower the frequency, and the higher chance that it will be emissions that will interfere with your data and system.

; Longer cables have more length exposed to external interfering emissions.

Also, use thick cables that are built to specification. Some USB cables with thinner wiring have higher electrical resistance. This can be equal to what a much longer wire would have, and thus create a similar voltage drop where the Phidget will not turn on.

====Options for longer cables====
The maximum length for a USB cable is 5m. This is laid out in the USB specifications. Often times however a system requires more reach. In this case there are a few options available to you. You can use what is known as an active extension cable or USB extender. These cables act like extension cables and add power to the line so that the signal can travel further. A second option is to use a Cat5 extender. These extenders are 2 USB dongles that connect on either end of your system. You join them up with Cat5 cable. This allows you to run over much longer distances than USB traditionally allows.

===Power Cables===

There are "DC Wire Table" references on the Internet which describe how to pick a wire appropriate for your voltage and amperage. When selecting AC wires, you will probably be using pre-made extension cords. Cords add interference resonance length to your circuit, just like USB cables do as [[#USB Cables|described above]]. A long extension cord can create huge electromagnetic interference for your circuit and other systems in the area when first plugged in.

Also as with the USB cables above, cut the cables to the shortest length possible. This is again both for voltage drop reasons and frequency emission reasons.

===Hubs===

Avoid hubs where possible. Unpowered hubs are good for reading data from memory keys, but not for powering many external devices. If you must use a hub, buy a powered one.

===Sensor and Motor Wiring===
All Phidgets sensor class devices (products whose part numbers start with 11 such as the 1129) use a 3 channel ribbon cable for power and data transmission. Similarly, all our motors and load cells use multichannel wire interfaces. As mentioned previously, USB spec limits cables to 5m, this is not the case for these wires. The biggest concerns are electromagnetic interference (EMI) and voltage drop. In general you should be able to run these wires over significant distances (30m or more) with the load cells in particular having very long range. If EMI starts causing issues you can always use ferrite beads on the cable near the sensor or motor and the controller to reduce noise.

===Cable Gauges for Terminal Blocks===

Many Phidgets products feature green terminal blocks that use screws to hold wires in place, making it easy to take apart and rebuild connections in your project. The size of the terminal block determines the gauge of wire you should use.

{|border=1
|+'''Terminal Block Size and Wire Gauge'''
! Terminal Block Width (mm/port)
! Recommended Wire Gauge (AWG)
|-
| 3.81
| 14 to 26
|-
| 5.0
| 12 to 26
|-
| 9.5
| 10 to 26
|-
|}

The gauge of cables and wires is measured in AWG, which is the American Wire Gauge standard. The following table lists the properties of wire gauges commonly used with Phidgets:

{|border=1
|+'''American Wire Gauge Sizes'''
! AWG Size
! Diameter (mm)
! Area (mm²)
|-
| 10
| 2.588
| 5.26
|-
| 11
| 2.305
| 4.17
|-
| 12
| 2.053
| 3.31
|-
| 13
| 1.828
| 2.62
|-
| 14
| 1.628
| 2.08
|-
| 15
| 1.450
| 1.65
|-
| 16
| 1.291
| 1.31
|-
| 17
| 1.150
| 1.04
|-
| 18
| 1.024
| 0.823
|-
| 19
| 0.912
| 0.653
|-
| 20
| 0.812
| 0.518
|-
| 21
| 0.723
| 0.410
|-
| 22
| 0.644
| 0.326
|-
| 23
| 0.573
| 0.258
|-
| 24
| 0.511
| 0.205
|-
| 25
| 0.455
| 0.162
|-
| 26
| 0.405
| 0.129
|-
|}

==Hooking Up The Pieces==

Here, things can be tricky. You might think: just plug everything in and go! But often it is not that simple. Many Phidgets require special care when hooking up. We encourage a process where you apply the concepts in this Primer, through analysis, to your system. So, we don't explicitly list the boards most commonly affected until the [[#Affected Products|end of this Primer]].

The ''categories'' of the boards which require special attention within a complex system are:

# Phidgets with more than one power source, and
# Phidgets needing precise measuring or control of an external power source

If you are already thinking about your boards in your head and trying to figure out whether they fit into one category or another, you're on the right track! The list of [[#Affected Products|commonly affected boards]] are only the common ones... with a sufficiently complex system, you could conceivably create problems with ''any'' boards.

Both types of projects require a full understanding of [[#The Basics|electrical basics]]. Using those concepts, below we first describe problems that arise when hooking up different power sources, and extend that into using the solution to give more precise measurement and control.

===Shared Grounds===

Shared grounds can occur in Phidgets that handle two different power sources. Recognizing the sharing of a ground is not always easy. We show what it is, how it can be possible, and why it creates problems by starting with the most basic Phidget system. The simplest setup for a Phidget is to use the [[#Ground|ground]] of the computer it gets data and power from over a USB port:

[[Image:ground_simple_case.png]]

In this case, there is only one relative ground, and it is the PC ground, which is ground #1 in the image. The PC ground determines what is considered 0 volts for all signals on the Phidget. When you add different power sources or sinks in the system, you are pulling the system relative to the PC ground.

=====One Powered Phidget=====

The next most complicated system is one Phidget that handles two power sources. Let us say you have a motor controller, which takes power from USB, and which also takes power from a second power source. Although the second power source is usually just a wall plug, the simpler case for thinking about ground is actually a battery. A battery creates a second ''relative'' ground. Through the Phidget, relative ground #1 (from the PC) and #2 (from the battery) actually become the same ground:

[[Image:ground_wall_power.png]]

This is the first reason why systems with powered Phidgets have to carefully manage ground. If ground #1 and ground #2 are different with respect to each other (see the static shock analogy in the [[#Ground|ground section]] above), then whatever circuitry along the red dashed arrow must deal with the initial static shock. In this case it would be the circuitry of the Phidget. In the case of a battery, after the initial equalizing shock the battery will be whatever relative voltage the PC ground needs it to be. Hence a battery relative ground can 'float'.

If ground #2 comes from the wall, on the other hand, the ground does not 'float' and instead is always absolute 0 volts Earth ground. With the PC giving the power, this is not a problem in practice because the PC can also float (as with a laptop), or it uses Earth ground. But if you were using a different and more powerful USB power supply instead of a PC, and then connected it to the absolute Earth ground through the Phidget, the Phidget would bear the brunt of any ground equalization that would occur. If neither the new ground nor the old ground float, and the power supplies were powerful enough, this would eventually destroy the Phidget. In this case, you would want to use isolation, as described in [[#How To Fix This|How To Fix This]] below.

=====Multiple Powered Phidgets=====

A worse case comes in when you are using two powered Phidgets and one external power source. Again, say you are using a battery as the external power source. It would be tempting to simply wire both grounds from the Phidgets to the ground on the battery:

[[Image:ground_two_phidget.png]]

Although this looks benign, you have actually created a new circuit. The circuit is a second path, via ground, for the current to return to the voltage source. This is also known as a '''ground loop'''. The path we intuitively think of the current returning by is '''<span style="color:blue;">path A</span>''', but the sharing of grounds has created a new path through the motherboard, '''<span style="color:red;">path B</span>''':

[[Image:ground_two_paths.png]]

All current gets 'pumped' in a loop by voltage, and so it will use all return paths available to it, assuming all paths are equally easy (electrically) to use. This extends the pipe analogy, where water will flow in every path that exists. So, if your battery (or other power source with ground #2) is quite powerful, you can actually harm your motherboard within your PC (or at least your USB bus ground), because '''<span style="color:red;">path B</span>''' runs through the motherboard circuitry on the way back to the voltage source.

This problem does ''not'' apply to using a different power source between a black power plug and for the green control terminal block on, say, a [[DC Motor and Controller Primer|DC motor controller]]. Although the grounds are connected, and they run across a part of a Phidget board, creating a ground loop does not actually run through any circuitry if only these types of boards are used. If you have a complex system with other types of boards and therefore circuitry between black plug power port and green terminal block connections, draw out your system carefully to identify the loops.

Ground loops can be fixed by one of the ways described in [[#How To Fix This|How to Fix This]] below.

=====Single Board Computer And Powered Hub=====

When combining one externally powered Phidget and the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer] or the [[Product - 1019 - PhidgetInterfaceKit 8/8/8 w/6 Port Hub]] on the same external power source, you still may inadvertently create a ground loop as described above in [[#Multiple Powered Phidgets|the multiple powered Phidgets section]]. If they share a true [[#Ground|Earth ground]], this is not a problem. But if the ground is from a battery, or uninterruptible power supply, etc. then you should carefully draw out your system circuit and examine it for ground loops.

====How To Fix This====

Once you are aware of shared grounds in your system, you have two options.

One, for ground loop problems in simple systems (two Phidgets), you could make the normal return path ('''<span style="color:blue;">path A</span>''') the most electrically desirable path. This is best for simple systems where you have a lot of control over all of the ground wires within your system. For the ground wires leading directly from the Phidget to the external power supply ('''<span style="color:blue;">path A</span>'''), lower the resistance in the wire as much as possible. You can do this by keeping the wires short, and using a thick (large gague) wire for the hookups.

Although this solution works, sometimes you do not have much choice on how long your ground return wires can be, because the location of your power supply and and Phidgets are set by your system design. If you cannot be totally sure that the direct ground path is the shortest and most electrically desirable path, it is best to use the second option: a '''USB Isolator''' such as the [[Product - 3060 - USB Isolator|Phidget 3060]]. This isolator is like any other USB isolator - it can be used on a Phidget system, as well as any system that needs ground isolation.

You need isolators for every USB cable in your system, less one. If you have two USB connections, you need one isolator; three USB connections, two isolators, and so on. The one USB connection can remain non-isolated because a single ground connection cannot form a loop. However, if you are concerned about connecting the grounds as described in the [[#One Powered Phidget|single connected Phidget section above]], use a USB isolator on every cable.

===Precise Voltage Control===

Precise voltage (or other system) control and measurement is related to the concept of [[#Shared Ground|shared ground above]]. But here, you want to keep grounds separate not only to prevent ground loops, but also to make your system more sensitive to what it will control or measure.

For example, we make Phidgets that can create power precisely, or that can take it in and measure it. One such product is the 1002, which outputs a precise analog voltage with which to control an analog system. Now that you know about [[#Ground|relative ground]], however, you would be right to expect that you do not want to combine the ground in the PC and the ground in the system.

Even if you don't care about system sensitivity, you can still create [[#Multiple Powered Phidgets|ground loops]] in a system with multiple of these types of Phidgets. In addition, if you are using the Phidget to control a large, powerful system, even a single Phidget can receive damage from connecting two powerful power sources meeting across it, also as [[#One Powered Phidget|described earlier]].

But above and beyond the powered Phidget problems, there is another reason to separate (isolate) the electrical grounds in your system. The reason is: to make your system control more precise. For example, with the 1002, if you are trying to control an external system with an Phidget output voltage, that output voltage should be relative to the ''system you are trying to control'', not relative to the PC. Rather than forcing the grounds - and therefore the relative voltages - to be equal to each other, you can provide more precise control by isolating the grounds and working with the relative voltage of the controlled system on its own terms.

<span style="color:red;">Schematic-type image of a ground isolated analog out on a 1002</span>

====How To Fix This====

The solution to all of these problems in precise voltage control systems is to use USB isolation, even for a single Phidget. The [[Product - 3060 - USB Isolator|Phidget 3060]] is one such isolator. It inserts along the USB connection between your PC and the Phidget, and it separates the Phidget (and controlled system) ground from the PC ground. This fixes ground loops, separates relative voltage mis-matches, and isolates the control system for better precision.

<span style="color:red;">Image of 1002 and Isolator connected, with lines superimposed on the image to show non-copper connection in isolator</span>

==Affected Products==

If you're not sure whether a certain concept applies to your Phidget within a complex system, the best way to figure this out is by doing some mental (or pencil and paper) simulation. Draw the inputs and outputs for the entire board, and label them with voltage, list their required amperage (or watts), and draw connections (such as ground connections) through any circuitry.

With a technique like this, it is easy to see that some products - such as the [{{SERVER}}/products.php?product_id=1049 Phidget Spatial] - are simply not complex at all. Although you could conceivably create problems (such as by using separate power supplies instead of using USB power and connecting the grounds incorrectly, or by using really long wires), this would be an exceptional case.

Other Phidgets can be more easily used incorrectly without realizing it. These are often devices that are simple in some systems and yet complex in others. Your primary defense against designing unreliable systems is to draw the system out and identifying any problems using the concepts in this primer. To help you, however, you can generally think of two classes of Phidgets which usually need careful handling when they are part of complex systems:
# Phidgets with more than one power source, (these can be subject to the [[#Shared Grounds|multiple power source problems]] described above)
# Phidgets needing precise measuring of an external power source (these can be subject to the [[#Shared Grounds|multiple power source problems]] ''and'' [[#Precise Voltage Control|precise voltage control]] problems)

Expanded into individual products, the Phidgets which are most often affected are.....

# These Phidgets use a second type of external power:
#* Motor controllers
#**{{LinksNeeded|DC Motors and Controllers|[[DC Motor and Controller Primer|DC controllers]]}}
#**[[Stepper Motor and Controller Primer|Stepper controllers]]
#**{{LinksNeeded|Servo controllers|[[Servo Motor and Controller Primer|Servo controllers]]}}
#* Pure relay boards
#**[[Solid State Relay Primer|Solid state relay boards]]
#**[[Mechanical Relay Primer|Mechanical relay boards]]
#* Interface kits with relays
#**[{{SERVER}}/products.php?product_id=1017 1017 - PhidgetInterfaceKit 0/0/8]
#**[{{SERVER}}/products.php?product_id=1014 1014 - PhidgetInterfaceKit 0/0/4]
#* Powered Digital Output Interface Kits
#** [{{SERVER}}/products.php?product_id=1012 1012 - PhidgetInterfaceKit 0/16/16]
#* Interface Kits with Powered Hubs
#** The [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer]
#** [{{SERVER}}/products.php?product_id=1019 1019 - PhidgetInterfaceKit 8/8/8 w/6 Port Hub]
# And these Phidgets may have a need to be sensitive to external power:
#* {{LinksNeeded|Thermocouple|[[Temperature Sensor Primer|Thermocouple]]}} control
#* Analog Output ([{{SERVER}}/products.php?product_id=1002 1002 - PhidgetAnalog 4-Output])
#* Frequency Counter ([{{SERVER}}/products.php?product_id=1002 1054 - PhidgetFrequencyCounter])

==Conclusions==

This page should have helped you to:
*Choose a power supply from either the [[#Wall Power|wall]] or a [[#Battery Power|battery]]
*Properly [[#Ground|ground]] and/or [[#How To Fix This|isolate]] that power supply from looping through other circuitry
*Also use [[#How To Fix This|isolation]] to make your control or measurement system more precise
*Keep your cables short and thick to reduce electromagnetic emissions and limit voltage drop
*Be more aware of system-wide power problems in general, and use drawing and analysis of systems to identify problems

==Glossary==
===Memory Effect===
Memory effect is an effect observed in NiCd batteries that causes them to hold less charge. It pertains to the specific situation in which NiCd batteries lose their maximum capacity if they are repeatedly recharged without being fully discharged. The battery appears to remember the smaller capacity. The term is often misused in cases where other batteries seem to hold less charge than originally, however this is most likely due to age and use. This phenomenon is unique NiCd batteries.

Electricity Primer

2012-06-29T21:51:33Z

Cora: /* Affected Products */

[[Category: Primer]]

==Introduction==

Design of reliable systems is really, really hard. The main challenge is the design of reliable building blocks - i.e. circuit and board layouts - from which to create your system. Phidgets does the majority of this work for you. And, once you have reliable building blocks, designing a reliable system from them is much easier.

However, you can still make an unreliable system out of Phidgets. In fact, if you are building a more complex system than the common examples we show through our documentation, and you have limited experience in complex electrical design, you will probably - and unintentionally - introduce design flaws that will make your system unreliable.

There are two reasons why you should read this primer:
# You want to build a complex system, more complex than we illustrate in our documentation. To succeed, you need to understand concepts.
# You understand how to make your system work, and you want to ensure it is well designed for maximum reliability and/or precision.

==The Basics==

To understand our discussion of potential problems and their solutions below, you'll need to be familiar with the basics. For this page, 'being familiar' means more than simply having heard of voltage, amperage, and power. You will need to have a working, conceptual model in your head, so that you can apply that model to your own system and examine it for problems. This section is all about giving the tools to build that mental model.

First, some terminology. We introduce it by analogy. If a circuit is a water system,
* The '''voltage''' is the ''pressure'' in the system
* The '''power supply''' is the ''pump'' creating the pressure
* The '''amperage''', also known as current, is the amount of ''flow''
* The '''load''' is the ''faucet'' - adjusting your load will adjust the flow
* The '''resistance''' is an attribute of the load - how tight or loose the faucet is
* The '''ground''' is the return path from load to pump.

The basic concepts for all of these terms are presented below.

===Load===

We start with the load, because the load is the purpose of your entire system.

In simple, USB-only Phidget systems, the load is the Phidget itself. The USB port is ready to provide power, but it does not (and cannot) until a load is applied (i.e. the Phidget is attached) and the circuit is completed.

Without a load that connects in a loop, it is like attaching a closed pipe to your pump. Initially, water will fill the pipe, and pressurize it, but once the pipe fills the system as a whole will do nothing more. To allow the pump to drive the load, and the flow to supply the load, we need to have a completed circuit, like this:

[[Image:elec_flow.png|150px]]

The load and the pump must '''match'''. If the load lets too much flow through, the pump will work too hard and burn itself out. This is what happens when you short circuit a power supply. The load is then simply a wire, which basically opens the flood gates and drains your power supply pump. The load must not let too much flow through, which it does by '''resistance'''. Likewise, the pump cannot push too hard on the load, or the load will break. This is discussed in-depth as part of [[#Voltage and Amperage|Voltage and Amperage]] below.

===Voltage and Amperage===

Within the flow concept [[#Load|above]], voltage is pressure. Specifically, it is the ''difference'' in pressure between the flow and the return. Voltage is measured in volts, and is denoted by '''V'''.

Amperage - also known as current - is the flow, or the amount of water that moves. At the pump, the amount of current out and the amount of current in are equal. The pressure might vary widely (highly pressurized pipes out, low pressure pipes back) but the ''amount'' of current is always the same. Amperage is measured in Amps, and is denoted by '''A'''.

To match a pump to a load, the voltage and amperage of the power (supply) and load (sink) must line up. We discuss picking a power supply - whether [[#Wall Power|wall mains]], or [[#Battery Power|batteries]] - in the [[#Power Needs|Power Needs section]] farther along in the document, but we need a few more concepts before we get there.

Power supplies - whether wall power or batteries - are usually rated based on voltage and amperage. Voltage is the specification to be the most careful with for circuits. Too much voltage is the same as overpressurizing your pipes - they will burst. In the case of electronics, you device will break.

This can be counterintuitive - in reference to safety (for humans) around electronics, you may have heard "It is not the voltage that will kill you, it is the amperage". Because of this, it may be tempting to think that too high of an amperage will harm your device, but this is not true. Our hearts are very susceptible to amperage but not voltage, hence amperage is considered dangerous for us whereas voltage is not. But a circuit is not like a human body - in a circuit trying to handle a power supply it is the voltage that matters most.

====Set Voltage (No Control)====

Most loads do no power regulation of their own. They simply take the voltage given to them and do useful things with it. You can tell that a pre-designed load (like a Phidget) falls into this category because it gives its voltage need ''as an exact value''. For example, most Phdigets use exactly 5 V of USB power. These loads will also tell you their amperage, which is a flow need that must be met or exceeded. A load will only use as much amperage as it needs.

====Controlled Power====

Some loads change the voltage or current they receive. This can be with the intent to either (a) keep a constant amount of power flowing from a draining power source like batteries, or (b) to modify a common power source (i.e. 12 V at 1 A) into an uncommon power source (i.e. 1 V at 12 A). This process is called '''regulation'''.

You can tell that a pre-designed load (like a Phidget) falls into this "power-regulated device" category because it gives its voltage need ''as a range''. For example, the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer (SBC)] can take 6 V to 15 V.

To understand how this works, take the example of a flywheel. Flywheels are designed to be heavy and to take work in order to get them spinning at speed. But once you have them spinning, you can extract that work later at a more consistent rate:

[[Image:elec_flywheel.png]]

Flywheels can either make amperage or voltage be the more consistent blue line over time. The most common one in Phidgets is for stable amperage. Regulated amperage is also how LED lights can stay consistently bright for any length of time when using batteries. Stable voltage design is usually applied when the voltage is too low to begin with (such as any device that runs on a single AA battery), and the flywheel must amplify and stabilize it over time.

For those readers trying to envision how this works electrically, in practice the flywheel is an inductor (or, a transformer utilizing its inductor properties). For both voltage and amperage regulation, one way relief valves (diodes) must be added. And, in amperage regulation a reservoir (capacitor) must be added to offset the current drop by pulling ''more'' amperage as a battery drains. Then, a controller is needed to measure and then correspondingly enable and disable the flywheel system as the voltage or amperage drops from the supply.

But with those details in place, the inductor (and capacitor, in the case of amperage regulation) can effectively take the variety of voltages from, say, a draining battery, and still allow the board to run. Some devices even do this naturally. For example, motors often can take a variety of voltages because their construction (i.e. wire wrapping) naturally creates inductance.

These regulated systems often list the power they need directly, using a type of power rating called '''watts'''. Watts are voltage and amperage together (i.e. power):

<math>
\text{Amperage} =\frac{\text{Watts}}{\text{Voltage}}
</math>

Watts can be a handy way to describe flow and pressure together for these regulated devices. Rather than separating voltage and amperage like the unregulated devices do (i.e. this load needs exactly 12 V, or this load will draw exactly 2 A), the unit of watts will allow different value combinations of volts and amps as long as the wattage remains the same. For example, a 12 watt device with a voltage range of 5 to 12 volts can run on 6 V at 2 A, or 12 V at 1 A. Either will work. Amperage for all values in the device's range of 5 to 12 V can be found with the equation above. Because of this, watts are often preferred when trying to match a power supply to a regulated load.

===Ground===

All circuits have a '''ground'''. This is simply the return pipe to the pump. In a circuit, it is denoted by an upside-down triangle:

[[Image:ground.png]]

When drawing a circuit diagram, the symbol is placed on the wires that return to the pump:

[[Image:elec_flow_ground.png|170px]]

This electric ground provides a voltage reference throughout the circuit. Ground is always '''0''' volts as far as the circuit is concerned. (Remember, voltage is the ''difference'' between the flow and return pipes at the pump.) Ground is important because it provides a reference from which all the parts of the circuit can speak the same "voltage language" to each other, which matters a lot when a certain voltage means "1" and a certain voltage means "0".

There is only one '''absolute''' ground, and that is the Earth, which is taken to be 0 volts as an absolute value. Circuits not well-grounded to the Earth (of which there are many - your cell phone, car, etc) operate at a '''relative''' voltage. The upside-down triangle above denotes a ''relative'' ground.

With relative voltage, only the difference between local ground and the local high voltage matters. For example, a cell phone might operate as a 3 volt device, which means relative to its ground it always operates between 0 and 3 volts. But if that cell phone were compared carefully to Earth ground, its absolute voltage could be, say, between 10 and 13 volts. Until comparison, the device doesn't "feel" charged. This is the same as how you don't "feel" charged after skidding your feet in socks across a carpeted floor. But, when you "compare" yourself to Earth ground by touching some well-grounded metal, you receive a static electricity shock.

The same thing can happen when you combine two different power supplies, as we discuss [[#Projects With Different Power Sources|below]].

===Power===

There can be different types of pumps, and at this point we should supplant our heart symbol with some actual power supply pump symbols. For example, this is the symbol for a direct current (DC) battery:

[[Image:elec_battery_basic.png|200px]]

The + end is on the out flow, and the - end is on the return (ground). Batteries are usually listed with their voltages. This is because the resistance of the load will determine how much amperage is drawn, but too much voltage and you will harm your load.

This is the symbol for alternating current (AC) that you would get directly from the wall:

[[Image:elec_wall_basic.png|200px]]

Again, this is listed using voltage for the same reasons as DC. A relative ground symbol is still used on the return line here. AC devices can still operate on relative voltage if they do not use Earth ground (the third prong on a wall plug in North America). This is how some loads have AC cords with only two prongs - they operate on a relative voltage and relative ground. And relative AC voltage, having significantly more voltage (pressure) behind it, can really hit a device hard when two power supplies meet across it.

This connecting of multiple power supplies is quite a complex subject, and is described further in both [[#Power Needs|picking different power supplies]] and [[#One Powered Phidget|connecting different power supplies]] later on in this Primer.

===Emissions and Wires===

To talk about emissions, it is worth speaking more precisely about what a load is. The typical, simple Phidget setup is receiving 5 V direct current (DC) from the computer over the USB port. Let's model this as coming from a battery so that we can examine all parts of the system. From the point of view of the battery, the Phidget load is not just the green board with the circuitry on it. The load ''also'' includes the power cable (i.e. two wires in the USB cable), and anything else on the path out or back from the circuitry to the battery itself:

[[Image:elec_phidget_basic.png|200px]]

This is important because the wires play a role in the voltage that eventually makes it to the Phidget. This is true all the time, even when the Phidget is attached to a computer instead of a battery. All wires have some resistance, and so they are, in a way, in and of themselves circuits. Therefore, because of their resistance, the wires 'use' some of the 5 V heading out to the Phidget circuit board. This is discussed more below, but essentially longer cables have more resistance and at some point the voltage will drop so much over the length that the Phidget will not turn on.

To conceptually separate the wires from the Phidget in terms of the load, we can now start drawing the wires themselves in our circuit diagram, instead of the curved concept arrows indicating flow and return:

[[Image:elec_phidget_wires.png|200px]]

When talking about the 5V relative ground in this system, we are in fact talking about the ground ''right at the battery'' so we move the ground symbol to the battery itself.

Then, the resistance on these wires creates a possible problem - the emission of electromagnetic radiation as the wires naturally drop the voltage:

[[Image:elec_phidget_emissions.png|200px]]

These emissions are at a set frequency determined by the length of the wire:
* Long wires create low frequencies (harmful interference)
* Short wires create high frequencies (less harmful interference)

This can be minimized by having the flow and return wires be the same length and sit right next to each other. This way, the emissions somewhat cancel each other out from the flow and return going in opposite directions. This is partially how USB cables minimize emissions.

So, the way you design your connections (i.e. the resistance and placement of your wire) will have a direct affect on:
# The voltage that reaches the Phidget
# The emissions that your system produces

With all this talk of emissions, you might be tempted to try to shield parts or all of your system from emissions that either your system or external systems create.

Keep in mind that shielding is actually really hard to do correctly. Especially when grounding your shielding, with ad-hoc design you have a high chance of having an interfering signal (that has traveled out to the shield and traveled back via ground) creating a larger problem than not having a shield at all. Rather than shielding, it is easier to simply keep your cables short and with as low a resistance as possible throughout your system to minimize your emissions in the first place.

Identification of and solutions to these (and other more complex) problems are discussed in detail in the [[#Selecting Cables|section on choosing cables]] and the [[#Hooking Up The Pieces|section on connecting the pieces]] below.

===Multiple Loads===

The easiest way to hook up multiple Phidgets is in parallel, where the voltage stays the same but they share the amperage. Here the DC supply is two USB ports, each at 5 V and 0.5 A:

[[Image:elec_phidget_parallel.png|250px]]

However, the length of your wires comes into play again, because the voltage that actually reaches the Phidgets above is somewhat less than 5 V. So if your wires are long, or mismatched, the voltage may not match and will give you strange results. The voltage is both affected on the way out, and on the way back. Assuming the wires are the same length:

[[Image:elec_phidget_wire_drop.png|350px]]

In this way, you can create difficult-to-debug problems within a complex system, where one Phidget works but others mysteriously fail.

==Power Needs==

Now that you've understood the basics, it is time to actually talk about decisions and design. This section will help you choose a power supply for your Phidget. Let's say you want to run the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer] off of a battery. Or you want to run a motor controller with a power supply you bought from the hobby store. What do you need to buy? Will one you already have work? It is worth it to spend a moment with pencil and paper to work through this section and identify your power needs.

As described [[#Voltage and Amperage|earlier]], voltage is pressure. Too much pressure behind your faucet, and the water mains or faucet will break. Likewise, if you have too much voltage from a power supply, your circuit will break. You should choose a supply with voltage that ''matches the range the Phidget can accept''. The voltage cannot be over the maximum (otherwise, like pressure in a pipe, the pipe will burst), and the voltage cannot be under the minimum (otherwise, like pressure in a pipe, no flow will occur). Also, generally, a device (like a motor controller) will perform better at its maximum rated voltage if a range is available.

But the faucet doesn't care whether there is a big reservoir or small reservoir feeding the system, as long as the pressure is managed. Likewise, you can choose a power supply with more amperage than you need (a big reservoir to draw from) as long as the voltage matches. In the same way that a faucet restricts water by design, loads draw and allow only the amperage that they need. However, the amperage cannot be less than the Phidget needs. In that case, you will either overextend (and break) your power supply, or the circuit simply will not turn on at all.

The specification [[#Device List|for your specific device]] will list its power needs. For most devices, the external power supply needs will simply be listed in voltage and amperage. USB power is 5V at up to 500 mA (0.5 Amps). Most Phidgets will draw less than this - if you need precision, you can check the specification for your particular Phidget. And, if it is an Interface Kit, you can add the draw of each analog sensor and digital in/out from their specifications.

However, some Phidgets (e.g. motors, and the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer]) do not have a straight amperage and voltage specification. Instead, their power draw will be listed in watts, for which you [[#Voltage and Amperage|saw a relation earlier]] to convert to the values you need.

===Wall Power===

Wall power sources usually take the alternating current (AC) from the wall and convert it into a direct current (DC). These power supplies often take your familiar two-or-three prong wall connector and put power out via a barrel plug-type connector. AC power (typically 110 or 240 volts, depending where you live in the world) goes in the typical wall plug, and DC power (typically 5 to 24 volts) comes out the barrel plug. Most power supplies of this type list the conversion explicitly, such as: 110-240 Volts to 12 Volts at 2 Amps. You'll want to match your Phidget's needs against the 12 Volts at 2 Amps.

*The voltage must match exactly
**If the Phidget takes a range of voltages, the supply must fall within the range
*The amperage can be equal to or greater than the Phidget needs

A wall power supply is essentially an inexhaustible supply of current, so you don't need to worry about it running out like you would with batteries.

===Battery Power===

If you intend to use a battery bank (even of only one battery) to power your Phidget, you probably want to know what type of battery to purchase.

====Battery Chemistries====
The first thing that sets batteries apart is the type of materials used in their construction. The following table shows several of the more common battery chemistries as well as the voltage per cell they produce and the specific energy of the chemistry.

{| border = 1
| align="center" style="background:#f0f0f0;"|'''Chemistry'''
| align="center" style="background:#f0f0f0;"|'''Nominal Cell Voltage'''
| align="center" style="background:#f0f0f0;"|'''Specific Energy (MJ/kg)'''
| align="center" style="background:#f0f0f0;"|'''Description'''
|-
| align = "center" colspan = 4|Primary Batteries
|-
| Alkaline||1.5||0.4||These are the most common form of battery. Many commercially available AA and AAA batteries are alkaline.
|-
| Lithium (LiMnO2)||3||0.83-1.01||These are used in high drain devices or devices with a long shelf life as they have a very low self discharge rate.
|-
| Silver-oxide||1.55||0.47||Only used in small button cells as these are quite expensive.
|-
| align = "center" colspan = 4|Secondary Batteries
|-
| NiCd||1.2||0.14||Older technology, suffers from [[Electricity Primer#Memory Effect|memory effect]]. Capable of very high discharge rates with no ill effects. Moderate self discharge rate.
|-
| Lead-acid||2.1||0.14||Not particularly good with high discharge rate. Moderate rate of self discharge.
|-
| NiMH||1.2||0.36||Very heavy. Good performance in high drain devices. Very high energy density naturally, at the cost of a high self discharge rate. Newer versions are able to get rid of some of the self discharge though they suffer ~25% lower energy densities as a result.
|-
| Lithium Ion||3.6||0.46||Expensive to produce but very high energy density. Very low self discharge rate. Safety hazard as short circuiting can yield explosive or fiery results.
|}

====Choosing a Battery====
Batteries are chosen first by their voltage (V). Match the voltage exactly to the voltage the Phidget needs. Over or under this value, you could harm the board or have it simply fail to turn on.

Next, choose a battery that has adequate amperage to feed your device for the time you need. The lifespan of the battery will usually be listed in Amp-Hours (or Ah). For example, a double wide 12 V lantern battery will have usually around 7-8 amp hours. This means if you drew one amp from it for seven to eight hours, the battery would be totally drained. Or you could draw two amps from it and drain it in 3.5-4 hours. This does not mean however, that you can draw 36A for 15 minutes. It is important to understand that there is a limit at which more power simply cannot be drawn from the battery. Effectively, high drain devices will decrease the rated Ah. The amount differs from battery to battery so to be sure it is recommended to check the data sheets for the battery you are using. If the battery did not come with a data sheet they can usually be found on the manufacturers website. The data sheets should have a graph that shows the relationship between current draw (usually in mA) and capacity (Ah or mAh). Another useful thing that can be gathered from the datasheets is the batteries response to temperature. Batteries tend to not work as well in cold environments, most manufacturers will provide graphs of how the batteries lifespans will shorten at different temperatures. This is often very significant, causing the battery to last a fraction of its normal lifespan at temperatures below -10°C.

Finding the amperage or voltage sometimes needs to be done indirectly by using a specification of watts. The relationship between amperage, voltage, and watts is given above in the [[#Voltage and Amperage|voltage and amperage section]].

For an example, let us say you want to use battery power to run the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer]. The specifications say that it uses 1.2 watts as a base value. The specifications also say that it can take 12 V DC power. If we choose to use a 12 V battery, at 1.2 watts it will use 0.1 amps according to the equation [[#Voltage and Amperage|shown earlier]]. Going by amp-hours alone, if our battery is a double-wide lantern type 12 V battery, with 7 amp hours, with 0.1 amp draw it will last 70 hours, or almost three days.

<math>
\text{Maximum Running Days} =\frac{\text{Battery Amp Hours}}{\text{Device Amps} * \text{24}}
</math>

However, to estimate ''average'' running time (rather than maximum running time possible), amp-hours cannot be used so directly. Over time, batteries decrease in voltage as their power is used up. Practically speaking, this means one of two things for your load. For loads that do not regulate voltage or current, the amperage will also decrease over time. The classic example is an LED light source that grows dimmer and dimmer as the batteries are used up.

You should usually only count on about 60% of the stated amp hour rating to apply before expecting to run into problems from escalated drain due to battery voltage drop. This is especially true for deep cycle rechargeable batteries left in an installation, where draining more than 60% could also harm the battery.

Then, for lead-acid batteries, a typical battery is tested from full to complete drain over 20 hours by the manufacturer to obtain the advertised amp-hour rating. Draining a battery at a faster rate than this will result in even more reduction in capacity, by 10% or even more. This due to [http://en.wikipedia.org/wiki/Peukert%27s_law Peukert's Law].

There are plenty of [http://www.google.ca/search?&q=battery+calculator battery calculators] around the Internet which take most or all of these additional factors into account when recommending an amp-hour rating. For longer-term installations, the solar power online community has some excellent resources.

====Setting up Multiple Batteries====
You can hook up multiple batteries in series to get more voltage at the same amperage. The amperage is additive. For example, you can hook up two single-wide 6 V lantern batteries in series to produce 12 V. Or two 12 V batteries in series to produce 24 volts. This system would still only have the amp hours of ''one'' of the lantern batteries, because you will be essentially using them both at once:

[[Image:elec_battery_series.png|250px]]

The upside down triangle (ground) is explained above in a [[#Ground|section of its own]].

Or, you can hook up multiple batteries in parallel to get more amperage at the same voltage. For example, you could hook up two 12 V deep cycle batteries in parallel to provide more amperage at 12 V, which is like having a deeper reservoir of power for your device to use:

[[Image:elec_battery_parallel.png|250px]]

====Heat====
*all batteries have some sort of internal resistance
*can be found on the battery's data sheet
*the more power you pull from the battery the more heat is going to build up as a consequence of the internal resistance.
*larger internal resistances will cause heat to build up faster.
*when charging a battery you are not just limited to the power in the battery. nothing stops you from dumping energy into the battery past the point where it is fully charged
**this is why charging batteries is a bit of a tricky business.
**many batteries come with custom chargers that have control systems to prevent this type of overcharging.

====Weight====
Finally, weight matters - a car battery is much heavier than a lantern battery. Batteries vary widely by weight per amperage. Lithium batteries are usually very light for their power, followed by alkaline, followed by lead acid. This may not seem important at first, but if you are building a mobile robot it is worth calculating in the work of carting around a battery. You may find that, for the length of time you want it to run, your battery requires some system redesign.

==Selecting Cables==

===USB Cables===

In general, use the shortest cables possible. There are many reasons for this [[#Emissions and Wires|described above]], but as a summary:

; Long cables reduce the voltage that reaches the Phidget.
: This happens in both directions. So, for every unit cable length added, the voltage decreases by twice the electrical resistance of that length of cable. With especially long cables the Phidget may drop below its 4.6 volt threshold and simply never turn on.

; Long cables increase the width of your circuit.
:All circuits act as emitting antennas for the resonance frequency of the circuit structure. The longer the wires in the circuit, the lower the frequency, and the higher chance that it will be emissions that will interfere with your data and system.

; Longer cables have more length exposed to external interfering emissions.

Also, use thick cables that are built to specification. Some USB cables with thinner wiring have higher electrical resistance. This can be equal to what a much longer wire would have, and thus create a similar voltage drop where the Phidget will not turn on.

====Options for longer cables====
The maximum length for a USB cable is 5m. This is laid out in the USB specifications. Often times however a system requires more reach. In this case there are a few options available to you. You can use what is known as an active extension cable or USB extender. These cables act like extension cables and add power to the line so that the signal can travel further. A second option is to use a Cat5 extender. These extenders are 2 USB dongles that connect on either end of your system. You join them up with Cat5 cable. This allows you to run over much longer distances than USB traditionally allows.

===Power Cables===

There are "DC Wire Table" references on the Internet which describe how to pick a wire appropriate for your voltage and amperage. When selecting AC wires, you will probably be using pre-made extension cords. Cords add interference resonance length to your circuit, just like USB cables do as [[#USB Cables|described above]]. A long extension cord can create huge electromagnetic interference for your circuit and other systems in the area when first plugged in.

Also as with the USB cables above, cut the cables to the shortest length possible. This is again both for voltage drop reasons and frequency emission reasons.

===Hubs===

Avoid hubs where possible. Unpowered hubs are good for reading data from memory keys, but not for powering many external devices. If you must use a hub, buy a powered one.

===Sensor and Motor Wiring===
All Phidgets sensor class devices (products whose part numbers start with 11 such as the 1129) use a 3 channel ribbon cable for power and data transmission. Similarly, all our motors and load cells use multichannel wire interfaces. As mentioned previously, USB spec limits cables to 5m, this is not the case for these wires. The biggest concerns are electromagnetic interference (EMI) and voltage drop. In general you should be able to run these wires over significant distances (30m or more) with the load cells in particular having very long range. If EMI starts causing issues you can always use ferrite beads on the cable near the sensor or motor and the controller to reduce noise.

===Cable Gauges for Terminal Blocks===

Many Phidgets products feature green terminal blocks that use screws to hold wires in place, making it easy to take apart and rebuild connections in your project. The size of the terminal block determines the gauge of wire you should use.

{|border=1
|+'''Terminal Block Size and Wire Gauge'''
! Terminal Block Width (mm/port)
! Recommended Wire Gauge (AWG)
|-
| 3.81
| 14 to 26
|-
| 5.0
| 12 to 26
|-
| 9.5
| 10 to 26
|-
|}

The gauge of cables and wires is measured in AWG, which is the American Wire Gauge standard. The following table lists the properties of wire gauges commonly used with Phidgets:

{|border=1
|+'''American Wire Gauge Sizes'''
! AWG Size
! Diameter (mm)
! Area (mm²)
|-
| 10
| 2.588
| 5.26
|-
| 11
| 2.305
| 4.17
|-
| 12
| 2.053
| 3.31
|-
| 13
| 1.828
| 2.62
|-
| 14
| 1.628
| 2.08
|-
| 15
| 1.450
| 1.65
|-
| 16
| 1.291
| 1.31
|-
| 17
| 1.150
| 1.04
|-
| 18
| 1.024
| 0.823
|-
| 19
| 0.912
| 0.653
|-
| 20
| 0.812
| 0.518
|-
| 21
| 0.723
| 0.410
|-
| 22
| 0.644
| 0.326
|-
| 23
| 0.573
| 0.258
|-
| 24
| 0.511
| 0.205
|-
| 25
| 0.455
| 0.162
|-
| 26
| 0.405
| 0.129
|-
|}

==Hooking Up The Pieces==

Here, things can be tricky. You might think: just plug everything in and go! But often it is not that simple. Many Phidgets require special care when hooking up. We encourage a process where you apply the concepts in this Primer, through analysis, to your system. So, we don't explicitly list the boards most commonly affected until the [[#Affected Products|end of this Primer]].

The ''categories'' of the boards which require special attention within a complex system are:

# Phidgets with more than one power source, and
# Phidgets needing precise measuring or control of an external power source

If you are already thinking about your boards in your head and trying to figure out whether they fit into one category or another, you're on the right track! The list of [[#Affected Products|commonly affected boards]] are only the common ones... with a sufficiently complex system, you could conceivably create problems with ''any'' boards.

Both types of projects require a full understanding of [[#The Basics|electrical basics]]. Using those concepts, below we first describe problems that arise when hooking up different power sources, and extend that into using the solution to give more precise measurement and control.

===Shared Grounds===

Shared grounds can occur in Phidgets that handle two different power sources. Recognizing the sharing of a ground is not always easy. We show what it is, how it can be possible, and why it creates problems by starting with the most basic Phidget system. The simplest setup for a Phidget is to use the [[#Ground|ground]] of the computer it gets data and power from over a USB port:

[[Image:ground_simple_case.png]]

In this case, there is only one relative ground, and it is the PC ground, which is ground #1 in the image. The PC ground determines what is considered 0 volts for all signals on the Phidget. When you add different power sources or sinks in the system, you are pulling the system relative to the PC ground.

=====One Powered Phidget=====

The next most complicated system is one Phidget that handles two power sources. Let us say you have a motor controller, which takes power from USB, and which also takes power from a second power source. Although the second power source is usually just a wall plug, the simpler case for thinking about ground is actually a battery. A battery creates a second ''relative'' ground. Through the Phidget, relative ground #1 (from the PC) and #2 (from the battery) actually become the same ground:

[[Image:ground_wall_power.png]]

This is the first reason why systems with powered Phidgets have to carefully manage ground. If ground #1 and ground #2 are different with respect to each other (see the static shock analogy in the [[#Ground|ground section]] above), then whatever circuitry along the red dashed arrow must deal with the initial static shock. In this case it would be the circuitry of the Phidget. In the case of a battery, after the initial equalizing shock the battery will be whatever relative voltage the PC ground needs it to be. Hence a battery relative ground can 'float'.

If ground #2 comes from the wall, on the other hand, the ground does not 'float' and instead is always absolute 0 volts Earth ground. With the PC giving the power, this is not a problem in practice because the PC can also float (as with a laptop), or it uses Earth ground. But if you were using a different and more powerful USB power supply instead of a PC, and then connected it to the absolute Earth ground through the Phidget, the Phidget would bear the brunt of any ground equalization that would occur. If neither the new ground nor the old ground float, and the power supplies were powerful enough, this would eventually destroy the Phidget. In this case, you would want to use isolation, as described in [[#How To Fix This|How To Fix This]] below.

=====Multiple Powered Phidgets=====

A worse case comes in when you are using two powered Phidgets and one external power source. Again, say you are using a battery as the external power source. It would be tempting to simply wire both grounds from the Phidgets to the ground on the battery:

[[Image:ground_two_phidget.png]]

Although this looks benign, you have actually created a new circuit. The circuit is a second path, via ground, for the current to return to the voltage source. This is also known as a '''ground loop'''. The path we intuitively think of the current returning by is '''<span style="color:blue;">path A</span>''', but the sharing of grounds has created a new path through the motherboard, '''<span style="color:red;">path B</span>''':

[[Image:ground_two_paths.png]]

All current gets 'pumped' in a loop by voltage, and so it will use all return paths available to it, assuming all paths are equally easy (electrically) to use. This extends the pipe analogy, where water will flow in every path that exists. So, if your battery (or other power source with ground #2) is quite powerful, you can actually harm your motherboard within your PC (or at least your USB bus ground), because '''<span style="color:red;">path B</span>''' runs through the motherboard circuitry on the way back to the voltage source.

This problem does ''not'' apply to using a different power source between a black power plug and for the green control terminal block on, say, a [[DC Motor and Controller Primer|DC motor controller]]. Although the grounds are connected, and they run across a part of a Phidget board, creating a ground loop does not actually run through any circuitry if only these types of boards are used. If you have a complex system with other types of boards and therefore circuitry between black plug power port and green terminal block connections, draw out your system carefully to identify the loops.

Ground loops can be fixed by one of the ways described in [[#How To Fix This|How to Fix This]] below.

=====Single Board Computer And Powered Hub=====

When combining one externally powered Phidget and the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer] or the [[Product - 1019 - PhidgetInterfaceKit 8/8/8 w/6 Port Hub]] on the same external power source, you still may inadvertently create a ground loop as described above in [[#Multiple Powered Phidgets|the multiple powered Phidgets section]]. If they share a true [[#Ground|Earth ground]], this is not a problem. But if the ground is from a battery, or uninterruptible power supply, etc. then you should carefully draw out your system circuit and examine it for ground loops.

====How To Fix This====

Once you are aware of shared grounds in your system, you have two options.

One, for ground loop problems in simple systems (two Phidgets), you could make the normal return path ('''<span style="color:blue;">path A</span>''') the most electrically desirable path. This is best for simple systems where you have a lot of control over all of the ground wires within your system. For the ground wires leading directly from the Phidget to the external power supply ('''<span style="color:blue;">path A</span>'''), lower the resistance in the wire as much as possible. You can do this by keeping the wires short, and using a thick (large gague) wire for the hookups.

Although this solution works, sometimes you do not have much choice on how long your ground return wires can be, because the location of your power supply and and Phidgets are set by your system design. If you cannot be totally sure that the direct ground path is the shortest and most electrically desirable path, it is best to use the second option: a '''USB Isolator''' such as the [[Product - 3060 - USB Isolator|Phidget 3060]]. This isolator is like any other USB isolator - it can be used on a Phidget system, as well as any system that needs ground isolation.

You need isolators for every USB cable in your system, less one. If you have two USB connections, you need one isolator; three USB connections, two isolators, and so on. The one USB connection can remain non-isolated because a single ground connection cannot form a loop. However, if you are concerned about connecting the grounds as described in the [[#One Powered Phidget|single connected Phidget section above]], use a USB isolator on every cable.

===Precise Voltage Control===

Precise voltage (or other system) control and measurement is related to the concept of [[#Shared Ground|shared ground above]]. But here, you want to keep grounds separate not only to prevent ground loops, but also to make your system more sensitive to what it will control or measure.

For example, we make Phidgets that can create power precisely, or that can take it in and measure it. One such product is the 1002, which outputs a precise analog voltage with which to control an analog system. Now that you know about [[#Ground|relative ground]], however, you would be right to expect that you do not want to combine the ground in the PC and the ground in the system.

Even if you don't care about system sensitivity, you can still create [[#Multiple Powered Phidgets|ground loops]] in a system with multiple of these types of Phidgets. In addition, if you are using the Phidget to control a large, powerful system, even a single Phidget can receive damage from connecting two powerful power sources meeting across it, also as [[#One Powered Phidget|described earlier]].

But above and beyond the powered Phidget problems, there is another reason to separate (isolate) the electrical grounds in your system. The reason is: to make your system control more precise. For example, with the 1002, if you are trying to control an external system with an Phidget output voltage, that output voltage should be relative to the ''system you are trying to control'', not relative to the PC. Rather than forcing the grounds - and therefore the relative voltages - to be equal to each other, you can provide more precise control by isolating the grounds and working with the relative voltage of the controlled system on its own terms.

<span style="color:red;">Schematic-type image of a ground isolated analog out on a 1002</span>

====How To Fix This====

The solution to all of these problems in precise voltage control systems is to use USB isolation, even for a single Phidget. The [[Product - 3060 - USB Isolator|Phidget 3060]] is one such isolator. It inserts along the USB connection between your PC and the Phidget, and it separates the Phidget (and controlled system) ground from the PC ground. This fixes ground loops, separates relative voltage mis-matches, and isolates the control system for better precision.

<span style="color:red;">Image of 1002 and Isolator connected, with lines superimposed on the image to show non-copper connection in isolator</span>

==Affected Products==

If you're not sure whether a certain concept applies to your Phidget within a complex system, the best way to figure this out is by doing some mental (or pencil and paper) simulation. Draw the inputs and outputs for the entire board, and label them with voltage, list their required amperage (or watts), and draw connections (such as ground connections) through any circuitry.

With a technique like this, it is easy to see that some products - such as the [[Product - 1049 - PhidgetSpatial 0/0/3|Phidget Spatial]] - are simply not complex at all. Although you could conceivably create problems (such as by using separate power supplies instead of using USB power and connecting the grounds incorrectly, or by using really long wires), this would be an exceptional case.

Other Phidgets can be more easily used incorrectly without realizing it. These are often devices that are simple in some systems and yet complex in others. Your primary defense against designing unreliable systems is to draw the system out and identifying any problems using the concepts in this primer. To help you, however, you can generally think of two classes of Phidgets which usually need careful handling when they are part of complex systems:
# Phidgets with more than one power source, (these can be subject to the [[#Shared Grounds|multiple power source problems]] described above)
# Phidgets needing precise measuring of an external power source (these can be subject to the [[#Shared Grounds|multiple power source problems]] ''and'' [[#Precise Voltage Control|precise voltage control]] problems)

Expanded into individual products, the Phidgets which are most often affected are.....

# These Phidgets use a second type of external power:
#* Motor controllers
#**{{LinksNeeded|DC Motors and Controllers|[[DC Motor and Controller Primer|DC controllers]]}}
#**[[Stepper Motor and Controller Primer|Stepper controllers]]
#**{{LinksNeeded|Servo controllers|[[Servo Motor and Controller Primer|Servo controllers]]}}
#* Pure relay boards
#**[[Solid State Relay Primer|Solid state relay boards]]
#**[[Mechanical Relay Primer|Mechanical relay boards]]
#* Interface kits with relays
#**[{{SERVER}}/products.php?product_id=1017 1017 - PhidgetInterfaceKit 0/0/8]
#**[{{SERVER}}/products.php?product_id=1014 1014 - PhidgetInterfaceKit 0/0/4]
#* Powered Digital Output Interface Kits
#** [{{SERVER}}/products.php?product_id=1012 1012 - PhidgetInterfaceKit 0/16/16]
#* Interface Kits with Powered Hubs
#** The [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer]
#** [{{SERVER}}/products.php?product_id=1019 1019 - PhidgetInterfaceKit 8/8/8 w/6 Port Hub]
# And these Phidgets may have a need to be sensitive to external power:
#* [[Temperature Sensor Primer|Thermocouple]] control
#* Analog Output ([{{SERVER}}/products.php?product_id=1002 1002 - PhidgetAnalog 4-Output])
#* Frequency Counter ([{{SERVER}}/products.php?product_id=1002 1054 - PhidgetFrequencyCounter])

==Conclusions==

This page should have helped you to:
*Choose a power supply from either the [[#Wall Power|wall]] or a [[#Battery Power|battery]]
*Properly [[#Ground|ground]] and/or [[#How To Fix This|isolate]] that power supply from looping through other circuitry
*Also use [[#How To Fix This|isolation]] to make your control or measurement system more precise
*Keep your cables short and thick to reduce electromagnetic emissions and limit voltage drop
*Be more aware of system-wide power problems in general, and use drawing and analysis of systems to identify problems

==Glossary==
===Memory Effect===
Memory effect is an effect observed in NiCd batteries that causes them to hold less charge. It pertains to the specific situation in which NiCd batteries lose their maximum capacity if they are repeatedly recharged without being fully discharged. The battery appears to remember the smaller capacity. The term is often misused in cases where other batteries seem to hold less charge than originally, however this is most likely due to age and use. This phenomenon is unique NiCd batteries.

OS - Phidget SBC

2012-06-29T21:46:02Z

Cora:

[[Category:OS]]
{{OSLang|[[File:icon-Linux.png|64x64px|link=OS - Linux]]|On the Single Board Computer (SBC), Phidgets can be either plugged directly into one of the USB ports or run over a network using the [[#WebService | WebService]].}}
__TOC__

==Quick Downloads==

Unlike our other supported operating systems, the SBC '''does not require downloads''' unless you are doing something advanced like loading the firmware or developing your own kernel. You will know if you need these downloads, otherwise, the SBC should work as described on the [[1072_-_Getting_Started|SBC2 Getting Started Guide]] right out of the box.

*[{{SERVER}}/downloads/libraries/phidgetsbc2.bin SBC2 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
*[{{SERVER}}/Drivers_Info.html#SBC2 License]

Note that, instead of using the firmware to update your SBC, updates should normally be done via the System -> Packages page on your SBC2 web interface. It is rarely necessary to completely re-flash your device.

==Getting Started with the Phidget SBC Debian Linux==

The Single Board Computer (SBC) is a unique Phidget. It is a computer with a Linux operating system. It can compile code, save files, manage background jobs, host information over the web, and more.

'''If this is your first time''' using the Phidget SBC, you will want to start with the [[1072 - Getting Started | Getting Started Guide for the SBC]]. After that, here we will get you started on topics beyond those in the getting started guide, including how to write Phidget code to run on the SBC. You '''do not need this page''' if you are simply using the SBC to broadcast data from Phidgets over the network - it does that automatically. We describe how to verify and use this in the [[1072 - Getting Started | Getting Started Guide]].

This page will show you how to:
* Install the ability to write and develop code on the SBC itself
* Use the command line for basic coding tasks
* Troubleshoot the SBC's network
It will also give additional specifications, which are useful for doing more advanced things with the SBC hardware and software.

Before reading this page, you should have done the following via the Getting Started Guide:
* Set up networking on your SBC, via either Ethernet or wireless
* Set up an admin password
* Learned the IP address or link local address of the SBC
We will use this information in setting up the libraries and drivers to use the SBC for writing and running code.

Conceivably, you could simply use the SBC like any Linux computer, and do all of your development and compiling of Phidget code on the SBC itself. In practice this gets complicated as the SBC does not have a keyboard or screen. So usually, you will want to develop your code an external computer and copy files and settings over to the SBC via a network. This makes this Getting Started section unique, in that we show you how to set up both computers:
* Your [[#Getting Started - External Computer | External Development Computer]], usually your main desktop or laptop which will transfer files and settings to and from the SBC
* The [[#Getting Started - The SBC (Debian Linux) | SBC]] itself, which needs programming language libraries to use Phidgets.

===Getting Started - External Computer===

You have two ways to connect to the SBC from an external computer: via the [[#SBC Web Interface|SBC Web Interface]] and over the more powerful but complex [[#SSH | Secure Shell (SSH)]].

====SBC Web Interface====

You have already worked extensively with the web interface in the [[1072 - Getting Started | Getting Started Guide for the SBC]]. This was the tool within a web browser which was opened either via the Phidget control panel on Windows, or by simply entering the IP or link local address into an internet browser. It allowed you to set the password, set up internet connectivity, and so on.

This section doesn't have more information on the interface; rather, it simply serves as a reminder that you have the web interface as an available tool. Examples, including screenshots, are placed where appropriate in this document. The web interface will probably stay your initial go-to way to connect to the SBC, especially for tasks that benefit from graphical interaction, like setting up wireless or using the webcam.

====SSH====

The most flexible way to transfer files and commands to and from the SBC is via a program called '''ssh'''. The ssh program provides command line text access over a network into the SBC. Using it, you can run programs and give the SBC commands. The ssh program has a companion program called '''scp''' which can copy files back and forth. If you are unfamiliar with ssh, you can think of it like the command line or a Mac terminal, but with a remote connection to a different computer. It is a minimal yet effective way to interact with a remote computer.

Before connecting over ssh, you will need:
* The '''IP address''' (such as 168.254.3.0) or '''link local address''' (such as phidgetsbc.local) of the SBC
* The '''admin password''' for the SBC
Both of these items can be found by following the steps in the [[1072 - Getting Started | Getting Started Guide for the SBC]].

You will also need to enable SSH on the SBC side. This can be done through the [[#SBC Web Interface| Web Interface]], under {{Code|Network → Settings}}, by changing the ''SSH Server'' radio button to ''Enabled'' and saving your changes:

[[File:sbc_turn_on_ssh.png|link=|alt=]]

=====SSH on Windows=====

The ssh program is not installed on Windows by default. But, there are a variety of SSH programs available for free. One simple and commonly used program is [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY], and it has the advantage that the executable doesn't need to install, it just runs.

With PuTTY, when you first run the program it will ask you what to connect to. Enter the IP address or link local address of the SBC, and then click the SSH radio button right below the address, which will change the port to 22. Then click open, and you'll have an ssh connection to the SBC open in a terminal. It will prompt you for a user name ({{Code|root}}) and password (the admin password).

To copy files back and forth, there is an SCP component to PuTTY, called PSCP, which is available from the same [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY download page]. Use of PSCP will be similar with the address, username, and password, except that you will be transferring files instead of sending commands.

=====SSH on Linux and Mac OS=====

Linux and Mac OS already have ssh installed by default. To run ssh simply open a terminal...
* {{Code|Ctrl-Alt-T}} on Linux
* {{Code|Applications → Utilities → Terminal}} on Mac OS
...and type:

<div class="source">
<syntaxhighlight lang=bash>
ssh root@phidgetsbc.local
</syntaxhighlight>
</div>

If you have re-named your SBC, include that name instead of the {{Code|phidgetsbc.local}} link address. Or, you can use the SBC's IP address, e.g. something like {{Code|ssh root@168.254.3.0}}

To copy files back and forth, the command follows the form of: {{Code|scp from to}}

So, to copy a file {{Code|/root/data.txt}} from the SBC to your local machine, type:

<div class="source">
<syntaxhighlight lang=bash>
scp root@phidgetsbc.local:/root/data.txt .
</syntaxhighlight>
</div>

Note the use of the dot '''.''' to indicate that scp should put the file in the current local directory. If you're not sure what folder the terminal is operating in type {{Code|pwd}} to print the working directory. Terminals usually start by default in your home folder.

===Getting Started - The SBC (Debian Linux)===

The SBC runs Linux, which is a full operating system. It is stripped down compared to a full desktop release of Linux, but you can compile code on it, run programs, schedule tasks, create and manage files, run a web server, and much, much more.

At this point you have connected to the SBC via the [[#SBC Web Interface|web interface]], and probably also through [[#SSH|SSH]]. This section will help you install libraries and drivers that you probably want - i.e. support for C, Java, and Python. After this section, you'll be well into the depths of using the SBC as a computer, and so you'll probably want to keep the [[#Using SBC Linux|Using SBC Linux section]] open for reference while you work if you are not already familiar with Linux.

The SBC comes with the following Phidget functionality installed:
* The Phidget C libraries {{Code|libphidget21.so}}
* The Phidget [[#WebService | WebService]]
(If you are simply curious what these are and how they get installed, we describe the process on the [[OS - Linux | general Linux page]].)

But to compile C programs, or run Java programs, or use Python, you will need to install these languages onto the SBC.

Before installing anything on the SBC, however, (even via a button on the web interface) make sure that the ''Include full Debian Package Repository'' option is checked in the web interface under {{Code|System → Packages}}.

====Installing C/C++ and Java====

The simplest way to install C/C++ and Java on the SBC is via the web interface. There is a button under {{Code|System → Packages}} to install C support (including {{Code|gcc}}) and another button to install Java support:

[[File:sbc_packages_web.png|link-|alt=]]

Now you're ready to begin programming. We have programming pages for both [[Language - C/C++|C/C++]] and for [[Language - Java|Java]]. Remember that if you're unfamiliar with Linux, we have help on using files and running programs automatically in the [[#Using SBC Linux|Using SBC Linux section]].

If you want to avoid using the [[#SSH|SSH]] interface on the SBC entirely, and you want to write your program in Java and run it continuously from boot (which is the only option if you want to avoid [[#SSH|SSH]]), we have a [[#Program in Java with the Web Interface|very in-depth section]] on that topic.

====Installing Python====

Installing Python has two steps. First, you'll need to install the basic ability to run python, and then you'll need to install the Phidget Python module. Both steps (and both options) require that you issue the relevant commands through an [[#SSH|SSH terminal]].

=====Basic Python=====

The base Python functionality can be downloaded and installed in one step with [[#apt|apt]] (i.e. in a terminal, type):

<div class="source">
<syntaxhighlight lang=bash>
apt-get install python
</syntaxhighlight>
</div>

This will give you Python, and now you just have to install the Phidget Python module to gain Phidget functionality.

=====Install Phidget Python Method 1: Use a USB Key=====

Copy the [{{SERVER}}/downloads/libraries/PhidgetsPython.zip Python Libraries] onto a USB key. Unpack the zip file into a folder on the USB key. Insert the key into the SBC.

You will have to figure out where the USB key (and the Phidget Python library folder) is now located. We describe how in the general [[#Using USB Data Keys | Using USB Data Keys]] section.

After you know the place where the USB key is mounted, in a terminal go to that directory (e.g. type {{Code|cd /media/usb0/}}), enter the unpacked Phidget Python Library folder, and run:

<div class="source">
<syntaxhighlight lang=bash>
python setup.py install
</syntaxhighlight>
</div>

Now, you're ready to begin writing Python code for the SBC. For more help on writing and using Python with Phidgets, we have an whole [[Language - Python | page on that topic]]. Remember that if you're unfamiliar with Linux, we have help on using files and running programs automatically in the [[#Using SBC Linux|Using SBC Linux section]].

=====Install Phidget Python Method 2: Use the Internet=====

Rather than using a USB key to transfer the file, the SBC can download it directly from the internet. You will need {{Code|wget}} and {{Code|unzip}} installed, both of which are small:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install wget
apt-get install unzip
</syntaxhighlight>
</div>

Copy the web link address for the [{{SERVER}}/downloads/libraries/PhidgetsPython.zip Python Libraries].

In an SSH terminal to the SBC, type: {{Code|wget http://www.python_library_link}} where instead of http://www.python_library_link you insert the link you just copied. Copying into a terminal can usually be done via the right-click menu.

This will download the Phidget python libraries to the folder you ran the {{Code|wget}} command in. Unzip the downloaded file using the command {{Code|unzip file}}, where file is the filename from {{Code|wget}}. Or try typing {{Code|ls}} to list the names of a file in the directory, which should include the unzipped folder. Enter the unzipped folder (e.g. use {{Code|cd}} to change directory), and install the Phidget Python libraries:

<div class="source">
<syntaxhighlight lang=bash>
python setup.py install
</syntaxhighlight>
</div>

Now, you're ready to begin writing Python code for the SBC. For more help on writing and using Python with Phidgets, we have a whole [[Language - Python | page on that topic]]. Remember that if you're unfamiliar with Linux, we have help on using files and running programs automatically in the [[#Using SBC Linux|Using SBC Linux section]].

====Installing Other Languages====

You may also be able to program on the SBC using [[Language - Ruby|Ruby]] and [[Language - C Sharp|C# under Mono]], though we do not offer in-depth support for these languages on the SBC. The installation procedures should more or less follow that of [[#Installing Python|installing python]] on the SBC, except you will be installing Ruby or Mono. Performing package searches using [[#apt|apt cache search]] can help you find the relevant software.

For C#, as of 2012 the {{Code|mono-complete}} package is broken on the Debian Squeeze repository. Rather, you have to install the Mono runtime and Mono compiler separately.

To install the runtime package (and its dependencies), use [[#apt|apt]]:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install mono-runtime
</syntaxhighlight>
</div>

Then, to install the C# compiler:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install mono-gmcs
</syntaxhighlight>
</div>

Or the Visual Basic compiler:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install mono-vbnc
</syntaxhighlight>
</div>

Then, the system and library packages do not link correctly for the version 2.0 of Mono. If this is the case, your code will compile fine, but when you try to run it, you will get an error like:

:{{Code|The assembly mscorlib.dll was not found or could not be loaded.}}
:{{Code|It should have been installed in the `/usr/lib/mono/1.0/mscorlib.dll' directory.}}

In this case, you need to install these two packages:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install libmono-corlib1.0-cil
apt-get install libmono-system1.0-cil
</syntaxhighlight>
</div>

Here we found these packages to work by working through the tree structure. As a general rule, you can find these dependencies by using install (here, {{Code|apt-get install mono-complete}}) to get a sense of the package tree structure. This will possibly tell you that the packages are broken, but at the same time this will list the dependencies of the packages. Trying to install individual dependencies will show you that although a root-package fails, the sub-packages will sometimes succeed, and install what you need.

If you want to use a specific dll or library that is not available in this reduced version of mono, you can install mono complete by switching from Emdebian+Debian to just Debian. To do this:

In {{Code|/etc/apt/preferences}} make the following changes:
:{{Code|Package: *}}
:{{Code|<nowiki>Pin: release a=stable</nowiki>}}
:{{Code|Pin-Priority: 1010}}

In {{Code|/etc/apt/sources.list/mutistrap-debian.list}} remove the emdebian line.

Apply the changes:

<div class="source">
<syntaxhighlight lang=bash>
apt-get update
apt-get dist-upgrade
</syntaxhighlight>
</div>

Many packages will be 'downgraded' from the emdebian to debian versions. Delete the {{Code|<nowiki>/etc/apt/preferences</nowiki>}} file and install mono-complete:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install monodoc-http mono-complete
</syntaxhighlight>
</div>

Choose monodoc-http explicitly, because otherwise the install fails on monodoc-browser.

After this process, you can compile your C# Code.cs Phidget source file the same way as on a generic [[Language - C Sharp#Linux|Linux with Mono]] system. Please refer to that page on how to obtain the *.dll Phidget resource file and compile your code. On the SBC, however, because you are already running as root (the Super User), you do not need 'sudo' and indeed the SBC will give you an error if you use it. Instead, compiling and running will look like:

<div class="source">
<syntaxhighlight lang=bash>
gmcs Code.cs -r:Phidget21.NET.dll
mono Code.exe
</syntaxhighlight>
</div>

==Using SBC Linux==

Now that you've set up communication with the SBC, and installed whichever programming language support you need, you're probably ready for a short tour of useful tools on the SBC's version of Linux.

First, you will by default be running on the SBC as '''root''', which is the super-user. For Linux users, this probably makes you nervous because you know you can overwrite important system files without the system asking for additional permission. As a Windows or Mac OS user - although you may usually run your computer as an administrator - your familiar system usually prompts you to confirm before you do anything really dangerous, and this will '''not''' happen on the SBC as the root user.

Next, there is no installed help on the SBC. Help on Linux is usually called 'man pages' which is short for 'the manual pages'. On a full Linux system, usually if you need help with any command you can type, for example, {{Code|man ls}} and it will give you help with the program [[#ls|ls]]. But these help pages take up significant space, and they are widely available online. So, if you need more help with a certain command, you can always type {{Code|man command}} into your favourite search engine.

Finally, the SBC has no windowing system. For Linux users, this means no X-windows (Gnome, KDE, etc). And as a Windows or Mac user, you can think of it as running all of your programs and commands through the terminal or DOS prompt command line. The SBC provides all of the functionality of an operating system (e.g. process scheduling, file management, etc) but without any graphical interface. The only exception is the [[#SBC Web Interface|web interface]], which gives graphical access to a limited part of what the SBC can do.

===Some Useful Commands===

If you are doing more with the SBC than simply running pre-written programs [[#Writing a Phidget Program|in Java to run continuously from boot]], you will be interacting with the SBC's Linux operating system over the command line by using [[#SSH|SSH]]. This section discusses useful programs already installed on the SBC, and how to run them on the command line.

====ls====

The '''ls''' program lists the contents of a directory.

It will show both files and folders, but not files that start with a "." (these are hidden files on Linux).
*If you also want to show hidden files, use {{Code|ls -a}}
*If you want more information, such as size and date modified, use {{Code|ls -l}}
*Commands can be combined, like {{Code|ls -al}}

====cd====

The '''cd''' program changes to a new directory.

For example, {{Code|cd /root}} changes into the directory at the base of the file tree called ''root''.

Note:
* Linux uses forward slashes
* The base of all directories is "/" (not "C:\")
* The tilde symbol (~) is short for your home directory (i.e. when you are root, this is short for "/root")
* The double dot ".." means move one directory higher (for example from {{Code|/root/data/}} to {{Code|/root/}})

====pwd====

The '''pwd''' program prints the current directory you are working in. ('P'rint 'W'orking 'D'irectory)

For example:
:{{Code|root@phidgetsbc:~# pwd}}
:{{Code|/root}}

====cp, mv, and rm====

These programs are copy ('''cp'''), move ('''mv'''), and remove ('''rm''').

Copy copies a file from one location and pastes it to another.

For example, if you have a file {{Code|data.txt}}, typing {{Code|cp data.txt data_backup.txt}} will put a copy of the file {{Code|data.txt}} into {{Code|data_backup.txt}}

Move moves a file (this is also useful for renaming files) to a new destination.

For example, if you have a file {{Code|data.txt}}, typing {{Code|mv data.txt data_backup.txt}} will put the contents of {{Code|data.txt}} into {{Code|data_backup.txt}}, and then will remove {{Code|data.txt}}.

Remove deletes a file.

For example, typing {{Code|rm data.txt}} will delete {{Code|data.txt}}.

Note that '''rm''' is final. Once you remove a file using {{Code|rm}}, it is gone forever. There is no recycle bin, no temporary trash, nothing other than backups you may have personally created in the past!

Directories can only be removed with {{Code|rmdir}}, and then only if they are empty. If you want to remove a directory and all the files in it, use {{Code|rm -rf directory}} but be '''very, very careful''' with this command. Trying to remove everything within a directory (e.g. {{Code|rm -rf *}}) is one of the most dangerous commands you can run on a Linux system, as running it from the wrong directory will result in Linux happily removing everything under that directory -- which could be your entire filesystem.

====find====

The '''find''' program does what it says - it finds things.

Unfortunately for the casual user, the find program is very flexible and powerful, and thus not especially intuitive to use. But, here are some examples:

{| style="border:1px solid darkgray;" cellpadding="15px;"
|-
! SSH Command
! What it Does
! Example
|-
| {{Code|find folder -name file.txt}}
| Looks for all files in a folder (/ for root - or all - folders) with a certain name (* for wildcard)
| {{Code|find / -name *.jpg}}
|-
| {{Code|find folder -mtime +X}}
| Looks for all files in a folder modified less than X days ago
| {{Code|find /root -mtime +30}}
|}

====grep====

The '''grep''' program takes text input and searches for a term.

For example, if you type {{Code|mount}} to view what devices are mounted (e.g. loaded) on your SBC, you will see:

<div class="source">
<syntaxhighlight lang=text>
root@phidgetsbc:~# mount
tmpfs on /lib/init/rw type tmpfs (rw,nosuid,mode=0755)
proc on /proc type proc (rw,noexec,nosuid,nodev)
sysfs on /sys type sysfs (rw,noexec,nosuid,nodev)
udev on /dev type tmpfs (rw,mode=0755)
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev)
devpts on /dev/pts type devpts (rw,noexec,nosuid,gid=5,mode=620)
rootfs on / type rootfs (rw)
procbususb on /proc/bus/usb type usbfs (rw)
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

This may be a lot of information you don't need. If you are only interested in a USB key attachment (as described in the [[#Using USB Data Keys|Using USB Data Keys]] section), you can use grep to filter that one response:

<div class="source">
<syntaxhighlight lang=text>
root@phidgetsbc:~# mount | grep sda1
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

====nano====

The '''nano''' program is a small text editor that you can use within an SSH terminal.

Nano can be surprisingly useful for writing short lengths of code right on the SBC, so there is no need to transfer files and keep track of different file versions on different computers.

Nano has all keyboard commands which are listed at the bottom of the screen at all times as a reminder (Ctrl-O to save, Ctrl-X to exit, these expand with a larger terminal window). And, nano provides what is called 'syntax highlighting', which colours reserved keywords, comments, strings, and so on as appropriate to the programming language you are using. Nano detects the programming language via the extension of the file ({{Code|.java}} for Java, {{Code|.c}} for C/C++, and {{Code|.py}} for Python).

Typing {{Code|nano test.py}} on an SSH command line and then entering a few lines of Python into the new empty file results in:

[[File:sbc_nano_python.png|link=|alt=]]

====apt====

The '''apt''' program allows you to install, uninstall, upgrade, and search software available for the SBC.
For a non-Linux user, the apt framework may be daunting at first, but it actually allows you to keep your system up to date and install and manage software quickly, easily, and for free.

'''Note:''' Before installing anything on the SBC, make sure that the ''Include full Debian Package Repository'' option is checked in the web interface under {{Code|System → Packages}}.

{| style="border:1px solid darkgray;" cellpadding="15px;"
|-
! SSH Command
! What it Does
! Example
|-
| {{Code|apt-cache search term}}
| Looks for all programs (packages) that have {{Code|term}} in the title or description
| {{Code|apt-cache search opencv}}
|-
| {{Code|apt-cache show package}}
| Shows a lot of data about {{Code|package}} including size, version, etc
| {{Code|apt-cache show unzip}}
|-
| {{Code|apt-get update}}
| Gets the most recent listing of available software
| {{Code|apt-get update}} (No options)
|-
| {{Code|apt-get install program}}
| Installs {{Code|program}} from the internet
| {{Code|apt-get install python}}
|-
|}

====mount====

The program {{Code|mount}} shows you all of the mounted devices on your SBC.

For example:

<div class="source">
<syntaxhighlight lang="text">
root@phidgetsbc:~# mount
tmpfs on /lib/init/rw type tmpfs (rw,nosuid,mode=0755)
proc on /proc type proc (rw,noexec,nosuid,nodev)
sysfs on /sys type sysfs (rw,noexec,nosuid,nodev)
udev on /dev type tmpfs (rw,mode=0755)
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev)
devpts on /dev/pts type devpts (rw,noexec,nosuid,gid=5,mode=620)
rootfs on / type rootfs (rw)
procbususb on /proc/bus/usb type usbfs (rw)
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

For the non-Linux user, the concept of a device may be quite strange. To give a short summary, everything on Linux that you can read or write is a file. Webcams are files (i.e. you can 'read' photos from them), USB keys are files, and each filesystem (tmp storage, the kernel portion, the main filesystem) are also themselves files. These files specify what and how something can be written. These are not necessarily linear, for example, you can see above that the USB key ({{Code|/media/usb0}} is mounted ''within'' the root file system {{Code|rootfs}} which is /.

So mount gives you an idea of what devices have been 'mounted' for reading or writing, and how you can read and write to them. More information on mount (and its various forms, like {{Code|umount}}) is available widely around the Internet.

====which====

The program {{Code|which}} tells you if and where a program is installed.

For example, on a default SBC, typing {{Code|which python}} will return no results. But after successfully [[#Installing Python | installing python]], it will return {{Code|/usr/bin/python}} as the location of the python program/binary/executable.

===Some Useful Commands to Install===

These are other programs you may find useful on the command line. Although they are not on the SBC by default, these and other programs can usually be installed simply by using [[#apt|apt-get install]], with the exception of gcc. For example, {{Code|apt-get install wget}} will download and install [[#wget|wget]].

'''Note:''' This section and the section on [[#Some Useful Commands|pre-installed commands]] can hardly cover all of the complexities and power of the Linux operating system. There are many excellent tutorials online, and between them and using [[#apt|apt]] to find and install programs you should be able to learn a lot and perform any number of complex useful tasks.

====gcc====

The '''gcc''' program is the C compiler for Linux.

If you are an experienced C/C++ user on Mac or Linux, or if you've already read our [[Language - C/C++ | C Language page]], you might think you need to install gcc via {{Code|apt-get}} to compile C code. However, gcc is not in the package repository for the SBC, so {{Code|apt-get install gcc}} will fail. Rather, to install gcc, you can do it via the web interface, as described in the [[#Installing C/C++ and Java|Installing C/C++ and Java]] section.

After installing it via the SBC web interface, you can use {{Code|gcc}} normally.

====less====

The '''less''' program displays the contents of a text or source code file. When displaying the file, {{Code|less}} allows you to scroll up and down to read it.

This is useful if you are writing your sensor readings to a data file, and you want to read the data file while it is being written by your main code. If your data file is called {{Code|data.txt}}, you can type {{Code|less data.txt}} and see the lines in the file, and what they are.

The {{Code|less}} program output can also be piped into another program. For example, you can use {{Code|less}} and the word search program {{Code|grep}} to find lines within a file with a search term. For instance, if you have a C source code file {{Code|Program.c}} on the SBC, and you want to see all the lines in {{Code|Program.c}} that contain a variable name {{Code|var}}, you can type:
:<code>less Program.c | grep var</code>

====wget====

The '''wget''' program allows you to get an online file (over http) and download it to the SBC.

For example, to get the source file (HTML) from the Phidgets home page, you can type:

<div class="source">
<syntaxhighlight lang=bash>
wget http://www.phidgets.com
</syntaxhighlight>
</div>

This is most useful for downloading libraries, drivers, or anything (zip, tar, etc) you need from the web which is not available by [[#apt|using apt]].

===Writing a Phidget Program===

We provide two ways to write and upload a Phidget Program:
# The [[#SBC Web Interface|web interface]]:
#* This is useful for simple projects written in Java that you want to start only at boot
#* You can also use C projects, but they must be compiled off the SBC for an ARM processor
# Over [[#SSH|SSH]], which will allow you to write or transfer source code directly to and from the SBC
#* This is useful for all other projects, such as:
#** Projects that run at scheduled times (e.g. once per minute)
#** Projects that use languages other than Java or ARM-compiled C
Note that you can still run an [[#SSH|SSH]] project at boot, you just have to write and install a startup script. This is a bit complex, but we do have an example that starts the program {{Code|phidgetwebservice21}} [[OS - Linux#As A Service|at boot using a script]].

Once you know which method you'd like to use, you can continue on to learn how to [[#Program in Java with the Web Interface|Program in Java with the Web Interface]], or how to [[#Program with SSH|Program with SSH]] using Java, C, or Python. If you are actually typing in source code on the SBC, you'll find our [[#Developing Code on the SBC|developing code on the SBC section]] useful.

====Program in Java with the Web Interface====

To show how to write, compile, and install Java programs on the SBC, we'll use the [[Language - Java|Java Hello World]] example code. You can download the HelloWorld example by downloading the whole [{{SERVER}}/downloads/examples/JavaJNI.zip Java example package]. Make sure you have [[#Installing C/C++ and Java|Java installed on the SBC]].

Here's how to get the HelloWorld code running on the SBC. On your external computer:

1. Download the SBC version of the Phidget Java libraries ({{Code|phidget21.jar}}). You can download this from the [[#SBC Web Interface|web interface]], on the page under {{Code|Projects → Projects}}, under the '''Notes''' section.

2. Place the SBC version of {{Code|phidget21.jar}} into a directory on your external computer. This will be your working directory that you will use to compile the Java files.

3. Also copy the {{Code|HelloWorld.java}} file into that working directory.

4. Compile the {{Code|HelloWorld.java}} file from within that working directory. From the command line prompt on Windows, this will be:
<div class="source">
<syntaxhighlight lang=bash>
javac -classpath .;phidget21.jar HelloWorld.java
</syntaxhighlight>
</div>
In a terminal on Linux or Mac OS, this will be:
<div class="source">
<syntaxhighlight lang=bash>
javac -classpath .:phidget21.jar HelloWorld.java
</syntaxhighlight>
</div>

5. You should now have three compiled class files: {{Code|HelloWorld.class}}, {{Code|HelloWorld$1.class}}, and {{Code|HelloWorld$2.class}}. You don't need to try and run them, and if you do you may encounter an error because the SBC {{Code|phidget21.jar}} may be slightly different than the Phidget support you have installed on your external computer.

Now we move onto the SBC:

6. Create a new project on the SBC, in the web interface under {{Code|Projects → Projects}}. Call it HelloWorld:

[[File:sbc_create_project.png|link=|alt=]]

7. On the next screen, you will be prompted to upload your files. We will upload the three Java class files, and then click the {{Code|Start}} button:

[[File:sbc_web_run_project.png|link=|alt=]]

8. You'll note that as it runs, there are two links below the {{Code|Stop}} button: One called {{Code|stdout}}, which is ''Standard Output'', and one called {{Code|stderr}}, which is ''Standard Error''. Usually, when you run a program on the command line, you see both standard out and standard error at the same time - i.e. you get all program output right there in your terminal or command prompt. But when running a program in the background, Linux splits the output up into normal output and error output as this is very useful for debugging (i.e. you can check if standard error is empty).

Here, however, if you're not sure whether the program will run correctly, you should first check {{Code|stderr}} to see if any errors were generated, and then check {{Code|stdout}} to see if the output looks as expected.

To write your own Java program, follow the same process but use your own source code instead of the {{Code|HelloWorld.java}} example.

Now that you have a running program, we offer additional help on [[#Via the Web Interface|running a program automatically using the web interface]].

====Program with SSH====

Similarly to starting a program via the [[#Program in Java with the Web Interface|web interface]], we use the Phidget Java {{Code|HelloWorld}} example here.

Make sure you have [[#Installing C/C++ and Java|Java installed on the SBC]]. To compile and run the {{Code|HelloWorld}} example:

1. Open an [[#SSH|SSH terminal]] to the SBC

2. Download the [{{SERVER}}/downloads/examples/JavaJNI.zip Phidget Java Examples] to the SBC, using [[#wget|wget]] (you may need to install {{Code|wget}} using [[#apt|apt]].)

3. Unpack the examples using [[#unzip|unzip]] (you may need to install {{Code|unzip}} using [[#apt|apt]].)

4. The location of {{Code|phidget21.jar}} on the SBC is {{Code|/usr/share/java/phidget21.jar}}. Within the unzipped example directory, compile the {{Code|HelloWorld.java}} example:

<div class="source">
<syntaxhighlight lang=bash>
javac -classpath .:/usr/share/java/phidget21.jar HelloWorld.java
</syntaxhighlight>
</div>

5. To run the {{Code|HelloWorld}} program, use:

<div class="source">
<syntaxhighlight lang=bash>
java -classpath .:/usr/share/java/phidget21.jar HelloWorld
</syntaxhighlight>
</div>

Now that you have a running program, you'll probably want to learn to [[#Running a Program Automatically|run this Java program automatically]].

'''Permissions Note:''' If you're used to using Linux with Phidgets already, you'll probably notice that you don't need to switch into root using {{Code|sudo}} on the SBC in order to run programs. This is because you already are running as root, not because the [[OS - Linux#Setting udev Rules|udev rules are set up]]. So if you set up another user, or [[#Via Cron|run a cron job]] as anything other than root or system, you'll need to add permission for the Phidget program to run in your [[OS - Linux#Setting udev Rules|udev rules]].

====Developing Code on the SBC====

When you're not just using pre-written source code, and you're writing code actually on the SBC itself, you'll probably want to use [[#nano|nano]]. Other terminal editors on the SBC include {{Code|vi}} which is already installed, and {{Code|emacs}}, which you can install using [[#apt|apt]]. Both {{Code|vi}} and {{Code|emacs}} are much more efficient for the experienced user, but they contain modes and keyboard shortcuts that can seem strange or almost hindering to the casual user.

Regardless of which editor you choose to use, some of your keyboard habits may not transfer well. For example, in the Linux command line, the command {{Code|Ctrl-C}} means ''stop the currently running program'', (i.e. your open editor) not copy. Within most SSH terminals, you can copy and paste using the right-mouse button, and on some terminals (and all native Linux terminals) you can copy by simply highlighting text, and you can paste it using the middle (scroll) mouse button. On the other hand, if you write a program that hangs on the command line, {{Code|Ctrl-C}} can actually be useful to terminate it.

Also {{Code|Ctrl-Z}} does not mean ''undo'', rather it means ''run the current program in the background''. This is useful because running a program in an SSH terminal simply hangs your SSH input until the program is done. So typing {{Code|Ctrl-Z}} while the program is running frees up the command line for more input. But if you accidentally hit {{Code|Ctrl-Z}} while running an editor like [[#nano|nano]], the editor will immediately exit to the command line. Don't worry though, it will not stop or lose your work. You can bring it back up by using the {{Code|fg}} (e.g. 'foreground') command, like {{Code|fg nano}}, and this will automatically bring your nano process back to the front.

===Running a Program Automatically===

For testing your program, you will certainly want to run it via [[#SSH|SSH]] or via the {{Code|Start}} button on the project page on the web interface until you are quite sure it runs well. However, eventually you will probably want the program to run without your input, either [[#Via the Web Interface|continuously, and starting at boot]], or via a task scheduled to [[#Via Cron|run to completion at certain times]].

Both have their advantages and disadvantages. Usually, you would want to use the continuous, from-boot methods for event driven code that has to handle a wide variety of user input that could occur at any time. You would want to use the scheduled method when the SBC needs to perform a repeated task (e.g. reading sensor data) again and again. The main difference is:
* With the continuous (boot) method you can have any Phidgets (including sensors, LEDs, input switches, etc) attached and giving events to your code all the time, and
* With the scheduled (cron) method you have much less of a chance to run into long-term memory management and instability problems with any code you write, because your program runs for only a short time before exiting and getting cleaned up.

====Via the Web Interface====

To use this method, you must have created the program you want to run as [[#Program in Java with the Web Interface | a Java or ARM-compiled C project in the web interface]]. If you would like to use another language, or another way of uploading your project, but you still want to start at boot and run continuously, you will need to use a [[#Via a Boot Script|boot script]].

In the web interface, go to the {{Code|Projects}} tab, and click on the project you would like to run. Near the bottom of the project page (the one with the {{Code|Start}} and {{Code|Stop}} buttons at the top), there will be a section called {{Code|Startup Settings}}. You can see a screenshot of the whole project page, including these settings, in the [[#Program in Java with the Web Interface | web interface project section]].

Select the {{Code|Enabled}} radio button. The other defaults should be fine, unless you specifically know otherwise:
* For ''Boot Order'', lower numbers boot first. Booting later means more programs are available for use, booting earlier means other programs can use your program.
* ''Run as a daemon'' starts the program as a daemon, which is a program that runs in the background. Unless you have ''explicitly'' written your program as a daemon, leave this checked. (If you don't know what a daemon is, don't worry, you haven't written one, so leave it checked.) ''Un''checking this when your program is a normal program will cause the SBC to hang while booting.
* The ''Executable or Class'' name should be automatically sensed to be your main Java class
* ''Arguments'' are any command line arguments you need, just as you would type them into the command line

'''Note:''' Your program must be very, very stable to run properly via the web interface. Imagine your program running continuously for days, or months on end. Any memory leaks, over time, will render your program (and the SBC) unusable until a reboot. Counts or other variables that increase within your program and never reset may create a segmentation fault eventually.

If, for stability purposes, you want your program to start, run for a little while, and then exit so that the SBC operating system can clean up the memory each time, you'll probably want to use [[#Via Cron|Cron]] to run your program instead.

====Via Cron====

Cron can automatically schedule programs - known as 'jobs', or 'cron jobs' - at most once per minute. Less often than that, it is very flexible, allowing you to run it on certain months, weekdays, hours, etc. Cron simply reads a special file (your {{Code|crontab}}) and runs whatever programs are listed, with whatever timing they are listed with. The cron program runs all the time in the background, making it what is known as a Linux ''daemon'', but the programs it starts as jobs run only as long as they naturally would, and then they exit.

If you need your program to run more often than once per minute, have the program schedule itself while still running. For example, to run every five seconds, run a fast loop, and sleep for five seconds. Do this twenty times and exit. Then schedule this once per minute using cron, and your program will in essence run every five seconds.

Setting up a cron job simply entails editing your {{Code|crontab}} file.

First, you'll probably want to specify your default editor to be [[#nano|nano]]. Otherwise it will default to {{Code|vi}} and you'll have to figure out {{Code|vi}} in order to add lines to your crontab:

<div class="source">
<syntaxhighlight lang=bash>
export EDITOR=nano
</syntaxhighlight>
</div>

Then, to edit your crontab file, simply type:

<div class="source">
<syntaxhighlight lang=bash>
crontab -e
</syntaxhighlight>
</div>

Each line of the crontab file is one scheduled job. Lines that start with a hash "#" are comments and are ignored. There is an example line in the crontab, and a reminder line at the very end. Essentially, each line should contain:

<div class="source">
<syntaxhighlight lang=text>
minute hour dayOfMonth month dayOfWeek command
</syntaxhighlight>
</div>

Where:
*{{Code|command}} is the program you want to run (with absolute path, and arguments)
** For example, {{Code|./myprogram argument1}} won't work, but {{Code|/root/code/myprogram argument1}} will
* Each time argument is either a number, a list of numbers separated by commas, or an asterisk
** For example, * * * * * means every minute for all days and months, 0,30 * * * * means every thirty minutes (i.e. at the top of the hour and at 30 minutes in) for all days and months

If you already have jobs scheduled, you'll see them in the file that comes up. You can edit, add, or delete.

After you save, you'll see a little message back in the terminal that says the new crontab file was installed, and it is now scheduled! Cron always starts every boot, and so if you have edited and installed your crontab as above, the scheduling of your program will start properly even after a reboot of the SBC. However, if you are having strange scheduling problems, you may want to familiarize yourself with the [[#Software Details|software details]] of how the SBC as a whole determines the current date and time.

=====My Cron Job Doesn't Work!=====

It is actually very common for a script or program to work on the command line but then ''not'' work as a cron job. The most common reason for this, by far, is that you specify ''relative'' paths in your program to access files rather than ''absolute'' paths. For example:
* {{Code|code/project.c}} is a relative path (bad for cron)
* {{Code|/root/code/project.c}} is an absolute path (good for cron)
The cron jobs are ''not'' executed from your home directory, or your code directory, so they will not be using the same location you may be using to test your code. So always use absolute paths.

Another common reason is you may be using environment variables or other settings that are true in a terminal but are ''not'' true by default in the raw system. You can end up taking many things for granted in a shell, for example the shortcut "~" means home directory in a shell, but not by default in the raw system. The things that get loaded for a shell (but which are not present in the raw system) are:
* The settings loaded by {{Code|/etc/profile}}
* Any settings in {{Code|~/.bashrc}}, which is nothing by default on the SBC

On a full Linux operating system, you would use the logs written to by cron to find the error output and debug it. On the SBC, however, cron does not write logs (otherwise, these logs would eat up the SBC memory very quickly even for routine jobs). For short-term debugging, you can write output from your program to a file, and read that file afterwards to figure out what your program is doing.

====Via a Boot Script====

If you want to run your program constantly and for it to start at boot like the [[#Via the Web Interface|web interface would do]], you can install your program into the boot order using a script. This is a somewhat involved process, and you should be familiar with shell programming in Linux. For this process, we only offer a [[OS - Linux#As A Service|similar example]] which installs and runs the program {{Code|phidgetwebservice21}} within the boot sequence.

===Using USB Data Keys===

After plugging the USB key in, it won't just appear on your desktop, so to speak, so you'll need to figure out where you can read and write to it within the SSH directory structure.

The web interface program can help with this. After you plug a USB key in, it will show up under {{Code|Status → System}}. Or, the USB key and all other attached devices can be seen at {{Code|Status → USB}}:

[[File:sbc_mounted_devices.png|link=|alt=]]

In the screenshot above, you can see that the USB key is located in {{Code|/media/usb0}}.

Alternately, you can use the SSH command {{Code|mount}}, and the searching program {{Code|grep}} which will filter the response of {{Code|mount}} and only return the lines with your search term ({{Code|usb}}):

<div class="source">
<syntaxhighlight lang=bash>
root@phidgetsbc:~# mount | grep usb
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

In this case, the USB key can be written to and read from using the {{Code|/media/usb0}} directory. Copying a file to {{Code|/media/usb0}} will copy a file to the USB key. The same goes for removing, renaming, opening files within your program, etc.

'''Note:''' Mount points like {{Code|/media/usb0}} should not be hard-coded into any of your programs. (See the [[#Common Problems and Solutions | Common Problems and Solutions]] section for more information.) If you need to obtain the mount point for a freshly mounted USB key within your code, have your code obtain the mount tables and search on the ''device'' (e.g. {{Code|/dev/sda1}} or {{Code|/dev/sdb1}}) and obtain the corresponding mounted {{Code|/media/usbN}} location, where N is a number 0-9.

===Saving and Retrieving Data===

This section covers getting data on and off of the SBC. There are two main methods of simply moving data on and off the SBC - via a [[#Via a USB Key|USB key]], and via [[#Over the Network (SCP)|copy over the network]] - and a third method for moving and installing data when it concerns [[#Backing Up Your Data|backing up lower level system data]].

====Via a USB Key====

After plugging in a USB data key, first you need to [[#Using USB Data Keys | find out the location]] where that data key was mounted.

Let's say the location of the USB key is {{Code|/media/usb0/}}, and we want to copy the file {{Code|data.txt}} to the USB key. Your SSH session might look something like this, using [[#ls|ls]] and [[#mount|mount]]:

<div class="source">
<syntaxhighlight lang=bash>
root@phidgetsbc:~# ls
data.txt
root@phidgetsbc:~# mount
tmpfs on /lib/init/rw type tmpfs (rw,nosuid,mode=0755)
proc on /proc type proc (rw,noexec,nosuid,nodev)
sysfs on /sys type sysfs (rw,noexec,nosuid,nodev)
udev on /dev type tmpfs (rw,mode=0755)
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev)
devpts on /dev/pts type devpts (rw,noexec,nosuid,gid=5,mode=620)
rootfs on / type rootfs (rw)
procbususb on /proc/bus/usb type usbfs (rw)
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
root@phidgetsbc:~# cp data.txt /media/usb0/
</syntaxhighlight>
</div>

The '''cp''' program copies data from a source to a destination. The syntax is {{Code|cp from to}}, where here we are copying from {{Code|data.txt}} to {{Code|/media/usb0/}}.

'''Caution:''' Even if there is no USB key mounted at {{Code|/media/usb0/}}, this use of {{Code|cp}} will still work ''with no errors''! This is because there is still a file called {{Code|/media/usb0/}}, there is just no USB key file system ''mounted'' to that point. So be sure to run [[#mount|mount]] or use some other method of determining that there is, in fact, a USB data key attached and where it is mounted to.

====Over the Network (SCP)====

SCP is a command line program already installed on Linux and Mac OS, and downloadable for free on Windows. We discuss it and give examples in the [[#SSH|SSH]] section, but remember it here when you're trying to get data on and off of the SBC. With SSH or a terminal already open, you'll probably find it to be much faster and easier than dealing with a USB key.

====Backing Up Your Data====

For the web interface, you can save and restore all web interface settings under the {{Code|System → Backup & Restore}} tab.

To save the settings of what packages are installed for later re-installation, you can type:

<div class="source">
<syntaxhighlight lang=bash>
dpkg --get-selections > installedPrograms.txt
</syntaxhighlight>
</div>

Then save the file {{Code|installedPrograms.txt}} externally. If you have to completely wipe the SBC, you can just reinstall the whole list by moving the {{Code|installedPrograms.txt}} file back onto the SBC, and then typing:

<div class="source">
<syntaxhighlight lang=bash>
dpkg –set-selections < installedPrograms.txt
apt-get dselect-upgrade
</syntaxhighlight>
</div>

Also remember to externally save:
* Your {{Code|~/.bashrc}} settings file if you've changed it
* Your {{Code|crontab}} file if [[#Via Cron|you've edited it]]
* Any data files or code you've created

It is important to save these settings often, and at points where you know the system is running well. It may be tempting to create a backup right before you [[#Recovery System|wipe the SBC and start from scratch]], but often the reason you are having problems then is some setting or change, and backing these up and reinstalling them will only reinstall the problem.

To truly back the files up, you must copy them to an external computer or location using either a [[#Via a USB Key|USB Key]] or [[#Over the Network (SCP) | over the network]]. Then they can be copied back if needed later.

If you are looking to restore data on an SBC that will not boot properly, you'll want to be in the [[#Partial Recovery|partial recovery]] portion of our Troubleshooting section.

==Troubleshooting==

The SBC can be quite tricky to debug, because it is a complex and flexible computer. Common problems and solutions include:
* You can't find the SBC on the network at all - refer to the [[#Initial Internet Setup|Initial Internet Setup]] section
* You have changed some setting or file such that the SBC doesn't run anymore, or doesn't run as expected - refer to the [[#Recovery|Recovery]] section

If you are having trouble using Phidgets on the SBC, you should go through the [[OS - Linux#Troubleshooting | Troubleshooting section on the general Linux page]]. Some of the problems on the Linux page (such as library problems) are easier to fix by simply working through the [[#Recovery|Recovery]] section when they occur on the SBC.

Namely, it often helps to simply perform a [[#Factory Reset|factory reset]] on the SBC (save your files and installed program list first, as [[#Backing Up Your Data|described here]]). Sometimes you change a file or setting within the operating system when you are trying to get something up and running, and this unintentionally affects other programs too. Performing a factory reset starts you with a clean slate.

If your problem doesn't seem to be fixed by these steps, or the information within this guide, please [[Contact Us|ask us]]!

===Initial Internet Setup===

To set up the SBC, you almost always need a ''wired'' Ethernet connection with DHCP (Dynamic Host Configuration Protocol), and without a firewall. This connection should be to a ''router'', not directly plugged in to your computer.

Even if you do not have this type of a connection at home, these types of connections are very common at both offices and universities. On a Windows or Mac OS computer, you can bring up the Phidget Control Panel as described in the SBC's [[1072 - Getting Started|Getting Started Page]]. Failing this, or on a Linux computer, we discuss some alternate setup methods in this section. Keep in mind that without a wired, open DHCP connection these setup methods can be difficult and fickle.

====No Wired-Only Connection====

Sometimes it can work to plug the SBC, using Ethernet, directly into an Ethernet port on your home wireless router. Do not plug it directly into your computer! (Although in some instances, a direct connection can be made to work on Linux, see the [[#No DHCP|No DHCP]] section below)

This direct-router method is a very picky process, however, and can fail because:
* Some home and office routers place a firewall between wireless connections (clients) and wired connections (the local area network)
* Some home and office routers do not by default allow both Ethernet DHCP and wireless DHCP.
* Some routers and DHCP hubs only provide access to an internet connection, and do not provide local area network inter-connections (this is common on mobile device tethering hubs)

Routers are quite complex, and even with admin privileges it can be a painstaking process to find all the right firewall settings to turn off in order to allow two computers on the network to talk to one another, rather than just connect to the internet. This is why university or office networks are often ideal for the purpose of setting up the SBC, because these institutions depend on computers on a local network being able to talk together. University libraries in particular can be a good source of wired DHCP connection ports.

Covering all of the different router configuration possibilities here, and how to change them to make the SBC work, is essentially impossible. If you try using the SBC at home or at work, the SBC does not work on the first try when plugged directly into the router via Ethernet, and you want to make that connection work rather than seeking out an alternate for the initial setup, you should find documentation specific to your router (usually available online) and properly configure it.

The good news is that if you can find an Ethernet DHCP connection ''just once'' for a short time, you can use that connection to configure the SBC to work on your home wireless network. During that initial connection, you can enable wireless and set up as many wireless DHCP connections (with passwords) that you need. Once wireless is enabled and set up, you can take the SBC home to your wireless router and the SBC will automatically seek out and connect to its remembered networks as they appear. At that point, you can also use wireless like a normal internet, web interface, and SSH connection.

====No Link Local Addressing====

If you have a wired DHCP connection, no firewall, and no link local addressing (e.g. bonjour or avahi is not installed) then you will need access to the DHCP router logs. From the router logs, you should see the connection (or attempted connection) by the SBC within the logs. From that log entry, you should either be able to determine the IP address for the SBC, or see what happens when the router blocks access. The IP address can be used in place of the link local address for both the web interface and for SSH.

====No DHCP====

The SBC will first try to use DHCP, but then it will revert to responding to a link local address under bonjour and avahi. If you are depending on this, please wait '''at least three minutes''' after the SBC boots for the SBC to fail in obtaining a DHCP connection and properly revert to link local addressing.

If you have a static IP setup, and want to use link local addressing rather than accessing the router logs, this should usually work by default on Windows and Mac OS (e.g. type the address such as {{Code|phidgetsbc.local}} into a web browser). If it doesn't work automatically, there is not much you can do and you should seek out a wired DHCP connection elsewhere.

On Linux, it also should work by default, but you have the additional option of explicitly adding routes that look within the default network settings for the SBC. From a terminal (as root), type:
* {{Code|route add -net 169.254.0.0 netmask 255.255.0.0 dev eth0 metric 99}}
* {{Code|route add default dev eth0 metric 99}}
You can also compile and use the {{Code|phidgetsbclist.c}} example (use the provided Makefile, don't use gcc) in the [{{SERVER}}/downloads/libraries/libphidget.tar.gz Phidget Linux Libraries] package, under the {{Code|examples}} folder. This will allow you to see if the SBC is detected on the network at all. Note that to use this option you must have the Phidget Libraries and the Phidget WebService installed on your Linux computer - in-depth instructions to do this are on the [[OS - Linux|main Linux page]].

===Recovery System===

You can either boot the SBC into recovery mode and attempt to recover files and settings, or you can completely wipe the SBC by performing a factory reset. If the LEDs do not turn on normally (red on constantly, green on at first start, then off, then on when fully booted) then you'll want to read the [[#Hardware Issues|hardware issues]] section.

====Partial Recovery====

The recovery system can be entered in two ways:
# From the {{Code|System → Backup & Restore}} web interface page.
# By holding down the reset button for 20+ seconds - until the green light has switched from flashing slowly to flashing quickly.

The recovery system runs an [[#SSH|SSH]] server where the username and password both are {{Code|root}}.

If the main filesystem has been damaged/misconfigured in such a way that it won’t boot, you may be able to fix the issue or recover important files before running a full factory reset. From an SSH connection to the recovery system, you can mount the main root filesystem with the following commands (assuming it’s not damaged):

<div class="source">
<syntaxhighlight lang=bash>
ubiattach /dev/ubi_ctrl -m 6
mount -t ubifs /dev/ubi0_0 /mnt
</syntaxhighlight>
</div>

====Factory Reset====

This restores the kernel and root filesystem from backup, overwriting any changes that may have been made and ''completely wiping the system'' to the state that it got shipped in. (You can save your files and installed program list first, as [[#Backing Up Your Data|described here]].) This can be enacted one of two ways.
# Use the reset button:
##Enter the recovery mode by holding down the reset button for 20+ seconds as above (until fast flashing)
##Wait for a full boot (i.e. you can see it on the Phidget control panel, or can SSH with username and password as {{Code|root}})
##Hold down the reset button again, but this time for only 10 seconds (until slow flashing)
##Wait for the SBC to fully reset and reboot (at least three minutes) - the LED will turn off and on again when this occurs
##*Note that after a factory reboot the SSH server will be disabled
##*Also note that after a factory reboot the SBC creates new SSH keys, and reverts to the {{Code|phidgetsbc.local}} address
# Via the web interface, under {{Code|System → Backup & Restore → Go button}}, where you can follow the instructions

====Hardware Issues====

The LEDs are an indicator of the hardware working properly. The normal boot process is:
* Red LED: Turns on from moment of power being applied.
* Green LED: Turns on momentarily when power applied, then turns off momentarily, then turns on and stays on when booted.

If the green status LED never turns on (or fails to turn on the second time), the boot process is failing somewhere. This could be due to:
* A damaged OS - Try performing a [[#Factory Reset|Factory Reset]]
* If this fails, it is likely hardware damage (very difficult to diagnose, please [[Contact Us|contact us]])

If neither LED turns on, hardware damage is even more likely. Unless the path to the red LED is the one thing that has been damaged, the device is likely not receiving and using power.
* Try performing a [[#Factory Reset|Factory Reset]], and if that does not work please [[Contact Us|contact us]]

=====USB Issues=====

On the Phidget SBC2, there is a hardware issue that is unrelated to the LEDs. It is a USB problem, and manifests in many ways:
* Strange behaviour when some devices but not others are plugged in to the SBC
* Strange behaviour with combinations of devices
* Failure (or intermittent failure) to see Phidgets on the USB hub, or USB keys on the hub

This problem is fixable, either on your own or by sending your SBC back to Phidgets. For an in-depth solution, see the [[SBC2_USB_Hub_Fix | SBC2 Hub Fix Page]].

===Updating Your SBC===

If you've owned your SBC for a while and want to update your packages, you can run:

<div class="source">
<syntaxhighlight lang=bash>
apt-get update
apt-get upgrade
</syntaxhighlight>
</div>

...to ''update'' your software source list and then ''upgrade'' to the latest version of all installed software. If you are used to Mac OS or Windows, note that this does not just update the non-kernel parts of the operating system, it updates every additional piece of software you have installed.

To update the SBC software itself (e.g. the kernel), it is easiest to use the web interface, under {{Code|System → Backup & Restore → Go button}}, to enter a page that will give you the option to update. You will need to have an update file on a USB key inserted into the SBC, of type:
* UBI Image (system_ubi.img), or
* Kernel image (uImage), or
* Phidget Upgrade package containing both UBI and Kernel images (phidgetsbc*.bin)

These are either obtained from the Phidgets website, or are a custom kernel / filesystem that you can create yourself, if you are experienced.

The reason why this information is in troubleshooting is that you should certainly [[#Backing Up Your Data|back up your system]] before trying this. And, it is quite rare to need to upgrade the kernel or filesystem on the SBC, so something serious should be going on before you attempt it. Try using the [[#Recovery System|recovery system]] first.

==Programming Languages==

Now that you have the basic libraries installed, you can pick your language and begin programming!

If you are not using the [[#WebService | webservice]] to control a Phidget over a network, your next step will be to delve into the use of your specific language. Each page has its own set of specific libraries, code examples, and setup instructions.

On SBC Linux, we recommend the following languages:

*[[Language - C/C++|C/C++]]
*[[Language - Java | Java]]
*[[Language - Python | Python]]

These languages may also run on the SBC, but we do not yet directly offer SBC support for them:
* [[Language - Ruby|Ruby]]
* [[Language - C Sharp|C#]] (using Mono)

You can probably figure out how to install and use them by a combination of the language pages linked above, and the section on [[#Installing Other Languages|installing other languages on the SBC]].

==WebService==

The SBC comes with the [[Phidget WebService]] installed, and the SBC automatically starts the WebService at boot.

To practice using the WebService, and to learn more about it, we have hands-on examples on the [[OS - Linux|general Linux page]], starting in the [[OS - Linux#Using the WebService|using the WebService section]].

==Advanced Uses==

===Using a Different Wireless Adapter===

The support for the wireless adaptor that Phidgets sells is written into the SBC kernel. Hence, we do not support using other adaptors.

However, Linux is very flexible, and it is possible (though not easy) to write a custom kernel for the SBC and add support for a new wireless adaptor. We can't help you with this, but we do provide some basic guidelines for [[#Custom Kernel and Filesystem|building your own kernel]].

===Using a Different Webcam===

In addition to the webcam that Phidgets sells, you have the option to use many different webcams with the SBC. There is a [http://www.ideasonboard.org/uvc/#devices long list] of compatible webcams.

The common thread for these webcams is that they use UVC - the USB Video Class - drivers for Linux. You can then use [[#mount|mount]] to find out what video device your webcam is mounted under.

===Taking Pictures With the Webcam===

Probably the most straightforward way to use a webcam for pictures rather than video is to use the {{Code|opencv}} library. You can get it by:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install libcv2.1
</syntaxhighlight>
</div>

If there is no {{Code|libcv2.1}} package, you can perform {{Code|apt-cache search libcv}} to find the current version.

The opencv libraries can also be used within Python, by installing the link between them:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install python-opencv
</syntaxhighlight>
</div>

Then taking pictures from within code becomes quite simple. For example, in Python, taking and saving an image is four lines:

<div class="source">
<syntaxhighlight lang=bash>
#! /usr/bin/python

import cv

# The webcam is located at /dev/video0
# OpenCV only needs the number after video
webcam = cv.CaptureFromCAM(0)

frame = cv.QueryFrame(webcam)

cv.SaveImage("image.jpg", frame)
</syntaxhighlight>
</div>

For the complete OpenCV documentation, see [http://opencv.willowgarage.com/documentation/index.html The OpenCV Reference], and specifically the section on [http://opencv.willowgarage.com/documentation/reading_and_writing_images_and_video.html Reading and Writing Images].

'''Note:''' The SBC is probably not as powerful for image processing and transport when compared to your desktop computer. Try running your image processing code on the SBC from an early point in development. During those test runs, you can visit the first System page of the [[#SBC Web Interface|SBC Web Interface]] to check the processor and memory use. For more information on processor power, check the specification for your SBC (on the product page on [{{SERVER}} our main website]) as well as our discussion of [[#Pushing Processor Limits|pushing processor limits]] below.

===Checking System Logs===

The SBC maintains two logs: a kernel log and a system log.

The kernel log is for low-level occurrences, such as devices attaching and leaving the USB hub, recording what drivers are being used, and so on.

The system log (syslog) is for normal chatter from the operating system. Any program with the right permissions can use it (though you need to know the method to write to it, information all around the Internet can help) and it contains everything from the Ethernet going up and down, to webserver requests, and so on. If you don't run many programs or services on the SBC, the syslog will essentially be a mirror of the kernel log, because the kernel is the only thing talking.

You can check these logs by using the web interface in the {{Code|System → Logs}} tab.

Or you can perform more powerful filtering and displaying via an SSH terminal. For example, {{Code|dmesg}} is the command to display the kernel log, and {{Code|tail}} prints the last ten lines of input. So, if you are trying to see if you can get a device to be detected on USB, you can run <code>dmesg | tail</code> to print the latest ten lines of kernel log data.

The actual locations of the log files (for filtering and reading) are:
* {{Code|/var/log/syslog}}
* {{Code|/var/log/dmesg}}
But don't edit them directly! Always follow the advice and procedures around the Internet on how to properly log items to syslog.

===X Forwarding===

Although most tasks can be done using the [[#SBC Web Interface|SBC Web Interface]] or [[#SSH|SSH]], you can also set up X11 forwarding on the SBC. X11 is the window manager base, which provides a graphical windowing system on the SBC. Although you probably won't connect directly to the X11 manager (i.e. by plugging a screen directly into the SBC), X11 also gives a user the ability to forward graphical windows over SSH. You will need the following packages installed:
* {{Code|x11-common}}
* {{Code|xbase-clients}}
After installing, make sure that the line in {{Code|/etc/ssh/sshd_config}} has a line that says:
:{{Code|X11Forwarding yes}}
Then log out and log back into the SBC. This second time you log in, use the {{Code|-X}} switch to turn on X forwarding for that connection:
:{{Code|ssh -X root@phidgetsbc.local}}
Then you should be able to run programs that launch a window, and it will launch remotely and appear on the computer you have the SSH connection from.

===Pushing Processor Limits===

The SBC, though more powerful than many embedded computers out there, is probably about as powerful as your smartphone. If you hook up 1 ms Phidget sampling devices to all six of its USB ports, events and packets will probably get lost. The exact data rates you can accomplish depend on:
* What else is running on the SBC
* How efficient your code is for external operations (like File I/O)
* Other minor details (e.g. the temperature of the SBC, etc)

If you want to achieve data rates as fast as possible, try these tips:
* Program in C, not in an interpreted language (Python, Java, .NET)
* Perform file I/O as little as possible. Locally cache data, manage your writing to a file in a separate thread, and use low-level write calls.
* Change the [[#Custom Kernel and Filesystem|filesystem]] to a faster, non-compressed file system.
** Alternatively, use a high-data-rate USB key.
* Keep other running processes to a minimum.
** If you are running code locally right on the SBC, turn off the Phidget WebService.

===Custom Kernel and Filesystem===

You can compile your own kernel and flash it to the board. It is left up to the user to configure an appropriate cross-compiler for kernel development. You may also be able to compile a new kernel on-board. We have a kernel development kit, complete with patch file and README:
* [{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC Kernel Development Package]

Compiling a new, custom kernel is somewhat complex. If the SBC is your first experience with Linux, writing a custom kernel will be difficult. However, it will probably also be very rewarding because you can put whatever you like into it. We might be able to offer additional suggestions, but ultimately you're on your own here.

You may be able to write a custom kernel right on the SBC, but the easiest way is to develop the kernel on an external computer. And the easiest way to develop on an external computer is for that computer to also be Linux, even just in a Virtual Machine. The time spent loading a copy of Linux into a virtual machine (such as VirtualBox, which is free) onto your computer will probably be less time than setting up a standard compiler on Windows to cross-compile.

On your external Linux system, you will need:
* A cross-compiling toolchain for the ARM processor, which we briefly describe on the [[OS - Linux#Cross-Compiling with a Custom Toolchain | main Linux page]], and
* The [{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC Kernel Development Package] from the Phidgets website.
The kernel development kit has a brief README file which describes how to obtain the proper kernel and patch, configure, customize, and build it.

We have an application guide in progress, which walks through building a custom kernel to add Bluetooth support to the SBC. Please contact us if you would like more information. Even if you are trying to add support for hardware other than a bluetooth modem, or wondering if support even exists in the kernel for your modem (3G, alternate wireless, etc) you will probably find the application guide helpful. Follow it up to the point where you run the program {{Code|menuconfig}} (you don't need an SBC to do this), which will give you a menu of all drivers you can enable in the SBC kernel.

After making your new kernel, you should have a uImage and modules target for your Makefile. At this point you can transfer your kernel files onto the SBC, make their targets, and transfer them into the nand memory. This involves erasing the old kernel, flashing the new kernel, installing the new kernel modules, and rebooting. From the SBC, in the kernel directory:

<div class="source">
<syntaxhighlight lang=bash>
make uImage; make modules
flash-eraseall /dev/mtd3
nandwrite -p /dev/mtd3 arch/arm/boot/uImage
make modules-install
reboot
</syntaxhighlight>
</div>

Custom kernels can also be flashed from the [[#Recovery System | Recovery System]].

If you need to create a root filesystem image, the filesystem type is UBIFS, and the commands to create it are:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -m 2KiB -e 126KiB -c 4050 -r $ROOTFS/ system_ubifs.img
ubinize -o system_ubi.img -m 2KiB -p 128KiB -s 512 ubinize.cfg
</syntaxhighlight>
</div>

Where {{Code|ubinize.cfg}} contains:

<div class="source">
<syntaxhighlight lang=bash>
# Section header
[rootfs]
# Volume mode (other option is static)
mode=ubi
# Source image
image=system_ubifs.img
# Volume ID in UBI image
vol_id=0
# Volume size
vol_size=64128KiB
# Allow for dynamic resize
vol_type=dynamic
# Volume name
vol_name=rootfs
# Autoresize volume at first mount
vol_flags=autoresize
</syntaxhighlight>
</div>

You then flash ‘system_ubi.img’ (not ‘system_ubifs.img’) from the recovery system.

Again, like the custom kernel creation, the need to create a custom root filesystem is essentially non-existent except for those advanced users who already know they need it... and furthermore, you are almost entirely on your own.

==Software Details==

For even more advanced uses of the SBC, it may help to know the gritty details of the SBC software system.

;Operating System
:Debian/GNU Linux
:Kernel 2.6.X or higher (generally kept up to date with latest releases, use {{Code|uname -r}} to check the kernel version)

;Main Filesystem (rootfs)
:UBIFS (a raw flash type of file system)
:Mounted in a 460 MB Nand partition (in Read/Write mode)

;Kernel
:uImage format
:Has its own 3MiB partition on bare Nand

;Web Interface Scripts and Configuration Data
:Located in {{Code|/etc/webif}}
:Modifying these scripts can be done; however, it is very easy to enter invalid data that could cause the system to behave unexpectedly or not boot.

;User Applications uploaded through Web Interface
:Located in {{Code|/usr/userapps}}

;Webcam Device Location
:{{Code|/dev/video0}}
:Numbers increase with more webcams

;Date and Time
:Set using ntp (network time protocol) at boot
:The ntp daemon continues to run in the background and will periodically update the clock
:The network keeps the SBC very close to real time
:Also there is a real-time clock with battery backup which will preserve date/time across reboots, power removal
:The real-time clock is synced to system time during reboot/shutdown
:If power is unplugged suddenly, and the network not restored, the real-time clock may not have the correct time

;Wireless Networking System
:Wireless adapter support for the wireless adapter that Phidgets sells is written into the kernel
:It supports WEP and WPA
:It is best configured through the configuration interface.

;Nand Layout
:The board contains 512MiB on Nand. This nand is split into 7 partitions as follows:
:0: u-boot size: 256K Read Only
:1: u-boot_env size: 128K Read Only
:2: recovery_kernel size: 2M Read Only
:3: kernel size: 3M Writable
:4: flashfs size: ~3.625M Read Only
:5: recovery_fs size: ~ 43M Read Only
:6: rootfs size: ~ 460M Writable
: The final size of flashfs/recovery_fs/rootfs depends on the image size at production, and on the number/location of bad blocks in the NAND.
: '''Note''': U-Boot and recovery kernel and filesystem cannot be written from Linux - this is a safety measure.

;Boot Loader
:U-Boot is used for setting up the processor and booting Linux, and is only accessible via a serial connection.
:Normal users will not need to use or modify it.
:Be very careful when modifying the u-boot partition. If it is damaged or overwritten, it is difficult to fix.
:When using U-Boot, a prompt will appear via serial shortly after power on.
:The environment variables will help you determine how to boot Linux on the SBC
:You can also refer to the [http://www.denx.de/wiki/DULG/Manual U-Boot documentation]

;Boot Process
:From power on...
:1. Processor loads first 4 bytes from NAND into Steppingstone and runs it.
:2. Steppingstone sets up RAM, copies u-boot from NAND into RAM and runs U-Boot.
:3. U-Boot initializes the processor, sets GPIO state, etc., copies the linux kernel into RAM, sets up the kernel command line arguments, checks that the kernel image is valid, and boots it.
:4. Linux boots, bringing up USB, Networking, NAND, etc. and then mounts the rootfs NAND partition on /.
:5. init gets run as the parents of all processes, as uses the /etc/inittab script to bring up the system. This includes mounting other filesystems, settings the hostname, and running the scripts in /etc/init.d, among other things.
:6. inittab then turns the green LED on.
:7. inittab then sets up a getty on the first serial port, ready for interfacing using the debug board.

==Common Problems and Solutions==

{{ProblemSolution|USB Memory Key mounting|Sometimes USB Memory Keys mount at more than one location}}

When you insert a memory key, the SBC will load it as a device (e.g. {{Code|/dev/sda1}}) and it will also ''mount'' the key for reading and writing within the {{Code|/media/}} directory. The {{Code|/media/}} directory version will be called something like {{Code|usb0}}.
At times, an inserted memory key will get mounted in more than one location. You can observe if this occurs by checking the currently mounted devices with the command {{Code|mount}}:

<div class="source">
<syntaxhighlight lang="text">
root@phidgetsbc:~# mount
tmpfs on /lib/init/rw type tmpfs (rw,nosuid,mode=0755)
proc on /proc type proc (rw,noexec,nosuid,nodev)
sysfs on /sys type sysfs (rw,noexec,nosuid,nodev)
udev on /dev type tmpfs (rw,mode=0755)
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev)
devpts on /dev/pts type devpts (rw,noexec,nosuid,gid=5,mode=620)
rootfs on / type rootfs (rw)
procbususb on /proc/bus/usb type usbfs (rw)
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
/dev/sda1 on /media/usb1 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

You will note that the same device ({{Code|/dev/sda1}}) is now mounted at ''both'' {{Code|/media/usb0}} and {{Code|/media/usb1}}. To fix this problem as it occurs, you can use {{Code|umount}} (notice there is no letter 'n') to unmount the second instance:

<div class="source">
<syntaxhighlight lang="text">
root@phidgetsbc:~# umount /media/usb1
</syntaxhighlight>
</div>

In practice, this should not be a problem, because writing to or reading from either {{Code|usb0}} or {{Code|usb1}} will have the same effect on the memory key. However, if you hard-code a media location into your program (i.e. expecting {{Code|/media/usb0}} to be the first USB key you insert and {{Code|/media/usb1}} to be the second key) your program will sometimes work and sometimes fail.

To get around this within code, find the mount point for each device as it appears. The devices, such as {{Code|/dev/sda1}} will always refer to the actual memory key. But, they cannot be written to directly without being mounted, so you will have to parse the mount table (what is returned from {{Code|mount}}) within your code to find the device and its corresponding mount point.

This is a problem with the standard embedded Debian automount program, and we have no known fix.

{{ProblemSolution|Perl Locale Errors on SSH|No Locales Installed}}

By default, no locales are installed on the SBC. If you use [[#apt|apt]] a lot to install and manage your software on the SBC, you will get messages like this:

<div class="source">
<syntaxhighlight lang="text">
perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
LANGUAGE = (unset),
LC_ALL = (unset),
LANG = "en_CA.UTF-8"
are supported and installed on your system.
perl: warning: Falling back to the standard locale ("C").
locale: Cannot set LC_CTYPE to default locale: No such file or directory
locale: Cannot set LC_MESSAGES to default locale: No such file or directory
locale: Cannot set LC_ALL to default locale: No such file or directory
</syntaxhighlight>
</div>

To squelch these messages, you should install and reconfigure your locale like this:

<div class="source">
<syntaxhighlight lang="bash">
apt-get install locales
dpkg-reconfigure locales
</syntaxhighlight>
</div>

The last command will show you a long list from which you should pick your location, by language. For example, en_CA is english_Canada. Here in Calgary, we use en_CA.UTF-8 and so for the first question we would input locale "114" and for the second (system) question we would input {{Code|en_CA}} for the locale.

This might give you a locale undefined error, in which case you can generate the locale (for us, again, it is en_CA):

<div class="source">
<syntaxhighlight lang="bash">
locale-gen en_CA
</syntaxhighlight>
</div>

OS - Phidget SBC

2012-06-29T21:45:29Z

Cora:

[[Category:OS]]
{{OSLang|[[File:icon-Linux.png|64x64px|link=OS - Linux]]|On the Single Board Computer (SBC), Phidgets can be either plugged directly into one of the USB ports or run over a network using the [[#WebService | WebService]].}}
__TOC__

==Quick Downloads==

Unlike our other supported operating systems, the SBC '''does not require downloads''' unless you are doing something advanced like loading the firmware or developing your own kernel. You will know if you need these downloads, otherwise, the SBC should work as described on the [[1072_-_Getting_Started|SBC2 Getting Started Guide]] right out of the box.

*[{{SERVER}}/downloads/libraries/phidgetsbc2.bin SBC2 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
*[{{SERVER}}/Drivers_Info.html#SBC2 License]

Note that, instead of using the firmware to update your SBC, updates should normally be done via the System -> Packages page on your SBC2 web interface. It is rarely necessary to completely re-flash your device.

==Getting Started with the Phidget SBC Debian Linux==

The Single Board Computer (SBC) is a unique Phidget. It is a computer with a Linux operating system. It can compile code, save files, manage background jobs, host information over the web, and more.

'''If this is your first time''' using the Phidget SBC, you will want to start with the [[1072 - Getting Started | Getting Started Guide for the SBC]]. After that, here we will get you started on topics beyond those in the getting started guide, including how to write Phidget code to run on the SBC. You '''do not need this page''' if you are simply using the SBC to broadcast data from Phidgets over the network - it does that automatically. We describe how to verify and use this in the [[1072 - Getting Started | Getting Started Guide]].

This page will show you how to:
* Install the ability to write and develop code on the SBC itself
* Use the command line for basic coding tasks
* Troubleshoot the SBC's network
It will also give additional specifications, which are useful for doing more advanced things with the SBC hardware and software.

Before reading this page, you should have done the following via the Getting Started Guide:
* Set up networking on your SBC, via either Ethernet or wireless
* Set up an admin password
* Learned the IP address or link local address of the SBC
We will use this information in setting up the libraries and drivers to use the SBC for writing and running code.

Conceivably, you could simply use the SBC like any Linux computer, and do all of your development and compiling of Phidget code on the SBC itself. In practice this gets complicated as the SBC does not have a keyboard or screen. So usually, you will want to develop your code an external computer and copy files and settings over to the SBC via a network. This makes this Getting Started section unique, in that we show you how to set up both computers:
* Your [[#Getting Started - External Computer | External Development Computer]], usually your main desktop or laptop which will transfer files and settings to and from the SBC
* The [[#Getting Started - The SBC (Debian Linux) | SBC]] itself, which needs programming language libraries to use Phidgets.

===Getting Started - External Computer===

You have two ways to connect to the SBC from an external computer: via the [[#SBC Web Interface|SBC Web Interface]] and over the more powerful but complex [[#SSH | Secure Shell (SSH)]].

====SBC Web Interface====

You have already worked extensively with the web interface in the [[1072 - Getting Started | Getting Started Guide for the SBC]]. This was the tool within a web browser which was opened either via the Phidget control panel on Windows, or by simply entering the IP or link local address into an internet browser. It allowed you to set the password, set up internet connectivity, and so on.

This section doesn't have more information on the interface; rather, it simply serves as a reminder that you have the web interface as an available tool. Examples, including screenshots, are placed where appropriate in this document. The web interface will probably stay your initial go-to way to connect to the SBC, especially for tasks that benefit from graphical interaction, like setting up wireless or using the webcam.

====SSH====

The most flexible way to transfer files and commands to and from the SBC is via a program called '''ssh'''. The ssh program provides command line text access over a network into the SBC. Using it, you can run programs and give the SBC commands. The ssh program has a companion program called '''scp''' which can copy files back and forth. If you are unfamiliar with ssh, you can think of it like the command line or a Mac terminal, but with a remote connection to a different computer. It is a minimal yet effective way to interact with a remote computer.

Before connecting over ssh, you will need:
* The '''IP address''' (such as 168.254.3.0) or '''link local address''' (such as phidgetsbc.local) of the SBC
* The '''admin password''' for the SBC
Both of these items can be found by following the steps in the [[1072 0 - Getting Started | Getting Started Guide for the SBC]].

You will also need to enable SSH on the SBC side. This can be done through the [[#SBC Web Interface| Web Interface]], under {{Code|Network → Settings}}, by changing the ''SSH Server'' radio button to ''Enabled'' and saving your changes:

[[File:sbc_turn_on_ssh.png|link=|alt=]]

=====SSH on Windows=====

The ssh program is not installed on Windows by default. But, there are a variety of SSH programs available for free. One simple and commonly used program is [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY], and it has the advantage that the executable doesn't need to install, it just runs.

With PuTTY, when you first run the program it will ask you what to connect to. Enter the IP address or link local address of the SBC, and then click the SSH radio button right below the address, which will change the port to 22. Then click open, and you'll have an ssh connection to the SBC open in a terminal. It will prompt you for a user name ({{Code|root}}) and password (the admin password).

To copy files back and forth, there is an SCP component to PuTTY, called PSCP, which is available from the same [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY download page]. Use of PSCP will be similar with the address, username, and password, except that you will be transferring files instead of sending commands.

=====SSH on Linux and Mac OS=====

Linux and Mac OS already have ssh installed by default. To run ssh simply open a terminal...
* {{Code|Ctrl-Alt-T}} on Linux
* {{Code|Applications → Utilities → Terminal}} on Mac OS
...and type:

<div class="source">
<syntaxhighlight lang=bash>
ssh root@phidgetsbc.local
</syntaxhighlight>
</div>

If you have re-named your SBC, include that name instead of the {{Code|phidgetsbc.local}} link address. Or, you can use the SBC's IP address, e.g. something like {{Code|ssh root@168.254.3.0}}

To copy files back and forth, the command follows the form of: {{Code|scp from to}}

So, to copy a file {{Code|/root/data.txt}} from the SBC to your local machine, type:

<div class="source">
<syntaxhighlight lang=bash>
scp root@phidgetsbc.local:/root/data.txt .
</syntaxhighlight>
</div>

Note the use of the dot '''.''' to indicate that scp should put the file in the current local directory. If you're not sure what folder the terminal is operating in type {{Code|pwd}} to print the working directory. Terminals usually start by default in your home folder.

===Getting Started - The SBC (Debian Linux)===

The SBC runs Linux, which is a full operating system. It is stripped down compared to a full desktop release of Linux, but you can compile code on it, run programs, schedule tasks, create and manage files, run a web server, and much, much more.

At this point you have connected to the SBC via the [[#SBC Web Interface|web interface]], and probably also through [[#SSH|SSH]]. This section will help you install libraries and drivers that you probably want - i.e. support for C, Java, and Python. After this section, you'll be well into the depths of using the SBC as a computer, and so you'll probably want to keep the [[#Using SBC Linux|Using SBC Linux section]] open for reference while you work if you are not already familiar with Linux.

The SBC comes with the following Phidget functionality installed:
* The Phidget C libraries {{Code|libphidget21.so}}
* The Phidget [[#WebService | WebService]]
(If you are simply curious what these are and how they get installed, we describe the process on the [[OS - Linux | general Linux page]].)

But to compile C programs, or run Java programs, or use Python, you will need to install these languages onto the SBC.

Before installing anything on the SBC, however, (even via a button on the web interface) make sure that the ''Include full Debian Package Repository'' option is checked in the web interface under {{Code|System → Packages}}.

====Installing C/C++ and Java====

The simplest way to install C/C++ and Java on the SBC is via the web interface. There is a button under {{Code|System → Packages}} to install C support (including {{Code|gcc}}) and another button to install Java support:

[[File:sbc_packages_web.png|link-|alt=]]

Now you're ready to begin programming. We have programming pages for both [[Language - C/C++|C/C++]] and for [[Language - Java|Java]]. Remember that if you're unfamiliar with Linux, we have help on using files and running programs automatically in the [[#Using SBC Linux|Using SBC Linux section]].

If you want to avoid using the [[#SSH|SSH]] interface on the SBC entirely, and you want to write your program in Java and run it continuously from boot (which is the only option if you want to avoid [[#SSH|SSH]]), we have a [[#Program in Java with the Web Interface|very in-depth section]] on that topic.

====Installing Python====

Installing Python has two steps. First, you'll need to install the basic ability to run python, and then you'll need to install the Phidget Python module. Both steps (and both options) require that you issue the relevant commands through an [[#SSH|SSH terminal]].

=====Basic Python=====

The base Python functionality can be downloaded and installed in one step with [[#apt|apt]] (i.e. in a terminal, type):

<div class="source">
<syntaxhighlight lang=bash>
apt-get install python
</syntaxhighlight>
</div>

This will give you Python, and now you just have to install the Phidget Python module to gain Phidget functionality.

=====Install Phidget Python Method 1: Use a USB Key=====

Copy the [{{SERVER}}/downloads/libraries/PhidgetsPython.zip Python Libraries] onto a USB key. Unpack the zip file into a folder on the USB key. Insert the key into the SBC.

You will have to figure out where the USB key (and the Phidget Python library folder) is now located. We describe how in the general [[#Using USB Data Keys | Using USB Data Keys]] section.

After you know the place where the USB key is mounted, in a terminal go to that directory (e.g. type {{Code|cd /media/usb0/}}), enter the unpacked Phidget Python Library folder, and run:

<div class="source">
<syntaxhighlight lang=bash>
python setup.py install
</syntaxhighlight>
</div>

Now, you're ready to begin writing Python code for the SBC. For more help on writing and using Python with Phidgets, we have an whole [[Language - Python | page on that topic]]. Remember that if you're unfamiliar with Linux, we have help on using files and running programs automatically in the [[#Using SBC Linux|Using SBC Linux section]].

=====Install Phidget Python Method 2: Use the Internet=====

Rather than using a USB key to transfer the file, the SBC can download it directly from the internet. You will need {{Code|wget}} and {{Code|unzip}} installed, both of which are small:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install wget
apt-get install unzip
</syntaxhighlight>
</div>

Copy the web link address for the [{{SERVER}}/downloads/libraries/PhidgetsPython.zip Python Libraries].

In an SSH terminal to the SBC, type: {{Code|wget http://www.python_library_link}} where instead of http://www.python_library_link you insert the link you just copied. Copying into a terminal can usually be done via the right-click menu.

This will download the Phidget python libraries to the folder you ran the {{Code|wget}} command in. Unzip the downloaded file using the command {{Code|unzip file}}, where file is the filename from {{Code|wget}}. Or try typing {{Code|ls}} to list the names of a file in the directory, which should include the unzipped folder. Enter the unzipped folder (e.g. use {{Code|cd}} to change directory), and install the Phidget Python libraries:

<div class="source">
<syntaxhighlight lang=bash>
python setup.py install
</syntaxhighlight>
</div>

Now, you're ready to begin writing Python code for the SBC. For more help on writing and using Python with Phidgets, we have a whole [[Language - Python | page on that topic]]. Remember that if you're unfamiliar with Linux, we have help on using files and running programs automatically in the [[#Using SBC Linux|Using SBC Linux section]].

====Installing Other Languages====

You may also be able to program on the SBC using [[Language - Ruby|Ruby]] and [[Language - C Sharp|C# under Mono]], though we do not offer in-depth support for these languages on the SBC. The installation procedures should more or less follow that of [[#Installing Python|installing python]] on the SBC, except you will be installing Ruby or Mono. Performing package searches using [[#apt|apt cache search]] can help you find the relevant software.

For C#, as of 2012 the {{Code|mono-complete}} package is broken on the Debian Squeeze repository. Rather, you have to install the Mono runtime and Mono compiler separately.

To install the runtime package (and its dependencies), use [[#apt|apt]]:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install mono-runtime
</syntaxhighlight>
</div>

Then, to install the C# compiler:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install mono-gmcs
</syntaxhighlight>
</div>

Or the Visual Basic compiler:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install mono-vbnc
</syntaxhighlight>
</div>

Then, the system and library packages do not link correctly for the version 2.0 of Mono. If this is the case, your code will compile fine, but when you try to run it, you will get an error like:

:{{Code|The assembly mscorlib.dll was not found or could not be loaded.}}
:{{Code|It should have been installed in the `/usr/lib/mono/1.0/mscorlib.dll' directory.}}

In this case, you need to install these two packages:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install libmono-corlib1.0-cil
apt-get install libmono-system1.0-cil
</syntaxhighlight>
</div>

Here we found these packages to work by working through the tree structure. As a general rule, you can find these dependencies by using install (here, {{Code|apt-get install mono-complete}}) to get a sense of the package tree structure. This will possibly tell you that the packages are broken, but at the same time this will list the dependencies of the packages. Trying to install individual dependencies will show you that although a root-package fails, the sub-packages will sometimes succeed, and install what you need.

If you want to use a specific dll or library that is not available in this reduced version of mono, you can install mono complete by switching from Emdebian+Debian to just Debian. To do this:

In {{Code|/etc/apt/preferences}} make the following changes:
:{{Code|Package: *}}
:{{Code|<nowiki>Pin: release a=stable</nowiki>}}
:{{Code|Pin-Priority: 1010}}

In {{Code|/etc/apt/sources.list/mutistrap-debian.list}} remove the emdebian line.

Apply the changes:

<div class="source">
<syntaxhighlight lang=bash>
apt-get update
apt-get dist-upgrade
</syntaxhighlight>
</div>

Many packages will be 'downgraded' from the emdebian to debian versions. Delete the {{Code|<nowiki>/etc/apt/preferences</nowiki>}} file and install mono-complete:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install monodoc-http mono-complete
</syntaxhighlight>
</div>

Choose monodoc-http explicitly, because otherwise the install fails on monodoc-browser.

After this process, you can compile your C# Code.cs Phidget source file the same way as on a generic [[Language - C Sharp#Linux|Linux with Mono]] system. Please refer to that page on how to obtain the *.dll Phidget resource file and compile your code. On the SBC, however, because you are already running as root (the Super User), you do not need 'sudo' and indeed the SBC will give you an error if you use it. Instead, compiling and running will look like:

<div class="source">
<syntaxhighlight lang=bash>
gmcs Code.cs -r:Phidget21.NET.dll
mono Code.exe
</syntaxhighlight>
</div>

==Using SBC Linux==

Now that you've set up communication with the SBC, and installed whichever programming language support you need, you're probably ready for a short tour of useful tools on the SBC's version of Linux.

First, you will by default be running on the SBC as '''root''', which is the super-user. For Linux users, this probably makes you nervous because you know you can overwrite important system files without the system asking for additional permission. As a Windows or Mac OS user - although you may usually run your computer as an administrator - your familiar system usually prompts you to confirm before you do anything really dangerous, and this will '''not''' happen on the SBC as the root user.

Next, there is no installed help on the SBC. Help on Linux is usually called 'man pages' which is short for 'the manual pages'. On a full Linux system, usually if you need help with any command you can type, for example, {{Code|man ls}} and it will give you help with the program [[#ls|ls]]. But these help pages take up significant space, and they are widely available online. So, if you need more help with a certain command, you can always type {{Code|man command}} into your favourite search engine.

Finally, the SBC has no windowing system. For Linux users, this means no X-windows (Gnome, KDE, etc). And as a Windows or Mac user, you can think of it as running all of your programs and commands through the terminal or DOS prompt command line. The SBC provides all of the functionality of an operating system (e.g. process scheduling, file management, etc) but without any graphical interface. The only exception is the [[#SBC Web Interface|web interface]], which gives graphical access to a limited part of what the SBC can do.

===Some Useful Commands===

If you are doing more with the SBC than simply running pre-written programs [[#Writing a Phidget Program|in Java to run continuously from boot]], you will be interacting with the SBC's Linux operating system over the command line by using [[#SSH|SSH]]. This section discusses useful programs already installed on the SBC, and how to run them on the command line.

====ls====

The '''ls''' program lists the contents of a directory.

It will show both files and folders, but not files that start with a "." (these are hidden files on Linux).
*If you also want to show hidden files, use {{Code|ls -a}}
*If you want more information, such as size and date modified, use {{Code|ls -l}}
*Commands can be combined, like {{Code|ls -al}}

====cd====

The '''cd''' program changes to a new directory.

For example, {{Code|cd /root}} changes into the directory at the base of the file tree called ''root''.

Note:
* Linux uses forward slashes
* The base of all directories is "/" (not "C:\")
* The tilde symbol (~) is short for your home directory (i.e. when you are root, this is short for "/root")
* The double dot ".." means move one directory higher (for example from {{Code|/root/data/}} to {{Code|/root/}})

====pwd====

The '''pwd''' program prints the current directory you are working in. ('P'rint 'W'orking 'D'irectory)

For example:
:{{Code|root@phidgetsbc:~# pwd}}
:{{Code|/root}}

====cp, mv, and rm====

These programs are copy ('''cp'''), move ('''mv'''), and remove ('''rm''').

Copy copies a file from one location and pastes it to another.

For example, if you have a file {{Code|data.txt}}, typing {{Code|cp data.txt data_backup.txt}} will put a copy of the file {{Code|data.txt}} into {{Code|data_backup.txt}}

Move moves a file (this is also useful for renaming files) to a new destination.

For example, if you have a file {{Code|data.txt}}, typing {{Code|mv data.txt data_backup.txt}} will put the contents of {{Code|data.txt}} into {{Code|data_backup.txt}}, and then will remove {{Code|data.txt}}.

Remove deletes a file.

For example, typing {{Code|rm data.txt}} will delete {{Code|data.txt}}.

Note that '''rm''' is final. Once you remove a file using {{Code|rm}}, it is gone forever. There is no recycle bin, no temporary trash, nothing other than backups you may have personally created in the past!

Directories can only be removed with {{Code|rmdir}}, and then only if they are empty. If you want to remove a directory and all the files in it, use {{Code|rm -rf directory}} but be '''very, very careful''' with this command. Trying to remove everything within a directory (e.g. {{Code|rm -rf *}}) is one of the most dangerous commands you can run on a Linux system, as running it from the wrong directory will result in Linux happily removing everything under that directory -- which could be your entire filesystem.

====find====

The '''find''' program does what it says - it finds things.

Unfortunately for the casual user, the find program is very flexible and powerful, and thus not especially intuitive to use. But, here are some examples:

{| style="border:1px solid darkgray;" cellpadding="15px;"
|-
! SSH Command
! What it Does
! Example
|-
| {{Code|find folder -name file.txt}}
| Looks for all files in a folder (/ for root - or all - folders) with a certain name (* for wildcard)
| {{Code|find / -name *.jpg}}
|-
| {{Code|find folder -mtime +X}}
| Looks for all files in a folder modified less than X days ago
| {{Code|find /root -mtime +30}}
|}

====grep====

The '''grep''' program takes text input and searches for a term.

For example, if you type {{Code|mount}} to view what devices are mounted (e.g. loaded) on your SBC, you will see:

<div class="source">
<syntaxhighlight lang=text>
root@phidgetsbc:~# mount
tmpfs on /lib/init/rw type tmpfs (rw,nosuid,mode=0755)
proc on /proc type proc (rw,noexec,nosuid,nodev)
sysfs on /sys type sysfs (rw,noexec,nosuid,nodev)
udev on /dev type tmpfs (rw,mode=0755)
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev)
devpts on /dev/pts type devpts (rw,noexec,nosuid,gid=5,mode=620)
rootfs on / type rootfs (rw)
procbususb on /proc/bus/usb type usbfs (rw)
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

This may be a lot of information you don't need. If you are only interested in a USB key attachment (as described in the [[#Using USB Data Keys|Using USB Data Keys]] section), you can use grep to filter that one response:

<div class="source">
<syntaxhighlight lang=text>
root@phidgetsbc:~# mount | grep sda1
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

====nano====

The '''nano''' program is a small text editor that you can use within an SSH terminal.

Nano can be surprisingly useful for writing short lengths of code right on the SBC, so there is no need to transfer files and keep track of different file versions on different computers.

Nano has all keyboard commands which are listed at the bottom of the screen at all times as a reminder (Ctrl-O to save, Ctrl-X to exit, these expand with a larger terminal window). And, nano provides what is called 'syntax highlighting', which colours reserved keywords, comments, strings, and so on as appropriate to the programming language you are using. Nano detects the programming language via the extension of the file ({{Code|.java}} for Java, {{Code|.c}} for C/C++, and {{Code|.py}} for Python).

Typing {{Code|nano test.py}} on an SSH command line and then entering a few lines of Python into the new empty file results in:

[[File:sbc_nano_python.png|link=|alt=]]

====apt====

The '''apt''' program allows you to install, uninstall, upgrade, and search software available for the SBC.
For a non-Linux user, the apt framework may be daunting at first, but it actually allows you to keep your system up to date and install and manage software quickly, easily, and for free.

'''Note:''' Before installing anything on the SBC, make sure that the ''Include full Debian Package Repository'' option is checked in the web interface under {{Code|System → Packages}}.

{| style="border:1px solid darkgray;" cellpadding="15px;"
|-
! SSH Command
! What it Does
! Example
|-
| {{Code|apt-cache search term}}
| Looks for all programs (packages) that have {{Code|term}} in the title or description
| {{Code|apt-cache search opencv}}
|-
| {{Code|apt-cache show package}}
| Shows a lot of data about {{Code|package}} including size, version, etc
| {{Code|apt-cache show unzip}}
|-
| {{Code|apt-get update}}
| Gets the most recent listing of available software
| {{Code|apt-get update}} (No options)
|-
| {{Code|apt-get install program}}
| Installs {{Code|program}} from the internet
| {{Code|apt-get install python}}
|-
|}

====mount====

The program {{Code|mount}} shows you all of the mounted devices on your SBC.

For example:

<div class="source">
<syntaxhighlight lang="text">
root@phidgetsbc:~# mount
tmpfs on /lib/init/rw type tmpfs (rw,nosuid,mode=0755)
proc on /proc type proc (rw,noexec,nosuid,nodev)
sysfs on /sys type sysfs (rw,noexec,nosuid,nodev)
udev on /dev type tmpfs (rw,mode=0755)
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev)
devpts on /dev/pts type devpts (rw,noexec,nosuid,gid=5,mode=620)
rootfs on / type rootfs (rw)
procbususb on /proc/bus/usb type usbfs (rw)
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

For the non-Linux user, the concept of a device may be quite strange. To give a short summary, everything on Linux that you can read or write is a file. Webcams are files (i.e. you can 'read' photos from them), USB keys are files, and each filesystem (tmp storage, the kernel portion, the main filesystem) are also themselves files. These files specify what and how something can be written. These are not necessarily linear, for example, you can see above that the USB key ({{Code|/media/usb0}} is mounted ''within'' the root file system {{Code|rootfs}} which is /.

So mount gives you an idea of what devices have been 'mounted' for reading or writing, and how you can read and write to them. More information on mount (and its various forms, like {{Code|umount}}) is available widely around the Internet.

====which====

The program {{Code|which}} tells you if and where a program is installed.

For example, on a default SBC, typing {{Code|which python}} will return no results. But after successfully [[#Installing Python | installing python]], it will return {{Code|/usr/bin/python}} as the location of the python program/binary/executable.

===Some Useful Commands to Install===

These are other programs you may find useful on the command line. Although they are not on the SBC by default, these and other programs can usually be installed simply by using [[#apt|apt-get install]], with the exception of gcc. For example, {{Code|apt-get install wget}} will download and install [[#wget|wget]].

'''Note:''' This section and the section on [[#Some Useful Commands|pre-installed commands]] can hardly cover all of the complexities and power of the Linux operating system. There are many excellent tutorials online, and between them and using [[#apt|apt]] to find and install programs you should be able to learn a lot and perform any number of complex useful tasks.

====gcc====

The '''gcc''' program is the C compiler for Linux.

If you are an experienced C/C++ user on Mac or Linux, or if you've already read our [[Language - C/C++ | C Language page]], you might think you need to install gcc via {{Code|apt-get}} to compile C code. However, gcc is not in the package repository for the SBC, so {{Code|apt-get install gcc}} will fail. Rather, to install gcc, you can do it via the web interface, as described in the [[#Installing C/C++ and Java|Installing C/C++ and Java]] section.

After installing it via the SBC web interface, you can use {{Code|gcc}} normally.

====less====

The '''less''' program displays the contents of a text or source code file. When displaying the file, {{Code|less}} allows you to scroll up and down to read it.

This is useful if you are writing your sensor readings to a data file, and you want to read the data file while it is being written by your main code. If your data file is called {{Code|data.txt}}, you can type {{Code|less data.txt}} and see the lines in the file, and what they are.

The {{Code|less}} program output can also be piped into another program. For example, you can use {{Code|less}} and the word search program {{Code|grep}} to find lines within a file with a search term. For instance, if you have a C source code file {{Code|Program.c}} on the SBC, and you want to see all the lines in {{Code|Program.c}} that contain a variable name {{Code|var}}, you can type:
:<code>less Program.c | grep var</code>

====wget====

The '''wget''' program allows you to get an online file (over http) and download it to the SBC.

For example, to get the source file (HTML) from the Phidgets home page, you can type:

<div class="source">
<syntaxhighlight lang=bash>
wget http://www.phidgets.com
</syntaxhighlight>
</div>

This is most useful for downloading libraries, drivers, or anything (zip, tar, etc) you need from the web which is not available by [[#apt|using apt]].

===Writing a Phidget Program===

We provide two ways to write and upload a Phidget Program:
# The [[#SBC Web Interface|web interface]]:
#* This is useful for simple projects written in Java that you want to start only at boot
#* You can also use C projects, but they must be compiled off the SBC for an ARM processor
# Over [[#SSH|SSH]], which will allow you to write or transfer source code directly to and from the SBC
#* This is useful for all other projects, such as:
#** Projects that run at scheduled times (e.g. once per minute)
#** Projects that use languages other than Java or ARM-compiled C
Note that you can still run an [[#SSH|SSH]] project at boot, you just have to write and install a startup script. This is a bit complex, but we do have an example that starts the program {{Code|phidgetwebservice21}} [[OS - Linux#As A Service|at boot using a script]].

Once you know which method you'd like to use, you can continue on to learn how to [[#Program in Java with the Web Interface|Program in Java with the Web Interface]], or how to [[#Program with SSH|Program with SSH]] using Java, C, or Python. If you are actually typing in source code on the SBC, you'll find our [[#Developing Code on the SBC|developing code on the SBC section]] useful.

====Program in Java with the Web Interface====

To show how to write, compile, and install Java programs on the SBC, we'll use the [[Language - Java|Java Hello World]] example code. You can download the HelloWorld example by downloading the whole [{{SERVER}}/downloads/examples/JavaJNI.zip Java example package]. Make sure you have [[#Installing C/C++ and Java|Java installed on the SBC]].

Here's how to get the HelloWorld code running on the SBC. On your external computer:

1. Download the SBC version of the Phidget Java libraries ({{Code|phidget21.jar}}). You can download this from the [[#SBC Web Interface|web interface]], on the page under {{Code|Projects → Projects}}, under the '''Notes''' section.

2. Place the SBC version of {{Code|phidget21.jar}} into a directory on your external computer. This will be your working directory that you will use to compile the Java files.

3. Also copy the {{Code|HelloWorld.java}} file into that working directory.

4. Compile the {{Code|HelloWorld.java}} file from within that working directory. From the command line prompt on Windows, this will be:
<div class="source">
<syntaxhighlight lang=bash>
javac -classpath .;phidget21.jar HelloWorld.java
</syntaxhighlight>
</div>
In a terminal on Linux or Mac OS, this will be:
<div class="source">
<syntaxhighlight lang=bash>
javac -classpath .:phidget21.jar HelloWorld.java
</syntaxhighlight>
</div>

5. You should now have three compiled class files: {{Code|HelloWorld.class}}, {{Code|HelloWorld$1.class}}, and {{Code|HelloWorld$2.class}}. You don't need to try and run them, and if you do you may encounter an error because the SBC {{Code|phidget21.jar}} may be slightly different than the Phidget support you have installed on your external computer.

Now we move onto the SBC:

6. Create a new project on the SBC, in the web interface under {{Code|Projects → Projects}}. Call it HelloWorld:

[[File:sbc_create_project.png|link=|alt=]]

7. On the next screen, you will be prompted to upload your files. We will upload the three Java class files, and then click the {{Code|Start}} button:

[[File:sbc_web_run_project.png|link=|alt=]]

8. You'll note that as it runs, there are two links below the {{Code|Stop}} button: One called {{Code|stdout}}, which is ''Standard Output'', and one called {{Code|stderr}}, which is ''Standard Error''. Usually, when you run a program on the command line, you see both standard out and standard error at the same time - i.e. you get all program output right there in your terminal or command prompt. But when running a program in the background, Linux splits the output up into normal output and error output as this is very useful for debugging (i.e. you can check if standard error is empty).

Here, however, if you're not sure whether the program will run correctly, you should first check {{Code|stderr}} to see if any errors were generated, and then check {{Code|stdout}} to see if the output looks as expected.

To write your own Java program, follow the same process but use your own source code instead of the {{Code|HelloWorld.java}} example.

Now that you have a running program, we offer additional help on [[#Via the Web Interface|running a program automatically using the web interface]].

====Program with SSH====

Similarly to starting a program via the [[#Program in Java with the Web Interface|web interface]], we use the Phidget Java {{Code|HelloWorld}} example here.

Make sure you have [[#Installing C/C++ and Java|Java installed on the SBC]]. To compile and run the {{Code|HelloWorld}} example:

1. Open an [[#SSH|SSH terminal]] to the SBC

2. Download the [{{SERVER}}/downloads/examples/JavaJNI.zip Phidget Java Examples] to the SBC, using [[#wget|wget]] (you may need to install {{Code|wget}} using [[#apt|apt]].)

3. Unpack the examples using [[#unzip|unzip]] (you may need to install {{Code|unzip}} using [[#apt|apt]].)

4. The location of {{Code|phidget21.jar}} on the SBC is {{Code|/usr/share/java/phidget21.jar}}. Within the unzipped example directory, compile the {{Code|HelloWorld.java}} example:

<div class="source">
<syntaxhighlight lang=bash>
javac -classpath .:/usr/share/java/phidget21.jar HelloWorld.java
</syntaxhighlight>
</div>

5. To run the {{Code|HelloWorld}} program, use:

<div class="source">
<syntaxhighlight lang=bash>
java -classpath .:/usr/share/java/phidget21.jar HelloWorld
</syntaxhighlight>
</div>

Now that you have a running program, you'll probably want to learn to [[#Running a Program Automatically|run this Java program automatically]].

'''Permissions Note:''' If you're used to using Linux with Phidgets already, you'll probably notice that you don't need to switch into root using {{Code|sudo}} on the SBC in order to run programs. This is because you already are running as root, not because the [[OS - Linux#Setting udev Rules|udev rules are set up]]. So if you set up another user, or [[#Via Cron|run a cron job]] as anything other than root or system, you'll need to add permission for the Phidget program to run in your [[OS - Linux#Setting udev Rules|udev rules]].

====Developing Code on the SBC====

When you're not just using pre-written source code, and you're writing code actually on the SBC itself, you'll probably want to use [[#nano|nano]]. Other terminal editors on the SBC include {{Code|vi}} which is already installed, and {{Code|emacs}}, which you can install using [[#apt|apt]]. Both {{Code|vi}} and {{Code|emacs}} are much more efficient for the experienced user, but they contain modes and keyboard shortcuts that can seem strange or almost hindering to the casual user.

Regardless of which editor you choose to use, some of your keyboard habits may not transfer well. For example, in the Linux command line, the command {{Code|Ctrl-C}} means ''stop the currently running program'', (i.e. your open editor) not copy. Within most SSH terminals, you can copy and paste using the right-mouse button, and on some terminals (and all native Linux terminals) you can copy by simply highlighting text, and you can paste it using the middle (scroll) mouse button. On the other hand, if you write a program that hangs on the command line, {{Code|Ctrl-C}} can actually be useful to terminate it.

Also {{Code|Ctrl-Z}} does not mean ''undo'', rather it means ''run the current program in the background''. This is useful because running a program in an SSH terminal simply hangs your SSH input until the program is done. So typing {{Code|Ctrl-Z}} while the program is running frees up the command line for more input. But if you accidentally hit {{Code|Ctrl-Z}} while running an editor like [[#nano|nano]], the editor will immediately exit to the command line. Don't worry though, it will not stop or lose your work. You can bring it back up by using the {{Code|fg}} (e.g. 'foreground') command, like {{Code|fg nano}}, and this will automatically bring your nano process back to the front.

===Running a Program Automatically===

For testing your program, you will certainly want to run it via [[#SSH|SSH]] or via the {{Code|Start}} button on the project page on the web interface until you are quite sure it runs well. However, eventually you will probably want the program to run without your input, either [[#Via the Web Interface|continuously, and starting at boot]], or via a task scheduled to [[#Via Cron|run to completion at certain times]].

Both have their advantages and disadvantages. Usually, you would want to use the continuous, from-boot methods for event driven code that has to handle a wide variety of user input that could occur at any time. You would want to use the scheduled method when the SBC needs to perform a repeated task (e.g. reading sensor data) again and again. The main difference is:
* With the continuous (boot) method you can have any Phidgets (including sensors, LEDs, input switches, etc) attached and giving events to your code all the time, and
* With the scheduled (cron) method you have much less of a chance to run into long-term memory management and instability problems with any code you write, because your program runs for only a short time before exiting and getting cleaned up.

====Via the Web Interface====

To use this method, you must have created the program you want to run as [[#Program in Java with the Web Interface | a Java or ARM-compiled C project in the web interface]]. If you would like to use another language, or another way of uploading your project, but you still want to start at boot and run continuously, you will need to use a [[#Via a Boot Script|boot script]].

In the web interface, go to the {{Code|Projects}} tab, and click on the project you would like to run. Near the bottom of the project page (the one with the {{Code|Start}} and {{Code|Stop}} buttons at the top), there will be a section called {{Code|Startup Settings}}. You can see a screenshot of the whole project page, including these settings, in the [[#Program in Java with the Web Interface | web interface project section]].

Select the {{Code|Enabled}} radio button. The other defaults should be fine, unless you specifically know otherwise:
* For ''Boot Order'', lower numbers boot first. Booting later means more programs are available for use, booting earlier means other programs can use your program.
* ''Run as a daemon'' starts the program as a daemon, which is a program that runs in the background. Unless you have ''explicitly'' written your program as a daemon, leave this checked. (If you don't know what a daemon is, don't worry, you haven't written one, so leave it checked.) ''Un''checking this when your program is a normal program will cause the SBC to hang while booting.
* The ''Executable or Class'' name should be automatically sensed to be your main Java class
* ''Arguments'' are any command line arguments you need, just as you would type them into the command line

'''Note:''' Your program must be very, very stable to run properly via the web interface. Imagine your program running continuously for days, or months on end. Any memory leaks, over time, will render your program (and the SBC) unusable until a reboot. Counts or other variables that increase within your program and never reset may create a segmentation fault eventually.

If, for stability purposes, you want your program to start, run for a little while, and then exit so that the SBC operating system can clean up the memory each time, you'll probably want to use [[#Via Cron|Cron]] to run your program instead.

====Via Cron====

Cron can automatically schedule programs - known as 'jobs', or 'cron jobs' - at most once per minute. Less often than that, it is very flexible, allowing you to run it on certain months, weekdays, hours, etc. Cron simply reads a special file (your {{Code|crontab}}) and runs whatever programs are listed, with whatever timing they are listed with. The cron program runs all the time in the background, making it what is known as a Linux ''daemon'', but the programs it starts as jobs run only as long as they naturally would, and then they exit.

If you need your program to run more often than once per minute, have the program schedule itself while still running. For example, to run every five seconds, run a fast loop, and sleep for five seconds. Do this twenty times and exit. Then schedule this once per minute using cron, and your program will in essence run every five seconds.

Setting up a cron job simply entails editing your {{Code|crontab}} file.

First, you'll probably want to specify your default editor to be [[#nano|nano]]. Otherwise it will default to {{Code|vi}} and you'll have to figure out {{Code|vi}} in order to add lines to your crontab:

<div class="source">
<syntaxhighlight lang=bash>
export EDITOR=nano
</syntaxhighlight>
</div>

Then, to edit your crontab file, simply type:

<div class="source">
<syntaxhighlight lang=bash>
crontab -e
</syntaxhighlight>
</div>

Each line of the crontab file is one scheduled job. Lines that start with a hash "#" are comments and are ignored. There is an example line in the crontab, and a reminder line at the very end. Essentially, each line should contain:

<div class="source">
<syntaxhighlight lang=text>
minute hour dayOfMonth month dayOfWeek command
</syntaxhighlight>
</div>

Where:
*{{Code|command}} is the program you want to run (with absolute path, and arguments)
** For example, {{Code|./myprogram argument1}} won't work, but {{Code|/root/code/myprogram argument1}} will
* Each time argument is either a number, a list of numbers separated by commas, or an asterisk
** For example, * * * * * means every minute for all days and months, 0,30 * * * * means every thirty minutes (i.e. at the top of the hour and at 30 minutes in) for all days and months

If you already have jobs scheduled, you'll see them in the file that comes up. You can edit, add, or delete.

After you save, you'll see a little message back in the terminal that says the new crontab file was installed, and it is now scheduled! Cron always starts every boot, and so if you have edited and installed your crontab as above, the scheduling of your program will start properly even after a reboot of the SBC. However, if you are having strange scheduling problems, you may want to familiarize yourself with the [[#Software Details|software details]] of how the SBC as a whole determines the current date and time.

=====My Cron Job Doesn't Work!=====

It is actually very common for a script or program to work on the command line but then ''not'' work as a cron job. The most common reason for this, by far, is that you specify ''relative'' paths in your program to access files rather than ''absolute'' paths. For example:
* {{Code|code/project.c}} is a relative path (bad for cron)
* {{Code|/root/code/project.c}} is an absolute path (good for cron)
The cron jobs are ''not'' executed from your home directory, or your code directory, so they will not be using the same location you may be using to test your code. So always use absolute paths.

Another common reason is you may be using environment variables or other settings that are true in a terminal but are ''not'' true by default in the raw system. You can end up taking many things for granted in a shell, for example the shortcut "~" means home directory in a shell, but not by default in the raw system. The things that get loaded for a shell (but which are not present in the raw system) are:
* The settings loaded by {{Code|/etc/profile}}
* Any settings in {{Code|~/.bashrc}}, which is nothing by default on the SBC

On a full Linux operating system, you would use the logs written to by cron to find the error output and debug it. On the SBC, however, cron does not write logs (otherwise, these logs would eat up the SBC memory very quickly even for routine jobs). For short-term debugging, you can write output from your program to a file, and read that file afterwards to figure out what your program is doing.

====Via a Boot Script====

If you want to run your program constantly and for it to start at boot like the [[#Via the Web Interface|web interface would do]], you can install your program into the boot order using a script. This is a somewhat involved process, and you should be familiar with shell programming in Linux. For this process, we only offer a [[OS - Linux#As A Service|similar example]] which installs and runs the program {{Code|phidgetwebservice21}} within the boot sequence.

===Using USB Data Keys===

After plugging the USB key in, it won't just appear on your desktop, so to speak, so you'll need to figure out where you can read and write to it within the SSH directory structure.

The web interface program can help with this. After you plug a USB key in, it will show up under {{Code|Status → System}}. Or, the USB key and all other attached devices can be seen at {{Code|Status → USB}}:

[[File:sbc_mounted_devices.png|link=|alt=]]

In the screenshot above, you can see that the USB key is located in {{Code|/media/usb0}}.

Alternately, you can use the SSH command {{Code|mount}}, and the searching program {{Code|grep}} which will filter the response of {{Code|mount}} and only return the lines with your search term ({{Code|usb}}):

<div class="source">
<syntaxhighlight lang=bash>
root@phidgetsbc:~# mount | grep usb
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

In this case, the USB key can be written to and read from using the {{Code|/media/usb0}} directory. Copying a file to {{Code|/media/usb0}} will copy a file to the USB key. The same goes for removing, renaming, opening files within your program, etc.

'''Note:''' Mount points like {{Code|/media/usb0}} should not be hard-coded into any of your programs. (See the [[#Common Problems and Solutions | Common Problems and Solutions]] section for more information.) If you need to obtain the mount point for a freshly mounted USB key within your code, have your code obtain the mount tables and search on the ''device'' (e.g. {{Code|/dev/sda1}} or {{Code|/dev/sdb1}}) and obtain the corresponding mounted {{Code|/media/usbN}} location, where N is a number 0-9.

===Saving and Retrieving Data===

This section covers getting data on and off of the SBC. There are two main methods of simply moving data on and off the SBC - via a [[#Via a USB Key|USB key]], and via [[#Over the Network (SCP)|copy over the network]] - and a third method for moving and installing data when it concerns [[#Backing Up Your Data|backing up lower level system data]].

====Via a USB Key====

After plugging in a USB data key, first you need to [[#Using USB Data Keys | find out the location]] where that data key was mounted.

Let's say the location of the USB key is {{Code|/media/usb0/}}, and we want to copy the file {{Code|data.txt}} to the USB key. Your SSH session might look something like this, using [[#ls|ls]] and [[#mount|mount]]:

<div class="source">
<syntaxhighlight lang=bash>
root@phidgetsbc:~# ls
data.txt
root@phidgetsbc:~# mount
tmpfs on /lib/init/rw type tmpfs (rw,nosuid,mode=0755)
proc on /proc type proc (rw,noexec,nosuid,nodev)
sysfs on /sys type sysfs (rw,noexec,nosuid,nodev)
udev on /dev type tmpfs (rw,mode=0755)
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev)
devpts on /dev/pts type devpts (rw,noexec,nosuid,gid=5,mode=620)
rootfs on / type rootfs (rw)
procbususb on /proc/bus/usb type usbfs (rw)
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
root@phidgetsbc:~# cp data.txt /media/usb0/
</syntaxhighlight>
</div>

The '''cp''' program copies data from a source to a destination. The syntax is {{Code|cp from to}}, where here we are copying from {{Code|data.txt}} to {{Code|/media/usb0/}}.

'''Caution:''' Even if there is no USB key mounted at {{Code|/media/usb0/}}, this use of {{Code|cp}} will still work ''with no errors''! This is because there is still a file called {{Code|/media/usb0/}}, there is just no USB key file system ''mounted'' to that point. So be sure to run [[#mount|mount]] or use some other method of determining that there is, in fact, a USB data key attached and where it is mounted to.

====Over the Network (SCP)====

SCP is a command line program already installed on Linux and Mac OS, and downloadable for free on Windows. We discuss it and give examples in the [[#SSH|SSH]] section, but remember it here when you're trying to get data on and off of the SBC. With SSH or a terminal already open, you'll probably find it to be much faster and easier than dealing with a USB key.

====Backing Up Your Data====

For the web interface, you can save and restore all web interface settings under the {{Code|System → Backup & Restore}} tab.

To save the settings of what packages are installed for later re-installation, you can type:

<div class="source">
<syntaxhighlight lang=bash>
dpkg --get-selections > installedPrograms.txt
</syntaxhighlight>
</div>

Then save the file {{Code|installedPrograms.txt}} externally. If you have to completely wipe the SBC, you can just reinstall the whole list by moving the {{Code|installedPrograms.txt}} file back onto the SBC, and then typing:

<div class="source">
<syntaxhighlight lang=bash>
dpkg –set-selections < installedPrograms.txt
apt-get dselect-upgrade
</syntaxhighlight>
</div>

Also remember to externally save:
* Your {{Code|~/.bashrc}} settings file if you've changed it
* Your {{Code|crontab}} file if [[#Via Cron|you've edited it]]
* Any data files or code you've created

It is important to save these settings often, and at points where you know the system is running well. It may be tempting to create a backup right before you [[#Recovery System|wipe the SBC and start from scratch]], but often the reason you are having problems then is some setting or change, and backing these up and reinstalling them will only reinstall the problem.

To truly back the files up, you must copy them to an external computer or location using either a [[#Via a USB Key|USB Key]] or [[#Over the Network (SCP) | over the network]]. Then they can be copied back if needed later.

If you are looking to restore data on an SBC that will not boot properly, you'll want to be in the [[#Partial Recovery|partial recovery]] portion of our Troubleshooting section.

==Troubleshooting==

The SBC can be quite tricky to debug, because it is a complex and flexible computer. Common problems and solutions include:
* You can't find the SBC on the network at all - refer to the [[#Initial Internet Setup|Initial Internet Setup]] section
* You have changed some setting or file such that the SBC doesn't run anymore, or doesn't run as expected - refer to the [[#Recovery|Recovery]] section

If you are having trouble using Phidgets on the SBC, you should go through the [[OS - Linux#Troubleshooting | Troubleshooting section on the general Linux page]]. Some of the problems on the Linux page (such as library problems) are easier to fix by simply working through the [[#Recovery|Recovery]] section when they occur on the SBC.

Namely, it often helps to simply perform a [[#Factory Reset|factory reset]] on the SBC (save your files and installed program list first, as [[#Backing Up Your Data|described here]]). Sometimes you change a file or setting within the operating system when you are trying to get something up and running, and this unintentionally affects other programs too. Performing a factory reset starts you with a clean slate.

If your problem doesn't seem to be fixed by these steps, or the information within this guide, please [[Contact Us|ask us]]!

===Initial Internet Setup===

To set up the SBC, you almost always need a ''wired'' Ethernet connection with DHCP (Dynamic Host Configuration Protocol), and without a firewall. This connection should be to a ''router'', not directly plugged in to your computer.

Even if you do not have this type of a connection at home, these types of connections are very common at both offices and universities. On a Windows or Mac OS computer, you can bring up the Phidget Control Panel as described in the SBC's [[1072 0 - Getting Started|Getting Started Page]]. Failing this, or on a Linux computer, we discuss some alternate setup methods in this section. Keep in mind that without a wired, open DHCP connection these setup methods can be difficult and fickle.

====No Wired-Only Connection====

Sometimes it can work to plug the SBC, using Ethernet, directly into an Ethernet port on your home wireless router. Do not plug it directly into your computer! (Although in some instances, a direct connection can be made to work on Linux, see the [[#No DHCP|No DHCP]] section below)

This direct-router method is a very picky process, however, and can fail because:
* Some home and office routers place a firewall between wireless connections (clients) and wired connections (the local area network)
* Some home and office routers do not by default allow both Ethernet DHCP and wireless DHCP.
* Some routers and DHCP hubs only provide access to an internet connection, and do not provide local area network inter-connections (this is common on mobile device tethering hubs)

Routers are quite complex, and even with admin privileges it can be a painstaking process to find all the right firewall settings to turn off in order to allow two computers on the network to talk to one another, rather than just connect to the internet. This is why university or office networks are often ideal for the purpose of setting up the SBC, because these institutions depend on computers on a local network being able to talk together. University libraries in particular can be a good source of wired DHCP connection ports.

Covering all of the different router configuration possibilities here, and how to change them to make the SBC work, is essentially impossible. If you try using the SBC at home or at work, the SBC does not work on the first try when plugged directly into the router via Ethernet, and you want to make that connection work rather than seeking out an alternate for the initial setup, you should find documentation specific to your router (usually available online) and properly configure it.

The good news is that if you can find an Ethernet DHCP connection ''just once'' for a short time, you can use that connection to configure the SBC to work on your home wireless network. During that initial connection, you can enable wireless and set up as many wireless DHCP connections (with passwords) that you need. Once wireless is enabled and set up, you can take the SBC home to your wireless router and the SBC will automatically seek out and connect to its remembered networks as they appear. At that point, you can also use wireless like a normal internet, web interface, and SSH connection.

====No Link Local Addressing====

If you have a wired DHCP connection, no firewall, and no link local addressing (e.g. bonjour or avahi is not installed) then you will need access to the DHCP router logs. From the router logs, you should see the connection (or attempted connection) by the SBC within the logs. From that log entry, you should either be able to determine the IP address for the SBC, or see what happens when the router blocks access. The IP address can be used in place of the link local address for both the web interface and for SSH.

====No DHCP====

The SBC will first try to use DHCP, but then it will revert to responding to a link local address under bonjour and avahi. If you are depending on this, please wait '''at least three minutes''' after the SBC boots for the SBC to fail in obtaining a DHCP connection and properly revert to link local addressing.

If you have a static IP setup, and want to use link local addressing rather than accessing the router logs, this should usually work by default on Windows and Mac OS (e.g. type the address such as {{Code|phidgetsbc.local}} into a web browser). If it doesn't work automatically, there is not much you can do and you should seek out a wired DHCP connection elsewhere.

On Linux, it also should work by default, but you have the additional option of explicitly adding routes that look within the default network settings for the SBC. From a terminal (as root), type:
* {{Code|route add -net 169.254.0.0 netmask 255.255.0.0 dev eth0 metric 99}}
* {{Code|route add default dev eth0 metric 99}}
You can also compile and use the {{Code|phidgetsbclist.c}} example (use the provided Makefile, don't use gcc) in the [{{SERVER}}/downloads/libraries/libphidget.tar.gz Phidget Linux Libraries] package, under the {{Code|examples}} folder. This will allow you to see if the SBC is detected on the network at all. Note that to use this option you must have the Phidget Libraries and the Phidget WebService installed on your Linux computer - in-depth instructions to do this are on the [[OS - Linux|main Linux page]].

===Recovery System===

You can either boot the SBC into recovery mode and attempt to recover files and settings, or you can completely wipe the SBC by performing a factory reset. If the LEDs do not turn on normally (red on constantly, green on at first start, then off, then on when fully booted) then you'll want to read the [[#Hardware Issues|hardware issues]] section.

====Partial Recovery====

The recovery system can be entered in two ways:
# From the {{Code|System → Backup & Restore}} web interface page.
# By holding down the reset button for 20+ seconds - until the green light has switched from flashing slowly to flashing quickly.

The recovery system runs an [[#SSH|SSH]] server where the username and password both are {{Code|root}}.

If the main filesystem has been damaged/misconfigured in such a way that it won’t boot, you may be able to fix the issue or recover important files before running a full factory reset. From an SSH connection to the recovery system, you can mount the main root filesystem with the following commands (assuming it’s not damaged):

<div class="source">
<syntaxhighlight lang=bash>
ubiattach /dev/ubi_ctrl -m 6
mount -t ubifs /dev/ubi0_0 /mnt
</syntaxhighlight>
</div>

====Factory Reset====

This restores the kernel and root filesystem from backup, overwriting any changes that may have been made and ''completely wiping the system'' to the state that it got shipped in. (You can save your files and installed program list first, as [[#Backing Up Your Data|described here]].) This can be enacted one of two ways.
# Use the reset button:
##Enter the recovery mode by holding down the reset button for 20+ seconds as above (until fast flashing)
##Wait for a full boot (i.e. you can see it on the Phidget control panel, or can SSH with username and password as {{Code|root}})
##Hold down the reset button again, but this time for only 10 seconds (until slow flashing)
##Wait for the SBC to fully reset and reboot (at least three minutes) - the LED will turn off and on again when this occurs
##*Note that after a factory reboot the SSH server will be disabled
##*Also note that after a factory reboot the SBC creates new SSH keys, and reverts to the {{Code|phidgetsbc.local}} address
# Via the web interface, under {{Code|System → Backup & Restore → Go button}}, where you can follow the instructions

====Hardware Issues====

The LEDs are an indicator of the hardware working properly. The normal boot process is:
* Red LED: Turns on from moment of power being applied.
* Green LED: Turns on momentarily when power applied, then turns off momentarily, then turns on and stays on when booted.

If the green status LED never turns on (or fails to turn on the second time), the boot process is failing somewhere. This could be due to:
* A damaged OS - Try performing a [[#Factory Reset|Factory Reset]]
* If this fails, it is likely hardware damage (very difficult to diagnose, please [[Contact Us|contact us]])

If neither LED turns on, hardware damage is even more likely. Unless the path to the red LED is the one thing that has been damaged, the device is likely not receiving and using power.
* Try performing a [[#Factory Reset|Factory Reset]], and if that does not work please [[Contact Us|contact us]]

=====USB Issues=====

On the Phidget SBC2, there is a hardware issue that is unrelated to the LEDs. It is a USB problem, and manifests in many ways:
* Strange behaviour when some devices but not others are plugged in to the SBC
* Strange behaviour with combinations of devices
* Failure (or intermittent failure) to see Phidgets on the USB hub, or USB keys on the hub

This problem is fixable, either on your own or by sending your SBC back to Phidgets. For an in-depth solution, see the [[SBC2_USB_Hub_Fix | SBC2 Hub Fix Page]].

===Updating Your SBC===

If you've owned your SBC for a while and want to update your packages, you can run:

<div class="source">
<syntaxhighlight lang=bash>
apt-get update
apt-get upgrade
</syntaxhighlight>
</div>

...to ''update'' your software source list and then ''upgrade'' to the latest version of all installed software. If you are used to Mac OS or Windows, note that this does not just update the non-kernel parts of the operating system, it updates every additional piece of software you have installed.

To update the SBC software itself (e.g. the kernel), it is easiest to use the web interface, under {{Code|System → Backup & Restore → Go button}}, to enter a page that will give you the option to update. You will need to have an update file on a USB key inserted into the SBC, of type:
* UBI Image (system_ubi.img), or
* Kernel image (uImage), or
* Phidget Upgrade package containing both UBI and Kernel images (phidgetsbc*.bin)

These are either obtained from the Phidgets website, or are a custom kernel / filesystem that you can create yourself, if you are experienced.

The reason why this information is in troubleshooting is that you should certainly [[#Backing Up Your Data|back up your system]] before trying this. And, it is quite rare to need to upgrade the kernel or filesystem on the SBC, so something serious should be going on before you attempt it. Try using the [[#Recovery System|recovery system]] first.

==Programming Languages==

Now that you have the basic libraries installed, you can pick your language and begin programming!

If you are not using the [[#WebService | webservice]] to control a Phidget over a network, your next step will be to delve into the use of your specific language. Each page has its own set of specific libraries, code examples, and setup instructions.

On SBC Linux, we recommend the following languages:

*[[Language - C/C++|C/C++]]
*[[Language - Java | Java]]
*[[Language - Python | Python]]

These languages may also run on the SBC, but we do not yet directly offer SBC support for them:
* [[Language - Ruby|Ruby]]
* [[Language - C Sharp|C#]] (using Mono)

You can probably figure out how to install and use them by a combination of the language pages linked above, and the section on [[#Installing Other Languages|installing other languages on the SBC]].

==WebService==

The SBC comes with the [[Phidget WebService]] installed, and the SBC automatically starts the WebService at boot.

To practice using the WebService, and to learn more about it, we have hands-on examples on the [[OS - Linux|general Linux page]], starting in the [[OS - Linux#Using the WebService|using the WebService section]].

==Advanced Uses==

===Using a Different Wireless Adapter===

The support for the wireless adaptor that Phidgets sells is written into the SBC kernel. Hence, we do not support using other adaptors.

However, Linux is very flexible, and it is possible (though not easy) to write a custom kernel for the SBC and add support for a new wireless adaptor. We can't help you with this, but we do provide some basic guidelines for [[#Custom Kernel and Filesystem|building your own kernel]].

===Using a Different Webcam===

In addition to the webcam that Phidgets sells, you have the option to use many different webcams with the SBC. There is a [http://www.ideasonboard.org/uvc/#devices long list] of compatible webcams.

The common thread for these webcams is that they use UVC - the USB Video Class - drivers for Linux. You can then use [[#mount|mount]] to find out what video device your webcam is mounted under.

===Taking Pictures With the Webcam===

Probably the most straightforward way to use a webcam for pictures rather than video is to use the {{Code|opencv}} library. You can get it by:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install libcv2.1
</syntaxhighlight>
</div>

If there is no {{Code|libcv2.1}} package, you can perform {{Code|apt-cache search libcv}} to find the current version.

The opencv libraries can also be used within Python, by installing the link between them:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install python-opencv
</syntaxhighlight>
</div>

Then taking pictures from within code becomes quite simple. For example, in Python, taking and saving an image is four lines:

<div class="source">
<syntaxhighlight lang=bash>
#! /usr/bin/python

import cv

# The webcam is located at /dev/video0
# OpenCV only needs the number after video
webcam = cv.CaptureFromCAM(0)

frame = cv.QueryFrame(webcam)

cv.SaveImage("image.jpg", frame)
</syntaxhighlight>
</div>

For the complete OpenCV documentation, see [http://opencv.willowgarage.com/documentation/index.html The OpenCV Reference], and specifically the section on [http://opencv.willowgarage.com/documentation/reading_and_writing_images_and_video.html Reading and Writing Images].

'''Note:''' The SBC is probably not as powerful for image processing and transport when compared to your desktop computer. Try running your image processing code on the SBC from an early point in development. During those test runs, you can visit the first System page of the [[#SBC Web Interface|SBC Web Interface]] to check the processor and memory use. For more information on processor power, check the specification for your SBC (on the product page on [{{SERVER}} our main website]) as well as our discussion of [[#Pushing Processor Limits|pushing processor limits]] below.

===Checking System Logs===

The SBC maintains two logs: a kernel log and a system log.

The kernel log is for low-level occurrences, such as devices attaching and leaving the USB hub, recording what drivers are being used, and so on.

The system log (syslog) is for normal chatter from the operating system. Any program with the right permissions can use it (though you need to know the method to write to it, information all around the Internet can help) and it contains everything from the Ethernet going up and down, to webserver requests, and so on. If you don't run many programs or services on the SBC, the syslog will essentially be a mirror of the kernel log, because the kernel is the only thing talking.

You can check these logs by using the web interface in the {{Code|System → Logs}} tab.

Or you can perform more powerful filtering and displaying via an SSH terminal. For example, {{Code|dmesg}} is the command to display the kernel log, and {{Code|tail}} prints the last ten lines of input. So, if you are trying to see if you can get a device to be detected on USB, you can run <code>dmesg | tail</code> to print the latest ten lines of kernel log data.

The actual locations of the log files (for filtering and reading) are:
* {{Code|/var/log/syslog}}
* {{Code|/var/log/dmesg}}
But don't edit them directly! Always follow the advice and procedures around the Internet on how to properly log items to syslog.

===X Forwarding===

Although most tasks can be done using the [[#SBC Web Interface|SBC Web Interface]] or [[#SSH|SSH]], you can also set up X11 forwarding on the SBC. X11 is the window manager base, which provides a graphical windowing system on the SBC. Although you probably won't connect directly to the X11 manager (i.e. by plugging a screen directly into the SBC), X11 also gives a user the ability to forward graphical windows over SSH. You will need the following packages installed:
* {{Code|x11-common}}
* {{Code|xbase-clients}}
After installing, make sure that the line in {{Code|/etc/ssh/sshd_config}} has a line that says:
:{{Code|X11Forwarding yes}}
Then log out and log back into the SBC. This second time you log in, use the {{Code|-X}} switch to turn on X forwarding for that connection:
:{{Code|ssh -X root@phidgetsbc.local}}
Then you should be able to run programs that launch a window, and it will launch remotely and appear on the computer you have the SSH connection from.

===Pushing Processor Limits===

The SBC, though more powerful than many embedded computers out there, is probably about as powerful as your smartphone. If you hook up 1 ms Phidget sampling devices to all six of its USB ports, events and packets will probably get lost. The exact data rates you can accomplish depend on:
* What else is running on the SBC
* How efficient your code is for external operations (like File I/O)
* Other minor details (e.g. the temperature of the SBC, etc)

If you want to achieve data rates as fast as possible, try these tips:
* Program in C, not in an interpreted language (Python, Java, .NET)
* Perform file I/O as little as possible. Locally cache data, manage your writing to a file in a separate thread, and use low-level write calls.
* Change the [[#Custom Kernel and Filesystem|filesystem]] to a faster, non-compressed file system.
** Alternatively, use a high-data-rate USB key.
* Keep other running processes to a minimum.
** If you are running code locally right on the SBC, turn off the Phidget WebService.

===Custom Kernel and Filesystem===

You can compile your own kernel and flash it to the board. It is left up to the user to configure an appropriate cross-compiler for kernel development. You may also be able to compile a new kernel on-board. We have a kernel development kit, complete with patch file and README:
* [{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC Kernel Development Package]

Compiling a new, custom kernel is somewhat complex. If the SBC is your first experience with Linux, writing a custom kernel will be difficult. However, it will probably also be very rewarding because you can put whatever you like into it. We might be able to offer additional suggestions, but ultimately you're on your own here.

You may be able to write a custom kernel right on the SBC, but the easiest way is to develop the kernel on an external computer. And the easiest way to develop on an external computer is for that computer to also be Linux, even just in a Virtual Machine. The time spent loading a copy of Linux into a virtual machine (such as VirtualBox, which is free) onto your computer will probably be less time than setting up a standard compiler on Windows to cross-compile.

On your external Linux system, you will need:
* A cross-compiling toolchain for the ARM processor, which we briefly describe on the [[OS - Linux#Cross-Compiling with a Custom Toolchain | main Linux page]], and
* The [{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC Kernel Development Package] from the Phidgets website.
The kernel development kit has a brief README file which describes how to obtain the proper kernel and patch, configure, customize, and build it.

We have an application guide in progress, which walks through building a custom kernel to add Bluetooth support to the SBC. Please contact us if you would like more information. Even if you are trying to add support for hardware other than a bluetooth modem, or wondering if support even exists in the kernel for your modem (3G, alternate wireless, etc) you will probably find the application guide helpful. Follow it up to the point where you run the program {{Code|menuconfig}} (you don't need an SBC to do this), which will give you a menu of all drivers you can enable in the SBC kernel.

After making your new kernel, you should have a uImage and modules target for your Makefile. At this point you can transfer your kernel files onto the SBC, make their targets, and transfer them into the nand memory. This involves erasing the old kernel, flashing the new kernel, installing the new kernel modules, and rebooting. From the SBC, in the kernel directory:

<div class="source">
<syntaxhighlight lang=bash>
make uImage; make modules
flash-eraseall /dev/mtd3
nandwrite -p /dev/mtd3 arch/arm/boot/uImage
make modules-install
reboot
</syntaxhighlight>
</div>

Custom kernels can also be flashed from the [[#Recovery System | Recovery System]].

If you need to create a root filesystem image, the filesystem type is UBIFS, and the commands to create it are:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -m 2KiB -e 126KiB -c 4050 -r $ROOTFS/ system_ubifs.img
ubinize -o system_ubi.img -m 2KiB -p 128KiB -s 512 ubinize.cfg
</syntaxhighlight>
</div>

Where {{Code|ubinize.cfg}} contains:

<div class="source">
<syntaxhighlight lang=bash>
# Section header
[rootfs]
# Volume mode (other option is static)
mode=ubi
# Source image
image=system_ubifs.img
# Volume ID in UBI image
vol_id=0
# Volume size
vol_size=64128KiB
# Allow for dynamic resize
vol_type=dynamic
# Volume name
vol_name=rootfs
# Autoresize volume at first mount
vol_flags=autoresize
</syntaxhighlight>
</div>

You then flash ‘system_ubi.img’ (not ‘system_ubifs.img’) from the recovery system.

Again, like the custom kernel creation, the need to create a custom root filesystem is essentially non-existent except for those advanced users who already know they need it... and furthermore, you are almost entirely on your own.

==Software Details==

For even more advanced uses of the SBC, it may help to know the gritty details of the SBC software system.

;Operating System
:Debian/GNU Linux
:Kernel 2.6.X or higher (generally kept up to date with latest releases, use {{Code|uname -r}} to check the kernel version)

;Main Filesystem (rootfs)
:UBIFS (a raw flash type of file system)
:Mounted in a 460 MB Nand partition (in Read/Write mode)

;Kernel
:uImage format
:Has its own 3MiB partition on bare Nand

;Web Interface Scripts and Configuration Data
:Located in {{Code|/etc/webif}}
:Modifying these scripts can be done; however, it is very easy to enter invalid data that could cause the system to behave unexpectedly or not boot.

;User Applications uploaded through Web Interface
:Located in {{Code|/usr/userapps}}

;Webcam Device Location
:{{Code|/dev/video0}}
:Numbers increase with more webcams

;Date and Time
:Set using ntp (network time protocol) at boot
:The ntp daemon continues to run in the background and will periodically update the clock
:The network keeps the SBC very close to real time
:Also there is a real-time clock with battery backup which will preserve date/time across reboots, power removal
:The real-time clock is synced to system time during reboot/shutdown
:If power is unplugged suddenly, and the network not restored, the real-time clock may not have the correct time

;Wireless Networking System
:Wireless adapter support for the wireless adapter that Phidgets sells is written into the kernel
:It supports WEP and WPA
:It is best configured through the configuration interface.

;Nand Layout
:The board contains 512MiB on Nand. This nand is split into 7 partitions as follows:
:0: u-boot size: 256K Read Only
:1: u-boot_env size: 128K Read Only
:2: recovery_kernel size: 2M Read Only
:3: kernel size: 3M Writable
:4: flashfs size: ~3.625M Read Only
:5: recovery_fs size: ~ 43M Read Only
:6: rootfs size: ~ 460M Writable
: The final size of flashfs/recovery_fs/rootfs depends on the image size at production, and on the number/location of bad blocks in the NAND.
: '''Note''': U-Boot and recovery kernel and filesystem cannot be written from Linux - this is a safety measure.

;Boot Loader
:U-Boot is used for setting up the processor and booting Linux, and is only accessible via a serial connection.
:Normal users will not need to use or modify it.
:Be very careful when modifying the u-boot partition. If it is damaged or overwritten, it is difficult to fix.
:When using U-Boot, a prompt will appear via serial shortly after power on.
:The environment variables will help you determine how to boot Linux on the SBC
:You can also refer to the [http://www.denx.de/wiki/DULG/Manual U-Boot documentation]

;Boot Process
:From power on...
:1. Processor loads first 4 bytes from NAND into Steppingstone and runs it.
:2. Steppingstone sets up RAM, copies u-boot from NAND into RAM and runs U-Boot.
:3. U-Boot initializes the processor, sets GPIO state, etc., copies the linux kernel into RAM, sets up the kernel command line arguments, checks that the kernel image is valid, and boots it.
:4. Linux boots, bringing up USB, Networking, NAND, etc. and then mounts the rootfs NAND partition on /.
:5. init gets run as the parents of all processes, as uses the /etc/inittab script to bring up the system. This includes mounting other filesystems, settings the hostname, and running the scripts in /etc/init.d, among other things.
:6. inittab then turns the green LED on.
:7. inittab then sets up a getty on the first serial port, ready for interfacing using the debug board.

==Common Problems and Solutions==

{{ProblemSolution|USB Memory Key mounting|Sometimes USB Memory Keys mount at more than one location}}

When you insert a memory key, the SBC will load it as a device (e.g. {{Code|/dev/sda1}}) and it will also ''mount'' the key for reading and writing within the {{Code|/media/}} directory. The {{Code|/media/}} directory version will be called something like {{Code|usb0}}.
At times, an inserted memory key will get mounted in more than one location. You can observe if this occurs by checking the currently mounted devices with the command {{Code|mount}}:

<div class="source">
<syntaxhighlight lang="text">
root@phidgetsbc:~# mount
tmpfs on /lib/init/rw type tmpfs (rw,nosuid,mode=0755)
proc on /proc type proc (rw,noexec,nosuid,nodev)
sysfs on /sys type sysfs (rw,noexec,nosuid,nodev)
udev on /dev type tmpfs (rw,mode=0755)
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev)
devpts on /dev/pts type devpts (rw,noexec,nosuid,gid=5,mode=620)
rootfs on / type rootfs (rw)
procbususb on /proc/bus/usb type usbfs (rw)
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
/dev/sda1 on /media/usb1 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

You will note that the same device ({{Code|/dev/sda1}}) is now mounted at ''both'' {{Code|/media/usb0}} and {{Code|/media/usb1}}. To fix this problem as it occurs, you can use {{Code|umount}} (notice there is no letter 'n') to unmount the second instance:

<div class="source">
<syntaxhighlight lang="text">
root@phidgetsbc:~# umount /media/usb1
</syntaxhighlight>
</div>

In practice, this should not be a problem, because writing to or reading from either {{Code|usb0}} or {{Code|usb1}} will have the same effect on the memory key. However, if you hard-code a media location into your program (i.e. expecting {{Code|/media/usb0}} to be the first USB key you insert and {{Code|/media/usb1}} to be the second key) your program will sometimes work and sometimes fail.

To get around this within code, find the mount point for each device as it appears. The devices, such as {{Code|/dev/sda1}} will always refer to the actual memory key. But, they cannot be written to directly without being mounted, so you will have to parse the mount table (what is returned from {{Code|mount}}) within your code to find the device and its corresponding mount point.

This is a problem with the standard embedded Debian automount program, and we have no known fix.

{{ProblemSolution|Perl Locale Errors on SSH|No Locales Installed}}

By default, no locales are installed on the SBC. If you use [[#apt|apt]] a lot to install and manage your software on the SBC, you will get messages like this:

<div class="source">
<syntaxhighlight lang="text">
perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
LANGUAGE = (unset),
LC_ALL = (unset),
LANG = "en_CA.UTF-8"
are supported and installed on your system.
perl: warning: Falling back to the standard locale ("C").
locale: Cannot set LC_CTYPE to default locale: No such file or directory
locale: Cannot set LC_MESSAGES to default locale: No such file or directory
locale: Cannot set LC_ALL to default locale: No such file or directory
</syntaxhighlight>
</div>

To squelch these messages, you should install and reconfigure your locale like this:

<div class="source">
<syntaxhighlight lang="bash">
apt-get install locales
dpkg-reconfigure locales
</syntaxhighlight>
</div>

The last command will show you a long list from which you should pick your location, by language. For example, en_CA is english_Canada. Here in Calgary, we use en_CA.UTF-8 and so for the first question we would input locale "114" and for the second (system) question we would input {{Code|en_CA}} for the locale.

This might give you a locale undefined error, in which case you can generate the locale (for us, again, it is en_CA):

<div class="source">
<syntaxhighlight lang="bash">
locale-gen en_CA
</syntaxhighlight>
</div>

Electricity Primer

2012-06-29T21:42:20Z

Cora:

[[Category: Primer]]

==Introduction==

Design of reliable systems is really, really hard. The main challenge is the design of reliable building blocks - i.e. circuit and board layouts - from which to create your system. Phidgets does the majority of this work for you. And, once you have reliable building blocks, designing a reliable system from them is much easier.

However, you can still make an unreliable system out of Phidgets. In fact, if you are building a more complex system than the common examples we show through our documentation, and you have limited experience in complex electrical design, you will probably - and unintentionally - introduce design flaws that will make your system unreliable.

There are two reasons why you should read this primer:
# You want to build a complex system, more complex than we illustrate in our documentation. To succeed, you need to understand concepts.
# You understand how to make your system work, and you want to ensure it is well designed for maximum reliability and/or precision.

==The Basics==

To understand our discussion of potential problems and their solutions below, you'll need to be familiar with the basics. For this page, 'being familiar' means more than simply having heard of voltage, amperage, and power. You will need to have a working, conceptual model in your head, so that you can apply that model to your own system and examine it for problems. This section is all about giving the tools to build that mental model.

First, some terminology. We introduce it by analogy. If a circuit is a water system,
* The '''voltage''' is the ''pressure'' in the system
* The '''power supply''' is the ''pump'' creating the pressure
* The '''amperage''', also known as current, is the amount of ''flow''
* The '''load''' is the ''faucet'' - adjusting your load will adjust the flow
* The '''resistance''' is an attribute of the load - how tight or loose the faucet is
* The '''ground''' is the return path from load to pump.

The basic concepts for all of these terms are presented below.

===Load===

We start with the load, because the load is the purpose of your entire system.

In simple, USB-only Phidget systems, the load is the Phidget itself. The USB port is ready to provide power, but it does not (and cannot) until a load is applied (i.e. the Phidget is attached) and the circuit is completed.

Without a load that connects in a loop, it is like attaching a closed pipe to your pump. Initially, water will fill the pipe, and pressurize it, but once the pipe fills the system as a whole will do nothing more. To allow the pump to drive the load, and the flow to supply the load, we need to have a completed circuit, like this:

[[Image:elec_flow.png|150px]]

The load and the pump must '''match'''. If the load lets too much flow through, the pump will work too hard and burn itself out. This is what happens when you short circuit a power supply. The load is then simply a wire, which basically opens the flood gates and drains your power supply pump. The load must not let too much flow through, which it does by '''resistance'''. Likewise, the pump cannot push too hard on the load, or the load will break. This is discussed in-depth as part of [[#Voltage and Amperage|Voltage and Amperage]] below.

===Voltage and Amperage===

Within the flow concept [[#Load|above]], voltage is pressure. Specifically, it is the ''difference'' in pressure between the flow and the return. Voltage is measured in volts, and is denoted by '''V'''.

Amperage - also known as current - is the flow, or the amount of water that moves. At the pump, the amount of current out and the amount of current in are equal. The pressure might vary widely (highly pressurized pipes out, low pressure pipes back) but the ''amount'' of current is always the same. Amperage is measured in Amps, and is denoted by '''A'''.

To match a pump to a load, the voltage and amperage of the power (supply) and load (sink) must line up. We discuss picking a power supply - whether [[#Wall Power|wall mains]], or [[#Battery Power|batteries]] - in the [[#Power Needs|Power Needs section]] farther along in the document, but we need a few more concepts before we get there.

Power supplies - whether wall power or batteries - are usually rated based on voltage and amperage. Voltage is the specification to be the most careful with for circuits. Too much voltage is the same as overpressurizing your pipes - they will burst. In the case of electronics, you device will break.

This can be counterintuitive - in reference to safety (for humans) around electronics, you may have heard "It is not the voltage that will kill you, it is the amperage". Because of this, it may be tempting to think that too high of an amperage will harm your device, but this is not true. Our hearts are very susceptible to amperage but not voltage, hence amperage is considered dangerous for us whereas voltage is not. But a circuit is not like a human body - in a circuit trying to handle a power supply it is the voltage that matters most.

====Set Voltage (No Control)====

Most loads do no power regulation of their own. They simply take the voltage given to them and do useful things with it. You can tell that a pre-designed load (like a Phidget) falls into this category because it gives its voltage need ''as an exact value''. For example, most Phdigets use exactly 5 V of USB power. These loads will also tell you their amperage, which is a flow need that must be met or exceeded. A load will only use as much amperage as it needs.

====Controlled Power====

Some loads change the voltage or current they receive. This can be with the intent to either (a) keep a constant amount of power flowing from a draining power source like batteries, or (b) to modify a common power source (i.e. 12 V at 1 A) into an uncommon power source (i.e. 1 V at 12 A). This process is called '''regulation'''.

You can tell that a pre-designed load (like a Phidget) falls into this "power-regulated device" category because it gives its voltage need ''as a range''. For example, the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer (SBC)] can take 6 V to 15 V.

To understand how this works, take the example of a flywheel. Flywheels are designed to be heavy and to take work in order to get them spinning at speed. But once you have them spinning, you can extract that work later at a more consistent rate:

[[Image:elec_flywheel.png]]

Flywheels can either make amperage or voltage be the more consistent blue line over time. The most common one in Phidgets is for stable amperage. Regulated amperage is also how LED lights can stay consistently bright for any length of time when using batteries. Stable voltage design is usually applied when the voltage is too low to begin with (such as any device that runs on a single AA battery), and the flywheel must amplify and stabilize it over time.

For those readers trying to envision how this works electrically, in practice the flywheel is an inductor (or, a transformer utilizing its inductor properties). For both voltage and amperage regulation, one way relief valves (diodes) must be added. And, in amperage regulation a reservoir (capacitor) must be added to offset the current drop by pulling ''more'' amperage as a battery drains. Then, a controller is needed to measure and then correspondingly enable and disable the flywheel system as the voltage or amperage drops from the supply.

But with those details in place, the inductor (and capacitor, in the case of amperage regulation) can effectively take the variety of voltages from, say, a draining battery, and still allow the board to run. Some devices even do this naturally. For example, motors often can take a variety of voltages because their construction (i.e. wire wrapping) naturally creates inductance.

These regulated systems often list the power they need directly, using a type of power rating called '''watts'''. Watts are voltage and amperage together (i.e. power):

<math>
\text{Amperage} =\frac{\text{Watts}}{\text{Voltage}}
</math>

Watts can be a handy way to describe flow and pressure together for these regulated devices. Rather than separating voltage and amperage like the unregulated devices do (i.e. this load needs exactly 12 V, or this load will draw exactly 2 A), the unit of watts will allow different value combinations of volts and amps as long as the wattage remains the same. For example, a 12 watt device with a voltage range of 5 to 12 volts can run on 6 V at 2 A, or 12 V at 1 A. Either will work. Amperage for all values in the device's range of 5 to 12 V can be found with the equation above. Because of this, watts are often preferred when trying to match a power supply to a regulated load.

===Ground===

All circuits have a '''ground'''. This is simply the return pipe to the pump. In a circuit, it is denoted by an upside-down triangle:

[[Image:ground.png]]

When drawing a circuit diagram, the symbol is placed on the wires that return to the pump:

[[Image:elec_flow_ground.png|170px]]

This electric ground provides a voltage reference throughout the circuit. Ground is always '''0''' volts as far as the circuit is concerned. (Remember, voltage is the ''difference'' between the flow and return pipes at the pump.) Ground is important because it provides a reference from which all the parts of the circuit can speak the same "voltage language" to each other, which matters a lot when a certain voltage means "1" and a certain voltage means "0".

There is only one '''absolute''' ground, and that is the Earth, which is taken to be 0 volts as an absolute value. Circuits not well-grounded to the Earth (of which there are many - your cell phone, car, etc) operate at a '''relative''' voltage. The upside-down triangle above denotes a ''relative'' ground.

With relative voltage, only the difference between local ground and the local high voltage matters. For example, a cell phone might operate as a 3 volt device, which means relative to its ground it always operates between 0 and 3 volts. But if that cell phone were compared carefully to Earth ground, its absolute voltage could be, say, between 10 and 13 volts. Until comparison, the device doesn't "feel" charged. This is the same as how you don't "feel" charged after skidding your feet in socks across a carpeted floor. But, when you "compare" yourself to Earth ground by touching some well-grounded metal, you receive a static electricity shock.

The same thing can happen when you combine two different power supplies, as we discuss [[#Projects With Different Power Sources|below]].

===Power===

There can be different types of pumps, and at this point we should supplant our heart symbol with some actual power supply pump symbols. For example, this is the symbol for a direct current (DC) battery:

[[Image:elec_battery_basic.png|200px]]

The + end is on the out flow, and the - end is on the return (ground). Batteries are usually listed with their voltages. This is because the resistance of the load will determine how much amperage is drawn, but too much voltage and you will harm your load.

This is the symbol for alternating current (AC) that you would get directly from the wall:

[[Image:elec_wall_basic.png|200px]]

Again, this is listed using voltage for the same reasons as DC. A relative ground symbol is still used on the return line here. AC devices can still operate on relative voltage if they do not use Earth ground (the third prong on a wall plug in North America). This is how some loads have AC cords with only two prongs - they operate on a relative voltage and relative ground. And relative AC voltage, having significantly more voltage (pressure) behind it, can really hit a device hard when two power supplies meet across it.

This connecting of multiple power supplies is quite a complex subject, and is described further in both [[#Power Needs|picking different power supplies]] and [[#One Powered Phidget|connecting different power supplies]] later on in this Primer.

===Emissions and Wires===

To talk about emissions, it is worth speaking more precisely about what a load is. The typical, simple Phidget setup is receiving 5 V direct current (DC) from the computer over the USB port. Let's model this as coming from a battery so that we can examine all parts of the system. From the point of view of the battery, the Phidget load is not just the green board with the circuitry on it. The load ''also'' includes the power cable (i.e. two wires in the USB cable), and anything else on the path out or back from the circuitry to the battery itself:

[[Image:elec_phidget_basic.png|200px]]

This is important because the wires play a role in the voltage that eventually makes it to the Phidget. This is true all the time, even when the Phidget is attached to a computer instead of a battery. All wires have some resistance, and so they are, in a way, in and of themselves circuits. Therefore, because of their resistance, the wires 'use' some of the 5 V heading out to the Phidget circuit board. This is discussed more below, but essentially longer cables have more resistance and at some point the voltage will drop so much over the length that the Phidget will not turn on.

To conceptually separate the wires from the Phidget in terms of the load, we can now start drawing the wires themselves in our circuit diagram, instead of the curved concept arrows indicating flow and return:

[[Image:elec_phidget_wires.png|200px]]

When talking about the 5V relative ground in this system, we are in fact talking about the ground ''right at the battery'' so we move the ground symbol to the battery itself.

Then, the resistance on these wires creates a possible problem - the emission of electromagnetic radiation as the wires naturally drop the voltage:

[[Image:elec_phidget_emissions.png|200px]]

These emissions are at a set frequency determined by the length of the wire:
* Long wires create low frequencies (harmful interference)
* Short wires create high frequencies (less harmful interference)

This can be minimized by having the flow and return wires be the same length and sit right next to each other. This way, the emissions somewhat cancel each other out from the flow and return going in opposite directions. This is partially how USB cables minimize emissions.

So, the way you design your connections (i.e. the resistance and placement of your wire) will have a direct affect on:
# The voltage that reaches the Phidget
# The emissions that your system produces

With all this talk of emissions, you might be tempted to try to shield parts or all of your system from emissions that either your system or external systems create.

Keep in mind that shielding is actually really hard to do correctly. Especially when grounding your shielding, with ad-hoc design you have a high chance of having an interfering signal (that has traveled out to the shield and traveled back via ground) creating a larger problem than not having a shield at all. Rather than shielding, it is easier to simply keep your cables short and with as low a resistance as possible throughout your system to minimize your emissions in the first place.

Identification of and solutions to these (and other more complex) problems are discussed in detail in the [[#Selecting Cables|section on choosing cables]] and the [[#Hooking Up The Pieces|section on connecting the pieces]] below.

===Multiple Loads===

The easiest way to hook up multiple Phidgets is in parallel, where the voltage stays the same but they share the amperage. Here the DC supply is two USB ports, each at 5 V and 0.5 A:

[[Image:elec_phidget_parallel.png|250px]]

However, the length of your wires comes into play again, because the voltage that actually reaches the Phidgets above is somewhat less than 5 V. So if your wires are long, or mismatched, the voltage may not match and will give you strange results. The voltage is both affected on the way out, and on the way back. Assuming the wires are the same length:

[[Image:elec_phidget_wire_drop.png|350px]]

In this way, you can create difficult-to-debug problems within a complex system, where one Phidget works but others mysteriously fail.

==Power Needs==

Now that you've understood the basics, it is time to actually talk about decisions and design. This section will help you choose a power supply for your Phidget. Let's say you want to run the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer] off of a battery. Or you want to run a motor controller with a power supply you bought from the hobby store. What do you need to buy? Will one you already have work? It is worth it to spend a moment with pencil and paper to work through this section and identify your power needs.

As described [[#Voltage and Amperage|earlier]], voltage is pressure. Too much pressure behind your faucet, and the water mains or faucet will break. Likewise, if you have too much voltage from a power supply, your circuit will break. You should choose a supply with voltage that ''matches the range the Phidget can accept''. The voltage cannot be over the maximum (otherwise, like pressure in a pipe, the pipe will burst), and the voltage cannot be under the minimum (otherwise, like pressure in a pipe, no flow will occur). Also, generally, a device (like a motor controller) will perform better at its maximum rated voltage if a range is available.

But the faucet doesn't care whether there is a big reservoir or small reservoir feeding the system, as long as the pressure is managed. Likewise, you can choose a power supply with more amperage than you need (a big reservoir to draw from) as long as the voltage matches. In the same way that a faucet restricts water by design, loads draw and allow only the amperage that they need. However, the amperage cannot be less than the Phidget needs. In that case, you will either overextend (and break) your power supply, or the circuit simply will not turn on at all.

The specification [[#Device List|for your specific device]] will list its power needs. For most devices, the external power supply needs will simply be listed in voltage and amperage. USB power is 5V at up to 500 mA (0.5 Amps). Most Phidgets will draw less than this - if you need precision, you can check the specification for your particular Phidget. And, if it is an Interface Kit, you can add the draw of each analog sensor and digital in/out from their specifications.

However, some Phidgets (e.g. motors, and the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer]) do not have a straight amperage and voltage specification. Instead, their power draw will be listed in watts, for which you [[#Voltage and Amperage|saw a relation earlier]] to convert to the values you need.

===Wall Power===

Wall power sources usually take the alternating current (AC) from the wall and convert it into a direct current (DC). These power supplies often take your familiar two-or-three prong wall connector and put power out via a barrel plug-type connector. AC power (typically 110 or 240 volts, depending where you live in the world) goes in the typical wall plug, and DC power (typically 5 to 24 volts) comes out the barrel plug. Most power supplies of this type list the conversion explicitly, such as: 110-240 Volts to 12 Volts at 2 Amps. You'll want to match your Phidget's needs against the 12 Volts at 2 Amps.

*The voltage must match exactly
**If the Phidget takes a range of voltages, the supply must fall within the range
*The amperage can be equal to or greater than the Phidget needs

A wall power supply is essentially an inexhaustible supply of current, so you don't need to worry about it running out like you would with batteries.

===Battery Power===

If you intend to use a battery bank (even of only one battery) to power your Phidget, you probably want to know what type of battery to purchase.

====Battery Chemistries====
The first thing that sets batteries apart is the type of materials used in their construction. The following table shows several of the more common battery chemistries as well as the voltage per cell they produce and the specific energy of the chemistry.

{| border = 1
| align="center" style="background:#f0f0f0;"|'''Chemistry'''
| align="center" style="background:#f0f0f0;"|'''Nominal Cell Voltage'''
| align="center" style="background:#f0f0f0;"|'''Specific Energy (MJ/kg)'''
| align="center" style="background:#f0f0f0;"|'''Description'''
|-
| align = "center" colspan = 4|Primary Batteries
|-
| Alkaline||1.5||0.4||These are the most common form of battery. Many commercially available AA and AAA batteries are alkaline.
|-
| Lithium (LiMnO2)||3||0.83-1.01||These are used in high drain devices or devices with a long shelf life as they have a very low self discharge rate.
|-
| Silver-oxide||1.55||0.47||Only used in small button cells as these are quite expensive.
|-
| align = "center" colspan = 4|Secondary Batteries
|-
| NiCd||1.2||0.14||Older technology, suffers from [[Electricity Primer#Memory Effect|memory effect]]. Capable of very high discharge rates with no ill effects. Moderate self discharge rate.
|-
| Lead-acid||2.1||0.14||Not particularly good with high discharge rate. Moderate rate of self discharge.
|-
| NiMH||1.2||0.36||Very heavy. Good performance in high drain devices. Very high energy density naturally, at the cost of a high self discharge rate. Newer versions are able to get rid of some of the self discharge though they suffer ~25% lower energy densities as a result.
|-
| Lithium Ion||3.6||0.46||Expensive to produce but very high energy density. Very low self discharge rate. Safety hazard as short circuiting can yield explosive or fiery results.
|}

====Choosing a Battery====
Batteries are chosen first by their voltage (V). Match the voltage exactly to the voltage the Phidget needs. Over or under this value, you could harm the board or have it simply fail to turn on.

Next, choose a battery that has adequate amperage to feed your device for the time you need. The lifespan of the battery will usually be listed in Amp-Hours (or Ah). For example, a double wide 12 V lantern battery will have usually around 7-8 amp hours. This means if you drew one amp from it for seven to eight hours, the battery would be totally drained. Or you could draw two amps from it and drain it in 3.5-4 hours. This does not mean however, that you can draw 36A for 15 minutes. It is important to understand that there is a limit at which more power simply cannot be drawn from the battery. Effectively, high drain devices will decrease the rated Ah. The amount differs from battery to battery so to be sure it is recommended to check the data sheets for the battery you are using. If the battery did not come with a data sheet they can usually be found on the manufacturers website. The data sheets should have a graph that shows the relationship between current draw (usually in mA) and capacity (Ah or mAh). Another useful thing that can be gathered from the datasheets is the batteries response to temperature. Batteries tend to not work as well in cold environments, most manufacturers will provide graphs of how the batteries lifespans will shorten at different temperatures. This is often very significant, causing the battery to last a fraction of its normal lifespan at temperatures below -10°C.

Finding the amperage or voltage sometimes needs to be done indirectly by using a specification of watts. The relationship between amperage, voltage, and watts is given above in the [[#Voltage and Amperage|voltage and amperage section]].

For an example, let us say you want to use battery power to run the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer]. The specifications say that it uses 1.2 watts as a base value. The specifications also say that it can take 12 V DC power. If we choose to use a 12 V battery, at 1.2 watts it will use 0.1 amps according to the equation [[#Voltage and Amperage|shown earlier]]. Going by amp-hours alone, if our battery is a double-wide lantern type 12 V battery, with 7 amp hours, with 0.1 amp draw it will last 70 hours, or almost three days.

<math>
\text{Maximum Running Days} =\frac{\text{Battery Amp Hours}}{\text{Device Amps} * \text{24}}
</math>

However, to estimate ''average'' running time (rather than maximum running time possible), amp-hours cannot be used so directly. Over time, batteries decrease in voltage as their power is used up. Practically speaking, this means one of two things for your load. For loads that do not regulate voltage or current, the amperage will also decrease over time. The classic example is an LED light source that grows dimmer and dimmer as the batteries are used up.

You should usually only count on about 60% of the stated amp hour rating to apply before expecting to run into problems from escalated drain due to battery voltage drop. This is especially true for deep cycle rechargeable batteries left in an installation, where draining more than 60% could also harm the battery.

Then, for lead-acid batteries, a typical battery is tested from full to complete drain over 20 hours by the manufacturer to obtain the advertised amp-hour rating. Draining a battery at a faster rate than this will result in even more reduction in capacity, by 10% or even more. This due to [http://en.wikipedia.org/wiki/Peukert%27s_law Peukert's Law].

There are plenty of [http://www.google.ca/search?&q=battery+calculator battery calculators] around the Internet which take most or all of these additional factors into account when recommending an amp-hour rating. For longer-term installations, the solar power online community has some excellent resources.

====Setting up Multiple Batteries====
You can hook up multiple batteries in series to get more voltage at the same amperage. The amperage is additive. For example, you can hook up two single-wide 6 V lantern batteries in series to produce 12 V. Or two 12 V batteries in series to produce 24 volts. This system would still only have the amp hours of ''one'' of the lantern batteries, because you will be essentially using them both at once:

[[Image:elec_battery_series.png|250px]]

The upside down triangle (ground) is explained above in a [[#Ground|section of its own]].

Or, you can hook up multiple batteries in parallel to get more amperage at the same voltage. For example, you could hook up two 12 V deep cycle batteries in parallel to provide more amperage at 12 V, which is like having a deeper reservoir of power for your device to use:

[[Image:elec_battery_parallel.png|250px]]

====Heat====
*all batteries have some sort of internal resistance
*can be found on the battery's data sheet
*the more power you pull from the battery the more heat is going to build up as a consequence of the internal resistance.
*larger internal resistances will cause heat to build up faster.
*when charging a battery you are not just limited to the power in the battery. nothing stops you from dumping energy into the battery past the point where it is fully charged
**this is why charging batteries is a bit of a tricky business.
**many batteries come with custom chargers that have control systems to prevent this type of overcharging.

====Weight====
Finally, weight matters - a car battery is much heavier than a lantern battery. Batteries vary widely by weight per amperage. Lithium batteries are usually very light for their power, followed by alkaline, followed by lead acid. This may not seem important at first, but if you are building a mobile robot it is worth calculating in the work of carting around a battery. You may find that, for the length of time you want it to run, your battery requires some system redesign.

==Selecting Cables==

===USB Cables===

In general, use the shortest cables possible. There are many reasons for this [[#Emissions and Wires|described above]], but as a summary:

; Long cables reduce the voltage that reaches the Phidget.
: This happens in both directions. So, for every unit cable length added, the voltage decreases by twice the electrical resistance of that length of cable. With especially long cables the Phidget may drop below its 4.6 volt threshold and simply never turn on.

; Long cables increase the width of your circuit.
:All circuits act as emitting antennas for the resonance frequency of the circuit structure. The longer the wires in the circuit, the lower the frequency, and the higher chance that it will be emissions that will interfere with your data and system.

; Longer cables have more length exposed to external interfering emissions.

Also, use thick cables that are built to specification. Some USB cables with thinner wiring have higher electrical resistance. This can be equal to what a much longer wire would have, and thus create a similar voltage drop where the Phidget will not turn on.

====Options for longer cables====
The maximum length for a USB cable is 5m. This is laid out in the USB specifications. Often times however a system requires more reach. In this case there are a few options available to you. You can use what is known as an active extension cable or USB extender. These cables act like extension cables and add power to the line so that the signal can travel further. A second option is to use a Cat5 extender. These extenders are 2 USB dongles that connect on either end of your system. You join them up with Cat5 cable. This allows you to run over much longer distances than USB traditionally allows.

===Power Cables===

There are "DC Wire Table" references on the Internet which describe how to pick a wire appropriate for your voltage and amperage. When selecting AC wires, you will probably be using pre-made extension cords. Cords add interference resonance length to your circuit, just like USB cables do as [[#USB Cables|described above]]. A long extension cord can create huge electromagnetic interference for your circuit and other systems in the area when first plugged in.

Also as with the USB cables above, cut the cables to the shortest length possible. This is again both for voltage drop reasons and frequency emission reasons.

===Hubs===

Avoid hubs where possible. Unpowered hubs are good for reading data from memory keys, but not for powering many external devices. If you must use a hub, buy a powered one.

===Sensor and Motor Wiring===
All Phidgets sensor class devices (products whose part numbers start with 11 such as the 1129) use a 3 channel ribbon cable for power and data transmission. Similarly, all our motors and load cells use multichannel wire interfaces. As mentioned previously, USB spec limits cables to 5m, this is not the case for these wires. The biggest concerns are electromagnetic interference (EMI) and voltage drop. In general you should be able to run these wires over significant distances (30m or more) with the load cells in particular having very long range. If EMI starts causing issues you can always use ferrite beads on the cable near the sensor or motor and the controller to reduce noise.

===Cable Gauges for Terminal Blocks===

Many Phidgets products feature green terminal blocks that use screws to hold wires in place, making it easy to take apart and rebuild connections in your project. The size of the terminal block determines the gauge of wire you should use.

{|border=1
|+'''Terminal Block Size and Wire Gauge'''
! Terminal Block Width (mm/port)
! Recommended Wire Gauge (AWG)
|-
| 3.81
| 14 to 26
|-
| 5.0
| 12 to 26
|-
| 9.5
| 10 to 26
|-
|}

The gauge of cables and wires is measured in AWG, which is the American Wire Gauge standard. The following table lists the properties of wire gauges commonly used with Phidgets:

{|border=1
|+'''American Wire Gauge Sizes'''
! AWG Size
! Diameter (mm)
! Area (mm²)
|-
| 10
| 2.588
| 5.26
|-
| 11
| 2.305
| 4.17
|-
| 12
| 2.053
| 3.31
|-
| 13
| 1.828
| 2.62
|-
| 14
| 1.628
| 2.08
|-
| 15
| 1.450
| 1.65
|-
| 16
| 1.291
| 1.31
|-
| 17
| 1.150
| 1.04
|-
| 18
| 1.024
| 0.823
|-
| 19
| 0.912
| 0.653
|-
| 20
| 0.812
| 0.518
|-
| 21
| 0.723
| 0.410
|-
| 22
| 0.644
| 0.326
|-
| 23
| 0.573
| 0.258
|-
| 24
| 0.511
| 0.205
|-
| 25
| 0.455
| 0.162
|-
| 26
| 0.405
| 0.129
|-
|}

==Hooking Up The Pieces==

Here, things can be tricky. You might think: just plug everything in and go! But often it is not that simple. Many Phidgets require special care when hooking up. We encourage a process where you apply the concepts in this Primer, through analysis, to your system. So, we don't explicitly list the boards most commonly affected until the [[#Affected Products|end of this Primer]].

The ''categories'' of the boards which require special attention within a complex system are:

# Phidgets with more than one power source, and
# Phidgets needing precise measuring or control of an external power source

If you are already thinking about your boards in your head and trying to figure out whether they fit into one category or another, you're on the right track! The list of [[#Affected Products|commonly affected boards]] are only the common ones... with a sufficiently complex system, you could conceivably create problems with ''any'' boards.

Both types of projects require a full understanding of [[#The Basics|electrical basics]]. Using those concepts, below we first describe problems that arise when hooking up different power sources, and extend that into using the solution to give more precise measurement and control.

===Shared Grounds===

Shared grounds can occur in Phidgets that handle two different power sources. Recognizing the sharing of a ground is not always easy. We show what it is, how it can be possible, and why it creates problems by starting with the most basic Phidget system. The simplest setup for a Phidget is to use the [[#Ground|ground]] of the computer it gets data and power from over a USB port:

[[Image:ground_simple_case.png]]

In this case, there is only one relative ground, and it is the PC ground, which is ground #1 in the image. The PC ground determines what is considered 0 volts for all signals on the Phidget. When you add different power sources or sinks in the system, you are pulling the system relative to the PC ground.

=====One Powered Phidget=====

The next most complicated system is one Phidget that handles two power sources. Let us say you have a motor controller, which takes power from USB, and which also takes power from a second power source. Although the second power source is usually just a wall plug, the simpler case for thinking about ground is actually a battery. A battery creates a second ''relative'' ground. Through the Phidget, relative ground #1 (from the PC) and #2 (from the battery) actually become the same ground:

[[Image:ground_wall_power.png]]

This is the first reason why systems with powered Phidgets have to carefully manage ground. If ground #1 and ground #2 are different with respect to each other (see the static shock analogy in the [[#Ground|ground section]] above), then whatever circuitry along the red dashed arrow must deal with the initial static shock. In this case it would be the circuitry of the Phidget. In the case of a battery, after the initial equalizing shock the battery will be whatever relative voltage the PC ground needs it to be. Hence a battery relative ground can 'float'.

If ground #2 comes from the wall, on the other hand, the ground does not 'float' and instead is always absolute 0 volts Earth ground. With the PC giving the power, this is not a problem in practice because the PC can also float (as with a laptop), or it uses Earth ground. But if you were using a different and more powerful USB power supply instead of a PC, and then connected it to the absolute Earth ground through the Phidget, the Phidget would bear the brunt of any ground equalization that would occur. If neither the new ground nor the old ground float, and the power supplies were powerful enough, this would eventually destroy the Phidget. In this case, you would want to use isolation, as described in [[#How To Fix This|How To Fix This]] below.

=====Multiple Powered Phidgets=====

A worse case comes in when you are using two powered Phidgets and one external power source. Again, say you are using a battery as the external power source. It would be tempting to simply wire both grounds from the Phidgets to the ground on the battery:

[[Image:ground_two_phidget.png]]

Although this looks benign, you have actually created a new circuit. The circuit is a second path, via ground, for the current to return to the voltage source. This is also known as a '''ground loop'''. The path we intuitively think of the current returning by is '''<span style="color:blue;">path A</span>''', but the sharing of grounds has created a new path through the motherboard, '''<span style="color:red;">path B</span>''':

[[Image:ground_two_paths.png]]

All current gets 'pumped' in a loop by voltage, and so it will use all return paths available to it, assuming all paths are equally easy (electrically) to use. This extends the pipe analogy, where water will flow in every path that exists. So, if your battery (or other power source with ground #2) is quite powerful, you can actually harm your motherboard within your PC (or at least your USB bus ground), because '''<span style="color:red;">path B</span>''' runs through the motherboard circuitry on the way back to the voltage source.

This problem does ''not'' apply to using a different power source between a black power plug and for the green control terminal block on, say, a [[DC Motor and Controller Primer|DC motor controller]]. Although the grounds are connected, and they run across a part of a Phidget board, creating a ground loop does not actually run through any circuitry if only these types of boards are used. If you have a complex system with other types of boards and therefore circuitry between black plug power port and green terminal block connections, draw out your system carefully to identify the loops.

Ground loops can be fixed by one of the ways described in [[#How To Fix This|How to Fix This]] below.

=====Single Board Computer And Powered Hub=====

When combining one externally powered Phidget and the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer] or the [[Product - 1019 - PhidgetInterfaceKit 8/8/8 w/6 Port Hub]] on the same external power source, you still may inadvertently create a ground loop as described above in [[#Multiple Powered Phidgets|the multiple powered Phidgets section]]. If they share a true [[#Ground|Earth ground]], this is not a problem. But if the ground is from a battery, or uninterruptible power supply, etc. then you should carefully draw out your system circuit and examine it for ground loops.

====How To Fix This====

Once you are aware of shared grounds in your system, you have two options.

One, for ground loop problems in simple systems (two Phidgets), you could make the normal return path ('''<span style="color:blue;">path A</span>''') the most electrically desirable path. This is best for simple systems where you have a lot of control over all of the ground wires within your system. For the ground wires leading directly from the Phidget to the external power supply ('''<span style="color:blue;">path A</span>'''), lower the resistance in the wire as much as possible. You can do this by keeping the wires short, and using a thick (large gague) wire for the hookups.

Although this solution works, sometimes you do not have much choice on how long your ground return wires can be, because the location of your power supply and and Phidgets are set by your system design. If you cannot be totally sure that the direct ground path is the shortest and most electrically desirable path, it is best to use the second option: a '''USB Isolator''' such as the [[Product - 3060 - USB Isolator|Phidget 3060]]. This isolator is like any other USB isolator - it can be used on a Phidget system, as well as any system that needs ground isolation.

You need isolators for every USB cable in your system, less one. If you have two USB connections, you need one isolator; three USB connections, two isolators, and so on. The one USB connection can remain non-isolated because a single ground connection cannot form a loop. However, if you are concerned about connecting the grounds as described in the [[#One Powered Phidget|single connected Phidget section above]], use a USB isolator on every cable.

===Precise Voltage Control===

Precise voltage (or other system) control and measurement is related to the concept of [[#Shared Ground|shared ground above]]. But here, you want to keep grounds separate not only to prevent ground loops, but also to make your system more sensitive to what it will control or measure.

For example, we make Phidgets that can create power precisely, or that can take it in and measure it. One such product is the 1002, which outputs a precise analog voltage with which to control an analog system. Now that you know about [[#Ground|relative ground]], however, you would be right to expect that you do not want to combine the ground in the PC and the ground in the system.

Even if you don't care about system sensitivity, you can still create [[#Multiple Powered Phidgets|ground loops]] in a system with multiple of these types of Phidgets. In addition, if you are using the Phidget to control a large, powerful system, even a single Phidget can receive damage from connecting two powerful power sources meeting across it, also as [[#One Powered Phidget|described earlier]].

But above and beyond the powered Phidget problems, there is another reason to separate (isolate) the electrical grounds in your system. The reason is: to make your system control more precise. For example, with the 1002, if you are trying to control an external system with an Phidget output voltage, that output voltage should be relative to the ''system you are trying to control'', not relative to the PC. Rather than forcing the grounds - and therefore the relative voltages - to be equal to each other, you can provide more precise control by isolating the grounds and working with the relative voltage of the controlled system on its own terms.

<span style="color:red;">Schematic-type image of a ground isolated analog out on a 1002</span>

====How To Fix This====

The solution to all of these problems in precise voltage control systems is to use USB isolation, even for a single Phidget. The [[Product - 3060 - USB Isolator|Phidget 3060]] is one such isolator. It inserts along the USB connection between your PC and the Phidget, and it separates the Phidget (and controlled system) ground from the PC ground. This fixes ground loops, separates relative voltage mis-matches, and isolates the control system for better precision.

<span style="color:red;">Image of 1002 and Isolator connected, with lines superimposed on the image to show non-copper connection in isolator</span>

==Affected Products==

If you're not sure whether a certain concept applies to your Phidget within a complex system, the best way to figure this out is by doing some mental (or pencil and paper) simulation. Draw the inputs and outputs for the entire board, and label them with voltage, list their required amperage (or watts), and draw connections (such as ground connections) through any circuitry.

With a technique like this, it is easy to see that some products - such as the [[Product - 1049 - PhidgetSpatial 0/0/3|Phidget Spatial]] - are simply not complex at all. Although you could conceivably create problems (such as by using separate power supplies instead of using USB power and connecting the grounds incorrectly, or by using really long wires), this would be an exceptional case.

Other Phidgets can be more easily used incorrectly without realizing it. These are often devices that are simple in some systems and yet complex in others. Your primary defense against designing unreliable systems is to draw the system out and identifying any problems using the concepts in this primer. To help you, however, you can generally think of two classes of Phidgets which usually need careful handling when they are part of complex systems:
# Phidgets with more than one power source, (these can be subject to the [[#Shared Grounds|multiple power source problems]] described above)
# Phidgets needing precise measuring of an external power source (these can be subject to the [[#Shared Grounds|multiple power source problems]] ''and'' [[#Precise Voltage Control|precise voltage control]] problems)

Expanded into individual products, the Phidgets which are most often affected are.....

# These Phidgets use a second type of external power:
#* Motor controllers
#**[[DC Motor and Controller Primer|DC controllers]]
#**[[Stepper Motor and Controller Primer|Stepper controllers]]
#**{{LinksNeeded|Servo controllers|[[Servo Motor and Controller Primer|Servo controllers]]}}
#* Pure relay boards
#**[[Solid State Relay Primer|Solid state relay boards]]
#**[[Mechanical Relay Primer|Mechanical relay boards]]
#* Interface kits with relays
#**[[Product - 1017 - PhidgetInterfaceKit 0/0/8]]
#**[[Product - 1014 - PhidgetInterfaceKit 0/0/4]]
#* Powered Digital Output Interface Kits
#** [[Product - 1012 - PhidgetInterfaceKit 0/16/16]]
#* Interface Kits with Powered Hubs
#** The [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer]
#** [[Product - 1019 - PhidgetInterfaceKit 8/8/8 w/6 Port Hub]]
# And these Phidgets may have a need to be sensitive to external power:
#* [[Temperature Sensor Primer|Thermocouple]] control
#* Analog Output ([[Product - 1002 - PhidgetAnalog 4-Output]])
#* Frequency Counter ([[Product - 1054 - PhidgetFrequencyCounter]])

==Conclusions==

This page should have helped you to:
*Choose a power supply from either the [[#Wall Power|wall]] or a [[#Battery Power|battery]]
*Properly [[#Ground|ground]] and/or [[#How To Fix This|isolate]] that power supply from looping through other circuitry
*Also use [[#How To Fix This|isolation]] to make your control or measurement system more precise
*Keep your cables short and thick to reduce electromagnetic emissions and limit voltage drop
*Be more aware of system-wide power problems in general, and use drawing and analysis of systems to identify problems

==Glossary==
===Memory Effect===
Memory effect is an effect observed in NiCd batteries that causes them to hold less charge. It pertains to the specific situation in which NiCd batteries lose their maximum capacity if they are repeatedly recharged without being fully discharged. The battery appears to remember the smaller capacity. The term is often misused in cases where other batteries seem to hold less charge than originally, however this is most likely due to age and use. This phenomenon is unique NiCd batteries.

Solid State Relay Guide

2012-06-29T21:41:39Z

Cora:

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[Image:SSR.jpg]]
| [[Image:3052.jpg|200px]]
|}

==Introduction==

[[Image:SSR.jpg|thumb|A "hockey puck" SSR, so named because of its thick shape and black color. They are specifically designed to switch either AC loads or DC loads, but never both.]]

Solid state relays (SSRs) turn on or off the power being supplied to other devices, in a similar fashion as a physical [[Switch Primer|switch]]. However, instead of being switched by human interaction like a physical switch, SSRs are switched electronically.
With SSRs, you can control high-current devices such as lights or appliances with low-current signals, like a standard DC signal from a [[Digital Output Primer|Digital Output]]. Most SSRs will switch on with a voltage of 3V or higher. This makes them perfect for use with Phidget [[Interface Kits]], or any device with a digital output.

SSRs perform the same job as [[Mechanical Relay Primer|Mechanical Relays]], but have the following advantages:
* SSRs produce less electromagnetic interference than mechanical relays during operation. This is mostly due to the absence of a phenomenon called [[Mechanical Relay Primer#Arcing, Interference, and Sticking|contact arcing]] only present in mechanical relays, where the physical contacts of the relay tend to spark internally while switching. The reduced interference can also be attributed to the fact that SSRs do not use electromagnets to switch.
* The switch contacts of a mechanical relay will eventually wear down from arcing. An SSR will have a longer life because its internals are purely digital. Properly used, they will last for millions of cycles.
* SSRs turn on and off faster than mechanical relays (≈1ms compared to ≈10ms).
* SSRs are less susceptible to physical vibrations than mechanical relays.
* Since the switch inside an SSR isn't a mechanical switch, it does not suffer from [[Switch Primer#Bounce|contact bounce]] and operates silently.

However, compared to Mechanical Relays, SSRs:
* Are more expensive.
* Will dissipate more energy in the form of heat (1-2% of the energy intended to power the load).

==How SSRs Work==

[[Image:SSR_Internals.png|thumb|A conceptual diagram of the insides of an SSR.]]

The control inputs are connected internally to an LED, which shines across an air gap to light sensors.
The light sensor is connected to the transistors which open or close, supplying the relay's load with power.
When a transistor is '''closed''', current can flow freely through the relay, causing the load and power supply to be connected.
When a transistor is '''open''', almost all current is blocked, causing the load to become disconnected from the power supply.
The pairing of an LED with light sensors is called an optocoupler, and is a common technique to link two parts of a circuit without a direct electrical connection.

===Basic Use===

Controlling an SSR is no more complicated than turning an LED on and off. Switch it on, switch it off, it is that easy (see the [[Digital Output Primer|Digital Output Primer]], or our [{{SERVER}}/products.php?product_id=1031 specific LED controller] for more).

The ability of an SSR to switch a load is very similar to a [[Mechanical Relay Primer|mechanical relay]] or simple switch.
By turning the digital output controlling the relay on and off, you control whether or not the load is connected to its power supply.

The challenge is to pick an appropriate type of SSR for your application. There is no single SSR perfect for all applications. To choose an SSR for your particular application, please follow the [[#Choosing an SSR|Choosing an SSR]] section.

===Safety===

Since relays switch high currents and voltages, standard precautions apply. Make sure you never touch the terminals while the relay is powered. If your SSR came with a plastic cover, use it. Even when the SSR is switched off, a very small amount of current will flow.

When an SSR fails, it most often fails permanently closed. This is because when the transistor inside fails due to excessive current or heat, it will usually short out, allowing current to pass through unimpeded.
This means that as long as the power supply remains on, the load will be powered, possibly creating a fire or safety hazard.

==Choosing an SSR==

===Identify your voltage===

First, determine whether you need to switch AC or DC voltage. The electrical grid, and thus your wall outlet, runs AC, whereas batteries and most small power supplies are DC.

Next, determine the maximum number of volts you will be switching. If you are switching DC, particularly with batteries, assume your voltage is at least 25% more than what your battery is rated for. Even larger fluctuations occur on AC, but AC SSRs are designed to handle these surges. Typical AC voltage from a wall socket in North America is 110VAC, whereas in Europe it is usually 220VAC. If you are switching AC voltage from a wall socket, check which standard your country uses, and use that number as your voltage.

===Identify your current===

The current drawn by your load when turned on affects how large of an SSR you need, and how hot it will be when it is in use. If you know how much current, on average, your load draws, this is what we call '''Average Load Current'''. If you don't know the average current, but you know the wattage (power rating) of your load, you can calculate Average Load Current by:

<math>
\text{Average Load Current} =\frac{\text{Watts}}{\text{Operating Voltage}}
</math>

Next, you need to know the current drawn by your load when it is first turned on. Many loads demand a huge inrush of current when the load is first turned on. This places a significant amount of stress on the electronics inside the SSR. If you've ever noticed the lights dimming in the house for a second when the furnace starts up, this is caused by the fan motor starting up. In the same way that it takes a lot of force to move a heavy object from rest, it initially takes a lot of current to power up a fan or incandescent bulb. It's very difficult to measure the '''Surge Current''' itself, so we use a multiplier based on your device type. Surge Current is also referred to as '''inrush current'''.

{|border=1
|+'''Surge Current Multiplier'''
! Application
! Multiplier
|-
| Incandescent Light Bulbs || 6x
|-
| Motors || 6x
|-
| LEDs || 1x
|-
| Complex Electronics i.e., Motor Controllers, Phidgets || 6x
|-
| Fluorescent Light Fixtures (AC Only) || 10x
|-
| Transformers || 20x
|-
| Heaters || 1x
|-
|}

Multiply your Average Load Current by the multiplier for your device type to calculate the Surge Current.

===I need to switch AC===

Most AC applications will be switching 110 to 240 Volt power coming from the grid. If that's you, go to the [[#Mains Voltage (110 to 240V AC)|Mains Voltage (110 to 240V AC)]] section.

We also cover low voltage AC applications - 28 VAC (Volts AC) or less. For more information, visit the [[#AC/DC SSRs|AC/DC SSRs]] section.

===I need to switch DC===

If you only need to switch a small amount of current - 9 Amps or less, consider our compact, cost effective [[#AC/DC SSRs|AC/DC SSRs]].

If you need to switch more than 9 Amps, you need a serious [[#DC SSRs|DC SSR]].

If you need to switch up to 16 small loads of 2 Amps or less, you can use the [[Open Collector Digital Output Primer|open collector digital outputs]] on a [[1012_2 - PhidgetInterfaceKit 0/16/16|1012 PhidgetInterfaceKit 0/16/16]], which can be wired to behave similarly to relays.

==I need Gradual Dimming==

Instead of simply turning the load on/off, if you want to dim it gradually, you can use a proportional control SSR. They are able to reduce the average power to the load gradually, in proportion to the strength of the input signal. For more information, you can visit the [[#Proportional Control SSR|Proportional Control SSR Section]].

==Mains Voltage (110 to 240V AC)==

We sell AC SSRs for 120 VAC or 240 VAC operation. If you are unsure what voltages you could eventually need to switch, the 240 VAC relays can be used to switch 120 VAC with no problems. Please note we are very conservative in how we rate SSRs - our 120 VAC relays are rated by the manufacturer for 240 VAC, and the 240 VAC for 480 VAC. We strongly recommend against using them to the manufacturer rated voltage. To understand why, read the [[#AC SSR Protection|AC SSR Protection]] section.

===Load Type - Inductive vs. Resistive===

[[Image:zero cross.png|right|thumb|300px|This graph shows the difference between zero-cross and random turn-on. The blue line represents the oscillating voltage of an AC load, and the shaded areas represent the sections when the relay is turned on and letting current pass through. As you can see, the random turn-on SSR immediately opens when activated, while the zero-cross turn-on SSR waits until the voltage crosses zero before opening.]]

If your load is inductive, you need to choose a '''Random Turn On''' relay. If your load is resistive, choose a '''Zero Crossing''' relay.

Your Load will probably be inductive if it is built around a large coil of wire - motors and transformers are typical examples. A load considered resistive may also have loops of wire - for instance, hair dryers, toasters, incandescent bulbs use twisted wire elements to generate the heat. An inductive load will have thousands of loops of wire - it's a matter of scale. There is no such thing as a perfectly resistive load - but a load has to be very inductive to cause the zero crossing SSRs to malfunction.

SSRs are designed to either turn on immediately ('''Random Turn On'''), or wait until the next 'alternation' of the voltage ('''Zero Crossing'''). Zero Crossing SSRs create less electromagnetic 'noise' when they turn on. They are best used with resistive loads - Zero Crossing SSRs are not able to turn off some inductive loads. It's very difficult to determine which inductive loads will create problems - well beyond the scope of this document. If your load is inductive, we recommend buying the '''Random Turn On''' SSRs.

{|border=1
|+ '''Inductive and Resistive Loads'''
! Application
! Load Type
|-
| Incandescent Light Bulbs || Resistive
|-
| Fluorescent Light Fixtures || Inductive or Resistive <font size=4>'''*'''</font>
|-
| Motors || Inductive
|-
| Transformers || Inductive
|-
| Heaters || Resistive
|-
| Computer / Electronics || Resistive
|-
| AC/DC power supplies (brick heavy type) || Inductive
|-
|AC/DC Power supplies (lightweight switchers) || Resistive
|}

<font size=4>'''<nowiki>*</nowiki>'''</font> ''For fluorescent light fixtures, older units (magnetic ballast) may be inductive, and newer units are often resistive (electronic ballast).''

===Choosing your AC SSR===

Now that you have identified your Operating Voltage, Average and Surge Current, and your load type (inductive or resistive), you can create a short list of relays whose
* '''Maximum Load Voltage''' are greater than or equal to your operating voltage,
* '''Maximum Surge Current''' are greater than or equal to your surge current, and
* '''Load type''' matches what you chose for random turn on/zero crossing.

<font color=green> < Table: +ac_ssr > </font>

{|border=1
! Phidgets Product #
! Manufacturer Part #
! Current Type
! Turn-on Type
! Control Voltage (V)
! Max. Load Voltage (V)
! Max. Load Current Without Heatsink (A)
! Max. Load Current with 3955 Heatsink (A)
! Max. Load Current with 3956 Heatsink (A)
! Max. Surge Current (A)
! Output Type
|-
| 3953_0 || HFS34/D-240A20PS-Y || AC || Random Turn-on || 3-32VDC || 120 || 8 || 15 || 20 || 255 || SCR
|-
| 3954_0 || HFS34/D-240A80PS-Y || AC || Random Turn-on || 3-32VDC || 120 || 10 || 20 || 50 || 800 || SCR
|}

Now compare the '''Max. Load Current without Heatsink''' value for the SSRs on your list to your Average Load Current. If your Average Load Current is greater, you may need a heatsink. For selecting a heatsink, please consult [[#Picking a heatsink|Picking a Heatsink]]. Alternatively, look at other SSRs on your list - there may be an SSR that can handle your average load current with no heatsink.

At this point, you know the SSR you need.

Instead of simply turning the load on/off, if you want to dim it gradually, you can use a proportional control SSR. They are able to reduce the average power to the load gradually, in proportion to the strength of the input signal. For more information, you can visit the [[#Proportional Control SSR|Proportional Control SSR Section]].

If you are interested in learning more about SSRs in general, check out our [[#Did you know?|"Did you know?"]] section.

===AC SSR Protection===

[[Image:MOV.jpg|thumb|An MOV, which comes packaged with our AC "Hockey Puck" relays. ]]

Your AC SSR from Phidgets comes with a circular disc with two legs (pictured). This is a Metal Oxide Varistor (MOV) and should be installed across the load (larger) terminals of your SSR. MOVs are the classic surge protector - an inexpensive component that absorbs high voltage spikes. High voltage spikes are caused by inductive loads when they are turned off, and also happen very often on the electrical grid, as nearby devices are operated. Even if your load is resistive, use an MOV to protect the SSR.

Matching an MOV to an SSR is not easy - this is why we include an MOV with your SSR. If an MOV is chosen for too low of a voltage spike, it will wear out quickly. If it is chosen for too high of a voltage spike, it will not protect the SSR adequately. To balance SSR protection against MOV lifetime, we have found it necessary to use SSRs built for 240 VAC in 120 VAC applications, and SSRs built for 480 VAC in 240 VAC applications. If you must operate our AC SSRs on higher voltages than we recommend, do not use the included MOV.

As MOVs wear out from use, they will become more sensitive to common voltage spikes, causing them to wear out quicker. When they entirely fail, they will become a short circuit, potentially creating a fire hazard. The MOV included with your SSR has a fuse built in which will disable the MOV when it becomes a hazard. To be on the safe side, avoid mounting your SSR near any flammable material.

===Proportional Control SSR===

Proportional Control Relays (often simply called "Control Relays") are SSRs you can use to control the amount of power to the load. Rather than reduce the voltage, or somehow limit the current - which would be very expensive solutions, the Proportional SSR reduces power by turning the load on/off quickly, feeding full power in short pulses.

Proportional SSRs are controlled by a variable voltage - as the control voltage increases, more power is available to the load. Our PhidgetAnalog product can be used to control Proportional SSRs, since an [[Analog Output Primer|analog output]] can output various amounts of voltage, as opposed to a digital output, which only has two states- high and low. We don't sell Proportional SSRs - but they can be purchased from [http://www.digikey.com Digikey], where they are called AC Linear Controlled SSRs.

A quick and dirty solution for dimming with Phidgets is to use an {{LinksNeeded|RC Servo Motor|[[Servo Motor and Controller Primer|RC Servo Motor]]}} with a PhidgetAdvancedServo controller to rotate the knob on a light dimmer. From software, the RC Servo Motor is rotated to the desired position, cranking the knob as it turns. While this may seem like a roundabout way of achieving proportional control, dimmers tend to be much less expensive because they are less specialized and are manufactured in greater quantity.

===Example circuits with AC SSRs===

[[Image:AC SSR Load.png|right|thumb|300px|Schematic of an AC SSR switching a generic load. A metal oxide varistor is added across the load to protect the SSR.]]

When wiring up an AC circuit, particularly for long term installation, you may find it helpful to buy a book on residential wiring from your local hardware store. There are many wiring conventions (and often legal codes) which will help you plan your project, and the legal codes are often a great source of wisdom.

<br clear="all">

==DC SSRs (0 to 50V DC)==

We sell DC SSRs for that switch a maximum load of 50 volts. If you are unsure what voltages you could be switching in the future, higher voltage DC SSRs can be used to switch lower voltages. Common engineering practice would be to purchase an SSR rated for 50-100% higher voltage than the voltage you plan to be switching. For instance, if you are switching 24V, a 50V SSR is reasonable.

===Choosing your DC SSR===

Now that you have identified your Operating Voltage, Average and Surge Current, you can create a short list of relays whose
* Maximum Load Voltage are greater than or equal to your operating voltage,
* Maximum Surge Current are greater than or equal to your surge current, and
* Maximum Average Current is greater than or equal to your Average current.

<font color=green> < Table: +dc_ssr > </font>

{|border=1
! Phidgets Product #
! Manufacturer Part #
! Current Type
! Turn-on Type
! Control Voltage (V)
! Max. Load Voltage (V)
! Max. Load Current Without Heatsink (A)
! Max. Load Current with 3955 Heatsink (A)
! Max. Load Current with 3956 Heatsink (A)
! Max. Surge Current (A)
! Output Type
|-
| 3950_0 || HFS33/D-30D50M || DC || N/A || 3-32VDC || 30 || 18 || 50 || 50 || 120 || MOSFET
|-
| 3951_0 || HFS33/D-50D80M || DC || N/A || 3-32VDC || 50 || 20 || 40 || 80 || 200 || MOSFET
|-
| 3952_0 || HFS33/D-30D100M || DC || N/A || 3-32VDC || 30 || 25 || 50 || 100 || 240 || MOSFET
|-
|}

Now compare the '''Max. Load Current without Heatsink''' value for the SSRs on your list to your Average Load Current. If your Average Load Current is greater, you may need a heatsink. For selecting a heatsink, please consult [[#Picking a Heatsink|Picking a Heatsink]]. Alternatively, look at other SSRs on your list - there may be an SSR that can handle your average load current without a heatsink. SSRs rated for a larger load than the load you're using will be more efficient (meaning less energy lost in the form of heat) than an SSR that's being operated at its maximum load.

At this point, you know the SSR you need.

If you are interested in learning more about SSRs in general, check out our [[#Did you know?|"Did you know?"]] section.

===DC SSR Protection===

[[Image:Diode.jpg|thumb| A diode, included with our DC "hockey puck" SSRs. The cathode is marked with a line. The blue symbol shows circuit diagram equivalent of the diode.]]

[[Image:relaymotor.jpg|thumb| A DC SSR switching an electric motor. The 1018 Phidget InterfaceKit controls the SSR using its digital outputs. A diode is shown installed across the motor, and a fuse is hooked up between the power supply and the rest of the circuit.]]

Your DC SSR from Phidgets comes with a diode. This diode should be installed across your load, with the Cathode installed towards the positive terminal of the power supply (as shown in the diagram).

If the diode is installed backwards, as soon as the SSR is turned on, the load will be shorted out, likely destroying the diode, or the SSR, or your power supply.
A fuse protecting your power supply is always a good idea. You can place the fuse in between the positive terminal of the power supply and the positive terminal of the load side of the SSR.

The diode protects the SSR from powerful residual currents after the SSR is turned off. While your load is being driven, inductance builds up magnetic fields around the wiring.
Every load is inductive to some degree, and when the SSR turns off, the magnetic fields will ram current against the now open SSR, easily damaging it. The diode allows these currents to recirculate in the load until they have lost their energy.

<br clear="all">

===Example circuits with DC SSRs===

[[Image:DC SSR Load.png|right|thumb|300px|Schematic of an DC SSR switching a generic load, which is protected by a diode connected in parallel. The circuit is protected by a fuse in series after the power supply.]]

The electrical isolation built into a DC SSR allows them to be placed within a circuit just like a switch. Since it is isolated, you don't have to worry about grounding or voltage offsets.

With a DC SSR, always make sure the positive load terminal (labeled +) is facing towards the positive terminal of the power supply. If the load terminals are reversed, your load will immediately turn on. There is a diode inside of the SSR that allows current to flow freely through it when the SSR is connected incorrectly. This feature is included because this sort of wiring mistake would destroy the transistor in the DC SSR otherwise.

The DC SSR can be installed on either side of the load, and it will work properly, but there is an advantage to installing the SSR between the power supply and the load. If the load is connected to the power supply, it will always have a potentially dangerous voltage on it, even when it is not operating.

<br clear="all">

==AC/DC SSRs (0 to 40V DC / 0 to 28V AC)==

[[Image:AC_DC_SSR.png|thumb|A small, versatile AC/DC SSR mounted on a Phidgets board for easy pin access.]]

Our AC/DC SSRs are built on a small PCB, making them physically smaller than the large "hockey puck" SSRs, and less expensive. They are limited to lower currents, and cannot be mounted on a heatsink.

We sell AC/DC SSRs that can switch up to 40 Volts DC or 28 Volts AC. This is indicated on the SSR Product pages under the Maximum Load Voltage specification. There is no lower limit on the voltages that the AC/DC SSRs can switch. If your voltage is close - be conservative. For instance, a 36 Volt system built from 3 Lead Acid batteries can reach 45 volts when charging.

===Picking your AC/DC SSR===

Now that you have identified your Operating Voltage, Average and Surge Current, you can create a short list of relays whose
* Maximum Load Voltage are greater than or equal to your operating voltage,
* Maximum Surge Current are greater than or equal to your surge current, and
* Maximum Average Current is greater than or equal to your Average current.

<font color=green> < Table: +versatile_ssr > </font>

{|border=1
! Phidgets Product #
! Manufacturer Part #
! Current Type
! Turn-on Type
! Control Voltage (V)
! Max. Load Voltage (V)
! Max. Load Current Without Heatsink (A)
! Max. Load Current with 3955 Heatsink (A)
! Max. Load Current with 3956 Heatsink (A)
! Max. Surge Current (A)
! Output Type
|-
| 3052_0 || N/A || AC/DC || N/A || ??? || 40DC or 28AC || 2.5 || N/A || N/A || 5 || MOSFET
|-
| 3053_0 || N/A || AC/DC || N/A || ??? || 40DC or 28AC || 9 || N/A || N/A || ??? || MOSFET
|}

If you are interested in minimum cost, you will likely choose the cheapest option that meets these criteria. If you are interested in high efficiency operation and less heat generation, consider buying an SSR with higher current rating.

Your AC/DC SSR from Phidgets has built in protection from static electricity, and dangerous residual currents after the SSR is turned off. If the load you are switching is powered by a DC source, installing a diode across the load will offer even more protection. Refer to the [[#DC SSR Protection|DC SSR Protection]] section for more information.

To learn more about SSRs in general, visit the [[#Did you know?|"Did you know?"]] section.

<br clear="all">

===Example circuits with AC/DC SSRs===

[[Image:Versatile SSR DC Load.png|thumb|A versatile AC/DC SSR switching a DC load. The load terminals are bidirectional, so it doesn't matter which way you hook them up. The optional diode can be added to help protect the SSR when switching DC loads.]]
[[Image:Versatile SSR AC Load.png|thumb|A versatile AC/DC SSR switching an AC load.]]

The electrical isolation built into a AC/DC SSR allows them to be placed within a circuit just like a switch. Circuits without electrical isolation require a lot more care - proper grounding, careful consideration of voltage offsets.

<br clear="all">

==Using heatsinks with Hockey Puck SSRs==

[[Image:3950_0 Accessories Web.jpg|thumb|A "hockey puck" SSR with plastic cover (left), a thermal pad (right). All hockey puck SSRs sold at Phidgets come with both of these accessories plus a diode or varistor to protect the SSR.]]
[[Image:3955_0 Functional Web.jpg|thumb|A "hockey puck" SSR mounted on a [[3955]] heatsink by two screws. The thermal pad is pressed between the SSR and the heatsink.]]

SSRs will only achieve their promise of reliability and long life if they are kept cool. Cool is relative, of course, but a good rule of thumb is to keep the metal base of the SSR at less than 85°C (185°F). A [[Thermocouple Primer|thermocouple]] can be used to precisely measure the temperature of the metal base.

Excess heat usually comes from too much current and too little heatsinking. A lot of heat can also be generated by frequently turning the relay on and off. If your relay is operated for brief periods of time, you may not need as large of a heatsink - provided the relay is never accidentally left on for extended periods. Unless space is a concern, it's better to err on the side of caution.

Before buying a heatsink, consider if you actually need it. If your application is running at room temperature, and your average current is less than the '''Max. Load Current without Heatsink''' specification of your SSR, then you don't need a heatsink. Alternatively, if your project has a large metal chassis that the SSR can bolt to, this can be used as your heatsink.

Each SSR suitable for use with heatsinks will include a specification of how much current it can switch with each heatsink we sell. This specification assumes a reasonable airflow over the heatsink, and that the flowing air is at room temperature. Our SSRs have a sheet of metal underneath, where the heat is concentrated - this is also where the heat is measured to tell if the SSR is too hot. Phidgets includes a grey thermal pad with our Hockey Puck SSRs (see pictured). You place this pad under an SSR when mounting it on a heatsink, or on large metal surfaces that can dissipate heat. The pad performs the same function as thermal grease - it helps conduct heat between the base of the SSR and the heatsink. If you prefer to use thermal grease, you can use it instead of the pad. Our heatsinks include screws for mounting SSRs. Use a good size screwdriver when tightening the SSR down on the heatsink to ensure good conduction.

{|border=1
! Phidgets Product #
! Product Name
! Manufacturer Part #
! Dimensions (mm)
! Thermal Resistance (C/W)
|-
| 3955_0 || Small Heatsink for SSR || HF92B-80 || 50x50x80 || 2.4
|-
| 3956_0 || Large Heatsink for SSR || HF92B-150A || 55x142x150 || 0.6
|-
|}

<br clear="all">

==Hooking up wires to the Hockey Puck SSR==

[[Image:relay_mov.jpg|thumb|An AC SSR with the wires attached normally and an MOV installed across the load side.]]
[[Image:lugs.jpg|thumb|TRM6 wiring lugs connected to a DC SSR.]]

When wiring your load to the SSR, the wire is looped clockwise around the terminal, so when the screw is tightened down, it will draw the wire in tighter. We recommend using wires up to 10 AWG in size - any larger, and the screws will not have enough thread left to tighten down, and they will strip. Larger wires can be attached using a wiring lug. The lug is clamped under the SSR screw, and the wire attaches to the lug.

Loose wire connections can generate a lot of heat - use a large enough screwdriver when clamping down the load wires to ensure that the screws are on tight enough.

For the current ratings of various wires sizes, please see [[Page on Wire Sizes]].

<br clear="all">

==Did you know?==

* Mains Voltage '''AC SSRs''' cannot switch DC. They will never turn the load off. AC SSRs turn off twice per AC Cycle, when the current changes direction and is momentarily zero. For example, AC is 60 Hz in North America, so the AC SSR has 120 opportunities per second to turn off (the SSR will only '''stay''' off if the control signal is low). If the SSR is operating from DC, the current will flow continuously, and the load will not turn off, even when the control input is off.

* An '''AC SSR''' turns off automatically every time the load current reaches zero. It will turn back on almost immediately as long as the signal controlling the SSR is high. An AC SSR will actually have a low, non-zero current value that it regards as 'zero'. This specification is usually called "Minimum Load Current" in the data sheet. If your load requires less than this minimum current, your SSR will never turn on, or will not reliably turn on. The simplest solution to this problem is to connect another load in parallel with the first, increasing the Current required by the load.

* SSR Manufacturers have started adding a simple circuit inside '''AC SSRs''', across the load terminals, called a snubber. The snubber absorbs very fast electrical changes that could normally cause an '''AC SSR''' to turn on accidentally. When the AC SSR is turned on, there is little voltage difference between the terminals, so the snubber has very little effect. When the AC SSR is turned off, the snubber is actively protecting the SSR - but at a cost, as it allows a small current through the SSR, which is wasted.

* An '''AC SSR''' uses bipolar transistors - an old technology that has been replaced by CMOS transistors in modern digital circuits. Bipolar transistors are still superior for handling high voltages. Bipolar transistors, and the more complex transistors built from them, will lose a constant voltage as current flows through them. The collection of transistors in your SSR will lose about 1.7 volts - so on a 120 VAC system, you will lose about 1.5% to the SSR. This energy converts to heat inside the SSR, and the heating from these transistors is the reason SSRs often need heatsinks.

* SSRs, and semiconductors in general, usually fail as a short circuit. A short circuit is a circuit whose internals have been damaged such that current can flow through it freely. This means your load will probably turn on permanently (until you disconnect the power source) - make sure this doesn't cause a safety hazard. For instance, Sauna Heaters have a simple thermally-triggered mechanical shutdown to protect them if control electronics fails.

* '''DC SSRs''' (at least the units we sell) use Metal Oxide Semiconductor Field Effect Transistors (MOSFETs). MOSFETs do not lose a constant voltage - instead, when they turn on, they act as a very slight restriction to the flow of current - a resistor. At low currents, the slight restriction wastes very little power, giving high efficiency and often not requiring a heatsink. This efficiency is lost as the current increases - a doubling of current quadruples the production of heat.

* Normally, a MOSFET can only block current in one direction - as soon as the voltage reverses, the current flows through a diode run in parallel to the MOSFET. If a MOSFET were used to switch AC, the load would be turned on half the time. A common solution is to use two MOSFETs back to back - which is what we do with our '''AC/DC SSRs'''.

Electricity Primer

2012-06-29T21:40:32Z

Cora:

[[Category: Primer]]

==Introduction==

Design of reliable systems is really, really hard. The main challenge is the design of reliable building blocks - i.e. circuit and board layouts - from which to create your system. Phidgets does the majority of this work for you. And, once you have reliable building blocks, designing a reliable system from them is much easier.

However, you can still make an unreliable system out of Phidgets. In fact, if you are building a more complex system than the common examples we show through our documentation, and you have limited experience in complex electrical design, you will probably - and unintentionally - introduce design flaws that will make your system unreliable.

There are two reasons why you should read this primer:
# You want to build a complex system, more complex than we illustrate in our documentation. To succeed, you need to understand concepts.
# You understand how to make your system work, and you want to ensure it is well designed for maximum reliability and/or precision.

==The Basics==

To understand our discussion of potential problems and their solutions below, you'll need to be familiar with the basics. For this page, 'being familiar' means more than simply having heard of voltage, amperage, and power. You will need to have a working, conceptual model in your head, so that you can apply that model to your own system and examine it for problems. This section is all about giving the tools to build that mental model.

First, some terminology. We introduce it by analogy. If a circuit is a water system,
* The '''voltage''' is the ''pressure'' in the system
* The '''power supply''' is the ''pump'' creating the pressure
* The '''amperage''', also known as current, is the amount of ''flow''
* The '''load''' is the ''faucet'' - adjusting your load will adjust the flow
* The '''resistance''' is an attribute of the load - how tight or loose the faucet is
* The '''ground''' is the return path from load to pump.

The basic concepts for all of these terms are presented below.

===Load===

We start with the load, because the load is the purpose of your entire system.

In simple, USB-only Phidget systems, the load is the Phidget itself. The USB port is ready to provide power, but it does not (and cannot) until a load is applied (i.e. the Phidget is attached) and the circuit is completed.

Without a load that connects in a loop, it is like attaching a closed pipe to your pump. Initially, water will fill the pipe, and pressurize it, but once the pipe fills the system as a whole will do nothing more. To allow the pump to drive the load, and the flow to supply the load, we need to have a completed circuit, like this:

[[Image:elec_flow.png|150px]]

The load and the pump must '''match'''. If the load lets too much flow through, the pump will work too hard and burn itself out. This is what happens when you short circuit a power supply. The load is then simply a wire, which basically opens the flood gates and drains your power supply pump. The load must not let too much flow through, which it does by '''resistance'''. Likewise, the pump cannot push too hard on the load, or the load will break. This is discussed in-depth as part of [[#Voltage and Amperage|Voltage and Amperage]] below.

===Voltage and Amperage===

Within the flow concept [[#Load|above]], voltage is pressure. Specifically, it is the ''difference'' in pressure between the flow and the return. Voltage is measured in volts, and is denoted by '''V'''.

Amperage - also known as current - is the flow, or the amount of water that moves. At the pump, the amount of current out and the amount of current in are equal. The pressure might vary widely (highly pressurized pipes out, low pressure pipes back) but the ''amount'' of current is always the same. Amperage is measured in Amps, and is denoted by '''A'''.

To match a pump to a load, the voltage and amperage of the power (supply) and load (sink) must line up. We discuss picking a power supply - whether [[#Wall Power|wall mains]], or [[#Battery Power|batteries]] - in the [[#Power Needs|Power Needs section]] farther along in the document, but we need a few more concepts before we get there.

Power supplies - whether wall power or batteries - are usually rated based on voltage and amperage. Voltage is the specification to be the most careful with for circuits. Too much voltage is the same as overpressurizing your pipes - they will burst. In the case of electronics, you device will break.

This can be counterintuitive - in reference to safety (for humans) around electronics, you may have heard "It is not the voltage that will kill you, it is the amperage". Because of this, it may be tempting to think that too high of an amperage will harm your device, but this is not true. Our hearts are very susceptible to amperage but not voltage, hence amperage is considered dangerous for us whereas voltage is not. But a circuit is not like a human body - in a circuit trying to handle a power supply it is the voltage that matters most.

====Set Voltage (No Control)====

Most loads do no power regulation of their own. They simply take the voltage given to them and do useful things with it. You can tell that a pre-designed load (like a Phidget) falls into this category because it gives its voltage need ''as an exact value''. For example, most Phdigets use exactly 5 V of USB power. These loads will also tell you their amperage, which is a flow need that must be met or exceeded. A load will only use as much amperage as it needs.

====Controlled Power====

Some loads change the voltage or current they receive. This can be with the intent to either (a) keep a constant amount of power flowing from a draining power source like batteries, or (b) to modify a common power source (i.e. 12 V at 1 A) into an uncommon power source (i.e. 1 V at 12 A). This process is called '''regulation'''.

You can tell that a pre-designed load (like a Phidget) falls into this "power-regulated device" category because it gives its voltage need ''as a range''. For example, the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer (SBC)] can take 6 V to 15 V.

To understand how this works, take the example of a flywheel. Flywheels are designed to be heavy and to take work in order to get them spinning at speed. But once you have them spinning, you can extract that work later at a more consistent rate:

[[Image:elec_flywheel.png]]

Flywheels can either make amperage or voltage be the more consistent blue line over time. The most common one in Phidgets is for stable amperage. Regulated amperage is also how LED lights can stay consistently bright for any length of time when using batteries. Stable voltage design is usually applied when the voltage is too low to begin with (such as any device that runs on a single AA battery), and the flywheel must amplify and stabilize it over time.

For those readers trying to envision how this works electrically, in practice the flywheel is an inductor (or, a transformer utilizing its inductor properties). For both voltage and amperage regulation, one way relief valves (diodes) must be added. And, in amperage regulation a reservoir (capacitor) must be added to offset the current drop by pulling ''more'' amperage as a battery drains. Then, a controller is needed to measure and then correspondingly enable and disable the flywheel system as the voltage or amperage drops from the supply.

But with those details in place, the inductor (and capacitor, in the case of amperage regulation) can effectively take the variety of voltages from, say, a draining battery, and still allow the board to run. Some devices even do this naturally. For example, motors often can take a variety of voltages because their construction (i.e. wire wrapping) naturally creates inductance.

These regulated systems often list the power they need directly, using a type of power rating called '''watts'''. Watts are voltage and amperage together (i.e. power):

<math>
\text{Amperage} =\frac{\text{Watts}}{\text{Voltage}}
</math>

Watts can be a handy way to describe flow and pressure together for these regulated devices. Rather than separating voltage and amperage like the unregulated devices do (i.e. this load needs exactly 12 V, or this load will draw exactly 2 A), the unit of watts will allow different value combinations of volts and amps as long as the wattage remains the same. For example, a 12 watt device with a voltage range of 5 to 12 volts can run on 6 V at 2 A, or 12 V at 1 A. Either will work. Amperage for all values in the device's range of 5 to 12 V can be found with the equation above. Because of this, watts are often preferred when trying to match a power supply to a regulated load.

===Ground===

All circuits have a '''ground'''. This is simply the return pipe to the pump. In a circuit, it is denoted by an upside-down triangle:

[[Image:ground.png]]

When drawing a circuit diagram, the symbol is placed on the wires that return to the pump:

[[Image:elec_flow_ground.png|170px]]

This electric ground provides a voltage reference throughout the circuit. Ground is always '''0''' volts as far as the circuit is concerned. (Remember, voltage is the ''difference'' between the flow and return pipes at the pump.) Ground is important because it provides a reference from which all the parts of the circuit can speak the same "voltage language" to each other, which matters a lot when a certain voltage means "1" and a certain voltage means "0".

There is only one '''absolute''' ground, and that is the Earth, which is taken to be 0 volts as an absolute value. Circuits not well-grounded to the Earth (of which there are many - your cell phone, car, etc) operate at a '''relative''' voltage. The upside-down triangle above denotes a ''relative'' ground.

With relative voltage, only the difference between local ground and the local high voltage matters. For example, a cell phone might operate as a 3 volt device, which means relative to its ground it always operates between 0 and 3 volts. But if that cell phone were compared carefully to Earth ground, its absolute voltage could be, say, between 10 and 13 volts. Until comparison, the device doesn't "feel" charged. This is the same as how you don't "feel" charged after skidding your feet in socks across a carpeted floor. But, when you "compare" yourself to Earth ground by touching some well-grounded metal, you receive a static electricity shock.

The same thing can happen when you combine two different power supplies, as we discuss [[#Projects With Different Power Sources|below]].

===Power===

There can be different types of pumps, and at this point we should supplant our heart symbol with some actual power supply pump symbols. For example, this is the symbol for a direct current (DC) battery:

[[Image:elec_battery_basic.png|200px]]

The + end is on the out flow, and the - end is on the return (ground). Batteries are usually listed with their voltages. This is because the resistance of the load will determine how much amperage is drawn, but too much voltage and you will harm your load.

This is the symbol for alternating current (AC) that you would get directly from the wall:

[[Image:elec_wall_basic.png|200px]]

Again, this is listed using voltage for the same reasons as DC. A relative ground symbol is still used on the return line here. AC devices can still operate on relative voltage if they do not use Earth ground (the third prong on a wall plug in North America). This is how some loads have AC cords with only two prongs - they operate on a relative voltage and relative ground. And relative AC voltage, having significantly more voltage (pressure) behind it, can really hit a device hard when two power supplies meet across it.

This connecting of multiple power supplies is quite a complex subject, and is described further in both [[#Power Needs|picking different power supplies]] and [[#One Powered Phidget|connecting different power supplies]] later on in this Primer.

===Emissions and Wires===

To talk about emissions, it is worth speaking more precisely about what a load is. The typical, simple Phidget setup is receiving 5 V direct current (DC) from the computer over the USB port. Let's model this as coming from a battery so that we can examine all parts of the system. From the point of view of the battery, the Phidget load is not just the green board with the circuitry on it. The load ''also'' includes the power cable (i.e. two wires in the USB cable), and anything else on the path out or back from the circuitry to the battery itself:

[[Image:elec_phidget_basic.png|200px]]

This is important because the wires play a role in the voltage that eventually makes it to the Phidget. This is true all the time, even when the Phidget is attached to a computer instead of a battery. All wires have some resistance, and so they are, in a way, in and of themselves circuits. Therefore, because of their resistance, the wires 'use' some of the 5 V heading out to the Phidget circuit board. This is discussed more below, but essentially longer cables have more resistance and at some point the voltage will drop so much over the length that the Phidget will not turn on.

To conceptually separate the wires from the Phidget in terms of the load, we can now start drawing the wires themselves in our circuit diagram, instead of the curved concept arrows indicating flow and return:

[[Image:elec_phidget_wires.png|200px]]

When talking about the 5V relative ground in this system, we are in fact talking about the ground ''right at the battery'' so we move the ground symbol to the battery itself.

Then, the resistance on these wires creates a possible problem - the emission of electromagnetic radiation as the wires naturally drop the voltage:

[[Image:elec_phidget_emissions.png|200px]]

These emissions are at a set frequency determined by the length of the wire:
* Long wires create low frequencies (harmful interference)
* Short wires create high frequencies (less harmful interference)

This can be minimized by having the flow and return wires be the same length and sit right next to each other. This way, the emissions somewhat cancel each other out from the flow and return going in opposite directions. This is partially how USB cables minimize emissions.

So, the way you design your connections (i.e. the resistance and placement of your wire) will have a direct affect on:
# The voltage that reaches the Phidget
# The emissions that your system produces

With all this talk of emissions, you might be tempted to try to shield parts or all of your system from emissions that either your system or external systems create.

Keep in mind that shielding is actually really hard to do correctly. Especially when grounding your shielding, with ad-hoc design you have a high chance of having an interfering signal (that has traveled out to the shield and traveled back via ground) creating a larger problem than not having a shield at all. Rather than shielding, it is easier to simply keep your cables short and with as low a resistance as possible throughout your system to minimize your emissions in the first place.

Identification of and solutions to these (and other more complex) problems are discussed in detail in the [[#Selecting Cables|section on choosing cables]] and the [[#Hooking Up The Pieces|section on connecting the pieces]] below.

===Multiple Loads===

The easiest way to hook up multiple Phidgets is in parallel, where the voltage stays the same but they share the amperage. Here the DC supply is two USB ports, each at 5 V and 0.5 A:

[[Image:elec_phidget_parallel.png|250px]]

However, the length of your wires comes into play again, because the voltage that actually reaches the Phidgets above is somewhat less than 5 V. So if your wires are long, or mismatched, the voltage may not match and will give you strange results. The voltage is both affected on the way out, and on the way back. Assuming the wires are the same length:

[[Image:elec_phidget_wire_drop.png|350px]]

In this way, you can create difficult-to-debug problems within a complex system, where one Phidget works but others mysteriously fail.

==Power Needs==

Now that you've understood the basics, it is time to actually talk about decisions and design. This section will help you choose a power supply for your Phidget. Let's say you want to run the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer] off of a battery. Or you want to run a motor controller with a power supply you bought from the hobby store. What do you need to buy? Will one you already have work? It is worth it to spend a moment with pencil and paper to work through this section and identify your power needs.

As described [[#Voltage and Amperage|earlier]], voltage is pressure. Too much pressure behind your faucet, and the water mains or faucet will break. Likewise, if you have too much voltage from a power supply, your circuit will break. You should choose a supply with voltage that ''matches the range the Phidget can accept''. The voltage cannot be over the maximum (otherwise, like pressure in a pipe, the pipe will burst), and the voltage cannot be under the minimum (otherwise, like pressure in a pipe, no flow will occur). Also, generally, a device (like a motor controller) will perform better at its maximum rated voltage if a range is available.

But the faucet doesn't care whether there is a big reservoir or small reservoir feeding the system, as long as the pressure is managed. Likewise, you can choose a power supply with more amperage than you need (a big reservoir to draw from) as long as the voltage matches. In the same way that a faucet restricts water by design, loads draw and allow only the amperage that they need. However, the amperage cannot be less than the Phidget needs. In that case, you will either overextend (and break) your power supply, or the circuit simply will not turn on at all.

The specification [[#Device List|for your specific device]] will list its power needs. For most devices, the external power supply needs will simply be listed in voltage and amperage. USB power is 5V at up to 500 mA (0.5 Amps). Most Phidgets will draw less than this - if you need precision, you can check the specification for your particular Phidget. And, if it is an Interface Kit, you can add the draw of each analog sensor and digital in/out from their specifications.

However, some Phidgets (e.g. motors, and the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer]) do not have a straight amperage and voltage specification. Instead, their power draw will be listed in watts, for which you [[#Voltage and Amperage|saw a relation earlier]] to convert to the values you need.

===Wall Power===

Wall power sources usually take the alternating current (AC) from the wall and convert it into a direct current (DC). These power supplies often take your familiar two-or-three prong wall connector and put power out via a barrel plug-type connector. AC power (typically 110 or 240 volts, depending where you live in the world) goes in the typical wall plug, and DC power (typically 5 to 24 volts) comes out the barrel plug. Most power supplies of this type list the conversion explicitly, such as: 110-240 Volts to 12 Volts at 2 Amps. You'll want to match your Phidget's needs against the 12 Volts at 2 Amps.

*The voltage must match exactly
**If the Phidget takes a range of voltages, the supply must fall within the range
*The amperage can be equal to or greater than the Phidget needs

A wall power supply is essentially an inexhaustible supply of current, so you don't need to worry about it running out like you would with batteries.

===Battery Power===

If you intend to use a battery bank (even of only one battery) to power your Phidget, you probably want to know what type of battery to purchase.

====Battery Chemistries====
The first thing that sets batteries apart is the type of materials used in their construction. The following table shows several of the more common battery chemistries as well as the voltage per cell they produce and the specific energy of the chemistry.

{| border = 1
| align="center" style="background:#f0f0f0;"|'''Chemistry'''
| align="center" style="background:#f0f0f0;"|'''Nominal Cell Voltage'''
| align="center" style="background:#f0f0f0;"|'''Specific Energy (MJ/kg)'''
| align="center" style="background:#f0f0f0;"|'''Description'''
|-
| align = "center" colspan = 4|Primary Batteries
|-
| Alkaline||1.5||0.4||These are the most common form of battery. Many commercially available AA and AAA batteries are alkaline.
|-
| Lithium (LiMnO2)||3||0.83-1.01||These are used in high drain devices or devices with a long shelf life as they have a very low self discharge rate.
|-
| Silver-oxide||1.55||0.47||Only used in small button cells as these are quite expensive.
|-
| align = "center" colspan = 4|Secondary Batteries
|-
| NiCd||1.2||0.14||Older technology, suffers from [[Electricity Primer#Memory Effect|memory effect]]. Capable of very high discharge rates with no ill effects. Moderate self discharge rate.
|-
| Lead-acid||2.1||0.14||Not particularly good with high discharge rate. Moderate rate of self discharge.
|-
| NiMH||1.2||0.36||Very heavy. Good performance in high drain devices. Very high energy density naturally, at the cost of a high self discharge rate. Newer versions are able to get rid of some of the self discharge though they suffer ~25% lower energy densities as a result.
|-
| Lithium Ion||3.6||0.46||Expensive to produce but very high energy density. Very low self discharge rate. Safety hazard as short circuiting can yield explosive or fiery results.
|}

====Choosing a Battery====
Batteries are chosen first by their voltage (V). Match the voltage exactly to the voltage the Phidget needs. Over or under this value, you could harm the board or have it simply fail to turn on.

Next, choose a battery that has adequate amperage to feed your device for the time you need. The lifespan of the battery will usually be listed in Amp-Hours (or Ah). For example, a double wide 12 V lantern battery will have usually around 7-8 amp hours. This means if you drew one amp from it for seven to eight hours, the battery would be totally drained. Or you could draw two amps from it and drain it in 3.5-4 hours. This does not mean however, that you can draw 36A for 15 minutes. It is important to understand that there is a limit at which more power simply cannot be drawn from the battery. Effectively, high drain devices will decrease the rated Ah. The amount differs from battery to battery so to be sure it is recommended to check the data sheets for the battery you are using. If the battery did not come with a data sheet they can usually be found on the manufacturers website. The data sheets should have a graph that shows the relationship between current draw (usually in mA) and capacity (Ah or mAh). Another useful thing that can be gathered from the datasheets is the batteries response to temperature. Batteries tend to not work as well in cold environments, most manufacturers will provide graphs of how the batteries lifespans will shorten at different temperatures. This is often very significant, causing the battery to last a fraction of its normal lifespan at temperatures below -10°C.

Finding the amperage or voltage sometimes needs to be done indirectly by using a specification of watts. The relationship between amperage, voltage, and watts is given above in the [[#Voltage and Amperage|voltage and amperage section]].

For an example, let us say you want to use battery power to run the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer]. The specifications say that it uses 1.2 watts as a base value. The specifications also say that it can take 12 V DC power. If we choose to use a 12 V battery, at 1.2 watts it will use 0.1 amps according to the equation [[#Voltage and Amperage|shown earlier]]. Going by amp-hours alone, if our battery is a double-wide lantern type 12 V battery, with 7 amp hours, with 0.1 amp draw it will last 70 hours, or almost three days.

<math>
\text{Maximum Running Days} =\frac{\text{Battery Amp Hours}}{\text{Device Amps} * \text{24}}
</math>

However, to estimate ''average'' running time (rather than maximum running time possible), amp-hours cannot be used so directly. Over time, batteries decrease in voltage as their power is used up. Practically speaking, this means one of two things for your load. For loads that do not regulate voltage or current, the amperage will also decrease over time. The classic example is an LED light source that grows dimmer and dimmer as the batteries are used up.

You should usually only count on about 60% of the stated amp hour rating to apply before expecting to run into problems from escalated drain due to battery voltage drop. This is especially true for deep cycle rechargeable batteries left in an installation, where draining more than 60% could also harm the battery.

Then, for lead-acid batteries, a typical battery is tested from full to complete drain over 20 hours by the manufacturer to obtain the advertised amp-hour rating. Draining a battery at a faster rate than this will result in even more reduction in capacity, by 10% or even more. This due to [http://en.wikipedia.org/wiki/Peukert%27s_law Peukert's Law].

There are plenty of [http://www.google.ca/search?&q=battery+calculator battery calculators] around the Internet which take most or all of these additional factors into account when recommending an amp-hour rating. For longer-term installations, the solar power online community has some excellent resources.

====Setting up Multiple Batteries====
You can hook up multiple batteries in series to get more voltage at the same amperage. The amperage is additive. For example, you can hook up two single-wide 6 V lantern batteries in series to produce 12 V. Or two 12 V batteries in series to produce 24 volts. This system would still only have the amp hours of ''one'' of the lantern batteries, because you will be essentially using them both at once:

[[Image:elec_battery_series.png|250px]]

The upside down triangle (ground) is explained above in a [[#Ground|section of its own]].

Or, you can hook up multiple batteries in parallel to get more amperage at the same voltage. For example, you could hook up two 12 V deep cycle batteries in parallel to provide more amperage at 12 V, which is like having a deeper reservoir of power for your device to use:

[[Image:elec_battery_parallel.png|250px]]

====Heat====
*all batteries have some sort of internal resistance
*can be found on the battery's data sheet
*the more power you pull from the battery the more heat is going to build up as a consequence of the internal resistance.
*larger internal resistances will cause heat to build up faster.
*when charging a battery you are not just limited to the power in the battery. nothing stops you from dumping energy into the battery past the point where it is fully charged
**this is why charging batteries is a bit of a tricky business.
**many batteries come with custom chargers that have control systems to prevent this type of overcharging.

====Weight====
Finally, weight matters - a car battery is much heavier than a lantern battery. Batteries vary widely by weight per amperage. Lithium batteries are usually very light for their power, followed by alkaline, followed by lead acid. This may not seem important at first, but if you are building a mobile robot it is worth calculating in the work of carting around a battery. You may find that, for the length of time you want it to run, your battery requires some system redesign.

==Selecting Cables==

===USB Cables===

In general, use the shortest cables possible. There are many reasons for this [[#Emissions and Wires|described above]], but as a summary:

; Long cables reduce the voltage that reaches the Phidget.
: This happens in both directions. So, for every unit cable length added, the voltage decreases by twice the electrical resistance of that length of cable. With especially long cables the Phidget may drop below its 4.6 volt threshold and simply never turn on.

; Long cables increase the width of your circuit.
:All circuits act as emitting antennas for the resonance frequency of the circuit structure. The longer the wires in the circuit, the lower the frequency, and the higher chance that it will be emissions that will interfere with your data and system.

; Longer cables have more length exposed to external interfering emissions.

Also, use thick cables that are built to specification. Some USB cables with thinner wiring have higher electrical resistance. This can be equal to what a much longer wire would have, and thus create a similar voltage drop where the Phidget will not turn on.

====Options for longer cables====
The maximum length for a USB cable is 5m. This is laid out in the USB specifications. Often times however a system requires more reach. In this case there are a few options available to you. You can use what is known as an active extension cable or USB extender. These cables act like extension cables and add power to the line so that the signal can travel further. A second option is to use a Cat5 extender. These extenders are 2 USB dongles that connect on either end of your system. You join them up with Cat5 cable. This allows you to run over much longer distances than USB traditionally allows.

===Power Cables===

There are "DC Wire Table" references on the Internet which describe how to pick a wire appropriate for your voltage and amperage. When selecting AC wires, you will probably be using pre-made extension cords. Cords add interference resonance length to your circuit, just like USB cables do as [[#USB Cables|described above]]. A long extension cord can create huge electromagnetic interference for your circuit and other systems in the area when first plugged in.

Also as with the USB cables above, cut the cables to the shortest length possible. This is again both for voltage drop reasons and frequency emission reasons.

===Hubs===

Avoid hubs where possible. Unpowered hubs are good for reading data from memory keys, but not for powering many external devices. If you must use a hub, buy a powered one.

===Sensor and Motor Wiring===
All Phidgets sensor class devices (products whose part numbers start with 11 such as the 1129) use a 3 channel ribbon cable for power and data transmission. Similarly, all our motors and load cells use multichannel wire interfaces. As mentioned previously, USB spec limits cables to 5m, this is not the case for these wires. The biggest concerns are electromagnetic interference (EMI) and voltage drop. In general you should be able to run these wires over significant distances (30m or more) with the load cells in particular having very long range. If EMI starts causing issues you can always use ferrite beads on the cable near the sensor or motor and the controller to reduce noise.

===Cable Gauges for Terminal Blocks===

Many Phidgets products feature green terminal blocks that use screws to hold wires in place, making it easy to take apart and rebuild connections in your project. The size of the terminal block determines the gauge of wire you should use.

{|border=1
|+'''Terminal Block Size and Wire Gauge'''
! Terminal Block Width (mm/port)
! Recommended Wire Gauge (AWG)
|-
| 3.81
| 14 to 26
|-
| 5.0
| 12 to 26
|-
| 9.5
| 10 to 26
|-
|}

The gauge of cables and wires is measured in AWG, which is the American Wire Gauge standard. The following table lists the properties of wire gauges commonly used with Phidgets:

{|border=1
|+'''American Wire Gauge Sizes'''
! AWG Size
! Diameter (mm)
! Area (mm²)
|-
| 10
| 2.588
| 5.26
|-
| 11
| 2.305
| 4.17
|-
| 12
| 2.053
| 3.31
|-
| 13
| 1.828
| 2.62
|-
| 14
| 1.628
| 2.08
|-
| 15
| 1.450
| 1.65
|-
| 16
| 1.291
| 1.31
|-
| 17
| 1.150
| 1.04
|-
| 18
| 1.024
| 0.823
|-
| 19
| 0.912
| 0.653
|-
| 20
| 0.812
| 0.518
|-
| 21
| 0.723
| 0.410
|-
| 22
| 0.644
| 0.326
|-
| 23
| 0.573
| 0.258
|-
| 24
| 0.511
| 0.205
|-
| 25
| 0.455
| 0.162
|-
| 26
| 0.405
| 0.129
|-
|}

==Hooking Up The Pieces==

Here, things can be tricky. You might think: just plug everything in and go! But often it is not that simple. Many Phidgets require special care when hooking up. We encourage a process where you apply the concepts in this Primer, through analysis, to your system. So, we don't explicitly list the boards most commonly affected until the [[#Affected Products|end of this Primer]].

The ''categories'' of the boards which require special attention within a complex system are:

# Phidgets with more than one power source, and
# Phidgets needing precise measuring or control of an external power source

If you are already thinking about your boards in your head and trying to figure out whether they fit into one category or another, you're on the right track! The list of [[#Affected Products|commonly affected boards]] are only the common ones... with a sufficiently complex system, you could conceivably create problems with ''any'' boards.

Both types of projects require a full understanding of [[#The Basics|electrical basics]]. Using those concepts, below we first describe problems that arise when hooking up different power sources, and extend that into using the solution to give more precise measurement and control.

===Shared Grounds===

Shared grounds can occur in Phidgets that handle two different power sources. Recognizing the sharing of a ground is not always easy. We show what it is, how it can be possible, and why it creates problems by starting with the most basic Phidget system. The simplest setup for a Phidget is to use the [[#Ground|ground]] of the computer it gets data and power from over a USB port:

[[Image:ground_simple_case.png]]

In this case, there is only one relative ground, and it is the PC ground, which is ground #1 in the image. The PC ground determines what is considered 0 volts for all signals on the Phidget. When you add different power sources or sinks in the system, you are pulling the system relative to the PC ground.

=====One Powered Phidget=====

The next most complicated system is one Phidget that handles two power sources. Let us say you have a motor controller, which takes power from USB, and which also takes power from a second power source. Although the second power source is usually just a wall plug, the simpler case for thinking about ground is actually a battery. A battery creates a second ''relative'' ground. Through the Phidget, relative ground #1 (from the PC) and #2 (from the battery) actually become the same ground:

[[Image:ground_wall_power.png]]

This is the first reason why systems with powered Phidgets have to carefully manage ground. If ground #1 and ground #2 are different with respect to each other (see the static shock analogy in the [[#Ground|ground section]] above), then whatever circuitry along the red dashed arrow must deal with the initial static shock. In this case it would be the circuitry of the Phidget. In the case of a battery, after the initial equalizing shock the battery will be whatever relative voltage the PC ground needs it to be. Hence a battery relative ground can 'float'.

If ground #2 comes from the wall, on the other hand, the ground does not 'float' and instead is always absolute 0 volts Earth ground. With the PC giving the power, this is not a problem in practice because the PC can also float (as with a laptop), or it uses Earth ground. But if you were using a different and more powerful USB power supply instead of a PC, and then connected it to the absolute Earth ground through the Phidget, the Phidget would bear the brunt of any ground equalization that would occur. If neither the new ground nor the old ground float, and the power supplies were powerful enough, this would eventually destroy the Phidget. In this case, you would want to use isolation, as described in [[#How To Fix This|How To Fix This]] below.

=====Multiple Powered Phidgets=====

A worse case comes in when you are using two powered Phidgets and one external power source. Again, say you are using a battery as the external power source. It would be tempting to simply wire both grounds from the Phidgets to the ground on the battery:

[[Image:ground_two_phidget.png]]

Although this looks benign, you have actually created a new circuit. The circuit is a second path, via ground, for the current to return to the voltage source. This is also known as a '''ground loop'''. The path we intuitively think of the current returning by is '''<span style="color:blue;">path A</span>''', but the sharing of grounds has created a new path through the motherboard, '''<span style="color:red;">path B</span>''':

[[Image:ground_two_paths.png]]

All current gets 'pumped' in a loop by voltage, and so it will use all return paths available to it, assuming all paths are equally easy (electrically) to use. This extends the pipe analogy, where water will flow in every path that exists. So, if your battery (or other power source with ground #2) is quite powerful, you can actually harm your motherboard within your PC (or at least your USB bus ground), because '''<span style="color:red;">path B</span>''' runs through the motherboard circuitry on the way back to the voltage source.

This problem does ''not'' apply to using a different power source between a black power plug and for the green control terminal block on, say, a [[DC Motor and Controller Primer|DC motor controller]]. Although the grounds are connected, and they run across a part of a Phidget board, creating a ground loop does not actually run through any circuitry if only these types of boards are used. If you have a complex system with other types of boards and therefore circuitry between black plug power port and green terminal block connections, draw out your system carefully to identify the loops.

Ground loops can be fixed by one of the ways described in [[#How To Fix This|How to Fix This]] below.

=====Single Board Computer And Powered Hub=====

When combining one externally powered Phidget and the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer] or the [[Product - 1019 - PhidgetInterfaceKit 8/8/8 w/6 Port Hub]] on the same external power source, you still may inadvertently create a ground loop as described above in [[#Multiple Powered Phidgets|the multiple powered Phidgets section]]. If they share a true [[#Ground|Earth ground]], this is not a problem. But if the ground is from a battery, or uninterruptible power supply, etc. then you should carefully draw out your system circuit and examine it for ground loops.

====How To Fix This====

Once you are aware of shared grounds in your system, you have two options.

One, for ground loop problems in simple systems (two Phidgets), you could make the normal return path ('''<span style="color:blue;">path A</span>''') the most electrically desirable path. This is best for simple systems where you have a lot of control over all of the ground wires within your system. For the ground wires leading directly from the Phidget to the external power supply ('''<span style="color:blue;">path A</span>'''), lower the resistance in the wire as much as possible. You can do this by keeping the wires short, and using a thick (large gague) wire for the hookups.

Although this solution works, sometimes you do not have much choice on how long your ground return wires can be, because the location of your power supply and and Phidgets are set by your system design. If you cannot be totally sure that the direct ground path is the shortest and most electrically desirable path, it is best to use the second option: a '''USB Isolator''' such as the [[Product - 3060 - USB Isolator|Phidget 3060]]. This isolator is like any other USB isolator - it can be used on a Phidget system, as well as any system that needs ground isolation.

You need isolators for every USB cable in your system, less one. If you have two USB connections, you need one isolator; three USB connections, two isolators, and so on. The one USB connection can remain non-isolated because a single ground connection cannot form a loop. However, if you are concerned about connecting the grounds as described in the [[#One Powered Phidget|single connected Phidget section above]], use a USB isolator on every cable.

===Precise Voltage Control===

Precise voltage (or other system) control and measurement is related to the concept of [[#Shared Ground|shared ground above]]. But here, you want to keep grounds separate not only to prevent ground loops, but also to make your system more sensitive to what it will control or measure.

For example, we make Phidgets that can create power precisely, or that can take it in and measure it. One such product is the 1002, which outputs a precise analog voltage with which to control an analog system. Now that you know about [[#Ground|relative ground]], however, you would be right to expect that you do not want to combine the ground in the PC and the ground in the system.

Even if you don't care about system sensitivity, you can still create [[#Multiple Powered Phidgets|ground loops]] in a system with multiple of these types of Phidgets. In addition, if you are using the Phidget to control a large, powerful system, even a single Phidget can receive damage from connecting two powerful power sources meeting across it, also as [[#One Powered Phidget|described earlier]].

But above and beyond the powered Phidget problems, there is another reason to separate (isolate) the electrical grounds in your system. The reason is: to make your system control more precise. For example, with the 1002, if you are trying to control an external system with an Phidget output voltage, that output voltage should be relative to the ''system you are trying to control'', not relative to the PC. Rather than forcing the grounds - and therefore the relative voltages - to be equal to each other, you can provide more precise control by isolating the grounds and working with the relative voltage of the controlled system on its own terms.

<span style="color:red;">Schematic-type image of a ground isolated analog out on a 1002</span>

====How To Fix This====

The solution to all of these problems in precise voltage control systems is to use USB isolation, even for a single Phidget. The [[Product - 3060 - USB Isolator|Phidget 3060]] is one such isolator. It inserts along the USB connection between your PC and the Phidget, and it separates the Phidget (and controlled system) ground from the PC ground. This fixes ground loops, separates relative voltage mis-matches, and isolates the control system for better precision.

<span style="color:red;">Image of 1002 and Isolator connected, with lines superimposed on the image to show non-copper connection in isolator</span>

==Affected Products==

If you're not sure whether a certain concept applies to your Phidget within a complex system, the best way to figure this out is by doing some mental (or pencil and paper) simulation. Draw the inputs and outputs for the entire board, and label them with voltage, list their required amperage (or watts), and draw connections (such as ground connections) through any circuitry.

With a technique like this, it is easy to see that some products - such as the [[Product - 1049 - PhidgetSpatial 0/0/3|Phidget Spatial]] - are simply not complex at all. Although you could conceivably create problems (such as by using separate power supplies instead of using USB power and connecting the grounds incorrectly, or by using really long wires), this would be an exceptional case.

Other Phidgets can be more easily used incorrectly without realizing it. These are often devices that are simple in some systems and yet complex in others. Your primary defense against designing unreliable systems is to draw the system out and identifying any problems using the concepts in this primer. To help you, however, you can generally think of two classes of Phidgets which usually need careful handling when they are part of complex systems:
# Phidgets with more than one power source, (these can be subject to the [[#Shared Grounds|multiple power source problems]] described above)
# Phidgets needing precise measuring of an external power source (these can be subject to the [[#Shared Grounds|multiple power source problems]] ''and'' [[#Precise Voltage Control|precise voltage control]] problems)

Expanded into individual products, the Phidgets which are most often affected are.....

# These Phidgets use a second type of external power:
#* Motor controllers
#**[[DC Motor and Controller Primer|DC controllers]]
#**[[Stepper Motor and Controller Primer|Stepper controllers]]
#**[[Servo Motor and Controller Primer|Servo controllers]]
#* Pure relay boards
#**[[Solid State Relay Primer|Solid state relay boards]]
#**[[Mechanical Relay Primer|Mechanical relay boards]]
#* Interface kits with relays
#**[[Product - 1017 - PhidgetInterfaceKit 0/0/8]]
#**[[Product - 1014 - PhidgetInterfaceKit 0/0/4]]
#* Powered Digital Output Interface Kits
#** [[Product - 1012 - PhidgetInterfaceKit 0/16/16]]
#* Interface Kits with Powered Hubs
#** The [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer]
#** [[Product - 1019 - PhidgetInterfaceKit 8/8/8 w/6 Port Hub]]
# And these Phidgets may have a need to be sensitive to external power:
#* [[Temperature Sensor Primer|Thermocouple]] control
#* Analog Output ([[Product - 1002 - PhidgetAnalog 4-Output]])
#* Frequency Counter ([[Product - 1054 - PhidgetFrequencyCounter]])

==Conclusions==

This page should have helped you to:
*Choose a power supply from either the [[#Wall Power|wall]] or a [[#Battery Power|battery]]
*Properly [[#Ground|ground]] and/or [[#How To Fix This|isolate]] that power supply from looping through other circuitry
*Also use [[#How To Fix This|isolation]] to make your control or measurement system more precise
*Keep your cables short and thick to reduce electromagnetic emissions and limit voltage drop
*Be more aware of system-wide power problems in general, and use drawing and analysis of systems to identify problems

==Glossary==
===Memory Effect===
Memory effect is an effect observed in NiCd batteries that causes them to hold less charge. It pertains to the specific situation in which NiCd batteries lose their maximum capacity if they are repeatedly recharged without being fully discharged. The battery appears to remember the smaller capacity. The term is often misused in cases where other batteries seem to hold less charge than originally, however this is most likely due to age and use. This phenomenon is unique NiCd batteries.

OS - Linux

2012-06-29T21:39:24Z

Cora:

[[Category:OS]]
{{OSLang|[[File:icon-Linux.png|64x64px|link=OS - Linux]]|On Linux, Phidgets can be either plugged directly into a USB Port or run over a network using the [[#WebService | WebService]].}}
__TOC__

You need kernel '''version 2.6''' (released in 2003) or later.

==Quick Downloads==

Linux has complete support for all Phidgets and their software APIs; the only thing it lacks when compared to Windows and Mac OSX is a graphical user interface. We walk you through all steps for download, installation, checking, and starting to write code below.

If you are already a pro, and just want the downloads:
*[{{SERVER}}/downloads/libraries/libphidget.tar.gz Phidget Libraries for Linux]
*[{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz Phidget Generic C Examples]
*[{{SERVER}}/downloads/libraries/phidgetwebservice.tar.gz Phidget WebService for Linux]
*[{{SERVER}}/Drivers_Info.html#linux Software license]

==Getting Started with Linux==

===Installing===

To install the libraries, follow these steps:

#Download {{Code|libusb-0.1}} and its development libraries.
#*Note that libusb may be already on your system, but the development libraries probably aren't.
#*Try {{Code|apt-cache search libusb}} in a terminal to find current installable packages from your source list
#*Or install [http://www.libusb.org/ from source], which includes the libusb development libraries by default
#Unpack and install the [{{SERVER}}/downloads/libraries/libphidget.tar.gz Phidget Libraries]
#*From the main unpacked libraries directory, run:
#*:{{Code|./configure}}
#*:{{Code|make}}
#*:{{Code|sudo make install}}
#*This will compile phidget21.h and place the library into your gcc path

'''Note:''' Although these libraries are written in C, the additional libraries for Python, Java, and most other Phidget-supported languages depend on them.

===Checking===

To confirm the libraries were installed and work correctly, you can check both the hardware and software sides of the interface. It is worth checking the software side first, because if it works then you know the hardware side is also okay.

====Software====

To confirm that the libraries were installed correctly and can be used in code, you can use the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz Phidget Generic C Examples].

The easiest way to confirm correct installation will be to compile and run the {{Code|HelloWorld}} C example, included in the examples download. This does not involve writing any C code, but it does involve compiling the example and running it, which is a quick process as we show below. If you feel more comfortable running the {{Code|HelloWorld}} example for your specific language, you can skip below and pick your language, but keep in mind that any problems could be with the C library installation and not necessarily with your language.

To compile and run the basic C example for checking your installation:

1. Unpack the Phidget Generic C Examples<br>
2. Open a terminal (often Ctrl-Alt-T) and go to the directory where the examples are unpacked<br>
3. Compile the {{Code|HelloWorld.c}} example:<br>
<div class="source">
<syntaxhighlight lang=bash>

gcc HelloWorld.c -o HelloWorld -lphidget21

</syntaxhighlight>
</div>
4. Run the {{Code|HelloWorld}} example:<br>
<div class="source">
<syntaxhighlight lang=bash>

sudo ./HelloWorld

</syntaxhighlight>
</div>
(The sudo is needed for USB access for now, see the [[#Setting udev Rules|Setting udev Rules]] section for how to change this)

The {{Code|-lphidget21}} will look in the standard library location for your Linux distribution (usually {{Code|/usr/lib/}}) for the Phidget 21 library file. Generally, libraries to be linked on Linux through {{Code|gcc}} have a naming convention. For example, {{Code|-lphidget21}} looks for the binary files '''{{Code|libphidget21.a}}''' and '''{{Code|libphidget21.so}}''' in the library location. These files are automatically put in the library location during the {{Code|make install}} step of [[#Installing | installing the libraries]].

The HelloWorld program will simply print out basic information for any device you plug in, and print a message upon unplugging the device. For example, starting the program, plugging in an Interface Kit Phidget, unplugging the Interface Kit, and pressing Enter displays:

<div class="source">
<syntaxhighlight lang=bash>

$ sudo ./HelloWorld

Opening...
Press Enter to end

Hello to Device Phidget InterfaceKit 8/8/8, Serial Number: 37299
Goodbye Device Phidget InterfaceKit 8/8/8, Serial Number: 37299

Closing...

</syntaxhighlight>
</div>

====Hardware====

If the out-of-the-box examples do not work, make sure the Phidget is seen by your USB interface. To check this, you can use the kernel log reader {{Code|dmesg}}. Pipe the output of {{Code|dmesg}} into the utility {{Code|tail}} to read the last ten lines of the log:

<div class="source">
<syntaxhighlight lang=bash>

$> dmesg | tail
....(9 lines)....
[24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd

</syntaxhighlight>
</div>

The number between the [ ] is the system time in seconds since the last boot up, so you can tell whether the event was recent or not. (This will also tell you the interrupt type of Phidget that is registered by the USB interface, see the [[#Common Problems and Solutions | common problems section below]] for more information on what this means.)

The Phidget should both connect and disconnect properly, so unplugging it should result in an additional line at the tail:

<div class="source">
<syntaxhighlight lang=bash>

$> dmesg | tail
....(8 lines)....
[24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd
[25094.809328] usb 2-1.2: USB disconnect, device number 5

</syntaxhighlight>
</div>

If you don't see similar lines to these at the tail of your kernel log, take a look at the [[#Troubleshooting|troubleshooting]] section below, as well as the '''Communications''' section of our [[General Troubleshooting#Communications Troubleshooting|general troubleshooting page]].

====Troubleshooting====

If the examples '''do not''' work but USB '''does''' work (i.e. your computer can consistently see the device in the [[#Hardware|hardware]]), take a moment to check the basics:
* No other programs, drivers, or processes are using that USB port in software
* You are running the example program as root (or your udev rules have been set properly)
* You are using libusb 0.1 (not 1.0 or later)
* You have compiled versions of libphidget21.a and libphidget21.so in your system library location (usually {{Code|/usr/lib}})
* The Phidget libraries are the latest version (visit the [[#Quick Downloads| quick downloads section]] to download them)
* Your Linux kernel version is 2.6 or later (type {{Code|uname -r}} in a terminal to get your kernel version)
* Check the [[#Common Problems and Solutions|common problems]] section below, some specific combinations can cause problems

If your problem doesn't seem to be fixed by these steps, make sure that the Phidget is seen '''consistently''' by USB (if it is erratic, try our [[General Troubleshooting|general troubleshooting guide]]). If you are still having problems after using the troubleshooting guide, please [[Contact Us|ask us]]!

==Programming Languages==

Now that you have the basic libraries installed, you can pick your language and begin programming!

If you are not using the [[#WebService | webservice]] (discussed below) to control a Phidget over a network, your next step will be to delve into the use of your specific language. Each page has its own set of specific libraries, code examples, and setup instructions.

On Linux, we recommend the following languages:

*[[Language - C/C++|C/C++]]
*[[Language - Java | Java]]
*[[Language - Python | Python]]
*[[Language - Ruby | Ruby]]
*[[Language - C Sharp | C#]] (Using [[Language - C Sharp#Mono|Mono]])
*[[Language - Flash AS3 | Flash AS3]]

You can also use these languages, but they do not support [[General Phidget Programming#Event Driven Code | event driven code]], and must use [[General Phidget Programming#Logic Code | logic code]] only:

*[[Language - MATLAB|MATLAB]]
*[[Language - Simulink|Simulink]]

==WebService==

The Phidget WebService allows you to remotely control a Phidget over a network.<br>This section helps you install, check, and use the WebService on Linux, but we also have an overview of the [[Phidget WebService]] in general.

===Installing the WebService===

To install the webservice, you must first have the [[#Installing|Phidget libraries installed]]. Then, follow these steps:

#Download '''avahi''' and its development libraries (mdnsresponder/bonjour is also an option, see the [[#WebService with mDNSResponder|webservice with mDNSResponder]] section)
#*Try {{Code|apt-cache search avahi}} in a terminal to find current packages
#*Often, this is installed in a default system, you may already have it
#Unpack and install the [{{SERVER}}/downloads/libraries/phidgetwebservice.tar.gz Phidgets WebService] source code tarball for Linux
#*From the unpacked WebService source code directory, run:
#*:{{Code|./configure}}
#*:{{Code|make}}
#*:{{Code|sudo make install}}
#*This will compile the executable {{Code|phidgetwebservice21}} and place it into {{Code|/usr/bin/phidgetwebservice21}}

====WebService with BSD====

For '''BSD''', the webservice has been found to work (BSD 8+) but requires a special configuration at the {{Code|./configure}} step:

<div class="source">
<syntaxhighlight lang=bash>
./configure LIBS=/usr/lib/libphidget21.so CFLAGS=-pthread
</syntaxhighlight>
</div>

Then {{Code|make}} and {{Code|sudo make install}} are the same.
<br>
The {{Code|LIBS}} argument may not be necessary, but sometimes BSD has trouble finding the library install location. The {{Code|CFLAGS}} argument is needed because BSD needs explicit linking for using threads.

====WebService with mDNSResponder====

To use '''mdnsresponder''' instead of avahi, change the configure script to be:

<div class="source">
<syntaxhighlight lang=bash>
./configure --enable-zeroconf=bonjour
</syntaxhighlight>
</div>

(To see all options, use {{Code|./configure --help}} like you would any configure script)

===Setting Up the WebService===

To set up and use the webservice, it helps to have [[#Setting udev Rules|set your udev rules]]. Otherwise, you must run the webservice as root.

You can get command line help with {{Code|phidgetwebservice21}} by using the {{Code|-h}} option:

<div class="source">
<syntaxhighlight lang=bash>
$ phidgetwebservice21 -h
</syntaxhighlight>

<syntaxhighlight lang=text>
'phidgetwebservice21' is a Phidget and Dictionary server from Phidgets Inc. See www.phidgets.com for more information.
Usage: phidgetwebservice21 [OPTION]
All parameters are optional. The default parameters are: port=5001, ServerName=(Computer Name) and no password

Options:
-p Port
-n Server Name
-P Password
-v Debug mode
-h Display this help
</syntaxhighlight>
</div>

You will see this help regardless of whether the webservice was correctly hooked in to avahi. In fact, you will see it even if you explicitly disabled mDNS in the {{Code|./configure}} step at compile:

<div class="source">
<syntaxhighlight lang=bash>
./configure --disable-zeroconf
</syntaxhighlight>
</div>

(To see all options, use {{Code|./configure --help}} like you would any configure script)

To find the defaults used by {{Code|phidget21webservice}}, the command line is the fastest way to learn the default server name and IP address of your computer:
*For the default server name, use {{Code|hostname}} on the command line.
*For your IP address, use {{Code|ifconfig -a}} on the command line.
**A line in the return text, under your main internet connection (usually {{Code|eth0}}) will say something like {{Code|inet addr:192.168.3.178}}, which is your IP.

Using a server name to connect would not be an option without avahi or some other mDNS service; in this case you would only have the option to use an IP address.

===Using the WebService===

To use a Phidget over the webservice, you'll want to:
* Obtain code you can use to open a Phidget remotely
* Start the webservice on the computer that directly connects to the Phidget
* Run your program on the remote computer that will control the Phidget over the network

The easiest way to test these steps on Linux is simply to set up the webservice and run the Phidget program on the same computer, using the loopback interface. Later, you can replace one of the two ends with a different computer and/or operating system.

To quickly create code to run remotely, in our examples we include commented out lines with openRemote() function calls of different types. In the C example for your device, find the line that says:

{{Code|CPhidget_open((CPhidgetHandle) device, -1)}}

and change it to be:

<div class="source">
<syntaxhighlight lang=bash>
int serial_number = 37299
CPhidget_openRemoteIP ((CPhidgetHandle) device, serial_number, "127.0.0.1", 5001, NULL)
</syntaxhighlight>
</div>

Except that you should replace '''37299''' with the serial number of your Phidget, which you can obtain from either the Phidget board itself, or from when you [[#Checking|ran the HelloWorld example code]]. The IP address "127.0.0.1" simply loops back to the same computer, and 5001 is the default port as found from using {{Code|phidget21webservice -h}} in [[#Setting Up the WebService|the Setting Up the WebService]] section. The NULL is used to not specify a password.

Save the changed example under a different filename. In the walkthrough here, we are using the {{Code|InterfaceKit.c}} example, and we rename it to be {{Code|InterfaceKitRemote.c}}

Compile your new C file. In our {{Code|InterfaceKitRemote.c}} case, this would be by:

<div class="source">
<syntaxhighlight lang=bash>
gcc InterfaceKitRemote.c -o InterfaceKitRemote -lphidget21
</syntaxhighlight>
</div>

1. Start two terminals to run this test, usually opened via Ctrl-Alt-T. Your [[#Setting udev Rules|udev rules]] need to be set up or you should use sudo for every command. First, start the webservice in Terminal #1:

[[Image:Linux_ws_start.png]]

This will broadcast any Phidget events, and receive any Phidget requests, both over the network.

2. Start the InterfaceKitRemote program that you just compiled which will open the remote Phidget. In this case, it is {{Code|InterfaceKitRemote}}:

[[Image:Linux_ws_step2.png]]

3. Now, plug in the Phidget! The {{Code|phidget21webservice}} program captures the attach and other events and sends them out over the network (in the background in Terminal #1) and the Phidget software objected opened with openRemote in Terminal #2 receives them:

[[Image:Linux_ws_step3.png]]

4. You can confirm that the webservice was indeed behind this exchange by killing the webservice process while still allowing the remote program to run:

[[Image:Linux_ws_step4.png]]

===Debugging the WebService===

In addition to enabling [[General Phidget Programming#Logging|logging]] in your Phidget code, you can get additional debugging information from the WebService itself. This additional debugging is enabled via a re-compile of the webservice. From the webservice source code directory, do:

<div class="source">
<syntaxhighlight lang=bash>
make clean

./configure --enable-debug

make

sudo make install
</syntaxhighlight>
</div>

If you suspect multicast DNS (mDNS) may be the problem, you can:
* Try compiling the webservice with mDNSResponder, as described in [[#Installing the WebService|Installing the WebService]], or
* Try compiling the webservice completely without mDNS, as described in [[#Setting Up the WebService|Setting Up the WebService]]

==Advanced Uses==

===Setting udev Rules===

If you don't want to be using {{Code|sudo}} to run Phidget programs (including the webservice) forever, you will want to create a {{Code|udev}} rule to allow yourself access to the Phidget when you are not root.

Udev has an easy way to set the owner and permissions of the USB interface of the Phidget - it finds all devices that match a given set of rules, and applies new traits to them. But you need to give udev something to match in order to apply the new settings. Here, we will tell udev to match the vendor code for Phidgets, Inc. You can get the vendor code in hex by using {{Code|lsusb}}:

<div class="source">
<syntaxhighlight lang=bash>
$> lsusb
....Information about other devices...
Bus 002 Device 013: ID 06c2:0045 Phidgets Inc. (formerly GLAB) PhidgetInterface Kit 8-8-8
</syntaxhighlight>
</div>

The two numbers separated by a colon are the codes for '''vendor:product'''. Since we want to set up the rule so that all Phidgets, no matter what product, can be used without root privileges, we use the vendor code, which is '''06c2'''.

The rules for udev are kept in files in {{Code|/etc/udev/rules.d/}} and are traditionally grouped into order of running (10 runs before 20, 30, etc) and device type (cd, network, etc). There should be one or more files in there already - if this is your first time editing udev rules take a look at them to see the syntax to use:
* Commas separate each pair with == or =
* One rule on each line, no line breaks
* Quotes around the value to be matched or changed
* Comments can be added on lines starting with #

Strictly speaking, the files run in lexical order (i.e. the order they're listed when you use {{Code|ls}}). A device can match many rules, and all will apply (if possible). If conflicting rules are found, the first rule found is followed.

To make sure the Phidget udev rules are found first, we can create a file {{Code|10-persistent-usb.rules}} (all udev rule files need to end with {{Code|.rules}}) and add one line to it:

<div class="source">
<syntaxhighlight lang=bash>
SUBSYSTEM=="usb", ATTRS{idVendor}=="06c2", MODE="0666", OWNER="user"
</syntaxhighlight>
</div>

Make sure to replace {{Code|user}} with your user name. You probably recognize the '''06c2''' from the vendor discussion above. We have added the match on {{Code|SUBSYSTEM}} to search first within usb (within a possibly big database). The {{Code|MODE}} sets read and write privileges for everyone to the device, and {{Code|OWNER}} sets the owner to be you.

Save the {{Code|10-persistent-usb.rules}} in {{Code|/etc/udev/rules.d/}} and then change its permissions so it can be read by all:

<div class="source">
<syntaxhighlight lang=bash>
sudo chmod a+r /etc/udev/rules.d/10-persistent-usb.rules
</syntaxhighlight>
</div>

The udev rule is now set, and it just has to get read in. The reading of the rules is goverened by a daemon, {{Code|udevd}}, which you can manage via the program {{Code|udevadm}}. The {{Code|udevadm}} man page is quite extensive for all sorts of uses of {{Code|udevadm}} while you are testing this or other udev rules. To re-read and implement the rules without having to reset the daemon or reset the computer, you can use:

<div class="source">
<syntaxhighlight lang=bash>
sudo udevadm control --reload-rules
</syntaxhighlight>
</div>

Finally, if you performed all of these steps with the Phidget plugged in to your computer, you will need to unplug and plug the Phidget back in before trying to use usb access without root privileges.

===Starting the WebService at Boot===

If you are tired of starting the webservice on the command line all the time, you can have the webservice start when your system starts, every time.

====User Space====

If you are running a standard Linux machine with an X-server (Unity, KDE) the easiest way to do this is to have the Phidget WebService start when your x server starts.

In this case, the webservice will be running in user space, so your [[#Setting udev Rules|udev rules need to be set up]] for the your user permissions to be able to access the USB ports using libusb.

Within the X-windowing system, there is usually some sort of {{Code|System → Settings/Preferences → Startup}} that you can choose to add programs that start when a user session starts. On Ubuntu you can use Unity to find programs listing "startup" in their names to accomplish the same thing. This will eventually lead you to a graphical tool like this to simply add the {{Code|/usr/bin/phidgetwebservice21}} program:

[[Image:linux_ws_boot.png|400px]]

====As A Service====

You would want to set the boot start of {{Code|phidgetwebservice21}} to be a service if you are running a server, or a headless machine. It is handy any time you need the webservice to be started as a booted, respawning service with a presence in different run levels and for all users.

A service is essentially a program that hangs out in the background, waiting to be used by some incoming task. When the service is needed, the service forks a program to handle that need. Most services that run on your Linux computer already have the ability to fork themselves.

The webservice, however, is just a binary on Linux - {{Code|phidgetwebservice21}} - and so we need a program that handles the forking for us. For this, we use the {{Code|start-stop-daemon}} program to spawn a standalone process for us, or kill it, based on our service-like start, stop, and restart commands.

To do this, we need:
# A script that tells the boot process how to start and handle the webservice (i.e. by using {{Code|start-stop-daemon}})
# A link from that script to the boot list
# An initialization file for the script

First, the script. We will walk through Debian here, both because it is such a common distribution and because it is the distribution that our [{{SERVER}}products.php?product_id=1072 Single Board Computer] runs. But {{Code|init}} is surprisingly diverse on Linux, including everything from a different boot order, to different initialization programs and structure, and even different runlevels.

On Debian (including Ubuntu), the initialization script covers:
* Runlevels that the service should be present on
* Dependencies of the service
* Name of the service and other informative data
* The location of the PIDFILE, which stores the process ID (pid) for later dealing with a spawned instance
* Any configuration file locations
* What to do when the service is given instructions to '''start''', '''stop''', or '''reload'''.

The Debian script we use to start the webservice on the [{{SERVER}}products.php?product_id=1072 Single Board Computer]:

<div class="source">
<syntaxhighlight line start="1" lang=bash>

#!/bin/sh

### BEGIN INIT INFO
# Provides: phidgetwebservice
# Required-Start: $network $remote_fs
# Required-Stop: $network $remote_fs
# Should-Start: avahi
# Should-Stop: avahi
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Phidget WebService
# Description: Phidget WebService for controlling Phidgets over the network.
### END INIT INFO

DESC="Phidget WebService"
NAME=phidgetwebservice
BIN=phidgetwebservice21
DAEMON=/usr/bin/$BIN
PIDFILE=/var/run/$NAME.pid
CFG=/etc/default/$NAME

# Gracefully exit if the package has been removed.
test -x $DAEMON || exit 0

# load config
pws_port="5001"
pws_serverid=""
pws_password=""
[ -f $CFG ] && . $CFG

start() {
[ -z "$pws_port" ] || OPTIONS="-p $pws_port "
[ -z "$pws_password" ] || OPTIONS="$OPTIONS-P $pws_password "

if [ -z "$pws_serverid" ]; then
OPTIONS="$OPTIONS -n $( hostname )"
else
OPTIONS="$OPTIONS -n $pws_serverid"
fi

echo -n "Starting $DESC: "
start-stop-daemon -S -b -q -p $PIDFILE -m -x $DAEMON -- $OPTIONS && echo "OK" || echo "ALREADY RUNNING"
}

stop() {
echo -n "Stopping $DESC: "
start-stop-daemon -K -q -p $PIDFILE -x $DAEMON && echo "OK" || echo "NOT RUNNING"
}

case "$1" in
start)
start
;;
stop)
stop
;;
restart|force-reload)
stop
sleep 1
start
;;
*)
echo "Usage: $0 {start|stop|restart}"
esac

exit 0
</syntaxhighlight>
</div>

Save the script into a file called {{Code|phidgetwebservice}}, and use {{Code|chmod 755}} to make it executable.

Also on Debian, startup service scripts should go in {{Code|/etc/init.d}}, and then put within the appropriate runlevel-numbered folder - by symbolic link. There is a handy tool to do this for you, called {{Code|insserv}}:

<div class="source">
<syntaxhighlight lang=bash>
sudo insserv -d phidgetwebservice
</syntaxhighlight>
</div>

The {{Code|insserv}} program is the program that makes use of the {{Code|### BEGIN INIT INFO...### END INIT INFO}} that appears at the top of the {{Code|phidgetwebservice}} script. Use {{Code|man insserv}} for more information. The {{Code|insserv}} tool handles the mess of finding the right runlevel folders (i.e. the {{Code|rc.d}} numbered folders) and making the appropriate links. You can see what links would be updated by running {{Code|insserv}} with the {{Code|-n}} option, for a dry run.

'''Note:''' When you run {{Code|insserv}}, all of the dependencies for the boot order are re-written. This means that all of the initialization scripts in {{Code|/etc/init.d}} are re-examined. So, you'll probably get a lot of output when you run the command.

Then, you can check that {{Code|phidgetwebservice}} is on the service list with:

<div class="source">
<syntaxhighlight lang=bash>
service --status-all
</syntaxhighlight>
</div>

And you can start it right now without rebooting like this:

[[Image:linux_system_service_start.png]]

The {{Code|service}} command has many options to start and stop services like the phidgetwebservice, try {{Code|man service}} for more information.

At this point, you can follow the client instructions on [[#Using the WebService|using the webservice]] to create a loopback test for the new webservice service that should now be running.

The final piece, for future configuration changes, is that the {{Code|/etc/init.d}} script looks for the file {{Code|/etc/default/phidgetwebservice}} upon starting up. The file is expected to contain the port, server ID, and password for the server side of the webservice. These are also set in the {{Code|phidgetwebservice}} script in {{Code|init.d}}, as you can see from reading the code above, but if you want to change them a lot, you can edit the configuration file rather than changing the {{Code|phidgetwebservice}} script and re-installing by {{Code|insserv}} every time. The configuration file in {{Code|/etc/default/}} should contain the same syntax as that used in the script source above:

<div class="source">
<syntaxhighlight lang=bash>
pws_port="5001"
pws_serverid=""
pws_password=""
</syntaxhighlight>
</div>

===Cross-Compiling with a Custom Toolchain===

This would allow you to have the Phidget libraries compiled to include in code for an embedded device. When developing for an embedded device, you will often write code for it on your 'normal' computer, and then build the code to binary with a different target than the processor in your computer. Many microcontrollers do not have the ability to run a full operating system, and hence cannot compile code natively.

The collection of tools used to create binary code for a separate system is called a ''toolchain''. Compiling the Phidget libraries specifically for an embedded system, and placing them into the path for writing code on top of the libraries is like adding another link in this chain.

You can use the typical {{Code|./configure}} setup for custom build targets:

<div class="source">
<syntaxhighlight lang=bash>
./configure --prefix=toolchain_location --build=this_system --host=target_system
</syntaxhighlight>
</div>

For the Phidget libraries, the {{Code|./configure}} tool works this way as well. You'd use this in the [[#Installing|install the libraries section]] setup. For example, let's say you're building the libraries to develop code for the [{{SERVER}}products.php?product_id=1072 Single Board Computer] as a target. Your system is a standard Linux system (i686-pc-linux-gnu) and the target system for the SBC is {{Code|arm-linux-gnueabi}}. For this target, you'll need the base of the GNU embedded Debian chain:

<div class="source">
<syntaxhighlight lang=bash>
sudo apt-get install gcc-arm-linux-gnueabi
</syntaxhighlight>
</div>

Then, download the Phidget libraries [[#Quick Downloads|above]] and unpack them into a folder {{Code|phidget_libraries}}. If {{Code|/usr/arm-linux-gnueabi}} is the location of your ARM toolchain (downloaded above in {{Code|gcc-arm-linux-gnueabi}}), type:

<div class="source">
<syntaxhighlight lang=bash>
~/phidget_libraries $> ./configure --prefix=/usr/arm-linux-gnueabi --build=i686-pc-linux-gnu --host=arm-linux-gnueabi
</syntaxhighlight>
</div>

===Linux on Non-Standard Systems===

We occasionally get requests to use Phidgets on Linux systems other than a standard laptop or desktop. One example is the new Raspberry Pi system. Often these systems include USB ports, so the combination makes sense.

Our libraries are installed by building from source, and their main dependency is the {{Code|libusb-dev}} library, so if you can get gcc on your machine (or set up a cross compiler for it) and you can also install the libusb-0.1 development headers, you can probably get Phidgets to work. Of course, we don't offer much support for these systems, so - depending on your system - expect to spend some raw time getting it up and going.

If you're new to the embedded computer thing, keep in mind that for these super basic systems, once you've gotten a power supply, and storage, and put the kernel you want on it, and then spent a couple of days of time getting things working, and more time getting your drivers going, costs add up pretty quickly. If you want a compact system that works right out of the box (and which can use all of our analog sensors in addition to our USB Phidgets), check out our [{{SERVER}}products.php?product_id=1072 Single Board Computer]. Our SBC:
* Has many more USB ports than super-stripped devices, and also has digital and analog ports
* Includes a power supply and can run on batteries easily
* Has a nice amount of RAM, a decent embedded processor, and built-in onboard storage (we've run R, GRASS, and X11 on it)
* Includes installed Debian, working Phidget drivers, and [[Phidget WebService|networked Phidget drivers]] from the moment it ships
* Has access to the full Debian repository including Python, Mono .NET, Ruby, and gcc
* Has a kernel development kit with patch file and instructions for adding new drivers (bluetooth, wireless, and so on)
* Comes with very in-depth documentation and technical support by phone and email
* Etc, etc.
The [[Phidget WebService|networked support]] in particular allows it to work with your cell phone and more.

But if you really do want a raw hobbyist system to tinker with, go for it! We're all nerds here - we've been there too and we certainly understand!

==Common Problems and Solutions==

{{ProblemSolution|Low Speed Phidgets (Max of 8)|Linux will only schedule one low-speed interrupt transfer per millisecond.}}

You can find out the type of your Phidget by attaching it and then running <code><font size=3>dmesg | tail</font></code>, which will display the type of Phidget from your kernel logs, as described above in the [[#Hardware|hardware section]]. The practical consequence of this is if your system has many low speed Phidgets attached, they will each be throttled down. Low speed Phidgets require an interrupt transfer as often as every 8 milliseconds. A Linux system could only have up to 8 of these Phidgets attached.

{{ProblemSolution|Sample Overrun Error|The data read from a program, or the first packet on the WebService, can give a sample overrun error (EEPHIDGET_OVERRUN).}}

Linux only polls data from the analog inputs on Phidgets when you ask it to. So there is some delay between when you open the device and when it actually attaches when data from those inputs are accumulating...and overrunning the buffer. This is simply in the nature of how Linux polls USB - we recommend catching (but ignoring) this one-time initial error.

Mechanical Relay Guide

2012-06-29T21:38:34Z

Cora: /* How it works */

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[File:1017.jpg|link=]]
| [[File:3051.jpg|250px|link=]]
|}

==Introduction==

Mechanical relays are devices that can turn on or turn off the power supplied to another device, like a switch. However, instead of having a person flip the switch, mechanical relays switch when provided with a small amount of power. This allows high-power circuits to be controlled by low-power devices.

They perform the same function as [[Solid State Relay Primer|Solid State Relays]], except they are less expensive and have a shorter lifespan.
You can use them to control [[LED Primer|LEDs]], heaters, appliances, and generally any powered device as long as the power you're switching falls within the limits of the relay you're using.

Phidgets sells boards with multiple relays on them, making it easy to control many separate circuits with your computer. Some boards plug straight into your USB port, while others are designed to connect to another device, such as an Interface Kit, or any device with enough [[Digital Output Primer|Digital Outputs]].

==How it works==

[[File:Mechanical_relay.jpg|thumb|link=|300px|'''Mechanical Relay'''<br />The switching arm and contacts of a [[#Single Pole, Double Throw (SPDT)|SPDT]] mechanical relay.]]

Mechanical relays use an electromagnetic coil to open or close the circuit. When current runs through the input and energizes the coil, it creates a small magnetic field which either pulls the arm of the switch away from the other contact of the switch, or pushes it down to close the switch depending on the how the switch is made. A relay also serves as an isolator, because the control (input) and load (output) ends of the relay are not electrically connected. This allows you to protect the device you're using to control the relay from power surges in your application.

===Basic Use===

Controlling a mechanical relay is as easy as turning on an LED or light bulb. By simply supplying enough power to energize the electromagnetic coil, you will be able to control a mechanical relay. A normal digital output will not be powerful enough without external components as described in the [[Digital Output Primer#Controlling a Relay with a N-Channel MOSFET| relay section of the Digital Output Primer]]. A Phidgets device with open collector digital outputs, (the ones you have to [{{SERVER}}/products.php?product_id=1012 provide power to]{{LinksNeeded||[[Digital Output Primer]]}}), on the other hand, will be able to control a relay on its own.
Relays are often used in large quantities to turn multiple devices on and off in a particular order or timing. For example, a popular trend has been to hook up many strands of Christmas lights to multiple relays and a control system in order to make them flash in rhythm with specific music.

Relays are designed to be controlled by a particular voltage applied to the coil. If you buy a relay product from Phidgets with integrated electronics, this is taken care of for you- you'll be able to switch the relays via USB or with any Phidgets device with enough [[Digital Output Primer|Digital Outputs]] (see table below), depending on which relay board you buy. If you are integrating your own relay, you'll want to keep an eye on the specifications. The relay coil is also specified for a particular current. For example, a 5V relay might require 70mA. If you connect this relay to a very weak source of 5V, like a digital output, the output will not be able to provide 70mA, and there will not be enough current to switch the relay.

(table: +mechanical_relay)

{|border=1
|+'''Mechanical Relays'''
! Phidgets Product #
! Connects to
! etc...
|-
| 1014_2 || USB || ...
|-
| 1017_1 || USB || ...
|-
| 3051_1 || Digital Output || ...
|}

The load side of the relay also requires a minimum current. This minimum load current (also called "wetting current") is a requirement because the electricity needs to conduct through an oxide layer that has formed on the contacts of the relay. If the minimum load current requirement of your relay is too high, you won't be able to use it to switch a signal (such as the data line on an analog sensor), you'll only be able to switch power to a circuit. If you're using a relay to switch a signal, [[#Contact Bounce|contact bounce]] might also be a problem.

====Switching Speed and High-Frequency Switching====

Even though they use moving mechanical parts, mechanical relays switch very quickly. The amount of time it takes for current to begin flowing through the circuit from when the relay's input is activated is in the order of tens of milliseconds. For extremely time-sensitive applications that need to minimize switching delay, [[Solid State Relay Primer|Solid State Relays]] can switch as quickly as 1ms.

You should be careful when using mechanical relays in applications that require very frequent switching. Typically, mechanical relays can only manage one contact every few seconds- any quicker and they may begin to overheat.

==Choosing a Relay==

Since mechanical relays are nothing more than a controllable switch, they support both AC and DC loads.

The major deciding factor in choosing a mechanical relay is the amount of current it's capable of switching.
For example, the most current you can switch with the largest mechanical relay we sell is 5A DC or 10A AC.
If the load you're switching consumes more current than our mechanical relays can handle, take a look at our [[Solid State Relay Primer|Solid State Relays]].

===Switch Type===

One of the major characteristics of a mechanical relay is the design of the switch inside. A switch can generally be defined by the number of '''poles''' and '''throws''' it has. The number of "poles" refers to the number of individual circuits the switch controls. The number of "throws" refers to the number of positions the switch arm can occupy.

[[File:Switch_types.jpg|border|300px|link=]]

====Single Pole, Single Throw (SPST)====

This is a simple switch with only one path for the current to follow. The relay is either designed to be '''normally open''' or '''normally closed'''. If it is normally open, the arm of the switch is held away from the contact with a spring when the relay is off and the electromagnet pulls the arm to make contact and close the switch when the relay is turned on. If it is normally closed, the arm of the switch is held to the contact when the relay is off, and the electromagnet pulls the arm away when the relay is turned on.

While the decision to use a normally opened or normally closed relay may seem arbitrary at first, it is actually very important for certain applications. If you choose a normally closed relay, it means your load will remain powered as long as the relay coil is '''not''' powered. If some other part of your system fails, causing your relay to lose power, your load will remain powered even though it should not be. For loads that are potentially dangerous when left on (such as a heater, or a high-power load) it is best to use a normally open relay, so that in the event of a system failure, the load will remain off. On the other hand, circuits that are designed to be powered most of the time but temporarily interrupted will use less power if they use a normally closed relay. An example of this type of circuit is the radio in a car: When the engine is started, the radio circuit is momentarily switched off because the engine needs a large amount of battery power to start.

====Single Pole, Double Throw (SPDT)====

[[File:relay2loads.png|thumb|link=|300px|'''Toggle Between Two Loads'''<br />By connecting the power supply to the common terminal, and connecting a different load to the other two terminals, a relay with a SPDT switch can be used to toggle power between the two loads.<br />[[Media:relay2loads.png|Full-size Image]]]]

This switch has two paths for the current to follow. This type of relay is useful if you want to toggle power between two different loads, as pictured. You can also use a SPDT relay as a single pole, single throw switch, and it can function as '''normally open''' or '''normally closed''' depending on which pins (common and normally open, or common and normally closed) you connect the load to.

<br clear="all">

====Double Pole, Single Throw (DPST)====

This switch functions like two SPST switches, but both switches are controlled by one coil. This type of switch is useful for keeping two loads on separate circuits while still being able to have them turn on and off in unison.

====Double Pole, Double Throw (DPDT)====

This switch functions the same as a SPDT switch, except there are two of them, but are both controlled by a single input on the relay. You can use this type of switch to simultaneously control two separate circuits.

==Troubleshooting==
===Contact Bounce===

As with any mechanical switch, relays are susceptible to [[Switch Primer#Bounce|contact bounce]]. This means that when the switch closes, the arm can bounce on the contact, causing the load's power to flicker slightly. This usually only matters when the application is triggered by pulses in the power signal, or for applications where meaningful data is being switched instead of power. For example, a circuit designed to increment a counter every time power is applied to its input could incorrectly interpret a bouncing relay contact as multiple switch events. Or, a circuit that uses a relay to switch an audio signal between two different paths will experience some static noise when switching if there is significant contact bounce. Check the [[Switch Primer|switch primer]] for information on how to deal with switch contact bounce. It's worth mentioning that [[Solid State Relay Primer|Solid State Relays]] don't suffer from contact bounce, because they operate without using moving mechanical parts.

===Arcing, Interference, and Sticking===

[[File:contact_arc.jpg|border|link=]]

When a mechanical relay opens or closes, for the moment that the arm of the switch is very close (but not connected) to the contact, the electric current can arc through the air between the contacts.
This arc can cause interference with nearby electrical instruments and sensors. For example, if an unshielded cable carrying an audio signal is travelling past some relays whose contacts are arcing when they switch, the audio would contain bursts of static noise.

This arcing can also heat up the contacts of the switch enough that they can slowly degrade away until the relay no longer functions. They could also weld together, causing the relay to stay on permanently, which means your load will be powered constantly. If this imposes safety concerns, you should install a fail-safe of some kind. For example, some sauna heaters are turned on with a mechanical relay. In the event of a relay failure, the sauna heater will remain on and continue heating the room beyond the intended temperature. However, a simple mechanical temperature sensor is installed which cuts power to the heater if the room goes beyond a certain temperature.

Some relays are encased in a clear plastic enclosure (sometimes called "ice cube" relays), so the switch contacts can be easily inspected. By inspecting the contacts periodically, you could tell when the relay is getting near the end of its life.

===Prolonging Relay Lifespan===

In order to prolong the lifespan of your relay, avoid switching loads of higher voltage or current than the relay is built for, and avoid highly inductive loads, which worsen the effects of contact arcing. Your Load will probably be inductive if it is built around a large coil of wire - motors and transformers are typical examples. A load considered resistive may also have loops of wire - for instance, hair dryers, toasters, incandescent bulbs use twisted wire elements to generate the heat. An inductive load will have thousands of loops of wire - it's a matter of scale.

Additionally, you should avoid switching at or near the relay's maximum frequency if possible. You can think of a mechanical relay's lifespan in terms of number times switched rather than the amount of time it's used for. A relay that doesn't need to be switched very often can last a long time. If your application requires constant switching over long periods of time, it might be more cost-effective to use a [[Solid State Relay Primer|Solid State Relay]].

====Arc Suppression ====

[[File:Mechanical_relay_diode.jpg|link=|thumb|300px|'''DC Load Protection'''<br/>A diagram of a mechanical relay switching a DC load. An optional diode and fuse are used to protect the relay and prevent hardware damaged caused by improper wiring.<br/>[[Media:Mechanical_relay_diode.jpg|Full-sized Image]]]]
[[File:Mechanical_relay_mov.jpg|link=|thumb|300px|'''AC Load Protection'''<br/>A diagram of a mechanical relay switching an AC load. An optional MOV or Transil diode is placed in parallel to protect the relay from voltage spikes.<br/>[[Media:Mechanical_relay_mov.jpg|Full-Sized Image]]]]
The main cause of failure for mechanical relays is electricity arcing across the contacts during switching. To lengthen the lifespan of your relay, you can add various circuit elements that mitigate arcing.

For DC powered applications, one simple method of mitigating the effects of contact arcing is to place a feedback diode across the load, as pictured. This will allow some of the residual electricity in the circuit to recirculate through the load instead of contributing to the arc that forms when the switch makes the transition from closed to open. You can buy a suitable diode from any electronics distributor, like this [http://parts.digikey.com/1/parts/1850825-diode-std-rec-10a-100v-r-6-10a02-t.html Diode] from Digikey.

For AC powered applications, you can put a Metal Oxide Varistor (MOV) across the load terminals of the relay in order to protect it from voltage spikes. An MOV will not remove the entire arc, but it will be helpful in circuits up to several hundred volts. You can buy an MOV from any electronics distributor, like this [http://parts.digikey.com/1/parts/714083-varistor-thermal-200v-10ka-20mm-tmov20rp200e.html MOV] from Digikey.

For low-voltage AC applications, a bi-directional transient voltage suppression diode ("transil diode") that is rated for higher than the AC voltage of the circuit can be placed across the relay terminals in order to protect it from voltage spikes. You can buy one from any electronics distributor, like this [http://parts.digikey.com/1/parts/718140-transil-600w-47v-bidir-do-15-p6ke47carl.html Transil Diode] from Digikey.

<br clear="all">

==Conclusion==

Mechanical relays are inexpensive and simple devices that allow AC or DC circuits to be switched on and off using a small amount of power.
They come in a variety of switch formats, enabling the user to build some very clever control into a circuit. Phidgets Inc. sells boards with multiple relays that can be connected directly to USB, so they can be controlled by your program.

Contact arcing and switch bounce can be an obstacle for some applications, but both are common problems and can be worked around fairly easily.
Mechanical relays don't last as long as solid state relays, but if you take care of them, they can be a good cost-effective alternative.

==Products in this Category==

* [[1014_2 - PhidgetInterfaceKit 0/0/4]]
* [[1017_1 - PhidgetInterfaceKit 0/0/8]]
* [[3051_1 - Dual Relay Board]]

==Glossary==

===Switch Type===
* SPST - either normally open or normally closed. Simple on/off switch.
* SPDT - 3 pins, has both a NO and NC pin and can function like a SPST switch of either type, or can be used to toggle power between two different loads.
* DPDT - Same as SPDT but there are two controlled by the same relay input. Useful for controlling 2 seperate circuits in a synchronized manner.
* Potential selection criteria for specific switching circuits.

===Contact Arcing===
* As the switch moves from the "on" position to the "off" position (and vice-versa) there is a moment when the arm of the switch in close enough to the contact that electricity will arc through the air, creating lots of heat and possibly damaging the contact. (Diagram would be useful)
* Arcing can lead to sticking, where the switch welds itself closed. If your relay is always on, it might be stuck.
* Arcing will be more severe with higher power loads or highly inductive loads.
* Arcing is expected, but can be mitigated by:
** For DC, feedback diode across load
** For AC, Snubber circuit or
** MOV or
** TVS

===Switching Speed===
* Lifespan of relay is measured in number of contacts, not time in use. Faster switching -> shorter life.
* Switching is audible - you can hear the switching, which might be annoying / undesirable, or it might be good as a confirmation the system is operating.
* Switching speed is limited by heating in the contacts - the arcing generates heat, and switching high loads faster than the rated switching speed will cause the relay to overheat.

===Operating Time===
* Time it takes for the arm of the switch to connect with the contact after being activated
* If 10ms is too slow, look at SSRs

===Control Voltage===
* Can be controlled via digital output
* Relay offers isolation between load circuit and control circuit

===Maximum (AC/DC) Switching Voltage===
* Secondary selection criteria.

===Maximum (AC/DC) Switching Current===
* Main selection criteria.
* If they need to switch more than 5A DC, or 10A AC, go to SSRs
* Inductive loads- does the same multiplier apply as for SSRs?

===Minimum Switching Current===
* A certain amount of current is needed on the LOAD side of a relay.
* Oxide films build up on the contacts, so this minimum is required to conduct through them.
* This spec determines whether or not the relay can switch a signal instead of power.
** If you are switching a signal rather than power, contact bounce could be a problem.

Mechanical Relay Guide

2012-06-29T21:37:17Z

Cora: /* Basic Use */

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[File:1017.jpg|link=]]
| [[File:3051.jpg|250px|link=]]
|}

==Introduction==

Mechanical relays are devices that can turn on or turn off the power supplied to another device, like a switch. However, instead of having a person flip the switch, mechanical relays switch when provided with a small amount of power. This allows high-power circuits to be controlled by low-power devices.

They perform the same function as [[Solid State Relay Primer|Solid State Relays]], except they are less expensive and have a shorter lifespan.
You can use them to control [[LED Primer|LEDs]], heaters, appliances, and generally any powered device as long as the power you're switching falls within the limits of the relay you're using.

Phidgets sells boards with multiple relays on them, making it easy to control many separate circuits with your computer. Some boards plug straight into your USB port, while others are designed to connect to another device, such as an Interface Kit, or any device with enough [[Digital Output Primer|Digital Outputs]].

==How it works==

[[File:Mechanical_relay.jpg|thumb|link=|300px|'''Mechanical Relay'''<br />The switching arm and contacts of a [[#Single Pole, Double Throw (SPDT)|SPDT]] mechanical relay.]]

Mechanical relays use an electromagnetic coil to open or close the circuit. When current runs through the input and energizes the coil, it creates a small magnetic field which either pulls the arm of the switch away from the other contact of the switch, or pushes it down to close the switch depending on the how the switch is made. A relay also serves as an isolator, because the control (input) and load (output) ends of the relay are not electrically connected. This allows you to protect the device you're using to control the relay from power surges in your application.

===Basic Use===

Controlling a mechanical relay is as easy as turning on an LED or light bulb. By simply supplying enough power to energize the electromagnetic coil, you will be able to control a mechanical relay. A normal digital output will not be powerful enough without external components as described in the [[Digital Output Primer#Controlling a Relay with a N-Channel MOSFET| relay section of the Digital Output Primer]]. A Phidgets device with {{LinksNeeded|open collector digital outputs, (the ones you have to [{{SERVER}}/products.php?product_id=1012 provide power to]|[[Digital Output Primer]]}}, on the other hand, will be able to control a relay on its own.
Relays are often used in large quantities to turn multiple devices on and off in a particular order or timing. For example, a popular trend has been to hook up many strands of Christmas lights to multiple relays and a control system in order to make them flash in rhythm with specific music.

Relays are designed to be controlled by a particular voltage applied to the coil. If you buy a relay product from Phidgets with integrated electronics, this is taken care of for you- you'll be able to switch the relays via USB or with any Phidgets device with enough [[Digital Output Primer|Digital Outputs]] (see table below), depending on which relay board you buy. If you are integrating your own relay, you'll want to keep an eye on the specifications. The relay coil is also specified for a particular current. For example, a 5V relay might require 70mA. If you connect this relay to a very weak source of 5V, like a digital output, the output will not be able to provide 70mA, and there will not be enough current to switch the relay.

(table: +mechanical_relay)

{|border=1
|+'''Mechanical Relays'''
! Phidgets Product #
! Connects to
! etc...
|-
| 1014_2 || USB || ...
|-
| 1017_1 || USB || ...
|-
| 3051_1 || Digital Output || ...
|}

The load side of the relay also requires a minimum current. This minimum load current (also called "wetting current") is a requirement because the electricity needs to conduct through an oxide layer that has formed on the contacts of the relay. If the minimum load current requirement of your relay is too high, you won't be able to use it to switch a signal (such as the data line on an analog sensor), you'll only be able to switch power to a circuit. If you're using a relay to switch a signal, [[#Contact Bounce|contact bounce]] might also be a problem.

====Switching Speed and High-Frequency Switching====

Even though they use moving mechanical parts, mechanical relays switch very quickly. The amount of time it takes for current to begin flowing through the circuit from when the relay's input is activated is in the order of tens of milliseconds. For extremely time-sensitive applications that need to minimize switching delay, [[Solid State Relay Primer|Solid State Relays]] can switch as quickly as 1ms.

You should be careful when using mechanical relays in applications that require very frequent switching. Typically, mechanical relays can only manage one contact every few seconds- any quicker and they may begin to overheat.

==Choosing a Relay==

Since mechanical relays are nothing more than a controllable switch, they support both AC and DC loads.

The major deciding factor in choosing a mechanical relay is the amount of current it's capable of switching.
For example, the most current you can switch with the largest mechanical relay we sell is 5A DC or 10A AC.
If the load you're switching consumes more current than our mechanical relays can handle, take a look at our [[Solid State Relay Primer|Solid State Relays]].

===Switch Type===

One of the major characteristics of a mechanical relay is the design of the switch inside. A switch can generally be defined by the number of '''poles''' and '''throws''' it has. The number of "poles" refers to the number of individual circuits the switch controls. The number of "throws" refers to the number of positions the switch arm can occupy.

[[File:Switch_types.jpg|border|300px|link=]]

====Single Pole, Single Throw (SPST)====

This is a simple switch with only one path for the current to follow. The relay is either designed to be '''normally open''' or '''normally closed'''. If it is normally open, the arm of the switch is held away from the contact with a spring when the relay is off and the electromagnet pulls the arm to make contact and close the switch when the relay is turned on. If it is normally closed, the arm of the switch is held to the contact when the relay is off, and the electromagnet pulls the arm away when the relay is turned on.

While the decision to use a normally opened or normally closed relay may seem arbitrary at first, it is actually very important for certain applications. If you choose a normally closed relay, it means your load will remain powered as long as the relay coil is '''not''' powered. If some other part of your system fails, causing your relay to lose power, your load will remain powered even though it should not be. For loads that are potentially dangerous when left on (such as a heater, or a high-power load) it is best to use a normally open relay, so that in the event of a system failure, the load will remain off. On the other hand, circuits that are designed to be powered most of the time but temporarily interrupted will use less power if they use a normally closed relay. An example of this type of circuit is the radio in a car: When the engine is started, the radio circuit is momentarily switched off because the engine needs a large amount of battery power to start.

====Single Pole, Double Throw (SPDT)====

[[File:relay2loads.png|thumb|link=|300px|'''Toggle Between Two Loads'''<br />By connecting the power supply to the common terminal, and connecting a different load to the other two terminals, a relay with a SPDT switch can be used to toggle power between the two loads.<br />[[Media:relay2loads.png|Full-size Image]]]]

This switch has two paths for the current to follow. This type of relay is useful if you want to toggle power between two different loads, as pictured. You can also use a SPDT relay as a single pole, single throw switch, and it can function as '''normally open''' or '''normally closed''' depending on which pins (common and normally open, or common and normally closed) you connect the load to.

<br clear="all">

====Double Pole, Single Throw (DPST)====

This switch functions like two SPST switches, but both switches are controlled by one coil. This type of switch is useful for keeping two loads on separate circuits while still being able to have them turn on and off in unison.

====Double Pole, Double Throw (DPDT)====

This switch functions the same as a SPDT switch, except there are two of them, but are both controlled by a single input on the relay. You can use this type of switch to simultaneously control two separate circuits.

==Troubleshooting==
===Contact Bounce===

As with any mechanical switch, relays are susceptible to [[Switch Primer#Bounce|contact bounce]]. This means that when the switch closes, the arm can bounce on the contact, causing the load's power to flicker slightly. This usually only matters when the application is triggered by pulses in the power signal, or for applications where meaningful data is being switched instead of power. For example, a circuit designed to increment a counter every time power is applied to its input could incorrectly interpret a bouncing relay contact as multiple switch events. Or, a circuit that uses a relay to switch an audio signal between two different paths will experience some static noise when switching if there is significant contact bounce. Check the [[Switch Primer|switch primer]] for information on how to deal with switch contact bounce. It's worth mentioning that [[Solid State Relay Primer|Solid State Relays]] don't suffer from contact bounce, because they operate without using moving mechanical parts.

===Arcing, Interference, and Sticking===

[[File:contact_arc.jpg|border|link=]]

When a mechanical relay opens or closes, for the moment that the arm of the switch is very close (but not connected) to the contact, the electric current can arc through the air between the contacts.
This arc can cause interference with nearby electrical instruments and sensors. For example, if an unshielded cable carrying an audio signal is travelling past some relays whose contacts are arcing when they switch, the audio would contain bursts of static noise.

This arcing can also heat up the contacts of the switch enough that they can slowly degrade away until the relay no longer functions. They could also weld together, causing the relay to stay on permanently, which means your load will be powered constantly. If this imposes safety concerns, you should install a fail-safe of some kind. For example, some sauna heaters are turned on with a mechanical relay. In the event of a relay failure, the sauna heater will remain on and continue heating the room beyond the intended temperature. However, a simple mechanical temperature sensor is installed which cuts power to the heater if the room goes beyond a certain temperature.

Some relays are encased in a clear plastic enclosure (sometimes called "ice cube" relays), so the switch contacts can be easily inspected. By inspecting the contacts periodically, you could tell when the relay is getting near the end of its life.

===Prolonging Relay Lifespan===

In order to prolong the lifespan of your relay, avoid switching loads of higher voltage or current than the relay is built for, and avoid highly inductive loads, which worsen the effects of contact arcing. Your Load will probably be inductive if it is built around a large coil of wire - motors and transformers are typical examples. A load considered resistive may also have loops of wire - for instance, hair dryers, toasters, incandescent bulbs use twisted wire elements to generate the heat. An inductive load will have thousands of loops of wire - it's a matter of scale.

Additionally, you should avoid switching at or near the relay's maximum frequency if possible. You can think of a mechanical relay's lifespan in terms of number times switched rather than the amount of time it's used for. A relay that doesn't need to be switched very often can last a long time. If your application requires constant switching over long periods of time, it might be more cost-effective to use a [[Solid State Relay Primer|Solid State Relay]].

====Arc Suppression ====

[[File:Mechanical_relay_diode.jpg|link=|thumb|300px|'''DC Load Protection'''<br/>A diagram of a mechanical relay switching a DC load. An optional diode and fuse are used to protect the relay and prevent hardware damaged caused by improper wiring.<br/>[[Media:Mechanical_relay_diode.jpg|Full-sized Image]]]]
[[File:Mechanical_relay_mov.jpg|link=|thumb|300px|'''AC Load Protection'''<br/>A diagram of a mechanical relay switching an AC load. An optional MOV or Transil diode is placed in parallel to protect the relay from voltage spikes.<br/>[[Media:Mechanical_relay_mov.jpg|Full-Sized Image]]]]
The main cause of failure for mechanical relays is electricity arcing across the contacts during switching. To lengthen the lifespan of your relay, you can add various circuit elements that mitigate arcing.

For DC powered applications, one simple method of mitigating the effects of contact arcing is to place a feedback diode across the load, as pictured. This will allow some of the residual electricity in the circuit to recirculate through the load instead of contributing to the arc that forms when the switch makes the transition from closed to open. You can buy a suitable diode from any electronics distributor, like this [http://parts.digikey.com/1/parts/1850825-diode-std-rec-10a-100v-r-6-10a02-t.html Diode] from Digikey.

For AC powered applications, you can put a Metal Oxide Varistor (MOV) across the load terminals of the relay in order to protect it from voltage spikes. An MOV will not remove the entire arc, but it will be helpful in circuits up to several hundred volts. You can buy an MOV from any electronics distributor, like this [http://parts.digikey.com/1/parts/714083-varistor-thermal-200v-10ka-20mm-tmov20rp200e.html MOV] from Digikey.

For low-voltage AC applications, a bi-directional transient voltage suppression diode ("transil diode") that is rated for higher than the AC voltage of the circuit can be placed across the relay terminals in order to protect it from voltage spikes. You can buy one from any electronics distributor, like this [http://parts.digikey.com/1/parts/718140-transil-600w-47v-bidir-do-15-p6ke47carl.html Transil Diode] from Digikey.

<br clear="all">

==Conclusion==

Mechanical relays are inexpensive and simple devices that allow AC or DC circuits to be switched on and off using a small amount of power.
They come in a variety of switch formats, enabling the user to build some very clever control into a circuit. Phidgets Inc. sells boards with multiple relays that can be connected directly to USB, so they can be controlled by your program.

Contact arcing and switch bounce can be an obstacle for some applications, but both are common problems and can be worked around fairly easily.
Mechanical relays don't last as long as solid state relays, but if you take care of them, they can be a good cost-effective alternative.

==Products in this Category==

* [[1014_2 - PhidgetInterfaceKit 0/0/4]]
* [[1017_1 - PhidgetInterfaceKit 0/0/8]]
* [[3051_1 - Dual Relay Board]]

==Glossary==

===Switch Type===
* SPST - either normally open or normally closed. Simple on/off switch.
* SPDT - 3 pins, has both a NO and NC pin and can function like a SPST switch of either type, or can be used to toggle power between two different loads.
* DPDT - Same as SPDT but there are two controlled by the same relay input. Useful for controlling 2 seperate circuits in a synchronized manner.
* Potential selection criteria for specific switching circuits.

===Contact Arcing===
* As the switch moves from the "on" position to the "off" position (and vice-versa) there is a moment when the arm of the switch in close enough to the contact that electricity will arc through the air, creating lots of heat and possibly damaging the contact. (Diagram would be useful)
* Arcing can lead to sticking, where the switch welds itself closed. If your relay is always on, it might be stuck.
* Arcing will be more severe with higher power loads or highly inductive loads.
* Arcing is expected, but can be mitigated by:
** For DC, feedback diode across load
** For AC, Snubber circuit or
** MOV or
** TVS

===Switching Speed===
* Lifespan of relay is measured in number of contacts, not time in use. Faster switching -> shorter life.
* Switching is audible - you can hear the switching, which might be annoying / undesirable, or it might be good as a confirmation the system is operating.
* Switching speed is limited by heating in the contacts - the arcing generates heat, and switching high loads faster than the rated switching speed will cause the relay to overheat.

===Operating Time===
* Time it takes for the arm of the switch to connect with the contact after being activated
* If 10ms is too slow, look at SSRs

===Control Voltage===
* Can be controlled via digital output
* Relay offers isolation between load circuit and control circuit

===Maximum (AC/DC) Switching Voltage===
* Secondary selection criteria.

===Maximum (AC/DC) Switching Current===
* Main selection criteria.
* If they need to switch more than 5A DC, or 10A AC, go to SSRs
* Inductive loads- does the same multiplier apply as for SSRs?

===Minimum Switching Current===
* A certain amount of current is needed on the LOAD side of a relay.
* Oxide films build up on the contacts, so this minimum is required to conduct through them.
* This spec determines whether or not the relay can switch a signal instead of power.
** If you are switching a signal rather than power, contact bounce could be a problem.

Mechanical Relay Guide

2012-06-29T21:36:45Z

Cora: /* How it works */

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[File:1017.jpg|link=]]
| [[File:3051.jpg|250px|link=]]
|}

==Introduction==

Mechanical relays are devices that can turn on or turn off the power supplied to another device, like a switch. However, instead of having a person flip the switch, mechanical relays switch when provided with a small amount of power. This allows high-power circuits to be controlled by low-power devices.

They perform the same function as [[Solid State Relay Primer|Solid State Relays]], except they are less expensive and have a shorter lifespan.
You can use them to control [[LED Primer|LEDs]], heaters, appliances, and generally any powered device as long as the power you're switching falls within the limits of the relay you're using.

Phidgets sells boards with multiple relays on them, making it easy to control many separate circuits with your computer. Some boards plug straight into your USB port, while others are designed to connect to another device, such as an Interface Kit, or any device with enough [[Digital Output Primer|Digital Outputs]].

==How it works==

[[File:Mechanical_relay.jpg|thumb|link=|300px|'''Mechanical Relay'''<br />The switching arm and contacts of a [[#Single Pole, Double Throw (SPDT)|SPDT]] mechanical relay.]]

Mechanical relays use an electromagnetic coil to open or close the circuit. When current runs through the input and energizes the coil, it creates a small magnetic field which either pulls the arm of the switch away from the other contact of the switch, or pushes it down to close the switch depending on the how the switch is made. A relay also serves as an isolator, because the control (input) and load (output) ends of the relay are not electrically connected. This allows you to protect the device you're using to control the relay from power surges in your application.

===Basic Use===

Controlling a mechanical relay is as easy as turning on an LED or light bulb. By simply supplying enough power to energize the electromagnetic coil, you will be able to control a mechanical relay. A normal digital output will not be powerful enough without external components as described in the [[Digital Output Primer#Controlling a Relay with a N-Channel MOSFET| relay section of the Digital Output Primer]]. A Phidgets device with {{LinksNeeded|open collector digital outputs, (the ones you have to [{{SERVER}}/products.php?product_id=1012 provide power to]|[[Open Collector Digital Output Primer|Open Collector Digital Outputs]]}}, on the other hand, will be able to control a relay on its own.
Relays are often used in large quantities to turn multiple devices on and off in a particular order or timing. For example, a popular trend has been to hook up many strands of Christmas lights to multiple relays and a control system in order to make them flash in rhythm with specific music.

Relays are designed to be controlled by a particular voltage applied to the coil. If you buy a relay product from Phidgets with integrated electronics, this is taken care of for you- you'll be able to switch the relays via USB or with any Phidgets device with enough [[Digital Output Primer|Digital Outputs]] (see table below), depending on which relay board you buy. If you are integrating your own relay, you'll want to keep an eye on the specifications. The relay coil is also specified for a particular current. For example, a 5V relay might require 70mA. If you connect this relay to a very weak source of 5V, like a digital output, the output will not be able to provide 70mA, and there will not be enough current to switch the relay.

(table: +mechanical_relay)

{|border=1
|+'''Mechanical Relays'''
! Phidgets Product #
! Connects to
! etc...
|-
| 1014_2 || USB || ...
|-
| 1017_1 || USB || ...
|-
| 3051_1 || Digital Output || ...
|}

The load side of the relay also requires a minimum current. This minimum load current (also called "wetting current") is a requirement because the electricity needs to conduct through an oxide layer that has formed on the contacts of the relay. If the minimum load current requirement of your relay is too high, you won't be able to use it to switch a signal (such as the data line on an analog sensor), you'll only be able to switch power to a circuit. If you're using a relay to switch a signal, [[#Contact Bounce|contact bounce]] might also be a problem.

====Switching Speed and High-Frequency Switching====

Even though they use moving mechanical parts, mechanical relays switch very quickly. The amount of time it takes for current to begin flowing through the circuit from when the relay's input is activated is in the order of tens of milliseconds. For extremely time-sensitive applications that need to minimize switching delay, [[Solid State Relay Primer|Solid State Relays]] can switch as quickly as 1ms.

You should be careful when using mechanical relays in applications that require very frequent switching. Typically, mechanical relays can only manage one contact every few seconds- any quicker and they may begin to overheat.

==Choosing a Relay==

Since mechanical relays are nothing more than a controllable switch, they support both AC and DC loads.

The major deciding factor in choosing a mechanical relay is the amount of current it's capable of switching.
For example, the most current you can switch with the largest mechanical relay we sell is 5A DC or 10A AC.
If the load you're switching consumes more current than our mechanical relays can handle, take a look at our [[Solid State Relay Primer|Solid State Relays]].

===Switch Type===

One of the major characteristics of a mechanical relay is the design of the switch inside. A switch can generally be defined by the number of '''poles''' and '''throws''' it has. The number of "poles" refers to the number of individual circuits the switch controls. The number of "throws" refers to the number of positions the switch arm can occupy.

[[File:Switch_types.jpg|border|300px|link=]]

====Single Pole, Single Throw (SPST)====

This is a simple switch with only one path for the current to follow. The relay is either designed to be '''normally open''' or '''normally closed'''. If it is normally open, the arm of the switch is held away from the contact with a spring when the relay is off and the electromagnet pulls the arm to make contact and close the switch when the relay is turned on. If it is normally closed, the arm of the switch is held to the contact when the relay is off, and the electromagnet pulls the arm away when the relay is turned on.

While the decision to use a normally opened or normally closed relay may seem arbitrary at first, it is actually very important for certain applications. If you choose a normally closed relay, it means your load will remain powered as long as the relay coil is '''not''' powered. If some other part of your system fails, causing your relay to lose power, your load will remain powered even though it should not be. For loads that are potentially dangerous when left on (such as a heater, or a high-power load) it is best to use a normally open relay, so that in the event of a system failure, the load will remain off. On the other hand, circuits that are designed to be powered most of the time but temporarily interrupted will use less power if they use a normally closed relay. An example of this type of circuit is the radio in a car: When the engine is started, the radio circuit is momentarily switched off because the engine needs a large amount of battery power to start.

====Single Pole, Double Throw (SPDT)====

[[File:relay2loads.png|thumb|link=|300px|'''Toggle Between Two Loads'''<br />By connecting the power supply to the common terminal, and connecting a different load to the other two terminals, a relay with a SPDT switch can be used to toggle power between the two loads.<br />[[Media:relay2loads.png|Full-size Image]]]]

This switch has two paths for the current to follow. This type of relay is useful if you want to toggle power between two different loads, as pictured. You can also use a SPDT relay as a single pole, single throw switch, and it can function as '''normally open''' or '''normally closed''' depending on which pins (common and normally open, or common and normally closed) you connect the load to.

<br clear="all">

====Double Pole, Single Throw (DPST)====

This switch functions like two SPST switches, but both switches are controlled by one coil. This type of switch is useful for keeping two loads on separate circuits while still being able to have them turn on and off in unison.

====Double Pole, Double Throw (DPDT)====

This switch functions the same as a SPDT switch, except there are two of them, but are both controlled by a single input on the relay. You can use this type of switch to simultaneously control two separate circuits.

==Troubleshooting==
===Contact Bounce===

As with any mechanical switch, relays are susceptible to [[Switch Primer#Bounce|contact bounce]]. This means that when the switch closes, the arm can bounce on the contact, causing the load's power to flicker slightly. This usually only matters when the application is triggered by pulses in the power signal, or for applications where meaningful data is being switched instead of power. For example, a circuit designed to increment a counter every time power is applied to its input could incorrectly interpret a bouncing relay contact as multiple switch events. Or, a circuit that uses a relay to switch an audio signal between two different paths will experience some static noise when switching if there is significant contact bounce. Check the [[Switch Primer|switch primer]] for information on how to deal with switch contact bounce. It's worth mentioning that [[Solid State Relay Primer|Solid State Relays]] don't suffer from contact bounce, because they operate without using moving mechanical parts.

===Arcing, Interference, and Sticking===

[[File:contact_arc.jpg|border|link=]]

When a mechanical relay opens or closes, for the moment that the arm of the switch is very close (but not connected) to the contact, the electric current can arc through the air between the contacts.
This arc can cause interference with nearby electrical instruments and sensors. For example, if an unshielded cable carrying an audio signal is travelling past some relays whose contacts are arcing when they switch, the audio would contain bursts of static noise.

This arcing can also heat up the contacts of the switch enough that they can slowly degrade away until the relay no longer functions. They could also weld together, causing the relay to stay on permanently, which means your load will be powered constantly. If this imposes safety concerns, you should install a fail-safe of some kind. For example, some sauna heaters are turned on with a mechanical relay. In the event of a relay failure, the sauna heater will remain on and continue heating the room beyond the intended temperature. However, a simple mechanical temperature sensor is installed which cuts power to the heater if the room goes beyond a certain temperature.

Some relays are encased in a clear plastic enclosure (sometimes called "ice cube" relays), so the switch contacts can be easily inspected. By inspecting the contacts periodically, you could tell when the relay is getting near the end of its life.

===Prolonging Relay Lifespan===

In order to prolong the lifespan of your relay, avoid switching loads of higher voltage or current than the relay is built for, and avoid highly inductive loads, which worsen the effects of contact arcing. Your Load will probably be inductive if it is built around a large coil of wire - motors and transformers are typical examples. A load considered resistive may also have loops of wire - for instance, hair dryers, toasters, incandescent bulbs use twisted wire elements to generate the heat. An inductive load will have thousands of loops of wire - it's a matter of scale.

Additionally, you should avoid switching at or near the relay's maximum frequency if possible. You can think of a mechanical relay's lifespan in terms of number times switched rather than the amount of time it's used for. A relay that doesn't need to be switched very often can last a long time. If your application requires constant switching over long periods of time, it might be more cost-effective to use a [[Solid State Relay Primer|Solid State Relay]].

====Arc Suppression ====

[[File:Mechanical_relay_diode.jpg|link=|thumb|300px|'''DC Load Protection'''<br/>A diagram of a mechanical relay switching a DC load. An optional diode and fuse are used to protect the relay and prevent hardware damaged caused by improper wiring.<br/>[[Media:Mechanical_relay_diode.jpg|Full-sized Image]]]]
[[File:Mechanical_relay_mov.jpg|link=|thumb|300px|'''AC Load Protection'''<br/>A diagram of a mechanical relay switching an AC load. An optional MOV or Transil diode is placed in parallel to protect the relay from voltage spikes.<br/>[[Media:Mechanical_relay_mov.jpg|Full-Sized Image]]]]
The main cause of failure for mechanical relays is electricity arcing across the contacts during switching. To lengthen the lifespan of your relay, you can add various circuit elements that mitigate arcing.

For DC powered applications, one simple method of mitigating the effects of contact arcing is to place a feedback diode across the load, as pictured. This will allow some of the residual electricity in the circuit to recirculate through the load instead of contributing to the arc that forms when the switch makes the transition from closed to open. You can buy a suitable diode from any electronics distributor, like this [http://parts.digikey.com/1/parts/1850825-diode-std-rec-10a-100v-r-6-10a02-t.html Diode] from Digikey.

For AC powered applications, you can put a Metal Oxide Varistor (MOV) across the load terminals of the relay in order to protect it from voltage spikes. An MOV will not remove the entire arc, but it will be helpful in circuits up to several hundred volts. You can buy an MOV from any electronics distributor, like this [http://parts.digikey.com/1/parts/714083-varistor-thermal-200v-10ka-20mm-tmov20rp200e.html MOV] from Digikey.

For low-voltage AC applications, a bi-directional transient voltage suppression diode ("transil diode") that is rated for higher than the AC voltage of the circuit can be placed across the relay terminals in order to protect it from voltage spikes. You can buy one from any electronics distributor, like this [http://parts.digikey.com/1/parts/718140-transil-600w-47v-bidir-do-15-p6ke47carl.html Transil Diode] from Digikey.

<br clear="all">

==Conclusion==

Mechanical relays are inexpensive and simple devices that allow AC or DC circuits to be switched on and off using a small amount of power.
They come in a variety of switch formats, enabling the user to build some very clever control into a circuit. Phidgets Inc. sells boards with multiple relays that can be connected directly to USB, so they can be controlled by your program.

Contact arcing and switch bounce can be an obstacle for some applications, but both are common problems and can be worked around fairly easily.
Mechanical relays don't last as long as solid state relays, but if you take care of them, they can be a good cost-effective alternative.

==Products in this Category==

* [[1014_2 - PhidgetInterfaceKit 0/0/4]]
* [[1017_1 - PhidgetInterfaceKit 0/0/8]]
* [[3051_1 - Dual Relay Board]]

==Glossary==

===Switch Type===
* SPST - either normally open or normally closed. Simple on/off switch.
* SPDT - 3 pins, has both a NO and NC pin and can function like a SPST switch of either type, or can be used to toggle power between two different loads.
* DPDT - Same as SPDT but there are two controlled by the same relay input. Useful for controlling 2 seperate circuits in a synchronized manner.
* Potential selection criteria for specific switching circuits.

===Contact Arcing===
* As the switch moves from the "on" position to the "off" position (and vice-versa) there is a moment when the arm of the switch in close enough to the contact that electricity will arc through the air, creating lots of heat and possibly damaging the contact. (Diagram would be useful)
* Arcing can lead to sticking, where the switch welds itself closed. If your relay is always on, it might be stuck.
* Arcing will be more severe with higher power loads or highly inductive loads.
* Arcing is expected, but can be mitigated by:
** For DC, feedback diode across load
** For AC, Snubber circuit or
** MOV or
** TVS

===Switching Speed===
* Lifespan of relay is measured in number of contacts, not time in use. Faster switching -> shorter life.
* Switching is audible - you can hear the switching, which might be annoying / undesirable, or it might be good as a confirmation the system is operating.
* Switching speed is limited by heating in the contacts - the arcing generates heat, and switching high loads faster than the rated switching speed will cause the relay to overheat.

===Operating Time===
* Time it takes for the arm of the switch to connect with the contact after being activated
* If 10ms is too slow, look at SSRs

===Control Voltage===
* Can be controlled via digital output
* Relay offers isolation between load circuit and control circuit

===Maximum (AC/DC) Switching Voltage===
* Secondary selection criteria.

===Maximum (AC/DC) Switching Current===
* Main selection criteria.
* If they need to switch more than 5A DC, or 10A AC, go to SSRs
* Inductive loads- does the same multiplier apply as for SSRs?

===Minimum Switching Current===
* A certain amount of current is needed on the LOAD side of a relay.
* Oxide films build up on the contacts, so this minimum is required to conduct through them.
* This spec determines whether or not the relay can switch a signal instead of power.
** If you are switching a signal rather than power, contact bounce could be a problem.

Mechanical Relay Guide

2012-06-29T21:35:40Z

Cora:

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[File:1017.jpg|link=]]
| [[File:3051.jpg|250px|link=]]
|}

==Introduction==

Mechanical relays are devices that can turn on or turn off the power supplied to another device, like a switch. However, instead of having a person flip the switch, mechanical relays switch when provided with a small amount of power. This allows high-power circuits to be controlled by low-power devices.

They perform the same function as [[Solid State Relay Primer|Solid State Relays]], except they are less expensive and have a shorter lifespan.
You can use them to control [[LED Primer|LEDs]], heaters, appliances, and generally any powered device as long as the power you're switching falls within the limits of the relay you're using.

Phidgets sells boards with multiple relays on them, making it easy to control many separate circuits with your computer. Some boards plug straight into your USB port, while others are designed to connect to another device, such as an Interface Kit, or any device with enough [[Digital Output Primer|Digital Outputs]].

==How it works==

[[File:Mechanical_relay.jpg|thumb|link=|300px|'''Mechanical Relay'''<br />The switching arm and contacts of a [[#Single Pole, Double Throw (SPDT)|SPDT]] mechanical relay.]]

Mechanical relays use an electromagnetic coil to open or close the circuit. When current runs through the input and energizes the coil, it creates a small magnetic field which either pulls the arm of the switch away from the other contact of the switch, or pushes it down to close the switch depending on the how the switch is made. A relay also serves as an isolator, because the control (input) and load (output) ends of the relay are not electrically connected. This allows you to protect the device you're using to control the relay from power surges in your application.

===Basic Use===

Controlling a mechanical relay is as easy as turning on an LED or light bulb. By simply supplying enough power to energize the electromagnetic coil, you will be able to control a mechanical relay. A normal digital output will not be powerful enough without external components as described in the [[Digital Output Primer#Controlling a Relay with a N-Channel MOSFET| relay section of the Digital Output Primer]]. A Phidgets device with {{LinksNeeded|open collector digital outputs, the ones you have to provide power to|[[Open Collector Digital Output Primer|Open Collector Digital Outputs]]}}, on the other hand, will be able to control a relay on its own.
Relays are often used in large quantities to turn multiple devices on and off in a particular order or timing. For example, a popular trend has been to hook up many strands of Christmas lights to multiple relays and a control system in order to make them flash in rhythm with specific music.

Relays are designed to be controlled by a particular voltage applied to the coil. If you buy a relay product from Phidgets with integrated electronics, this is taken care of for you- you'll be able to switch the relays via USB or with any Phidgets device with enough [[Digital Output Primer|Digital Outputs]] (see table below), depending on which relay board you buy. If you are integrating your own relay, you'll want to keep an eye on the specifications. The relay coil is also specified for a particular current. For example, a 5V relay might require 70mA. If you connect this relay to a very weak source of 5V, like a digital output, the output will not be able to provide 70mA, and there will not be enough current to switch the relay.

(table: +mechanical_relay)

{|border=1
|+'''Mechanical Relays'''
! Phidgets Product #
! Connects to
! etc...
|-
| 1014_2 || USB || ...
|-
| 1017_1 || USB || ...
|-
| 3051_1 || Digital Output || ...
|}

The load side of the relay also requires a minimum current. This minimum load current (also called "wetting current") is a requirement because the electricity needs to conduct through an oxide layer that has formed on the contacts of the relay. If the minimum load current requirement of your relay is too high, you won't be able to use it to switch a signal (such as the data line on an analog sensor), you'll only be able to switch power to a circuit. If you're using a relay to switch a signal, [[#Contact Bounce|contact bounce]] might also be a problem.

====Switching Speed and High-Frequency Switching====

Even though they use moving mechanical parts, mechanical relays switch very quickly. The amount of time it takes for current to begin flowing through the circuit from when the relay's input is activated is in the order of tens of milliseconds. For extremely time-sensitive applications that need to minimize switching delay, [[Solid State Relay Primer|Solid State Relays]] can switch as quickly as 1ms.

You should be careful when using mechanical relays in applications that require very frequent switching. Typically, mechanical relays can only manage one contact every few seconds- any quicker and they may begin to overheat.

==Choosing a Relay==

Since mechanical relays are nothing more than a controllable switch, they support both AC and DC loads.

The major deciding factor in choosing a mechanical relay is the amount of current it's capable of switching.
For example, the most current you can switch with the largest mechanical relay we sell is 5A DC or 10A AC.
If the load you're switching consumes more current than our mechanical relays can handle, take a look at our [[Solid State Relay Primer|Solid State Relays]].

===Switch Type===

One of the major characteristics of a mechanical relay is the design of the switch inside. A switch can generally be defined by the number of '''poles''' and '''throws''' it has. The number of "poles" refers to the number of individual circuits the switch controls. The number of "throws" refers to the number of positions the switch arm can occupy.

[[File:Switch_types.jpg|border|300px|link=]]

====Single Pole, Single Throw (SPST)====

This is a simple switch with only one path for the current to follow. The relay is either designed to be '''normally open''' or '''normally closed'''. If it is normally open, the arm of the switch is held away from the contact with a spring when the relay is off and the electromagnet pulls the arm to make contact and close the switch when the relay is turned on. If it is normally closed, the arm of the switch is held to the contact when the relay is off, and the electromagnet pulls the arm away when the relay is turned on.

While the decision to use a normally opened or normally closed relay may seem arbitrary at first, it is actually very important for certain applications. If you choose a normally closed relay, it means your load will remain powered as long as the relay coil is '''not''' powered. If some other part of your system fails, causing your relay to lose power, your load will remain powered even though it should not be. For loads that are potentially dangerous when left on (such as a heater, or a high-power load) it is best to use a normally open relay, so that in the event of a system failure, the load will remain off. On the other hand, circuits that are designed to be powered most of the time but temporarily interrupted will use less power if they use a normally closed relay. An example of this type of circuit is the radio in a car: When the engine is started, the radio circuit is momentarily switched off because the engine needs a large amount of battery power to start.

====Single Pole, Double Throw (SPDT)====

[[File:relay2loads.png|thumb|link=|300px|'''Toggle Between Two Loads'''<br />By connecting the power supply to the common terminal, and connecting a different load to the other two terminals, a relay with a SPDT switch can be used to toggle power between the two loads.<br />[[Media:relay2loads.png|Full-size Image]]]]

This switch has two paths for the current to follow. This type of relay is useful if you want to toggle power between two different loads, as pictured. You can also use a SPDT relay as a single pole, single throw switch, and it can function as '''normally open''' or '''normally closed''' depending on which pins (common and normally open, or common and normally closed) you connect the load to.

<br clear="all">

====Double Pole, Single Throw (DPST)====

This switch functions like two SPST switches, but both switches are controlled by one coil. This type of switch is useful for keeping two loads on separate circuits while still being able to have them turn on and off in unison.

====Double Pole, Double Throw (DPDT)====

This switch functions the same as a SPDT switch, except there are two of them, but are both controlled by a single input on the relay. You can use this type of switch to simultaneously control two separate circuits.

==Troubleshooting==
===Contact Bounce===

As with any mechanical switch, relays are susceptible to [[Switch Primer#Bounce|contact bounce]]. This means that when the switch closes, the arm can bounce on the contact, causing the load's power to flicker slightly. This usually only matters when the application is triggered by pulses in the power signal, or for applications where meaningful data is being switched instead of power. For example, a circuit designed to increment a counter every time power is applied to its input could incorrectly interpret a bouncing relay contact as multiple switch events. Or, a circuit that uses a relay to switch an audio signal between two different paths will experience some static noise when switching if there is significant contact bounce. Check the [[Switch Primer|switch primer]] for information on how to deal with switch contact bounce. It's worth mentioning that [[Solid State Relay Primer|Solid State Relays]] don't suffer from contact bounce, because they operate without using moving mechanical parts.

===Arcing, Interference, and Sticking===

[[File:contact_arc.jpg|border|link=]]

When a mechanical relay opens or closes, for the moment that the arm of the switch is very close (but not connected) to the contact, the electric current can arc through the air between the contacts.
This arc can cause interference with nearby electrical instruments and sensors. For example, if an unshielded cable carrying an audio signal is travelling past some relays whose contacts are arcing when they switch, the audio would contain bursts of static noise.

This arcing can also heat up the contacts of the switch enough that they can slowly degrade away until the relay no longer functions. They could also weld together, causing the relay to stay on permanently, which means your load will be powered constantly. If this imposes safety concerns, you should install a fail-safe of some kind. For example, some sauna heaters are turned on with a mechanical relay. In the event of a relay failure, the sauna heater will remain on and continue heating the room beyond the intended temperature. However, a simple mechanical temperature sensor is installed which cuts power to the heater if the room goes beyond a certain temperature.

Some relays are encased in a clear plastic enclosure (sometimes called "ice cube" relays), so the switch contacts can be easily inspected. By inspecting the contacts periodically, you could tell when the relay is getting near the end of its life.

===Prolonging Relay Lifespan===

In order to prolong the lifespan of your relay, avoid switching loads of higher voltage or current than the relay is built for, and avoid highly inductive loads, which worsen the effects of contact arcing. Your Load will probably be inductive if it is built around a large coil of wire - motors and transformers are typical examples. A load considered resistive may also have loops of wire - for instance, hair dryers, toasters, incandescent bulbs use twisted wire elements to generate the heat. An inductive load will have thousands of loops of wire - it's a matter of scale.

Additionally, you should avoid switching at or near the relay's maximum frequency if possible. You can think of a mechanical relay's lifespan in terms of number times switched rather than the amount of time it's used for. A relay that doesn't need to be switched very often can last a long time. If your application requires constant switching over long periods of time, it might be more cost-effective to use a [[Solid State Relay Primer|Solid State Relay]].

====Arc Suppression ====

[[File:Mechanical_relay_diode.jpg|link=|thumb|300px|'''DC Load Protection'''<br/>A diagram of a mechanical relay switching a DC load. An optional diode and fuse are used to protect the relay and prevent hardware damaged caused by improper wiring.<br/>[[Media:Mechanical_relay_diode.jpg|Full-sized Image]]]]
[[File:Mechanical_relay_mov.jpg|link=|thumb|300px|'''AC Load Protection'''<br/>A diagram of a mechanical relay switching an AC load. An optional MOV or Transil diode is placed in parallel to protect the relay from voltage spikes.<br/>[[Media:Mechanical_relay_mov.jpg|Full-Sized Image]]]]
The main cause of failure for mechanical relays is electricity arcing across the contacts during switching. To lengthen the lifespan of your relay, you can add various circuit elements that mitigate arcing.

For DC powered applications, one simple method of mitigating the effects of contact arcing is to place a feedback diode across the load, as pictured. This will allow some of the residual electricity in the circuit to recirculate through the load instead of contributing to the arc that forms when the switch makes the transition from closed to open. You can buy a suitable diode from any electronics distributor, like this [http://parts.digikey.com/1/parts/1850825-diode-std-rec-10a-100v-r-6-10a02-t.html Diode] from Digikey.

For AC powered applications, you can put a Metal Oxide Varistor (MOV) across the load terminals of the relay in order to protect it from voltage spikes. An MOV will not remove the entire arc, but it will be helpful in circuits up to several hundred volts. You can buy an MOV from any electronics distributor, like this [http://parts.digikey.com/1/parts/714083-varistor-thermal-200v-10ka-20mm-tmov20rp200e.html MOV] from Digikey.

For low-voltage AC applications, a bi-directional transient voltage suppression diode ("transil diode") that is rated for higher than the AC voltage of the circuit can be placed across the relay terminals in order to protect it from voltage spikes. You can buy one from any electronics distributor, like this [http://parts.digikey.com/1/parts/718140-transil-600w-47v-bidir-do-15-p6ke47carl.html Transil Diode] from Digikey.

<br clear="all">

==Conclusion==

Mechanical relays are inexpensive and simple devices that allow AC or DC circuits to be switched on and off using a small amount of power.
They come in a variety of switch formats, enabling the user to build some very clever control into a circuit. Phidgets Inc. sells boards with multiple relays that can be connected directly to USB, so they can be controlled by your program.

Contact arcing and switch bounce can be an obstacle for some applications, but both are common problems and can be worked around fairly easily.
Mechanical relays don't last as long as solid state relays, but if you take care of them, they can be a good cost-effective alternative.

==Products in this Category==

* [[1014_2 - PhidgetInterfaceKit 0/0/4]]
* [[1017_1 - PhidgetInterfaceKit 0/0/8]]
* [[3051_1 - Dual Relay Board]]

==Glossary==

===Switch Type===
* SPST - either normally open or normally closed. Simple on/off switch.
* SPDT - 3 pins, has both a NO and NC pin and can function like a SPST switch of either type, or can be used to toggle power between two different loads.
* DPDT - Same as SPDT but there are two controlled by the same relay input. Useful for controlling 2 seperate circuits in a synchronized manner.
* Potential selection criteria for specific switching circuits.

===Contact Arcing===
* As the switch moves from the "on" position to the "off" position (and vice-versa) there is a moment when the arm of the switch in close enough to the contact that electricity will arc through the air, creating lots of heat and possibly damaging the contact. (Diagram would be useful)
* Arcing can lead to sticking, where the switch welds itself closed. If your relay is always on, it might be stuck.
* Arcing will be more severe with higher power loads or highly inductive loads.
* Arcing is expected, but can be mitigated by:
** For DC, feedback diode across load
** For AC, Snubber circuit or
** MOV or
** TVS

===Switching Speed===
* Lifespan of relay is measured in number of contacts, not time in use. Faster switching -> shorter life.
* Switching is audible - you can hear the switching, which might be annoying / undesirable, or it might be good as a confirmation the system is operating.
* Switching speed is limited by heating in the contacts - the arcing generates heat, and switching high loads faster than the rated switching speed will cause the relay to overheat.

===Operating Time===
* Time it takes for the arm of the switch to connect with the contact after being activated
* If 10ms is too slow, look at SSRs

===Control Voltage===
* Can be controlled via digital output
* Relay offers isolation between load circuit and control circuit

===Maximum (AC/DC) Switching Voltage===
* Secondary selection criteria.

===Maximum (AC/DC) Switching Current===
* Main selection criteria.
* If they need to switch more than 5A DC, or 10A AC, go to SSRs
* Inductive loads- does the same multiplier apply as for SSRs?

===Minimum Switching Current===
* A certain amount of current is needed on the LOAD side of a relay.
* Oxide films build up on the contacts, so this minimum is required to conduct through them.
* This spec determines whether or not the relay can switch a signal instead of power.
** If you are switching a signal rather than power, contact bounce could be a problem.

InterfaceKit Digital Outputs

2012-06-29T21:33:47Z

Cora:

[[Category: Primer]]
{{HiddenNeeds|This should eventually include open collector digital outputs, and their differences}}
==Introduction==

Digital Outputs can be used to drive LEDs, solid state relays, and transistors (or anything that will accept a CMOS signal).
Digital outputs can be used to control devices that accept a +5V control signal.
With transistors and some electronics experience, other devices can be controlled, such as buzzers, lights, larger LEDs, relays.

==Specifications and Features==

[[Image:digital_output.jpg|right|thumb|A Phidgets digital output.]]

The 250 ohm resistance is internal to the PhidgetInterfaceKit 8/8/8, and limits the current that can flow through the output.
This is intended to protect the device from being damaged if there is a short to ground or if an LED is used.
Ultimately this means the maximum current output of the digital outputs is 16mA. In practice you should not try to draw 16mA from the outputs for extended periods of time though as this can lead to damaged components. You should try to limit your current draw to less than 5mA though up to 10 would not cause any immediate concerns.
The output is intended to drive TTL or CMOS inputs; it is not designed to provide power to an external circuit.

In practice the frequency at which these outputs can be switched is highly dependent on system properties such as OS, USB hardware, and cabling. However, it is a good bet that the majority of systems will be able to achieve 1kHz.

<br clear="all">
===Ground Protection===
Ground terminals on the InterfaceKit share a common ground with USB ground.
Because they are not internally isolated, these terminals will expose the USB ground potential of the PC to which they are connected.
Be sure you are completely familiar with any circuit you intend to connect to the InterfaceKit before it is connected.
If a reverse voltage or dangerously high voltage is applied to the input or output terminals, damage to the Phidget or the PC may result.

===5 Volt Terminal Block===
For users who need it, we provide 5V on the terminal block next to Digital Output 7.

==Using the Digital Outputs==
Here are some circuit diagrams that illustrate how to connect various devices to the digital outputs on your Phidget.

===Driving an LED with the Digital Output===

[[Image:LED_digital_output.jpg|right|thumb|Schematic for connecting to an LED.]]

Connecting an LED to a digital output is simple. Wire the anode to a digital output labeled 0 to 7 on the Interface Kit, and the cathode to a supplied ground, labeled G.

<br clear="all">
===Using a 3052 SSR Board with a Digital Output===

[[Image:3052_digital_output.jpg|right|thumb|Schematic for connecting a 3052 board.]]

Setting the digital output to true causes the output of the 3052 to turn on.
This can be used to control AC or DC devices.

The load can also be switched with the 3052 on the high side.
High side switching is helpful for powering more complicated circuitry that cannot tolerate having multiple grounds.

<br clear="all">
===Isolating a Digital Output with a MOSFET based SSR===

[[Image:isolating_digital_output_ssr.jpg|right|thumb|Schematic for isolating a digital input with an SSR.]]

It’s possible to wire up your own Solid State Relay to the digital output.
MOSFET based SSRs have the advantage that they can be understood as being a simple switch.

There are many other types of SSRs that are more suitable for controlling higher power, higher voltage AC devices that can also be controlled in the same fashion.

<br clear="all">
===Isolating a Digital Output with an Optocoupler===

[[Image:isolating_digital_output_optocoupler.jpg|right|thumb|Schematic for isolating a digital input with an optocoupler.]]

In some applications, particularly where there is a lot of electrical noise (automotive), or where you want maximum protection of the circuitry (interactive installations, kiosks), electrical isolation buys you a huge margin of protection.
Driving the LED causes the output transistor to sink current.

The maximum current through the transistor will depend in part on the characteristics of the optocoupler.

<br clear="all">
===Controlling a Relay with a N-Channel MOSFET===

[[Image:relay_nmos.jpg|right|thumb|Schematic for using a relay with an NMOS transistor.]]

A inexpensive mosfet and flyback diode can be used to control larger loads - relays for example - directly from the digital output.
Be sure to use a Logic-Level MOSFET so that the +5V Digital Output is able to turn it on.

<br clear="all">
===Controlling a Relay with a NPN Transistor===

[[Image:relay_npn.jpg|right|thumb|Schematic for using a relay with an NPN transistor.]]

This circuit is very similar to the N-channel mosfet - but you may already have NPN transistors on hand.

<br clear="all">
===Using a 3051 Dual Relay Board with one or two Digital Outputs===

[[Image:3051_digital_outputs.jpg|right|thumb|Schematic for using a 3051 board.]]

The 3051 Dual Relay Board is designed to be used with the PhidgetInterfaceKit 8/8/8.
An Analog Input can be used to supply power to the relays, and one or two digital outputs used to control the relays.
The 3051 is a good option if you need a couple relays in your project.
<br clear="all">

==Update Rate==

Please check the specification for the maximum rate of sampling that the Digital input can measure. This is often slower than your program can change it. So, if you change the output one way and then flip it back immediately in your code, the interface kit may not register the change.

Solid State Relay Guide

2012-06-29T21:31:45Z

Cora: /* How SSRs Work */

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[Image:SSR.jpg]]
| [[Image:3052.jpg|200px]]
|}

==Introduction==

[[Image:SSR.jpg|thumb|A "hockey puck" SSR, so named because of its thick shape and black color. They are specifically designed to switch either AC loads or DC loads, but never both.]]

Solid state relays (SSRs) turn on or off the power being supplied to other devices, in a similar fashion as a physical [[Switch Primer|switch]]. However, instead of being switched by human interaction like a physical switch, SSRs are switched electronically.
With SSRs, you can control high-current devices such as lights or appliances with low-current signals, like a standard DC signal from a [[Digital Output Primer|Digital Output]]. Most SSRs will switch on with a voltage of 3V or higher. This makes them perfect for use with Phidget [[Interface Kits]], or any device with a digital output.

SSRs perform the same job as [[Mechanical Relay Primer|Mechanical Relays]], but have the following advantages:
* SSRs produce less electromagnetic interference than mechanical relays during operation. This is mostly due to the absence of a phenomenon called [[Mechanical Relay Primer#Arcing, Interference, and Sticking|contact arcing]] only present in mechanical relays, where the physical contacts of the relay tend to spark internally while switching. The reduced interference can also be attributed to the fact that SSRs do not use electromagnets to switch.
* The switch contacts of a mechanical relay will eventually wear down from arcing. An SSR will have a longer life because its internals are purely digital. Properly used, they will last for millions of cycles.
* SSRs turn on and off faster than mechanical relays (≈1ms compared to ≈10ms).
* SSRs are less susceptible to physical vibrations than mechanical relays.
* Since the switch inside an SSR isn't a mechanical switch, it does not suffer from [[Switch Primer#Bounce|contact bounce]] and operates silently.

However, compared to Mechanical Relays, SSRs:
* Are more expensive.
* Will dissipate more energy in the form of heat (1-2% of the energy intended to power the load).

==How SSRs Work==

[[Image:SSR_Internals.png|thumb|A conceptual diagram of the insides of an SSR.]]

The control inputs are connected internally to an LED, which shines across an air gap to light sensors.
The light sensor is connected to the transistors which open or close, supplying the relay's load with power.
When a transistor is '''closed''', current can flow freely through the relay, causing the load and power supply to be connected.
When a transistor is '''open''', almost all current is blocked, causing the load to become disconnected from the power supply.
The pairing of an LED with light sensors is called an optocoupler, and is a common technique to link two parts of a circuit without a direct electrical connection.

===Basic Use===

Controlling an SSR is no more complicated than turning an LED on and off. Switch it on, switch it off, it is that easy (see the [[Digital Output Primer|Digital Output Primer]], or our [{{SERVER}}/products.php?product_id=1031 specific LED controller] for more).

The ability of an SSR to switch a load is very similar to a [[Mechanical Relay Primer|mechanical relay]] or simple switch.
By turning the digital output controlling the relay on and off, you control whether or not the load is connected to its power supply.

The challenge is to pick an appropriate type of SSR for your application. There is no single SSR perfect for all applications. To choose an SSR for your particular application, please follow the [[#Choosing an SSR|Choosing an SSR]] section.

===Safety===

Since relays switch high currents and voltages, standard precautions apply. Make sure you never touch the terminals while the relay is powered. If your SSR came with a plastic cover, use it. Even when the SSR is switched off, a very small amount of current will flow.

When an SSR fails, it most often fails permanently closed. This is because when the transistor inside fails due to excessive current or heat, it will usually short out, allowing current to pass through unimpeded.
This means that as long as the power supply remains on, the load will be powered, possibly creating a fire or safety hazard.

==Choosing an SSR==

===Identify your voltage===

First, determine whether you need to switch AC or DC voltage. The electrical grid, and thus your wall outlet, runs AC, whereas batteries and most small power supplies are DC.

Next, determine the maximum number of volts you will be switching. If you are switching DC, particularly with batteries, assume your voltage is at least 25% more than what your battery is rated for. Even larger fluctuations occur on AC, but AC SSRs are designed to handle these surges. Typical AC voltage from a wall socket in North America is 110VAC, whereas in Europe it is usually 220VAC. If you are switching AC voltage from a wall socket, check which standard your country uses, and use that number as your voltage.

===Identify your current===

The current drawn by your load when turned on affects how large of an SSR you need, and how hot it will be when it is in use. If you know how much current, on average, your load draws, this is what we call '''Average Load Current'''. If you don't know the average current, but you know the wattage (power rating) of your load, you can calculate Average Load Current by:

<math>
\text{Average Load Current} =\frac{\text{Watts}}{\text{Operating Voltage}}
</math>

Next, you need to know the current drawn by your load when it is first turned on. Many loads demand a huge inrush of current when the load is first turned on. This places a significant amount of stress on the electronics inside the SSR. If you've ever noticed the lights dimming in the house for a second when the furnace starts up, this is caused by the fan motor starting up. In the same way that it takes a lot of force to move a heavy object from rest, it initially takes a lot of current to power up a fan or incandescent bulb. It's very difficult to measure the '''Surge Current''' itself, so we use a multiplier based on your device type. Surge Current is also referred to as '''inrush current'''.

{|border=1
|+'''Surge Current Multiplier'''
! Application
! Multiplier
|-
| Incandescent Light Bulbs || 6x
|-
| Motors || 6x
|-
| LEDs || 1x
|-
| Complex Electronics i.e., Motor Controllers, Phidgets || 6x
|-
| Fluorescent Light Fixtures (AC Only) || 10x
|-
| Transformers || 20x
|-
| Heaters || 1x
|-
|}

Multiply your Average Load Current by the multiplier for your device type to calculate the Surge Current.

===I need to switch AC===

Most AC applications will be switching 110 to 240 Volt power coming from the grid. If that's you, go to the [[#Mains Voltage (110 to 240V AC)|Mains Voltage (110 to 240V AC)]] section.

We also cover low voltage AC applications - 28 VAC (Volts AC) or less. For more information, visit the [[#AC/DC SSRs|AC/DC SSRs]] section.

===I need to switch DC===

If you only need to switch a small amount of current - 9 Amps or less, consider our compact, cost effective [[#AC/DC SSRs|AC/DC SSRs]].

If you need to switch more than 9 Amps, you need a serious [[#DC SSRs|DC SSR]].

If you need to switch up to 16 small loads of 2 Amps or less, you can use the [[Open Collector Digital Output Primer|open collector digital outputs]] on a [[1012_2 - PhidgetInterfaceKit 0/16/16|1012 PhidgetInterfaceKit 0/16/16]], which can be wired to behave similarly to relays.

==I need Gradual Dimming==

Instead of simply turning the load on/off, if you want to dim it gradually, you can use a proportional control SSR. They are able to reduce the average power to the load gradually, in proportion to the strength of the input signal. For more information, you can visit the [[#Proportional Control SSR|Proportional Control SSR Section]].

==Mains Voltage (110 to 240V AC)==

We sell AC SSRs for 120 VAC or 240 VAC operation. If you are unsure what voltages you could eventually need to switch, the 240 VAC relays can be used to switch 120 VAC with no problems. Please note we are very conservative in how we rate SSRs - our 120 VAC relays are rated by the manufacturer for 240 VAC, and the 240 VAC for 480 VAC. We strongly recommend against using them to the manufacturer rated voltage. To understand why, read the [[#AC SSR Protection|AC SSR Protection]] section.

===Load Type - Inductive vs. Resistive===

[[Image:zero cross.png|right|thumb|300px|This graph shows the difference between zero-cross and random turn-on. The blue line represents the oscillating voltage of an AC load, and the shaded areas represent the sections when the relay is turned on and letting current pass through. As you can see, the random turn-on SSR immediately opens when activated, while the zero-cross turn-on SSR waits until the voltage crosses zero before opening.]]

If your load is inductive, you need to choose a '''Random Turn On''' relay. If your load is resistive, choose a '''Zero Crossing''' relay.

Your Load will probably be inductive if it is built around a large coil of wire - motors and transformers are typical examples. A load considered resistive may also have loops of wire - for instance, hair dryers, toasters, incandescent bulbs use twisted wire elements to generate the heat. An inductive load will have thousands of loops of wire - it's a matter of scale. There is no such thing as a perfectly resistive load - but a load has to be very inductive to cause the zero crossing SSRs to malfunction.

SSRs are designed to either turn on immediately ('''Random Turn On'''), or wait until the next 'alternation' of the voltage ('''Zero Crossing'''). Zero Crossing SSRs create less electromagnetic 'noise' when they turn on. They are best used with resistive loads - Zero Crossing SSRs are not able to turn off some inductive loads. It's very difficult to determine which inductive loads will create problems - well beyond the scope of this document. If your load is inductive, we recommend buying the '''Random Turn On''' SSRs.

{|border=1
|+ '''Inductive and Resistive Loads'''
! Application
! Load Type
|-
| Incandescent Light Bulbs || Resistive
|-
| Fluorescent Light Fixtures || Inductive or Resistive <font size=4>'''*'''</font>
|-
| Motors || Inductive
|-
| Transformers || Inductive
|-
| Heaters || Resistive
|-
| Computer / Electronics || Resistive
|-
| AC/DC power supplies (brick heavy type) || Inductive
|-
|AC/DC Power supplies (lightweight switchers) || Resistive
|}

<font size=4>'''<nowiki>*</nowiki>'''</font> ''For fluorescent light fixtures, older units (magnetic ballast) may be inductive, and newer units are often resistive (electronic ballast).''

===Choosing your AC SSR===

Now that you have identified your Operating Voltage, Average and Surge Current, and your load type (inductive or resistive), you can create a short list of relays whose
* '''Maximum Load Voltage''' are greater than or equal to your operating voltage,
* '''Maximum Surge Current''' are greater than or equal to your surge current, and
* '''Load type''' matches what you chose for random turn on/zero crossing.

<font color=green> < Table: +ac_ssr > </font>

{|border=1
! Phidgets Product #
! Manufacturer Part #
! Current Type
! Turn-on Type
! Control Voltage (V)
! Max. Load Voltage (V)
! Max. Load Current Without Heatsink (A)
! Max. Load Current with 3955 Heatsink (A)
! Max. Load Current with 3956 Heatsink (A)
! Max. Surge Current (A)
! Output Type
|-
| 3953_0 || HFS34/D-240A20PS-Y || AC || Random Turn-on || 3-32VDC || 120 || 8 || 15 || 20 || 255 || SCR
|-
| 3954_0 || HFS34/D-240A80PS-Y || AC || Random Turn-on || 3-32VDC || 120 || 10 || 20 || 50 || 800 || SCR
|}

Now compare the '''Max. Load Current without Heatsink''' value for the SSRs on your list to your Average Load Current. If your Average Load Current is greater, you may need a heatsink. For selecting a heatsink, please consult [[#Picking a heatsink|Picking a Heatsink]]. Alternatively, look at other SSRs on your list - there may be an SSR that can handle your average load current with no heatsink.

At this point, you know the SSR you need.

Instead of simply turning the load on/off, if you want to dim it gradually, you can use a proportional control SSR. They are able to reduce the average power to the load gradually, in proportion to the strength of the input signal. For more information, you can visit the [[#Proportional Control SSR|Proportional Control SSR Section]].

If you are interested in learning more about SSRs in general, check out our [[#Did you know?|"Did you know?"]] section.

===AC SSR Protection===

[[Image:MOV.jpg|thumb|An MOV, which comes packaged with our AC "Hockey Puck" relays. ]]

Your AC SSR from Phidgets comes with a circular disc with two legs (pictured). This is a Metal Oxide Varistor (MOV) and should be installed across the load (larger) terminals of your SSR. MOVs are the classic surge protector - an inexpensive component that absorbs high voltage spikes. High voltage spikes are caused by inductive loads when they are turned off, and also happen very often on the electrical grid, as nearby devices are operated. Even if your load is resistive, use an MOV to protect the SSR.

Matching an MOV to an SSR is not easy - this is why we include an MOV with your SSR. If an MOV is chosen for too low of a voltage spike, it will wear out quickly. If it is chosen for too high of a voltage spike, it will not protect the SSR adequately. To balance SSR protection against MOV lifetime, we have found it necessary to use SSRs built for 240 VAC in 120 VAC applications, and SSRs built for 480 VAC in 240 VAC applications. If you must operate our AC SSRs on higher voltages than we recommend, do not use the included MOV.

As MOVs wear out from use, they will become more sensitive to common voltage spikes, causing them to wear out quicker. When they entirely fail, they will become a short circuit, potentially creating a fire hazard. The MOV included with your SSR has a fuse built in which will disable the MOV when it becomes a hazard. To be on the safe side, avoid mounting your SSR near any flammable material.

===Proportional Control SSR===

Proportional Control Relays (often simply called "Control Relays") are SSRs you can use to control the amount of power to the load. Rather than reduce the voltage, or somehow limit the current - which would be very expensive solutions, the Proportional SSR reduces power by turning the load on/off quickly, feeding full power in short pulses.

Proportional SSRs are controlled by a variable voltage - as the control voltage increases, more power is available to the load. Our PhidgetAnalog product can be used to control Proportional SSRs, since an [[Analog Output Primer|analog output]] can output various amounts of voltage, as opposed to a digital output, which only has two states- high and low. We don't sell Proportional SSRs - but they can be purchased from [http://www.digikey.com Digikey], where they are called AC Linear Controlled SSRs.

A quick and dirty solution for dimming with Phidgets is to use an [[Servo Motor and Controller Primer|RC Servo Motor]] with a PhidgetAdvancedServo controller to rotate the knob on a light dimmer. From software, the RC Servo Motor is rotated to the desired position, cranking the knob as it turns. While this may seem like a roundabout way of achieving proportional control, dimmers tend to be much less expensive because they are less specialized and are manufactured in greater quantity.

===Example circuits with AC SSRs===

[[Image:AC SSR Load.png|right|thumb|300px|Schematic of an AC SSR switching a generic load. A metal oxide varistor is added across the load to protect the SSR.]]

When wiring up an AC circuit, particularly for long term installation, you may find it helpful to buy a book on residential wiring from your local hardware store. There are many wiring conventions (and often legal codes) which will help you plan your project, and the legal codes are often a great source of wisdom.

<br clear="all">

==DC SSRs (0 to 50V DC)==

We sell DC SSRs for that switch a maximum load of 50 volts. If you are unsure what voltages you could be switching in the future, higher voltage DC SSRs can be used to switch lower voltages. Common engineering practice would be to purchase an SSR rated for 50-100% higher voltage than the voltage you plan to be switching. For instance, if you are switching 24V, a 50V SSR is reasonable.

===Choosing your DC SSR===

Now that you have identified your Operating Voltage, Average and Surge Current, you can create a short list of relays whose
* Maximum Load Voltage are greater than or equal to your operating voltage,
* Maximum Surge Current are greater than or equal to your surge current, and
* Maximum Average Current is greater than or equal to your Average current.

<font color=green> < Table: +dc_ssr > </font>

{|border=1
! Phidgets Product #
! Manufacturer Part #
! Current Type
! Turn-on Type
! Control Voltage (V)
! Max. Load Voltage (V)
! Max. Load Current Without Heatsink (A)
! Max. Load Current with 3955 Heatsink (A)
! Max. Load Current with 3956 Heatsink (A)
! Max. Surge Current (A)
! Output Type
|-
| 3950_0 || HFS33/D-30D50M || DC || N/A || 3-32VDC || 30 || 18 || 50 || 50 || 120 || MOSFET
|-
| 3951_0 || HFS33/D-50D80M || DC || N/A || 3-32VDC || 50 || 20 || 40 || 80 || 200 || MOSFET
|-
| 3952_0 || HFS33/D-30D100M || DC || N/A || 3-32VDC || 30 || 25 || 50 || 100 || 240 || MOSFET
|-
|}

Now compare the '''Max. Load Current without Heatsink''' value for the SSRs on your list to your Average Load Current. If your Average Load Current is greater, you may need a heatsink. For selecting a heatsink, please consult [[#Picking a Heatsink|Picking a Heatsink]]. Alternatively, look at other SSRs on your list - there may be an SSR that can handle your average load current without a heatsink. SSRs rated for a larger load than the load you're using will be more efficient (meaning less energy lost in the form of heat) than an SSR that's being operated at its maximum load.

At this point, you know the SSR you need.

If you are interested in learning more about SSRs in general, check out our [[#Did you know?|"Did you know?"]] section.

===DC SSR Protection===

[[Image:Diode.jpg|thumb| A diode, included with our DC "hockey puck" SSRs. The cathode is marked with a line. The blue symbol shows circuit diagram equivalent of the diode.]]

[[Image:relaymotor.jpg|thumb| A DC SSR switching an electric motor. The 1018 Phidget InterfaceKit controls the SSR using its digital outputs. A diode is shown installed across the motor, and a fuse is hooked up between the power supply and the rest of the circuit.]]

Your DC SSR from Phidgets comes with a diode. This diode should be installed across your load, with the Cathode installed towards the positive terminal of the power supply (as shown in the diagram).

If the diode is installed backwards, as soon as the SSR is turned on, the load will be shorted out, likely destroying the diode, or the SSR, or your power supply.
A fuse protecting your power supply is always a good idea. You can place the fuse in between the positive terminal of the power supply and the positive terminal of the load side of the SSR.

The diode protects the SSR from powerful residual currents after the SSR is turned off. While your load is being driven, inductance builds up magnetic fields around the wiring.
Every load is inductive to some degree, and when the SSR turns off, the magnetic fields will ram current against the now open SSR, easily damaging it. The diode allows these currents to recirculate in the load until they have lost their energy.

<br clear="all">

===Example circuits with DC SSRs===

[[Image:DC SSR Load.png|right|thumb|300px|Schematic of an DC SSR switching a generic load, which is protected by a diode connected in parallel. The circuit is protected by a fuse in series after the power supply.]]

The electrical isolation built into a DC SSR allows them to be placed within a circuit just like a switch. Since it is isolated, you don't have to worry about grounding or voltage offsets.

With a DC SSR, always make sure the positive load terminal (labeled +) is facing towards the positive terminal of the power supply. If the load terminals are reversed, your load will immediately turn on. There is a diode inside of the SSR that allows current to flow freely through it when the SSR is connected incorrectly. This feature is included because this sort of wiring mistake would destroy the transistor in the DC SSR otherwise.

The DC SSR can be installed on either side of the load, and it will work properly, but there is an advantage to installing the SSR between the power supply and the load. If the load is connected to the power supply, it will always have a potentially dangerous voltage on it, even when it is not operating.

<br clear="all">

==AC/DC SSRs (0 to 40V DC / 0 to 28V AC)==

[[Image:AC_DC_SSR.png|thumb|A small, versatile AC/DC SSR mounted on a Phidgets board for easy pin access.]]

Our AC/DC SSRs are built on a small PCB, making them physically smaller than the large "hockey puck" SSRs, and less expensive. They are limited to lower currents, and cannot be mounted on a heatsink.

We sell AC/DC SSRs that can switch up to 40 Volts DC or 28 Volts AC. This is indicated on the SSR Product pages under the Maximum Load Voltage specification. There is no lower limit on the voltages that the AC/DC SSRs can switch. If your voltage is close - be conservative. For instance, a 36 Volt system built from 3 Lead Acid batteries can reach 45 volts when charging.

===Picking your AC/DC SSR===

Now that you have identified your Operating Voltage, Average and Surge Current, you can create a short list of relays whose
* Maximum Load Voltage are greater than or equal to your operating voltage,
* Maximum Surge Current are greater than or equal to your surge current, and
* Maximum Average Current is greater than or equal to your Average current.

<font color=green> < Table: +versatile_ssr > </font>

{|border=1
! Phidgets Product #
! Manufacturer Part #
! Current Type
! Turn-on Type
! Control Voltage (V)
! Max. Load Voltage (V)
! Max. Load Current Without Heatsink (A)
! Max. Load Current with 3955 Heatsink (A)
! Max. Load Current with 3956 Heatsink (A)
! Max. Surge Current (A)
! Output Type
|-
| 3052_0 || N/A || AC/DC || N/A || ??? || 40DC or 28AC || 2.5 || N/A || N/A || 5 || MOSFET
|-
| 3053_0 || N/A || AC/DC || N/A || ??? || 40DC or 28AC || 9 || N/A || N/A || ??? || MOSFET
|}

If you are interested in minimum cost, you will likely choose the cheapest option that meets these criteria. If you are interested in high efficiency operation and less heat generation, consider buying an SSR with higher current rating.

Your AC/DC SSR from Phidgets has built in protection from static electricity, and dangerous residual currents after the SSR is turned off. If the load you are switching is powered by a DC source, installing a diode across the load will offer even more protection. Refer to the [[#DC SSR Protection|DC SSR Protection]] section for more information.

To learn more about SSRs in general, visit the [[#Did you know?|"Did you know?"]] section.

<br clear="all">

===Example circuits with AC/DC SSRs===

[[Image:Versatile SSR DC Load.png|thumb|A versatile AC/DC SSR switching a DC load. The load terminals are bidirectional, so it doesn't matter which way you hook them up. The optional diode can be added to help protect the SSR when switching DC loads.]]
[[Image:Versatile SSR AC Load.png|thumb|A versatile AC/DC SSR switching an AC load.]]

The electrical isolation built into a AC/DC SSR allows them to be placed within a circuit just like a switch. Circuits without electrical isolation require a lot more care - proper grounding, careful consideration of voltage offsets.

<br clear="all">

==Using heatsinks with Hockey Puck SSRs==

[[Image:3950_0 Accessories Web.jpg|thumb|A "hockey puck" SSR with plastic cover (left), a thermal pad (right). All hockey puck SSRs sold at Phidgets come with both of these accessories plus a diode or varistor to protect the SSR.]]
[[Image:3955_0 Functional Web.jpg|thumb|A "hockey puck" SSR mounted on a [[3955]] heatsink by two screws. The thermal pad is pressed between the SSR and the heatsink.]]

SSRs will only achieve their promise of reliability and long life if they are kept cool. Cool is relative, of course, but a good rule of thumb is to keep the metal base of the SSR at less than 85°C (185°F). A [[Thermocouple Primer|thermocouple]] can be used to precisely measure the temperature of the metal base.

Excess heat usually comes from too much current and too little heatsinking. A lot of heat can also be generated by frequently turning the relay on and off. If your relay is operated for brief periods of time, you may not need as large of a heatsink - provided the relay is never accidentally left on for extended periods. Unless space is a concern, it's better to err on the side of caution.

Before buying a heatsink, consider if you actually need it. If your application is running at room temperature, and your average current is less than the '''Max. Load Current without Heatsink''' specification of your SSR, then you don't need a heatsink. Alternatively, if your project has a large metal chassis that the SSR can bolt to, this can be used as your heatsink.

Each SSR suitable for use with heatsinks will include a specification of how much current it can switch with each heatsink we sell. This specification assumes a reasonable airflow over the heatsink, and that the flowing air is at room temperature. Our SSRs have a sheet of metal underneath, where the heat is concentrated - this is also where the heat is measured to tell if the SSR is too hot. Phidgets includes a grey thermal pad with our Hockey Puck SSRs (see pictured). You place this pad under an SSR when mounting it on a heatsink, or on large metal surfaces that can dissipate heat. The pad performs the same function as thermal grease - it helps conduct heat between the base of the SSR and the heatsink. If you prefer to use thermal grease, you can use it instead of the pad. Our heatsinks include screws for mounting SSRs. Use a good size screwdriver when tightening the SSR down on the heatsink to ensure good conduction.

{|border=1
! Phidgets Product #
! Product Name
! Manufacturer Part #
! Dimensions (mm)
! Thermal Resistance (C/W)
|-
| 3955_0 || Small Heatsink for SSR || HF92B-80 || 50x50x80 || 2.4
|-
| 3956_0 || Large Heatsink for SSR || HF92B-150A || 55x142x150 || 0.6
|-
|}

<br clear="all">

==Hooking up wires to the Hockey Puck SSR==

[[Image:relay_mov.jpg|thumb|An AC SSR with the wires attached normally and an MOV installed across the load side.]]
[[Image:lugs.jpg|thumb|TRM6 wiring lugs connected to a DC SSR.]]

When wiring your load to the SSR, the wire is looped clockwise around the terminal, so when the screw is tightened down, it will draw the wire in tighter. We recommend using wires up to 10 AWG in size - any larger, and the screws will not have enough thread left to tighten down, and they will strip. Larger wires can be attached using a wiring lug. The lug is clamped under the SSR screw, and the wire attaches to the lug.

Loose wire connections can generate a lot of heat - use a large enough screwdriver when clamping down the load wires to ensure that the screws are on tight enough.

For the current ratings of various wires sizes, please see [[Page on Wire Sizes]].

<br clear="all">

==Did you know?==

* Mains Voltage '''AC SSRs''' cannot switch DC. They will never turn the load off. AC SSRs turn off twice per AC Cycle, when the current changes direction and is momentarily zero. For example, AC is 60 Hz in North America, so the AC SSR has 120 opportunities per second to turn off (the SSR will only '''stay''' off if the control signal is low). If the SSR is operating from DC, the current will flow continuously, and the load will not turn off, even when the control input is off.

* An '''AC SSR''' turns off automatically every time the load current reaches zero. It will turn back on almost immediately as long as the signal controlling the SSR is high. An AC SSR will actually have a low, non-zero current value that it regards as 'zero'. This specification is usually called "Minimum Load Current" in the data sheet. If your load requires less than this minimum current, your SSR will never turn on, or will not reliably turn on. The simplest solution to this problem is to connect another load in parallel with the first, increasing the Current required by the load.

* SSR Manufacturers have started adding a simple circuit inside '''AC SSRs''', across the load terminals, called a snubber. The snubber absorbs very fast electrical changes that could normally cause an '''AC SSR''' to turn on accidentally. When the AC SSR is turned on, there is little voltage difference between the terminals, so the snubber has very little effect. When the AC SSR is turned off, the snubber is actively protecting the SSR - but at a cost, as it allows a small current through the SSR, which is wasted.

* An '''AC SSR''' uses bipolar transistors - an old technology that has been replaced by CMOS transistors in modern digital circuits. Bipolar transistors are still superior for handling high voltages. Bipolar transistors, and the more complex transistors built from them, will lose a constant voltage as current flows through them. The collection of transistors in your SSR will lose about 1.7 volts - so on a 120 VAC system, you will lose about 1.5% to the SSR. This energy converts to heat inside the SSR, and the heating from these transistors is the reason SSRs often need heatsinks.

* SSRs, and semiconductors in general, usually fail as a short circuit. A short circuit is a circuit whose internals have been damaged such that current can flow through it freely. This means your load will probably turn on permanently (until you disconnect the power source) - make sure this doesn't cause a safety hazard. For instance, Sauna Heaters have a simple thermally-triggered mechanical shutdown to protect them if control electronics fails.

* '''DC SSRs''' (at least the units we sell) use Metal Oxide Semiconductor Field Effect Transistors (MOSFETs). MOSFETs do not lose a constant voltage - instead, when they turn on, they act as a very slight restriction to the flow of current - a resistor. At low currents, the slight restriction wastes very little power, giving high efficiency and often not requiring a heatsink. This efficiency is lost as the current increases - a doubling of current quadruples the production of heat.

* Normally, a MOSFET can only block current in one direction - as soon as the voltage reverses, the current flows through a diode run in parallel to the MOSFET. If a MOSFET were used to switch AC, the load would be turned on half the time. A common solution is to use two MOSFETs back to back - which is what we do with our '''AC/DC SSRs'''.

Solid State Relay Guide

2012-06-29T21:31:29Z

Cora: /* How SSRs Work */

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[Image:SSR.jpg]]
| [[Image:3052.jpg|200px]]
|}

==Introduction==

[[Image:SSR.jpg|thumb|A "hockey puck" SSR, so named because of its thick shape and black color. They are specifically designed to switch either AC loads or DC loads, but never both.]]

Solid state relays (SSRs) turn on or off the power being supplied to other devices, in a similar fashion as a physical [[Switch Primer|switch]]. However, instead of being switched by human interaction like a physical switch, SSRs are switched electronically.
With SSRs, you can control high-current devices such as lights or appliances with low-current signals, like a standard DC signal from a [[Digital Output Primer|Digital Output]]. Most SSRs will switch on with a voltage of 3V or higher. This makes them perfect for use with Phidget [[Interface Kits]], or any device with a digital output.

SSRs perform the same job as [[Mechanical Relay Primer|Mechanical Relays]], but have the following advantages:
* SSRs produce less electromagnetic interference than mechanical relays during operation. This is mostly due to the absence of a phenomenon called [[Mechanical Relay Primer#Arcing, Interference, and Sticking|contact arcing]] only present in mechanical relays, where the physical contacts of the relay tend to spark internally while switching. The reduced interference can also be attributed to the fact that SSRs do not use electromagnets to switch.
* The switch contacts of a mechanical relay will eventually wear down from arcing. An SSR will have a longer life because its internals are purely digital. Properly used, they will last for millions of cycles.
* SSRs turn on and off faster than mechanical relays (≈1ms compared to ≈10ms).
* SSRs are less susceptible to physical vibrations than mechanical relays.
* Since the switch inside an SSR isn't a mechanical switch, it does not suffer from [[Switch Primer#Bounce|contact bounce]] and operates silently.

However, compared to Mechanical Relays, SSRs:
* Are more expensive.
* Will dissipate more energy in the form of heat (1-2% of the energy intended to power the load).

==How SSRs Work==

[[Image:SSR_Internals.png|thumb|A conceptual diagram of the insides of an SSR.]]

The control inputs are connected internally to an LED, which shines across an air gap to light sensors.
The light sensor is connected to the transistors which open or close, supplying the relay's load with power.
When a transistor is '''closed''', current can flow freely through the relay, causing the load and power supply to be connected.
When a transistor is '''open''', almost all current is blocked, causing the load to become disconnected from the power supply.
The pairing of an LED with light sensors is called an optocoupler, and is a common technique to link two parts of a circuit without a direct electrical connection.

===Basic Use===

Controlling an SSR is no more complicated than turning an LED on and off. Switch it on, switch it off, it is that easy (see the [[Digital Output Primer|Digital Output primer]], or our [{{SERVER}}/products.php?product_id=1031 specific LED controller] for more).

The ability of an SSR to switch a load is very similar to a [[Mechanical Relay Primer|mechanical relay]] or simple switch.
By turning the digital output controlling the relay on and off, you control whether or not the load is connected to its power supply.

The challenge is to pick an appropriate type of SSR for your application. There is no single SSR perfect for all applications. To choose an SSR for your particular application, please follow the [[#Choosing an SSR|Choosing an SSR]] section.

===Safety===

Since relays switch high currents and voltages, standard precautions apply. Make sure you never touch the terminals while the relay is powered. If your SSR came with a plastic cover, use it. Even when the SSR is switched off, a very small amount of current will flow.

When an SSR fails, it most often fails permanently closed. This is because when the transistor inside fails due to excessive current or heat, it will usually short out, allowing current to pass through unimpeded.
This means that as long as the power supply remains on, the load will be powered, possibly creating a fire or safety hazard.

==Choosing an SSR==

===Identify your voltage===

First, determine whether you need to switch AC or DC voltage. The electrical grid, and thus your wall outlet, runs AC, whereas batteries and most small power supplies are DC.

Next, determine the maximum number of volts you will be switching. If you are switching DC, particularly with batteries, assume your voltage is at least 25% more than what your battery is rated for. Even larger fluctuations occur on AC, but AC SSRs are designed to handle these surges. Typical AC voltage from a wall socket in North America is 110VAC, whereas in Europe it is usually 220VAC. If you are switching AC voltage from a wall socket, check which standard your country uses, and use that number as your voltage.

===Identify your current===

The current drawn by your load when turned on affects how large of an SSR you need, and how hot it will be when it is in use. If you know how much current, on average, your load draws, this is what we call '''Average Load Current'''. If you don't know the average current, but you know the wattage (power rating) of your load, you can calculate Average Load Current by:

<math>
\text{Average Load Current} =\frac{\text{Watts}}{\text{Operating Voltage}}
</math>

Next, you need to know the current drawn by your load when it is first turned on. Many loads demand a huge inrush of current when the load is first turned on. This places a significant amount of stress on the electronics inside the SSR. If you've ever noticed the lights dimming in the house for a second when the furnace starts up, this is caused by the fan motor starting up. In the same way that it takes a lot of force to move a heavy object from rest, it initially takes a lot of current to power up a fan or incandescent bulb. It's very difficult to measure the '''Surge Current''' itself, so we use a multiplier based on your device type. Surge Current is also referred to as '''inrush current'''.

{|border=1
|+'''Surge Current Multiplier'''
! Application
! Multiplier
|-
| Incandescent Light Bulbs || 6x
|-
| Motors || 6x
|-
| LEDs || 1x
|-
| Complex Electronics i.e., Motor Controllers, Phidgets || 6x
|-
| Fluorescent Light Fixtures (AC Only) || 10x
|-
| Transformers || 20x
|-
| Heaters || 1x
|-
|}

Multiply your Average Load Current by the multiplier for your device type to calculate the Surge Current.

===I need to switch AC===

Most AC applications will be switching 110 to 240 Volt power coming from the grid. If that's you, go to the [[#Mains Voltage (110 to 240V AC)|Mains Voltage (110 to 240V AC)]] section.

We also cover low voltage AC applications - 28 VAC (Volts AC) or less. For more information, visit the [[#AC/DC SSRs|AC/DC SSRs]] section.

===I need to switch DC===

If you only need to switch a small amount of current - 9 Amps or less, consider our compact, cost effective [[#AC/DC SSRs|AC/DC SSRs]].

If you need to switch more than 9 Amps, you need a serious [[#DC SSRs|DC SSR]].

If you need to switch up to 16 small loads of 2 Amps or less, you can use the [[Open Collector Digital Output Primer|open collector digital outputs]] on a [[1012_2 - PhidgetInterfaceKit 0/16/16|1012 PhidgetInterfaceKit 0/16/16]], which can be wired to behave similarly to relays.

==I need Gradual Dimming==

Instead of simply turning the load on/off, if you want to dim it gradually, you can use a proportional control SSR. They are able to reduce the average power to the load gradually, in proportion to the strength of the input signal. For more information, you can visit the [[#Proportional Control SSR|Proportional Control SSR Section]].

==Mains Voltage (110 to 240V AC)==

We sell AC SSRs for 120 VAC or 240 VAC operation. If you are unsure what voltages you could eventually need to switch, the 240 VAC relays can be used to switch 120 VAC with no problems. Please note we are very conservative in how we rate SSRs - our 120 VAC relays are rated by the manufacturer for 240 VAC, and the 240 VAC for 480 VAC. We strongly recommend against using them to the manufacturer rated voltage. To understand why, read the [[#AC SSR Protection|AC SSR Protection]] section.

===Load Type - Inductive vs. Resistive===

[[Image:zero cross.png|right|thumb|300px|This graph shows the difference between zero-cross and random turn-on. The blue line represents the oscillating voltage of an AC load, and the shaded areas represent the sections when the relay is turned on and letting current pass through. As you can see, the random turn-on SSR immediately opens when activated, while the zero-cross turn-on SSR waits until the voltage crosses zero before opening.]]

If your load is inductive, you need to choose a '''Random Turn On''' relay. If your load is resistive, choose a '''Zero Crossing''' relay.

Your Load will probably be inductive if it is built around a large coil of wire - motors and transformers are typical examples. A load considered resistive may also have loops of wire - for instance, hair dryers, toasters, incandescent bulbs use twisted wire elements to generate the heat. An inductive load will have thousands of loops of wire - it's a matter of scale. There is no such thing as a perfectly resistive load - but a load has to be very inductive to cause the zero crossing SSRs to malfunction.

SSRs are designed to either turn on immediately ('''Random Turn On'''), or wait until the next 'alternation' of the voltage ('''Zero Crossing'''). Zero Crossing SSRs create less electromagnetic 'noise' when they turn on. They are best used with resistive loads - Zero Crossing SSRs are not able to turn off some inductive loads. It's very difficult to determine which inductive loads will create problems - well beyond the scope of this document. If your load is inductive, we recommend buying the '''Random Turn On''' SSRs.

{|border=1
|+ '''Inductive and Resistive Loads'''
! Application
! Load Type
|-
| Incandescent Light Bulbs || Resistive
|-
| Fluorescent Light Fixtures || Inductive or Resistive <font size=4>'''*'''</font>
|-
| Motors || Inductive
|-
| Transformers || Inductive
|-
| Heaters || Resistive
|-
| Computer / Electronics || Resistive
|-
| AC/DC power supplies (brick heavy type) || Inductive
|-
|AC/DC Power supplies (lightweight switchers) || Resistive
|}

<font size=4>'''<nowiki>*</nowiki>'''</font> ''For fluorescent light fixtures, older units (magnetic ballast) may be inductive, and newer units are often resistive (electronic ballast).''

===Choosing your AC SSR===

Now that you have identified your Operating Voltage, Average and Surge Current, and your load type (inductive or resistive), you can create a short list of relays whose
* '''Maximum Load Voltage''' are greater than or equal to your operating voltage,
* '''Maximum Surge Current''' are greater than or equal to your surge current, and
* '''Load type''' matches what you chose for random turn on/zero crossing.

<font color=green> < Table: +ac_ssr > </font>

{|border=1
! Phidgets Product #
! Manufacturer Part #
! Current Type
! Turn-on Type
! Control Voltage (V)
! Max. Load Voltage (V)
! Max. Load Current Without Heatsink (A)
! Max. Load Current with 3955 Heatsink (A)
! Max. Load Current with 3956 Heatsink (A)
! Max. Surge Current (A)
! Output Type
|-
| 3953_0 || HFS34/D-240A20PS-Y || AC || Random Turn-on || 3-32VDC || 120 || 8 || 15 || 20 || 255 || SCR
|-
| 3954_0 || HFS34/D-240A80PS-Y || AC || Random Turn-on || 3-32VDC || 120 || 10 || 20 || 50 || 800 || SCR
|}

Now compare the '''Max. Load Current without Heatsink''' value for the SSRs on your list to your Average Load Current. If your Average Load Current is greater, you may need a heatsink. For selecting a heatsink, please consult [[#Picking a heatsink|Picking a Heatsink]]. Alternatively, look at other SSRs on your list - there may be an SSR that can handle your average load current with no heatsink.

At this point, you know the SSR you need.

Instead of simply turning the load on/off, if you want to dim it gradually, you can use a proportional control SSR. They are able to reduce the average power to the load gradually, in proportion to the strength of the input signal. For more information, you can visit the [[#Proportional Control SSR|Proportional Control SSR Section]].

If you are interested in learning more about SSRs in general, check out our [[#Did you know?|"Did you know?"]] section.

===AC SSR Protection===

[[Image:MOV.jpg|thumb|An MOV, which comes packaged with our AC "Hockey Puck" relays. ]]

Your AC SSR from Phidgets comes with a circular disc with two legs (pictured). This is a Metal Oxide Varistor (MOV) and should be installed across the load (larger) terminals of your SSR. MOVs are the classic surge protector - an inexpensive component that absorbs high voltage spikes. High voltage spikes are caused by inductive loads when they are turned off, and also happen very often on the electrical grid, as nearby devices are operated. Even if your load is resistive, use an MOV to protect the SSR.

Matching an MOV to an SSR is not easy - this is why we include an MOV with your SSR. If an MOV is chosen for too low of a voltage spike, it will wear out quickly. If it is chosen for too high of a voltage spike, it will not protect the SSR adequately. To balance SSR protection against MOV lifetime, we have found it necessary to use SSRs built for 240 VAC in 120 VAC applications, and SSRs built for 480 VAC in 240 VAC applications. If you must operate our AC SSRs on higher voltages than we recommend, do not use the included MOV.

As MOVs wear out from use, they will become more sensitive to common voltage spikes, causing them to wear out quicker. When they entirely fail, they will become a short circuit, potentially creating a fire hazard. The MOV included with your SSR has a fuse built in which will disable the MOV when it becomes a hazard. To be on the safe side, avoid mounting your SSR near any flammable material.

===Proportional Control SSR===

Proportional Control Relays (often simply called "Control Relays") are SSRs you can use to control the amount of power to the load. Rather than reduce the voltage, or somehow limit the current - which would be very expensive solutions, the Proportional SSR reduces power by turning the load on/off quickly, feeding full power in short pulses.

Proportional SSRs are controlled by a variable voltage - as the control voltage increases, more power is available to the load. Our PhidgetAnalog product can be used to control Proportional SSRs, since an [[Analog Output Primer|analog output]] can output various amounts of voltage, as opposed to a digital output, which only has two states- high and low. We don't sell Proportional SSRs - but they can be purchased from [http://www.digikey.com Digikey], where they are called AC Linear Controlled SSRs.

A quick and dirty solution for dimming with Phidgets is to use an [[Servo Motor and Controller Primer|RC Servo Motor]] with a PhidgetAdvancedServo controller to rotate the knob on a light dimmer. From software, the RC Servo Motor is rotated to the desired position, cranking the knob as it turns. While this may seem like a roundabout way of achieving proportional control, dimmers tend to be much less expensive because they are less specialized and are manufactured in greater quantity.

===Example circuits with AC SSRs===

[[Image:AC SSR Load.png|right|thumb|300px|Schematic of an AC SSR switching a generic load. A metal oxide varistor is added across the load to protect the SSR.]]

When wiring up an AC circuit, particularly for long term installation, you may find it helpful to buy a book on residential wiring from your local hardware store. There are many wiring conventions (and often legal codes) which will help you plan your project, and the legal codes are often a great source of wisdom.

<br clear="all">

==DC SSRs (0 to 50V DC)==

We sell DC SSRs for that switch a maximum load of 50 volts. If you are unsure what voltages you could be switching in the future, higher voltage DC SSRs can be used to switch lower voltages. Common engineering practice would be to purchase an SSR rated for 50-100% higher voltage than the voltage you plan to be switching. For instance, if you are switching 24V, a 50V SSR is reasonable.

===Choosing your DC SSR===

Now that you have identified your Operating Voltage, Average and Surge Current, you can create a short list of relays whose
* Maximum Load Voltage are greater than or equal to your operating voltage,
* Maximum Surge Current are greater than or equal to your surge current, and
* Maximum Average Current is greater than or equal to your Average current.

<font color=green> < Table: +dc_ssr > </font>

{|border=1
! Phidgets Product #
! Manufacturer Part #
! Current Type
! Turn-on Type
! Control Voltage (V)
! Max. Load Voltage (V)
! Max. Load Current Without Heatsink (A)
! Max. Load Current with 3955 Heatsink (A)
! Max. Load Current with 3956 Heatsink (A)
! Max. Surge Current (A)
! Output Type
|-
| 3950_0 || HFS33/D-30D50M || DC || N/A || 3-32VDC || 30 || 18 || 50 || 50 || 120 || MOSFET
|-
| 3951_0 || HFS33/D-50D80M || DC || N/A || 3-32VDC || 50 || 20 || 40 || 80 || 200 || MOSFET
|-
| 3952_0 || HFS33/D-30D100M || DC || N/A || 3-32VDC || 30 || 25 || 50 || 100 || 240 || MOSFET
|-
|}

Now compare the '''Max. Load Current without Heatsink''' value for the SSRs on your list to your Average Load Current. If your Average Load Current is greater, you may need a heatsink. For selecting a heatsink, please consult [[#Picking a Heatsink|Picking a Heatsink]]. Alternatively, look at other SSRs on your list - there may be an SSR that can handle your average load current without a heatsink. SSRs rated for a larger load than the load you're using will be more efficient (meaning less energy lost in the form of heat) than an SSR that's being operated at its maximum load.

At this point, you know the SSR you need.

If you are interested in learning more about SSRs in general, check out our [[#Did you know?|"Did you know?"]] section.

===DC SSR Protection===

[[Image:Diode.jpg|thumb| A diode, included with our DC "hockey puck" SSRs. The cathode is marked with a line. The blue symbol shows circuit diagram equivalent of the diode.]]

[[Image:relaymotor.jpg|thumb| A DC SSR switching an electric motor. The 1018 Phidget InterfaceKit controls the SSR using its digital outputs. A diode is shown installed across the motor, and a fuse is hooked up between the power supply and the rest of the circuit.]]

Your DC SSR from Phidgets comes with a diode. This diode should be installed across your load, with the Cathode installed towards the positive terminal of the power supply (as shown in the diagram).

If the diode is installed backwards, as soon as the SSR is turned on, the load will be shorted out, likely destroying the diode, or the SSR, or your power supply.
A fuse protecting your power supply is always a good idea. You can place the fuse in between the positive terminal of the power supply and the positive terminal of the load side of the SSR.

The diode protects the SSR from powerful residual currents after the SSR is turned off. While your load is being driven, inductance builds up magnetic fields around the wiring.
Every load is inductive to some degree, and when the SSR turns off, the magnetic fields will ram current against the now open SSR, easily damaging it. The diode allows these currents to recirculate in the load until they have lost their energy.

<br clear="all">

===Example circuits with DC SSRs===

[[Image:DC SSR Load.png|right|thumb|300px|Schematic of an DC SSR switching a generic load, which is protected by a diode connected in parallel. The circuit is protected by a fuse in series after the power supply.]]

The electrical isolation built into a DC SSR allows them to be placed within a circuit just like a switch. Since it is isolated, you don't have to worry about grounding or voltage offsets.

With a DC SSR, always make sure the positive load terminal (labeled +) is facing towards the positive terminal of the power supply. If the load terminals are reversed, your load will immediately turn on. There is a diode inside of the SSR that allows current to flow freely through it when the SSR is connected incorrectly. This feature is included because this sort of wiring mistake would destroy the transistor in the DC SSR otherwise.

The DC SSR can be installed on either side of the load, and it will work properly, but there is an advantage to installing the SSR between the power supply and the load. If the load is connected to the power supply, it will always have a potentially dangerous voltage on it, even when it is not operating.

<br clear="all">

==AC/DC SSRs (0 to 40V DC / 0 to 28V AC)==

[[Image:AC_DC_SSR.png|thumb|A small, versatile AC/DC SSR mounted on a Phidgets board for easy pin access.]]

Our AC/DC SSRs are built on a small PCB, making them physically smaller than the large "hockey puck" SSRs, and less expensive. They are limited to lower currents, and cannot be mounted on a heatsink.

We sell AC/DC SSRs that can switch up to 40 Volts DC or 28 Volts AC. This is indicated on the SSR Product pages under the Maximum Load Voltage specification. There is no lower limit on the voltages that the AC/DC SSRs can switch. If your voltage is close - be conservative. For instance, a 36 Volt system built from 3 Lead Acid batteries can reach 45 volts when charging.

===Picking your AC/DC SSR===

Now that you have identified your Operating Voltage, Average and Surge Current, you can create a short list of relays whose
* Maximum Load Voltage are greater than or equal to your operating voltage,
* Maximum Surge Current are greater than or equal to your surge current, and
* Maximum Average Current is greater than or equal to your Average current.

<font color=green> < Table: +versatile_ssr > </font>

{|border=1
! Phidgets Product #
! Manufacturer Part #
! Current Type
! Turn-on Type
! Control Voltage (V)
! Max. Load Voltage (V)
! Max. Load Current Without Heatsink (A)
! Max. Load Current with 3955 Heatsink (A)
! Max. Load Current with 3956 Heatsink (A)
! Max. Surge Current (A)
! Output Type
|-
| 3052_0 || N/A || AC/DC || N/A || ??? || 40DC or 28AC || 2.5 || N/A || N/A || 5 || MOSFET
|-
| 3053_0 || N/A || AC/DC || N/A || ??? || 40DC or 28AC || 9 || N/A || N/A || ??? || MOSFET
|}

If you are interested in minimum cost, you will likely choose the cheapest option that meets these criteria. If you are interested in high efficiency operation and less heat generation, consider buying an SSR with higher current rating.

Your AC/DC SSR from Phidgets has built in protection from static electricity, and dangerous residual currents after the SSR is turned off. If the load you are switching is powered by a DC source, installing a diode across the load will offer even more protection. Refer to the [[#DC SSR Protection|DC SSR Protection]] section for more information.

To learn more about SSRs in general, visit the [[#Did you know?|"Did you know?"]] section.

<br clear="all">

===Example circuits with AC/DC SSRs===

[[Image:Versatile SSR DC Load.png|thumb|A versatile AC/DC SSR switching a DC load. The load terminals are bidirectional, so it doesn't matter which way you hook them up. The optional diode can be added to help protect the SSR when switching DC loads.]]
[[Image:Versatile SSR AC Load.png|thumb|A versatile AC/DC SSR switching an AC load.]]

The electrical isolation built into a AC/DC SSR allows them to be placed within a circuit just like a switch. Circuits without electrical isolation require a lot more care - proper grounding, careful consideration of voltage offsets.

<br clear="all">

==Using heatsinks with Hockey Puck SSRs==

[[Image:3950_0 Accessories Web.jpg|thumb|A "hockey puck" SSR with plastic cover (left), a thermal pad (right). All hockey puck SSRs sold at Phidgets come with both of these accessories plus a diode or varistor to protect the SSR.]]
[[Image:3955_0 Functional Web.jpg|thumb|A "hockey puck" SSR mounted on a [[3955]] heatsink by two screws. The thermal pad is pressed between the SSR and the heatsink.]]

SSRs will only achieve their promise of reliability and long life if they are kept cool. Cool is relative, of course, but a good rule of thumb is to keep the metal base of the SSR at less than 85°C (185°F). A [[Thermocouple Primer|thermocouple]] can be used to precisely measure the temperature of the metal base.

Excess heat usually comes from too much current and too little heatsinking. A lot of heat can also be generated by frequently turning the relay on and off. If your relay is operated for brief periods of time, you may not need as large of a heatsink - provided the relay is never accidentally left on for extended periods. Unless space is a concern, it's better to err on the side of caution.

Before buying a heatsink, consider if you actually need it. If your application is running at room temperature, and your average current is less than the '''Max. Load Current without Heatsink''' specification of your SSR, then you don't need a heatsink. Alternatively, if your project has a large metal chassis that the SSR can bolt to, this can be used as your heatsink.

Each SSR suitable for use with heatsinks will include a specification of how much current it can switch with each heatsink we sell. This specification assumes a reasonable airflow over the heatsink, and that the flowing air is at room temperature. Our SSRs have a sheet of metal underneath, where the heat is concentrated - this is also where the heat is measured to tell if the SSR is too hot. Phidgets includes a grey thermal pad with our Hockey Puck SSRs (see pictured). You place this pad under an SSR when mounting it on a heatsink, or on large metal surfaces that can dissipate heat. The pad performs the same function as thermal grease - it helps conduct heat between the base of the SSR and the heatsink. If you prefer to use thermal grease, you can use it instead of the pad. Our heatsinks include screws for mounting SSRs. Use a good size screwdriver when tightening the SSR down on the heatsink to ensure good conduction.

{|border=1
! Phidgets Product #
! Product Name
! Manufacturer Part #
! Dimensions (mm)
! Thermal Resistance (C/W)
|-
| 3955_0 || Small Heatsink for SSR || HF92B-80 || 50x50x80 || 2.4
|-
| 3956_0 || Large Heatsink for SSR || HF92B-150A || 55x142x150 || 0.6
|-
|}

<br clear="all">

==Hooking up wires to the Hockey Puck SSR==

[[Image:relay_mov.jpg|thumb|An AC SSR with the wires attached normally and an MOV installed across the load side.]]
[[Image:lugs.jpg|thumb|TRM6 wiring lugs connected to a DC SSR.]]

When wiring your load to the SSR, the wire is looped clockwise around the terminal, so when the screw is tightened down, it will draw the wire in tighter. We recommend using wires up to 10 AWG in size - any larger, and the screws will not have enough thread left to tighten down, and they will strip. Larger wires can be attached using a wiring lug. The lug is clamped under the SSR screw, and the wire attaches to the lug.

Loose wire connections can generate a lot of heat - use a large enough screwdriver when clamping down the load wires to ensure that the screws are on tight enough.

For the current ratings of various wires sizes, please see [[Page on Wire Sizes]].

<br clear="all">

==Did you know?==

* Mains Voltage '''AC SSRs''' cannot switch DC. They will never turn the load off. AC SSRs turn off twice per AC Cycle, when the current changes direction and is momentarily zero. For example, AC is 60 Hz in North America, so the AC SSR has 120 opportunities per second to turn off (the SSR will only '''stay''' off if the control signal is low). If the SSR is operating from DC, the current will flow continuously, and the load will not turn off, even when the control input is off.

* An '''AC SSR''' turns off automatically every time the load current reaches zero. It will turn back on almost immediately as long as the signal controlling the SSR is high. An AC SSR will actually have a low, non-zero current value that it regards as 'zero'. This specification is usually called "Minimum Load Current" in the data sheet. If your load requires less than this minimum current, your SSR will never turn on, or will not reliably turn on. The simplest solution to this problem is to connect another load in parallel with the first, increasing the Current required by the load.

* SSR Manufacturers have started adding a simple circuit inside '''AC SSRs''', across the load terminals, called a snubber. The snubber absorbs very fast electrical changes that could normally cause an '''AC SSR''' to turn on accidentally. When the AC SSR is turned on, there is little voltage difference between the terminals, so the snubber has very little effect. When the AC SSR is turned off, the snubber is actively protecting the SSR - but at a cost, as it allows a small current through the SSR, which is wasted.

* An '''AC SSR''' uses bipolar transistors - an old technology that has been replaced by CMOS transistors in modern digital circuits. Bipolar transistors are still superior for handling high voltages. Bipolar transistors, and the more complex transistors built from them, will lose a constant voltage as current flows through them. The collection of transistors in your SSR will lose about 1.7 volts - so on a 120 VAC system, you will lose about 1.5% to the SSR. This energy converts to heat inside the SSR, and the heating from these transistors is the reason SSRs often need heatsinks.

* SSRs, and semiconductors in general, usually fail as a short circuit. A short circuit is a circuit whose internals have been damaged such that current can flow through it freely. This means your load will probably turn on permanently (until you disconnect the power source) - make sure this doesn't cause a safety hazard. For instance, Sauna Heaters have a simple thermally-triggered mechanical shutdown to protect them if control electronics fails.

* '''DC SSRs''' (at least the units we sell) use Metal Oxide Semiconductor Field Effect Transistors (MOSFETs). MOSFETs do not lose a constant voltage - instead, when they turn on, they act as a very slight restriction to the flow of current - a resistor. At low currents, the slight restriction wastes very little power, giving high efficiency and often not requiring a heatsink. This efficiency is lost as the current increases - a doubling of current quadruples the production of heat.

* Normally, a MOSFET can only block current in one direction - as soon as the voltage reverses, the current flows through a diode run in parallel to the MOSFET. If a MOSFET were used to switch AC, the load would be turned on half the time. A common solution is to use two MOSFETs back to back - which is what we do with our '''AC/DC SSRs'''.

OS - Phidget SBC

2012-06-29T20:42:26Z

Cora:

[[Category:OS]]
{{OSLang|[[File:icon-Linux.png|64x64px|link=OS - Linux]]|On the Single Board Computer (SBC), Phidgets can be either plugged directly into one of the USB ports or run over a network using the [[#WebService | WebService]].}}
__TOC__

==Quick Downloads==

Unlike our other supported operating systems, the SBC '''does not require downloads''' unless you are doing something advanced like loading the firmware or developing your own kernel. You will know if you need these downloads, otherwise, the SBC should work as described on the [[1072_-_Getting_Started|SBC2 Getting Started Guide]] right out of the box.

*[{{SERVER}}/downloads/libraries/phidgetsbc2.bin SBC2 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
*[{{SERVER}}/Drivers_Info.html#SBC2 License]

Note that, instead of using the firmware to update your SBC, updates should normally be done via the System -> Packages page on your SBC2 web interface. It is rarely necessary to completely re-flash your device.

==Getting Started with the Phidget SBC Debian Linux==

The Single Board Computer (SBC) is a unique Phidget. It is a computer with a Linux operating system. It can compile code, save files, manage background jobs, host information over the web, and more.

'''If this is your first time''' using the Phidget SBC, you will want to start with the [[1072 - Getting Started | Getting Started Guide for the SBC]]. After that, here we will get you started on topics beyond those in the getting started guide, including how to write Phidget code to run on the SBC. You '''do not need this page''' if you are simply using the SBC to broadcast data from Phidgets over the network - it does that automatically. We describe how to verify and use this in the [[1072 - Getting Started | Getting Started Guide]].

This page will show you how to:
* Install the ability to write and develop code on the SBC itself
* Use the command line for basic coding tasks
* Troubleshoot the SBC's network
It will also give additional specifications, which are useful for doing more advanced things with the SBC hardware and software.

Before reading this page, you should have done the following via the Getting Started Guide:
* Set up networking on your SBC, via either Ethernet or wireless
* Set up an admin password
* Learned the IP address or link local address of the SBC
We will use this information in setting up the libraries and drivers to use the SBC for writing and running code.

Conceivably, you could simply use the SBC like any Linux computer, and do all of your development and compiling of Phidget code on the SBC itself. In practice this gets complicated as the SBC does not have a keyboard or screen. So usually, you will want to develop your code an external computer and copy files and settings over to the SBC via a network. This makes this Getting Started section unique, in that we show you how to set up both computers:
* Your [[#Getting Started - External Computer | External Development Computer]], usually your main desktop or laptop which will transfer files and settings to and from the SBC
* The [[#Getting Started - The SBC (Debian Linux) | SBC]] itself, which needs programming language libraries to use Phidgets.

===Getting Started - External Computer===

You have two ways to connect to the SBC from an external computer: via the [[#SBC Web Interface|SBC Web Interface]] and over the more powerful but complex [[#SSH | Secure Shell (SSH)]].

====SBC Web Interface====

You have already worked extensively with the web interface in the [[1072 0 - Getting Started | Getting Started Guide for the SBC]]. This was the tool within a web browser which was opened either via the Phidget control panel on Windows, or by simply entering the IP or link local address into an internet browser. It allowed you to set the password, set up internet connectivity, and so on.

This section doesn't have more information on the interface; rather, it simply serves as a reminder that you have the web interface as an available tool. Examples, including screenshots, are placed where appropriate in this document. The web interface will probably stay your initial go-to way to connect to the SBC, especially for tasks that benefit from graphical interaction, like setting up wireless or using the webcam.

====SSH====

The most flexible way to transfer files and commands to and from the SBC is via a program called '''ssh'''. The ssh program provides command line text access over a network into the SBC. Using it, you can run programs and give the SBC commands. The ssh program has a companion program called '''scp''' which can copy files back and forth. If you are unfamiliar with ssh, you can think of it like the command line or a Mac terminal, but with a remote connection to a different computer. It is a minimal yet effective way to interact with a remote computer.

Before connecting over ssh, you will need:
* The '''IP address''' (such as 168.254.3.0) or '''link local address''' (such as phidgetsbc.local) of the SBC
* The '''admin password''' for the SBC
Both of these items can be found by following the steps in the [[1072 0 - Getting Started | Getting Started Guide for the SBC]].

You will also need to enable SSH on the SBC side. This can be done through the [[#SBC Web Interface| Web Interface]], under {{Code|Network → Settings}}, by changing the ''SSH Server'' radio button to ''Enabled'' and saving your changes:

[[File:sbc_turn_on_ssh.png|link=|alt=]]

=====SSH on Windows=====

The ssh program is not installed on Windows by default. But, there are a variety of SSH programs available for free. One simple and commonly used program is [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY], and it has the advantage that the executable doesn't need to install, it just runs.

With PuTTY, when you first run the program it will ask you what to connect to. Enter the IP address or link local address of the SBC, and then click the SSH radio button right below the address, which will change the port to 22. Then click open, and you'll have an ssh connection to the SBC open in a terminal. It will prompt you for a user name ({{Code|root}}) and password (the admin password).

To copy files back and forth, there is an SCP component to PuTTY, called PSCP, which is available from the same [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY download page]. Use of PSCP will be similar with the address, username, and password, except that you will be transferring files instead of sending commands.

=====SSH on Linux and Mac OS=====

Linux and Mac OS already have ssh installed by default. To run ssh simply open a terminal...
* {{Code|Ctrl-Alt-T}} on Linux
* {{Code|Applications → Utilities → Terminal}} on Mac OS
...and type:

<div class="source">
<syntaxhighlight lang=bash>
ssh root@phidgetsbc.local
</syntaxhighlight>
</div>

If you have re-named your SBC, include that name instead of the {{Code|phidgetsbc.local}} link address. Or, you can use the SBC's IP address, e.g. something like {{Code|ssh root@168.254.3.0}}

To copy files back and forth, the command follows the form of: {{Code|scp from to}}

So, to copy a file {{Code|/root/data.txt}} from the SBC to your local machine, type:

<div class="source">
<syntaxhighlight lang=bash>
scp root@phidgetsbc.local:/root/data.txt .
</syntaxhighlight>
</div>

Note the use of the dot '''.''' to indicate that scp should put the file in the current local directory. If you're not sure what folder the terminal is operating in type {{Code|pwd}} to print the working directory. Terminals usually start by default in your home folder.

===Getting Started - The SBC (Debian Linux)===

The SBC runs Linux, which is a full operating system. It is stripped down compared to a full desktop release of Linux, but you can compile code on it, run programs, schedule tasks, create and manage files, run a web server, and much, much more.

At this point you have connected to the SBC via the [[#SBC Web Interface|web interface]], and probably also through [[#SSH|SSH]]. This section will help you install libraries and drivers that you probably want - i.e. support for C, Java, and Python. After this section, you'll be well into the depths of using the SBC as a computer, and so you'll probably want to keep the [[#Using SBC Linux|Using SBC Linux section]] open for reference while you work if you are not already familiar with Linux.

The SBC comes with the following Phidget functionality installed:
* The Phidget C libraries {{Code|libphidget21.so}}
* The Phidget [[#WebService | WebService]]
(If you are simply curious what these are and how they get installed, we describe the process on the [[OS - Linux | general Linux page]].)

But to compile C programs, or run Java programs, or use Python, you will need to install these languages onto the SBC.

Before installing anything on the SBC, however, (even via a button on the web interface) make sure that the ''Include full Debian Package Repository'' option is checked in the web interface under {{Code|System → Packages}}.

====Installing C/C++ and Java====

The simplest way to install C/C++ and Java on the SBC is via the web interface. There is a button under {{Code|System → Packages}} to install C support (including {{Code|gcc}}) and another button to install Java support:

[[File:sbc_packages_web.png|link-|alt=]]

Now you're ready to begin programming. We have programming pages for both [[Language - C/C++|C/C++]] and for [[Language - Java|Java]]. Remember that if you're unfamiliar with Linux, we have help on using files and running programs automatically in the [[#Using SBC Linux|Using SBC Linux section]].

If you want to avoid using the [[#SSH|SSH]] interface on the SBC entirely, and you want to write your program in Java and run it continuously from boot (which is the only option if you want to avoid [[#SSH|SSH]]), we have a [[#Program in Java with the Web Interface|very in-depth section]] on that topic.

====Installing Python====

Installing Python has two steps. First, you'll need to install the basic ability to run python, and then you'll need to install the Phidget Python module. Both steps (and both options) require that you issue the relevant commands through an [[#SSH|SSH terminal]].

=====Basic Python=====

The base Python functionality can be downloaded and installed in one step with [[#apt|apt]] (i.e. in a terminal, type):

<div class="source">
<syntaxhighlight lang=bash>
apt-get install python
</syntaxhighlight>
</div>

This will give you Python, and now you just have to install the Phidget Python module to gain Phidget functionality.

=====Install Phidget Python Method 1: Use a USB Key=====

Copy the [{{SERVER}}/downloads/libraries/PhidgetsPython.zip Python Libraries] onto a USB key. Unpack the zip file into a folder on the USB key. Insert the key into the SBC.

You will have to figure out where the USB key (and the Phidget Python library folder) is now located. We describe how in the general [[#Using USB Data Keys | Using USB Data Keys]] section.

After you know the place where the USB key is mounted, in a terminal go to that directory (e.g. type {{Code|cd /media/usb0/}}), enter the unpacked Phidget Python Library folder, and run:

<div class="source">
<syntaxhighlight lang=bash>
python setup.py install
</syntaxhighlight>
</div>

Now, you're ready to begin writing Python code for the SBC. For more help on writing and using Python with Phidgets, we have an whole [[Language - Python | page on that topic]]. Remember that if you're unfamiliar with Linux, we have help on using files and running programs automatically in the [[#Using SBC Linux|Using SBC Linux section]].

=====Install Phidget Python Method 2: Use the Internet=====

Rather than using a USB key to transfer the file, the SBC can download it directly from the internet. You will need {{Code|wget}} and {{Code|unzip}} installed, both of which are small:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install wget
apt-get install unzip
</syntaxhighlight>
</div>

Copy the web link address for the [{{SERVER}}/downloads/libraries/PhidgetsPython.zip Python Libraries].

In an SSH terminal to the SBC, type: {{Code|wget http://www.python_library_link}} where instead of http://www.python_library_link you insert the link you just copied. Copying into a terminal can usually be done via the right-click menu.

This will download the Phidget python libraries to the folder you ran the {{Code|wget}} command in. Unzip the downloaded file using the command {{Code|unzip file}}, where file is the filename from {{Code|wget}}. Or try typing {{Code|ls}} to list the names of a file in the directory, which should include the unzipped folder. Enter the unzipped folder (e.g. use {{Code|cd}} to change directory), and install the Phidget Python libraries:

<div class="source">
<syntaxhighlight lang=bash>
python setup.py install
</syntaxhighlight>
</div>

Now, you're ready to begin writing Python code for the SBC. For more help on writing and using Python with Phidgets, we have a whole [[Language - Python | page on that topic]]. Remember that if you're unfamiliar with Linux, we have help on using files and running programs automatically in the [[#Using SBC Linux|Using SBC Linux section]].

====Installing Other Languages====

You may also be able to program on the SBC using [[Language - Ruby|Ruby]] and [[Language - C Sharp|C# under Mono]], though we do not offer in-depth support for these languages on the SBC. The installation procedures should more or less follow that of [[#Installing Python|installing python]] on the SBC, except you will be installing Ruby or Mono. Performing package searches using [[#apt|apt cache search]] can help you find the relevant software.

For C#, as of 2012 the {{Code|mono-complete}} package is broken on the Debian Squeeze repository. Rather, you have to install the Mono runtime and Mono compiler separately.

To install the runtime package (and its dependencies), use [[#apt|apt]]:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install mono-runtime
</syntaxhighlight>
</div>

Then, to install the C# compiler:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install mono-gmcs
</syntaxhighlight>
</div>

Or the Visual Basic compiler:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install mono-vbnc
</syntaxhighlight>
</div>

Then, the system and library packages do not link correctly for the version 2.0 of Mono. If this is the case, your code will compile fine, but when you try to run it, you will get an error like:

:{{Code|The assembly mscorlib.dll was not found or could not be loaded.}}
:{{Code|It should have been installed in the `/usr/lib/mono/1.0/mscorlib.dll' directory.}}

In this case, you need to install these two packages:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install libmono-corlib1.0-cil
apt-get install libmono-system1.0-cil
</syntaxhighlight>
</div>

Here we found these packages to work by working through the tree structure. As a general rule, you can find these dependencies by using install (here, {{Code|apt-get install mono-complete}}) to get a sense of the package tree structure. This will possibly tell you that the packages are broken, but at the same time this will list the dependencies of the packages. Trying to install individual dependencies will show you that although a root-package fails, the sub-packages will sometimes succeed, and install what you need.

If you want to use a specific dll or library that is not available in this reduced version of mono, you can install mono complete by switching from Emdebian+Debian to just Debian. To do this:

In {{Code|/etc/apt/preferences}} make the following changes:
:{{Code|Package: *}}
:{{Code|<nowiki>Pin: release a=stable</nowiki>}}
:{{Code|Pin-Priority: 1010}}

In {{Code|/etc/apt/sources.list/mutistrap-debian.list}} remove the emdebian line.

Apply the changes:

<div class="source">
<syntaxhighlight lang=bash>
apt-get update
apt-get dist-upgrade
</syntaxhighlight>
</div>

Many packages will be 'downgraded' from the emdebian to debian versions. Delete the {{Code|<nowiki>/etc/apt/preferences</nowiki>}} file and install mono-complete:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install monodoc-http mono-complete
</syntaxhighlight>
</div>

Choose monodoc-http explicitly, because otherwise the install fails on monodoc-browser.

After this process, you can compile your C# Code.cs Phidget source file the same way as on a generic [[Language - C Sharp#Linux|Linux with Mono]] system. Please refer to that page on how to obtain the *.dll Phidget resource file and compile your code. On the SBC, however, because you are already running as root (the Super User), you do not need 'sudo' and indeed the SBC will give you an error if you use it. Instead, compiling and running will look like:

<div class="source">
<syntaxhighlight lang=bash>
gmcs Code.cs -r:Phidget21.NET.dll
mono Code.exe
</syntaxhighlight>
</div>

==Using SBC Linux==

Now that you've set up communication with the SBC, and installed whichever programming language support you need, you're probably ready for a short tour of useful tools on the SBC's version of Linux.

First, you will by default be running on the SBC as '''root''', which is the super-user. For Linux users, this probably makes you nervous because you know you can overwrite important system files without the system asking for additional permission. As a Windows or Mac OS user - although you may usually run your computer as an administrator - your familiar system usually prompts you to confirm before you do anything really dangerous, and this will '''not''' happen on the SBC as the root user.

Next, there is no installed help on the SBC. Help on Linux is usually called 'man pages' which is short for 'the manual pages'. On a full Linux system, usually if you need help with any command you can type, for example, {{Code|man ls}} and it will give you help with the program [[#ls|ls]]. But these help pages take up significant space, and they are widely available online. So, if you need more help with a certain command, you can always type {{Code|man command}} into your favourite search engine.

Finally, the SBC has no windowing system. For Linux users, this means no X-windows (Gnome, KDE, etc). And as a Windows or Mac user, you can think of it as running all of your programs and commands through the terminal or DOS prompt command line. The SBC provides all of the functionality of an operating system (e.g. process scheduling, file management, etc) but without any graphical interface. The only exception is the [[#SBC Web Interface|web interface]], which gives graphical access to a limited part of what the SBC can do.

===Some Useful Commands===

If you are doing more with the SBC than simply running pre-written programs [[#Writing a Phidget Program|in Java to run continuously from boot]], you will be interacting with the SBC's Linux operating system over the command line by using [[#SSH|SSH]]. This section discusses useful programs already installed on the SBC, and how to run them on the command line.

====ls====

The '''ls''' program lists the contents of a directory.

It will show both files and folders, but not files that start with a "." (these are hidden files on Linux).
*If you also want to show hidden files, use {{Code|ls -a}}
*If you want more information, such as size and date modified, use {{Code|ls -l}}
*Commands can be combined, like {{Code|ls -al}}

====cd====

The '''cd''' program changes to a new directory.

For example, {{Code|cd /root}} changes into the directory at the base of the file tree called ''root''.

Note:
* Linux uses forward slashes
* The base of all directories is "/" (not "C:\")
* The tilde symbol (~) is short for your home directory (i.e. when you are root, this is short for "/root")
* The double dot ".." means move one directory higher (for example from {{Code|/root/data/}} to {{Code|/root/}})

====pwd====

The '''pwd''' program prints the current directory you are working in. ('P'rint 'W'orking 'D'irectory)

For example:
:{{Code|root@phidgetsbc:~# pwd}}
:{{Code|/root}}

====cp, mv, and rm====

These programs are copy ('''cp'''), move ('''mv'''), and remove ('''rm''').

Copy copies a file from one location and pastes it to another.

For example, if you have a file {{Code|data.txt}}, typing {{Code|cp data.txt data_backup.txt}} will put a copy of the file {{Code|data.txt}} into {{Code|data_backup.txt}}

Move moves a file (this is also useful for renaming files) to a new destination.

For example, if you have a file {{Code|data.txt}}, typing {{Code|mv data.txt data_backup.txt}} will put the contents of {{Code|data.txt}} into {{Code|data_backup.txt}}, and then will remove {{Code|data.txt}}.

Remove deletes a file.

For example, typing {{Code|rm data.txt}} will delete {{Code|data.txt}}.

Note that '''rm''' is final. Once you remove a file using {{Code|rm}}, it is gone forever. There is no recycle bin, no temporary trash, nothing other than backups you may have personally created in the past!

Directories can only be removed with {{Code|rmdir}}, and then only if they are empty. If you want to remove a directory and all the files in it, use {{Code|rm -rf directory}} but be '''very, very careful''' with this command. Trying to remove everything within a directory (e.g. {{Code|rm -rf *}}) is one of the most dangerous commands you can run on a Linux system, as running it from the wrong directory will result in Linux happily removing everything under that directory -- which could be your entire filesystem.

====find====

The '''find''' program does what it says - it finds things.

Unfortunately for the casual user, the find program is very flexible and powerful, and thus not especially intuitive to use. But, here are some examples:

{| style="border:1px solid darkgray;" cellpadding="15px;"
|-
! SSH Command
! What it Does
! Example
|-
| {{Code|find folder -name file.txt}}
| Looks for all files in a folder (/ for root - or all - folders) with a certain name (* for wildcard)
| {{Code|find / -name *.jpg}}
|-
| {{Code|find folder -mtime +X}}
| Looks for all files in a folder modified less than X days ago
| {{Code|find /root -mtime +30}}
|}

====grep====

The '''grep''' program takes text input and searches for a term.

For example, if you type {{Code|mount}} to view what devices are mounted (e.g. loaded) on your SBC, you will see:

<div class="source">
<syntaxhighlight lang=text>
root@phidgetsbc:~# mount
tmpfs on /lib/init/rw type tmpfs (rw,nosuid,mode=0755)
proc on /proc type proc (rw,noexec,nosuid,nodev)
sysfs on /sys type sysfs (rw,noexec,nosuid,nodev)
udev on /dev type tmpfs (rw,mode=0755)
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev)
devpts on /dev/pts type devpts (rw,noexec,nosuid,gid=5,mode=620)
rootfs on / type rootfs (rw)
procbususb on /proc/bus/usb type usbfs (rw)
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

This may be a lot of information you don't need. If you are only interested in a USB key attachment (as described in the [[#Using USB Data Keys|Using USB Data Keys]] section), you can use grep to filter that one response:

<div class="source">
<syntaxhighlight lang=text>
root@phidgetsbc:~# mount | grep sda1
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

====nano====

The '''nano''' program is a small text editor that you can use within an SSH terminal.

Nano can be surprisingly useful for writing short lengths of code right on the SBC, so there is no need to transfer files and keep track of different file versions on different computers.

Nano has all keyboard commands which are listed at the bottom of the screen at all times as a reminder (Ctrl-O to save, Ctrl-X to exit, these expand with a larger terminal window). And, nano provides what is called 'syntax highlighting', which colours reserved keywords, comments, strings, and so on as appropriate to the programming language you are using. Nano detects the programming language via the extension of the file ({{Code|.java}} for Java, {{Code|.c}} for C/C++, and {{Code|.py}} for Python).

Typing {{Code|nano test.py}} on an SSH command line and then entering a few lines of Python into the new empty file results in:

[[File:sbc_nano_python.png|link=|alt=]]

====apt====

The '''apt''' program allows you to install, uninstall, upgrade, and search software available for the SBC.
For a non-Linux user, the apt framework may be daunting at first, but it actually allows you to keep your system up to date and install and manage software quickly, easily, and for free.

'''Note:''' Before installing anything on the SBC, make sure that the ''Include full Debian Package Repository'' option is checked in the web interface under {{Code|System → Packages}}.

{| style="border:1px solid darkgray;" cellpadding="15px;"
|-
! SSH Command
! What it Does
! Example
|-
| {{Code|apt-cache search term}}
| Looks for all programs (packages) that have {{Code|term}} in the title or description
| {{Code|apt-cache search opencv}}
|-
| {{Code|apt-cache show package}}
| Shows a lot of data about {{Code|package}} including size, version, etc
| {{Code|apt-cache show unzip}}
|-
| {{Code|apt-get update}}
| Gets the most recent listing of available software
| {{Code|apt-get update}} (No options)
|-
| {{Code|apt-get install program}}
| Installs {{Code|program}} from the internet
| {{Code|apt-get install python}}
|-
|}

====mount====

The program {{Code|mount}} shows you all of the mounted devices on your SBC.

For example:

<div class="source">
<syntaxhighlight lang="text">
root@phidgetsbc:~# mount
tmpfs on /lib/init/rw type tmpfs (rw,nosuid,mode=0755)
proc on /proc type proc (rw,noexec,nosuid,nodev)
sysfs on /sys type sysfs (rw,noexec,nosuid,nodev)
udev on /dev type tmpfs (rw,mode=0755)
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev)
devpts on /dev/pts type devpts (rw,noexec,nosuid,gid=5,mode=620)
rootfs on / type rootfs (rw)
procbususb on /proc/bus/usb type usbfs (rw)
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

For the non-Linux user, the concept of a device may be quite strange. To give a short summary, everything on Linux that you can read or write is a file. Webcams are files (i.e. you can 'read' photos from them), USB keys are files, and each filesystem (tmp storage, the kernel portion, the main filesystem) are also themselves files. These files specify what and how something can be written. These are not necessarily linear, for example, you can see above that the USB key ({{Code|/media/usb0}} is mounted ''within'' the root file system {{Code|rootfs}} which is /.

So mount gives you an idea of what devices have been 'mounted' for reading or writing, and how you can read and write to them. More information on mount (and its various forms, like {{Code|umount}}) is available widely around the Internet.

====which====

The program {{Code|which}} tells you if and where a program is installed.

For example, on a default SBC, typing {{Code|which python}} will return no results. But after successfully [[#Installing Python | installing python]], it will return {{Code|/usr/bin/python}} as the location of the python program/binary/executable.

===Some Useful Commands to Install===

These are other programs you may find useful on the command line. Although they are not on the SBC by default, these and other programs can usually be installed simply by using [[#apt|apt-get install]], with the exception of gcc. For example, {{Code|apt-get install wget}} will download and install [[#wget|wget]].

'''Note:''' This section and the section on [[#Some Useful Commands|pre-installed commands]] can hardly cover all of the complexities and power of the Linux operating system. There are many excellent tutorials online, and between them and using [[#apt|apt]] to find and install programs you should be able to learn a lot and perform any number of complex useful tasks.

====gcc====

The '''gcc''' program is the C compiler for Linux.

If you are an experienced C/C++ user on Mac or Linux, or if you've already read our [[Language - C/C++ | C Language page]], you might think you need to install gcc via {{Code|apt-get}} to compile C code. However, gcc is not in the package repository for the SBC, so {{Code|apt-get install gcc}} will fail. Rather, to install gcc, you can do it via the web interface, as described in the [[#Installing C/C++ and Java|Installing C/C++ and Java]] section.

After installing it via the SBC web interface, you can use {{Code|gcc}} normally.

====less====

The '''less''' program displays the contents of a text or source code file. When displaying the file, {{Code|less}} allows you to scroll up and down to read it.

This is useful if you are writing your sensor readings to a data file, and you want to read the data file while it is being written by your main code. If your data file is called {{Code|data.txt}}, you can type {{Code|less data.txt}} and see the lines in the file, and what they are.

The {{Code|less}} program output can also be piped into another program. For example, you can use {{Code|less}} and the word search program {{Code|grep}} to find lines within a file with a search term. For instance, if you have a C source code file {{Code|Program.c}} on the SBC, and you want to see all the lines in {{Code|Program.c}} that contain a variable name {{Code|var}}, you can type:
:<code>less Program.c | grep var</code>

====wget====

The '''wget''' program allows you to get an online file (over http) and download it to the SBC.

For example, to get the source file (HTML) from the Phidgets home page, you can type:

<div class="source">
<syntaxhighlight lang=bash>
wget http://www.phidgets.com
</syntaxhighlight>
</div>

This is most useful for downloading libraries, drivers, or anything (zip, tar, etc) you need from the web which is not available by [[#apt|using apt]].

===Writing a Phidget Program===

We provide two ways to write and upload a Phidget Program:
# The [[#SBC Web Interface|web interface]]:
#* This is useful for simple projects written in Java that you want to start only at boot
#* You can also use C projects, but they must be compiled off the SBC for an ARM processor
# Over [[#SSH|SSH]], which will allow you to write or transfer source code directly to and from the SBC
#* This is useful for all other projects, such as:
#** Projects that run at scheduled times (e.g. once per minute)
#** Projects that use languages other than Java or ARM-compiled C
Note that you can still run an [[#SSH|SSH]] project at boot, you just have to write and install a startup script. This is a bit complex, but we do have an example that starts the program {{Code|phidgetwebservice21}} [[OS - Linux#As A Service|at boot using a script]].

Once you know which method you'd like to use, you can continue on to learn how to [[#Program in Java with the Web Interface|Program in Java with the Web Interface]], or how to [[#Program with SSH|Program with SSH]] using Java, C, or Python. If you are actually typing in source code on the SBC, you'll find our [[#Developing Code on the SBC|developing code on the SBC section]] useful.

====Program in Java with the Web Interface====

To show how to write, compile, and install Java programs on the SBC, we'll use the [[Language - Java|Java Hello World]] example code. You can download the HelloWorld example by downloading the whole [{{SERVER}}/downloads/examples/JavaJNI.zip Java example package]. Make sure you have [[#Installing C/C++ and Java|Java installed on the SBC]].

Here's how to get the HelloWorld code running on the SBC. On your external computer:

1. Download the SBC version of the Phidget Java libraries ({{Code|phidget21.jar}}). You can download this from the [[#SBC Web Interface|web interface]], on the page under {{Code|Projects → Projects}}, under the '''Notes''' section.

2. Place the SBC version of {{Code|phidget21.jar}} into a directory on your external computer. This will be your working directory that you will use to compile the Java files.

3. Also copy the {{Code|HelloWorld.java}} file into that working directory.

4. Compile the {{Code|HelloWorld.java}} file from within that working directory. From the command line prompt on Windows, this will be:
<div class="source">
<syntaxhighlight lang=bash>
javac -classpath .;phidget21.jar HelloWorld.java
</syntaxhighlight>
</div>
In a terminal on Linux or Mac OS, this will be:
<div class="source">
<syntaxhighlight lang=bash>
javac -classpath .:phidget21.jar HelloWorld.java
</syntaxhighlight>
</div>

5. You should now have three compiled class files: {{Code|HelloWorld.class}}, {{Code|HelloWorld$1.class}}, and {{Code|HelloWorld$2.class}}. You don't need to try and run them, and if you do you may encounter an error because the SBC {{Code|phidget21.jar}} may be slightly different than the Phidget support you have installed on your external computer.

Now we move onto the SBC:

6. Create a new project on the SBC, in the web interface under {{Code|Projects → Projects}}. Call it HelloWorld:

[[File:sbc_create_project.png|link=|alt=]]

7. On the next screen, you will be prompted to upload your files. We will upload the three Java class files, and then click the {{Code|Start}} button:

[[File:sbc_web_run_project.png|link=|alt=]]

8. You'll note that as it runs, there are two links below the {{Code|Stop}} button: One called {{Code|stdout}}, which is ''Standard Output'', and one called {{Code|stderr}}, which is ''Standard Error''. Usually, when you run a program on the command line, you see both standard out and standard error at the same time - i.e. you get all program output right there in your terminal or command prompt. But when running a program in the background, Linux splits the output up into normal output and error output as this is very useful for debugging (i.e. you can check if standard error is empty).

Here, however, if you're not sure whether the program will run correctly, you should first check {{Code|stderr}} to see if any errors were generated, and then check {{Code|stdout}} to see if the output looks as expected.

To write your own Java program, follow the same process but use your own source code instead of the {{Code|HelloWorld.java}} example.

Now that you have a running program, we offer additional help on [[#Via the Web Interface|running a program automatically using the web interface]].

====Program with SSH====

Similarly to starting a program via the [[#Program in Java with the Web Interface|web interface]], we use the Phidget Java {{Code|HelloWorld}} example here.

Make sure you have [[#Installing C/C++ and Java|Java installed on the SBC]]. To compile and run the {{Code|HelloWorld}} example:

1. Open an [[#SSH|SSH terminal]] to the SBC

2. Download the [{{SERVER}}/downloads/examples/JavaJNI.zip Phidget Java Examples] to the SBC, using [[#wget|wget]] (you may need to install {{Code|wget}} using [[#apt|apt]].)

3. Unpack the examples using [[#unzip|unzip]] (you may need to install {{Code|unzip}} using [[#apt|apt]].)

4. The location of {{Code|phidget21.jar}} on the SBC is {{Code|/usr/share/java/phidget21.jar}}. Within the unzipped example directory, compile the {{Code|HelloWorld.java}} example:

<div class="source">
<syntaxhighlight lang=bash>
javac -classpath .:/usr/share/java/phidget21.jar HelloWorld.java
</syntaxhighlight>
</div>

5. To run the {{Code|HelloWorld}} program, use:

<div class="source">
<syntaxhighlight lang=bash>
java -classpath .:/usr/share/java/phidget21.jar HelloWorld
</syntaxhighlight>
</div>

Now that you have a running program, you'll probably want to learn to [[#Running a Program Automatically|run this Java program automatically]].

'''Permissions Note:''' If you're used to using Linux with Phidgets already, you'll probably notice that you don't need to switch into root using {{Code|sudo}} on the SBC in order to run programs. This is because you already are running as root, not because the [[OS - Linux#Setting udev Rules|udev rules are set up]]. So if you set up another user, or [[#Via Cron|run a cron job]] as anything other than root or system, you'll need to add permission for the Phidget program to run in your [[OS - Linux#Setting udev Rules|udev rules]].

====Developing Code on the SBC====

When you're not just using pre-written source code, and you're writing code actually on the SBC itself, you'll probably want to use [[#nano|nano]]. Other terminal editors on the SBC include {{Code|vi}} which is already installed, and {{Code|emacs}}, which you can install using [[#apt|apt]]. Both {{Code|vi}} and {{Code|emacs}} are much more efficient for the experienced user, but they contain modes and keyboard shortcuts that can seem strange or almost hindering to the casual user.

Regardless of which editor you choose to use, some of your keyboard habits may not transfer well. For example, in the Linux command line, the command {{Code|Ctrl-C}} means ''stop the currently running program'', (i.e. your open editor) not copy. Within most SSH terminals, you can copy and paste using the right-mouse button, and on some terminals (and all native Linux terminals) you can copy by simply highlighting text, and you can paste it using the middle (scroll) mouse button. On the other hand, if you write a program that hangs on the command line, {{Code|Ctrl-C}} can actually be useful to terminate it.

Also {{Code|Ctrl-Z}} does not mean ''undo'', rather it means ''run the current program in the background''. This is useful because running a program in an SSH terminal simply hangs your SSH input until the program is done. So typing {{Code|Ctrl-Z}} while the program is running frees up the command line for more input. But if you accidentally hit {{Code|Ctrl-Z}} while running an editor like [[#nano|nano]], the editor will immediately exit to the command line. Don't worry though, it will not stop or lose your work. You can bring it back up by using the {{Code|fg}} (e.g. 'foreground') command, like {{Code|fg nano}}, and this will automatically bring your nano process back to the front.

===Running a Program Automatically===

For testing your program, you will certainly want to run it via [[#SSH|SSH]] or via the {{Code|Start}} button on the project page on the web interface until you are quite sure it runs well. However, eventually you will probably want the program to run without your input, either [[#Via the Web Interface|continuously, and starting at boot]], or via a task scheduled to [[#Via Cron|run to completion at certain times]].

Both have their advantages and disadvantages. Usually, you would want to use the continuous, from-boot methods for event driven code that has to handle a wide variety of user input that could occur at any time. You would want to use the scheduled method when the SBC needs to perform a repeated task (e.g. reading sensor data) again and again. The main difference is:
* With the continuous (boot) method you can have any Phidgets (including sensors, LEDs, input switches, etc) attached and giving events to your code all the time, and
* With the scheduled (cron) method you have much less of a chance to run into long-term memory management and instability problems with any code you write, because your program runs for only a short time before exiting and getting cleaned up.

====Via the Web Interface====

To use this method, you must have created the program you want to run as [[#Program in Java with the Web Interface | a Java or ARM-compiled C project in the web interface]]. If you would like to use another language, or another way of uploading your project, but you still want to start at boot and run continuously, you will need to use a [[#Via a Boot Script|boot script]].

In the web interface, go to the {{Code|Projects}} tab, and click on the project you would like to run. Near the bottom of the project page (the one with the {{Code|Start}} and {{Code|Stop}} buttons at the top), there will be a section called {{Code|Startup Settings}}. You can see a screenshot of the whole project page, including these settings, in the [[#Program in Java with the Web Interface | web interface project section]].

Select the {{Code|Enabled}} radio button. The other defaults should be fine, unless you specifically know otherwise:
* For ''Boot Order'', lower numbers boot first. Booting later means more programs are available for use, booting earlier means other programs can use your program.
* ''Run as a daemon'' starts the program as a daemon, which is a program that runs in the background. Unless you have ''explicitly'' written your program as a daemon, leave this checked. (If you don't know what a daemon is, don't worry, you haven't written one, so leave it checked.) ''Un''checking this when your program is a normal program will cause the SBC to hang while booting.
* The ''Executable or Class'' name should be automatically sensed to be your main Java class
* ''Arguments'' are any command line arguments you need, just as you would type them into the command line

'''Note:''' Your program must be very, very stable to run properly via the web interface. Imagine your program running continuously for days, or months on end. Any memory leaks, over time, will render your program (and the SBC) unusable until a reboot. Counts or other variables that increase within your program and never reset may create a segmentation fault eventually.

If, for stability purposes, you want your program to start, run for a little while, and then exit so that the SBC operating system can clean up the memory each time, you'll probably want to use [[#Via Cron|Cron]] to run your program instead.

====Via Cron====

Cron can automatically schedule programs - known as 'jobs', or 'cron jobs' - at most once per minute. Less often than that, it is very flexible, allowing you to run it on certain months, weekdays, hours, etc. Cron simply reads a special file (your {{Code|crontab}}) and runs whatever programs are listed, with whatever timing they are listed with. The cron program runs all the time in the background, making it what is known as a Linux ''daemon'', but the programs it starts as jobs run only as long as they naturally would, and then they exit.

If you need your program to run more often than once per minute, have the program schedule itself while still running. For example, to run every five seconds, run a fast loop, and sleep for five seconds. Do this twenty times and exit. Then schedule this once per minute using cron, and your program will in essence run every five seconds.

Setting up a cron job simply entails editing your {{Code|crontab}} file.

First, you'll probably want to specify your default editor to be [[#nano|nano]]. Otherwise it will default to {{Code|vi}} and you'll have to figure out {{Code|vi}} in order to add lines to your crontab:

<div class="source">
<syntaxhighlight lang=bash>
export EDITOR=nano
</syntaxhighlight>
</div>

Then, to edit your crontab file, simply type:

<div class="source">
<syntaxhighlight lang=bash>
crontab -e
</syntaxhighlight>
</div>

Each line of the crontab file is one scheduled job. Lines that start with a hash "#" are comments and are ignored. There is an example line in the crontab, and a reminder line at the very end. Essentially, each line should contain:

<div class="source">
<syntaxhighlight lang=text>
minute hour dayOfMonth month dayOfWeek command
</syntaxhighlight>
</div>

Where:
*{{Code|command}} is the program you want to run (with absolute path, and arguments)
** For example, {{Code|./myprogram argument1}} won't work, but {{Code|/root/code/myprogram argument1}} will
* Each time argument is either a number, a list of numbers separated by commas, or an asterisk
** For example, * * * * * means every minute for all days and months, 0,30 * * * * means every thirty minutes (i.e. at the top of the hour and at 30 minutes in) for all days and months

If you already have jobs scheduled, you'll see them in the file that comes up. You can edit, add, or delete.

After you save, you'll see a little message back in the terminal that says the new crontab file was installed, and it is now scheduled! Cron always starts every boot, and so if you have edited and installed your crontab as above, the scheduling of your program will start properly even after a reboot of the SBC. However, if you are having strange scheduling problems, you may want to familiarize yourself with the [[#Software Details|software details]] of how the SBC as a whole determines the current date and time.

=====My Cron Job Doesn't Work!=====

It is actually very common for a script or program to work on the command line but then ''not'' work as a cron job. The most common reason for this, by far, is that you specify ''relative'' paths in your program to access files rather than ''absolute'' paths. For example:
* {{Code|code/project.c}} is a relative path (bad for cron)
* {{Code|/root/code/project.c}} is an absolute path (good for cron)
The cron jobs are ''not'' executed from your home directory, or your code directory, so they will not be using the same location you may be using to test your code. So always use absolute paths.

Another common reason is you may be using environment variables or other settings that are true in a terminal but are ''not'' true by default in the raw system. You can end up taking many things for granted in a shell, for example the shortcut "~" means home directory in a shell, but not by default in the raw system. The things that get loaded for a shell (but which are not present in the raw system) are:
* The settings loaded by {{Code|/etc/profile}}
* Any settings in {{Code|~/.bashrc}}, which is nothing by default on the SBC

On a full Linux operating system, you would use the logs written to by cron to find the error output and debug it. On the SBC, however, cron does not write logs (otherwise, these logs would eat up the SBC memory very quickly even for routine jobs). For short-term debugging, you can write output from your program to a file, and read that file afterwards to figure out what your program is doing.

====Via a Boot Script====

If you want to run your program constantly and for it to start at boot like the [[#Via the Web Interface|web interface would do]], you can install your program into the boot order using a script. This is a somewhat involved process, and you should be familiar with shell programming in Linux. For this process, we only offer a [[OS - Linux#As A Service|similar example]] which installs and runs the program {{Code|phidgetwebservice21}} within the boot sequence.

===Using USB Data Keys===

After plugging the USB key in, it won't just appear on your desktop, so to speak, so you'll need to figure out where you can read and write to it within the SSH directory structure.

The web interface program can help with this. After you plug a USB key in, it will show up under {{Code|Status → System}}. Or, the USB key and all other attached devices can be seen at {{Code|Status → USB}}:

[[File:sbc_mounted_devices.png|link=|alt=]]

In the screenshot above, you can see that the USB key is located in {{Code|/media/usb0}}.

Alternately, you can use the SSH command {{Code|mount}}, and the searching program {{Code|grep}} which will filter the response of {{Code|mount}} and only return the lines with your search term ({{Code|usb}}):

<div class="source">
<syntaxhighlight lang=bash>
root@phidgetsbc:~# mount | grep usb
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

In this case, the USB key can be written to and read from using the {{Code|/media/usb0}} directory. Copying a file to {{Code|/media/usb0}} will copy a file to the USB key. The same goes for removing, renaming, opening files within your program, etc.

'''Note:''' Mount points like {{Code|/media/usb0}} should not be hard-coded into any of your programs. (See the [[#Common Problems and Solutions | Common Problems and Solutions]] section for more information.) If you need to obtain the mount point for a freshly mounted USB key within your code, have your code obtain the mount tables and search on the ''device'' (e.g. {{Code|/dev/sda1}} or {{Code|/dev/sdb1}}) and obtain the corresponding mounted {{Code|/media/usbN}} location, where N is a number 0-9.

===Saving and Retrieving Data===

This section covers getting data on and off of the SBC. There are two main methods of simply moving data on and off the SBC - via a [[#Via a USB Key|USB key]], and via [[#Over the Network (SCP)|copy over the network]] - and a third method for moving and installing data when it concerns [[#Backing Up Your Data|backing up lower level system data]].

====Via a USB Key====

After plugging in a USB data key, first you need to [[#Using USB Data Keys | find out the location]] where that data key was mounted.

Let's say the location of the USB key is {{Code|/media/usb0/}}, and we want to copy the file {{Code|data.txt}} to the USB key. Your SSH session might look something like this, using [[#ls|ls]] and [[#mount|mount]]:

<div class="source">
<syntaxhighlight lang=bash>
root@phidgetsbc:~# ls
data.txt
root@phidgetsbc:~# mount
tmpfs on /lib/init/rw type tmpfs (rw,nosuid,mode=0755)
proc on /proc type proc (rw,noexec,nosuid,nodev)
sysfs on /sys type sysfs (rw,noexec,nosuid,nodev)
udev on /dev type tmpfs (rw,mode=0755)
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev)
devpts on /dev/pts type devpts (rw,noexec,nosuid,gid=5,mode=620)
rootfs on / type rootfs (rw)
procbususb on /proc/bus/usb type usbfs (rw)
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
root@phidgetsbc:~# cp data.txt /media/usb0/
</syntaxhighlight>
</div>

The '''cp''' program copies data from a source to a destination. The syntax is {{Code|cp from to}}, where here we are copying from {{Code|data.txt}} to {{Code|/media/usb0/}}.

'''Caution:''' Even if there is no USB key mounted at {{Code|/media/usb0/}}, this use of {{Code|cp}} will still work ''with no errors''! This is because there is still a file called {{Code|/media/usb0/}}, there is just no USB key file system ''mounted'' to that point. So be sure to run [[#mount|mount]] or use some other method of determining that there is, in fact, a USB data key attached and where it is mounted to.

====Over the Network (SCP)====

SCP is a command line program already installed on Linux and Mac OS, and downloadable for free on Windows. We discuss it and give examples in the [[#SSH|SSH]] section, but remember it here when you're trying to get data on and off of the SBC. With SSH or a terminal already open, you'll probably find it to be much faster and easier than dealing with a USB key.

====Backing Up Your Data====

For the web interface, you can save and restore all web interface settings under the {{Code|System → Backup & Restore}} tab.

To save the settings of what packages are installed for later re-installation, you can type:

<div class="source">
<syntaxhighlight lang=bash>
dpkg --get-selections > installedPrograms.txt
</syntaxhighlight>
</div>

Then save the file {{Code|installedPrograms.txt}} externally. If you have to completely wipe the SBC, you can just reinstall the whole list by moving the {{Code|installedPrograms.txt}} file back onto the SBC, and then typing:

<div class="source">
<syntaxhighlight lang=bash>
dpkg –set-selections < installedPrograms.txt
apt-get dselect-upgrade
</syntaxhighlight>
</div>

Also remember to externally save:
* Your {{Code|~/.bashrc}} settings file if you've changed it
* Your {{Code|crontab}} file if [[#Via Cron|you've edited it]]
* Any data files or code you've created

It is important to save these settings often, and at points where you know the system is running well. It may be tempting to create a backup right before you [[#Recovery System|wipe the SBC and start from scratch]], but often the reason you are having problems then is some setting or change, and backing these up and reinstalling them will only reinstall the problem.

To truly back the files up, you must copy them to an external computer or location using either a [[#Via a USB Key|USB Key]] or [[#Over the Network (SCP) | over the network]]. Then they can be copied back if needed later.

If you are looking to restore data on an SBC that will not boot properly, you'll want to be in the [[#Partial Recovery|partial recovery]] portion of our Troubleshooting section.

==Troubleshooting==

The SBC can be quite tricky to debug, because it is a complex and flexible computer. Common problems and solutions include:
* You can't find the SBC on the network at all - refer to the [[#Initial Internet Setup|Initial Internet Setup]] section
* You have changed some setting or file such that the SBC doesn't run anymore, or doesn't run as expected - refer to the [[#Recovery|Recovery]] section

If you are having trouble using Phidgets on the SBC, you should go through the [[OS - Linux#Troubleshooting | Troubleshooting section on the general Linux page]]. Some of the problems on the Linux page (such as library problems) are easier to fix by simply working through the [[#Recovery|Recovery]] section when they occur on the SBC.

Namely, it often helps to simply perform a [[#Factory Reset|factory reset]] on the SBC (save your files and installed program list first, as [[#Backing Up Your Data|described here]]). Sometimes you change a file or setting within the operating system when you are trying to get something up and running, and this unintentionally affects other programs too. Performing a factory reset starts you with a clean slate.

If your problem doesn't seem to be fixed by these steps, or the information within this guide, please [[Contact Us|ask us]]!

===Initial Internet Setup===

To set up the SBC, you almost always need a ''wired'' Ethernet connection with DHCP (Dynamic Host Configuration Protocol), and without a firewall. This connection should be to a ''router'', not directly plugged in to your computer.

Even if you do not have this type of a connection at home, these types of connections are very common at both offices and universities. On a Windows or Mac OS computer, you can bring up the Phidget Control Panel as described in the SBC's [[1072 0 - Getting Started|Getting Started Page]]. Failing this, or on a Linux computer, we discuss some alternate setup methods in this section. Keep in mind that without a wired, open DHCP connection these setup methods can be difficult and fickle.

====No Wired-Only Connection====

Sometimes it can work to plug the SBC, using Ethernet, directly into an Ethernet port on your home wireless router. Do not plug it directly into your computer! (Although in some instances, a direct connection can be made to work on Linux, see the [[#No DHCP|No DHCP]] section below)

This direct-router method is a very picky process, however, and can fail because:
* Some home and office routers place a firewall between wireless connections (clients) and wired connections (the local area network)
* Some home and office routers do not by default allow both Ethernet DHCP and wireless DHCP.
* Some routers and DHCP hubs only provide access to an internet connection, and do not provide local area network inter-connections (this is common on mobile device tethering hubs)

Routers are quite complex, and even with admin privileges it can be a painstaking process to find all the right firewall settings to turn off in order to allow two computers on the network to talk to one another, rather than just connect to the internet. This is why university or office networks are often ideal for the purpose of setting up the SBC, because these institutions depend on computers on a local network being able to talk together. University libraries in particular can be a good source of wired DHCP connection ports.

Covering all of the different router configuration possibilities here, and how to change them to make the SBC work, is essentially impossible. If you try using the SBC at home or at work, the SBC does not work on the first try when plugged directly into the router via Ethernet, and you want to make that connection work rather than seeking out an alternate for the initial setup, you should find documentation specific to your router (usually available online) and properly configure it.

The good news is that if you can find an Ethernet DHCP connection ''just once'' for a short time, you can use that connection to configure the SBC to work on your home wireless network. During that initial connection, you can enable wireless and set up as many wireless DHCP connections (with passwords) that you need. Once wireless is enabled and set up, you can take the SBC home to your wireless router and the SBC will automatically seek out and connect to its remembered networks as they appear. At that point, you can also use wireless like a normal internet, web interface, and SSH connection.

====No Link Local Addressing====

If you have a wired DHCP connection, no firewall, and no link local addressing (e.g. bonjour or avahi is not installed) then you will need access to the DHCP router logs. From the router logs, you should see the connection (or attempted connection) by the SBC within the logs. From that log entry, you should either be able to determine the IP address for the SBC, or see what happens when the router blocks access. The IP address can be used in place of the link local address for both the web interface and for SSH.

====No DHCP====

The SBC will first try to use DHCP, but then it will revert to responding to a link local address under bonjour and avahi. If you are depending on this, please wait '''at least three minutes''' after the SBC boots for the SBC to fail in obtaining a DHCP connection and properly revert to link local addressing.

If you have a static IP setup, and want to use link local addressing rather than accessing the router logs, this should usually work by default on Windows and Mac OS (e.g. type the address such as {{Code|phidgetsbc.local}} into a web browser). If it doesn't work automatically, there is not much you can do and you should seek out a wired DHCP connection elsewhere.

On Linux, it also should work by default, but you have the additional option of explicitly adding routes that look within the default network settings for the SBC. From a terminal (as root), type:
* {{Code|route add -net 169.254.0.0 netmask 255.255.0.0 dev eth0 metric 99}}
* {{Code|route add default dev eth0 metric 99}}
You can also compile and use the {{Code|phidgetsbclist.c}} example (use the provided Makefile, don't use gcc) in the [{{SERVER}}/downloads/libraries/libphidget.tar.gz Phidget Linux Libraries] package, under the {{Code|examples}} folder. This will allow you to see if the SBC is detected on the network at all. Note that to use this option you must have the Phidget Libraries and the Phidget WebService installed on your Linux computer - in-depth instructions to do this are on the [[OS - Linux|main Linux page]].

===Recovery System===

You can either boot the SBC into recovery mode and attempt to recover files and settings, or you can completely wipe the SBC by performing a factory reset. If the LEDs do not turn on normally (red on constantly, green on at first start, then off, then on when fully booted) then you'll want to read the [[#Hardware Issues|hardware issues]] section.

====Partial Recovery====

The recovery system can be entered in two ways:
# From the {{Code|System → Backup & Restore}} web interface page.
# By holding down the reset button for 20+ seconds - until the green light has switched from flashing slowly to flashing quickly.

The recovery system runs an [[#SSH|SSH]] server where the username and password both are {{Code|root}}.

If the main filesystem has been damaged/misconfigured in such a way that it won’t boot, you may be able to fix the issue or recover important files before running a full factory reset. From an SSH connection to the recovery system, you can mount the main root filesystem with the following commands (assuming it’s not damaged):

<div class="source">
<syntaxhighlight lang=bash>
ubiattach /dev/ubi_ctrl -m 6
mount -t ubifs /dev/ubi0_0 /mnt
</syntaxhighlight>
</div>

====Factory Reset====

This restores the kernel and root filesystem from backup, overwriting any changes that may have been made and ''completely wiping the system'' to the state that it got shipped in. (You can save your files and installed program list first, as [[#Backing Up Your Data|described here]].) This can be enacted one of two ways.
# Use the reset button:
##Enter the recovery mode by holding down the reset button for 20+ seconds as above (until fast flashing)
##Wait for a full boot (i.e. you can see it on the Phidget control panel, or can SSH with username and password as {{Code|root}})
##Hold down the reset button again, but this time for only 10 seconds (until slow flashing)
##Wait for the SBC to fully reset and reboot (at least three minutes) - the LED will turn off and on again when this occurs
##*Note that after a factory reboot the SSH server will be disabled
##*Also note that after a factory reboot the SBC creates new SSH keys, and reverts to the {{Code|phidgetsbc.local}} address
# Via the web interface, under {{Code|System → Backup & Restore → Go button}}, where you can follow the instructions

====Hardware Issues====

The LEDs are an indicator of the hardware working properly. The normal boot process is:
* Red LED: Turns on from moment of power being applied.
* Green LED: Turns on momentarily when power applied, then turns off momentarily, then turns on and stays on when booted.

If the green status LED never turns on (or fails to turn on the second time), the boot process is failing somewhere. This could be due to:
* A damaged OS - Try performing a [[#Factory Reset|Factory Reset]]
* If this fails, it is likely hardware damage (very difficult to diagnose, please [[Contact Us|contact us]])

If neither LED turns on, hardware damage is even more likely. Unless the path to the red LED is the one thing that has been damaged, the device is likely not receiving and using power.
* Try performing a [[#Factory Reset|Factory Reset]], and if that does not work please [[Contact Us|contact us]]

=====USB Issues=====

On the Phidget SBC2, there is a hardware issue that is unrelated to the LEDs. It is a USB problem, and manifests in many ways:
* Strange behaviour when some devices but not others are plugged in to the SBC
* Strange behaviour with combinations of devices
* Failure (or intermittent failure) to see Phidgets on the USB hub, or USB keys on the hub

This problem is fixable, either on your own or by sending your SBC back to Phidgets. For an in-depth solution, see the [[SBC2_USB_Hub_Fix | SBC2 Hub Fix Page]].

===Updating Your SBC===

If you've owned your SBC for a while and want to update your packages, you can run:

<div class="source">
<syntaxhighlight lang=bash>
apt-get update
apt-get upgrade
</syntaxhighlight>
</div>

...to ''update'' your software source list and then ''upgrade'' to the latest version of all installed software. If you are used to Mac OS or Windows, note that this does not just update the non-kernel parts of the operating system, it updates every additional piece of software you have installed.

To update the SBC software itself (e.g. the kernel), it is easiest to use the web interface, under {{Code|System → Backup & Restore → Go button}}, to enter a page that will give you the option to update. You will need to have an update file on a USB key inserted into the SBC, of type:
* UBI Image (system_ubi.img), or
* Kernel image (uImage), or
* Phidget Upgrade package containing both UBI and Kernel images (phidgetsbc*.bin)

These are either obtained from the Phidgets website, or are a custom kernel / filesystem that you can create yourself, if you are experienced.

The reason why this information is in troubleshooting is that you should certainly [[#Backing Up Your Data|back up your system]] before trying this. And, it is quite rare to need to upgrade the kernel or filesystem on the SBC, so something serious should be going on before you attempt it. Try using the [[#Recovery System|recovery system]] first.

==Programming Languages==

Now that you have the basic libraries installed, you can pick your language and begin programming!

If you are not using the [[#WebService | webservice]] to control a Phidget over a network, your next step will be to delve into the use of your specific language. Each page has its own set of specific libraries, code examples, and setup instructions.

On SBC Linux, we recommend the following languages:

*[[Language - C/C++|C/C++]]
*[[Language - Java | Java]]
*[[Language - Python | Python]]

These languages may also run on the SBC, but we do not yet directly offer SBC support for them:
* [[Language - Ruby|Ruby]]
* [[Language - C Sharp|C#]] (using Mono)

You can probably figure out how to install and use them by a combination of the language pages linked above, and the section on [[#Installing Other Languages|installing other languages on the SBC]].

==WebService==

The SBC comes with the [[Phidget WebService]] installed, and the SBC automatically starts the WebService at boot.

To practice using the WebService, and to learn more about it, we have hands-on examples on the [[OS - Linux|general Linux page]], starting in the [[OS - Linux#Using the WebService|using the WebService section]].

==Advanced Uses==

===Using a Different Wireless Adapter===

The support for the wireless adaptor that Phidgets sells is written into the SBC kernel. Hence, we do not support using other adaptors.

However, Linux is very flexible, and it is possible (though not easy) to write a custom kernel for the SBC and add support for a new wireless adaptor. We can't help you with this, but we do provide some basic guidelines for [[#Custom Kernel and Filesystem|building your own kernel]].

===Using a Different Webcam===

In addition to the webcam that Phidgets sells, you have the option to use many different webcams with the SBC. There is a [http://www.ideasonboard.org/uvc/#devices long list] of compatible webcams.

The common thread for these webcams is that they use UVC - the USB Video Class - drivers for Linux. You can then use [[#mount|mount]] to find out what video device your webcam is mounted under.

===Taking Pictures With the Webcam===

Probably the most straightforward way to use a webcam for pictures rather than video is to use the {{Code|opencv}} library. You can get it by:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install libcv2.1
</syntaxhighlight>
</div>

If there is no {{Code|libcv2.1}} package, you can perform {{Code|apt-cache search libcv}} to find the current version.

The opencv libraries can also be used within Python, by installing the link between them:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install python-opencv
</syntaxhighlight>
</div>

Then taking pictures from within code becomes quite simple. For example, in Python, taking and saving an image is four lines:

<div class="source">
<syntaxhighlight lang=bash>
#! /usr/bin/python

import cv

# The webcam is located at /dev/video0
# OpenCV only needs the number after video
webcam = cv.CaptureFromCAM(0)

frame = cv.QueryFrame(webcam)

cv.SaveImage("image.jpg", frame)
</syntaxhighlight>
</div>

For the complete OpenCV documentation, see [http://opencv.willowgarage.com/documentation/index.html The OpenCV Reference], and specifically the section on [http://opencv.willowgarage.com/documentation/reading_and_writing_images_and_video.html Reading and Writing Images].

'''Note:''' The SBC is probably not as powerful for image processing and transport when compared to your desktop computer. Try running your image processing code on the SBC from an early point in development. During those test runs, you can visit the first System page of the [[#SBC Web Interface|SBC Web Interface]] to check the processor and memory use. For more information on processor power, check the specification for your SBC (on the product page on [{{SERVER}} our main website]) as well as our discussion of [[#Pushing Processor Limits|pushing processor limits]] below.

===Checking System Logs===

The SBC maintains two logs: a kernel log and a system log.

The kernel log is for low-level occurrences, such as devices attaching and leaving the USB hub, recording what drivers are being used, and so on.

The system log (syslog) is for normal chatter from the operating system. Any program with the right permissions can use it (though you need to know the method to write to it, information all around the Internet can help) and it contains everything from the Ethernet going up and down, to webserver requests, and so on. If you don't run many programs or services on the SBC, the syslog will essentially be a mirror of the kernel log, because the kernel is the only thing talking.

You can check these logs by using the web interface in the {{Code|System → Logs}} tab.

Or you can perform more powerful filtering and displaying via an SSH terminal. For example, {{Code|dmesg}} is the command to display the kernel log, and {{Code|tail}} prints the last ten lines of input. So, if you are trying to see if you can get a device to be detected on USB, you can run <code>dmesg | tail</code> to print the latest ten lines of kernel log data.

The actual locations of the log files (for filtering and reading) are:
* {{Code|/var/log/syslog}}
* {{Code|/var/log/dmesg}}
But don't edit them directly! Always follow the advice and procedures around the Internet on how to properly log items to syslog.

===X Forwarding===

Although most tasks can be done using the [[#SBC Web Interface|SBC Web Interface]] or [[#SSH|SSH]], you can also set up X11 forwarding on the SBC. X11 is the window manager base, which provides a graphical windowing system on the SBC. Although you probably won't connect directly to the X11 manager (i.e. by plugging a screen directly into the SBC), X11 also gives a user the ability to forward graphical windows over SSH. You will need the following packages installed:
* {{Code|x11-common}}
* {{Code|xbase-clients}}
After installing, make sure that the line in {{Code|/etc/ssh/sshd_config}} has a line that says:
:{{Code|X11Forwarding yes}}
Then log out and log back into the SBC. This second time you log in, use the {{Code|-X}} switch to turn on X forwarding for that connection:
:{{Code|ssh -X root@phidgetsbc.local}}
Then you should be able to run programs that launch a window, and it will launch remotely and appear on the computer you have the SSH connection from.

===Pushing Processor Limits===

The SBC, though more powerful than many embedded computers out there, is probably about as powerful as your smartphone. If you hook up 1 ms Phidget sampling devices to all six of its USB ports, events and packets will probably get lost. The exact data rates you can accomplish depend on:
* What else is running on the SBC
* How efficient your code is for external operations (like File I/O)
* Other minor details (e.g. the temperature of the SBC, etc)

If you want to achieve data rates as fast as possible, try these tips:
* Program in C, not in an interpreted language (Python, Java, .NET)
* Perform file I/O as little as possible. Locally cache data, manage your writing to a file in a separate thread, and use low-level write calls.
* Change the [[#Custom Kernel and Filesystem|filesystem]] to a faster, non-compressed file system.
** Alternatively, use a high-data-rate USB key.
* Keep other running processes to a minimum.
** If you are running code locally right on the SBC, turn off the Phidget WebService.

===Custom Kernel and Filesystem===

You can compile your own kernel and flash it to the board. It is left up to the user to configure an appropriate cross-compiler for kernel development. You may also be able to compile a new kernel on-board. We have a kernel development kit, complete with patch file and README:
* [{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC Kernel Development Package]

Compiling a new, custom kernel is somewhat complex. If the SBC is your first experience with Linux, writing a custom kernel will be difficult. However, it will probably also be very rewarding because you can put whatever you like into it. We might be able to offer additional suggestions, but ultimately you're on your own here.

You may be able to write a custom kernel right on the SBC, but the easiest way is to develop the kernel on an external computer. And the easiest way to develop on an external computer is for that computer to also be Linux, even just in a Virtual Machine. The time spent loading a copy of Linux into a virtual machine (such as VirtualBox, which is free) onto your computer will probably be less time than setting up a standard compiler on Windows to cross-compile.

On your external Linux system, you will need:
* A cross-compiling toolchain for the ARM processor, which we briefly describe on the [[OS - Linux#Cross-Compiling with a Custom Toolchain | main Linux page]], and
* The [{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC Kernel Development Package] from the Phidgets website.
The kernel development kit has a brief README file which describes how to obtain the proper kernel and patch, configure, customize, and build it.

We have an application guide in progress, which walks through building a custom kernel to add Bluetooth support to the SBC. Please contact us if you would like more information. Even if you are trying to add support for hardware other than a bluetooth modem, or wondering if support even exists in the kernel for your modem (3G, alternate wireless, etc) you will probably find the application guide helpful. Follow it up to the point where you run the program {{Code|menuconfig}} (you don't need an SBC to do this), which will give you a menu of all drivers you can enable in the SBC kernel.

After making your new kernel, you should have a uImage and modules target for your Makefile. At this point you can transfer your kernel files onto the SBC, make their targets, and transfer them into the nand memory. This involves erasing the old kernel, flashing the new kernel, installing the new kernel modules, and rebooting. From the SBC, in the kernel directory:

<div class="source">
<syntaxhighlight lang=bash>
make uImage; make modules
flash-eraseall /dev/mtd3
nandwrite -p /dev/mtd3 arch/arm/boot/uImage
make modules-install
reboot
</syntaxhighlight>
</div>

Custom kernels can also be flashed from the [[#Recovery System | Recovery System]].

If you need to create a root filesystem image, the filesystem type is UBIFS, and the commands to create it are:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -m 2KiB -e 126KiB -c 4050 -r $ROOTFS/ system_ubifs.img
ubinize -o system_ubi.img -m 2KiB -p 128KiB -s 512 ubinize.cfg
</syntaxhighlight>
</div>

Where {{Code|ubinize.cfg}} contains:

<div class="source">
<syntaxhighlight lang=bash>
# Section header
[rootfs]
# Volume mode (other option is static)
mode=ubi
# Source image
image=system_ubifs.img
# Volume ID in UBI image
vol_id=0
# Volume size
vol_size=64128KiB
# Allow for dynamic resize
vol_type=dynamic
# Volume name
vol_name=rootfs
# Autoresize volume at first mount
vol_flags=autoresize
</syntaxhighlight>
</div>

You then flash ‘system_ubi.img’ (not ‘system_ubifs.img’) from the recovery system.

Again, like the custom kernel creation, the need to create a custom root filesystem is essentially non-existent except for those advanced users who already know they need it... and furthermore, you are almost entirely on your own.

==Software Details==

For even more advanced uses of the SBC, it may help to know the gritty details of the SBC software system.

;Operating System
:Debian/GNU Linux
:Kernel 2.6.X or higher (generally kept up to date with latest releases, use {{Code|uname -r}} to check the kernel version)

;Main Filesystem (rootfs)
:UBIFS (a raw flash type of file system)
:Mounted in a 460 MB Nand partition (in Read/Write mode)

;Kernel
:uImage format
:Has its own 3MiB partition on bare Nand

;Web Interface Scripts and Configuration Data
:Located in {{Code|/etc/webif}}
:Modifying these scripts can be done; however, it is very easy to enter invalid data that could cause the system to behave unexpectedly or not boot.

;User Applications uploaded through Web Interface
:Located in {{Code|/usr/userapps}}

;Webcam Device Location
:{{Code|/dev/video0}}
:Numbers increase with more webcams

;Date and Time
:Set using ntp (network time protocol) at boot
:The ntp daemon continues to run in the background and will periodically update the clock
:The network keeps the SBC very close to real time
:Also there is a real-time clock with battery backup which will preserve date/time across reboots, power removal
:The real-time clock is synced to system time during reboot/shutdown
:If power is unplugged suddenly, and the network not restored, the real-time clock may not have the correct time

;Wireless Networking System
:Wireless adapter support for the wireless adapter that Phidgets sells is written into the kernel
:It supports WEP and WPA
:It is best configured through the configuration interface.

;Nand Layout
:The board contains 512MiB on Nand. This nand is split into 7 partitions as follows:
:0: u-boot size: 256K Read Only
:1: u-boot_env size: 128K Read Only
:2: recovery_kernel size: 2M Read Only
:3: kernel size: 3M Writable
:4: flashfs size: ~3.625M Read Only
:5: recovery_fs size: ~ 43M Read Only
:6: rootfs size: ~ 460M Writable
: The final size of flashfs/recovery_fs/rootfs depends on the image size at production, and on the number/location of bad blocks in the NAND.
: '''Note''': U-Boot and recovery kernel and filesystem cannot be written from Linux - this is a safety measure.

;Boot Loader
:U-Boot is used for setting up the processor and booting Linux, and is only accessible via a serial connection.
:Normal users will not need to use or modify it.
:Be very careful when modifying the u-boot partition. If it is damaged or overwritten, it is difficult to fix.
:When using U-Boot, a prompt will appear via serial shortly after power on.
:The environment variables will help you determine how to boot Linux on the SBC
:You can also refer to the [http://www.denx.de/wiki/DULG/Manual U-Boot documentation]

;Boot Process
:From power on...
:1. Processor loads first 4 bytes from NAND into Steppingstone and runs it.
:2. Steppingstone sets up RAM, copies u-boot from NAND into RAM and runs U-Boot.
:3. U-Boot initializes the processor, sets GPIO state, etc., copies the linux kernel into RAM, sets up the kernel command line arguments, checks that the kernel image is valid, and boots it.
:4. Linux boots, bringing up USB, Networking, NAND, etc. and then mounts the rootfs NAND partition on /.
:5. init gets run as the parents of all processes, as uses the /etc/inittab script to bring up the system. This includes mounting other filesystems, settings the hostname, and running the scripts in /etc/init.d, among other things.
:6. inittab then turns the green LED on.
:7. inittab then sets up a getty on the first serial port, ready for interfacing using the debug board.

==Common Problems and Solutions==

{{ProblemSolution|USB Memory Key mounting|Sometimes USB Memory Keys mount at more than one location}}

When you insert a memory key, the SBC will load it as a device (e.g. {{Code|/dev/sda1}}) and it will also ''mount'' the key for reading and writing within the {{Code|/media/}} directory. The {{Code|/media/}} directory version will be called something like {{Code|usb0}}.
At times, an inserted memory key will get mounted in more than one location. You can observe if this occurs by checking the currently mounted devices with the command {{Code|mount}}:

<div class="source">
<syntaxhighlight lang="text">
root@phidgetsbc:~# mount
tmpfs on /lib/init/rw type tmpfs (rw,nosuid,mode=0755)
proc on /proc type proc (rw,noexec,nosuid,nodev)
sysfs on /sys type sysfs (rw,noexec,nosuid,nodev)
udev on /dev type tmpfs (rw,mode=0755)
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev)
devpts on /dev/pts type devpts (rw,noexec,nosuid,gid=5,mode=620)
rootfs on / type rootfs (rw)
procbususb on /proc/bus/usb type usbfs (rw)
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
/dev/sda1 on /media/usb1 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</syntaxhighlight>
</div>

You will note that the same device ({{Code|/dev/sda1}}) is now mounted at ''both'' {{Code|/media/usb0}} and {{Code|/media/usb1}}. To fix this problem as it occurs, you can use {{Code|umount}} (notice there is no letter 'n') to unmount the second instance:

<div class="source">
<syntaxhighlight lang="text">
root@phidgetsbc:~# umount /media/usb1
</syntaxhighlight>
</div>

In practice, this should not be a problem, because writing to or reading from either {{Code|usb0}} or {{Code|usb1}} will have the same effect on the memory key. However, if you hard-code a media location into your program (i.e. expecting {{Code|/media/usb0}} to be the first USB key you insert and {{Code|/media/usb1}} to be the second key) your program will sometimes work and sometimes fail.

To get around this within code, find the mount point for each device as it appears. The devices, such as {{Code|/dev/sda1}} will always refer to the actual memory key. But, they cannot be written to directly without being mounted, so you will have to parse the mount table (what is returned from {{Code|mount}}) within your code to find the device and its corresponding mount point.

This is a problem with the standard embedded Debian automount program, and we have no known fix.

{{ProblemSolution|Perl Locale Errors on SSH|No Locales Installed}}

By default, no locales are installed on the SBC. If you use [[#apt|apt]] a lot to install and manage your software on the SBC, you will get messages like this:

<div class="source">
<syntaxhighlight lang="text">
perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
LANGUAGE = (unset),
LC_ALL = (unset),
LANG = "en_CA.UTF-8"
are supported and installed on your system.
perl: warning: Falling back to the standard locale ("C").
locale: Cannot set LC_CTYPE to default locale: No such file or directory
locale: Cannot set LC_MESSAGES to default locale: No such file or directory
locale: Cannot set LC_ALL to default locale: No such file or directory
</syntaxhighlight>
</div>

To squelch these messages, you should install and reconfigure your locale like this:

<div class="source">
<syntaxhighlight lang="bash">
apt-get install locales
dpkg-reconfigure locales
</syntaxhighlight>
</div>

The last command will show you a long list from which you should pick your location, by language. For example, en_CA is english_Canada. Here in Calgary, we use en_CA.UTF-8 and so for the first question we would input locale "114" and for the second (system) question we would input {{Code|en_CA}} for the locale.

This might give you a locale undefined error, in which case you can generate the locale (for us, again, it is en_CA):

<div class="source">
<syntaxhighlight lang="bash">
locale-gen en_CA
</syntaxhighlight>
</div>

OS - macOS

2012-06-29T20:42:06Z

Cora:

[[Category:OS]]
{{OSLang|[[File:Icon-Mac-OS.png‎|64x64px|link=]]|On OS X, Phidgets can be either plugged directly into a USB Port or run over a network using the [[#WebService|WebService]].}}
__TOC__
Phidgets are designed to run on '''OS X 10.4 Tiger or newer''', and can run on PPC, 32-bit, and 64-bit systems.

==Quick Downloads==

If this is your first Phidget, we highly recommend working through the Getting Started guide for your specific Phidget device, which may be found on its product page on [{{SERVER}} our main website]. If you already have the Preference Pane Installed and know how to use it, then you've already followed the guide and are ready to learn more about the workings behind the Preference Pane, the Phidget WebService, and more - all specific to OS X.

If you are already a pro, and just want the drivers:

*[{{SERVER}}downloads/libraries/Phidget.dmg OS X Installer Download]
*[{{SERVER}}/Drivers_Info.html#osx Software License]

==Getting Started with OS X==

===Installing===

The Phidget installer will install the core Phidget files onto your system.

To install the libraries, follow these steps:

1. Download the Phidget installer for your system:
*[{{SERVER}}/downloads/libraries/Phidget.dmg OS X Installer]

2. Open up the installer, and double click on {{Code|Phidgets.mpkg}} to install the libraries.

[[File:OSX Install 1.png|link=|alt=OS X Install]]

3. Proceed through the wizard.

[[File:OSX Install 2.png|link=|alt=OS X Install]]

4. Once the installation is complete, you are ready to program with Phidgets. To find out what files got installed, please see [[#Description of Installer files | Description of Installer files]] in the Appendix section.

Proceed onto to the [[#Phidget Preference Pane | next]] section where the Phidget Preference Pane will be discussed.

====Phidget Preference Pane====

The Phidget Preference Pane is a tool to quickly determine whether your system is able to communicate with Phidgets, and also act as a debugging tool.

Once the Phidget libraries are installed using the installer, open up the {{Code|System Preferences}} window.

[[File:OSX System Preferences.png|link=|alt=OS X System Preferences]]

Click on the {{Code|Phidgets}} icon in the {{Code|Other}} section to bring up the Phidgets Preference Pane.

[[File:OSX PreferencePane General.png|link=|alt=OS X PreferencePane General]]

The {{Code|general}} tab shows the list of Phidgets currently physically attached to the computer. You can also view the currently installed Phidget library version. You can double click on a Phidget device to open up an example program for the device.

[[File:OSX PreferencePane Example.png|link=|alt=OS X PreferencePane Example]]

In the above screenshot, the RFID example was opened. These examples are intended for demonstration and debugging purposes. If you have not yet already, please see the '''Getting Started''' guide for your device, which may be found on its product page on [{{SERVER}} our main website].

It is important to keep in mind that when an example Phidget application is opened from the Phidget Preference Pane or opened from any of your Phidget applications that you develop, it holds a lock on the Phidget. This prevents any other program from accessing the Phidget. Please ensure that this example application is closed(the Phidget Preference Pane can still be running) when you are running your own applications.

The next tab is the {{Code|Web Service}} tab, which allows you to control Phidgets over a network.

[[File:OSX PreferencePane Webservice Stopped.png|link=|alt=OS X PreferencePane WebService Stopped]]

Here, you can start and stop the WebService. Details are provided in the [[#WebService | WebService]] section. This screen also tells you whether the Phidget WebService is currently running.

The next tab is the {{Code|Labels}} tab. In this section, you can view the currently assigned labels of any Phidget attached to your computer. It is also possible to set the labels of Phidgets here too. You might want to set a label to a Phidget device because you can refer to it by its label as opposed to its serial number.

[[File:OSX PreferencePane Labels Local.png|link=|alt=OS X PreferencePane WebService Labels Local]]

You can also view the labels of any Phidget connected through the WebService

[[File:OSX PreferencePane Labels Remote.png|link=|alt=OS X PreferencePane WebService Labels Remote]]

The {{Code|Bonjour}} tab gives a list of all currently attached Phidgets that are connected to the WebService. You can also double click on the Phidget to connect to it over the network using one or more computers, but still use the Phidget on the computer it is directly connected to.

[[File:OSX PreferencePane Bonjour.png|link=|alt=OS X PreferencePane Bonjour]]

The last tab is the {{Code|PhidgetSBC}} tab, which displays the complete list of PhidgetSBCs connected to the network.

[[File:OSX PreferencePane PhidgetSBC.png|link=|alt=OS X PreferencePane PhidgetSBC]]

You can double click on the PhidgetSBC to bring up the PhidgetSBC Administration Console log-in page in your default browser.

[[File:PhidgetSBCAdminConsole.PNG|link=|alt=PhidgetSBC Admin Console]]

The PhidgetSBC Administration Console is where you can go to configure the PhidgetSBC. For more details, please see the [[1072 - Getting Started | PhidgetSBC]] section.

===Checking===

To confirm the libraries were installed and work correctly, you can check both the hardware and software components of the interface. It is worth checking the software side first, because if it works then you know the hardware side is also okay.

====Software====

If you have the Phidgets library installed on your system, you can verify that the software component is working by seeing if the Phidget device is listed in the General tab of the Phidget Preference Pane.

[[File:OSX PreferencePane General.png ‎|link=|alt=OS X Preference Pane General]]

The above screenshot shows that a PhidgetRFID and a PhidgetInterfaceKit are attached to the computer. If you see your Phidget in the list, you can continue to the [[#Programming Languages | programming languages]] section to learn more. If you are not able to see that the Phidget is in the list, there may be a hardware issue. Please see the [[#Hardware| hardware]] section for more details.

====Hardware====

You can verify that your computer detects that the Phidget is plugged in through a USB connection by going to the OS X System Profiler. You can access the System Profiler by selecting {{Code|About This Mac}} under the Apple icon.

[[File:OSX About This Mac.png‎|link=|alt=OS X About This Mac]]

The new window will open up.

[[File:OSX More Info.png|link=|alt=OS X More Info]]

Select {{Code|More Info}}. The System Profiler will show up. In the USB section, you will be able to find all connected USB devices.

[[File:OSX USB Devices.png ‎|link=|alt=OS X Attached USB Devices]]

In the above screenshot, The PhidgetInterfaceKit and PhidgetRFID are connected to the USB ports.

If you don't see the Phidget in the list, then take a look at the [[#Troubleshooting|troubleshooting]] section below, as well as the '''Communications''' section of our [[General Troubleshooting#Communications Troubleshooting|general troubleshooting page]].

====Troubleshooting====

If the example programs '''do not''' work but USB '''does''' work (i.e. your computer can consistently see the device in the [[#Hardware|hardware]]), take a moment to check the basics:
* You are using OS X 10.4 or newer.
* No other programs, drivers, or processes are using that USB port in software
* The Phidget libraries are the latest version (visit the [[#Quick Downloads| quick downloads section]] to download them)

* Check the [[#Common Problems and Solutions|common problems]] section below, some specific combinations can cause problems

If your problem doesn't seem to be fixed by these steps, make sure that the Phidget is seen '''consistently''' by USB (if it is erratic, try our [[General Troubleshooting|general troubleshooting guide]]). If you are still having problems after using the troubleshooting guide, please [[Contact Us|ask us]]!

==Programming Languages==
Phidgets’ philosophy is that you do not have to be an electrical engineer in order to do projects that use devices like sensors, motors, motor controllers, and interface boards. All you need to know is how to program.

After you have installed the drivers above, you should pick a programming language, install libraries, and run the examples for that specific language. You can learn more about what is needed to program in a particular language by choosing the language of your preference below. If you need help choosing a language, please look at the [[Software Overview#Language Support |language comparison table]].

We recommend the following languages for OS X:
* [[Language - Applescript|AppleScript]]
* [[Language - C/C++|C/C++]]
* [[Language - C Sharp|C# (Using Mono)]]
* [[Language - Cocoa | Cocoa]]
* [[Language - Flash AS3 | Flash AS3]]
* [[Language - Flex AS3 | Flex AS3]]
* [[Language - LiveCode | LiveCode]]
* [[Language - Java | Java]]
* [[Language - Max/MSP|Max/MSP]]
* [[Language - Python | Python]]
* [[Language - Ruby|Ruby]]

You can also use these languages, but they do not support [[General Phidget Programming#Event Driven Code | event driven code]], and must use [[General Phidget Programming#Logic Code | logic code]] only:

*[[Language - MATLAB|MATLAB]]
*[[Language - Simulink|Simulink]]

==WebService==

The Phidget WebService allows you to remotely control a Phidget over a network.

Drivers for the Phidget WebService on OS X are already included in the [[#Quick Downloads | Drivers]] above. If you see the Phidget Preference Pane in System Preferences, then you already have the WebService drivers installed.

There are two ways that you can connect to a Phidget hosted on another computer. The first method is by using the IP address/host name and port of the host computer. The second method makes the use of [http://en.wikipedia.org/wiki/Multicast_DNS mDNS], which allows Phidgets to be found and opened on the network by a server id instead of an IP address/host name. When using a server id, both the client and server will need to be running an implementation of zero configuration networking. The Phidget WebService takes advantage of [http://www.apple.com/support/downloads/bonjourforwindows.html Bonjour] software, which is built-in to OS X. It is a tool developed by Apple to locate devices, such as Phidgets, on a network.

This section helps you install, check, and use the WebService on Windows, but we also have an overview of the [[Phidget WebService]] in general.

===Turning the WebService On and Off===

There are two methods that can be used to turn the WebService on and off. The first method is through the Phidget Preference Pane. In the {{Code|WebService}} tab, you can start or stop the WebService. You can also choose to have the WebService start up automatically upon system boot up by selecting the {{Code|Start Automatically}} checkbox.

[[File:OSX PreferencePane Webservice Stopped.png|link=|alt=OS X PreferencePane WebService]]

The second method of turning the WebService on and off is through command line. After using our installer, the WebService utility is automatically installed in {{Code|/usr/bin/phidget21webservice}}.

You can get command line help with {{Code|phidgetwebservice21}} using the -h option:

<div class="source">
<syntaxhighlight lang=bash>
phidgetwebservice21 -h
</syntaxhighlight>

<syntaxhighlight lang=text>
'phidgetwebservice21' is a Phidget and Dictionary server from Phidgets Inc. See www.phidgets.com for more information.
Usage: phidgetwebservice21 [OPTION]
All parameters are optional. The default parameters are: port=5001, ServerName=(Computer Name) and no password

Options:
-p Port
-n Server Name
-P Password
-v Debug mode
-h Display this help
</syntaxhighlight>
</div>

Mapping out which command line options to which Phidget Preference Pane option is as follows:

-p: {{Code|Port}} field

-n: {{Code|ServerID}} field

-P: {{Code|Password}} field

-v: Not supported under the Phidget Preference Pane

To find the defaults used by {{Code|phidget21webservice}}, the command line is the fastest way to learn the default server name and IP address of your computer:
*For the default server name, use {{Code|hostname}} on the command line.
*For your IP address, use {{Code|ifconfig -a}} on the command line.
**A line in the return text, under your main internet connection (usually {{Code|eth0}}) will say something like {{Code|inet addr:192.168.3.178}}, which is your IP.

Here are some usage examples:

To start the WebService with default parameters:
<div class="source">
<syntaxhighlight lang=bash>
phidgetwebservice21
</syntaxhighlight>
</div>

To start the WebService with a server name of {{Code|myServer}}:
<div class="source">
<syntaxhighlight lang=bash>
phidgetwebservice21-n myServer
</syntaxhighlight>
</div>

To stop the WebService, simply close the command line window or press {{Code|Control}} and {{Code|c}} at the same time in the command line window.

===Using the WebService===

To use a Phidget over the WebService, you'll want to:
* Have two different computers connected to the same network. We will call the computer that has the Phidget directly connected to the USB port the host. The client will be the computer that runs a Phidget application to connect to the Phidget attached to the host. Please note that if you only have a single computer, you can also connect to the Phidget over the WebService. The computer will simply act as both a host and client. This will allow you to bypass the [[General Phidget Programming # Details for Open() | one application per Phidget limitation]].

* Start the WebService on the computer that directly connects to the Phidget
* Run your program on the remote computer that will control the Phidget over the network

The easiest way to test these steps on OS X is to set up the WebService and run the Phidget program on the client. Please follow these steps:

1. On the host, open up the Phidget Preference Pane and traverse to the {{Code|Web Service}} tab.

[[File:OSX PreferencePane Webservice Stopped.png |link=|alt=OS X Preference Pane WebService]]

2. Leave all fields the way they are, and click on {{Code|Start WebService}} to run the WebService.

3. You can determine that the WebService is running by looking at the status on the right side.

[[File:OSX PreferencePane Webservice Running.png|link=|alt=OS X PreferencePane WebService Running]]

4. Ensure that the Phidget is plugged in to the host.

5. On the client's Phidget Preference Pane, open up the {{Code|Bonjour}} tab. You will see the Phidget that is plugged into the host as one of the entries listed. Double click it to open the example application.

[[File:OSX PreferencePane Bonjour.png ‎‎ |link=|alt=OS X PreferencePane Bonjour.png ‎]]

6. The example application will open up, and you will be able to communicate with the Phidget over the WebService.

[[File:OSX PreferencePane Example.png ‎ |link=|alt=OS X PreferencePane Example]]

7. You can confirm that the WebService was indeed behind this exchange by terminating the WebService process while still allowing the remote program to run. On the host's Phidget Preference Pane, traverse to the {{Code|WebService}} tab. Hit {{Code|Stop WebService}} to terminate the WebService.

[[File:OSX PreferencePane Webservice Running.png|link=|alt=OS X PreferencePane WebService Running]]

8. Take a look at the example application on the client. Since the application can no longer connect to the WebService, there is nothing attached.

[[File:OSX PreferencePane Example Stopped.png |link=|alt=OS X PreferencePane Example Stopped]]

===Debugging the WebService===

In addition to enabling [[General Phidget Programming#Logging|logging]] in your Phidget code, you can get additional debugging information from the WebService itself. This additional debugging can only be enabled from the command line approach to start the WebService. Debug information is enabled by specifying the {{Code|-v}} option:

<div class="source">
<syntaxhighlight lang=bash>
phidgetwebservice21 -v -n "myServer"
</syntaxhighlight>
</div>

The debugging information will be shown as output in the command line console.

==Advanced Uses==

==Appendix==

===Description of Installer files===

Here is the list of files and their description for each file the installer puts onto your system.
===Description of Library files===

This section will explain the files that were placed onto your system as part of the installation process.
* <b>{{Code|Phidget21.framework}}</b> contains the actual Phidget library, which is used at run-time. It is placed into {{Code|/Library/Frameworks}}.
* <b>{{Code|Phidget.kext}}</b> is the kernel extension. It is placed into {{Code|/System/Library/Extensions}}.
* <b>{{Code|libphidget21.jnilib}}</b> is the JNI library for Java. It is placed into {{Code|/Library/Java/Extensions}}.
* <b>{{Code|Phidgets.prefpane}}</b> is the Phidgets Preference Pane. It is placed into {{Code|/Library/PreferencePanes}}.
* <b>{{Code|phidgetwebservice21}}</b> is the Phidget WebService. It is placed into {{Code|/usr/bin}}.
* <b>{{Code|PhidgetsOSA.app}}</b> is the the Phidgets agent for AppleScript. It is placed into {{Code|/Library/ScriptingAdditions}}.

==Common Problems and Solutions==

None, yet.

OS - Windows

2012-06-29T20:41:48Z

Cora:

[[Category:OS]]
{{OSLang|[[File:icon-Windows.png|64x64px|link=OS - Windows]]|Windows, Phidgets can be either plugged directly into a USB Port or run over a network using the [[#WebService | WebService]].
}}
__TOC__

Phidgets are designed to run on '''Windows 2000 or newer''', on both 32 and 64-bit systems.

==Quick Downloads==

If this is your first Phidget, we highly recommend working through the ''Getting Started'' guide for your specific Phidget device, which may be found on its product page on [{{SERVER}} main website]. If you already have the [[File:Ph.jpg]] icon in your task bar and know how to use it, then you've already followed the guide and are ready to learn more about the control panel, the Phidget WebService, and more - all specific to Windows.

If you are already a pro, and just want the drivers:

*[{{SERVER}}/downloads/libraries/Phidget-x86.exe 32 Bit Installer Download]
*[{{SERVER}}/downloads/libraries/Phidget-x64.exe 64 Bit Installer Download]

For special cases where you want to install the Phidget libraries without the installer, please see the [[#Advanced Uses | Advanced Uses]] section.
*[{{SERVER}}/downloads/libraries/Phidget21-windevel.zip Phidget21 Libraries] (32-Bit and 64-Bit development files without an installer)
*[{{SERVER}}/Drivers_Info.html#windows Software License]

==Getting Started with Windows==

===Installing===

The Phidget installer requires that your system has .NET framework 2.0 or higher. The .NET framework can be downloaded from [http://www.microsoft.com/net Microsoft]. If you do not have the .NET framework 2.0 or later installed, you can still use Phidgets. However, you won't be able to use the installer, and will have to manually install the Phidget libraries. Please see the [[#Advanced Uses | Advanced Uses]] section.

To install the libraries, follow these steps:

1. Download one of the Phidget installer for your system, depending on whether your system is 32 or 64-bit.
*[{{SERVER}}/downloads/libraries/Phidget-x86.exe 32-bit]
*[{{SERVER}}/downloads/libraries/Phidget-x64.exe 64-bit]

2. Open up the installer, and proceed through the wizard.

[[File:Windows Install.PNG|link=|alt=Windows Install]]

Please note that by default, the installer places the [[#Description of Installer files | Phidget libraries]] in {{Code|C:\Program Files\Phidgets}}.

3. Once the installation is complete, you are ready to program with Phidgets. To find out what files got installed, please see [[#Description of Installer files | Description of Installer files]] in the Appendix section.

Next, the Phidget Control Panel will be discussed.

====Phidget Control Panel====

The Phidget Control Panel is a tool to quickly determine whether your system is able to communicate with Phidgets, and also act as a debugging tool.

Once the Phidget libraries are installed using the installer, you should see the [[File:Ph.jpg]] icon in the taskbar. Double click on it to bring up the Phidget Control Panel. If the icon does not appear, just find and open the Phidget Control Panel from the start menu.

[[File:Windows ControlPanel General.PNG|link=|alt=Windows Control Panel General]]

The general tab shows the list of Phidgets currently physically attached to the computer. You can also view the currently installed Phidget library version, as well as having the checkbox option to choose whether the Phidget Control Panel is to be started up automatically once Windows boots up. You can double click on a Phidget device in the Phidget Control Panel to open up an example program for the device.

[[File:Windows ControlPanel Example.PNG|link=|alt=Windows Control Panel Example]]

In the above screenshot, the RFID example was opened. These examples are intended for demonstration and debugging purposes. If you have not yet already, please see the '''Getting Started''' guide for your device, which is found on its product page on [{{SERVER}} main website]. It is important to keep in mind that when an example Phidget application is opened from the Phidget Control Panel or opened from any of your Phidget applications that you develop, it holds a lock on the Phidget. This prevents any other program from accessing the Phidget. Please ensure that this example application is closed(the Phidget Control Panel can still be running) when you are running your own applications.

The next tab is the {{Code|WebService}} tab, which allows you to control Phidgets over a network. There are four sub-tabs. The first sub-tab is the {{Code|Setup}} tab.

[[File:Windows ControlPanel WebService Setup Running.PNG|link=|alt=Windows Control Panel WebService Setup]]

Here, you can start and stop the WebService. Details are provided in the [[#WebService | WebService]] section. You can also determine whether the Phidget WebService is currently running. There is also a check box that you can select to turn on verbose output, which will display useful troubleshooting information for the WebService.

The next sub-tab is the {{Code|Output}} tab, which provides useful debugging information while you are using the WebService. This tab will only show up if the verbose output option is selected in the previous tab.

[[File:Windows ControlPanel WebService Output.PNG|link=|alt=Windows Control Panel WebService Output]]

The {{Code|Dictionary}} sub-tab comes next; it lists all the key-value pairs that gets created when the WebService runs. More information is provided in the [[General Phidget Programming#Using the Dictionary|Dictionary]] section of the [[General Phidget Programming|General Phidget Programming]] page.

[[File:Windows ControlPanel WebService Dictionary.PNG|link=|alt=Windows Control WebService Dictionary]]

The {{Code|Bonjour}} sub-tab gives a list of all currently attached Phidgets that are connected to the WebService. This tab will only appear if you have [http://www.apple.com/support/downloads/bonjourforwindows.html Bonjour] installed onto your system. You can also double click on the Phidget to connect to it over the network using one or more computers, but still use the Phidget on the computer it is directly connected to.

[[File:Windows ControlPanel WebService Bonjour.PNG|link=|alt=Windows Control Panel WebService Bonjour]]

The last tab is the {{Code|PhidgetSBC}} tab, which displays the complete list of any PhidgetSBCs connected to the network. This tab will be enabled if you have [http://www.apple.com/support/downloads/bonjourforwindows.html Bonjour] installed onto your system.

[[File:Windows ControlPanel WebService PhidgetSBC.PNG|link=|alt=Windows Control Panel WebService PhidgetSBC]]

You can double click on the PhidgetSBC to bring up the PhidgetSBC Administration Console log-in page in your default browser.

[[File:PhidgetSBCAdminConsole.PNG|link=|alt=PhidgetSBC Admin Console]]

The PhidgetSBC Administration Console is where you can go to configure the PhidgetSBC. For more details, please see the [[1072 - Getting Started | PhidgetSBC]] section.

===Checking===

To confirm the libraries were installed and work correctly, you can check both the hardware and software components of the interface. It is worth checking the software side first, because if it works then you know the hardware side is also okay.

====Software====

If you have the Phidgets library installed on your system, you can verify that the software side component is working by seeing if a Phidget device is listed in the {{Code|General}} tab of the Phidget Control Panel.

[[File:Windows_ControlPanel_General.PNG|link=|alt=Windows Control Panel General]]

The above screenshot shows that a PhidgetRFID and a PhidgetInterfaceKit are attached to the computer. If you see your Phidget in the list, you can continue to the [[#Programming Languages | programming languages]] section to learn more. If you are not able to see that the Phidget is in the list, there may be a hardware issue. Please see the [[#Hardware| hardware]] section for more details.

====Hardware====

You can verify that your computer detects that the Phidget is plugged in through a USB connection by going to the Windows Device Manager.
On Windows XP, you can access the Device Manager by accessing the start menu, right clicking on {{Code|Computer}} and selecting {{Code|Properties}}. Next, select {{Code|Advanced System Settings}} to open up a new Window. Here, open up the {{Code|Hardware}} tab and select {{Code|Device Manager}}. The Device Manager window will open.

[[File:Windows7 DeviceManager.PNG|link=|alt=Windows Device Manager]]

Under the {{Code|Human Interface Devices}} heading, you can view whether your computer detects that the Phidget is connected through the USB if it is in the list. There should be a {{Code|HID-compliant device}} and a {{Code|USB Input Device}} entry for every Phidget that is attached to the computer. Please note that there is currently no way of directly determining which entry belongs to which Phidget. A simple way of verifying which entry belongs to which Phidget is to simply connect or disconnect the Phidget from the USB port of the computer. The list will automatically refresh to show the updated list of all connected USB devices.

If you don't see the Phidget in the list, then take a look at the [[#Troubleshooting|troubleshooting]] section below, as well as the '''Communications''' section of our [[General Troubleshooting#Communications Troubleshooting|general troubleshooting page]].

====Troubleshooting====

If the examples '''do not''' work but USB '''does''' work (i.e. your computer can consistently see the device in the [[#Hardware|hardware]]), take a moment to check the basics:
* You are using Windows 2000 or newer.
* The Phidget Control Panel requires that you have .NET framework 2.0 or newer.
* No other programs, drivers, or processes are using that USB port in software. Some drivers or software will sometimes mistakenly claim Phidget devices when waiting on some hardware to be connected. Please see the section: [[#Issue: Some third party software prevents communications with Phidgets|third party software prevents communications with Phidgets]] for more information.
* The Phidget libraries are the latest version (visit the [[#Quick Downloads| getting started section]] to download them)
* Check the [[#Common Problems and Solutions|common problems]] section below, some specific combinations can cause problems

If your problem doesn't seem to be fixed by these steps, make sure that the Phidget is seen '''consistently''' by USB (if it is erratic, try our [[General Troubleshooting|general troubleshooting guide]]). If you are still having problems after using the troubleshooting guide, please [[Contact Us|ask us]]!

==Programming Languages==

Phidgets’ philosophy is that you do not have to be an electrical engineer in order to do projects that use devices like sensors, motors, motor controllers, and interface boards. All you need to know is how to program.

After you have installed the drivers above, you should pick a programming language, install libraries, and run the examples for that specific language. You can learn more about what is needed to program in a particular language by choosing the language of your preference below. If you need help choosing a language, please look at the [[Software Overview#Language Support |language comparison table]].

On Windows, we recommend the following languages:

*[[Language - C Sharp|C#]]
*[[Language - C/C++|C/C++]]
*[[Language - Flash AS3|Flash AS3]]
*[[Language - Java|Java]]
*[[Language - LabVIEW|LabView]]
*[[Language - Max/MSP|Max/MSP]]
*[[Language - Python|Python]]
*[[Language - Visual Basic .NET|Visual Basic .NET]]
*[[Language - Visual Basic 6.0|Visual Basic 6.0]]

You can also use these languages, but they do not support [[General Phidget Programming#Event Driven Code | event driven code]], and must use [[General Phidget Programming#Logic Code | logic code]] only:

*[[Language - MATLAB|MATLAB]]
*[[Language - Simulink|Simulink]]

The following languages are also supported, but due to a lack of demand, the full API is not implemented. Please refer to the specific language for more information on what features are unsupported.
*[[Language - Adobe Director|Adobe Director]]
*[[Language - AutoIt|AutoIt]]
*[[Language - Delphi|Delphi]]
*[[Language - LiveCode|LiveCode]]
*[[Language - Visual Basic for Applications|Visual Basic for Applications]]
*[[Language - Visual Basic Script|Visual Basic Script]]

==WebService==

The Phidget WebService allows you to remotely control a Phidget over a network. For more information, please see the [[Phidget WebService|Phidget WebService]] page.

Drivers for the Phidget WebService on Windows are already included in the [[#Quick Downloads | Drivers]] above. If you have a [[File:Ph.jpg]] icon in your taskbar, you already have the WebService drivers installed.

There are two ways that you can connect to a Phidget hosted on another computer. The first method is by using the IP address/host name and port of the host computer. The second method makes the use of [http://en.wikipedia.org/wiki/Multicast_DNS mDNS], which allows Phidgets to be found and opened on the network by a server id instead of an IP address/host name. When using a server id, both the client and server will need to be running an implementation of zero configuration networking. The Phidget WebService takes advantage of the [http://www.apple.com/support/downloads/bonjourforwindows.html Bonjour] software. It is a tool, developed by Apple to locate devices such as Phidgets, and printers. You will have to install Bonjour onto your system to use the second method.

This section helps you install, check, and use the WebService on Windows, but we also have an overview of the [[Phidget WebService]] in general.

===Turning the WebService On and Off===

There are two methods that can be used to turn the WebService on and off. The first method is through the Phidget Control Panel. In the {{Code|WebService}} tab, you can start, restart or stop the WebService. You can also choose to have the WebService start up automatically upon Windows boot up by selecting {{Code|Automatic}} as the {{Code|Startup Type}}. By leaving the {{Code|Startup Type}} as {{Code|Manual}}, you will have to manually turn the WebService on everytime you wish to use it.

[[File:Windows ControlPanel WebService Setup Stopped.PNG|link=|alt=Windows Control Panel WebService Setup]]

The second method of turning the WebService on and off is through command line. If you used our installer, the WebService utility is automatically installed in {{Code|C:\Program Files\Phidgets\PhidgetWebservice21.exe}}. Otherwise, if you wish to manually install the {{Code|PhidgetWebservice21.exe}}, you can place it anywhere on your system, and navigate to it in command line.

You can get command line help with {{Code|PhidgetWebservice21.exe}} using the {{Code|-h}} option:

<div class="source">
<syntaxhighlight lang=bash>
PhidgetWebservice21 -h
</syntaxhighlight>

<syntaxhighlight lang=text>
'phidgetwebservice21' is a Phidget and Dictionary server from Phidgets Inc. See www.phidgets.com for more information.
Usage: phidgetwebservice21 [OPTION]
All parameters are optional. The default parameters are: port=5001, ServerName=(Computer Name) and no password

Options:
-p Port
-n Server Name
-P Password
-v Debug mode
-h Display this help
</syntaxhighlight>
</div>

Mapping out which command line options to which Phidget Control Panel option is as follows:

-p: {{Code|Port}} field

-n: {{Code|ServerID}} field

-P: {{Code|Password}} field

-v: {{Code|Enable verbose output}} checkbox

To find the host name and IP address of your computer, open up the command line prompt.
*For the default server name, type {{Code|hostname}}.
*For your IP address, type {{Code|ipconfig -all}}.
**A line in the return text, will say something like {{Code|192.168.2.198}}, which is your IP.

Here are some usage examples. The Windows command line is used. Traverse to the Phidget installation directory(by default, it is located in {{Code|C:\Program Files\Phidgets}}).

To start the WebService with default parameters:
<div class="source">
<syntaxhighlight lang=bash>
PhidgetWebservice21.exe
</syntaxhighlight>
</div>

To start the WebService with a server name of {{Code|myServer}}:
<div class="source">
<syntaxhighlight lang=bash>
PhidgetWebservice21.exe -n myServer
</syntaxhighlight>
</div>

To stop the WebService, simply close the command line window or press {{Code|Ctrl}} and {{Code|c}} at the same time in the command line window.

===Using the WebService===

To use a Phidget over the WebService, you'll want to:
* Have two different computers connected to the same network. We will call the computer that has the Phidget directly connected to the USB port the host. The client will be the computer that runs a Phidget application to connect to the Phidget attached to the host. Please note that if you only have a single computer, you can also connect to the Phidget over the WebService. The computer will simply act as both a host and client. This will allow you to bypass the [[General Phidget Programming # Details for Open() | one application per Phidget limitation]].

* Start the WebService on the computer that directly connects to the Phidget
* Run your program on the remote computer that will control the Phidget over the network

The easiest way to test these steps on Windows is [http://www.apple.com/support/downloads/bonjourforwindows.html download] and install Bonjour onto both the host and client. Next, we will set up the WebService and run the Phidget program on the client. Please follow these steps:

1. On the host, open up the Phidget Control Panel and traverse to the {{Code|Setup}} tab of the {{Code|WebService}} section.

[[File:Windows ControlPanel WebService Setup Stopped.PNG|link=|alt=Windows Control Panel WebService Setup Stopped]]

2. Leave all fields the way they are, and click on {{Code|Start}} to run the WebService.

3. You can determine that the WebService is running by looking at the WebService status at the bottom of the window.

[[File:Windows ControlPanel WebService Setup Running.PNG|link=|alt=Windows Control Panel WebService Setup Running]]

4. Ensure that the Phidget is plugged in to the host.

5. On the client's Phidget Control Panel, open up the {{Code|Bonjour}} tab in the {{Code|WebService}} section. You will see the Phidget that is plugged into the host as one of the entries listed. Double click it to open the example application.

[[File:Windows ControlPanel WebService Bonjour Running.PNG|link=|alt=Windows Control Panel WebService Bonjour]]

6. The example application will open up, and you will be able to communicate with the Phidget over the WebService.

[[File:Windows ControlPanel Example.PNG|link=|alt=Windows Control Panel Example]]

7. You can confirm that the WebService was indeed behind this exchange by terminating the WebService process while still allowing the remote program to run. On the host's Phidget Control Panel, traverse to the {{Code|Setup}} tab of the {{Code|WebService}} section. Hit {{Code|Stop}} to terminate the WebService.

[[File:Windows ControlPanel WebService Setup Running.PNG|link=|alt=Windows Control Panel WebService Setup Running]]

8. Take a look at the example application on the client. Since the application can no longer connect to the WebService, the attached state of the Phidget is false.

[[File:Windows ControlPanel WebService Example Disconnected.PNG|link=|alt=Windows Control Panel WebService Example while WebService Stopped]]

===Debugging the WebService===

In addition to enabling [[General Phidget Programming#Logging|logging]] in your Phidget code, you can get additional debugging information from the WebService itself. This additional debugging can be enabled from the {{Code|Enable verbose output}} checkbox in the Phidget Control Panel.

[[File:Windows ControlPanel WebService Setup Running.PNG|link=|alt=Windows Control Panel WebService Setup]]

The debugging information is shown in the {{Code|Output}} tab.

[[File:Windows ControlPanel WebService Output Running.PNG|link=|alt=Windows Control Panel WebService Output Running]]

If you are using the command line approach to start the WebService, debug information is enabled by specifying the {{Code|-v}} option:

<div class="source">
<syntaxhighlight lang=bash>
PhidgetWebservice21.exe -v -n "myServer"
</syntaxhighlight>
</div>

The debugging information is shown command line output. This will prove useful when debugging WebService problems.

==Advanced Uses==

===Manual File Installation===

The Phidget installer installs the most commonly used files onto your system. However, there may be special cases where you want to install the Phidget libraries without the installers. This section will describe the purpose of the most important files file and cover how to manually install and distribute the libraries with your code. You can get the files [{{SERVER}}/downloads/libraries/Phidget21-windevel.zip here].

====Description of Library files====

Here is the list of files and their description for each file the installer puts onto your system. You don't need to know this if you're just using our installer, but if you are looking to distribute our libraries with your code (without your clients having to use our installer) this list will help you pick and choose what you need:

* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. It is also placed in {{Code|C:\Windows\System32}}.
* <b>{{Code|PhidgetWebService21.exe}}</b> is used to control Phidgets remotely across a network using the [[#WebService | PhidgetWebservce]].
* <b>{{Code|PhidgetWindowsService21.exe}}</b> is a Windows service that controls {{Code|PhidgetWebService21.exe}}.
* <b>{{Code|phidget21.lib}}</b> is used by your compiler to link to the dll. Your compiler has to know where this file is, by default our installer puts {{Code|phidget21.lib}} into {{Code|C:\Program Files\Phidgets}}, so you can either point your compiler to that location, or copy and link to it in a directory for your project workspace. {{Code|phidget21.lib}} is written to be compatible with most compilers - but your specific compiler may need a different format. Check our documentation for your specific compiler for details. Please note that we provide versions of the {{Code|phidget21.lib}} that are specifically optimized for 32-bit or 64-bit systems. If you are using a 64 bit versions of Windows, the {{Code|phidget21.lib}} is placed in {{Code|C:\Program Files\Phidgets}}; The 32 bit version of {{Code|phidget21.lib}} is placed in {{Code|C:\Program Files\Phidgets\x86}}.
* <b>{{Code|phidget21.h}}</b> lists all the Phidget API function calls available to your code. Your compiler also has to know where this file is. By default, our installer puts {{Code|phidget21.h}} into {{Code|C:\Program Files\Phidgets}} so you can either point your compiler to that location, or copy and link to it in a directory for your project workspace.
* <b>{{Code|phidget21.jar}}</b> is an archive containing the Phidgets library, used by the [[Language - Java | Java]] programming language.
* <b>{{Code|Phidget21.NET.dll}}</b> is the Phidgets library for .NET framework 2.0 or greater. Any .NET language can be used, including [[Language - C Sharp | C#]] , and [[Language - Visual Basic .NET | Visual Basic .NET]].
* <b>{{Code|Phidget21.NET1.1.dll}}</b> is the Phidgets library for .NET framework 1.1. Any .NET language can be used, including [[Language - C Sharp | C#]] , and [[Language - Visual Basic .NET | Visual Basic .NET]]. This version of the dll should ''only'' be used for .NET 1.1 applications, not .NET 2.0 applications.
* <b>{{Code|Phidget21.NET.XML}}</b> provides the IntelliSense in-line documentation for the .NET library in Visual Studio.
* <b>{{Code|Phidget21COM.dll}}</b> is the Component Object Model(COM) library and provides your project access to the Phidget ActiveX objects. This libraries is used by the [[Language - Adobe Director|AdobeDirector]], [[Language - AutoIt|AutoIT]], [[Language - Delphi|Delphi]], [[Language - Visual Basic 6.0|Visual Basic 6.0]], [[Language - Visual Basic for Applications|Visual Basic for Applications]], [[Language - Visual Basic Script|Visual Basic Script]].
* <b>{{Code|Phidget21Manager.exe}}</b> is a tool to quickly determine whether your system is able to control Phidgets, and also act as a debugging tool.
* <b>{{Code|Examples}} folder</b> contain example applications that allows you to quickly see if your Phidget is properly configured.
* <b>{{Code|x86 folder}} folder</b> contain the 32 bit versions of {{Code|phidget21.dll}}, {{Code|phidget21.lib}}, {{Code|Phidget21COM.dll}}. These folder will only appear on 64 bit installations and is useful if you want to code against the 32 bit libraries.

=====Special Cases of Library Install=====

Regardless of what language you will be using to program Phidgets, you will need the {{Code|phidget21.dll}} placed in the {{Code|C:\WINDOWS\system32}} directory. Additional files are needed for the language that you choose. Please refer to the documentation provided by your [[Software Overview#Language Support|language]] to determine what files are needed and the steps needed to install them onto your system.

You can find the {{Code|phidget21.dll}} in the link below:

*[{{SERVER}}/downloads/libraries/Phidget21-windevel.zip Phidget21 Libraries] (32-Bit and 64-Bit development files without an installer)

{{Code|PhidgetWebService21.exe}} is also provided in the link above.

===Windows in a Virtual Machine===

Phidgets can also be used inside a virtual machine. Instructions for VMWare and VirtualBox are provided below. Virtual PC is not supported as USB Phidgets requires a virtual platform that supports HID USB Devices and since Virtual PC does not support HID USB devices, Phidgets may not be used.

As always, please ensure that you have the latest Phidget [[#Quick Downloads | drivers]] installed on the virtual machine and that you are using the latest version of your virtual software.

<b>VMWare:</b>

To enable USB Phidgets, select Virtual Machine -> Removable Devices -> and select the Phidget Input Device -> Connect.

<b>VirtualBox</b>

To enable USB Phidgets, VirtualBox Guest Additions(Devices -> Install Guest Additions) may need to be installed. Afterwards, click on Devices -> USB Devices and select the Phidget device to enable. The state should go from Busy to Captured. VirtualBox may bring up a new hardware wizard in the host operating system, which has to be installed. Please note that Phidgets with USB hubs (for example, the [{{SERVER}}/products.php?product_id=1019 1019 Interface Kit with 6-port hub]), are undetectable; Fortunately, Phidgets that are attached to such Phidgets are detectable.

Note that Windows XP "mode" in Windows 7 does '''not''' support Phidgets.

===Installing Without an Internet Connection===
When running the Phidgets installer it will check for other applications such as .NET. Part of this requires an active internet connection. The downside to this is that even if you have the applications installed already, if you do not have an internet connection you cannot complete the installation process. There is a way around this however which involves extracting the Phidget21.msi out of the .exe installer. To do this follow these steps:

*Run the installer.
[[image:Msi-1.png|400px]]
*Once the installer has started up and you are at the first informational window, navigate to your {{Code|Local Disk\Users\"username"\AppData\Local\Temp}} folder.
*Look for the most recently modified folders. The Phidgets one will not have an obvious title, most likely a seemingly random string of numbers and characters.
[[image:Msi-2.png|500px]]
*In this folder you will find the Phidget21.msi. This can be used to install the Phidgets libraries without needing an internet connection.

==Common Problems and Solutions==

===Issue: Projects are not working after a Phidget21 reinstall===
Affected Operating Systems: '''Windows'''

Solution: You need to reset your references and library paths. When you reinstall the Phidgets drivers all of the old paths can get broken. Make sure that you are including the right header files and that you have referenced the right libraries and that should fix the problem.

===Issue: Some third party software prevents communications with Phidgets===
Affected Operating Systems: '''Windows'''

Some drivers or software will sometimes mistakenly claim Phidget devices when waiting on some hardware to be connected.
This is caused by the drivers taking every HID (human interface device) on the USB bus, effectively stealing them from the Phidgets drivers.
When this happens, the device shows up in the Phidget Control Panel at start up but examples and programs are unable to make a connection to the Phidget.
This is known to occur with Logitech QuickCam, Force Feedback Mouse, Nike, Velleman K8055, and some SteelSeries drivers.

Solution: Try shutting/uninstalling the offending driver/software down or kill its process in the task manager when using Phidgets.

===Issue: A corrupt installation fails on uninstall or repair===
Affected Operating Systems: '''Windows'''

Solution: If the normal uninstall fails, or for whatever reason, you can choose to remove the Phidget drivers manually.
Please perform the following:
# Shut down any programs using the Phidget libraries, including the WebService and the Phidget Control Panel.
# Delete {{Code|C:\Program Files\Phidgets\}}
# Remove the Phidgets key from the Registry {{Code|[-HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services PhidgetWebService21]}}.

In most cases this is enough to get the installer working again. If you need to remove all traces of the Phidgets libraries manually, perform the following additional steps:

# Unregister the COM library: {{Code|regsvr32 /u "C:\Program Files\Phidgets\Phidget21COM.dll"}}.
# Remove {{Code|Phidget21.NET}} and {{Code|Policy.2.1.Phidget21.NET}} from {{Code|C:\Windows\Assembly\}}.
# Delete {{Code|C:\Documents and Settings\All Users\Application Data\Phidgets}} if you are using WindowsXP or {{Code|C:\Users\All Users\Phidgets}} if you are using Windows Vista.
# Delete {{Code|C:\Windows\system32\phidget21.dll}}.
# Delete Phidgets from the start menu.
# Search for and remove keys mentioning Phidgets from the registry in the following locations:
#* {{Code|[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\]}}
#* {{Code|[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Installer\Products\]}}
#* {{Code|[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\AssemblyFolders\Phidgets Inc]}}
#* {{Code|[HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run\Phidget21Manager]}}
#* {{Code|[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Installer\Assemblies\Global\]}}
# Reboot

'''NOTE:''' You can go through the registry and purge any other keys mentioning Phidgets if you still have problems, but at this point you should be able to reinstall under most cases. There will also be keys relating to the installer, the .NET library and the COM library, but they should not interfere with anything.

===Issue: Event data is sporadic/slow/clumped over the WebService===
Affected Operating Systems: '''Windows'''

Windows implements 200ms delayed ACKs for network traffic. When traffic is one-way only - as it is with event data, the data will all arrive in clumps every 200ms because of delayed ACKs.

This can be a great drawback for applications which rely on low latency event data over the network. (source: http://support.microsoft.com/kb/214397)

This delayed ACK behavior can be disabled in windows to decrease event latency as documented here: http://support.microsoft.com/kb/328890

In the future, the Phidgets library may implement this differently, but so far we have been unable to match the performance achieved by disabling delayed ACK.

===Issue: Windows XP "mode" in Windows 7 does not work with Phidgets===
Affected Operating Systems: '''Windows''' (running XP in included XP mode)

Although XP supports some USB devices, its overall device support is spotty. If you need to run XP within a virtual machine, Phidgets work under both VMWare and VirtualBox - the two main virtual machine programs. However, this means you will need to own a copy of Windows XP to install into the virtual machine.

Language - Python

2012-06-29T20:33:35Z

Cora: /* Quick Downloads */

[[Category:Language]]
{{OSLang|[[File:icon-Python.png|64x64px|link=|alt=Python]]|Python is an object oriented programming language developed by the [http://www.python.org/psf/summary/ Python Software Foundation], is powerful and easy to learn.}}
__TOC__

==Introduction==

{{LanguageSupport|Python|the complete Phidget API, including events|all Phidget devices.|Windows, OS X and Linux. We provide instructions on how to set up your environment for [[#Command line | command line]], [[#IDLE | IDLE]], and [[#Eclipse with PyDev | Eclipse with PyDev]]|

Only Python 2.5 or higher is supported.}}

==Quick Downloads==

{{QuickDownloads|Python|
{{APIQuickDownloads|{{SERVER}}/documentation/PythonDoc.zip}}
{{ExtraAPIQuickDownloads|{{SERVER}}/documentation/web/PythonDoc/Phidgets.html|HTML Version of}}|
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/Python.zip|}}|
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/libraries/PhidgetsPython.zip|Python|}}
{{WindowsQuickDownloads}}
{{MacQuickDownloads}}
{{LinuxQuickDownloads}}
}}

==Getting started with Python==

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

Instructions are divided up by operating system. Choose:
*[[#Windows(2000/XP/Vista/7)|Windows 2000 / XP / Vista / 7]]
*[[#OS X |OS X]]
*[[#Linux | Linux]] (including PhidgetSBC)

==Windows (2000/XP/Vista/7)==

===Description of Library===
Python programs on Windows depend on the following. The installers in the [[#Libraries and Drivers | Quick Downloads]] section put only the {{Code|phidget21.dll}} into your system. You will need to manually put the Phidget Python Module into your system.
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. By default, it is placed in {{Code|C:\Windows\System32}}.
* <b>{{Code|Phidget Python Module}}</b> is the Phidget library for Python.
* <b>{{Code|setup.py}}</b> is used to install the Phidget module into the standard location for third party Python modules. On typical Python environments, this setup will install the Phidget Python module in the {{Code|site-packages}} directory.

If you do not want to use our installer, you can download the [{{SERVER}}/downloads/libraries/Phidget21-windevel.zip {{Code|phidget21.dll}}] and refer to our [[OS - Windows|Windows page]] for manual installation instructions.

The first thing you will have to do is to [[#Installing the Phidget Python Module |install the {{Code|Phidget Python Module}}]].
Afterwards, Running the examples and writing your own code can be fairly compiler-specific, so we include instructions for each environment below.

===Installing the Phidget Python Module===

Please start by downloading [{{SERVER}}/downloads/libraries/PhidgetsPython.zip Phidget Python Module]. After extracting the file, open up a command line terminal, traverse to the directory containing {{Code|setup.py}} and enter the following to install the Phidget Python module into the Python environment.

<div class="source">
<syntaxhighlight lang=bash>
python setup.py install
</syntaxhighlight>
</div>

===Command Line===

====Use Our Examples====
Please ensure that the Phidget Python Module is [[#Installing the Phidget Python Module | installed]] onto your system.

Next, download the [{{SERVER}}/downloads/examples/Python.zip examples] and unpack them into a folder. While these examples were written in Python 3.0, they are also compatible with Python 2.5 (with a [[#All Operating Systems: The examples produces an error while running in a Python 2.5 environment. | minor modification]]). It is probably best to start with the HelloWorld program, which will work with any Phidget. There is also an example file for your specific Phidget device. {{FindYourDevice}}

Now, open up a command line prompt and navigate to the directory of the example folder.

Next, enter the following to run the example:

<div class="source">
<syntaxhighlight lang=bash>
python example.py
</syntaxhighlight>
</div>

Once you have the Python examples running, we have a [[#Follow the Examples|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 Phidgets Python libraries. Please see the [[#Use Our Examples| Use Our Examples ]] section for instructions.

Then, in your code, you will need to reference to the Phidget Python library.

<div class="source">
<syntaxhighlight lang=python>
from Phidgets.PhidgetException import *
from Phidgets.Events.Events import *
</syntaxhighlight>
</div>

Then, you will also have to add a reference to your particular Phidget. For example, you would include the following line for a PhidgetInterfaceKit:
<div class="source">
<syntaxhighlight lang=python>
from Phidgets.Devices.InterfaceKit import *
</syntaxhighlight>
</div>

Please see the [{{SERVER}}/downloads/examples/Python.zip examples] on how to add a reference to your particular Phidget.

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

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

===IDLE===

====Use Our Examples====

Please ensure that the Phidget Python Module is [[#Installing the Phidget Python Module | installed]] onto your system.

Next, download the [{{SERVER}}/downloads/examples/Python.zip examples] and unpack them into a folder. While these examples were written in Python 3.0, they are also compatible with Python 2.5 (with a [[#All Operating Systems: The examples produces an error while running in a Python 2.5 environment. | minor modification]]). It is probably best to start with the HelloWorld program, which will work with any Phidget. There is also an example file for your specific Phidget device. {{FindYourDevice}} Now, open the example in the IDLE editor.

The only thing left to do is to run the examples! Click on Run → Run Module.

[[File:Python IDLE Run.PNG|link=|alt=Run?]]

Once you have the Python examples running, we have a [[#Follow the Examples|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 Python library. Please see the [[#Use Our Examples 2| Use Our Examples ]] section for instructions.

Then, in your code, you will need to reference to the Phidget Python library.

<div class="source">
<syntaxhighlight lang=python>
from Phidgets.PhidgetException import *
from Phidgets.Events.Events import *
</syntaxhighlight>
</div>

Then, you will also have to add a reference to your particular Phidget. For example, you would include the following line for a PhidgetInterfaceKit:
<div class="source">
<syntaxhighlight lang=python>
from Phidgets.Devices.InterfaceKit import *
</syntaxhighlight>
</div>

Please see the [{{SERVER}}/downloads/examples/Python.zip examples] on how to add a reference to your particular Phidget.

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

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

===Eclipse with PyDev===

====Use Our Examples====

1. Please ensure that the Phidget Python Module is [[#Installing the Phidget Python Module | installed]] onto your system.

2. Next, download the [{{SERVER}}/downloads/examples/Python.zip examples] and unpack them into a folder. While these examples were written in Python 3.0, they are also compatible with Python 2.5 (with a [[#All Operating Systems: The examples produces an error while running in a Python 2.5 environment. | minor modification]]). It is probably best to start with the HelloWorld program, which will work with any Phidget. There is also an example file for your specific Phidget device. {{FindYourDevice}} You will need this example source code to be imported into your project later on.

3. Next, a new project will need to be created. Generate a new PyDev project with a descriptive name such as PhidgetTest.

[[File:Python PyDev New Project.PNG|link=|alt=New Project]]

4. To import the example program into your project, right click the Project and select {{Code|Import}}.

[[File:Python PyDev Import File 1.PNG|link=|alt=Import File]]

5. On the next screen, select {{Code|File System}} and proceed to the next screen.

[[File:Python PyDev Import File 2.PNG|link=|alt=Import File]]

6. Browse to the directory where you extracted the examples into, and select the example you wish to open.

[[File:Python PyDev Import File 3.PNG|link=|alt=Import File]]

7. The only thing left to do is to run the examples! Click on Run → Run.

[[File:Python PyDev Run.PNG|link=|alt=Run?]]

Once you have the Python examples running, we have a [[#Follow the Examples|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 Python library. Please see the [[#Use Our Examples 3 | Use Our Examples ]] section for instructions.

Then, in your code, you will need to include a reference to the Phidget Python library.

<div class="source">
<syntaxhighlight lang=python>
from Phidgets.PhidgetException import *
from Phidgets.Events.Events import *
</syntaxhighlight>
</div>

You will also have to add a reference to your particular Phidget. For example, you would include the following line for a PhidgetInterfaceKit:
<div class="source">
<syntaxhighlight lang=python>
from Phidgets.Devices.InterfaceKit import *
</syntaxhighlight>
</div>

Please see the [{{SERVER}}/downloads/examples/Python.zip examples] on how to add a reference to your particular Phidget.

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

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

==OS X==

The first step in using Python on Mac is to install the Phidget libraries. Compile and install them as explained on the [[OS - OS X]] page, which also describes the different Phidget files, their installed locations, and their roles....

The next step is to install the Phidget Python module. Download it here:
* [{{SERVER}}/downloads/libraries/PhidgetsPython.zip Phidget Python Module]

Then, unpack the module and enter the root of the newly unzipped directory. There will be a script in the base directory called {{Code|setup.py}}. This is used the same way as most other distributed Python modules - from a command line type:

<div class="source">
<syntaxhighlight lang=bash>
python setup.py install
</syntaxhighlight>
</div>

This will build the module and install the built python module files into your {{Code|site-packages}} directory.

===Use Our Examples===

First, download the examples:
*[{{SERVER}}/downloads/examples/Python.zip Phidget Python Examples]

Unpack them, and enter the root directory. You will find examples specific to each Phidget device, as well as a {{Code|HelloWorld.py}} example. The {{Code|HelloWorld.py}} code is probably the easiest example to run as it will work with any Phidget device. Or you can use the example specific to your Phidget. {{FindYourDevice}}

The Phidget examples were written in Python 3.0 and this tutorial assumes its use. However, they should still be compatible with Python 2.6. To run the examples using Python 2.5, you will need to modify the example code in the exception handling to read “except RuntimeError, e:”, instead of “except RuntimeError as e:”.

If needed, make those changes to the {{Code|HelloWorld.py}} example or the one for your Phidget.

<div class="source">
<syntaxhighlight lang=bash>
python HelloWorld.py
</syntaxhighlight>
</div>

===Write Your Own Code===

When writing your code from scratch, you start it as you would any Python code, such as within a text editor like Emacs, Vi, Gedit, or Kate. In your '''{{Code|.py}}''' source code file, you must include a reference to the Phidget module:

<div class="source">
<syntaxhighlight lang=python>
from Phidgets.PhidgetException import *
from Phidgets.Events.Events import *
</syntaxhighlight>
</div>

In addition, you should include the module functions for your specific device. In the case of the Interface Kit, this would be:

<div class="source">
<syntaxhighlight lang=python>
from Phidgets.Devices.InterfaceKit import *
</syntaxhighlight>
</div>

For other devices, it would be the software object you found when running the examples above. Then, you would run your Python code the same way as the examples.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided Python examples and which has resources such as the API reference.

==Linux==

Python has excellent support on Linux.

The first step in using Python on Linux is to install the Phidget libraries. These are the core Phidget libraries, written in C, which when compiled become part of the programming libraries available to your system. Download, compile, and install from the links and instructions on the main [[OS - Linux | Linux page]]. That Linux page also describes the different Phidget files, their installed locations, and their roles.

The next step is to install the Phidget Python module. Download it here:
* [{{SERVER}}/downloads/libraries/PhidgetsPython.zip Phidget Python Module]

Then, unpack the module and enter the root of the newly unzipped directory. There will be a script in the base directory called {{Code|setup.py}}. This is used the same way as most other distributed Python modules - from a command line type:

<div class="source">
<syntaxhighlight lang=bash>
python setup.py install
</syntaxhighlight>
</div>

This will build the module and install the built python module files into your {{Code|site-packages}} directory.

===Use Our Examples===

First, download the examples:
*[{{SERVER}}/downloads/examples/Python.zip Phidget Python Examples]

Unpack them, and enter the root directory. You will find examples specific to each Phidget device, as well as a {{Code|HelloWorld.py}} example. The {{Code|HelloWorld.py}} code is probably the easiest example to run as it will work with any Phidget device. Or you can use the example specific to your Phidget. {{FindYourDevice}}

The Phidget examples were written in Python 3.0 and this tutorial assumes its use. However, they should still be compatible with Python 2.6. To run the examples using Python 2.5, you will need to modify the example code in the exception handling to read “except RuntimeError, e:”, instead of “except RuntimeError as e:”.

If needed, make those changes to the {{Code|HelloWorld.py}} example or the one for your Phidget.

Then, if you have not set up [[OS_-_Linux#Setting_udev_Rules|your udev rules for USB access]], you will need to run the Python example as '''root''':

<div class="source">
<syntaxhighlight lang=bash>
sudo python HelloWorld.py
</syntaxhighlight>
</div>

===Write Your Own Code===

When writing your code from scratch, you start it as you would any Python code on Linux, such as within a text editor like Emacs, Vi, Gedit, or Kate. In your '''{{Code|.py}}''' source code file, you must include a reference to the Phidget module:

<div class="source">
<syntaxhighlight lang=python>
from Phidgets.PhidgetException import *
from Phidgets.Events.Events import *
</syntaxhighlight>
</div>

In addition, you should include the module functions for your specific device. In the case of the Interface Kit, this would be:

<div class="source">
<syntaxhighlight lang=python>
from Phidgets.Devices.InterfaceKit import *
</syntaxhighlight>
</div>

For other devices, it would be the software object you found when running the examples above. Then, you would run your Python code the same way as the examples.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided Python examples and which has resources such as the API reference.

==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 Python code will be our Python API information, with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|both of which are available in Python|[{{SERVER}}/documentation/PythonDoc.zip Python API]}}

===Example Flow===

{{ExamplePseudocode|In Python, you can name these '''event''' functions whatever you like. You will then pass their function names 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 Python 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.|
[{{SERVER}}/documentation/PythonDoc.zip Python API]}}

===Code Snippets===

Specific calls in Python 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 Python 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 [{{SERVER}}/products.php?product_id=1018 Phidget Interface Kit] as our device, the general calls would look like this:

====Step One: Initialize and Open====

<div class="source">
<syntaxhighlight lang=python>
# Create
try:
device = InterfaceKit()
except RuntimeError as e:
print("Runtime Error: %s" % e.message)

# Open
try:
device.openPhidget()
except PhidgetException as e:
print (“Phidget Exception %i: %s” % (e.code, e.detail))
exit(1)
</syntaxhighlight>
</div>

The variable {{Code|device}} is now a handle for the Phidget. This example is ''specific to the Interface Kit'' because the call InterfaceKit() is used. For another device, use the correspondingly named call in the Python API.

The handle '''device''' is then used for all the Python function calls using the Phidget for its device-specific functions - in this case, Interface Kit specific functions. Every type of Phidget also inherits functionality from the Phidget base class.

Note that open() opens the software object, but not hardware. So, it is not a guarantee you can use the Phidget immediately. The different types of open can be used with parameters to try and get the first device it can find, open based on its serial number, or even open across the network. The API manual lists all of the available modes that open provides.

Also note that you can catch exceptions thrown by the Phidget library as we did above when using the openPhidget() call. In other words, this should probably be present around most of your Phidget calls, especially when you are learning how to use the Phidget and debugging your code:

<div class="source">
<syntaxhighlight lang=python>
try:
# Your code goes here
except PhidgetException as e:
print (“Phidget Exception %i: %s” % (e.code, e.detail))
exit(1)
</syntaxhighlight>
</div>

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

To use the Phidget, it must be plugged in (attached). We can handle this simply by calling waitForAttachment. This function works for any Phidget. WaitForAttachment will block indefinitely until a connection is made to the Phidget, or an optional timeout is exceeded:

<div class="source">
<syntaxhighlight lang=python>
device.waitForAttach(10000)
print ("%d attached!" % (device.getSerialNum()))
</syntaxhighlight>
</div>

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:

<div class="source">
<syntaxhighlight lang=python>
def AttachHandler(event):
attachedDevice = event.device
serialNumber = attachedDevice.getSerialNum()
deviceName = attachedDevice.getDeviceName()
print("Hello to Device " + str(deviceName) + ", Serial Number: " + str(serialNumber))

# Insert code for -creating- device here....

try:
device.setOnAttachHandler(AttachHandler)
except PhidgetException as e:
# Insert code for handling any exceptions
# A common exception will occur if you do not create the device properly above

# Insert code for -opening- device here....
</syntaxhighlight>
</div>

====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 [{{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:

<div class="source">
<syntaxhighlight lang=python>

# Get a data point from Analog Port 0
device.getSensorValue(0)

# Set digital output port 0 to be on
device.setOutputState(0, 1)

</syntaxhighlight>
</div>

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

<div class="source">
<syntaxhighlight lang=python>

def sensorChanged(e):
print (“Sensor %i: %i” % (e.index, e.value))
return 0

# Insert code to create an Interface Kit called 'device'

# Hook our function above into the device object
device.setOnSensorChangeHandler(sensorChanged)

# Insert code to open 'device'

</syntaxhighlight>
</div>

====Step Four: Close and Delete====

At the end of your program, don’t forget to call closePhidget() to free any locks on the Phidget that the openPhidget() call put in place!

<div class="source">
<syntaxhighlight lang=python>

device.closePhidget()

</syntaxhighlight>
</div>

{{MoreHowTos}}

The ''complete'' set of functions you have available for all Phidgets can be found in the [{{SERVER}}/documentation/PythonDoc.zip Python 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 on its product page on our [{{SERVER}} main website].

==Common Problems and Solutions/Workarounds==

==={{ProblemSolution|OS X|My application hangs when using multiple devices in a single Python application.}}===

A call to {{Code|open}} may hang indefinitely if multiple devices are being programmed in a single Python application. To circumvent this, allow the application to delay a short period between {{Code|open}} calls. For most environments, a 1.25 millisecond delay is enough. For example:
<div class="source">
<syntaxhighlight lang=python>
import time
...
interface_kit.openPhidget(94695)
time.sleep(0.00125)
rfid.openPhidget(33502)
</syntaxhighlight>
</div>

==={{ProblemSolution|All Operating Systems|The examples produce an error while running in a Python 2.5 environment.}}===

Running the examples produces an error similar to the following:
<div class="source">
<syntaxhighlight lang=python>
InterfaceKit-simple.py:33: Warning: 'as' will become a reserved keyword in Python 2.6
File "InterfaceKit-simple.py", line 33
except RuntimeError as e:
SyntaxError: invalid syntax
</syntaxhighlight>
</div>

To run the example code in Python 2.5, all the lines containing:
<div class="source">
<syntaxhighlight lang=python>
except RuntimeError as e:
</syntaxhighlight>
</div>
will need to be replaced with:
<div class="source">
<syntaxhighlight lang=python>
except Runtime, e:
</syntaxhighlight>
</div>

And then it should run.

Language - LabVIEW

2012-06-29T20:32:45Z

Cora: /* Quick Downloads */

[[Category:Language]]
{{OSLang|[[File:icon-LabVIEW.png|64x64px|link=|alt=]]|LabVIEW, developed by [http://www.ni.com National Instruments] is dataflow programming language for data processing.}}
__TOC__

==Introduction==

{{LanguageSupport|LabVIEW|the complete Phidget API, including events|all Phidget devices.| Windows. A minimum version of LabVIEW 7.1.1 is required to use the Phidget LabVIEW 32 bit library. For the Phidget LabVIEW 64 bit library, a minimum version of LabVIEW 2009 is required. OS X and Linux are unsupported as the Labview/Phidgets combination has not been tested on those systems.|}}

==Quick Downloads==
{{QuickDownloads|LabVIEW|
{{APIQuickDownloads|{{SERVER}}/documentation/LabVIEW_Manual.pdf PDF}}
{{ExtraAPIQuickDownloads|{{SERVER}}/documentation/web/LabVIEWDoc/index.html|HTML version of}}|
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/LabVIEWx866.zip| (32 bit Windows - same file as LabVIEW library)}}
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/LabVIEWx64.zip| (64 bit Windows - same file as LabVIEW library)}}|
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/examples/LabVIEWx86.zip|LabVIEW|(32 bit Windows - same file as LabVIEW Examples)}}
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/examples/LabVIEWx64.zip|LabVIEW|(64 bit Windows - same file as LabVIEW Examples)}}
{{WindowsQuickDownloads}}
}}

==Getting started with LabVIEW==

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

==Windows (2000/XP/Vista/7)==

===Description of Library Files===
LabVIEW programs on Windows depend on the following two items, The installers in the [[#Libraries and Drivers|Quick Downloads]] section put only the {{Code|phidget21.dll}} into your system. You will need to manually put the Phidget LabVIEW library onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. By default, it is placed in {{Code|C:\Windows\System32}}.
* <b>{{Code|Phidgets LabVIEW library}}</b> contains the Phidget library for LabVIEW. You need to place the library into your LabVIEW functions palette. Instructions are explained in the [[#Write Your Own Code | Write Your Own Code]] section.

If you do not want to use our installer, you can download the [{{SERVER}}/downloads/libraries/phidget21-x86.zip {{Code|phidget21.dll}}] and manually install it where you want; refer to our [[OS_-_Windows#Manual_File_Installation | Manual Installation Instructions]].

We include instructions for LabVIEW 2011 on [[#Use Our Examples | using our examples]] and [[#Write Your Own Code | writing your own code]].

====Use Our Examples====

To run the examples, you first download the examples found in the [[#Example Code | Quick Downloads]] section and unpack them into a folder. Here, you will find the {{Code|examples}} folder, which contains {{Code|vi}} programs for all the devices. Each {{Code|vi}} example demonstrate the usage of a few of the device's properties. To get a broader understanding of the device, you should take a look at all the {{Code|vi}} examples inside the directory for your device. {{FindYourDevice}}

1. Inside the {{Code|examples}} folder, navigate to the directory for your device.

2. Open up any {{Code|.vi}} of your choice in LabVIEW. In this section, the {{Code|Sensor to Output Example.vi}} of the PhidgetInterfaceKit examples will be used.

[[File:LabVIEW Win Front Panel.PNG|link=|alt=Front Panel]]

You will see the front panel of the example. The front panel shows the user interface of the {{code|vi}} program.

3. Next, let us take a look at the block diagram by navigating to {{Code|Window → Show Block Diagram}}.

[[File:LabVIEW Win Block Diagram 1.PNG|link=|alt=Block Diagram]]

The block diagram shows the logic of the application.

[[File:LabVIEW Win Block Diagram 2.PNG|link=|alt=Block Diagram]]

4. The only thing left to do is to run the examples! Navigate to {{Code|Operate → Run}}.

[[File:LabVIEW Win Run 1.PNG|link=|alt=Run]]

5. The application will run.

[[File:LabVIEW Win Run 2.PNG|link=|alt=Run]]

You can determine that your device is connected to your application if you see the indicator for {{Code|attached}} turn green and the correct serial number is displayed. These features are available in most of the example {{Code|vis}} we provide.

6. When you are ready to terminate the application, click on the [[File:LabVIEW Win Stop.PNG|link=|alt=Stop]] button to release the hold on the device. Please keep in mind that the application may not terminate properly if you stop it by clicking on {{Code|Operate → Stop}}.

Once you have the LabVIEW examples running, we have a [[#Follow the Examples|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 add the Phidget LabVIEW library to your development environment. To begin:

1. Navigate to {{Code|Tools → Advanced → Edit Palette Set}} to modify the functions palette.

[[File:LabVIEW Win Functions Palette 1.PNG|link=|alt=Edit Function Palette]]

2. The functions palette will show up. Right click an empty area, and select {{Code|Insert → Subpalette}}.

[[File:LabVIEW Win Functions Palette 2.PNG|link=|alt=Insert Function Palette]]

3. Next, select {{Code|Link to a directory}}.

[[File:LabVIEW Win Functions Palette 3.PNG|link=|alt=Link to a library]]

4. Make sure you have the Phidget LabVIEW library and examples in the [[#Libraries and Drivers| Quick Downloads]] section downloaded and extracted. After extracting, you will find the {{Code|Phidgets}} folder. In LabVIEW, browse to the {{Code|Phidgets}} folder, and select {{Code|Current Folder}}.

[[File:LabVIEW Win Functions Palette 4.PNG|link=|alt=Select Phidgets library]]

This will load the Phidget LabVIEW library into the functions palette. You can find all the functions that pertain to Phidgets inside the {{Code|Phidgets}} palette.

[[File:LabVIEW Win Functions Palette 5.PNG|link=|alt=Phidgets LabVIEW Library]]

5. Click on {{Code|Save Changes}} in the {{Code|Edit Controls and Functions Palette Set}} window.

[[File:LabVIEW Win Functions Palette 6.PNG|link=|alt=Save Function Palette]]

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

The same [[#Follow the Examples|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.

Since LabVIEW is a graphical language, the best way to get the 'code snippets' you need is to take them from our examples. The best way to find what blocks exist and how to use them is probably to switch between the block diagram view and the GUI view between examples that apply to you. This will allow you to use pieces from our examples to create your own LabVIEW application.

Your main reference for writing LabVIEW code will be our LabVIEW API information, with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|both of which are available in LabVIEW|[{{SERVER}}/documentation/LabVIEW_Manual.pdf API Manual]}}

If you are really getting in to using Phidgets, you probably want our more general programming resources as well. Although these are focused on the text-based languages that we support (C++, Java, etc), the concepts remain the same on how Phidgets are used within code. Our [[General Phidget Programming]] page gives more information about:
* [[General Phidget Programming#Using Multiple Phidgets|Using Multiple Phidgets]] (or a Phidget [[General Phidget Programming#Creating a Software Object|other than the Interface Kit]])
* Catching [[General Phidget Programming#Exceptions and Errors|exceptions and errors]] and [[General Phidget Programming#Logging|using logging]]
* [[General Phidget Programming#Event Driven Code|Event catching]] versus [[General Phidget Programming#Logic Code|direct polling]]
* And more....
Of course, most of these concepts are covered using block flow within LabVIEW, but knowing the general order of operations can help you structure your code.

==Common Problems and Solutions/Workarounds==

===Issue: Events can occasionally cause issues, especially when there are multiple of the same type of event===
In other words, if you open 2 Interface Kits and have a sensor change event for each one your system can behave unpredictably. To solve this issue you have to stop using events and simply poll the device. Events work similarly to polling in LabVIEW anyway and should not cause substantial performance changes to your application.

Note that Phidgets do not always work cleanly in Labview. Sometimes they do not appear, sometimes they work veeerrryyy slowly. No known fixes yet, hopefully soon.

Language - LabVIEW

2012-06-29T20:32:30Z

Cora: /* Quick Downloads */

[[Category:Language]]
{{OSLang|[[File:icon-LabVIEW.png|64x64px|link=|alt=]]|LabVIEW, developed by [http://www.ni.com National Instruments] is dataflow programming language for data processing.}}
__TOC__

==Introduction==

{{LanguageSupport|LabVIEW|the complete Phidget API, including events|all Phidget devices.| Windows. A minimum version of LabVIEW 7.1.1 is required to use the Phidget LabVIEW 32 bit library. For the Phidget LabVIEW 64 bit library, a minimum version of LabVIEW 2009 is required. OS X and Linux are unsupported as the Labview/Phidgets combination has not been tested on those systems.|}}

==Quick Downloads==
{{QuickDownloads|LabVIEW|
{{APIQuickDownloads|{{SERVER}}/documentation/LabVIEW_Manual.pdf}}
{{APIQuickDownloads|{{SERVER}}/documentation/web/LabVIEWDoc/index.html|HTML version of}}|
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/LabVIEWx866.zip| (32 bit Windows - same file as LabVIEW library)}}
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/LabVIEWx64.zip| (64 bit Windows - same file as LabVIEW library)}}|
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/examples/LabVIEWx86.zip|LabVIEW|(32 bit Windows - same file as LabVIEW Examples)}}
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/examples/LabVIEWx64.zip|LabVIEW|(64 bit Windows - same file as LabVIEW Examples)}}
{{WindowsQuickDownloads}}
}}

==Getting started with LabVIEW==

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

==Windows (2000/XP/Vista/7)==

===Description of Library Files===
LabVIEW programs on Windows depend on the following two items, The installers in the [[#Libraries and Drivers|Quick Downloads]] section put only the {{Code|phidget21.dll}} into your system. You will need to manually put the Phidget LabVIEW library onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. By default, it is placed in {{Code|C:\Windows\System32}}.
* <b>{{Code|Phidgets LabVIEW library}}</b> contains the Phidget library for LabVIEW. You need to place the library into your LabVIEW functions palette. Instructions are explained in the [[#Write Your Own Code | Write Your Own Code]] section.

If you do not want to use our installer, you can download the [{{SERVER}}/downloads/libraries/phidget21-x86.zip {{Code|phidget21.dll}}] and manually install it where you want; refer to our [[OS_-_Windows#Manual_File_Installation | Manual Installation Instructions]].

We include instructions for LabVIEW 2011 on [[#Use Our Examples | using our examples]] and [[#Write Your Own Code | writing your own code]].

====Use Our Examples====

To run the examples, you first download the examples found in the [[#Example Code | Quick Downloads]] section and unpack them into a folder. Here, you will find the {{Code|examples}} folder, which contains {{Code|vi}} programs for all the devices. Each {{Code|vi}} example demonstrate the usage of a few of the device's properties. To get a broader understanding of the device, you should take a look at all the {{Code|vi}} examples inside the directory for your device. {{FindYourDevice}}

1. Inside the {{Code|examples}} folder, navigate to the directory for your device.

2. Open up any {{Code|.vi}} of your choice in LabVIEW. In this section, the {{Code|Sensor to Output Example.vi}} of the PhidgetInterfaceKit examples will be used.

[[File:LabVIEW Win Front Panel.PNG|link=|alt=Front Panel]]

You will see the front panel of the example. The front panel shows the user interface of the {{code|vi}} program.

3. Next, let us take a look at the block diagram by navigating to {{Code|Window → Show Block Diagram}}.

[[File:LabVIEW Win Block Diagram 1.PNG|link=|alt=Block Diagram]]

The block diagram shows the logic of the application.

[[File:LabVIEW Win Block Diagram 2.PNG|link=|alt=Block Diagram]]

4. The only thing left to do is to run the examples! Navigate to {{Code|Operate → Run}}.

[[File:LabVIEW Win Run 1.PNG|link=|alt=Run]]

5. The application will run.

[[File:LabVIEW Win Run 2.PNG|link=|alt=Run]]

You can determine that your device is connected to your application if you see the indicator for {{Code|attached}} turn green and the correct serial number is displayed. These features are available in most of the example {{Code|vis}} we provide.

6. When you are ready to terminate the application, click on the [[File:LabVIEW Win Stop.PNG|link=|alt=Stop]] button to release the hold on the device. Please keep in mind that the application may not terminate properly if you stop it by clicking on {{Code|Operate → Stop}}.

Once you have the LabVIEW examples running, we have a [[#Follow the Examples|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 add the Phidget LabVIEW library to your development environment. To begin:

1. Navigate to {{Code|Tools → Advanced → Edit Palette Set}} to modify the functions palette.

[[File:LabVIEW Win Functions Palette 1.PNG|link=|alt=Edit Function Palette]]

2. The functions palette will show up. Right click an empty area, and select {{Code|Insert → Subpalette}}.

[[File:LabVIEW Win Functions Palette 2.PNG|link=|alt=Insert Function Palette]]

3. Next, select {{Code|Link to a directory}}.

[[File:LabVIEW Win Functions Palette 3.PNG|link=|alt=Link to a library]]

4. Make sure you have the Phidget LabVIEW library and examples in the [[#Libraries and Drivers| Quick Downloads]] section downloaded and extracted. After extracting, you will find the {{Code|Phidgets}} folder. In LabVIEW, browse to the {{Code|Phidgets}} folder, and select {{Code|Current Folder}}.

[[File:LabVIEW Win Functions Palette 4.PNG|link=|alt=Select Phidgets library]]

This will load the Phidget LabVIEW library into the functions palette. You can find all the functions that pertain to Phidgets inside the {{Code|Phidgets}} palette.

[[File:LabVIEW Win Functions Palette 5.PNG|link=|alt=Phidgets LabVIEW Library]]

5. Click on {{Code|Save Changes}} in the {{Code|Edit Controls and Functions Palette Set}} window.

[[File:LabVIEW Win Functions Palette 6.PNG|link=|alt=Save Function Palette]]

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

The same [[#Follow the Examples|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.

Since LabVIEW is a graphical language, the best way to get the 'code snippets' you need is to take them from our examples. The best way to find what blocks exist and how to use them is probably to switch between the block diagram view and the GUI view between examples that apply to you. This will allow you to use pieces from our examples to create your own LabVIEW application.

Your main reference for writing LabVIEW code will be our LabVIEW API information, with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|both of which are available in LabVIEW|[{{SERVER}}/documentation/LabVIEW_Manual.pdf API Manual]}}

If you are really getting in to using Phidgets, you probably want our more general programming resources as well. Although these are focused on the text-based languages that we support (C++, Java, etc), the concepts remain the same on how Phidgets are used within code. Our [[General Phidget Programming]] page gives more information about:
* [[General Phidget Programming#Using Multiple Phidgets|Using Multiple Phidgets]] (or a Phidget [[General Phidget Programming#Creating a Software Object|other than the Interface Kit]])
* Catching [[General Phidget Programming#Exceptions and Errors|exceptions and errors]] and [[General Phidget Programming#Logging|using logging]]
* [[General Phidget Programming#Event Driven Code|Event catching]] versus [[General Phidget Programming#Logic Code|direct polling]]
* And more....
Of course, most of these concepts are covered using block flow within LabVIEW, but knowing the general order of operations can help you structure your code.

==Common Problems and Solutions/Workarounds==

===Issue: Events can occasionally cause issues, especially when there are multiple of the same type of event===
In other words, if you open 2 Interface Kits and have a sensor change event for each one your system can behave unpredictably. To solve this issue you have to stop using events and simply poll the device. Events work similarly to polling in LabVIEW anyway and should not cause substantial performance changes to your application.

Note that Phidgets do not always work cleanly in Labview. Sometimes they do not appear, sometimes they work veeerrryyy slowly. No known fixes yet, hopefully soon.

Language - Visual Basic

2012-06-29T20:29:01Z

Cora: /* Quick Downloads */

[[Category:Language]]
{{OSLang|[[File:icon-Visual Basic Net.png|64x64px|link=|alt=]]|Visual Basic .NET, developed by [http://www.microsoft.com Microsoft] is a modern object oriented programming language and the successor to [[Language - Visual Basic 6.0 | Visual Basic 6.0]].}}
__TOC__

==Introduction==

{{LanguageSupport|Visual Basic .NET|the complete Phidget API, including events|all Phidget devices.|the .NET or Mono framework. Both of the frameworks are supported on Windows. For Linux and OS X, only the Mono framework can be used. We provide instructions on how to set up your environment/compilers for [[#Visual Studio 2005/2008/2010 | Visual Studio 2005/2008/2010]], [[#Visual Studio 2003 | Visual Studio 2003]], [[#MonoDevelop | MonoDevelop]] and the [[#Mono | Mono command line compilers]]|}}

==Quick Downloads==
{{QuickDownloads|Visual Basic .NET|
{{APIQuickDownloads|{{SERVER}}/documentation/Phidget21.NET.zip .NET}}
{{ExtraAPIQuickDownloads|{{SERVER}}/documentation/web/NETDoc/Index.html|HTML Version of}}|
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/VBNET.zip|}}|
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/libraries/phidget21-x86.zip|.NET Framework Files|}}
{{WindowsQuickDownloads}}
}}

==Getting started with Visual Basic .NET==

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

Instructions are divided up by operating system. Choose:
*[[#Windows(2000/XP/Vista/7)|Windows 2000 / XP / Vista / 7]]
*[[#OS X |OS X]]
*[[#Linux | Linux]] (including PhidgetSBC)

==Windows (2000/XP/Vista/7)==

===Description of Library Files===
Visual Basic .NET programs on Windows depend on the following files, which the installers above put onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget 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|Phidget21.NET.dll}}</b> is the Phidget 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|Phidget21.NET1.1.dll}}</b> is the Phidget 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.
You can optionally install the following files:
* <b>{{Code|Phidget21.NET.XML}}</b> provides the IntelliSense in-line documentation for the .NET library in Visual Studio/MonoDevelop. This documentation is also visible in the Object Browser in Visual Studio. By default, it is placed into {{Code|C:\Program Files\Phidgets}}.
* <b>{{Code|Policy.2.1.Phidget21.NET.dll}}</b> is the policy assembly for {{Code|Phidget21.NET.dll}}. Our installer places this file in the Global Assembly Cache(GAC) directory. It directs any programs compiled against version 2.1.0 or higher of {{Code|Phidget21.NET.dll}} to use the most recent installed version.

If you do not want to use our installer, you can download the five [{{SERVER}}/downloads/libraries/Phidget21-windevel.zip files].

Running the examples and writing your own code can be fairly environment-specific, so we include instructions for [[#Visual Studio 2005/2008/2010 | Visual Studio 2005/2008/2010]], [[#Visual Studio 2003 | Visual Studio 2003]], [[#MonoDevelop | MonoDevelop]] and the [[#Mono | Mono command line compiler]].

===Visual Studio 2005/2008/2010===

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.

=====Use Our Examples=====

Please start by downloading the [{{SERVER}}/downloads/examples/VBNET.zip examples] and unpack them into a folder. While these examples were written in Visual Studio 2005 and Visual Studio 2008, Visual Studio 2010 will easily open and upgrade them with the Visual Studio Conversion Wizard.

[[File:VS2005 Conversion Wizard.PNG|link=|alt=Conversion Wizard]]

To load all projects in Visual Studio, go to File → Open → Project, and open {{Code|AllExamples/AllExamples.sln}} or {{Code|AllExamples/AllExamples_vs2008.sln}} for Visual Studio 2005 and 2008, respectively.

This will load all of the examples available for Visual Basic .NET, and then you can set your main project to be the HelloWorld project that will work with any Phidget board. Or you can choose the example that matches your device. {{FindYourDevice}}

The only thing left to do is to run the examples! Click on Debug → Start Debugging. Please note that the projects, by default try to find the {{Code|Phidget21.NET.dll}} in {{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 type Phidget is not defined, please re-add the reference to {{Code|Phidget21.NET.dll}}. Please see the [[#Write Your Own Code | Write Your Own Code ]] section for details.

[[File:VBNET VS2005 Run.PNG|link=|alt=Run]]

Once you have the Visual Basic .NET examples running, we have a [[#Follow the Examples|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 .NET library. To begin:

1. Generate a new Visual Basic .NET Console Application project with a descriptive name such as PhidgetTest.

[[File:VBNET VS2005 New Project.PNG|link=|alt=New Project]]

2. Add a reference to the Phidget .NET library.

[[File:VBNET VS2005 Add Reference 1.PNG|link=|alt=Add Reference]]

3. Under the .NET tab, select {{Code|Phidget21.NET.dll}}.
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:VBNET VS2005 Add Reference 2.PNG|link=|alt=Add Reference]]

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

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

===Visual Studio 2003===

=====Use Our Examples=====

As the Visual Basic .NET examples were written in Visual Studio 2005 and 2008, Visual Studio 2003 is not able to open the examples. Furthermore, it will be difficult to import the examples into your Visual Studio 2003 project as you will need to recreate the GUI components. Fortunately, taking a look at the source code will give you valuable programming insight. We have a [[#Follow the Examples|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 development environment to properly link the Phidget .NET library.

1. Generate a new Visual Basic Console Application project with a descriptive name such as PhidgetTest.

[[File:VBNET VS2003 New Project.PNG|link=|alt=New Project]]

2. Add a reference to the Phidget .NET library.

[[File:VBNET VS2003 Add Reference 1.PNG|link=|alt=Add Reference]]

3. Under the .NET tab, select {{Code|Phidget21.NET1.1.dll}}.
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:VBNET VS2003 Add Reference 2.PNG|link=|alt=Add Reference]]

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

The [[#Follow the Examples|teaching ]] section also has further resources for programming your Phidget.

===Mono===

This section will provide instructions on how to compile using the {{Code|vbnc}} compiler.

=====Use Our Examples=====

We do not have Visual Basic .NET examples for the Mono framework. Fortunately, you can take a look at the source code for our [{{SERVER}}/downloads/examples/CSharp.zip Visual Studio 2005 and 2008 examples] for valuable programming insight. We have a [[#Follow the Examples|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 compiler to properly link the Phidget .NET library.

Place the {{Code|Phidget21.NET.dll}} in the same directory as your source code.
To compile and build an executable, run:
<div class="source">
<syntaxhighlight lang=bash>
vbnc /out:example.exe /r:Phidget21.NET.dll Example.vb
</syntaxhighlight>
</div>

Afterwards, you will have an executable named {{Code|example.exe}} that you can run. Type the following to run the program:
<div class="source">
<syntaxhighlight lang=bash>
mono example.exe
</syntaxhighlight>
</div>

The [[#Follow the Examples|teaching]] section also has further resources for programming your Phidget.

===MonoDevelop===

=====Use Our Examples=====

Download the [{{SERVER}}/downloads/examples/VBNET.zip examples] and unpack them into a folder. Here, you can find example programs for all the devices, as well as a HelloWorld program that will run with any Phidget.

These examples were written in Visual Studio 2005 and 2008, but they are also compatible with MonoDevelop. Please note that the examples are only designed to be run under the .NET framework. The examples are not compatible with the Mono framework. Despite this, if you are using the Mono framework, you can use the code within the examples for valuable programming insight.

The rest of this section will explain the steps needed to run our examples under the .NET framework. To load all projects in MonoDevelop, go to File → Open, and open {{Code|AllExamples/AllExamples.sln}}

This will load all of the examples available for Visual Basic .NET, and then you can set your main project to be the one that matches your device. {{FindYourDevice}}

[[File:VBNET Win MonoDevelop Startup Project.PNG|link=|alt=Start Up Project]]

The only thing left to do is to run the examples! Right click the project, and click on {{Code|Run With}} and select the Microsoft .NET 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 Phidget is not defined, 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.

[[File:VBNET Win MonoDevelop Run.PNG|link=|alt=Run]]

Once you have the Visual Basic .NET examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget .NET library. To begin:

1. Create a new Visual Basic .NET console project with a descriptive name such as PhidgetTest.

[[File:VBNET Win MonoDevelop New Project.PNG|link=|alt=New Project]]

2. Add a reference to the Phidget .NET library.

[[File:VBNET Win MonoDevelop Add Reference 1.PNG|link=|alt=Add Reference]]

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.

[[File:VBNET Win MonoDevelop Add Reference 2.PNG|link=|alt=Add Reference]]

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

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

==OS X==

Visual Basic .NET has excellent support on OS X through the Mono framework.

The first step in using Visual Basic .NET on Mac is to install the Phidget libraries. Compile and install them as explained on the [[OS - OS X]] page, which also describes the different Phidget files, their installed locations, and their roles....

===Use Our Examples===

The first thing you are going to need to do is install [http://www.mono-project.com/Main_Page Mono] (Note that Mono is only available for Intel Macs and not PowerPC). You will need both the SDK and the runtime.

Then, you will need the Phidget .NET libraries. These are part of the Windows library zip file download:

* [{{SERVER}}/downloads/libraries/Phidget21-windevel.zip Phidget Windows Library Zip File]

Extract the library zip file. Descriptions for the files are available on the [[OS - Windows]] page, but for now we only need the {{Code|Phidget21.NET.dll}} file to run the Phidget VB.NET examples in Mono. So remember where you unzipped these Windows libraries - you will need to copy the {{Code|Phidget21.NET.dll}} file into your example directory shortly.

Next, you'll want to download and extract the Phidget Visual Basic .NET Examples (not the ones for .NET Compact):

* [{{SERVER}}/downloads/examples/VBNET.zip Visual Basic .NET Examples for Windows]

One more thing needs to be done before you can compile and run the examples. You need to set up a special configuration file so that Mono knows where to find the phidget21.dll. Since Mac does not use dll's you need to redirect it to the appropriate file. Create a new file in the same directory as the example you wish to compile and name it <code>Phidget21.NET.dll.config</code>. Put the following into the file:

<div class="source">
<syntaxhighlight lang=xml>
<configuration>
<dllmap dll="phidget21.dll" target="/Library/Frameworks/Phidget21.framework/Versions/Current/Phidget21" />
</configuration>
</syntaxhighlight>
</div>

All that is left is to compile and run the code. When compiling, you need to link to the Phidget library. As the Phidget21.NET file is an "additional assembly" in VB.NET/Mono, you can link to the assembly using the {{Code|-r}} "reference" switch:

To check that your Mac, Phidget, and Mono setup is all working together, you'll want to run the Visual Basic (VB) examples. You'll probably want to start with the Hello World VB example. Alternatively, you could find the source code for your device. {{Template:FindYourDevice}}

All of the .NET examples are much larger projects through Visual Studio, so you'll need to dig around within the project and find the source code and compile only that source code using Mono.

Let's say you're running the Hello World example. The source code for the example is in the directory:

:{{Code|VBNET/}} → {{Code|Hello World/}} → {{Code|Module1.vb}}

Other examples will be in directories named appropriately for their software object name, rather than {{Code|Hello World}}. Once you have found the example you want to run, copy the {{Code|Phidget21.NET.dll}} file that you unzipped earlier into that example directory where the {{Code|Module1.vb}} file is.

Then, compile the code. When compiling, you need to link to the Phidget library. As the Phidget21.NET file is an "additional assembly" in Visual Basic/Mono, you can link to the assembly using the {{Code|-r}} "reference" switch:

<div class="source">
<syntaxhighlight lang=bash>
vbnc Module1.vb -r:Phidget21.NET.dll
</syntaxhighlight>
</div>

This will compile a {{Code|*.exe}} file - in this case, {{Code|Module1.exe}}. This you can then run under Mono:

<div class="source">
<syntaxhighlight lang=bash>
sudo mono Program.exe
</syntaxhighlight>
</div>

Remember that the {{Code|sudo}} is needed unless you have your [[OS - Linux#Setting udev Rules|udev rules set on your Linux system]].

If you will be compiling with an IDE such as GTK# or MonoDevelop, we don't have explicit instructions by IDE for Linux. However, you will probably find the [[#MonoDevelop | MonoDevelop]] section in the Windows portion above useful.

===Write Your Own Code===

When writing your code from scratch, you start it as you would any Visual Basic code on OS X, such as within a text editor. In your .vb source code file, you must include a reference to the Phidget software object. In the case of a Phidget interface kit device, this would look like:

<div class="source">
<syntaxhighlight lang=vbnet>
Public Class Form1
'The Phidget object declaration

Dim WithEvents ifKit As Phidgets.InterfaceKit

'... Form1_Load and Form1_OnClosing here
End Class
</syntaxhighlight>
</div>

For other devices, check the API for your device on our webpage for the software object name, and the [{{SERVER}}/documentation/Phidget21.NET.zip API for .NET] for the specific syntax to use. Then, you would compile your completed VB code the same way as the examples above.

Mono also has a few different IDEs which you can use to develop code, and these are especially useful if you are doing GUI development. We provide instructions for MonoDevelop - one such IDE - being used [[#MonoDevelop|under Windows]].

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching section]] to help you follow the provided VB examples and which has resources such as the API reference.

==Linux==

Visual Basic .NET has support on Linux through the Mono framework.

===Use Our Examples===

The first step in using Visual Basic .NET with Phidgets on Linux is to install Mono. Although you probably have already done this if you're a Visual Basic .NET programmer, you want to make sure you have all of the packages you'll need. Try:

<div class="source">
<syntaxhighlight lang=bash>
sudo apt-get mono-complete
</syntaxhighlight>
</div>

The Visual Basic Mono framework also requires the Visual Basic .NET compiler, {{Code|vbnc}}. This can be installed via another Mono package:

<div class="source">
<syntaxhighlight lang=bash>
sudo apt-get install mono-vbnc
</syntaxhighlight>
</div>

Next, you'll want to install the main 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.

Then, you will need the Phidget .NET libraries. These are part of the Windows library zip file download:

* [{{SERVER}}/downloads/libraries/Phidget21-windevel.zip Phidget Windows Library Zip File]

Extract the library zip file. Descriptions for the files are available on the [[OS - Windows]] page, but for now we only need the {{Code|Phidget21.NET.dll}} file to run the Phidget Visual Basic examples in Mono. So remember where you unzipped these Windows libraries - you will need to copy the {{Code|Phidget21.NET.dll}} file into your example directory shortly.

Next, you'll want to download and extract the Phidget Visual Basic .NET Examples (not the ones for .NET Compact):

* [{{SERVER}}/downloads/examples/VBNET.zip Visual Basic .NET Examples for Windows]

To check that your Linux, Phidget, and Mono setup is all working together, you'll want to run the Visual Basic (VB) examples. You'll probably want to start with the Hello World VB example. Alternatively, you could find the source code for your device. {{Template:FindYourDevice}}

All of the .NET examples are much larger projects through Visual Studio, so you'll need to dig around within the project and find the source code and compile only that source code using Mono.

Let's say you're running the Hello World example. The source code for the example is in the directory:

:{{Code|VBNET/}} → {{Code|Hello World/}} → {{Code|Module1.vb}}

Other examples will be in directories named appropriately for their software object name, rather than {{Code|Hello World}}. Once you have found the example you want to run, copy the {{Code|Phidget21.NET.dll}} file that you unzipped earlier into that example directory where the {{Code|Module1.vb}} file is.

Then, compile the code. When compiling, you need to link to the Phidget library. As the Phidget21.NET file is an "additional assembly" in Visual Basic/Mono, you can link to the assembly using the {{Code|-r}} "reference" switch:

<div class="source">
<syntaxhighlight lang=bash>
vbnc Module1.vb -r:Phidget21.NET.dll
</syntaxhighlight>
</div>

This will compile a {{Code|*.exe}} file - in this case, {{Code|Module1.exe}}. This you can then run under Mono:

<div class="source">
<syntaxhighlight lang=bash>
sudo mono Program.exe
</syntaxhighlight>
</div>

Remember that the {{Code|sudo}} is needed unless you have your [[OS - Linux#Setting udev Rules|udev rules set on your Linux system]].

If you will be compiling with an IDE such as GTK# or MonoDevelop, we don't have explicit instructions by IDE for Linux. However, you will probably find the [[#MonoDevelop | MonoDevelop]] section in the Windows portion above useful.

===Write Your Own Code===

When writing your code from scratch, you start it as you would any Visual Basic code on Linux, such as within a text editor like Emacs, Vi, Gedit, or Kate. In your .vb source code file, you must include a reference to the Phidget software object. In the case of a Phidget interface kit device, this would look like:

<div class="source">
<syntaxhighlight lang=vbnet>
Public Class Form1
'The Phidget object declaration

Dim WithEvents ifKit As Phidgets.InterfaceKit

'... Form1_Load and Form1_OnClosing here
End Class
</syntaxhighlight>
</div>

For other devices, check the API for your device on our webpage for the software object name, and the [{{SERVER}}/documentation/Phidget21.NET.zip API for .NET] for the specific syntax to use. Then, you would compile your completed VB code the same way as the examples above.

Mono also has a few different IDEs which you can use to develop code, and these are especially useful if you are doing GUI development. We provide instructions for MonoDevelop - one such IDE - being used [[#MonoDevelop|under Windows]].

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching section]] to help you follow the provided VB examples and which has resources such as the API reference.

==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 Visual Basic .NET code will be our .NET API information, with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|both of which are available in .NET|[{{SERVER}}m/documentation/Phidget21.NET.zip .NET API]}}

===Example Flow===

{{ExamplePseudocode|In Visual Basic .NET, you can name these '''event''' functions whatever you like, although you must catch the events by name in the "Handles" portion of the function declaration. The "Handles" portion of the function hooks them into the actual events when they occur. See our examples for details.<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 device-specific examples to show you more detail on using your Phidget.
|Creating a Phidget software object in Visual Basic .NET 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.|
[{{SERVER}}/documentation/Phidget21.NET.zip .NET API]}}

===Code Snippets===

Specific calls in Visual Basic (VB) .NET 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 VB .NET 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.

====Step One: Initialize and Open====

The open() function opens the software object, but not hardware. So, it is not a guarantee you can use the Phidget immediately.

The different types of open can be used with parameters to try and get the first device it can find, open based on its serial number, or even open across the network. The API manual lists and [[General Phidget Programming]] discusses all of the available modes that open provides.

For example, if we were using an Interface Kit Phidget board as our device, the create and open calls would look like this:

<div class="source">
<syntaxhighlight lang=vbnet>
ifKit = New Phidgets.InterfaceKit
ifKit.open()
</syntaxhighlight>
</div>

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

To use the Phidget, it must be plugged in (attached). We can handle this by using event driven programming and tracking the AttachEvents and DetachEvents, or we can handle this by calling waitForAttachment. This function works for any Phidget. WaitForAttachment will block indefinitely until a connection is made to the Phidget, or an optional timeout is exceeded.

When combined in your initialization function with the initialization and open from above, the wait for attachment would look like this:

<div class="source">
<syntaxhighlight lang=vbnet>
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs)
Handles MyBase.Load
ifKit = New Phidgets.InterfaceKit
ifKit.open()
ifKit.waitForAttachment(3000)
End Sub
</syntaxhighlight>
</div>

====Step Three: Do Things with the Phidget====

We recommend the use of event driven programming when working with Phidgets. In VB.NET we can hook an event handler into the event of a sensor changing on an Interface Kit board with the following code:

<div class="source">
<syntaxhighlight lang=vbnet>
Private Sub ifKit_SensorChange(ByVal sender As Object, ByVal e As Phidgets.Events.SensorChangeEventArgs) Handles ifKit.SensorChange
TextBox1.Text = "Index " + e.Index.ToString() + " Value: " + e.Value.ToString()
End Sub
</syntaxhighlight>
</div>

With this function, the code inside ifKit_SensorChange will get executed every time the Phidget Interface Kit reports a change on one of its analog inputs. This is because it "Handles" the SensorChange event. Some events such as Attach and Detach belong to the base Phidget object and thus are common to all types of Phidgets.

Some values can be read and sent directly to the Phidget, simply use the instance members and properties. This is also how you would set properties on the Phidget such as the output state or
sensor sensitivity. For example, obtaining the value of analog input (sensor) 0 on an Interface Kit board would be via:

<div class="source">
<syntaxhighlight lang=vbnet>
Dim val As Integer = ifKit.sensors(0).Value
</syntaxhighlight>
</div>

====Step Four: Close and Delete====

At the end of your program, unhook any events and call Application.DoEvents(). This will make sure there are no outstanding events being processed before calling close.

<div class="source">
<syntaxhighlight lang=vbnet>
Private Sub Form1_FormClosing(ByVal sender As Object, ByVal e As System.Windows.Forms.FormClosingEventArgs) Handles Me.FormClosing
RemoveHandler ifKit.SensorChange, AddressOf ifKit_SensorChange
Application.DoEvents()
ifKit.close()
End Sub
</syntaxhighlight>
</div>

{{MoreHowTos}}

The ''complete'' set of functions you have available for all Phidgets can be found in the [{{SERVER}}/documentation/Phidget21.NET.zip .NET 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 on its product page on our [{{SERVER}} main website].

==Common Problems and Solutions/Workarounds==

==={{ProblemSolution|All Operating Systems|The Phidgets.Events.ErrorEventHandler conflicts with System.IO.ErrorEventHandler.}}===

<div class="source">
<syntaxhighlight lang=csharp>
using System.IO;
using Phidgets;
using Phidgets.Events;
...
spatial.Error += new ErrorEventHandler(spatial_Error);

...
void spatial_Error(object sender, ErrorEventArgs e){
...
}
</syntaxhighlight>
</div>

The above code produces the following errors:

{{Code|'ErrorEventHandler' is an ambiguous reference between 'System.IO.ErrorEventHandler' and 'Phidgets.Events.ErrorEventHandler'}}.

and

{{Code|'ErrorEventArgs' is an ambiguous reference between 'System.IO.ErrorEventArgs' and 'Phidgets.Events.ErrorEventArgs'}}.

The error is due to the {{Code|System.IO}} and {{Code|Phidgets.Events}} namespaces both having a class called {{Code|ErrorEventHandler}}.

To get around this issue, use the fully qualified namespace when referring to the {{Code|ErrorEventHandler}} and {{Code|ErrorEventArgs}} classes:
<div class="source">
<syntaxhighlight lang=csharp>
using System.IO;
using Phidgets;
using Phidgets.Events;
...
spatial.Error += new Phidgets.Events.ErrorEventHandler(spatial_Error);
...

void spatial_Error(object sender, Phidgets.Events.ErrorEventArgs e){
...
}

</syntaxhighlight>
</div>

Language - C Sharp

2012-06-29T20:27:31Z

Cora: /* Quick Downloads */

[[Category:Language]]
{{OSLang|[[File:icon-CSharp.png|64x64px|link=|alt=]]|C# is a modern, object-oriented programming language developed by [http://www.microsoft.com Microsoft].}}
__TOC__

==Introduction==

{{LanguageSupport|C#|the complete Phidget API, including events|all Phidget devices.|the .NET or Mono framework. Both of the frameworks are supported on Windows. For Linux and OS X, only the Mono framework can be used. We provide instructions on how to set up your environment/compilers for [[#Visual Studio 2005/2008/2010 | Visual Studio 2005/2008/2010]], [[#Visual Studio 2003 | Visual Studio 2003]], [[#MonoDevelop | MonoDevelop]] and the [[#Mono | Mono command line compilers]]|}}

==Quick Downloads==
{{QuickDownloads|C#|
{{APIQuickDownloads|{{SERVER}}/documentation/Phidget21.NET.zip .NET}}
{{ExtraAPIQuickDownloads|{{SERVER}}/documentation/web/NETDoc/Index.html|HTML Version of}}|
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/CSharp.zip|}}|
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/libraries/phidget21-x86.zip|.NET Framework Files|}}
{{WindowsQuickDownloads}}
{{MacQuickDownloads}}
{{LinuxQuickDownloads}}}}

==Getting started with C#==

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

Instructions are divided up by operating system. Choose:
*[[#Windows(2000/XP/Vista/7)|Windows 2000 / XP / Vista / 7]]
*[[#OS X |OS X]]
*[[#Linux | Linux]] (including PhidgetSBC)

==Windows (2000/XP/Vista/7)==

===Description of Library Files===
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 Phidget 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|Phidget21.NET.dll}}</b> is the Phidget 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|Phidget21.NET1.1.dll}}</b> is the Phidget 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.
You can optionally install the following files:
* <b>{{Code|Phidget21.NET.XML}}</b> provides the IntelliSense in-line documentation for the .NET library in Visual Studio/MonoDevelop. This documentation is also visible in the Object Browser in Visual Studio. By default, it is placed into {{Code|C:\Program Files\Phidgets}}.
* <b>{{Code|Policy.2.1.Phidget21.NET.dll}}</b> is the policy assembly for {{Code|Phidget21.NET.dll}}. Our installer places this file in the Global Assembly Cache(GAC) directory. It directs any programs compiled against version 2.1.0 or higher of {{Code|Phidget21.NET.dll}} to use the most recent installed version.

If you do not want to use our installer, you can download the five [{{SERVER}}/downloads/libraries/Phidget21-windevel.zip files].

Running the examples and writing your own code can be fairly compiler-specific, so we include instructions for each compiler below.

===Visual Studio 2005/2008/2010===

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.

=====Use Our Examples=====

Please start by downloading the [{{SERVER}}/downloads/examples/CSharp.zip examples] and unpacking them into a folder. 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 → Open → Project, and open {{Code|AllExamples/AllExamples.sln}} or {{Code|AllExamples/AllExamples_vs2008.sln}} for Visual Studio 2005 and 2008, respectively.

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.

[[File:VS2005 Conversion Wizard.PNG|link=|alt=Conversion Wizard]]

The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

Start by setting the {{Code|HelloWorld}} project as your start up project.

The only thing left to do is to run the example! Click on Debug → 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.

[[File:CSharp VS2005 Run.PNG|link=|alt=Run]]

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 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

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=====

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:

1. Generate a new Visual C# Windows Applications project with a descriptive name such as PhidgetTest.

[[File:CSharp VS2005 New Project.PNG|link=|alt=New Project]]

2. Add a reference to the Phidget .NET library.

[[File:CSharp VS2005 Add Reference.PNG|link=|alt=Add Reference]]

3. Under the .NET tab, select {{Code|Phidget21.NET.dll}}.
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]]

4. Then, in your code, you will need to include the Phidget .NET library:

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

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

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

===Visual Studio 2003===

=====Use Our Examples=====

1. Download the [{{SERVER}}/downloads/examples/CSharp.zip examples] and unpack them into a folder. Here, you can find the HelloWorld example which works with any Phidget. You can also find example programs for all the devices. {{FindYourDevice}}

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.

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.

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

3. Add a reference to the Phidget .NET library.

[[File:CSharp_VS2003 Add Reference 1.PNG|link=|alt=Add Reference]]

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.

[[File:CSharp_VS2003 Add Reference 2.PNG|link=|alt=Add Reference]]

5. To import the simple example program into your project, please: open up {{Code|Class1.cs}}.

6. Traverse to the example in Windows Explorer and locate the {{Code|Program.cs}} file.

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

7. Copy and paste the contents from that file into {{Code|Class1.cs}}.

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

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

9. Now, you can run the example. Click on Debug → 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=====

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 .NET library. Please see the [[#Use Our Examples 2 | Use Our Examples ]] section for instructions.

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

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

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

===Mono===

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.

=====Use Our Examples=====

Download the [{{SERVER}}/downloads/examples/CSharp.zip examples] and unpack them into a folder. Here, you can find the HelloWorld program that will work with any Phidget. You will also find example programs for all the devices. {{FindYourDevice}}.

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

Place the {{Code|Phidget21.NET.dll}} in the same directory as your source code.

To compile and build an executable, run:
<div class="source">
<syntaxhighlight lang=bash>
mcs /out:example.exe /r:phidget21.NET.dll example.cs
</syntaxhighlight>
</div>

If you have the {{Code|Phidget21.NET.dll}} installed in another location, please change the path to the file's location accordingly.

Afterwards, you will have an executable named {{Code|example.exe}} that you can run. Type the following to run the program:
<div class="source">
<syntaxhighlight lang=bash>
mono example.exe
</syntaxhighlight>
</div>

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=====

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 .NET library. Please see the [[#Use Our Examples 3 | Use Our Example ]] section for instructions.

In your code, you will need to include the Phidget .NET library:

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

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

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

===MonoDevelop===

=====Use Our Examples=====

Download the [{{SERVER}}/downloads/examples/CSharp.zip examples] and unpack them into a folder. Here, you can find example programs for all the devices, as well as a HelloWorld program that will work with any Phidget. {{FindYourDevice}}

These examples were written in Visual Studio 2005 and 2008, but are also compatible with MonoDevelop.

To load all projects in MonoDevelop, go to File → Open, and open {{Code|AllExamples/AllExamples.sln}}

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

[[File:CSharp MonoDevelop Win Start Up.PNG|link=|alt=Start Up Project]]

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.

[[File:CSharp MonoDevelop Win Run As.PNG|link=|alt=Run As]]

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=====

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 .NET library. To begin:

1. Create a new C# empty project with a descriptive name such as PhidgetTest.

[[File:CSharp MonoDevelop Win New Project.PNG|link=|alt=New Project]]

2. Add a reference to the Phidget .NET library.

[[File:CSharp MonoDevelop Win Reference.PNG|link=|alt=Add Reference]]

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.

[[File:CSharp MonoDevelop Win Reference 2.PNG|link=|alt=Add Reference]]

4. Then, in your code, you will need to include the Phidget .NET library:

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

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

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

==OS X==

The first thing you are going to need to do is install [http://www.mono-project.com/Main_Page Mono] (Note that Mono is only available for Intel Macs and not PowerPC). You will need both the SDK and the runtime.

Then, you will need the Phidget .NET libraries. These are part of the Windows library zip file download:

* [{{SERVER}}/downloads/libraries/Phidget21-windevel.zip Phidget Windows Library Zip File]

Extract the library zip file. Descriptions for the files are available on the [[OS - Windows]] page, but for now we only need the {{Code|Phidget21.NET.dll}} file to run the Phidget C# examples in Mono. So remember where you unzipped these Windows libraries - you will need to copy the {{Code|Phidget21.NET.dll}} file into your example directory shortly.

Next, you'll want to download and extract the Phidget C# Examples (For Windows, not for .NET Compact):

* [{{SERVER}}/downloads/examples/CSharp.zip C Sharp Examples for Windows]

One more thing needs to be done before you can compile and run the examples. You need to set up a special configuration file so that Mono knows where to find the phidget21.dll. Since Mac does not use dll's you need to redirect it to the appropriate file. Create a new file in the same directory as the example you wish to compile and name it <code>Phidget21.NET.dll.config</code>. Put the following into the file:

<div class="source">
<syntaxhighlight lang=xml>
<configuration>
<dllmap dll="phidget21.dll" target="/Library/Frameworks/Phidget21.framework/Versions/Current/Phidget21" />
</configuration>
</syntaxhighlight>
</div>

All that is left is to compile and run the code. When compiling, you need to link to the Phidget library. As the Phidget21.NET file is an "additional assembly" in C#/Mono, you can link to the assembly using the {{Code|-r}} "reference" switch:

<div class="source">
<syntaxhighlight lang=bash>
gmcs Program.cs -r:Phidget21.NET.dll
</syntaxhighlight>
</div>

This will compile a {{Code|*.exe}} file - in this case, {{Code|Program.exe}}. This you can then run under Mono:

<div class="source">
<syntaxhighlight lang=bash>
mono Program.exe
</syntaxhighlight>
</div>

If you will be compiling with an IDE such as GTK# or MonoDevelop, we don't have explicit instructions by IDE for OS X. However, you will probably find the [[#MonoDevelop | MonoDevelop]] section in the Windows portion above useful.

==Linux==

C# has support on Linux through the Mono framework.

===Use Our Examples===

The first step in using C# with Phidgets on Linux is to make sure that you have all of Mono installed. Although you probably have already done this if you're a C# programmer, you want to make sure you have all of the packages you'll need. Try:

<div class="source">
<syntaxhighlight lang=bash>
sudo apt-get mono-complete
</syntaxhighlight>
</div>

Next, you'll want to install the main 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.

Then, you will need the Phidget .NET libraries. These are part of the Windows library zip file download:

* [{{SERVER}}/downloads/libraries/Phidget21-windevel.zip Phidget Windows Library Zip File]

Extract the library zip file. Descriptions for the files are available on the [[OS - Windows]] page, but for now we only need the {{Code|Phidget21.NET.dll}} file to run the Phidget C# examples in Mono. So remember where you unzipped these Windows libraries - you will need to copy the {{Code|Phidget21.NET.dll}} file into your example directory shortly.

Next, you'll want to download and extract the Phidget C# Examples (For Windows, not for .NET Compact):

* [{{SERVER}}/downloads/examples/CSharp.zip C Sharp Examples for Windows]

To check that your Linux, Phidget, and Mono setup is all working together, you'll want to run the C# examples. Specifically, you'll want to run the ''simple'' C# examples. You can either use the HelloWorld program that will work with any Phidget, or you can find the source code for your device. {{FindYourDevice}}

Let's say you're running the Temperature Sensor example (for the 1048 or 1051). The source code for the example is in the directory:

:{{Code|TemperatureSensorExamples}} → {{Code|TemperatureSensor-simple}} → {{Code|TemperatureSensor-simple}} → {{Code|Program.cs}}

Other examples will be in directories named appropriately for their software object name. Once you have found the example you want to run, copy the {{Code|Phidget21.NET.dll}} file that you unzipped earlier into that example directory where the {{Code|Program.cs}} file is.

Then, compile the code. When compiling, you need to link to the Phidget library. As the Phidget21.NET file is an "additional assembly" in C#/Mono, you can link to the assembly using the {{Code|-r}} "reference" switch:

<div class="source">
<syntaxhighlight lang=bash>
gmcs Program.cs -r:Phidget21.NET.dll
</syntaxhighlight>
</div>

This will compile a {{Code|*.exe}} file - in this case, {{Code|Program.exe}}. This you can then run under Mono:

<div class="source">
<syntaxhighlight lang=bash>
sudo mono Program.exe
</syntaxhighlight>
</div>

Remember that the {{Code|sudo}} is needed unless you have your [[OS - Linux#Setting udev Rules|udev rules set on your Linux system]].

If you will be compiling with an IDE such as GTK# or MonoDevelop, we don't have explicit instructions by IDE for Linux. However, you will probably find the [[#MonoDevelop | MonoDevelop]] section in the Windows portion above useful.

===Write Your Own Code===

When writing your code from scratch, you start it as you would any C# code on Linux, such as within a text editor like Emacs, Vi, Gedit, or Kate. In your .cs source code file, you must include a reference to the Phidget Library:

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

Then, you would compile your completed C# code the same way as the examples above.

Mono also has a few different IDEs which you can use to develop code, and these are especially useful if you are doing GUI development. We provide instructions for MonoDevelop - one such IDE - being used [[#MonoDevelop|under Windows]].

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching section]] to help you follow the provided C# examples and which has resources such as the API reference.

==Windows CE==

===Description of Library Files===
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 Phidget 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|Phidget21.NET.dll}}</b> is the Phidget 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|Phidget21.NET1.1.dll}}</b> is the Phidget library for .NET framework <i><b>1.1</b></i>. 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.
You can optionally install the following files:
* <b>{{Code|Phidget21.NET.XML}}</b> provides the IntelliSense in-line documentation for the .NET library in Visual Studio/MonoDevelop. This documentation is also visible in the Object Browser in Visual Studio. By default, it is placed into {{Code|C:\Program Files\Phidgets}}.
* <b>{{Code|Policy.2.1.Phidget21.NET.dll}}</b> is the policy assembly for {{Code|Phidget21.NET.dll}}. Our installer places this file in the Global Assembly Cache(GAC) directory. It directs any programs compiled against version 2.1.0 or higher of {{Code|Phidget21.NET.dll}} to use the most recent installed version.

If you do not want to use our installer, you can download the five [{{SERVER}}/downloads/libraries/Phidget21-windevel.zip files].

Running the examples and writing your own code can be fairly compiler-specific, so we include instructions for each compiler below.

===Visual Studio 2005/2008/2010===

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.

=====Use Our Examples=====

Please start by downloading the [{{SERVER}}/downloads/examples/CSharp.zip examples] and unpack them into a folder. 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 → Open → Project, and open {{Code|AllExamples/AllExamples.sln}} or {{Code|AllExamples/AllExamples_vs2008.sln}} for Visual Studio 2005 and 2008, respectively.

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.
[[File:VS2005 Conversion Wizard.PNG|link=|alt=Conversion Wizard]]

The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

Start by setting the {{Code|HelloWorld}} project as your start up project.

The only thing left to do is to run the example! Click on Debug → 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.

[[File:CSharp VS2005 Run.PNG|link=|alt=Run]]

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 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}} Please ensure that you have set your start up project to be the one that matches your device before compiling.

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=====

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:

1. Generate a new Visual C# Windows Applications project with a descriptive name such as PhidgetTest.

[[File:CSharp VS2005 New Project.PNG|link=|alt=New Project]]

2. Add a reference to the Phidget .NET library.

[[File:CSharp VS2005 Add Reference.PNG|link=|alt=Add Reference]]

3. Under the .NET tab, select {{Code|Phidget21.NET.dll}}.
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]]

4. Then, in your code, you will need to include the Phidget .NET library:

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

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

The same [[#Follow the Examples|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 C# code will be our C# API information, with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|both of which are available in C#|[{{SERVER}}/documentation/Phidget21.NET.zip .NET API]}}

===Example Flow===

{{ExamplePseudocode|In C#, you can name these '''event''' functions whatever you like. You will add them to the Phidget .NET library in the Main Code section. This hooks them into the actual events when they occur. <br><br>
In the example code, the event functions common to all Phidgets are things like attach, detach, and error handling.<br>
Other 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.
|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.|
[{{SERVER}}/documentation/Phidget21.NET.zip .NET API]}}

===Code Snippets===

Specific calls in C# 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 C# 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.

====Step One: Initialize and Open====

The open() function opens the software object, but not hardware. So, it is not a guarantee you can use the Phidget immediately.

The different types of open can be used with parameters to try and get the first device it can find, open based on its serial number, or even open across the network. The API manual lists and [[General Phidget Programming]] discusses all of the available modes that open provides.

For example, if we were using a Temperature Sensor board as our device, the general calls would look like this:

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

namespace Program {
class Code {
static void Main(string[] args) {
try {

// Declare a TemperatureSensor object
TemperatureSensor device = new TemperatureSensor();

// Hook in any event handlers
// ...

// Open the device
device.open();

} catch (PhidgetException ex) { Console.WriteLine(ex.Description); }
}
}
}
</syntaxhighlight>
</div>

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

To use the Phidget, it must be plugged in (attached). We can handle this by using event driven programming and tracking the AttachEvents and DetachEvents, or we can handle this by calling waitForAttachment. This function works for any Phidget. WaitForAttachment will block indefinitely until a connection is made to the Phidget, or an optional timeout is exceeded:

<div class="source">
<syntaxhighlight lang=csharp>
device.open();
Console.WriteLine("Waiting for TemperatureSensor to be attached....");
device.waitForAttachment();
</syntaxhighlight>
</div>

One important thing to remember is that when working with Phidgets, a local connection will reserve the device until closed. This means only one program can access the Phidget locally. Many computers can access one Phidget over the [[Phidget WebService]].

====Step Three: Do Things with the Phidget====

We recommend the use of event driven programming when working with Phidgets. This allows the program to execute other tasks until the Phidget generates a new event. You can hook a custom function into an event trigger like this, using the Interface Kit Phidget as an example:

<div class="source">
<syntaxhighlight lang=csharp>
ifKit.SensorChange += new SensorChangeEventHandler(ifKit_SensorChange);
</syntaxhighlight>
</div>

The ifKit_SensorChange method is defined as follows:

<div class="source">
<syntaxhighlight lang=csharp>
void ifKit_SensorChange(object sender, SensorChangeEventArgs e) {
textBox1.Text = "Index " + e.Index + " Value: " + e.Value;
}
</syntaxhighlight>
</div>

Some values can be directly read and set on the Phidget. These functions can be used inside a polling loop as an alternative to event driven programming. The line inside the loop would be something like this, after which you could do something with the value:

<div class="source">
<syntaxhighlight lang=csharp>
int val = device.sensors[0].Value;
</syntaxhighlight>
</div>

====Step Four: Close and Delete====

At the end of your program, unhook any events and call Application.DoEvents(). This will make sure there are no outstanding events being processed before calling close.

<div class="source">
<syntaxhighlight lang=csharp>
private void Form1_FormClosing(object sender, FormClosingEventArgs e) {
ifKit.SensorChange -= new SensorChangeEventHandler(ifKit_SensorChange);
//run any events in the message queue
Application.DoEvents();
ifKit.close();
}
</syntaxhighlight>
</div>

{{MoreHowTos}}

The ''complete'' set of functions you have available for all Phidgets can be found in the [{{SERVER}}/documentation/Phidget21.NET.zip .NET 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 on its product page on our [{{SERVER}} main website].

==Common Problems and Solutions/Workarounds==

==={{ProblemSolution|All Operating Systems|The Phidgets.Events.ErrorEventHandler conflicts with System.IO.ErrorEventHandler.}}===

<div class="source">
<syntaxhighlight lang=csharp>
using System.IO;
using Phidgets;
using Phidgets.Events;
...
spatial.Error += new ErrorEventHandler(spatial_Error);

...
void spatial_Error(object sender, ErrorEventArgs e){
...
}
</syntaxhighlight>
</div>

The above code produces the following errors:

{{Code|'ErrorEventHandler' is an ambiguous reference between 'System.IO.ErrorEventHandler' and 'Phidgets.Events.ErrorEventHandler'}}.

and

{{Code|'ErrorEventArgs' is an ambiguous reference between 'System.IO.ErrorEventArgs' and 'Phidgets.Events.ErrorEventArgs'}}.

The error is due to the {{Code|System.IO}} and {{Code|Phidgets.Events}} namespaces both having a class called {{Code|ErrorEventHandler}}.

To get around this issue, use the fully qualified namespace when referring to the {{Code|ErrorEventHandler}} and {{Code|ErrorEventArgs}} classes:
<div class="source">
<syntaxhighlight lang=csharp>
using System.IO;
using Phidgets;
using Phidgets.Events;
...
spatial.Error += new Phidgets.Events.ErrorEventHandler(spatial_Error);
...

void spatial_Error(object sender, Phidgets.Events.ErrorEventArgs e){
...
}

</syntaxhighlight>
</div>

Language - C Sharp

2012-06-29T20:27:13Z

Cora: /* Quick Downloads */

[[Category:Language]]
{{OSLang|[[File:icon-CSharp.png|64x64px|link=|alt=]]|C# is a modern, object-oriented programming language developed by [http://www.microsoft.com Microsoft].}}
__TOC__

==Introduction==

{{LanguageSupport|C#|the complete Phidget API, including events|all Phidget devices.|the .NET or Mono framework. Both of the frameworks are supported on Windows. For Linux and OS X, only the Mono framework can be used. We provide instructions on how to set up your environment/compilers for [[#Visual Studio 2005/2008/2010 | Visual Studio 2005/2008/2010]], [[#Visual Studio 2003 | Visual Studio 2003]], [[#MonoDevelop | MonoDevelop]] and the [[#Mono | Mono command line compilers]]|}}

==Quick Downloads==
{{QuickDownloads|C#|
{{APIQuickDownloads|{{SERVER}}/documentation/Phidget21.NET.zip .NET}}
{{APIQuickDownloads|{{SERVER}}/documentation/web/NETDoc/Index.html|HTML Version of}}|
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/CSharp.zip|}}|
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/libraries/phidget21-x86.zip|.NET Framework Files|}}
{{WindowsQuickDownloads}}
{{MacQuickDownloads}}
{{LinuxQuickDownloads}}}}

==Getting started with C#==

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

Instructions are divided up by operating system. Choose:
*[[#Windows(2000/XP/Vista/7)|Windows 2000 / XP / Vista / 7]]
*[[#OS X |OS X]]
*[[#Linux | Linux]] (including PhidgetSBC)

==Windows (2000/XP/Vista/7)==

===Description of Library Files===
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 Phidget 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|Phidget21.NET.dll}}</b> is the Phidget 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|Phidget21.NET1.1.dll}}</b> is the Phidget 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.
You can optionally install the following files:
* <b>{{Code|Phidget21.NET.XML}}</b> provides the IntelliSense in-line documentation for the .NET library in Visual Studio/MonoDevelop. This documentation is also visible in the Object Browser in Visual Studio. By default, it is placed into {{Code|C:\Program Files\Phidgets}}.
* <b>{{Code|Policy.2.1.Phidget21.NET.dll}}</b> is the policy assembly for {{Code|Phidget21.NET.dll}}. Our installer places this file in the Global Assembly Cache(GAC) directory. It directs any programs compiled against version 2.1.0 or higher of {{Code|Phidget21.NET.dll}} to use the most recent installed version.

If you do not want to use our installer, you can download the five [{{SERVER}}/downloads/libraries/Phidget21-windevel.zip files].

Running the examples and writing your own code can be fairly compiler-specific, so we include instructions for each compiler below.

===Visual Studio 2005/2008/2010===

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.

=====Use Our Examples=====

Please start by downloading the [{{SERVER}}/downloads/examples/CSharp.zip examples] and unpacking them into a folder. 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 → Open → Project, and open {{Code|AllExamples/AllExamples.sln}} or {{Code|AllExamples/AllExamples_vs2008.sln}} for Visual Studio 2005 and 2008, respectively.

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.

[[File:VS2005 Conversion Wizard.PNG|link=|alt=Conversion Wizard]]

The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

Start by setting the {{Code|HelloWorld}} project as your start up project.

The only thing left to do is to run the example! Click on Debug → 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.

[[File:CSharp VS2005 Run.PNG|link=|alt=Run]]

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 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

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=====

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:

1. Generate a new Visual C# Windows Applications project with a descriptive name such as PhidgetTest.

[[File:CSharp VS2005 New Project.PNG|link=|alt=New Project]]

2. Add a reference to the Phidget .NET library.

[[File:CSharp VS2005 Add Reference.PNG|link=|alt=Add Reference]]

3. Under the .NET tab, select {{Code|Phidget21.NET.dll}}.
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]]

4. Then, in your code, you will need to include the Phidget .NET library:

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

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

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

===Visual Studio 2003===

=====Use Our Examples=====

1. Download the [{{SERVER}}/downloads/examples/CSharp.zip examples] and unpack them into a folder. Here, you can find the HelloWorld example which works with any Phidget. You can also find example programs for all the devices. {{FindYourDevice}}

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.

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.

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

3. Add a reference to the Phidget .NET library.

[[File:CSharp_VS2003 Add Reference 1.PNG|link=|alt=Add Reference]]

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.

[[File:CSharp_VS2003 Add Reference 2.PNG|link=|alt=Add Reference]]

5. To import the simple example program into your project, please: open up {{Code|Class1.cs}}.

6. Traverse to the example in Windows Explorer and locate the {{Code|Program.cs}} file.

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

7. Copy and paste the contents from that file into {{Code|Class1.cs}}.

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

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

9. Now, you can run the example. Click on Debug → 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=====

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 .NET library. Please see the [[#Use Our Examples 2 | Use Our Examples ]] section for instructions.

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

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

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

===Mono===

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.

=====Use Our Examples=====

Download the [{{SERVER}}/downloads/examples/CSharp.zip examples] and unpack them into a folder. Here, you can find the HelloWorld program that will work with any Phidget. You will also find example programs for all the devices. {{FindYourDevice}}.

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

Place the {{Code|Phidget21.NET.dll}} in the same directory as your source code.

To compile and build an executable, run:
<div class="source">
<syntaxhighlight lang=bash>
mcs /out:example.exe /r:phidget21.NET.dll example.cs
</syntaxhighlight>
</div>

If you have the {{Code|Phidget21.NET.dll}} installed in another location, please change the path to the file's location accordingly.

Afterwards, you will have an executable named {{Code|example.exe}} that you can run. Type the following to run the program:
<div class="source">
<syntaxhighlight lang=bash>
mono example.exe
</syntaxhighlight>
</div>

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=====

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 .NET library. Please see the [[#Use Our Examples 3 | Use Our Example ]] section for instructions.

In your code, you will need to include the Phidget .NET library:

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

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

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

===MonoDevelop===

=====Use Our Examples=====

Download the [{{SERVER}}/downloads/examples/CSharp.zip examples] and unpack them into a folder. Here, you can find example programs for all the devices, as well as a HelloWorld program that will work with any Phidget. {{FindYourDevice}}

These examples were written in Visual Studio 2005 and 2008, but are also compatible with MonoDevelop.

To load all projects in MonoDevelop, go to File → Open, and open {{Code|AllExamples/AllExamples.sln}}

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

[[File:CSharp MonoDevelop Win Start Up.PNG|link=|alt=Start Up Project]]

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.

[[File:CSharp MonoDevelop Win Run As.PNG|link=|alt=Run As]]

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=====

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 .NET library. To begin:

1. Create a new C# empty project with a descriptive name such as PhidgetTest.

[[File:CSharp MonoDevelop Win New Project.PNG|link=|alt=New Project]]

2. Add a reference to the Phidget .NET library.

[[File:CSharp MonoDevelop Win Reference.PNG|link=|alt=Add Reference]]

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.

[[File:CSharp MonoDevelop Win Reference 2.PNG|link=|alt=Add Reference]]

4. Then, in your code, you will need to include the Phidget .NET library:

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

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

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

==OS X==

The first thing you are going to need to do is install [http://www.mono-project.com/Main_Page Mono] (Note that Mono is only available for Intel Macs and not PowerPC). You will need both the SDK and the runtime.

Then, you will need the Phidget .NET libraries. These are part of the Windows library zip file download:

* [{{SERVER}}/downloads/libraries/Phidget21-windevel.zip Phidget Windows Library Zip File]

Extract the library zip file. Descriptions for the files are available on the [[OS - Windows]] page, but for now we only need the {{Code|Phidget21.NET.dll}} file to run the Phidget C# examples in Mono. So remember where you unzipped these Windows libraries - you will need to copy the {{Code|Phidget21.NET.dll}} file into your example directory shortly.

Next, you'll want to download and extract the Phidget C# Examples (For Windows, not for .NET Compact):

* [{{SERVER}}/downloads/examples/CSharp.zip C Sharp Examples for Windows]

One more thing needs to be done before you can compile and run the examples. You need to set up a special configuration file so that Mono knows where to find the phidget21.dll. Since Mac does not use dll's you need to redirect it to the appropriate file. Create a new file in the same directory as the example you wish to compile and name it <code>Phidget21.NET.dll.config</code>. Put the following into the file:

<div class="source">
<syntaxhighlight lang=xml>
<configuration>
<dllmap dll="phidget21.dll" target="/Library/Frameworks/Phidget21.framework/Versions/Current/Phidget21" />
</configuration>
</syntaxhighlight>
</div>

All that is left is to compile and run the code. When compiling, you need to link to the Phidget library. As the Phidget21.NET file is an "additional assembly" in C#/Mono, you can link to the assembly using the {{Code|-r}} "reference" switch:

<div class="source">
<syntaxhighlight lang=bash>
gmcs Program.cs -r:Phidget21.NET.dll
</syntaxhighlight>
</div>

This will compile a {{Code|*.exe}} file - in this case, {{Code|Program.exe}}. This you can then run under Mono:

<div class="source">
<syntaxhighlight lang=bash>
mono Program.exe
</syntaxhighlight>
</div>

If you will be compiling with an IDE such as GTK# or MonoDevelop, we don't have explicit instructions by IDE for OS X. However, you will probably find the [[#MonoDevelop | MonoDevelop]] section in the Windows portion above useful.

==Linux==

C# has support on Linux through the Mono framework.

===Use Our Examples===

The first step in using C# with Phidgets on Linux is to make sure that you have all of Mono installed. Although you probably have already done this if you're a C# programmer, you want to make sure you have all of the packages you'll need. Try:

<div class="source">
<syntaxhighlight lang=bash>
sudo apt-get mono-complete
</syntaxhighlight>
</div>

Next, you'll want to install the main 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.

Then, you will need the Phidget .NET libraries. These are part of the Windows library zip file download:

* [{{SERVER}}/downloads/libraries/Phidget21-windevel.zip Phidget Windows Library Zip File]

Extract the library zip file. Descriptions for the files are available on the [[OS - Windows]] page, but for now we only need the {{Code|Phidget21.NET.dll}} file to run the Phidget C# examples in Mono. So remember where you unzipped these Windows libraries - you will need to copy the {{Code|Phidget21.NET.dll}} file into your example directory shortly.

Next, you'll want to download and extract the Phidget C# Examples (For Windows, not for .NET Compact):

* [{{SERVER}}/downloads/examples/CSharp.zip C Sharp Examples for Windows]

To check that your Linux, Phidget, and Mono setup is all working together, you'll want to run the C# examples. Specifically, you'll want to run the ''simple'' C# examples. You can either use the HelloWorld program that will work with any Phidget, or you can find the source code for your device. {{FindYourDevice}}

Let's say you're running the Temperature Sensor example (for the 1048 or 1051). The source code for the example is in the directory:

:{{Code|TemperatureSensorExamples}} → {{Code|TemperatureSensor-simple}} → {{Code|TemperatureSensor-simple}} → {{Code|Program.cs}}

Other examples will be in directories named appropriately for their software object name. Once you have found the example you want to run, copy the {{Code|Phidget21.NET.dll}} file that you unzipped earlier into that example directory where the {{Code|Program.cs}} file is.

Then, compile the code. When compiling, you need to link to the Phidget library. As the Phidget21.NET file is an "additional assembly" in C#/Mono, you can link to the assembly using the {{Code|-r}} "reference" switch:

<div class="source">
<syntaxhighlight lang=bash>
gmcs Program.cs -r:Phidget21.NET.dll
</syntaxhighlight>
</div>

This will compile a {{Code|*.exe}} file - in this case, {{Code|Program.exe}}. This you can then run under Mono:

<div class="source">
<syntaxhighlight lang=bash>
sudo mono Program.exe
</syntaxhighlight>
</div>

Remember that the {{Code|sudo}} is needed unless you have your [[OS - Linux#Setting udev Rules|udev rules set on your Linux system]].

If you will be compiling with an IDE such as GTK# or MonoDevelop, we don't have explicit instructions by IDE for Linux. However, you will probably find the [[#MonoDevelop | MonoDevelop]] section in the Windows portion above useful.

===Write Your Own Code===

When writing your code from scratch, you start it as you would any C# code on Linux, such as within a text editor like Emacs, Vi, Gedit, or Kate. In your .cs source code file, you must include a reference to the Phidget Library:

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

Then, you would compile your completed C# code the same way as the examples above.

Mono also has a few different IDEs which you can use to develop code, and these are especially useful if you are doing GUI development. We provide instructions for MonoDevelop - one such IDE - being used [[#MonoDevelop|under Windows]].

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching section]] to help you follow the provided C# examples and which has resources such as the API reference.

==Windows CE==

===Description of Library Files===
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 Phidget 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|Phidget21.NET.dll}}</b> is the Phidget 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|Phidget21.NET1.1.dll}}</b> is the Phidget library for .NET framework <i><b>1.1</b></i>. 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.
You can optionally install the following files:
* <b>{{Code|Phidget21.NET.XML}}</b> provides the IntelliSense in-line documentation for the .NET library in Visual Studio/MonoDevelop. This documentation is also visible in the Object Browser in Visual Studio. By default, it is placed into {{Code|C:\Program Files\Phidgets}}.
* <b>{{Code|Policy.2.1.Phidget21.NET.dll}}</b> is the policy assembly for {{Code|Phidget21.NET.dll}}. Our installer places this file in the Global Assembly Cache(GAC) directory. It directs any programs compiled against version 2.1.0 or higher of {{Code|Phidget21.NET.dll}} to use the most recent installed version.

If you do not want to use our installer, you can download the five [{{SERVER}}/downloads/libraries/Phidget21-windevel.zip files].

Running the examples and writing your own code can be fairly compiler-specific, so we include instructions for each compiler below.

===Visual Studio 2005/2008/2010===

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.

=====Use Our Examples=====

Please start by downloading the [{{SERVER}}/downloads/examples/CSharp.zip examples] and unpack them into a folder. 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 → Open → Project, and open {{Code|AllExamples/AllExamples.sln}} or {{Code|AllExamples/AllExamples_vs2008.sln}} for Visual Studio 2005 and 2008, respectively.

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.
[[File:VS2005 Conversion Wizard.PNG|link=|alt=Conversion Wizard]]

The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

Start by setting the {{Code|HelloWorld}} project as your start up project.

The only thing left to do is to run the example! Click on Debug → 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.

[[File:CSharp VS2005 Run.PNG|link=|alt=Run]]

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 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}} Please ensure that you have set your start up project to be the one that matches your device before compiling.

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=====

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:

1. Generate a new Visual C# Windows Applications project with a descriptive name such as PhidgetTest.

[[File:CSharp VS2005 New Project.PNG|link=|alt=New Project]]

2. Add a reference to the Phidget .NET library.

[[File:CSharp VS2005 Add Reference.PNG|link=|alt=Add Reference]]

3. Under the .NET tab, select {{Code|Phidget21.NET.dll}}.
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]]

4. Then, in your code, you will need to include the Phidget .NET library:

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

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

The same [[#Follow the Examples|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 C# code will be our C# API information, with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|both of which are available in C#|[{{SERVER}}/documentation/Phidget21.NET.zip .NET API]}}

===Example Flow===

{{ExamplePseudocode|In C#, you can name these '''event''' functions whatever you like. You will add them to the Phidget .NET library in the Main Code section. This hooks them into the actual events when they occur. <br><br>
In the example code, the event functions common to all Phidgets are things like attach, detach, and error handling.<br>
Other 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.
|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.|
[{{SERVER}}/documentation/Phidget21.NET.zip .NET API]}}

===Code Snippets===

Specific calls in C# 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 C# 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.

====Step One: Initialize and Open====

The open() function opens the software object, but not hardware. So, it is not a guarantee you can use the Phidget immediately.

The different types of open can be used with parameters to try and get the first device it can find, open based on its serial number, or even open across the network. The API manual lists and [[General Phidget Programming]] discusses all of the available modes that open provides.

For example, if we were using a Temperature Sensor board as our device, the general calls would look like this:

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

namespace Program {
class Code {
static void Main(string[] args) {
try {

// Declare a TemperatureSensor object
TemperatureSensor device = new TemperatureSensor();

// Hook in any event handlers
// ...

// Open the device
device.open();

} catch (PhidgetException ex) { Console.WriteLine(ex.Description); }
}
}
}
</syntaxhighlight>
</div>

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

To use the Phidget, it must be plugged in (attached). We can handle this by using event driven programming and tracking the AttachEvents and DetachEvents, or we can handle this by calling waitForAttachment. This function works for any Phidget. WaitForAttachment will block indefinitely until a connection is made to the Phidget, or an optional timeout is exceeded:

<div class="source">
<syntaxhighlight lang=csharp>
device.open();
Console.WriteLine("Waiting for TemperatureSensor to be attached....");
device.waitForAttachment();
</syntaxhighlight>
</div>

One important thing to remember is that when working with Phidgets, a local connection will reserve the device until closed. This means only one program can access the Phidget locally. Many computers can access one Phidget over the [[Phidget WebService]].

====Step Three: Do Things with the Phidget====

We recommend the use of event driven programming when working with Phidgets. This allows the program to execute other tasks until the Phidget generates a new event. You can hook a custom function into an event trigger like this, using the Interface Kit Phidget as an example:

<div class="source">
<syntaxhighlight lang=csharp>
ifKit.SensorChange += new SensorChangeEventHandler(ifKit_SensorChange);
</syntaxhighlight>
</div>

The ifKit_SensorChange method is defined as follows:

<div class="source">
<syntaxhighlight lang=csharp>
void ifKit_SensorChange(object sender, SensorChangeEventArgs e) {
textBox1.Text = "Index " + e.Index + " Value: " + e.Value;
}
</syntaxhighlight>
</div>

Some values can be directly read and set on the Phidget. These functions can be used inside a polling loop as an alternative to event driven programming. The line inside the loop would be something like this, after which you could do something with the value:

<div class="source">
<syntaxhighlight lang=csharp>
int val = device.sensors[0].Value;
</syntaxhighlight>
</div>

====Step Four: Close and Delete====

At the end of your program, unhook any events and call Application.DoEvents(). This will make sure there are no outstanding events being processed before calling close.

<div class="source">
<syntaxhighlight lang=csharp>
private void Form1_FormClosing(object sender, FormClosingEventArgs e) {
ifKit.SensorChange -= new SensorChangeEventHandler(ifKit_SensorChange);
//run any events in the message queue
Application.DoEvents();
ifKit.close();
}
</syntaxhighlight>
</div>

{{MoreHowTos}}

The ''complete'' set of functions you have available for all Phidgets can be found in the [{{SERVER}}/documentation/Phidget21.NET.zip .NET 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 on its product page on our [{{SERVER}} main website].

==Common Problems and Solutions/Workarounds==

==={{ProblemSolution|All Operating Systems|The Phidgets.Events.ErrorEventHandler conflicts with System.IO.ErrorEventHandler.}}===

<div class="source">
<syntaxhighlight lang=csharp>
using System.IO;
using Phidgets;
using Phidgets.Events;
...
spatial.Error += new ErrorEventHandler(spatial_Error);

...
void spatial_Error(object sender, ErrorEventArgs e){
...
}
</syntaxhighlight>
</div>

The above code produces the following errors:

{{Code|'ErrorEventHandler' is an ambiguous reference between 'System.IO.ErrorEventHandler' and 'Phidgets.Events.ErrorEventHandler'}}.

and

{{Code|'ErrorEventArgs' is an ambiguous reference between 'System.IO.ErrorEventArgs' and 'Phidgets.Events.ErrorEventArgs'}}.

The error is due to the {{Code|System.IO}} and {{Code|Phidgets.Events}} namespaces both having a class called {{Code|ErrorEventHandler}}.

To get around this issue, use the fully qualified namespace when referring to the {{Code|ErrorEventHandler}} and {{Code|ErrorEventArgs}} classes:
<div class="source">
<syntaxhighlight lang=csharp>
using System.IO;
using Phidgets;
using Phidgets.Events;
...
spatial.Error += new Phidgets.Events.ErrorEventHandler(spatial_Error);
...

void spatial_Error(object sender, Phidgets.Events.ErrorEventArgs e){
...
}

</syntaxhighlight>
</div>

Electricity Primer

2012-06-29T20:23:31Z

Cora:

[[Category: Primer]]

==Introduction==

Design of reliable systems is really, really hard. The main challenge is the design of reliable building blocks - i.e. circuit and board layouts - from which to create your system. Phidgets does the majority of this work for you. And, once you have reliable building blocks, designing a reliable system from them is much easier.

However, you can still make an unreliable system out of Phidgets. In fact, if you are building a more complex system than the common examples we show through our documentation, and you have limited experience in complex electrical design, you will probably - and unintentionally - introduce design flaws that will make your system unreliable.

There are two reasons why you should read this primer:
# You want to build a complex system, more complex than we illustrate in our documentation. To succeed, you need to understand concepts.
# You understand how to make your system work, and you want to ensure it is well designed for maximum reliability and/or precision.

==The Basics==

To understand our discussion of potential problems and their solutions below, you'll need to be familiar with the basics. For this page, 'being familiar' means more than simply having heard of voltage, amperage, and power. You will need to have a working, conceptual model in your head, so that you can apply that model to your own system and examine it for problems. This section is all about giving the tools to build that mental model.

First, some terminology. We introduce it by analogy. If a circuit is a water system,
* The '''voltage''' is the ''pressure'' in the system
* The '''power supply''' is the ''pump'' creating the pressure
* The '''amperage''', also known as current, is the amount of ''flow''
* The '''load''' is the ''faucet'' - adjusting your load will adjust the flow
* The '''resistance''' is an attribute of the load - how tight or loose the faucet is
* The '''ground''' is the return path from load to pump.

The basic concepts for all of these terms are presented below.

===Load===

We start with the load, because the load is the purpose of your entire system.

In simple, USB-only Phidget systems, the load is the Phidget itself. The USB port is ready to provide power, but it does not (and cannot) until a load is applied (i.e. the Phidget is attached) and the circuit is completed.

Without a load that connects in a loop, it is like attaching a closed pipe to your pump. Initially, water will fill the pipe, and pressurize it, but once the pipe fills the system as a whole will do nothing more. To allow the pump to drive the load, and the flow to supply the load, we need to have a completed circuit, like this:

[[Image:elec_flow.png|150px]]

The load and the pump must '''match'''. If the load lets too much flow through, the pump will work too hard and burn itself out. This is what happens when you short circuit a power supply. The load is then simply a wire, which basically opens the flood gates and drains your power supply pump. The load must not let too much flow through, which it does by '''resistance'''. Likewise, the pump cannot push too hard on the load, or the load will break. This is discussed in-depth as part of [[#Voltage and Amperage|Voltage and Amperage]] below.

===Voltage and Amperage===

Within the flow concept [[#Load|above]], voltage is pressure. Specifically, it is the ''difference'' in pressure between the flow and the return. Voltage is measured in volts, and is denoted by '''V'''.

Amperage - also known as current - is the flow, or the amount of water that moves. At the pump, the amount of current out and the amount of current in are equal. The pressure might vary widely (highly pressurized pipes out, low pressure pipes back) but the ''amount'' of current is always the same. Amperage is measured in Amps, and is denoted by '''A'''.

To match a pump to a load, the voltage and amperage of the power (supply) and load (sink) must line up. We discuss picking a power supply - whether [[#Wall Power|wall mains]], or [[#Battery Power|batteries]] - in the [[#Power Needs|Power Needs section]] farther along in the document, but we need a few more concepts before we get there.

Power supplies - whether wall power or batteries - are usually rated based on voltage and amperage. Voltage is the specification to be the most careful with for circuits. Too much voltage is the same as overpressurizing your pipes - they will burst. In the case of electronics, you device will break.

This can be counterintuitive - in reference to safety (for humans) around electronics, you may have heard "It is not the voltage that will kill you, it is the amperage". Because of this, it may be tempting to think that too high of an amperage will harm your device, but this is not true. Our hearts are very susceptible to amperage but not voltage, hence amperage is considered dangerous for us whereas voltage is not. But a circuit is not like a human body - in a circuit trying to handle a power supply it is the voltage that matters most.

====Set Voltage (No Control)====

Most loads do no power regulation of their own. They simply take the voltage given to them and do useful things with it. You can tell that a pre-designed load (like a Phidget) falls into this category because it gives its voltage need ''as an exact value''. For example, most Phdigets use exactly 5 V of USB power. These loads will also tell you their amperage, which is a flow need that must be met or exceeded. A load will only use as much amperage as it needs.

====Controlled Power====

Some loads change the voltage or current they receive. This can be with the intent to either (a) keep a constant amount of power flowing from a draining power source like batteries, or (b) to modify a common power source (i.e. 12 V at 1 A) into an uncommon power source (i.e. 1 V at 12 A). This process is called '''regulation'''.

You can tell that a pre-designed load (like a Phidget) falls into this "power-regulated device" category because it gives its voltage need ''as a range''. For example, the [[SBC|Phidget Single Board Computer]] can take 6 V to 15 V.

To understand how this works, take the example of a flywheel. Flywheels are designed to be heavy and to take work in order to get them spinning at speed. But once you have them spinning, you can extract that work later at a more consistent rate:

[[Image:elec_flywheel.png]]

Flywheels can either make amperage or voltage be the more consistent blue line over time. The most common one in Phidgets is for stable amperage. Regulated amperage is also how LED lights can stay consistently bright for any length of time when using batteries. Stable voltage design is usually applied when the voltage is too low to begin with (such as any device that runs on a single AA battery), and the flywheel must amplify and stabilize it over time.

For those readers trying to envision how this works electrically, in practice the flywheel is an inductor (or, a transformer utilizing its inductor properties). For both voltage and amperage regulation, one way relief valves (diodes) must be added. And, in amperage regulation a reservoir (capacitor) must be added to offset the current drop by pulling ''more'' amperage as a battery drains. Then, a controller is needed to measure and then correspondingly enable and disable the flywheel system as the voltage or amperage drops from the supply.

But with those details in place, the inductor (and capacitor, in the case of amperage regulation) can effectively take the variety of voltages from, say, a draining battery, and still allow the board to run. Some devices even do this naturally. For example, motors often can take a variety of voltages because their construction (i.e. wire wrapping) naturally creates inductance.

These regulated systems often list the power they need directly, using a type of power rating called '''watts'''. Watts are voltage and amperage together (i.e. power):

<math>
\text{Amperage} =\frac{\text{Watts}}{\text{Voltage}}
</math>

Watts can be a handy way to describe flow and pressure together for these regulated devices. Rather than separating voltage and amperage like the unregulated devices do (i.e. this load needs exactly 12 V, or this load will draw exactly 2 A), the unit of watts will allow different value combinations of volts and amps as long as the wattage remains the same. For example, a 12 watt device with a voltage range of 5 to 12 volts can run on 6 V at 2 A, or 12 V at 1 A. Either will work. Amperage for all values in the device's range of 5 to 12 V can be found with the equation above. Because of this, watts are often preferred when trying to match a power supply to a regulated load.

===Ground===

All circuits have a '''ground'''. This is simply the return pipe to the pump. In a circuit, it is denoted by an upside-down triangle:

[[Image:ground.png]]

When drawing a circuit diagram, the symbol is placed on the wires that return to the pump:

[[Image:elec_flow_ground.png|170px]]

This electric ground provides a voltage reference throughout the circuit. Ground is always '''0''' volts as far as the circuit is concerned. (Remember, voltage is the ''difference'' between the flow and return pipes at the pump.) Ground is important because it provides a reference from which all the parts of the circuit can speak the same "voltage language" to each other, which matters a lot when a certain voltage means "1" and a certain voltage means "0".

There is only one '''absolute''' ground, and that is the Earth, which is taken to be 0 volts as an absolute value. Circuits not well-grounded to the Earth (of which there are many - your cell phone, car, etc) operate at a '''relative''' voltage. The upside-down triangle above denotes a ''relative'' ground.

With relative voltage, only the difference between local ground and the local high voltage matters. For example, a cell phone might operate as a 3 volt device, which means relative to its ground it always operates between 0 and 3 volts. But if that cell phone were compared carefully to Earth ground, its absolute voltage could be, say, between 10 and 13 volts. Until comparison, the device doesn't "feel" charged. This is the same as how you don't "feel" charged after skidding your feet in socks across a carpeted floor. But, when you "compare" yourself to Earth ground by touching some well-grounded metal, you receive a static electricity shock.

The same thing can happen when you combine two different power supplies, as we discuss [[#Projects With Different Power Sources|below]].

===Power===

There can be different types of pumps, and at this point we should supplant our heart symbol with some actual power supply pump symbols. For example, this is the symbol for a direct current (DC) battery:

[[Image:elec_battery_basic.png|200px]]

The + end is on the out flow, and the - end is on the return (ground). Batteries are usually listed with their voltages. This is because the resistance of the load will determine how much amperage is drawn, but too much voltage and you will harm your load.

This is the symbol for alternating current (AC) that you would get directly from the wall:

[[Image:elec_wall_basic.png|200px]]

Again, this is listed using voltage for the same reasons as DC. A relative ground symbol is still used on the return line here. AC devices can still operate on relative voltage if they do not use Earth ground (the third prong on a wall plug in North America). This is how some loads have AC cords with only two prongs - they operate on a relative voltage and relative ground. And relative AC voltage, having significantly more voltage (pressure) behind it, can really hit a device hard when two power supplies meet across it.

This connecting of multiple power supplies is quite a complex subject, and is described further in both [[#Power Needs|picking different power supplies]] and [[#One Powered Phidget|connecting different power supplies]] later on in this Primer.

===Emissions and Wires===

To talk about emissions, it is worth speaking more precisely about what a load is. The typical, simple Phidget setup is receiving 5 V direct current (DC) from the computer over the USB port. Let's model this as coming from a battery so that we can examine all parts of the system. From the point of view of the battery, the Phidget load is not just the green board with the circuitry on it. The load ''also'' includes the power cable (i.e. two wires in the USB cable), and anything else on the path out or back from the circuitry to the battery itself:

[[Image:elec_phidget_basic.png|200px]]

This is important because the wires play a role in the voltage that eventually makes it to the Phidget. This is true all the time, even when the Phidget is attached to a computer instead of a battery. All wires have some resistance, and so they are, in a way, in and of themselves circuits. Therefore, because of their resistance, the wires 'use' some of the 5 V heading out to the Phidget circuit board. This is discussed more below, but essentially longer cables have more resistance and at some point the voltage will drop so much over the length that the Phidget will not turn on.

To conceptually separate the wires from the Phidget in terms of the load, we can now start drawing the wires themselves in our circuit diagram, instead of the curved concept arrows indicating flow and return:

[[Image:elec_phidget_wires.png|200px]]

When talking about the 5V relative ground in this system, we are in fact talking about the ground ''right at the battery'' so we move the ground symbol to the battery itself.

Then, the resistance on these wires creates a possible problem - the emission of electromagnetic radiation as the wires naturally drop the voltage:

[[Image:elec_phidget_emissions.png|200px]]

These emissions are at a set frequency determined by the length of the wire:
* Long wires create low frequencies (harmful interference)
* Short wires create high frequencies (less harmful interference)

This can be minimized by having the flow and return wires be the same length and sit right next to each other. This way, the emissions somewhat cancel each other out from the flow and return going in opposite directions. This is partially how USB cables minimize emissions.

So, the way you design your connections (i.e. the resistance and placement of your wire) will have a direct affect on:
# The voltage that reaches the Phidget
# The emissions that your system produces

With all this talk of emissions, you might be tempted to try to shield parts or all of your system from emissions that either your system or external systems create.

Keep in mind that shielding is actually really hard to do correctly. Especially when grounding your shielding, with ad-hoc design you have a high chance of having an interfering signal (that has traveled out to the shield and traveled back via ground) creating a larger problem than not having a shield at all. Rather than shielding, it is easier to simply keep your cables short and with as low a resistance as possible throughout your system to minimize your emissions in the first place.

Identification of and solutions to these (and other more complex) problems are discussed in detail in the [[#Selecting Cables|section on choosing cables]] and the [[#Hooking Up The Pieces|section on connecting the pieces]] below.

===Multiple Loads===

The easiest way to hook up multiple Phidgets is in parallel, where the voltage stays the same but they share the amperage. Here the DC supply is two USB ports, each at 5 V and 0.5 A:

[[Image:elec_phidget_parallel.png|250px]]

However, the length of your wires comes into play again, because the voltage that actually reaches the Phidgets above is somewhat less than 5 V. So if your wires are long, or mismatched, the voltage may not match and will give you strange results. The voltage is both affected on the way out, and on the way back. Assuming the wires are the same length:

[[Image:elec_phidget_wire_drop.png|350px]]

In this way, you can create difficult-to-debug problems within a complex system, where one Phidget works but others mysteriously fail.

==Power Needs==

Now that you've understood the basics, it is time to actually talk about decisions and design. This section will help you choose a power supply for your Phidget. Let's say you want to run the [[SBC|Single Board Computer]] off of a battery. Or you want to run a motor controller with a power supply you bought from the hobby store. What do you need to buy? Will one you already have work? It is worth it to spend a moment with pencil and paper to work through this section and identify your power needs.

As described [[#Voltage and Amperage|earlier]], voltage is pressure. Too much pressure behind your faucet, and the water mains or faucet will break. Likewise, if you have too much voltage from a power supply, your circuit will break. You should choose a supply with voltage that ''matches the range the Phidget can accept''. The voltage cannot be over the maximum (otherwise, like pressure in a pipe, the pipe will burst), and the voltage cannot be under the minimum (otherwise, like pressure in a pipe, no flow will occur). Also, generally, a device (like a motor controller) will perform better at its maximum rated voltage if a range is available.

But the faucet doesn't care whether there is a big reservoir or small reservoir feeding the system, as long as the pressure is managed. Likewise, you can choose a power supply with more amperage than you need (a big reservoir to draw from) as long as the voltage matches. In the same way that a faucet restricts water by design, loads draw and allow only the amperage that they need. However, the amperage cannot be less than the Phidget needs. In that case, you will either overextend (and break) your power supply, or the circuit simply will not turn on at all.

The specification [[#Device List|for your specific device]] will list its power needs. For most devices, the external power supply needs will simply be listed in voltage and amperage. USB power is 5V at up to 500 mA (0.5 Amps). Most Phidgets will draw less than this - if you need precision, you can check the specification for your particular Phidget. And, if it is an Interface Kit, you can add the draw of each analog sensor and digital in/out from their specifications.

However, some Phidgets (e.g. motors, and the [[SBC|Single Board Computer]]) do not have a straight amperage and voltage specification. Instead, their power draw will be listed in watts, for which you [[#Voltage and Amperage|saw a relation earlier]] to convert to the values you need.

===Wall Power===

Wall power sources usually take the alternating current (AC) from the wall and convert it into a direct current (DC). These power supplies often take your familiar two-or-three prong wall connector and put power out via a barrel plug-type connector. AC power (typically 110 or 240 volts, depending where you live in the world) goes in the typical wall plug, and DC power (typically 5 to 24 volts) comes out the barrel plug. Most power supplies of this type list the conversion explicitly, such as: 110-240 Volts to 12 Volts at 2 Amps. You'll want to match your Phidget's needs against the 12 Volts at 2 Amps.

*The voltage must match exactly
**If the Phidget takes a range of voltages, the supply must fall within the range
*The amperage can be equal to or greater than the Phidget needs

A wall power supply is essentially an inexhaustible supply of current, so you don't need to worry about it running out like you would with batteries.

===Battery Power===

If you intend to use a battery bank (even of only one battery) to power your Phidget, you probably want to know what type of battery to purchase.

====Battery Chemistries====
The first thing that sets batteries apart is the type of materials used in their construction. The following table shows several of the more common battery chemistries as well as the voltage per cell they produce and the specific energy of the chemistry.

{| border = 1
| align="center" style="background:#f0f0f0;"|'''Chemistry'''
| align="center" style="background:#f0f0f0;"|'''Nominal Cell Voltage'''
| align="center" style="background:#f0f0f0;"|'''Specific Energy (MJ/kg)'''
| align="center" style="background:#f0f0f0;"|'''Description'''
|-
| align = "center" colspan = 4|Primary Batteries
|-
| Alkaline||1.5||0.4||These are the most common form of battery. Many commercially available AA and AAA batteries are alkaline.
|-
| Lithium (LiMnO2)||3||0.83-1.01||These are used in high drain devices or devices with a long shelf life as they have a very low self discharge rate.
|-
| Silver-oxide||1.55||0.47||Only used in small button cells as these are quite expensive.
|-
| align = "center" colspan = 4|Secondary Batteries
|-
| NiCd||1.2||0.14||Older technology, suffers from [[Electricity Primer#Memory Effect|memory effect]]. Capable of very high discharge rates with no ill effects. Moderate self discharge rate.
|-
| Lead-acid||2.1||0.14||Not particularly good with high discharge rate. Moderate rate of self discharge.
|-
| NiMH||1.2||0.36||Very heavy. Good performance in high drain devices. Very high energy density naturally, at the cost of a high self discharge rate. Newer versions are able to get rid of some of the self discharge though they suffer ~25% lower energy densities as a result.
|-
| Lithium Ion||3.6||0.46||Expensive to produce but very high energy density. Very low self discharge rate. Safety hazard as short circuiting can yield explosive or fiery results.
|}

====Choosing a Battery====
Batteries are chosen first by their voltage (V). Match the voltage exactly to the voltage the Phidget needs. Over or under this value, you could harm the board or have it simply fail to turn on.

Next, choose a battery that has adequate amperage to feed your device for the time you need. The lifespan of the battery will usually be listed in Amp-Hours (or Ah). For example, a double wide 12 V lantern battery will have usually around 7-8 amp hours. This means if you drew one amp from it for seven to eight hours, the battery would be totally drained. Or you could draw two amps from it and drain it in 3.5-4 hours. This does not mean however, that you can draw 36A for 15 minutes. It is important to understand that there is a limit at which more power simply cannot be drawn from the battery. Effectively, high drain devices will decrease the rated Ah. The amount differs from battery to battery so to be sure it is recommended to check the data sheets for the battery you are using. If the battery did not come with a data sheet they can usually be found on the manufacturers website. The data sheets should have a graph that shows the relationship between current draw (usually in mA) and capacity (Ah or mAh). Another useful thing that can be gathered from the datasheets is the batteries response to temperature. Batteries tend to not work as well in cold environments, most manufacturers will provide graphs of how the batteries lifespans will shorten at different temperatures. This is often very significant, causing the battery to last a fraction of its normal lifespan at temperatures below -10°C.

Finding the amperage or voltage sometimes needs to be done indirectly by using a specification of watts. The relationship between amperage, voltage, and watts is given above in the [[#Voltage and Amperage|voltage and amperage section]].

For an example, let us say you want to use battery power to run the [[SBC|Phidget Single Board Computer]]. The specifications say that it uses 1.2 watts as a base value. The specifications also say that it can take 12 V DC power. If we choose to use a 12 V battery, at 1.2 watts it will use 0.1 amps according to the equation [[#Voltage and Amperage|shown earlier]]. Going by amp-hours alone, if our battery is a double-wide lantern type 12 V battery, with 7 amp hours, with 0.1 amp draw it will last 70 hours, or almost three days.

<math>
\text{Maximum Running Days} =\frac{\text{Battery Amp Hours}}{\text{Device Amps} * \text{24}}
</math>

However, to estimate ''average'' running time (rather than maximum running time possible), amp-hours cannot be used so directly. Over time, batteries decrease in voltage as their power is used up. Practically speaking, this means one of two things for your load. For loads that do not regulate voltage or current, the amperage will also decrease over time. The classic example is an LED light source that grows dimmer and dimmer as the batteries are used up.

You should usually only count on about 60% of the stated amp hour rating to apply before expecting to run into problems from escalated drain due to battery voltage drop. This is especially true for deep cycle rechargeable batteries left in an installation, where draining more than 60% could also harm the battery.

Then, for lead-acid batteries, a typical battery is tested from full to complete drain over 20 hours by the manufacturer to obtain the advertised amp-hour rating. Draining a battery at a faster rate than this will result in even more reduction in capacity, by 10% or even more. This due to [http://en.wikipedia.org/wiki/Peukert%27s_law Peukert's Law].

There are plenty of [http://www.google.ca/search?&q=battery+calculator battery calculators] around the Internet which take most or all of these additional factors into account when recommending an amp-hour rating. For longer-term installations, the solar power online community has some excellent resources.

====Setting up Multiple Batteries====
You can hook up multiple batteries in series to get more voltage at the same amperage. The amperage is additive. For example, you can hook up two single-wide 6 V lantern batteries in series to produce 12 V. Or two 12 V batteries in series to produce 24 volts. This system would still only have the amp hours of ''one'' of the lantern batteries, because you will be essentially using them both at once:

[[Image:elec_battery_series.png|250px]]

The upside down triangle (ground) is explained above in a [[#Ground|section of its own]].

Or, you can hook up multiple batteries in parallel to get more amperage at the same voltage. For example, you could hook up two 12 V deep cycle batteries in parallel to provide more amperage at 12 V, which is like having a deeper reservoir of power for your device to use:

[[Image:elec_battery_parallel.png|250px]]

====Heat====
*all batteries have some sort of internal resistance
*can be found on the battery's data sheet
*the more power you pull from the battery the more heat is going to build up as a consequence of the internal resistance.
*larger internal resistances will cause heat to build up faster.
*when charging a battery you are not just limited to the power in the battery. nothing stops you from dumping energy into the battery past the point where it is fully charged
**this is why charging batteries is a bit of a tricky business.
**many batteries come with custom chargers that have control systems to prevent this type of overcharging.

====Weight====
Finally, weight matters - a car battery is much heavier than a lantern battery. Batteries vary widely by weight per amperage. Lithium batteries are usually very light for their power, followed by alkaline, followed by lead acid. This may not seem important at first, but if you are building a mobile robot it is worth calculating in the work of carting around a battery. You may find that, for the length of time you want it to run, your battery requires some system redesign.

==Selecting Cables==

===USB Cables===

In general, use the shortest cables possible. There are many reasons for this [[#Emissions and Wires|described above]], but as a summary:

; Long cables reduce the voltage that reaches the Phidget.
: This happens in both directions. So, for every unit cable length added, the voltage decreases by twice the electrical resistance of that length of cable. With especially long cables the Phidget may drop below its 4.6 volt threshold and simply never turn on.

; Long cables increase the width of your circuit.
:All circuits act as emitting antennas for the resonance frequency of the circuit structure. The longer the wires in the circuit, the lower the frequency, and the higher chance that it will be emissions that will interfere with your data and system.

; Longer cables have more length exposed to external interfering emissions.

Also, use thick cables that are built to specification. Some USB cables with thinner wiring have higher electrical resistance. This can be equal to what a much longer wire would have, and thus create a similar voltage drop where the Phidget will not turn on.

====Options for longer cables====
The maximum length for a USB cable is 5m. This is laid out in the USB specifications. Often times however a system requires more reach. In this case there are a few options available to you. You can use what is known as an active extension cable or USB extender. These cables act like extension cables and add power to the line so that the signal can travel further. A second option is to use a Cat5 extender. These extenders are 2 USB dongles that connect on either end of your system. You join them up with Cat5 cable. This allows you to run over much longer distances than USB traditionally allows.

===Power Cables===

There are "DC Wire Table" references on the Internet which describe how to pick a wire appropriate for your voltage and amperage. When selecting AC wires, you will probably be using pre-made extension cords. Cords add interference resonance length to your circuit, just like USB cables do as [[#USB Cables|described above]]. A long extension cord can create huge electromagnetic interference for your circuit and other systems in the area when first plugged in.

Also as with the USB cables above, cut the cables to the shortest length possible. This is again both for voltage drop reasons and frequency emission reasons.

===Hubs===

Avoid hubs where possible. Unpowered hubs are good for reading data from memory keys, but not for powering many external devices. If you must use a hub, buy a powered one.

===Sensor and Motor Wiring===
All Phidgets sensor class devices (products whose part numbers start with 11 such as the 1129) use a 3 channel ribbon cable for power and data transmission. Similarly, all our motors and load cells use multichannel wire interfaces. As mentioned previously, USB spec limits cables to 5m, this is not the case for these wires. The biggest concerns are electromagnetic interference (EMI) and voltage drop. In general you should be able to run these wires over significant distances (30m or more) with the load cells in particular having very long range. If EMI starts causing issues you can always use ferrite beads on the cable near the sensor or motor and the controller to reduce noise.

===Cable Gauges for Terminal Blocks===

Many Phidgets products feature green terminal blocks that use screws to hold wires in place, making it easy to take apart and rebuild connections in your project. The size of the terminal block determines the gauge of wire you should use.

{|border=1
|+'''Terminal Block Size and Wire Gauge'''
! Terminal Block Width (mm/port)
! Recommended Wire Gauge (AWG)
|-
| 3.81
| 14 to 26
|-
| 5.0
| 12 to 26
|-
| 9.5
| 10 to 26
|-
|}

The gauge of cables and wires is measured in AWG, which is the American Wire Gauge standard. The following table lists the properties of wire gauges commonly used with Phidgets:

{|border=1
|+'''American Wire Gauge Sizes'''
! AWG Size
! Diameter (mm)
! Area (mm²)
|-
| 10
| 2.588
| 5.26
|-
| 11
| 2.305
| 4.17
|-
| 12
| 2.053
| 3.31
|-
| 13
| 1.828
| 2.62
|-
| 14
| 1.628
| 2.08
|-
| 15
| 1.450
| 1.65
|-
| 16
| 1.291
| 1.31
|-
| 17
| 1.150
| 1.04
|-
| 18
| 1.024
| 0.823
|-
| 19
| 0.912
| 0.653
|-
| 20
| 0.812
| 0.518
|-
| 21
| 0.723
| 0.410
|-
| 22
| 0.644
| 0.326
|-
| 23
| 0.573
| 0.258
|-
| 24
| 0.511
| 0.205
|-
| 25
| 0.455
| 0.162
|-
| 26
| 0.405
| 0.129
|-
|}

==Hooking Up The Pieces==

Here, things can be tricky. You might think: just plug everything in and go! But often it is not that simple. Many Phidgets require special care when hooking up. We encourage a process where you apply the concepts in this Primer, through analysis, to your system. So, we don't explicitly list the boards most commonly affected until the [[#Affected Products|end of this Primer]].

The ''categories'' of the boards which require special attention within a complex system are:

# Phidgets with more than one power source, and
# Phidgets needing precise measuring or control of an external power source

If you are already thinking about your boards in your head and trying to figure out whether they fit into one category or another, you're on the right track! The list of [[#Affected Products|commonly affected boards]] are only the common ones... with a sufficiently complex system, you could conceivably create problems with ''any'' boards.

Both types of projects require a full understanding of [[#The Basics|electrical basics]]. Using those concepts, below we first describe problems that arise when hooking up different power sources, and extend that into using the solution to give more precise measurement and control.

===Shared Grounds===

Shared grounds can occur in Phidgets that handle two different power sources. Recognizing the sharing of a ground is not always easy. We show what it is, how it can be possible, and why it creates problems by starting with the most basic Phidget system. The simplest setup for a Phidget is to use the [[#Ground|ground]] of the computer it gets data and power from over a USB port:

[[Image:ground_simple_case.png]]

In this case, there is only one relative ground, and it is the PC ground, which is ground #1 in the image. The PC ground determines what is considered 0 volts for all signals on the Phidget. When you add different power sources or sinks in the system, you are pulling the system relative to the PC ground.

=====One Powered Phidget=====

The next most complicated system is one Phidget that handles two power sources. Let us say you have a motor controller, which takes power from USB, and which also takes power from a second power source. Although the second power source is usually just a wall plug, the simpler case for thinking about ground is actually a battery. A battery creates a second ''relative'' ground. Through the Phidget, relative ground #1 (from the PC) and #2 (from the battery) actually become the same ground:

[[Image:ground_wall_power.png]]

This is the first reason why systems with powered Phidgets have to carefully manage ground. If ground #1 and ground #2 are different with respect to each other (see the static shock analogy in the [[#Ground|ground section]] above), then whatever circuitry along the red dashed arrow must deal with the initial static shock. In this case it would be the circuitry of the Phidget. In the case of a battery, after the initial equalizing shock the battery will be whatever relative voltage the PC ground needs it to be. Hence a battery relative ground can 'float'.

If ground #2 comes from the wall, on the other hand, the ground does not 'float' and instead is always absolute 0 volts Earth ground. With the PC giving the power, this is not a problem in practice because the PC can also float (as with a laptop), or it uses Earth ground. But if you were using a different and more powerful USB power supply instead of a PC, and then connected it to the absolute Earth ground through the Phidget, the Phidget would bear the brunt of any ground equalization that would occur. If neither the new ground nor the old ground float, and the power supplies were powerful enough, this would eventually destroy the Phidget. In this case, you would want to use isolation, as described in [[#How To Fix This|How To Fix This]] below.

=====Multiple Powered Phidgets=====

A worse case comes in when you are using two powered Phidgets and one external power source. Again, say you are using a battery as the external power source. It would be tempting to simply wire both grounds from the Phidgets to the ground on the battery:

[[Image:ground_two_phidget.png]]

Although this looks benign, you have actually created a new circuit. The circuit is a second path, via ground, for the current to return to the voltage source. This is also known as a '''ground loop'''. The path we intuitively think of the current returning by is '''<span style="color:blue;">path A</span>''', but the sharing of grounds has created a new path through the motherboard, '''<span style="color:red;">path B</span>''':

[[Image:ground_two_paths.png]]

All current gets 'pumped' in a loop by voltage, and so it will use all return paths available to it, assuming all paths are equally easy (electrically) to use. This extends the pipe analogy, where water will flow in every path that exists. So, if your battery (or other power source with ground #2) is quite powerful, you can actually harm your motherboard within your PC (or at least your USB bus ground), because '''<span style="color:red;">path B</span>''' runs through the motherboard circuitry on the way back to the voltage source.

This problem does ''not'' apply to using a different power source between a black power plug and for the green control terminal block on, say, a [[DC Motor and Controller Primer|DC motor controller]]. Although the grounds are connected, and they run across a part of a Phidget board, creating a ground loop does not actually run through any circuitry if only these types of boards are used. If you have a complex system with other types of boards and therefore circuitry between black plug power port and green terminal block connections, draw out your system carefully to identify the loops.

Ground loops can be fixed by one of the ways described in [[#How To Fix This|How to Fix This]] below.

=====Single Board Computer And Powered Hub=====

When combining one externally powered Phidget and the [[SBC|Single Board Computer]] or the [[Product - 1019 - PhidgetInterfaceKit 8/8/8 w/6 Port Hub]] on the same external power source, you still may inadvertently create a ground loop as described above in [[#Multiple Powered Phidgets|the multiple powered Phidgets section]]. If they share a true [[#Ground|Earth ground]], this is not a problem. But if the ground is from a battery, or uninterruptible power supply, etc. then you should carefully draw out your system circuit and examine it for ground loops.

====How To Fix This====

Once you are aware of shared grounds in your system, you have two options.

One, for ground loop problems in simple systems (two Phidgets), you could make the normal return path ('''<span style="color:blue;">path A</span>''') the most electrically desirable path. This is best for simple systems where you have a lot of control over all of the ground wires within your system. For the ground wires leading directly from the Phidget to the external power supply ('''<span style="color:blue;">path A</span>'''), lower the resistance in the wire as much as possible. You can do this by keeping the wires short, and using a thick (large gague) wire for the hookups.

Although this solution works, sometimes you do not have much choice on how long your ground return wires can be, because the location of your power supply and and Phidgets are set by your system design. If you cannot be totally sure that the direct ground path is the shortest and most electrically desirable path, it is best to use the second option: a '''USB Isolator''' such as the [[Product - 3060 - USB Isolator|Phidget 3060]]. This isolator is like any other USB isolator - it can be used on a Phidget system, as well as any system that needs ground isolation.

You need isolators for every USB cable in your system, less one. If you have two USB connections, you need one isolator; three USB connections, two isolators, and so on. The one USB connection can remain non-isolated because a single ground connection cannot form a loop. However, if you are concerned about connecting the grounds as described in the [[#One Powered Phidget|single connected Phidget section above]], use a USB isolator on every cable.

===Precise Voltage Control===

Precise voltage (or other system) control and measurement is related to the concept of [[#Shared Ground|shared ground above]]. But here, you want to keep grounds separate not only to prevent ground loops, but also to make your system more sensitive to what it will control or measure.

For example, we make Phidgets that can create power precisely, or that can take it in and measure it. One such product is the 1002, which outputs a precise analog voltage with which to control an analog system. Now that you know about [[#Ground|relative ground]], however, you would be right to expect that you do not want to combine the ground in the PC and the ground in the system.

Even if you don't care about system sensitivity, you can still create [[#Multiple Powered Phidgets|ground loops]] in a system with multiple of these types of Phidgets. In addition, if you are using the Phidget to control a large, powerful system, even a single Phidget can receive damage from connecting two powerful power sources meeting across it, also as [[#One Powered Phidget|described earlier]].

But above and beyond the powered Phidget problems, there is another reason to separate (isolate) the electrical grounds in your system. The reason is: to make your system control more precise. For example, with the 1002, if you are trying to control an external system with an Phidget output voltage, that output voltage should be relative to the ''system you are trying to control'', not relative to the PC. Rather than forcing the grounds - and therefore the relative voltages - to be equal to each other, you can provide more precise control by isolating the grounds and working with the relative voltage of the controlled system on its own terms.

<span style="color:red;">Schematic-type image of a ground isolated analog out on a 1002</span>

====How To Fix This====

The solution to all of these problems in precise voltage control systems is to use USB isolation, even for a single Phidget. The [[Product - 3060 - USB Isolator|Phidget 3060]] is one such isolator. It inserts along the USB connection between your PC and the Phidget, and it separates the Phidget (and controlled system) ground from the PC ground. This fixes ground loops, separates relative voltage mis-matches, and isolates the control system for better precision.

<span style="color:red;">Image of 1002 and Isolator connected, with lines superimposed on the image to show non-copper connection in isolator</span>

==Affected Products==

If you're not sure whether a certain concept applies to your Phidget within a complex system, the best way to figure this out is by doing some mental (or pencil and paper) simulation. Draw the inputs and outputs for the entire board, and label them with voltage, list their required amperage (or watts), and draw connections (such as ground connections) through any circuitry.

With a technique like this, it is easy to see that some products - such as the [[Product - 1049 - PhidgetSpatial 0/0/3|Phidget Spatial]] - are simply not complex at all. Although you could conceivably create problems (such as by using separate power supplies instead of using USB power and connecting the grounds incorrectly, or by using really long wires), this would be an exceptional case.

Other Phidgets can be more easily used incorrectly without realizing it. These are often devices that are simple in some systems and yet complex in others. Your primary defense against designing unreliable systems is to draw the system out and identifying any problems using the concepts in this primer. To help you, however, you can generally think of two classes of Phidgets which usually need careful handling when they are part of complex systems:
# Phidgets with more than one power source, (these can be subject to the [[#Shared Grounds|multiple power source problems]] described above)
# Phidgets needing precise measuring of an external power source (these can be subject to the [[#Shared Grounds|multiple power source problems]] ''and'' [[#Precise Voltage Control|precise voltage control]] problems)

Expanded into individual products, the Phidgets which are most often affected are.....

# These Phidgets use a second type of external power:
#* Motor controllers
#**[[DC Motor and Controller Primer|DC controllers]]
#**[[Stepper Motor and Controller Primer|Stepper controllers]]
#**[[Servo Motor and Controller Primer|Servo controllers]]
#* Pure relay boards
#**[[Solid State Relay Primer|Solid state relay boards]]
#**[[Mechanical Relay Primer|Mechanical relay boards]]
#* Interface kits with relays
#**[[Product - 1017 - PhidgetInterfaceKit 0/0/8]]
#**[[Product - 1014 - PhidgetInterfaceKit 0/0/4]]
#* Powered Digital Output Interface Kits
#** [[Product - 1012 - PhidgetInterfaceKit 0/16/16]]
#* Interface Kits with Powered Hubs
#** The [[SBC|Single Board Computer]]
#** [[Product - 1019 - PhidgetInterfaceKit 8/8/8 w/6 Port Hub]]
# And these Phidgets may have a need to be sensitive to external power:
#* [[Temperature Sensor Primer|Thermocouple]] control
#* Analog Output ([[Product - 1002 - PhidgetAnalog 4-Output]])
#* Frequency Counter ([[Product - 1054 - PhidgetFrequencyCounter]])

==Conclusions==

This page should have helped you to:
*Choose a power supply from either the [[#Wall Power|wall]] or a [[#Battery Power|battery]]
*Properly [[#Ground|ground]] and/or [[#How To Fix This|isolate]] that power supply from looping through other circuitry
*Also use [[#How To Fix This|isolation]] to make your control or measurement system more precise
*Keep your cables short and thick to reduce electromagnetic emissions and limit voltage drop
*Be more aware of system-wide power problems in general, and use drawing and analysis of systems to identify problems

==Glossary==
===Memory Effect===
Memory effect is an effect observed in NiCd batteries that causes them to hold less charge. It pertains to the specific situation in which NiCd batteries lose their maximum capacity if they are repeatedly recharged without being fully discharged. The battery appears to remember the smaller capacity. The term is often misused in cases where other batteries seem to hold less charge than originally, however this is most likely due to age and use. This phenomenon is unique NiCd batteries.

LED Guide

2012-06-29T20:22:55Z

Cora:

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[Image:RBG.jpg|500px]]
|}

<br clear="all" />
==Introduction==

Like normal diodes, Light Emitting Diodes (LEDs) are semiconductor devices designed to conduct current in one direction only. What makes LEDs unique is their internal material makeup: when atoms in an LED release energy due to the flow of forward current, it is released in the form of photons (light). Different construction materials and various phosphor coatings are used to produce numerous colors of light.

LEDs that Phidgets sells are all operable via the [[Digital Output Primer|digital outputs]] on any of our interface kits. However Phidgets also sells a specific [{{SERVER}}/products.php?product_id=1031 PhidgetLED-64 Advanced LED controller] since it is often desirable to control more LEDs than even the [{{SERVER}}/products.php?product_id=1012 1012 Phidget Interface Kit 0/16/16] can operate. It offers some unique features such as brightness control.

==How it works==
[[image:led.png|thumb|350px|Parts of an LED. The flat spot on the epoxy casing, is an anchor to prevent twisting from damaging the leads.]]

LEDs emit light from current flowing through them. As the current flows, the electronics experience a sudden drop in energy level (voltage). When that happens they release energy in the form of light. The amount of light produced is proportional to the current. Depending on the material used to make the LED, different colors can be created. Like a conventional diode, the current can only flow in one direction - from the anode to the cathode.

==Controlling LEDs==

===Forward Voltage===

The materials used within LEDs that cause them to emit different colors of light affect a property called its forward voltage. The forward voltage is the voltage at which current in the forward direction will flow through the device and allow the LED to convert electrical energy into light. If the voltage applied to the LED is below the forward voltage of the LED, very little current (or none) may flow, and therefore very little light will be emitted. Most standard LEDs with colors such as red, amber, orange, yellow, and green have forward voltages below 2.75 Volts, and can be used with a [[Digital Output Primer|digital output]] by simply soldering them to a connector-wire and inserting the wire into the output port. The forward voltage in the [{{SERVER}}/products.php?product_id=1031 1031 - PhidgetLED] will default to 2.75V, and the maximum current defaults to 20mA.

===Supply Voltage===
{|
|- valign="top"
|To be an effective LED controller your digital outputs must be capable of <br />adjusting the forward voltage supplied to the LEDs to 1.7, 2.75, 3.9 and 5 volts<br /> settings allowing you to properly drive blue, white, violet, ultra violet and purple LEDs.<br /> The supply voltage will affect all LEDs. If you set the supplied voltage too high,<br /> power will be wasted and the controller may shut down from thermal overload. If you<br /> set the supply voltage too low, your LEDs will not be driven at the requested<br /> current, and will be dim or non-functional.
|
{| border = 1
!colspan="2" style="background:#f0f0f0;"|Typical Forward Voltages
|-
| align="center" style="background:#f0f0f0;"|'''Color'''
| align="center" style="background:#f0f0f0;"|'''Forward Voltage'''
|-
| Infrared||< 1.9
|-
| Red||1.7 to 2.2
|-
| Orange||2.0 to 2.2
|-
| Yellow||2.1 to 2.4
|-
| Green||2 to 2.3
|-
| Blue||3.2 to 4.0
|-
| Ultraviolet||2.1 to 3.8
|-
| White||3.3 to 3.6
|}
|}

===Maximum Current and Brightness Control===

{|
|-valign="top"
|
Most LEDs fall within 20, 40, 60 or 80mA, and applies to all LEDs. The <br />Phidgets DiscreteLED API call can be used to provide more current <br />or control brightness and will adjust the current linearly between 0 <br />and the set maximum. This however does not imply a precise method <br />for controlling the visibility of emitted light, as this is affected by the <br />construction and quality of the LED as well as the eyes of the viewer. <br />Be cautious when changing the current property. Many small LEDs are <br />designed for a maximum 20mA, and can be destroyed if driven at higher <br />currents.
|
[[image:Ledcurrent.png|400px]]
|}

===Choosing Current and Voltage Settings===

Make sure to choose the minimum supply voltage setting to drive the LED that requires the most voltage during operation. Any extra voltage not required by the LED will be converted to heat by the 1031. For example, a Blue LED being driven at 20mA, 3.9V Supply, that requires 3.7 volts will cause (3.9V-3.7V + 0.4V) * 0.02A = 12 milliwatts of heat to be produced on the 1031. If this example instead uses a high power, 1.5V infrared LED at 80mA, this will create (3.9V-1.5V+0.4V)*0.08 Amps = 224 milliwatts of heat. See the Heat Dissipation and Thermal Protection section later on in this manual for more information about this issue.

==Multiplexed LEDs==
Multiplexing is a system wherein the entire display is not active at the same time. Instead, sub-units of the display are driven one at a time and the electronics combine with human persistence of vision (the phenomenon of the eye by which an afterimage is thought to persist for approximately one twenty-fifth of a second on the retina) to make the viewer believe the entire display is continuously active. Many controllers use this architecture to reduce power consumption. 7 segment display clocks are an example of this.

In an effort to reduce electrical noise in the system the PhidgetLED does not use multiplexing. All 64 anodes are connected to the same power supply and the cathode of each LED connection is attached to an individual constant current sink. Also, the LEDs are not controlled by PWM - they are driven at a constant current.

==Other uses for LED controllers==

LED controllers are typically just a set of special digital outputs. This means they aren't limited to just controlling LEDs. They can be used to control relays, solenoids and even very small motors. The PhidgetLED can also be used to drive opto-isolators and MOSFET SSRs. A diode integrated into the 1031 on each cathode will clamp inductive surges to the anode supply voltage.

==Power Requirements and Power Supply Selection==

The power supply that is included with the 1031 is rated at 12V and 2A (max). If your application requires more power, a larger power supply may be necessary. The on-board voltage regulator is able to supply up to 6A for each LED supply voltage setting, as long as the power supply is able to provide enough voltage and current to the regulator. Assume an efficiency of 80% for the on-board voltage regulator when determining if a different power supply is required.

==Heat Dissipation and Thermal Protection==

Projects that require a high supply voltage, or have a lot of heat being produced from over voltage settings, will have over-temperature problems. This can be mitigated somewhat by understanding how channels are grouped and how the heat is distributed around the controller. On the 1031 channels are split into four groups: (0-7,24-31), (8-23), (32-39, 56-63) and (40-55); each controlled by their own individual IC. Evenly distributing the LEDs that may produce a lot of heat across these groups will balance the load on the ICs and reduce the risk of thermal overload. When thermal overload occurs, the integrated circuit (IC) controlling the involved LEDs will disable the output of all the channels it controls. For example, if an over-temperature occurs due to channel 12, all of the channels 8 through 23 will be disabled by the IC until the temperature back within the operating range. Thermal protection is activated when the die of the IC reaches approximately 160 degrees Celsius. Once the over-temperature fault has been corrected (ie, the IC has cooled down), the output channels will be re-enabled with the same settings as before the thermal shutdown. An error message will be produced during an over-temperature.

==Products that fall under this category==

*[{{SERVER}}/products.php?product_id=1031 1031 - PhidgetLED-64 Advanced]

*[{{SERVER}}/products.php?product_id=3601 3601 - 10mm Red LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3602 3602 - 10mm Green LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3603 3603 - 10mm Blue LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3604 3604 - 10mm Yellow LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3605 3605 - 10mm White LED (Bag of 20)]

*[{{SERVER}}/products.php?product_id=3606 3606 - 5mm Four Chip Super Flux Red (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3607 3607 - 5mm Four Chip Super Flux Green (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3608 3608 - 5mm Four Chip Super Flux Blue (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3609 3609 - 5mm Four Chip Super Flux Yellow (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3610 3610 - 5mm Four Chip Super Flux White (Bag of 5)]

*[{{SERVER}}/products.php?product_id=3611 3611 - 5mm Diffused Red (Bag of 30)]
*[{{SERVER}}/products.php?product_id=3612 3612 - 5mm Diffused Yellow/Green (Bag of 30)]
*[{{SERVER}}/products.php?product_id=3613 - 5mm Diffused Blue (Bag of 30)]

*[{{SERVER}}/products.php?product_id=3614 3614 - Flexible LED Strip Green (5m)]
*[{{SERVER}}/products.php?product_id=3615 3615 - Flexible LED Strip Blue (5m)]
*[{{SERVER}}/products.php?product_id=3616 3616 - Flexible LED Strip White (5m)]

*[{{SERVER}}/products.php?product_id=3618 3618 - RGB LED Modules - String of 10]

OS - iOS

2012-06-29T20:06:19Z

Cora:

[[Category:OS]]
{{OSLang|[[File:Icon-iOS.png|64x64px|link=OS - iOS]]|iOS is the operating system used on iOS devices such as the iPad, iPhone, and iPod touch.}}
__TOC__

Phidgets are designed to run on devices with an iOS version of 3.0 or later. It is strongly recommended that your device have the latest iOS version available to the device installed. As iOS devices do not have USB ports, the Phidgets will have to be connected on a computer with USB ports, and the iOS device will be able to interact with the Phidget over the [[Phidget_WebService|WebService]]. If you are looking for a compact and an inexpensive way to host Phidgets over a network, take a look at our [{{SERVER}}/products.php?product_id=1072|Single Board Computer].

==Quick Downloads==

If this is your first Phidget, we highly recommend working through the ''Getting Started'' guide for your specific Phidget device, which may be found on its product page on [{{SERVER}} our main website].

If you are already a pro, and just want the iOS drivers:

*[{{SERVER}}/downloads/libraries/Phidget-iPhone.zip iOS Libraries]

==Getting Started with iOS==

===Installing===

iOS code is developed on an OS X machine, and so getting your Phidget to work locally on the OS X machine first will help you distinguish any issues from network ones later. The OS X machine will need the Phidget drivers installed, please see the [[OS - OS X | OS X]] page for more information.

You will also need to [{{SERVER}}/downloads/libraries/Phidget-iPhone.zip iOS drivers] to code your program against.
The "installation" of the Phidget iOS libraries is simply linking and distributing the libraries with your project. As the most common platform to do this is through Xcode, we provide brief instructions on how to easily follow along with our already-linked examples later.

To install the libraries, follow these steps on the development computer:

1. Download the Phidget [{{SERVER}}/downloads/libraries/Phidget-iPhone.zip drivers for iOS].

2. Unzip the file, and you will find three things:

# Libraries for the iOS device and iOS simulator.
# Example Xcode project for the PhidgetInterfaceKit and PhidgetManager.
# Skeleton Xcode project - contains the minimal project settings already filled in for Phidgets development.

Feel free to browse around within the folders to get a sense of what will be going on the iOS side. We describe how to link and use these library files later on the [[Language - iOS#Write Your Own Code | Write your own iOS code]] section of the iOS Cocoa Touch page. For now, having found them means you can copy and install them to any project directory you want.

First, though, it will be useful to check to make sure Phidgets work with your iOS system.

===Checking===

When you run a Phidgets iOS example, you transfer and link the libraries and code all at the same time. This should <i>just work</i> with our examples, but if problems arise this section gives more detail on pinpointing the source of the problem. We recommend starting with running the software examples right away - if the software works, you know the hardware works too.

====Software====

The easiest way to see whether your libraries are set up correctly within our examples or your own project is just to download them to the iOS device and run them. Detailed instructions for this (including choosing the right {{Code|HelloWorld}} project to run) are on the [[Language - iOS]] page. That page will be your next step - but if the examples do not run using the instructions, return here to debug your hardware.

====Hardware====

If you are having problems running the examples, you should check the hardware of the host computer.

When using the [[#WebService|WebService]] to control a Phidget, the problem may be with the USB connection on the remote computer. Make sure both the server-side of (a) the webservice and (b) the USB connection are working by using the instructions on the [[OS - OS X|OS X page]]

====Troubleshooting====

If the examples '''do not''' work but USB '''does''' work (i.e. your remote computer or iOS device can consistently see the device in the [[#Hardware|hardware]]), take a moment to check the basics:
* No other programs, drivers, or processes are using the Phidget on the host computer.
* You have copied and linked the Phidget iOS libraries (as described on the [[Language - iOS]] page)
* The Phidget libraries are the latest version (visit the [[#Quick Downloads| quick downloads section]] to download them)
* Ensure that the webservice drivers and the iOS libraries are both the latest version
* Ensure that you have the most up to date iOS version installed for your device.
* Check the [[#Common Problems and Solutions|common problems]] section below, some specific combinations can cause problems

If your problem doesn't seem to be fixed by these steps, make sure that the Phidget is seen '''consistently''' by USB in [[#Hardware|hardware]] (if it is erratic, try our [[General Troubleshooting|general troubleshooting guide]]). If you are still having problems after using the troubleshooting guide, please [[Contact Us|ask us]]!

==Programming Languages==

iOS programs are written in [[Language - iOS|Objective C]] using the Cocoa Touch framework. You can read on within this page to learn how to use iOS with the Webservice, or you can jump ahead right now to the [[Language - iOS|iOS]] page and start writing code!

==WebService==

The Phidget WebService allows you to remotely control a Phidget over a network.<br>This section helps you use the WebService on iOS, but we also have an overview of the [[Phidget WebService]] in general.

Currently, iOS devices cannot ''host'' the WebService, but they can use data streaming from another computer over the WebService.

===Setting Up the WebService===

Using an iOS device, your network-controlled Phidget system will probably look something like this:

[[Image:webservice_general_pctoios.png|600px|link=|alt=]]

To begin,

1. Start the WebService on the host computer
* How to do this [[OS - Windows#WebService|on Windows]]
* How to do this [[OS - OS X#WebService|on Mac OS]]
* How to do this [[OS - Linux#WebService|on Linux]]
* How to do this [[OS - Phidget SBC#WebService|on the Phidget Single Board Computer]]

2. Download and unzip the [{{SERVER}}/downloads/libraries/Phidget-iPhone.zip iOS Examples] anywhere on the development computer.

3. Open up the {{Code|HelloWorld.xcodeproj}} into Xcode. Select either an iOS device or iOS simulator as the destination. For more information, please see the [[Language - iOS#Use OurExamples|Use Our Examples]] section of the iOS language page.

4. In Xcode, hit the {{Code|Run}} button to transfer the application to the device or simulator as well as run it.

===Using the WebService===

After performing the steps above, you will be using the WebService already. Plugging in the Phidget to the host computer will give you a screen like this:

[[File:iOS Webservice Example HelloWorld Output.png|link=|alt=HelloWorld Output]]

The above screenshot shows that a number of Phidgets are attached to the USB ports of computer connected to the network. Go ahead and detach the Phidgets from the USB port of the host computer, and see what happens.

===Debugging the WebService===

Since an iOS device can only be a user and not a host of the WebService, you should use debugging server side. Refer to the webservice sections for each operating system:
* [[OS - Windows#WebService|Windows]]
* [[OS - OS X#WebService|Mac OS]]
* [[OS - Linux#WebService|Linux]]
* [[OS - Phidget SBC#WebService|Phidget Single Board Computer]]
In addition, if you are having WebService problems, you will probably find the webservice section of our [[General Troubleshooting#WebService Troubleshooting|General Troubleshooting Guide]] helpful as well.

==Advanced Uses==

===Description of Installer files===

Here is the list of files and their description for each file that is distributed through the iOS drivers.
* <b>{{Code|iphoneos/libPhidget21.a}}</b> contains the actual Phidget library, which is used at run-time. This library is used when you are testing the example on the actual iOS device.
* <b>{{Code|iphonesimulator/libPhidget21.a}}</b> contains the actual Phidget library, which is used at run-time. This library is used when you are testing the example an iOS simulator.
* <b>{{Code|phidget21.h}}</b> lists all the Phidget API function calls available to your code. Your compiler also has to know where this file is.
* <b>{{Code|SkeletonProject}}</b> is a Xcode project containing the bare minimum project settings already filled in to code with the Phidget library.

==Common Problems and Solutions==

None at this time.

OS - Android

2012-06-29T20:05:57Z

Cora:

[[Category:OS]]
{{OSLang|[[File:Icon-Android.png‎|64x64px|link=]]|Android is a mobile OS commonly used on smartphones and tablet computers.}}
__TOC__

Tablets with a USB port and Android version 3.1 or greater can control Phidgets directly plugged in to them. Earlier Android versions (tested down to 2.1) can control Phidgets over a network using the [[#WebService|WebService]]. We do not currently support Android devices acting as a [[Phidget WebService]] server, but if you are looking for a compact and cheaper-than-a-tablet way to host Phidgets over a network, take a look at our [{{SERVER}}/products.php?product_id=1072 Single Board Computer].

==Quick Downloads==

Already a pro, and just need the downloads? Here they are.

Android does not need special drivers installed, though for developing code you will need the Android Java libraries when you start writing code:
* [{{SERVER}}/downloads/examples/android-examples.tar.gz Phidget Android examples and libraries]
* [[Language - Android Java#Quick Downloads|Android Java page]]

Note that you will also need the libraries for the operating system your Phidget is directly connected to, if you don't have an Android 3.1+ tablet with USB:

'''Windows:'''
{{WindowsQuickDownloads}}
* Or refer to the main [[OS - Windows|Windows page]]

'''OS X:'''
{{MacQuickDownloads}}
* Or refer to the main [[OS - OS X|OS X page]]

'''Linux and the SBC:'''
{{LinuxQuickDownloads}}
* Or refer to the main [[OS - Linux|Linux page]]
* Direct connections work automatically with our [{{SERVER}}/products.php?product_id=1072 SBC], you can refer to its [[1072 - Getting Started|Getting Started]] page

==Getting Started with Android==

If this is your first Phidget, we highly recommend working through the Getting Started guide for your specific Phidget device, which may be found on its product page on [{{SERVER}} our main website].

Android code is developed on an external platform anyway (i.e. Windows, Mac OS, or Linux), and so getting your Phidget to work locally on that platform first will help you distinguish any issues from network ones later.

Near the end of the Windows, Mac OS, or Linux setup process, we direct you to choose a language. At that point, please remember to return here to this Android Java page.

Alternately, you can first try using [[Language - Java|mainstream Java]] to control the Phidget on your host computer and become familiar with it. On the mainstream Java page, we provide example code - including code that works on the Android development platform of Eclipse - to test your Phidget directly from your development computer.

For directly controlling a Phidget with your Android device (i.e. plugging a Phidget directly in to your tablet), you will need a USB host controller on your tablet. Some tablets have these; some do not. Just having a port that the USB cable can fit into does ''not'' necessarily indicate that the port can host a USB device. Alternatively, some tablets (like the Samsung Galaxy Tab, for example) have the large 30-pin connectors that ''can'' be changed into a USB host using Samsung's adaptor.

The best way is to locate within the specifications for your device whether the ports on your device can serve as a ''USB host''. Another way to know is that you can host other devices (such as using a USB memory key) on your tablet.

===Installing===

The 'installation' of the Phidget Android libraries is simply linking and distributing the libraries with your code. As the most common platform to do this (on Windows, Mac, and Linux) is through Eclipse, we provide brief instructions on how to get and install Eclipse so you can more easily follow along with our already-linked examples later.

====Eclipse (Android Java Development Platform)====

Development for your Android OS Phidget application can occur on Linux, Mac OSX, or Windows.

To install Eclipse, you will need the following:

# The JDK and Java on your development system
#*See the [[Language - Java|mainstream Java]] page for details on Java for Windows, Mac, and Linux
# Eclipse (a Java Integrated Development Environment) on your development system
#*[http://www.eclipse.org/downloads/ http://www.eclipse.org/downloads/] (for Windows or MacOS)
#*<code>sudo apt-get install eclipse</code> (for Linux)
#*For 64-bit Linux, you will need the <code>ia32-libs</code> package (the bridge to 32-bit software) as well for Android development, try:
#*:{{Code|sudo apt-get install ia32-libs}}

====Android SDK (and ADT Eclipse Plugin)====

After installing Java and Eclipse, you can install the Android Software Developer's Toolkit (SDK) and the Android plugin for Eclipse (ADT).

# Download and install the Android SDK package for your development system:
#*See the download instructions link at [http://developer.android.com/sdk/ http://developer.android.com/sdk/]
#*Google's instructions for installing are here: [http://developer.android.com/sdk/installing.html http://developer.android.com/sdk/installing.html]
# Download and install the ADT Eclipse Plugin for Android
#*Follow the instructions at [http://developer.android.com/sdk/eclipse-adt.html http://developer.android.com/sdk/eclipse-adt.html]

To check that the JDK, the Android SDK, and Eclipse have all been configured correctly, use the Google HelloAndroid example:

[http://developer.android.com/resources/tutorials/hello-world.html http://developer.android.com/resources/tutorials/hello-world.html]

Once you have confirmed that the Android SDK has been correctly installed, you are ready to begin developing applications with Phidgets.

=====Android SDK and ADT on Linux=====

After downloading and unpacking the Android SDK package (the link is [[#Android SDK (and ADT Eclipse Plugin)|just above]]), run the Android SDK manager. If {{Code|android-sdk-linux}} is the unpacked directory that was downloaded, try:
:{{Code|android-sdk-linux/tools/android}}

This will give you the option to download the Android versions you want to support. Running the SDK from within Eclipse ({{Code|Window}} → {{Code|Android SDK}}) will let you add those Android versions to Eclipse, for emulating them before downloading to an Android device and using with Phidgets.

Then, to add Android support to your compilation process in Eclipse, make sure {{Code|adb}} is in your path (e.g. by adding it to {{Code|/etc/environment}}).

====Phidget Libraries====

The libraries from the [{{SERVER}}/downloads/examples/android-examples.tar.gz Phidget Android examples] (not our mainstream Java examples, despite the same name) are the libraries for including with your Android code.

When you download and unzip the examples, each project (in addition to the source files, resources, and so on) contain three things:

# A libs/ folder
# A jar file containing the general Phidget java library (phidget21.jar)
# A jar file for directly driving USB devices from a USB port on the Android device (PhidgetsUSB.jar)

Feel free to browse around within these jar files to get a sense of what will be going on the Android OS side. We describe how to link and use these library files later on the [[Language - Android Java#Write Your Own Code | Write your own Android code]] section of the Android Java page. For now, having found them means you can copy and 'install' them to any project directory you want.

First, though, it will be useful to check to make sure Phidgets work with your Android system.

===Checking===

When you run a Phidgets Android example, you transfer and link the libraries and code all at the same time. This should 'just work' with our examples, but if problems arise this section gives more detail on pinpointing the source of the problem. We recommend starting with running the software examples right away - if the software works, you know the hardware works too.

====Software====

The easiest way to see whether your libraries are set up correctly within our examples or your own project is just to download them to the Android device and run them. Detailed instructions for this (including choosing the right {{Code|HelloWorld}} project to run) are on the [[Language - Android Java]] page. That page will be your next step - but if the examples do not run using the instructions, return here to debug your hardware.

====Hardware====

If you are having problems running the examples, you should check the [[#Remote Phidget|hardware of the host computer]] if your Android device is controlling the Phidget over the WebService. Or, you should check the hardware of your [[#Directly Connected Phidget|Android device]] if the Phidget is directly connected to the tablet's USB port.

=====Remote Phidget=====

When using the [[#WebService|WebService]] to control a Phidget, the problem may be with the USB connection on the remote computer. Make sure both the server-side of (a) the webservice and (b) the USB connection are working by using the instructions on the [[Software Overview#Operating System Support|page specific to the operating system]]

=====Directly Connected Phidget=====

To check whether a Phidget is correctly connecting in your Android hardware (even if our examples do not work), you can use the kernel logs on your Android tablet in a similar way as you would on [[OS - Linux|Linux]].

You need to access the logs from your debugging computer - e.g. the computer where you have installed Google's development plugins as described above. Plug a USB Phidget into your Android device. Then, as soon as possible, from a command line on that computer, use the ADB (Android Debugging Bridge) program to access the program {{Code|dmesg}} on your Android device:

<div class="source">
<syntaxhighlight lang=bash>
adb shell dmesg
</syntaxhighlight>
</div>

This will print out the entirety of the kernel logs on your Android device. Even if you have been running your device for only a little while, this could be thousands of lines of output. If you plugged the Phidget in and then ran {{Code|dmesg}} right away, the kernel detection of the Phidget should be almost at the bottom of the logs. If you are on Linux or Mac OS, you can mitigate the length of this output using {{Code|tail -n 50}} or so. If you are on Windows, you may consider using a command redirection operator like {{Code|>}} to write to a file and then view the last 50 or so lines.

Near the end of the output you will find something like this for a successful registration of a Phidget in the Android kernel:

<div class="source">
<syntaxhighlight lang=text>
<6>[ 3282.554249] usb 1-1.2: new full speed USB device using tegra-ehci and address 5
<6>[ 3282.612359] usb 1-1.2: New USB device found, idVendor=06c2, idProduct=0032
<6>[ 3282.612418] usb 1-1.2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
<6>[ 3282.612466] usb 1-1.2: Product: PhidgetTemperatureSensor
<6>[ 3282.612504] usb 1-1.2: Manufacturer: Phidgets Inc.
<6>[ 3282.612540] usb 1-1.2: SerialNumber: 287638
<4>[ 3282.612576] device: '1-1.2': device_add
<4>[ 3282.615639] device: '1-1.2:1.0': device_add
<4>[ 3282.618632] device: '0003:06C2:0032.0003': device_add
<3>[ 3282.631412] generic-usb 0003:06C2:0032.0003: claimed by neither input, hiddev nor hidraw
</syntaxhighlight>
</div>

If the kernel log Phidget attachment does '''not''' appear, make sure that other devices that are supposed to work with your tablet (USB data keys, keyboards, etc. - the list depending entirely on which tablet) do indeed work. Not having the Phidget appear in your kernel logs indicates there is a problem with your USB hardware on your Android device.

Note that in order to consider a port on your tablet to be compatible with Phidgets it must be able to '''host''' USB devices. Simply finding and using a USB cable to connect the Phidget to the power charging port on your phone or tablet is not enough! A host USB port should either say so explicitly, or at least act like a 'normal' USB port such as ones you would find on your PC, and be able to use many common USB devices like memory sticks.

If the kernel log attachment does appear, but your code doesn't run, the problem is probably with your code. Work through the [[Language - Android Java]] page to make sure you have all the libraries, jar files, and permissions set and linked properly to use your Phidget.

====Troubleshooting====

If the examples '''do not''' work but USB '''does''' work (i.e. your remote computer or Android device can consistently see the device in the [[#Hardware|hardware]]), take a moment to check the basics:
* No other programs, drivers, or processes are using that USB port in software
* You have properly set either android.permission.INTERNET or android.hardware.usb.host in your AndroidManifest.xml file (as described on the [[Language - Android Java]] page)
* You have copied and linked the Phidget jar libraries and libs/ folder into your project (as described on the [[Language - Android Java]] page)
* The Phidget libraries are the latest version (visit the [[#Quick Downloads| quick downloads section]] to download them)
* If using the Phidget over the webservice, make sure the webservice drivers and the Android libraries are both the latest version
* If directly connecting to your Android device, the port you are using is a real USB host port (not a reduced-function power charging port)
* Check the [[#Common Problems and Solutions|common problems]] section below, some specific combinations can cause problems

If your problem doesn't seem to be fixed by these steps, make sure that the Phidget is seen '''consistently''' by USB in [[#Hardware|hardware]] (if it is erratic, try our [[General Troubleshooting|general troubleshooting guide]]). If you are still having problems after using the troubleshooting guide, please [[Contact Us|ask us]]!

==Programming Languages==

Android OS programs are written in [[Language - Android Java|Android Java]] using the Android SDK and the Phidgets library. You can read on within this page to learn how to use Android with the WebService, or you can jump ahead right now to the [[Language - Android Java|Android Java]] page and start writing code!

Note that Android Java is NOT the same as mainstream Java. Any Java programs you have will probably need significant modification before they run on Android, including our [[Language - Java|mainstream Java]] Phidget Examples.

==WebService==

The Phidget WebService allows you to remotely control a Phidget over a network.<br>This section helps you use the WebService on Android, but we also have an overview of the [[Phidget WebService]] in general.

Currently, Android devices cannot ''host'' the WebService, but they can use data streaming from another computer over the WebService.

===Setting Up the WebService===

Using an Android device, your network-controlled Phidget system will probably look something like this:

[[Image:Webservice general pctoandroid.png|600px|link=|alt=]]

1. Start the WebService on the host computer
* How to do this [[OS - Windows#WebService|on Windows]]
* How to do this [[OS - OS X#WebService|on Mac OS]]
* How to do this [[OS - Linux#WebService|On Linux]]
* How to do this [[OS - Phidget SBC#WebService|On the Phidget Single Board Computer]]

2. Download the [{{SERVER}}/downloads/examples/android-examples.tar.gz Android Examples].
* Edit the IP address and port in the {{Code|HelloWorldRemote}} example to match the IP address of the host computer (5001 is the default port)
* Transfer the example {{Code|HelloWorldRemote}} to your Android Device
* Run the example on your Android device, making sure it is also connected to the local network
** In Eclipse, right-click on project in Package Explorer (To open the Package Explorer, use Window → Show View → Package Explorer)
** Select Run As... → Android Application

3. Plug a Phidget into the host computer

===Using the WebService===

After performing the steps above, you will be using the WebService already. Plugging in the Phidget to the host computer will probably give you a screen like this:

[[Image:android_helloworld_remotehello.png|700px|alt=|link=]]

(The Phidget you actually plugged in will show up, be it a TemperatureSensor or something else)

And when you unplug that Phidget from the remote host computer, you should see something like this on your Android device:

[[Image:android_helloworld_remotegoodbye.png|700px|alt=|link=]]

===Debugging the WebService===

As currently an Android device can only be a user and not a host of the WebService, you should use debugging server side. Refer to the webservice sections for each operating system:
* [[OS - Windows#WebService|Windows]]
* [[OS - OS X#WebService|Mac OS]]
* [[OS - Linux#WebService|Linux]]
* [[OS - Phidget SBC#WebService|Phidget Single Board Computer]]
In addition, if you are having webservice problems, you will probably find the webservice section of our [[General Troubleshooting#WebService Troubleshooting|General Troubleshooting Guide]] helpful as well.

==Advanced Uses==

None yet, feel free to [[Contact Us|suggest some]]!

==Common Problems and Solutions==

None at this time.

Language - Java

2012-06-29T20:01:50Z

Cora: /* Quick Downloads */

[[Category:Language]]
{{OSLang|[[File:icon-Java.png|64x64px|link=|alt=Java]]|Java is a modern, object-oriented programming language maintained by Oracle.}}
__TOC__

==Introduction==

{{LanguageSupport|Java|the complete Phidget API, including events|all Phidget devices.|the {{Code|javac}} command line compiler as well as in integrated development environments(IDEs) such as [[#NetBeans | NetBeans]] and [[#Eclipse | Eclipse]]|}}

==Quick Downloads==

{{QuickDownloads|Java|
{{APIQuickDownloads|{{SERVER}}/documentation/JavaDoc.zip}}
{{ExtraAPIQuickDownloads|{{SERVER}}/documentation/web/javadoc/index.html|HTML Version of}}|
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/JavaJNI.zip|}}|
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/libraries/phidget21jar.zip|Java|(phidget21.jar)}}
{{WindowsQuickDownloads}}
{{MacQuickDownloads}}
{{LinuxQuickDownloads}}
}}

==Getting started with Java==

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

Instructions are divided up by operating system. Choose:
*[[#Windows(2000/XP/Vista/7)|Windows 2000 / XP / Vista / 7]]
*[[#OS X |OS X]]
*[[#Linux | Linux]] (including PhidgetSBC)

==Windows (2000/XP/Vista/7)==

===Description of Library Files===
Java programs on Windows depend on two files, which the installers in the [[#Libraries and Drivers | Quick Downloads]] section put onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. By default, it is placed in {{Code|C:\Windows\System32}}.
* <b>{{Code|phidget21.jar}}</b> is the Phidget Java library for JDK <i><b>1.4.2</b></i> or higher. Your compiler has to know where this file is. By default, it is placed into {{Code|C:\Program Files\Phidgets}}. So, you can either point your compiler to that location, or copy and link to it in a directory for your project workspace. For more information, please see the section for your specific compiler/environment.

If you do not want to use our installer, you can download the [{{SERVER}}/downloads/libraries/phidget21-x86.zip {{Code|phidget21.dll}}] as well as the [{{SERVER}}/downloads/libraries/phidget21jar.zip {{Code|phidget21.jar}}] and manually install them where you want; refer to our [[OS_-_Windows#Manual_File_Installation|Manual Installation Instructions]].

Running the examples and writing your own code can be fairly compiler-specific, so we include instructions for each compiler below.

You can program Phidgets with Java in command line with the {{Code|javac}} compiler as well as in IDEs such as NetBeans and Eclipse.

===Javac (Command Line)===

====Use Our Examples====

Download the [{{SERVER}}/downloads/examples/JavaJNI.zip example] and unpack them into a folder. Here, you can find an example program called HelloWorld which will work with any Phidget. You can also find example programs for all the devices. {{FindYourDevice}} Please only use the simple examples. The full examples are intended for the [[#NetBeans | NetBeans IDE]].

Ensure that the {{Code|phidget21.jar}} is in the same directory as the source code.

To compile in Windows command prompt:
<div class="source">
<syntaxhighlight lang=bash>
javac -classpath .;phidget21.jar example.java
</syntaxhighlight>
</div>

This will create Java bytecode in the form of {{Code|.class}} files. Type the following to run the program:
<div class="source">
<syntaxhighlight lang=bash>
java -classpath .;phidget21.jar example
</syntaxhighlight>
</div>

If you wish, you can compile the project as a {{Code|.jar}} so there are fewer files to maintain. The [http://www.oracle.com/java Java SDK] provides the {{Code|jar}} utility which packages all the {{Code|.class}} files into a single {{Code|.jar}} file.
To begin, you will have to provide a Manifest file to indicate the program entry point. With your favourite text editor, create a new file with the following content:
<div class="source">
<syntaxhighlight lang=text>
Manifest-Version: 1.0
Class-Path: phidget21.jar
Main-Class: example
</syntaxhighlight>
<br/>
</div>
Ensure that the file ends in a single new line or a carriage return character.
Save the file as {{Code|example.mf}} and place it in the same directory as the other {{Code|.class}} files.
Next, create the .{{Code|jar}} with:
<div class="source">
<syntaxhighlight lang=bash>
jar -cfm example.jar example.mf *.class
</syntaxhighlight>
</div>
Afterwards, you can run the {{Code|.jar}} with:
<div class="source">
<syntaxhighlight lang=bash>
java -jar example.jar
</syntaxhighlight>
</div>
Once you have the Java examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget Java library. Please see the [[#Use Our Examples| previous]] section for instructions.

In your code, you will need to include the Phidget Java library:

<div class="source">
<syntaxhighlight lang=java>
import com.phidgets.*;
import com.phidgets.event.*;
</syntaxhighlight>
</div>

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

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

===NetBeans===

=====Use Our Examples=====

You first download the [{{SERVER}}/downloads/examples/JavaJNI.zip examples], unpack them into a folder, and then find the source code for your device. {{FindYourDevice}} The full examples were written in NetBeans, so the rest of this section will use these examples. To use the simple examples, you will have to import the source code into a new NetBeans project.

[[File:Java NetBeans Open Project.PNG|link=|alt=Open Project]]

The only thing left to do is to run the examples! Click on Run → Run Project. The project, by default tries to find the {{Code|phidget21.jar}} in {{Code|..\..\lib}}.

[[File:Java NetBeans Run.PNG|link=|alt=Run]]

Once you have the Java examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget Java library. To begin:

1. Create a new Java application project with a descriptive name such as PhidgetTest.

[[File:Java NetBeans New Project.PNG|link=|alt=New Project]]

2. Add a reference to the Phidget Java library. In the projects pane, right click {{Code|Libraries}} and add the {{Code|jar}}.

[[File:Java NetBeans Add Jar.PNG|link=|alt=Add Jar]]

3. Find and select {{Code|phidget21.jar}}.

[[File:Java NetBeans Add Jar 2.PNG|link=|alt=Add Jar]]

4. Then, in your code, you will need to include the Phidget Java library:

<div class="source">
<syntaxhighlight lang=java>
import com.phidgets.*;
import com.phidgets.event.*;
</syntaxhighlight>
</div>

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

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

===Eclipse===

=====Use Our Examples=====

1. Download the [{{SERVER}}/downloads/examples/JavaJNI.zip examples] and unpack them into a folder. Here, you can find an example program called HelloWorld which will work with any Phidget. You will also find example programs for all the devices. {{FindYourDevice}}

Please use the simple examples. The full examples were written in NetBeans, and are not compatible with Eclipse. The rest of this guide will assume that the simple examples are used. The example source code will be copied into your Eclipse project later on. Keep note of the file name of the example as a Java class will be created with the same name.

2. Generate a new Java project with a descriptive name such as PhidgetTest. Click next.

[[File:Java Eclipse New Project.PNG|link=|alt=New Project]]

3. On the next screen, go to the libraries panel and add an external {{Code|jar}}.

[[File:Java Eclipse Add Jar 1.PNG|link=|alt=Add Jar]]

4. Find and select {{Code|phidget21.jar}}.

[[File:Java Eclipse Add Jar 2.PNG|link=|alt=Add Jar]]

5. Add a new Java class to the project.

[[File:Java Eclipse New Class.PNG|link=|alt=New Class]]

6. Name this class with the same name as the simple example's name.

[[File:Java Eclipse New Class 2.PNG|link=|alt=New Class]]

7. Copy and paste the example source code over to the class you created.

[[File:Java Eclipse Source.PNG|link=|alt=Source Code]]

8. The only thing left to do is to run the examples!

[[File:Java Eclipse Run.PNG|link=|alt=Run]]

Once you have the Java examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget Java library. Please see the [[#Use Our Examples 3| Use Our Examples]] section for instructions.

In your code, you will need to include the Phidget Java library:

<div class="source">
<syntaxhighlight lang=java>
import com.phidgets.*;
import com.phidgets.event.*;
</syntaxhighlight>
</div>

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

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

==OS X==

The first step in using Java on Mac is to install the Phidget libraries. Compile and install them as explained on the [[OS - OS X|main Mac OS page]]. That page also describes the different Phidget files, their installed locations, and their roles.

===Use Our Examples===

The commands to compile in a OS X and Windows terminal are slightly different. Rather than prefixing {{Code|phidget21.jar}} with a semi-colon( {{Code|;}} ), a colon( {{Code|:}} ) is used. Make sure that the {{Code|phidget21.jar}} file is in the same directory as the code you are trying to compile.

<div class="source">
<syntaxhighlight lang=bash>
javac -classpath .:phidget21.jar example.java
</syntaxhighlight>
</div>

Then, to run the program:

<div class="source">
<syntaxhighlight lang=bash>
java -classpath .:phidget21.jar example
</syntaxhighlight>
</div>

This method can be used on any of the simple examples. If you are interested in using an IDE then refer to the [[Language - Java#Windows (2000/XP/Vista/7)|Windows]] section for information about setting up Phidgets projects in Eclipse or NetBeans.

===Write Your Own Code===
With the method just discussed, notice that you need to link the {{Code|phidget21.jar}} both at compile, and runtime. An alternative is to make a jar file of your program which includes the Phidget Java library. To do this first create a manifest file. A manifest is a text file used to define package related data. Make a text file called {{Code|MyProgram.mf}}, where {{Code|MyProgram}} is replaced by the name of your main class. Put the following lines into {{Code|MyProgram.mf}}:

<div class="source">
<syntaxhighlight lang=text>
Manifest-Version: 1.0
Class-Path: phidget21.jar
Main-Class: MyProgram

</syntaxhighlight>
</div>

'''Note:''' The manifest file should end with a carriage return. So, there should be an extra line at the bottom of the file.

After creating the manifest file, you can use the {{Code|jar}} function to create one self-contained file with your classes and the correct classpath.

<div class="source">
<syntaxhighlight lang=bash>
jar –cfm MyProgram.jar MyProgram.mf *.class
</syntaxhighlight>
</div>

If porting this for an external system, such as one that your customer would be running, the Phidget library would need to be compiled and distributed along with the {{Code|.jar}}. Although we do not directly support this, if you are interested in how to construct this, we provide both a distribution example and information on cross-compiling:
* The [[Language - Android Java | Android Java]] libraries have an ARM-compiled {{Code|libphidget21.so}} file included, as an example of distributing a compiled libphidget21.so with the jar file
* The [[OS - Linux#Cross-Compiling with a Custom Toolchain|Linux page]] has more detail for compiling the Phidget C Libraries for an external target.

===NetBeans===

We offer in-depth tutorials on using our examples in NetBeans and Eclipse in the [[#NetBeans|Windows NetBeans]] and [[#Eclipse|Windows Eclipse]] sections.

As our full examples are written with NetBeans, but NetBeans is not part of the standard OS X application suite., we offer installation instructions here before referring to the Windows sections.

====Installation====
To install NetBeans on a Mac, all you have to do is download the installer from [http://netbeans.org/ their website] and run it.

====Use Our Examples====

Once you have NetBeans installed, running our examples will be very similar to the process described in the [[#NetBeans|Windows NetBeans]] section.

====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 development environment to properly link the Phidget Java library. Please see the [[#NetBeans| Windows NetBeans]] section for instructions if you are unfamiliar with NetBeans.

In your code, you will need to include the Phidget Java library:

<div class="source">
<syntaxhighlight lang=java>
import com.phidgets.*;
import com.phidgets.event.*;
</syntaxhighlight>
</div>

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

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

==Linux==

Java has excellent support on Linux - there is an established implementation of the Java compiler and interpreter, and several Integrated Development Environments (IDEs) including NetBeans and Eclipse.

The first step in using Java on Linux is to install the base Phidget libraries. Compile and install them as explained on the main [[OS - Linux | Linux page]]. That Linux page also describes the different basic Phidget library files, their installed locations, and their roles.

You will also need the [{{SERVER}}/downloads/libraries/phidget21jar.zip Phidget Java Libraries (phidget21.jar)].

Once downloaded, the {{Code|phidget21.jar}} library file does not get 'installed' (i.e. do not run {{Code| java -jar phidget21.jar}}). Rather, the library file gets put into the path of whatever program you write, and you will link it via both the java compiler and the java interpreter. We walk you through this below.

We have two different types of Phidget examples in Java:
*Simple examples, to be run on the command line, and
*Full examples, to be run in NetBeans

Both are contained within the [{{SERVER}}/downloads/examples/JavaJNI.zip Phidget Java example download package].

===Description of Library Files===

The Phidget Java libraries depend on the C libraries being installed as explained on the main [[OS - Linux | Linux page]]. If you browse around within the phidget21.jar archive, you will find Java class files (too many to reasonably list here) that have names related to the devices they provide an API for.

These Java class files use the functions available in the ''dynamic'' Phidget21 C-language library on Linux. Dynamic libraries end with {{Code|.so}}, and so the C library that the Phidget Java class files use is {{Code|/usr/lib/libphidget21.so}}.

===Javac (Command Line)===

====Use Our Examples====

Linux gets somewhat complicated in that two Java compilers exist: {{Code|openjdk}} and {{Code|gcj}}. Furthermore, a given IDE can ''usually'' use either compiler. That being said, we only offer support here for openJDK and IDEs running openJDK.

To find out which type of compiler your computer has, use the {{Code|-version}} option on the command line. You can use the same option for your runtime environment (interpreter):

<div class="source">
<syntaxhighlight lang=text>
$> java -version
java version "1.6.0_23"
OpenJDK Runtime Environment (IcedTea6 1.11pre) (6b23~pre11-0ubuntu1.11.10.1)
OpenJDK 64-Bit Server VM (build 20.0-b11, mixed mode)

$> javac -version
javac 1.6.0_23
</syntaxhighlight>
</div>

The good news is that you can have both {{Code|openjdk}} and {{Code|gcj}} on your machine, co-habitating happily. There can be only one linked java and javac in {{Code|/usr/bin/}} however, and so this will correspond to whichever java compiler and interpreter you installed last.

If you do not have {{Code|openjdk}} installed already (this is the default Java installation for most Linux machines, so you will probably know), and you choose to install it for Phidget purposes, it is important is that the {{Code|java}} version be greater than the {{Code|javac}} version. Otherwise, your runtime environment will consider the stuff your compiler produces to be newfangled nonsense. So when installing Java from a repository, you should install both the jdk and the jre. These are, unfortunately, usually separate packages in a repository (e.g. {{Code|openjdk-7-jre}} and {{Code|openjdk-7-jdk}}).

The simple examples in Java are meant to be compiled and run on the command line. The example package includes a {{Code|Makefile}} so you can either make all of the examples at once, with:

<div class="source">
<syntaxhighlight lang=bash>
make all
</syntaxhighlight>
</div>

...Or you can make them individually. You can either use:
* The HelloWorld example, which will work with any Phidget, or
* The example with the name that corresponds to the family (software object) of your Phidget hardware.
{{FindYourDevice}} Once you've identified the right example - say, {{Code|HelloWorld.java}} - compile it on the command line with:

<div class="source">
<syntaxhighlight lang=bash>
javac -classpath .:phidget21.jar HelloWorld.java
</syntaxhighlight>
</div>

To run the example on a Linux machine [[OS - Linux#Setting udev Rules| without your udev USB rules set]], you will need to run the Java example as root:

<div class="source">
<syntaxhighlight lang=bash>
sudo java -classpath .:phidget21.jar HelloWorld
</syntaxhighlight>
</div>

====Write Your Own Code====

You'll note that the Phidget Java library file {{Code|phidget21.jar}} needs to be explicitly linked at both points in the compile and run process. Alternatively, you can make a jar file which includes the Phidget Java library. This process takes two steps, the first of which is creating a text file called {{Code|MyProgram.mf}}, where {{Code|MyProgram}} is replaced by the name of your main class in both the filename and the text below:

<div class="source">
<syntaxhighlight lang=text>
Manifest-Version: 1.0
Class-Path: phidget21.jar
Main-Class: MyProgram

</syntaxhighlight>
</div>

'''Note:''' The manifest file should end with a carriage return. So, there should be an extra line at the bottom of the file.

After creating the manifest file, you can use the {{Code|jar}} function to create one self-contained file with your classes and the correct classpath.

<div class="source">
<syntaxhighlight lang=bash>
jar –cfm MyProgram.jar MyProgram.mf *.class
</syntaxhighlight>
</div>

If porting this for an external system, such as one that your customer would be running, the Phidget library would need to be compiled and distributed along with the {{Code|.jar}}. Although we do not directly support this, if you are interested in how to construct this, we provide both a distribution example and information on cross-compiling:
* The [[Language - Android Java | Android Java]] libraries have an ARM-compiled {{Code|libphidget21.so}} file included, as an example of distributing a compiled libphidget21.so with the jar file
* The [[OS - Linux#Cross-Compiling with a Custom Toolchain|Linux page]] has more detail for compiling the Phidget C Libraries for an external target.

===NetBeans===

We offer in-depth tutorials on using our examples in NetBeans and Eclipse in the [[#NetBeans|Windows NetBeans]] and [[#Eclipse|Windows Eclipse]] sections.

As our full examples are written with NetBeans, but NetBeans is not part of the standard Linux package repository, we offer installation instructions here before referring to the Windows sections.

====Installation====

Although Eclipse is standard in the Debian/Ubuntu package repository, NetBeans is no longer standard. What is more, Netbeans does not install by default into a folder within your path. As our Phidget full Java examples are written using NetBeans, we provide basic installation instructions here so you can actually run them.

To install NetBeans:

1. Download the install script from website: [http://netbeans.org/downloads/ http://netbeans.org/downloads/]<br>
2. Change the permissions of the downloaded file to be executable. Usually, this is something like:
:{{Code|chmod +x netbeans-7.1-ml-javase-linux.sh}}<br>
3. Run the downloaded file as a script. (This will result in a GUI interaction that walks you through installation.)<br>
4. To find the location where the NetBeans installation occurred, run:<br>
:{{Code|updatedb}}
:{{Code|locate netbeans | grep bin}}<br>
5. Usually, the location of the binary is {{Code|/usr/local/netbeans-7.1/bin/netbeans}}, where 7.1 is the installed version.

====Use Our Examples====

Once you have NetBeans installed, running our examples will be very similar to the process described in the [[#NetBeans|Windows NetBeans]] section.

====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 development environment to properly link the Phidget Java library. Please see the [[#NetBeans| Windows NetBeans]] section for instructions if you are unfamiliar with NetBeans.

In your code, you will need to include the Phidget Java library:

<div class="source">
<syntaxhighlight lang=java>
import com.phidgets.*;
import com.phidgets.event.*;
</syntaxhighlight>
</div>

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

The [[#Follow the Examples|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 Java code will be our Java API information, with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|both of which are available in Java|[{{SERVER}}/documentation/JavaDoc.zip Java API]}}

===Example Flow===

{{ExamplePseudocode|In Java, it is easiest if you name these '''event''' functions the same as in our examples. You can change the main function pointer variable name, but none of the other names. Our examples show how to immediately hook these functions into the events that will call them <br> <br>
In the example code, the event functions common to all Phidgets are called things like '''AttachHandler()''' and '''DetachHandler()''', etc.<br>
But 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. Some 'get data' functions are also specific to each device.
|Creating a Phidget software object in Java - when you are not using the Manager - is specific to the Phidget. For a Phidget Spatial, for example, this would involve creating a {{Code|SpatialPhidget}} object. The device-specific examples show how to do this and other API functions.<br><br>
The software object provides device specific methods which are available from the API for your specific Phidget.|
[{{SERVER}}/documentation/JavaDoc.zip Java API]}}

===Code Snippets===

When programming in Java, you're in luck. All of our code snippet examples on our [[General Phidget Programming]] page are in both C++ and Java. Therefore, we do not include any here, because that page is much more in-depth, and you won't have to have two pages open at once. So head over there, and start writing code!

==Common Problems and Solutions/Workarounds==

None at this time.

Language - Android Java

2012-06-29T20:00:59Z

Cora: /* Quick Downloads */

[[Category:Language]]
{{OSLang|[[File:Icon-Android.png‎|64x64px|link=|alt=]]|Android Java is the main language used to program for the [[OS - Android|Android OS]].}}
__TOC__

==Introduction==

{{LanguageSupport|Android|nearly the complete Phidget API, including events, and only excepting a few open() calls outlined later|the Phidget Interface Kit and two Hello World examples.|Eclipse on Windows, Mac OS, and Linux|}}

==Quick Downloads==
{{QuickDownloads|Android|
{{APIQuickDownloads|{{SERVER}}/documentation/JavaDoc.zip}}
{{ExtraAPIQuickDownloads|{{SERVER}}/documentation/web/javadoc/index.html|HTML Version of}}|
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/android-examples.tar.gz|(and Phidget Android Library)}}|
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/examples/android-examples.tar.gz||(Phidget21.jar included in Examples)}}
{{WindowsQuickDownloads}}
{{MacQuickDownloads}}
{{LinuxQuickDownloads}}
}}

==Getting Started with Android Java (Eclipse)==

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

As Android development is primarily done on Eclipse, and Eclipse is relatively platform-independent, we provide instructions for Eclipse rather than by operating system.

For basic differences on installing and setting up Eclipse on your development system, you can try the [[OS - Android|Android Operating System]] page. However, your best bet for information about general use of Eclipse on your development operating system (Windows, Mac, or Linux) will be the [http://www.eclipse.org/documentation/ Eclipse support page] or the Internet at large.

Phidgets can run directly plugged in to Android devices with a USB port and system 3.1 or later.

Otherwise, Android can control a Phidget remotely over a network, by using the [[Phidget WebService]]

Hence, we split instructions up by Android OS version number.

===Android Under 3.1 (and/or no USB Port)===

These types of phones and tablets can use Phidgets only remotely over a network using the [[OS - Android#WebService|Phidget WebService]].

====Use Our Examples====

Download and unpack the [{{SERVER}}/downloads/examples/android-examples.tar.gz Phidget Examples for Android]. There are two Hello World examples: {{Code|HelloWorldRemote}} (the one you want), and {{Code|HelloWorld}} (for tablets with a USB port).

Import the {{Code|HelloWorldRemote}} example into Eclipse:
* File → Import... → General → Existing Projects Into Workspace → (Next)
* Select {{Code|HelloWorldRemote}} root directory → Select all files → Finish

Next, you '''must change''' the IP address within the example code to the IP address of the computer directly connected to the Phidget you are trying to control. This happens on the line that says something like:
<div class="source">
<syntaxhighlight lang=java>
device.open("192.168.3.133", 5001);
</syntaxhighlight>
</div>

Also, note that the HelloWorldRemote example was written for Android 2.1. If needed, you can change this in:
(Right Click on Project) → Properties → Resource (on left) → Android

To run the example: Right-click on project in Package Explorer (To open the Package Explorer, use Window → Show View → Package Explorer)

Select Run As... → Android Application

This will bring up the Android Virtual Device manager window. If your Android hardware is plugged in to your debugging computer, you will see the hardware as an option on which to run the example. You should run it directly on your Android device, unless you are comfortable setting up the emulator to run on your local network.

After the {{Code|HelloWorldRemote}} application starts running on your Android device:
# Make sure the Phidget WebService is running on the computer with the IP address you put into the code
#*For directions on how to set up and run the webservice on a remote computer, refer to the page [[Software Overview#Operating System Support|for that operating system]]
# Plug a Phidget into that computer

And on your Android device, depending on which Phidget you plug in, you should see something like:

[[Image:android_helloworld_remotehello.png|700px|alt=|link=]]

And when you unplug that Phidget from the remote computer, you should see something like this on your Android device:

[[Image:android_helloworld_remotegoodbye.png|700px|alt=|link=]]

If you have the specific Phidget for the other included Android examples (i.e. the InterfaceKit), you can run the other examples in the same way.

To envision the system in the background, you can refer to the WebService section on the [[OS - Android]] page.

====Write Your Own Code====

To write your own code from scratch, start with an Android project in Eclipse (File → New → Android Project). Then....

=====Step One: Link the Phidget Libraries to your Project=====

When you download and unzip the [{{SERVER}}/downloads/examples/android-examples.tar.gz Phidget Examples for Android], each project folder will (in addition to the project files themselves) contain three things:
# A libs/ folder (containing an armabi/ folder and a single file called libphidget21.so)
# A jar file containing the general Phidget java library (phidget21.jar)
# A jar file for directly driving USB devices from a USB port on the Android device (PhidgetsUSB.jar)

Copy the {{Code|libs}} folder, the {{Code|PhidgetsUSB.jar}} file, and the {{Code|phidget21.jar}} file to your project folder.

To install libraries to run a Phidget '''remotely''' over a network using the WebService:
# Add the libs/ folder to your project
#* To add the libs/ folder in Eclipse, simply place it in the root folder of your project
# Add the phidget21.jar file to your project
#* In Eclipse use the top-bar menu: Project → Properties → Java Build Path → Libraries (tab) → Add JAR

=====Step Two: Give your Program Permission to use the Internet=====

Add the following to your <code>AndroidManifest.xml</code> file:

<div class="source"><syntaxhighlight lang=xml>
<uses-permission android:name="android.permission.INTERNET"></uses-permission>
</syntaxhighlight></div>

=====Step Three: Include the Phidget Libraries in your Source=====

Then, in your code, include an {{Code|import}} reference to the library. In Android Java:

<div class="source"><syntaxhighlight lang=java>
// This contains all of the devices and the exceptions
import com.phidgets.*;

// This contains all of the event listeners
import com.phidgets.event.*;
</syntaxhighlight></div>

Then you are ready to begin coding!

===Android 3.1+ with USB Port===

If your tablet has a USB host port and is running Android 3.1 or later, you can plug Phidgets directly into it.

====Use Our Examples====

Download and unpack the [{{SERVER}}/downloads/examples/android-examples.tar.gz Phidget Examples for Android]. There are two Hello World examples: {{Code|HelloWorld}} (the one you want), and {{Code|HelloWorldRemote}} (for controlling Phidgets over the WebService).

Import the {{Code|HelloWorld}} example into Eclipse:
* File → Import... → General → Existing Projects Into Workspace → (Next)
* Select {{Code|HelloWorldRemote}} root directory → Select all files → Finish

Note that the HelloWorld example was written for Android 3.1. If needed, you can change this in:
(Right Click on Project) → Properties → Resource (on left) → Android

To run the example: Right-click on project in Package Explorer (To open the Package Explorer, use Window → Show View → Package Explorer)

Select Run As... → Android Application

This will bring up the Android Virtual Device manager window. If your Android hardware is plugged in to your debugging computer, you will see the hardware as an option on which to run the example. You should run it directly on your Android device, unless you are comfortable setting up the emulator to use your development computer's USB hub.

After the {{Code|HelloWorld}} application starts running on your Android device, plug a Phidget into your Android tablet's USB port!

Since the USB device requires special permission, the first thing you will probably see is a request from the Phidget example to use the USB port:

[[Image:android_helloworld_usb_permissions.png|500px|alt=|link=]]

And on your Android device, depending on which Phidget you plug in, you should see something like:

[[Image:android_helloworld_hello.png|700px|alt=|link=]]

And when you unplug that Phidget from the remote computer, you should see something like this on your Android device:

[[Image:android_helloworld_goodbye.png|700px|alt=|link=]]

If you have the specific Phidget for the other included Android examples (i.e. the InterfaceKit), you can run the other examples in the same way.

If you are having trouble running the examples, a method to debug the Android USB port is on the [[OS - Android]] page, under the Hardware section.

====Write Your Own Code====

To write your own code from scratch, start with an Android project in Eclipse (File → New → Android Project). Then....

=====Step One: Link the Phidget Libraries to your Project=====

When you download and unzip the [{{SERVER}}/downloads/examples/android-examples.tar.gz Phidget Examples for Android], each project folder will (in addition to the project files themselves) contain three things:
# A libs/ folder (containing an armabi/ folder and a single file called libphidget21.so)
# A jar file containing the general Phidget java library (phidget21.jar)
# A jar file for directly driving USB devices from a USB port on the Android device (PhidgetsUSB.jar)

Copy the {{Code|libs}} folder, the {{Code|PhidgetsUSB.jar}} file, and the {{Code|phidget21.jar}} file to your project folder.

To install libraries to run a Phidget '''remotely''' over a network using the WebService:
# Add the libs/ folder to your project
#* To add the libs/ folder in Eclipse, simply place it in the root folder of your project
# Add the phidget21.jar file to your project
# Also add the PhidgetsUSB.jar file to your project
#* In Eclipse, to add jar files use the top-bar menu: Project → Properties → Java Build Path → Libraries (tab) → Add JAR

=====Step Two: Give your Program Permission to use USB=====

Add the following to your <code>AndroidManifest.xml</code> file:

<div class="source"><syntaxhighlight lang=xml>
<uses-feature android:name="android.hardware.usb.host" />
</syntaxhighlight></div>

=====Step Three: Include the Phidget Libraries in your Source=====

Then, in your code, include an {{Code|import}} reference to the library. In Android Java:

<div class="source"><syntaxhighlight lang=java>
// This contains all of the devices and the exceptions
import com.phidgets.*;

// This contains all of the event listeners
import com.phidgets.event.*;
</syntaxhighlight></div>

Then you are ready to begin coding!

==Follow the Examples==

By following the instructions 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 section has resources for you to learn from the examples and write your own.

Programming with Phidgets in Android Java makes extensive use of the mainstream Java Phidgets library, so the Java API reference will be helpful:

{{UsingAPhidgetInCodeGeneral|although you can only use the event code in Android|[{{SERVER}}/documentation/JavaDoc.zip Java API]}}

===API Support===

Most of the Java API is supported in Android. However, only some of the available open calls are supported:

When using a Phidget over a network, you can open the remote Phidget using one of the supported Java API calls:
<div class="source"><syntaxhighlight lang=java>
void open(int serial, java.lang.String ipAddress, int port)
void open(int serial, java.lang.String ipAddress, int port, java.lang.String password)
void openAny(java.lang.String ipAddress, int port)
void openAny(java.lang.String ipAddress, int port, java.lang.String password)
void openLabel(java.lang.String label, java.lang.String ipAddress, int port)
void openLabel(java.lang.String label, java.lang.String ipAddress, int port, java.lang.String password)
</syntaxhighlight></div>

When using a Phidget when it is directly plugged in to an Android 3.1 or later tablet, you can use one of these supported Java API calls:
<div class="source"><syntaxhighlight lang=java>
void open(int serial)
void openAny()
void openLabel(java.lang.String label)
</syntaxhighlight></div>

This leaves these Java API calls, which are '''unsupported''' on Android:
<div class="source"><syntaxhighlight lang=java>
void open(int serial, java.lang.String serverID)
void open(int serial, java.lang.String serverID, java.lang.String password)
void openAny(java.lang.String serverID)
void openAny(java.lang.String serverID, java.lang.String password)
void openLabel(java.lang.String label, java.lang.String serverID)
void openLabel(java.lang.String label, java.lang.String serverID,
java.lang.String password)
</syntaxhighlight></div>

===Code Snippets===

Specific calls in Android Java 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 Android Java 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 [{{SERVER}}/products.php?product_id=1018 Phidget Interface Kit] as our device, the general calls would look like this:

====Step One: Initialize and Open====

For opening a remote Phidget over the network using the WebService:

<div class="source"><syntaxhighlight lang=java>
InterfaceKitPhidget device;
device = new InterfaceKitPhidget();

// Open first detected Interface Kit, remotely with IP address and port
device.open("192.168.3.33", 5001);
</syntaxhighlight></div>

For opening a Phidget directly attached to the tablet's USB port:

<div class="source"><syntaxhighlight lang=java>
InterfaceKitPhidget device;
com.phidgets.usb.Manager.Initialize(this);
device = new InterfaceKitPhidget();

// Open locally, with Phidget in tablet USB port
ik.open("192.168.3.33", 5001);
</syntaxhighlight></div>

The direct open call 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.

Both open calls will tell the program to continuously try to connect to a Phidget, based on the parameters given, even trying to reconnect if it gets disconnected.
This means that simply calling open does not guarantee you can use the Phidget immediately. We can handle this by using event driven programming and tracking the AttachEvents and DetachEvents....

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

To use the Phidget, it must be plugged in and a software event caught (i.e. attached).

Android Java is '''only''' event-driven, so you cannot use {{Code|waitForAttachment()}} without hanging and being relatively unsafe with your threads. Instead, you should define an event handler function that you can then synchronize and tie in with the attachment event itself.

First, let's write our handler:

<div class="source"><syntaxhighlight lang=java>
class AttachEventHandler implements Runnable {
Phidget device;
TextView eventOutput;

public AttachEventHandler(Phidget device, TextView eventOutput) {
this.device = device;
this.eventOutput = eventOutput; }

public void run() {
try {
// The actual useful thing our handler does
eventOutput.setText("Hello " + device.getDeviceName() + ", Serial " + Integer.toString(device.getSerialNumber()));
} catch (PhidgetException e) { e.printStackTrace(); }

// Notify whoever called us (and is waiting) that we're done
synchronized(this) { this.notify(); }
}
}
</syntaxhighlight></div>

This may seem complex, but really it is just:
# A class wrapper so we can work independently once we get permission from the main thread, and
# A way to call back to the {{Code|synchronized()}} call to let them know we're done and stay thread safe

Now that we have our 'handler' we can hook it in as an event function to trigger on device attachment:

<div class="source"><syntaxhighlight lang=java>
device.addAttachListener(new AttachListener() {
public void attached(final AttachEvent attachEvent) {
AttachEventHandler handler = new AttachEventHandler(attachEvent.getSource(), eventOutput);

// This is synchronised in case more than one device is attached before one completes attaching
synchronized(handler) {

runOnUiThread(handler);
try { handler.wait(); } catch (InterruptedException e) { e.printStackTrace(); }
}
}
});
</syntaxhighlight></div>

====Step Three: Do Things with the Phidget====

Again, because Android is event driven, use buttons (or timers) to schedule events if you want to poll the device at a certain interval or user specification. Otherwise, simply set the sensitivity and/or data rate (depending on your device type) and catch events as they come in using the handler structure above.

====Step Four: Close and Delete====

At the end of your program, don’t forget to call close to free any locks on the Phidget.

We can put the close() call for Phidgets in Android within an overridden version of the onDestroy() Android application function. Within it, we simply close the device. For Phidgets directly attached to a USB Android tablet, you should also call Uninitialize():

<div class="source"><syntaxhighlight lang=java>
@Override
protected void onDestroy() {
super.onDestroy();
try { device.close(); } catch (PhidgetException e) { e.printStackTrace(); }
// Uninitialize should only be called for directly connected Phidgets
com.phidgets.usb.Manager.Uninitialize();
}
</syntaxhighlight></div>

The ''complete'' set of functions you have available for all Phidgets can be found in the [{{SERVER}}/documentation/JavaDoc.zip Java API]. You can also find more description on any device-specific function in the Device API for your specific Phidget, which can be found on its product page on [[{{SERVER}} our main website]].

==Common Problems and Solutions/Workarounds==

This section contains some Android Java and Eclipse-specific common problems. For more answers about using Phidgets, visit our forums, FAQ, or contact us.

==={{ProblemSolution|Eclipse Error|Unable to get view server protocol version from device emulator}}===

Likely Fix: Project → Clean... → Clean All (If that does not work, clean again and restart Eclipse)

==={{ProblemSolution|Eclipse Error|Android requires compiler compliance level 5.0 or 6.0. Found 'X.Y' instead}}===

Likely Fix: This may happen when running the examples. The javac and java version on the example do not match those on your computer.
* Find the version of java and javac on your computer (for example, <code>java -version</code> on the command line)
* In Eclipse, open the Package Explorer (Window → Show View → Package Explorer)
* Find the project, right-click and select Properties
* In Properties → Java Compiler → (Checkbox) Enable Project Specific Settings → Set Compiler Compliance Level = Java Version → Apply
* When told this requires rebuild, say Rebuild Now

OS - Linux

2012-06-29T19:59:16Z

Cora:

[[Category:OS]]
{{OSLang|[[File:icon-Linux.png|64x64px|link=OS - Linux]]|On Linux, Phidgets can be either plugged directly into a USB Port or run over a network using the [[#WebService | WebService]].}}
__TOC__

You need kernel '''version 2.6''' (released in 2003) or later.

==Quick Downloads==

Linux has complete support for all Phidgets and their software APIs; the only thing it lacks when compared to Windows and Mac OSX is a graphical user interface. We walk you through all steps for download, installation, checking, and starting to write code below.

If you are already a pro, and just want the downloads:
*[{{SERVER}}/downloads/libraries/libphidget.tar.gz Phidget Libraries for Linux]
*[{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz Phidget Generic C Examples]
*[{{SERVER}}/downloads/libraries/phidgetwebservice.tar.gz Phidget WebService for Linux]
*[{{SERVER}}/Drivers_Info.html#linux Software license]

==Getting Started with Linux==

===Installing===

To install the libraries, follow these steps:

#Download {{Code|libusb-0.1}} and its development libraries.
#*Note that libusb may be already on your system, but the development libraries probably aren't.
#*Try {{Code|apt-cache search libusb}} in a terminal to find current installable packages from your source list
#*Or install [http://www.libusb.org/ from source], which includes the libusb development libraries by default
#Unpack and install the [{{SERVER}}/downloads/libraries/libphidget.tar.gz Phidget Libraries]
#*From the main unpacked libraries directory, run:
#*:{{Code|./configure}}
#*:{{Code|make}}
#*:{{Code|sudo make install}}
#*This will compile phidget21.h and place the library into your gcc path

'''Note:''' Although these libraries are written in C, the additional libraries for Python, Java, and most other Phidget-supported languages depend on them.

===Checking===

To confirm the libraries were installed and work correctly, you can check both the hardware and software sides of the interface. It is worth checking the software side first, because if it works then you know the hardware side is also okay.

====Software====

To confirm that the libraries were installed correctly and can be used in code, you can use the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz Phidget Generic C Examples].

The easiest way to confirm correct installation will be to compile and run the {{Code|HelloWorld}} C example, included in the examples download. This does not involve writing any C code, but it does involve compiling the example and running it, which is a quick process as we show below. If you feel more comfortable running the {{Code|HelloWorld}} example for your specific language, you can skip below and pick your language, but keep in mind that any problems could be with the C library installation and not necessarily with your language.

To compile and run the basic C example for checking your installation:

1. Unpack the Phidget Generic C Examples<br>
2. Open a terminal (often Ctrl-Alt-T) and go to the directory where the examples are unpacked<br>
3. Compile the {{Code|HelloWorld.c}} example:<br>
<div class="source">
<syntaxhighlight lang=bash>

gcc HelloWorld.c -o HelloWorld -lphidget21

</syntaxhighlight>
</div>
4. Run the {{Code|HelloWorld}} example:<br>
<div class="source">
<syntaxhighlight lang=bash>

sudo ./HelloWorld

</syntaxhighlight>
</div>
(The sudo is needed for USB access for now, see the [[#Setting udev Rules|Setting udev Rules]] section for how to change this)

The {{Code|-lphidget21}} will look in the standard library location for your Linux distribution (usually {{Code|/usr/lib/}}) for the Phidget 21 library file. Generally, libraries to be linked on Linux through {{Code|gcc}} have a naming convention. For example, {{Code|-lphidget21}} looks for the binary files '''{{Code|libphidget21.a}}''' and '''{{Code|libphidget21.so}}''' in the library location. These files are automatically put in the library location during the {{Code|make install}} step of [[#Installing | installing the libraries]].

The HelloWorld program will simply print out basic information for any device you plug in, and print a message upon unplugging the device. For example, starting the program, plugging in an Interface Kit Phidget, unplugging the Interface Kit, and pressing Enter displays:

<div class="source">
<syntaxhighlight lang=bash>

$ sudo ./HelloWorld

Opening...
Press Enter to end

Hello to Device Phidget InterfaceKit 8/8/8, Serial Number: 37299
Goodbye Device Phidget InterfaceKit 8/8/8, Serial Number: 37299

Closing...

</syntaxhighlight>
</div>

====Hardware====

If the out-of-the-box examples do not work, make sure the Phidget is seen by your USB interface. To check this, you can use the kernel log reader {{Code|dmesg}}. Pipe the output of {{Code|dmesg}} into the utility {{Code|tail}} to read the last ten lines of the log:

<div class="source">
<syntaxhighlight lang=bash>

$> dmesg | tail
....(9 lines)....
[24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd

</syntaxhighlight>
</div>

The number between the [ ] is the system time in seconds since the last boot up, so you can tell whether the event was recent or not. (This will also tell you the interrupt type of Phidget that is registered by the USB interface, see the [[#Common Problems and Solutions | common problems section below]] for more information on what this means.)

The Phidget should both connect and disconnect properly, so unplugging it should result in an additional line at the tail:

<div class="source">
<syntaxhighlight lang=bash>

$> dmesg | tail
....(8 lines)....
[24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd
[25094.809328] usb 2-1.2: USB disconnect, device number 5

</syntaxhighlight>
</div>

If you don't see similar lines to these at the tail of your kernel log, take a look at the [[#Troubleshooting|troubleshooting]] section below, as well as the '''Communications''' section of our [[General Troubleshooting#Communications Troubleshooting|general troubleshooting page]].

====Troubleshooting====

If the examples '''do not''' work but USB '''does''' work (i.e. your computer can consistently see the device in the [[#Hardware|hardware]]), take a moment to check the basics:
* No other programs, drivers, or processes are using that USB port in software
* You are running the example program as root (or your udev rules have been set properly)
* You are using libusb 0.1 (not 1.0 or later)
* You have compiled versions of libphidget21.a and libphidget21.so in your system library location (usually {{Code|/usr/lib}})
* The Phidget libraries are the latest version (visit the [[#Quick Downloads| quick downloads section]] to download them)
* Your Linux kernel version is 2.6 or later (type {{Code|uname -r}} in a terminal to get your kernel version)
* Check the [[#Common Problems and Solutions|common problems]] section below, some specific combinations can cause problems

If your problem doesn't seem to be fixed by these steps, make sure that the Phidget is seen '''consistently''' by USB (if it is erratic, try our [[General Troubleshooting|general troubleshooting guide]]). If you are still having problems after using the troubleshooting guide, please [[Contact Us|ask us]]!

==Programming Languages==

Now that you have the basic libraries installed, you can pick your language and begin programming!

If you are not using the [[#WebService | webservice]] (discussed below) to control a Phidget over a network, your next step will be to delve into the use of your specific language. Each page has its own set of specific libraries, code examples, and setup instructions.

On Linux, we recommend the following languages:

*[[Language - C/C++|C/C++]]
*[[Language - Java | Java]]
*[[Language - Python | Python]]
*[[Language - Ruby | Ruby]]
*[[Language - C Sharp | C#]] (Using [[Language - C Sharp#Mono|Mono]])
*[[Language - Flash AS3 | Flash AS3]]

You can also use these languages, but they do not support [[General Phidget Programming#Event Driven Code | event driven code]], and must use [[General Phidget Programming#Logic Code | logic code]] only:

*[[Language - MATLAB|MATLAB]]
*[[Language - Simulink|Simulink]]

==WebService==

The Phidget WebService allows you to remotely control a Phidget over a network.<br>This section helps you install, check, and use the WebService on Linux, but we also have an overview of the [[Phidget WebService]] in general.

===Installing the WebService===

To install the webservice, you must first have the [[#Installing|Phidget libraries installed]]. Then, follow these steps:

#Download '''avahi''' and its development libraries (mdnsresponder/bonjour is also an option, see the [[#WebService with mDNSResponder|webservice with mDNSResponder]] section)
#*Try {{Code|apt-cache search avahi}} in a terminal to find current packages
#*Often, this is installed in a default system, you may already have it
#Unpack and install the [{{SERVER}}/downloads/libraries/phidgetwebservice.tar.gz Phidgets WebService] source code tarball for Linux
#*From the unpacked WebService source code directory, run:
#*:{{Code|./configure}}
#*:{{Code|make}}
#*:{{Code|sudo make install}}
#*This will compile the executable {{Code|phidgetwebservice21}} and place it into {{Code|/usr/bin/phidgetwebservice21}}

====WebService with BSD====

For '''BSD''', the webservice has been found to work (BSD 8+) but requires a special configuration at the {{Code|./configure}} step:

<div class="source">
<syntaxhighlight lang=bash>
./configure LIBS=/usr/lib/libphidget21.so CFLAGS=-pthread
</syntaxhighlight>
</div>

Then {{Code|make}} and {{Code|sudo make install}} are the same.
<br>
The {{Code|LIBS}} argument may not be necessary, but sometimes BSD has trouble finding the library install location. The {{Code|CFLAGS}} argument is needed because BSD needs explicit linking for using threads.

====WebService with mDNSResponder====

To use '''mdnsresponder''' instead of avahi, change the configure script to be:

<div class="source">
<syntaxhighlight lang=bash>
./configure --enable-zeroconf=bonjour
</syntaxhighlight>
</div>

(To see all options, use {{Code|./configure --help}} like you would any configure script)

===Setting Up the WebService===

To set up and use the webservice, it helps to have [[#Setting udev Rules|set your udev rules]]. Otherwise, you must run the webservice as root.

You can get command line help with {{Code|phidgetwebservice21}} by using the {{Code|-h}} option:

<div class="source">
<syntaxhighlight lang=bash>
$ phidgetwebservice21 -h
</syntaxhighlight>

<syntaxhighlight lang=text>
'phidgetwebservice21' is a Phidget and Dictionary server from Phidgets Inc. See www.phidgets.com for more information.
Usage: phidgetwebservice21 [OPTION]
All parameters are optional. The default parameters are: port=5001, ServerName=(Computer Name) and no password

Options:
-p Port
-n Server Name
-P Password
-v Debug mode
-h Display this help
</syntaxhighlight>
</div>

You will see this help regardless of whether the webservice was correctly hooked in to avahi. In fact, you will see it even if you explicitly disabled mDNS in the {{Code|./configure}} step at compile:

<div class="source">
<syntaxhighlight lang=bash>
./configure --disable-zeroconf
</syntaxhighlight>
</div>

(To see all options, use {{Code|./configure --help}} like you would any configure script)

To find the defaults used by {{Code|phidget21webservice}}, the command line is the fastest way to learn the default server name and IP address of your computer:
*For the default server name, use {{Code|hostname}} on the command line.
*For your IP address, use {{Code|ifconfig -a}} on the command line.
**A line in the return text, under your main internet connection (usually {{Code|eth0}}) will say something like {{Code|inet addr:192.168.3.178}}, which is your IP.

Using a server name to connect would not be an option without avahi or some other mDNS service; in this case you would only have the option to use an IP address.

===Using the WebService===

To use a Phidget over the webservice, you'll want to:
* Obtain code you can use to open a Phidget remotely
* Start the webservice on the computer that directly connects to the Phidget
* Run your program on the remote computer that will control the Phidget over the network

The easiest way to test these steps on Linux is simply to set up the webservice and run the Phidget program on the same computer, using the loopback interface. Later, you can replace one of the two ends with a different computer and/or operating system.

To quickly create code to run remotely, in our examples we include commented out lines with openRemote() function calls of different types. In the C example for your device, find the line that says:

{{Code|CPhidget_open((CPhidgetHandle) device, -1)}}

and change it to be:

<div class="source">
<syntaxhighlight lang=bash>
int serial_number = 37299
CPhidget_openRemoteIP ((CPhidgetHandle) device, serial_number, "127.0.0.1", 5001, NULL)
</syntaxhighlight>
</div>

Except that you should replace '''37299''' with the serial number of your Phidget, which you can obtain from either the Phidget board itself, or from when you [[#Checking|ran the HelloWorld example code]]. The IP address "127.0.0.1" simply loops back to the same computer, and 5001 is the default port as found from using {{Code|phidget21webservice -h}} in [[#Setting Up the WebService|the Setting Up the WebService]] section. The NULL is used to not specify a password.

Save the changed example under a different filename. In the walkthrough here, we are using the {{Code|InterfaceKit.c}} example, and we rename it to be {{Code|InterfaceKitRemote.c}}

Compile your new C file. In our {{Code|InterfaceKitRemote.c}} case, this would be by:

<div class="source">
<syntaxhighlight lang=bash>
gcc InterfaceKitRemote.c -o InterfaceKitRemote -lphidget21
</syntaxhighlight>
</div>

1. Start two terminals to run this test, usually opened via Ctrl-Alt-T. Your [[#Setting udev Rules|udev rules]] need to be set up or you should use sudo for every command. First, start the webservice in Terminal #1:

[[Image:Linux_ws_start.png]]

This will broadcast any Phidget events, and receive any Phidget requests, both over the network.

2. Start the InterfaceKitRemote program that you just compiled which will open the remote Phidget. In this case, it is {{Code|InterfaceKitRemote}}:

[[Image:Linux_ws_step2.png]]

3. Now, plug in the Phidget! The {{Code|phidget21webservice}} program captures the attach and other events and sends them out over the network (in the background in Terminal #1) and the Phidget software objected opened with openRemote in Terminal #2 receives them:

[[Image:Linux_ws_step3.png]]

4. You can confirm that the webservice was indeed behind this exchange by killing the webservice process while still allowing the remote program to run:

[[Image:Linux_ws_step4.png]]

===Debugging the WebService===

In addition to enabling [[General Phidget Programming#Logging|logging]] in your Phidget code, you can get additional debugging information from the WebService itself. This additional debugging is enabled via a re-compile of the webservice. From the webservice source code directory, do:

<div class="source">
<syntaxhighlight lang=bash>
make clean

./configure --enable-debug

make

sudo make install
</syntaxhighlight>
</div>

If you suspect multicast DNS (mDNS) may be the problem, you can:
* Try compiling the webservice with mDNSResponder, as described in [[#Installing the WebService|Installing the WebService]], or
* Try compiling the webservice completely without mDNS, as described in [[#Setting Up the WebService|Setting Up the WebService]]

==Advanced Uses==

===Setting udev Rules===

If you don't want to be using {{Code|sudo}} to run Phidget programs (including the webservice) forever, you will want to create a {{Code|udev}} rule to allow yourself access to the Phidget when you are not root.

Udev has an easy way to set the owner and permissions of the USB interface of the Phidget - it finds all devices that match a given set of rules, and applies new traits to them. But you need to give udev something to match in order to apply the new settings. Here, we will tell udev to match the vendor code for Phidgets, Inc. You can get the vendor code in hex by using {{Code|lsusb}}:

<div class="source">
<syntaxhighlight lang=bash>
$> lsusb
....Information about other devices...
Bus 002 Device 013: ID 06c2:0045 Phidgets Inc. (formerly GLAB) PhidgetInterface Kit 8-8-8
</syntaxhighlight>
</div>

The two numbers separated by a colon are the codes for '''vendor:product'''. Since we want to set up the rule so that all Phidgets, no matter what product, can be used without root privileges, we use the vendor code, which is '''06c2'''.

The rules for udev are kept in files in {{Code|/etc/udev/rules.d/}} and are traditionally grouped into order of running (10 runs before 20, 30, etc) and device type (cd, network, etc). There should be one or more files in there already - if this is your first time editing udev rules take a look at them to see the syntax to use:
* Commas separate each pair with == or =
* One rule on each line, no line breaks
* Quotes around the value to be matched or changed
* Comments can be added on lines starting with #

Strictly speaking, the files run in lexical order (i.e. the order they're listed when you use {{Code|ls}}). A device can match many rules, and all will apply (if possible). If conflicting rules are found, the first rule found is followed.

To make sure the Phidget udev rules are found first, we can create a file {{Code|10-persistent-usb.rules}} (all udev rule files need to end with {{Code|.rules}}) and add one line to it:

<div class="source">
<syntaxhighlight lang=bash>
SUBSYSTEM=="usb", ATTRS{idVendor}=="06c2", MODE="0666", OWNER="user"
</syntaxhighlight>
</div>

Make sure to replace {{Code|user}} with your user name. You probably recognize the '''06c2''' from the vendor discussion above. We have added the match on {{Code|SUBSYSTEM}} to search first within usb (within a possibly big database). The {{Code|MODE}} sets read and write privileges for everyone to the device, and {{Code|OWNER}} sets the owner to be you.

Save the {{Code|10-persistent-usb.rules}} in {{Code|/etc/udev/rules.d/}} and then change its permissions so it can be read by all:

<div class="source">
<syntaxhighlight lang=bash>
sudo chmod a+r /etc/udev/rules.d/10-persistent-usb.rules
</syntaxhighlight>
</div>

The udev rule is now set, and it just has to get read in. The reading of the rules is goverened by a daemon, {{Code|udevd}}, which you can manage via the program {{Code|udevadm}}. The {{Code|udevadm}} man page is quite extensive for all sorts of uses of {{Code|udevadm}} while you are testing this or other udev rules. To re-read and implement the rules without having to reset the daemon or reset the computer, you can use:

<div class="source">
<syntaxhighlight lang=bash>
sudo udevadm control --reload-rules
</syntaxhighlight>
</div>

Finally, if you performed all of these steps with the Phidget plugged in to your computer, you will need to unplug and plug the Phidget back in before trying to use usb access without root privileges.

===Starting the WebService at Boot===

If you are tired of starting the webservice on the command line all the time, you can have the webservice start when your system starts, every time.

====User Space====

If you are running a standard Linux machine with an X-server (Unity, KDE) the easiest way to do this is to have the Phidget WebService start when your x server starts.

In this case, the webservice will be running in user space, so your [[#Setting udev Rules|udev rules need to be set up]] for the your user permissions to be able to access the USB ports using libusb.

Within the X-windowing system, there is usually some sort of {{Code|System → Settings/Preferences → Startup}} that you can choose to add programs that start when a user session starts. On Ubuntu you can use Unity to find programs listing "startup" in their names to accomplish the same thing. This will eventually lead you to a graphical tool like this to simply add the {{Code|/usr/bin/phidgetwebservice21}} program:

[[Image:linux_ws_boot.png|400px]]

====As A Service====

You would want to set the boot start of {{Code|phidgetwebservice21}} to be a service if you are running a server, or a headless machine. It is handy any time you need the webservice to be started as a booted, respawning service with a presence in different run levels and for all users.

A service is essentially a program that hangs out in the background, waiting to be used by some incoming task. When the service is needed, the service forks a program to handle that need. Most services that run on your Linux computer already have the ability to fork themselves.

The webservice, however, is just a binary on Linux - {{Code|phidgetwebservice21}} - and so we need a program that handles the forking for us. For this, we use the {{Code|start-stop-daemon}} program to spawn a standalone process for us, or kill it, based on our service-like start, stop, and restart commands.

To do this, we need:
# A script that tells the boot process how to start and handle the webservice (i.e. by using {{Code|start-stop-daemon}})
# A link from that script to the boot list
# An initialization file for the script

First, the script. We will walk through Debian here, both because it is such a common distribution and because it is the distribution that our [{{SERVER}}products.php?product_id=1072 Single Board Computer] runs. But {{Code|init}} is surprisingly diverse on Linux, including everything from a different boot order, to different initialization programs and structure, and even different runlevels.

On Debian (including Ubuntu), the initialization script covers:
* Runlevels that the service should be present on
* Dependencies of the service
* Name of the service and other informative data
* The location of the PIDFILE, which stores the process ID (pid) for later dealing with a spawned instance
* Any configuration file locations
* What to do when the service is given instructions to '''start''', '''stop''', or '''reload'''.

The Debian script we use to start the webservice on the [{{SERVER}}products.php?product_id=1072 Single Board Computer]:

<div class="source">
<syntaxhighlight line start="1" lang=bash>

#!/bin/sh

### BEGIN INIT INFO
# Provides: phidgetwebservice
# Required-Start: $network $remote_fs
# Required-Stop: $network $remote_fs
# Should-Start: avahi
# Should-Stop: avahi
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Phidget WebService
# Description: Phidget WebService for controlling Phidgets over the network.
### END INIT INFO

DESC="Phidget WebService"
NAME=phidgetwebservice
BIN=phidgetwebservice21
DAEMON=/usr/bin/$BIN
PIDFILE=/var/run/$NAME.pid
CFG=/etc/default/$NAME

# Gracefully exit if the package has been removed.
test -x $DAEMON || exit 0

# load config
pws_port="5001"
pws_serverid=""
pws_password=""
[ -f $CFG ] && . $CFG

start() {
[ -z "$pws_port" ] || OPTIONS="-p $pws_port "
[ -z "$pws_password" ] || OPTIONS="$OPTIONS-P $pws_password "

if [ -z "$pws_serverid" ]; then
OPTIONS="$OPTIONS -n $( hostname )"
else
OPTIONS="$OPTIONS -n $pws_serverid"
fi

echo -n "Starting $DESC: "
start-stop-daemon -S -b -q -p $PIDFILE -m -x $DAEMON -- $OPTIONS && echo "OK" || echo "ALREADY RUNNING"
}

stop() {
echo -n "Stopping $DESC: "
start-stop-daemon -K -q -p $PIDFILE -x $DAEMON && echo "OK" || echo "NOT RUNNING"
}

case "$1" in
start)
start
;;
stop)
stop
;;
restart|force-reload)
stop
sleep 1
start
;;
*)
echo "Usage: $0 {start|stop|restart}"
esac

exit 0
</syntaxhighlight>
</div>

Save the script into a file called {{Code|phidgetwebservice}}, and use {{Code|chmod 755}} to make it executable.

Also on Debian, startup service scripts should go in {{Code|/etc/init.d}}, and then put within the appropriate runlevel-numbered folder - by symbolic link. There is a handy tool to do this for you, called {{Code|insserv}}:

<div class="source">
<syntaxhighlight lang=bash>
sudo insserv -d phidgetwebservice
</syntaxhighlight>
</div>

The {{Code|insserv}} program is the program that makes use of the {{Code|### BEGIN INIT INFO...### END INIT INFO}} that appears at the top of the {{Code|phidgetwebservice}} script. Use {{Code|man insserv}} for more information. The {{Code|insserv}} tool handles the mess of finding the right runlevel folders (i.e. the {{Code|rc.d}} numbered folders) and making the appropriate links. You can see what links would be updated by running {{Code|insserv}} with the {{Code|-n}} option, for a dry run.

'''Note:''' When you run {{Code|insserv}}, all of the dependencies for the boot order are re-written. This means that all of the initialization scripts in {{Code|/etc/init.d}} are re-examined. So, you'll probably get a lot of output when you run the command.

Then, you can check that {{Code|phidgetwebservice}} is on the service list with:

<div class="source">
<syntaxhighlight lang=bash>
service --status-all
</syntaxhighlight>
</div>

And you can start it right now without rebooting like this:

[[Image:linux_system_service_start.png]]

The {{Code|service}} command has many options to start and stop services like the phidgetwebservice, try {{Code|man service}} for more information.

At this point, you can follow the client instructions on [[#Using the WebService|using the webservice]] to create a loopback test for the new webservice service that should now be running.

The final piece, for future configuration changes, is that the {{Code|/etc/init.d}} script looks for the file {{Code|/etc/default/phidgetwebservice}} upon starting up. The file is expected to contain the port, server ID, and password for the server side of the webservice. These are also set in the {{Code|phidgetwebservice}} script in {{Code|init.d}}, as you can see from reading the code above, but if you want to change them a lot, you can edit the configuration file rather than changing the {{Code|phidgetwebservice}} script and re-installing by {{Code|insserv}} every time. The configuration file in {{Code|/etc/default/}} should contain the same syntax as that used in the script source above:

<div class="source">
<syntaxhighlight lang=bash>
pws_port="5001"
pws_serverid=""
pws_password=""
</syntaxhighlight>
</div>

===Cross-Compiling with a Custom Toolchain===

This would allow you to have the Phidget libraries compiled to include in code for an embedded device. When developing for an embedded device, you will often write code for it on your 'normal' computer, and then build the code to binary with a different target than the processor in your computer. Many microcontrollers do not have the ability to run a full operating system, and hence cannot compile code natively.

The collection of tools used to create binary code for a separate system is called a ''toolchain''. Compiling the Phidget libraries specifically for an embedded system, and placing them into the path for writing code on top of the libraries is like adding another link in this chain.

You can use the typical {{Code|./configure}} setup for custom build targets:

<div class="source">
<syntaxhighlight lang=bash>
./configure --prefix=toolchain_location --build=this_system --host=target_system
</syntaxhighlight>
</div>

For the Phidget libraries, the {{Code|./configure}} tool works this way as well. You'd use this in the [[#Installing|install the libraries section]] setup. For example, let's say you're building the libraries to develop code for the [{{SERVER}}products.php?product_id=1072 Single Board Computer] as a target. Your system is a standard Linux system (i686-pc-linux-gnu) and the target system for the [[SBC]] is {{Code|arm-linux-gnueabi}}. For this target, you'll need the base of the GNU embedded Debian chain:

<div class="source">
<syntaxhighlight lang=bash>
sudo apt-get install gcc-arm-linux-gnueabi
</syntaxhighlight>
</div>

Then, download the Phidget libraries [[#Quick Downloads|above]] and unpack them into a folder {{Code|phidget_libraries}}. If {{Code|/usr/arm-linux-gnueabi}} is the location of your ARM toolchain (downloaded above in {{Code|gcc-arm-linux-gnueabi}}), type:

<div class="source">
<syntaxhighlight lang=bash>
~/phidget_libraries $> ./configure --prefix=/usr/arm-linux-gnueabi --build=i686-pc-linux-gnu --host=arm-linux-gnueabi
</syntaxhighlight>
</div>

===Linux on Non-Standard Systems===

We occasionally get requests to use Phidgets on Linux systems other than a standard laptop or desktop. One example is the new Raspberry Pi system. Often these systems include USB ports, so the combination makes sense.

Our libraries are installed by building from source, and their main dependency is the {{Code|libusb-dev}} library, so if you can get gcc on your machine (or set up a cross compiler for it) and you can also install the libusb-0.1 development headers, you can probably get Phidgets to work. Of course, we don't offer much support for these systems, so - depending on your system - expect to spend some raw time getting it up and going.

If you're new to the embedded computer thing, keep in mind that for these super basic systems, once you've gotten a power supply, and storage, and put the kernel you want on it, and then spent a couple of days of time getting things working, and more time getting your drivers going, costs add up pretty quickly. If you want a compact system that works right out of the box (and which can use all of our analog sensors in addition to our USB Phidgets), check out our [{{SERVER}}products.php?product_id=1072 Single Board Computer]. Our SBC:
* Has many more USB ports than super-stripped devices, and also has digital and analog ports
* Includes a power supply and can run on batteries easily
* Has a nice amount of RAM, a decent embedded processor, and built-in onboard storage (we've run R, GRASS, and X11 on it)
* Includes installed Debian, working Phidget drivers, and [[Phidget WebService|networked Phidget drivers]] from the moment it ships
* Has access to the full Debian repository including Python, Mono .NET, Ruby, and gcc
* Has a kernel development kit with patch file and instructions for adding new drivers (bluetooth, wireless, and so on)
* Comes with very in-depth documentation and technical support by phone and email
* Etc, etc.
The [[Phidget WebService|networked support]] in particular allows it to work with your cell phone and more.

But if you really do want a raw hobbyist system to tinker with, go for it! We're all nerds here - we've been there too and we certainly understand!

==Common Problems and Solutions==

{{ProblemSolution|Low Speed Phidgets (Max of 8)|Linux will only schedule one low-speed interrupt transfer per millisecond.}}

You can find out the type of your Phidget by attaching it and then running <code><font size=3>dmesg | tail</font></code>, which will display the type of Phidget from your kernel logs, as described above in the [[#Hardware|hardware section]]. The practical consequence of this is if your system has many low speed Phidgets attached, they will each be throttled down. Low speed Phidgets require an interrupt transfer as often as every 8 milliseconds. A Linux system could only have up to 8 of these Phidgets attached.

{{ProblemSolution|Sample Overrun Error|The data read from a program, or the first packet on the WebService, can give a sample overrun error (EEPHIDGET_OVERRUN).}}

Linux only polls data from the analog inputs on Phidgets when you ask it to. So there is some delay between when you open the device and when it actually attaches when data from those inputs are accumulating...and overrunning the buffer. This is simply in the nature of how Linux polls USB - we recommend catching (but ignoring) this one-time initial error.

OS - macOS

2012-06-29T19:58:42Z

Cora:

[[Category:OS]]
{{OSLang|[[File:Icon-Mac-OS.png‎|64x64px|link=]]|On OS X, Phidgets can be either plugged directly into a USB Port or run over a network using the [[#WebService|WebService]].}}
__TOC__
Phidgets are designed to run on '''OS X 10.4 Tiger or newer''', and can run on PPC, 32-bit, and 64-bit systems.

==Quick Downloads==

If this is your first Phidget, we highly recommend working through the Getting Started guide for your specific Phidget device, which may be found on its product page on [{{SERVER}} our main website]. If you already have the Preference Pane Installed and know how to use it, then you've already followed the guide and are ready to learn more about the workings behind the Preference Pane, the Phidget WebService, and more - all specific to OS X.

If you are already a pro, and just want the drivers:

*[{{SERVER}}downloads/libraries/Phidget.dmg OS X Installer Download]
*[{{SERVER}}/Drivers_Info.html#osx Software License]

==Getting Started with OS X==

===Installing===

The Phidget installer will install the core Phidget files onto your system.

To install the libraries, follow these steps:

1. Download the Phidget installer for your system:
*[{{SERVER}}/downloads/libraries/Phidget.dmg OS X Installer]

2. Open up the installer, and double click on {{Code|Phidgets.mpkg}} to install the libraries.

[[File:OSX Install 1.png|link=|alt=OS X Install]]

3. Proceed through the wizard.

[[File:OSX Install 2.png|link=|alt=OS X Install]]

4. Once the installation is complete, you are ready to program with Phidgets. To find out what files got installed, please see [[#Description of Installer files | Description of Installer files]] in the Appendix section.

Proceed onto to the [[#Phidget Preference Pane | next]] section where the Phidget Preference Pane will be discussed.

====Phidget Preference Pane====

The Phidget Preference Pane is a tool to quickly determine whether your system is able to communicate with Phidgets, and also act as a debugging tool.

Once the Phidget libraries are installed using the installer, open up the {{Code|System Preferences}} window.

[[File:OSX System Preferences.png|link=|alt=OS X System Preferences]]

Click on the {{Code|Phidgets}} icon in the {{Code|Other}} section to bring up the Phidgets Preference Pane.

[[File:OSX PreferencePane General.png|link=|alt=OS X PreferencePane General]]

The {{Code|general}} tab shows the list of Phidgets currently physically attached to the computer. You can also view the currently installed Phidget library version. You can double click on a Phidget device to open up an example program for the device.

[[File:OSX PreferencePane Example.png|link=|alt=OS X PreferencePane Example]]

In the above screenshot, the RFID example was opened. These examples are intended for demonstration and debugging purposes. If you have not yet already, please see the '''Getting Started''' guide for your device, which may be found on its product page on [{{SERVER}} our main website].

It is important to keep in mind that when an example Phidget application is opened from the Phidget Preference Pane or opened from any of your Phidget applications that you develop, it holds a lock on the Phidget. This prevents any other program from accessing the Phidget. Please ensure that this example application is closed(the Phidget Preference Pane can still be running) when you are running your own applications.

The next tab is the {{Code|Web Service}} tab, which allows you to control Phidgets over a network.

[[File:OSX PreferencePane Webservice Stopped.png|link=|alt=OS X PreferencePane WebService Stopped]]

Here, you can start and stop the WebService. Details are provided in the [[#WebService | WebService]] section. This screen also tells you whether the Phidget WebService is currently running.

The next tab is the {{Code|Labels}} tab. In this section, you can view the currently assigned labels of any Phidget attached to your computer. It is also possible to set the labels of Phidgets here too. You might want to set a label to a Phidget device because you can refer to it by its label as opposed to its serial number.

[[File:OSX PreferencePane Labels Local.png|link=|alt=OS X PreferencePane WebService Labels Local]]

You can also view the labels of any Phidget connected through the WebService

[[File:OSX PreferencePane Labels Remote.png|link=|alt=OS X PreferencePane WebService Labels Remote]]

The {{Code|Bonjour}} tab gives a list of all currently attached Phidgets that are connected to the WebService. You can also double click on the Phidget to connect to it over the network using one or more computers, but still use the Phidget on the computer it is directly connected to.

[[File:OSX PreferencePane Bonjour.png|link=|alt=OS X PreferencePane Bonjour]]

The last tab is the {{Code|PhidgetSBC}} tab, which displays the complete list of PhidgetSBCs connected to the network.

[[File:OSX PreferencePane PhidgetSBC.png|link=|alt=OS X PreferencePane PhidgetSBC]]

You can double click on the PhidgetSBC to bring up the PhidgetSBC Administration Console log-in page in your default browser.

[[File:PhidgetSBCAdminConsole.PNG|link=|alt=PhidgetSBC Admin Console]]

The PhidgetSBC Administration Console is where you can go to configure the PhidgetSBC. For more details, please see the [[1072 0 - Getting Started | PhidgetSBC]] section.

===Checking===

To confirm the libraries were installed and work correctly, you can check both the hardware and software components of the interface. It is worth checking the software side first, because if it works then you know the hardware side is also okay.

====Software====

If you have the Phidgets library installed on your system, you can verify that the software component is working by seeing if the Phidget device is listed in the General tab of the Phidget Preference Pane.

[[File:OSX PreferencePane General.png ‎|link=|alt=OS X Preference Pane General]]

The above screenshot shows that a PhidgetRFID and a PhidgetInterfaceKit are attached to the computer. If you see your Phidget in the list, you can continue to the [[#Programming Languages | programming languages]] section to learn more. If you are not able to see that the Phidget is in the list, there may be a hardware issue. Please see the [[#Hardware| hardware]] section for more details.

====Hardware====

You can verify that your computer detects that the Phidget is plugged in through a USB connection by going to the OS X System Profiler. You can access the System Profiler by selecting {{Code|About This Mac}} under the Apple icon.

[[File:OSX About This Mac.png‎|link=|alt=OS X About This Mac]]

The new window will open up.

[[File:OSX More Info.png|link=|alt=OS X More Info]]

Select {{Code|More Info}}. The System Profiler will show up. In the USB section, you will be able to find all connected USB devices.

[[File:OSX USB Devices.png ‎|link=|alt=OS X Attached USB Devices]]

In the above screenshot, The PhidgetInterfaceKit and PhidgetRFID are connected to the USB ports.

If you don't see the Phidget in the list, then take a look at the [[#Troubleshooting|troubleshooting]] section below, as well as the '''Communications''' section of our [[General Troubleshooting#Communications Troubleshooting|general troubleshooting page]].

====Troubleshooting====

If the example programs '''do not''' work but USB '''does''' work (i.e. your computer can consistently see the device in the [[#Hardware|hardware]]), take a moment to check the basics:
* You are using OS X 10.4 or newer.
* No other programs, drivers, or processes are using that USB port in software
* The Phidget libraries are the latest version (visit the [[#Quick Downloads| quick downloads section]] to download them)

* Check the [[#Common Problems and Solutions|common problems]] section below, some specific combinations can cause problems

If your problem doesn't seem to be fixed by these steps, make sure that the Phidget is seen '''consistently''' by USB (if it is erratic, try our [[General Troubleshooting|general troubleshooting guide]]). If you are still having problems after using the troubleshooting guide, please [[Contact Us|ask us]]!

==Programming Languages==
Phidgets’ philosophy is that you do not have to be an electrical engineer in order to do projects that use devices like sensors, motors, motor controllers, and interface boards. All you need to know is how to program.

After you have installed the drivers above, you should pick a programming language, install libraries, and run the examples for that specific language. You can learn more about what is needed to program in a particular language by choosing the language of your preference below. If you need help choosing a language, please look at the [[Software Overview#Language Support |language comparison table]].

We recommend the following languages for OS X:
* [[Language - Applescript|AppleScript]]
* [[Language - C/C++|C/C++]]
* [[Language - C Sharp|C# (Using Mono)]]
* [[Language - Cocoa | Cocoa]]
* [[Language - Flash AS3 | Flash AS3]]
* [[Language - Flex AS3 | Flex AS3]]
* [[Language - LiveCode | LiveCode]]
* [[Language - Java | Java]]
* [[Language - Max/MSP|Max/MSP]]
* [[Language - Python | Python]]
* [[Language - Ruby|Ruby]]

You can also use these languages, but they do not support [[General Phidget Programming#Event Driven Code | event driven code]], and must use [[General Phidget Programming#Logic Code | logic code]] only:

*[[Language - MATLAB|MATLAB]]
*[[Language - Simulink|Simulink]]

==WebService==

The Phidget WebService allows you to remotely control a Phidget over a network.

Drivers for the Phidget WebService on OS X are already included in the [[#Quick Downloads | Drivers]] above. If you see the Phidget Preference Pane in System Preferences, then you already have the WebService drivers installed.

There are two ways that you can connect to a Phidget hosted on another computer. The first method is by using the IP address/host name and port of the host computer. The second method makes the use of [http://en.wikipedia.org/wiki/Multicast_DNS mDNS], which allows Phidgets to be found and opened on the network by a server id instead of an IP address/host name. When using a server id, both the client and server will need to be running an implementation of zero configuration networking. The Phidget WebService takes advantage of [http://www.apple.com/support/downloads/bonjourforwindows.html Bonjour] software, which is built-in to OS X. It is a tool developed by Apple to locate devices, such as Phidgets, on a network.

This section helps you install, check, and use the WebService on Windows, but we also have an overview of the [[Phidget WebService]] in general.

===Turning the WebService On and Off===

There are two methods that can be used to turn the WebService on and off. The first method is through the Phidget Preference Pane. In the {{Code|WebService}} tab, you can start or stop the WebService. You can also choose to have the WebService start up automatically upon system boot up by selecting the {{Code|Start Automatically}} checkbox.

[[File:OSX PreferencePane Webservice Stopped.png|link=|alt=OS X PreferencePane WebService]]

The second method of turning the WebService on and off is through command line. After using our installer, the WebService utility is automatically installed in {{Code|/usr/bin/phidget21webservice}}.

You can get command line help with {{Code|phidgetwebservice21}} using the -h option:

<div class="source">
<syntaxhighlight lang=bash>
phidgetwebservice21 -h
</syntaxhighlight>

<syntaxhighlight lang=text>
'phidgetwebservice21' is a Phidget and Dictionary server from Phidgets Inc. See www.phidgets.com for more information.
Usage: phidgetwebservice21 [OPTION]
All parameters are optional. The default parameters are: port=5001, ServerName=(Computer Name) and no password

Options:
-p Port
-n Server Name
-P Password
-v Debug mode
-h Display this help
</syntaxhighlight>
</div>

Mapping out which command line options to which Phidget Preference Pane option is as follows:

-p: {{Code|Port}} field

-n: {{Code|ServerID}} field

-P: {{Code|Password}} field

-v: Not supported under the Phidget Preference Pane

To find the defaults used by {{Code|phidget21webservice}}, the command line is the fastest way to learn the default server name and IP address of your computer:
*For the default server name, use {{Code|hostname}} on the command line.
*For your IP address, use {{Code|ifconfig -a}} on the command line.
**A line in the return text, under your main internet connection (usually {{Code|eth0}}) will say something like {{Code|inet addr:192.168.3.178}}, which is your IP.

Here are some usage examples:

To start the WebService with default parameters:
<div class="source">
<syntaxhighlight lang=bash>
phidgetwebservice21
</syntaxhighlight>
</div>

To start the WebService with a server name of {{Code|myServer}}:
<div class="source">
<syntaxhighlight lang=bash>
phidgetwebservice21-n myServer
</syntaxhighlight>
</div>

To stop the WebService, simply close the command line window or press {{Code|Control}} and {{Code|c}} at the same time in the command line window.

===Using the WebService===

To use a Phidget over the WebService, you'll want to:
* Have two different computers connected to the same network. We will call the computer that has the Phidget directly connected to the USB port the host. The client will be the computer that runs a Phidget application to connect to the Phidget attached to the host. Please note that if you only have a single computer, you can also connect to the Phidget over the WebService. The computer will simply act as both a host and client. This will allow you to bypass the [[General Phidget Programming # Details for Open() | one application per Phidget limitation]].

* Start the WebService on the computer that directly connects to the Phidget
* Run your program on the remote computer that will control the Phidget over the network

The easiest way to test these steps on OS X is to set up the WebService and run the Phidget program on the client. Please follow these steps:

1. On the host, open up the Phidget Preference Pane and traverse to the {{Code|Web Service}} tab.

[[File:OSX PreferencePane Webservice Stopped.png |link=|alt=OS X Preference Pane WebService]]

2. Leave all fields the way they are, and click on {{Code|Start WebService}} to run the WebService.

3. You can determine that the WebService is running by looking at the status on the right side.

[[File:OSX PreferencePane Webservice Running.png|link=|alt=OS X PreferencePane WebService Running]]

4. Ensure that the Phidget is plugged in to the host.

5. On the client's Phidget Preference Pane, open up the {{Code|Bonjour}} tab. You will see the Phidget that is plugged into the host as one of the entries listed. Double click it to open the example application.

[[File:OSX PreferencePane Bonjour.png ‎‎ |link=|alt=OS X PreferencePane Bonjour.png ‎]]

6. The example application will open up, and you will be able to communicate with the Phidget over the WebService.

[[File:OSX PreferencePane Example.png ‎ |link=|alt=OS X PreferencePane Example]]

7. You can confirm that the WebService was indeed behind this exchange by terminating the WebService process while still allowing the remote program to run. On the host's Phidget Preference Pane, traverse to the {{Code|WebService}} tab. Hit {{Code|Stop WebService}} to terminate the WebService.

[[File:OSX PreferencePane Webservice Running.png|link=|alt=OS X PreferencePane WebService Running]]

8. Take a look at the example application on the client. Since the application can no longer connect to the WebService, there is nothing attached.

[[File:OSX PreferencePane Example Stopped.png |link=|alt=OS X PreferencePane Example Stopped]]

===Debugging the WebService===

In addition to enabling [[General Phidget Programming#Logging|logging]] in your Phidget code, you can get additional debugging information from the WebService itself. This additional debugging can only be enabled from the command line approach to start the WebService. Debug information is enabled by specifying the {{Code|-v}} option:

<div class="source">
<syntaxhighlight lang=bash>
phidgetwebservice21 -v -n "myServer"
</syntaxhighlight>
</div>

The debugging information will be shown as output in the command line console.

==Advanced Uses==

==Appendix==

===Description of Installer files===

Here is the list of files and their description for each file the installer puts onto your system.
===Description of Library files===

This section will explain the files that were placed onto your system as part of the installation process.
* <b>{{Code|Phidget21.framework}}</b> contains the actual Phidget library, which is used at run-time. It is placed into {{Code|/Library/Frameworks}}.
* <b>{{Code|Phidget.kext}}</b> is the kernel extension. It is placed into {{Code|/System/Library/Extensions}}.
* <b>{{Code|libphidget21.jnilib}}</b> is the JNI library for Java. It is placed into {{Code|/Library/Java/Extensions}}.
* <b>{{Code|Phidgets.prefpane}}</b> is the Phidgets Preference Pane. It is placed into {{Code|/Library/PreferencePanes}}.
* <b>{{Code|phidgetwebservice21}}</b> is the Phidget WebService. It is placed into {{Code|/usr/bin}}.
* <b>{{Code|PhidgetsOSA.app}}</b> is the the Phidgets agent for AppleScript. It is placed into {{Code|/Library/ScriptingAdditions}}.

==Common Problems and Solutions==

None, yet.

Language - C

2012-06-29T19:53:19Z

Cora: /* Quick Downloads */

[[Category:Language]]
{{OSLang|[[File:icon-C++.png|link=|alt=C/C++|64x64px]]|C++ is a general purpose, cross-platform programming language with a vast user base.}}
__TOC__

==Introduction==

{{LanguageSupport|C/C++|the complete Phidget API, including events|all Phidget devices.|Windows 2000/XP/Vista/7(environments include [[#Visual Studio | Visual Studio]], [[#Borland | Borland]], [[#Cygwin/MinGW | Cygwin, and MinGW]]), [[#Windows CE | Windows CE]], [[#OS X | OS X]], and [[#Linux | Linux]]|}}

==Quick Downloads==
{{QuickDownloads|C/C++|
{{APIQuickDownloads|{{SERVER}}/documentation/Phidget21_C_Doc.zip}}
{{ExtraAPIQuickDownloads|{{SERVER}}/documentation/web/cdoc/index.html|HTML Version of}}|
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/VCpp.zip Visual Studio 2005/2008/2010|}}
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz Generic|}}|
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/libraries/phidget21bcc.zip|Borland(Windows)|}}
{{WindowsQuickDownloads}}
{{MacQuickDownloads}}
{{LinuxQuickDownloads}}
}}

==Getting started with C/C++==

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

Instructions are divided up by operating system. Choose:
*[[#Windows(2000/XP/Vista/7)|Windows 2000 / XP / Vista / 7]]
*[[#OS X |OS X]]
*[[#Linux | Linux]] (including PhidgetSBC)

==Windows (2000/XP/Vista/7)==

===Description of Library Files===
C/C++ programs on Windows depend on three files, which the installers in [[#Libraries and Drivers|Quick Downloads]] put onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. By default, it is placed in {{Code|C:\Windows\System32}}.
* <b>{{Code|phidget21.lib}}</b> is used by your compiler to link to the dll. Your compiler has to know where this file is, by default our installer puts {{Code|phidget21.lib}} into {{Code|C:\Program Files\Phidgets}}, so you can either point your compiler to that location, or copy and link to it in a directory for your project workspace. {{Code|phidget21.lib}} is written to be compatible with most compilers - but your specific compiler may need a different format. Check our documentation for your specific compiler for details. Please note that we provide versions of the {{Code|phidget21.lib}} that are specifically optimized for 32-bit or 64-bit systems. If you are using a 64 bit versions of Windows, the {{Code|phidget21.lib}} is placed in {{Code|C:\Program Files\Phidgets}}; The 32 bit version of {{Code|phidget21.lib}} is placed in {{Code|C:\Program Files\Phidgets\x86}}.
* <b>{{Code|phidget21.h}}</b> lists all the Phidget API function calls available to your code. Your compiler also has to know where this file is. By default, our installer puts {{Code|phidget21.h}} into {{Code|C:\Program Files\Phidgets}} so 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 all three [{{SERVER}}/downloads/libraries/phidget21-x86.zip files] and manually install them where you want; refer to our [[OS_-_Windows#Manual_File_Installation | Manual Installation Instructions]].

Running the examples and writing your own code can be fairly compiler-specific, so we include instructions for [[#Visual Studio 2005/2008/2010 | Visual Studio 2005/2008/2010]], [[#Visual Studio 2003 | Visual Studio 2003]], [[#Visual Studio C++ 6.0 | Visual Studio 6]], [[#Borland| Borland]], [[#Cygwin/MinGW | Cygwin/MinGW]], and [[#Dev C++ | Dev C++]].

===Visual Studio===

C++/CLI (which used to be called Managed C++) is very different from mainstream C/C++. If you must use C++/CLI, consider calling the Phidget .NET library, instead of the C API normally used from C/C++. We have no documentation for using C++/CLI.

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.

====Visual Studio 2005/2008/2010====

=====Use Our Examples=====

To run the examples, you first download the [{{SERVER}}/downloads/examples/VCpp.zip examples] and unpack them into a folder. To load all projects in Visual Studio, go to File → Open → Project → Solution, and open {{Code|Visual Studio Phidgets Examples.sln}} in the {{Code|VCpp}} folder of the examples.

Since the examples were written in Visual Studio 2005, if you are opening the examples in Visual Studio 2008/2010, you will need to go through the Visual Studio Conversion Wizard to open and convert the 2005 project.

[[File:VS2005 Conversion Wizard.PNG|link=|alt=Conversion Wizard]]

This will load all of the examples available for C/C++. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

Start by setting the {{Code|HelloWorld}} project as your start up project.

[[File:VS2005 StartUp Project.PNG|link=|alt=Start Up Project]]

To run the example, click on Debug → Start Debugging. Please note that the projects, by default try to find the {{Code|phidget21.h}} and {{Code|phidget21.lib}} in the {{Code|$(SystemDrive)\Program Files\Phidgets}}. If you have these files installed in another location, please change the path to the file's location accordingly. Please see the [[#Write Your Own Code | Write Your Own Code]] section for details.

[[File:VS2005 Run.PNG|link=|alt=Run]]

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:VS2005 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget C/C++ library. To begin:

1. Generate a new Visual C++: Win32 Console Application project with a descriptive name such as PhidgetTest.

[[File:VS2005 New Project.PNG|link=|alt=New Project]]

2. Next, select Console Application.

[[File:VS2005 New Project 2.PNG|link=|alt=New Project]]

3. Open the project properties window.

4. Navigate to Configuration Properties → C/C++.

5. Add {{Code|"C:\Program Files\Phidgets"}} to the additional directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Header.PNG|link=|alt=Header File]]

6. Navigate to Configuration Properties → Linker → Input.

7. Edit the additional dependencies and add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}}. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Library.PNG|link=|alt=Library File]]

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

Then, in your code, you will need to include the Phidget C/C++ library:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

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

====Visual Studio 2003====

=====Use Our Examples=====

1. Start by downloading the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples]. You can import these examples into a Visual Studio 2003 C++ project. Afterwards, unpack them into a folder. Here, you can find example programs for all the devices. You will need this example source code to be copied into your C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. A new project will need to be created. Generate a new Visual C++ empty project(.NET) with a descriptive name such as HelloWorld.

[[File:VS2003 New Project.PNG|link=|alt=New Project]]

3. Create a new C++ file by adding a new item to the source files folder.

[[File:VS2003 New File.PNG|link=|alt=New File]]

[[File:VS2003 New File 2.PNG|link=|alt=New File]]

4. An empty C++ file will pop up. Please copy and paste the contents of the {{Code|HelloWorld.c}} program into here.

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

5. Next, the project setting needs to be set up. Open the project properties window.

6. Navigate to Configuration Properties → C/C++.

7. Add {{Code|"C:\Program Files\Phidgets"}} to the additional include directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2003 Header.PNG|link=|alt=Header File]]

8. Navigate to Configuration Properties → Linker → Input.

9. Add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}} to the additional dependencies field. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2003 Library.PNG|link=|alt=Library File]]

10. Now, you can run the example. Click on Debug → Start Without Debugging.

[[File:VS2003 Run.PNG|link=|alt=Run]]

11. 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:VS2003 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 2 | Use Our Examples]] section for instructions.

Then, in your code, you will need to include the Phidget C/C++ library:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

====Visual Studio C++ 6.0====

=====Use Our Examples=====

1. Download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Here, you can find example programs for all the devices. You will need this example source code to be copied into your C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. Next, a new project will need to be created. Generate a new Win32 Console Application project with a descriptive name such as HelloWorld.

[[File:VS6 New Project.PNG|link=|alt=New Project]]

3. Create an empty project.

[[File:VS6 New Project 2.PNG|link=|alt=New Project]]

4. Next, the project settings needs to be set up. Navigate to Project → Settings → C/C++ → Preprocessor.

5. Add {{Code|C:\Program Files\Phidgets}} to the additional include directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS6 Header.PNG|link=|alt=Header File]]

6. Navigate to Project → Settings → Link → Input → Additional library Path.

7. Add {{Code|phidget21.lib}} to the object/library modules field.

8. Add {{Code|C:\Program Files\Phidgets}} to the additional library path. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS6 Library.PNG|link=|alt=Library File]]

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

To import the example program into your project, please:

9. Create a new C++ file by navigating to File → New → Files → C++ Source File and enter a descriptive name such as HelloWorld.

[[File:VS6 New File.PNG|link=|alt=New File]]

10. An empty C++ file will pop up. Please copy and paste the contents of the {{Code|HelloWorld.c}} program here.

[[File:VS6 Source.PNG|link=|alt=Source Code]]

11. Now, you can run the example. Click on Build → Execute.

[[File:VS6 Run.PNG|link=|alt=Run]]

12. 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:VS6 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 3 | Use Our Examples]] section for instructions.

In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 3 | Use Our Examples]] section.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===Borland===

====Use Our Examples====

In addition to running one of the two [[#Libraries and Drivers:| Windows Installers]] above (which you probably already have if you worked through the ''Getting Started'' page for your device), you will need the [{{SERVER}}/downloads/libraries/phidget21bcc.zip Borland C++ Libraries]. {{Code|phidget21bcc.lib}} is typically placed in {{Code|C:\Program Files\Phidgets}}, but you are free to place it in any directory you wish.

After installing the Phidget C/C++ library, you're ready to download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples] and run the examples.

Afterwards, unpack the examples. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example. Locate the {{Code|HelloWorld.c}} file and type the following to compile the file and link the Phidget C/C++ library:

To compile, link the Phidget C/C++ library and build a binary executable, enter the following in a command line prompt in the directory with {{Code|HelloWorld.c}}:
<div class="source">
<syntaxhighlight lang=bash>
bcc32 -eHelloWorld -I"C:\Program Files\Phidgets" -L"C:\Program Files\Phidgets" phidget21bcc.lib HelloWorld.c
</syntaxhighlight>
</div>

It is assumed that {{Code|phidget21bcc.lib}} and {{Code|phidget21.h}} are placed in {{Code|C:\Program Files\Phidgets}}. If the files are placed in another location, please adjust the paths to both of the file's location accordingly.

In this case, {{Code|HelloWorld.c}} would be the '''.c''' file specific to your device. After using {{Code|bcc32}}, you will have an executable named {{Code|HelloWorld}} that you can run.

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:Borland HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

====Write Your Own Code====

When writing your code from scratch, you start it as you would any C/C++ code with Borland. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the examples [[#Use Our Examples 4 |above]].

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===GCC on Windows===

====Cygwin/MinGW====

=====Use Our Examples=====

Download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Afterwards, unpack the examples. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example. Locate the {{Code|HelloWorld.c}} file and type the following to compile the file and link the Phidget C/C++ library in a command line prompt:

<b>Cygwin</b>

<div class="source">
<syntaxhighlight lang=bash>
gcc example.c -o HelloWorld -I"/cygdrive/c/Program Files/Phidgets" -L"/cygdrive/c/Program Files/Phidgets" -lphidget21
</syntaxhighlight>
</div>

<b>MinGW</b>
<div class="source">
<syntaxhighlight lang=bash>
gcc example.c -o HelloWorld -I"C:\Program Files\Phidgets" -L"C:\Program Files\Phidgets" -lphidget21
</syntaxhighlight>
</div>

After using gcc, you will have an executable named {{Code|HelloWorld}} that you can run.
It is assumed that {{Code|phidget21.h}} and {{Code|phidget21.lib}} are placed in {{Code|C:\Program Files\Phidgets}}. If the files are placed in another location, please adjust the paths to the file's location accordingly.

After using {{Code|gcc}}, you will have an executable named {{Code|HelloWorld}} that you can run.

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:C MinGW HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

=====Write Your Own Code=====

When writing your code from scratch, you start it as you would any C/C++ code with Cygwin/MinGW in your favourite text editor. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 5| Use Our Examples]] section above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===Dev C++===

=====Use Our Examples=====

1. Download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Here, you can find example programs for all the devices. {{FindYourDevice}} You will need this example source code to be copied into your Dev C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. In order to control Phidgets with Dev C++, we will use the {{Code|reimp}} tool to convert the {{Code|phidget21.lib}} to a format that Dev C++ accepts. Download the [http://sourceforge.net/projects/mingw/ reimp tool]. Reimp is part of MinGW, a minimal UNIX emulator for Windows, and it is specifically within the mingw-utils package. You can check MinGW's [http://sourceforge.net/project/shownotes.php?release_id=126568 release notes] to ensure Reimp is in the version you are using.

3. Open up command line and traverse to the directory containing the reimp tool. Type the following command to create {{Code|libphidget21.a}}.
<div class="source">
<syntaxhighlight lang=bash>
reimp.exe "C:\Program Files\Phidgets\phidget21.lib"
</syntaxhighlight>
</div>
The command above assumes that the {{Code|phidget21.lib}} is in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly. Please note that the 64 bit version of {{Code|phidget21.lib}} is not supported on Dev C/C++. Please use the 32 bit version of {{Code|phidget21.lib}}.

4. Place {{Code|libphidget21.a}} in {{Code|<Dev-Cpp Install Directory>/lib}}.

5. Next, a new project will need to be created. Generate a new console application with a descriptive name such as PhidgetTest. Please select C as the project type.

[[File:DevC New Project.PNG|link=|alt=New Project]]

6. Next, the project settings needs to be set up. Navigate to Project Options → Directories → Include Directories.

7. Add a new path to {{Code|C:\Program Files\Phidgets}}. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:DevC Header.PNG|link=|alt=Header File]]

8. Navigate to Project Options → Parameters → Linker.

9. Add {{Code|-lphidget21}} to the field. This step will find the {{Code|libphidget21.a}} file in {{Code|<Dev-Cpp Install Directory>/lib}}.

[[File:DevC Library.PNG|link=|alt=Library File]]

10. To import the {{Code|HelloWorld}} program into your project, please open up {{Code|main.c}} in the editor.

11. An empty C file will pop up. Please copy and paste the contents of the example program.

[[File:DevC Source.PNG|link=|alt=Source Code]]

12. Now, you can run the example. Click on Execute → Compile & Run.

[[File:DevC Run.PNG|link=|alt=Run]]

13. 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:DevC HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 6 | Use Our Examples]] section for instructions.

In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the [[#Use Our Examples 6 | examples]] above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

==OS X==

C/C++ has excellent support on OS X through the gcc compiler.

The first step in using C/C++ on Mac is to install the Phidget C/C++ library. Compile and install them as explained on the Getting Started guide for your device, which you can find on its product page on [{{SERVER}} our main website]. Then, the [[OS - OS X#Description of Library files|OS - OS X]] page also describes the different Phidget files, their installed locations, and their roles.

===Use Our Examples===

After installing the main Phidget library for OS X as above, you're ready to download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples]. Afterwards, unzip the file. To run the example code, you'll need to find the source code ''for your specific device''. Then, compile the code under your platform and run it.

To compile, link the Phidget C/C++ library, and build an executable binary on OS X, do (for example, depending on the Headers location):

<div class="source">
<syntaxhighlight lang=bash>

gcc example.c -o example -framework Phidget21 -I/Library/Frameworks/Phidget21.framework/Headers
</syntaxhighlight>
</div>

After using gcc, you will have an executable named {{Code|example}} that you can run.

===Write Your Own Code===

When writing your code from scratch, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 7|Use Our Example]] section above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples. Even more help and references are provided from there.

==Linux==

C/C++ has support on Linux through the gcc compiler.

The first step in using C/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.

===Use Our Examples===

After installing the Phidget libraries for Linux as above, you're ready to download and run the examples:
*[{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz Generic C/C++ Examples]

To run the example code, you'll need to download and unpack the examples, and then find the source code for your device. {{FindYourDevice}} You can also use the HelloWorld program, which a basic program that can run with any Phidget. Then, compile the code under your platform and run it. When compiling, you need to link to the Phidget library.

To compile, link the Phidget libraries and build a binary executable on Linux, do the following in a terminal in the directory with {{Code|example.c}}:

<div class="source">
<syntaxhighlight lang=bash>
gcc example.c -o example -lphidget21
</syntaxhighlight>
</div>

In this case, {{Code|example.c}} would be the '''.c''' file specific to your device. After using gcc, you will have an executable named {{Code|example}} that you can run.

On Linux, if you have not set up [[OS_-_Linux#Setting_udev_Rules | your udev rules for USB access]], you will need to run the program '''as root''':

<div class="source">
<syntaxhighlight lang=bash>
sudo ./example
</syntaxhighlight>
</div>

===Write Your Own Code===

When writing your code from scratch, you start it as you would any C/C++ code on Linux, such as within a text editor like Emacs, Vi, Gedit, or Kate. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>
#include <phidget21.h>
</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the examples above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

==Windows CE==

===Description of Library Files===
C/C++ programs on Windows CE depend on the following files, which the Windows CE installer puts onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. It is placed in {{Code|\Windows}}.
* <b>{{Code|PhidgetWebService21.exe}}</b> is used to control Phidgets remotely across a network using the [[#WebService | PhidgetWebService]]. It can be placed anywhere on the system.
* <b>{{Code|phidget21.lib}}</b> is used by your compiler to link to the dll. Your compiler has to know where this file is.
* <b>{{Code|phidget21.h}}</b> lists all the Phidget API function calls available to your code. Your compiler also has to know where this file is.
* <b>{{Code|phidget.dll}}</b> is the Phidgets kernel driver. It is placed in {{Code|\Windows}}.

===Visual Studio 2005/2008/2010===

=====Use Our Examples=====

Currently, we have no example code for C/C++ on Windows CE. However, set up is very much the same as what it would be with [[#Visual Studio 2005/2008/2010 |Visual Studio 2005/2008/2010]] in Windows. The {{Code|phidget21.h}} and {{Code|phidget21.lib}} can be downloaded [{{SERVER}}/downloads/libraries/Phidget21-wincedevel.zip here].

=====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 development environment to properly link the Phidget C/C++ library. To begin:

1. Generate a new Visual C++: Win32 Smart Device project with a descriptive name such as PhidgetTest.

[[File:WinCE VS C NewProject 1.PNG|link=|alt=New Project]]

2. Select {{Code|Next}}.

[[File:WinCE VS C NewProject 2.PNG|link=|alt=New Project]]

3. Select the SDK(s) that you want to code against and elect {{Code|Next}}.

[[File:WinCE VS C NewProject 3.PNG|link=|alt=SDKs]]

4. Create a console application and select {{Code|Next}}.

[[File:WinCE VS C NewProject 4.PNG|link=|alt=Create Console Application]]

3. Open the project properties window.

4. Navigate to Configuration Properties → C/C++.

5. Add {{Code|"C:\Program Files\Phidgets"}} to the additional directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Header.PNG|link=|alt=Header File]]

6. Navigate to Configuration Properties → Linker → Input.

7. Edit the additional dependencies and add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}}. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Library.PNG|link=|alt=Library File]]

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

Then, in your code, you will need to include the Phidget C/C++ library:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

The same [[#Follow the Examples|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.

Your main reference for writing C code will be our C/C++ API information, with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|both of which are available in C/C++|[{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++ API]}}

===Example Flow===

{{ExamplePseudocode|In C/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 an object with the {{Code|CPhidgetSpatialHandle}} type, and then initializing it using the {{Code|CPhidgetSpatial_create function}}. The examples show how to do this and other API functions.<br><br>
Other C calls follow a similar syntax - {{Code|CPhidgetXXX_function}}, where XXX is the name of your device, and function is an action available from the API for your specific Phidget.|
[{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++ API]}}

===Code Snippets===

When programming in C/C++, you're in luck. All of our code snippet examples on our [[General Phidget Programming]] page are in both C++ and Java. Therefore, we do not include any here, because that page is much more in-depth, and you won't have to have two pages open at once. So head over there, and start writing code!

==Common Problems and Solutions/Workarounds==

===Issue: I am using a non US-English version of Windows, and the Visual C/C++ examples run into a linker error===
Affected Operating Systems: '''Windows'''

The example projects, by default finds the {{Code|phidget21.h}} and {{Code|phidget21.lib}} in ${SystemDrive}\Program Files\Phidgets. If you are using a non US-English version of Windows, the Phidget drivers may be installed into a different location. To resolve, you will have to modify the paths to these two files. For instructions, please see your environment/compiler section.

Language - C

2012-06-29T19:49:14Z

Cora: /* Quick Downloads */

[[Category:Language]]
{{OSLang|[[File:icon-C++.png|link=|alt=C/C++|64x64px]]|C++ is a general purpose, cross-platform programming language with a vast user base.}}
__TOC__

==Introduction==

{{LanguageSupport|C/C++|the complete Phidget API, including events|all Phidget devices.|Windows 2000/XP/Vista/7(environments include [[#Visual Studio | Visual Studio]], [[#Borland | Borland]], [[#Cygwin/MinGW | Cygwin, and MinGW]]), [[#Windows CE | Windows CE]], [[#OS X | OS X]], and [[#Linux | Linux]]|}}

==Quick Downloads==
{{QuickDownloads|C/C++|
{{APIQuickDownloads|{{SERVER}}/documentation/Phidget21_C_Doc.zip}}
{{ExtraLibraryQuickDownloads|{{SERVER}}/documentation/web/cdoc/index.html|HTML Version of API|}}|
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/VCpp.zip Visual Studio 2005/2008/2010|}}
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz Generic|}}|
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/libraries/phidget21bcc.zip|Borland(Windows)|}}
{{WindowsQuickDownloads}}
{{MacQuickDownloads}}
{{LinuxQuickDownloads}}
}}

==Getting started with C/C++==

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

Instructions are divided up by operating system. Choose:
*[[#Windows(2000/XP/Vista/7)|Windows 2000 / XP / Vista / 7]]
*[[#OS X |OS X]]
*[[#Linux | Linux]] (including PhidgetSBC)

==Windows (2000/XP/Vista/7)==

===Description of Library Files===
C/C++ programs on Windows depend on three files, which the installers in [[#Libraries and Drivers|Quick Downloads]] put onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. By default, it is placed in {{Code|C:\Windows\System32}}.
* <b>{{Code|phidget21.lib}}</b> is used by your compiler to link to the dll. Your compiler has to know where this file is, by default our installer puts {{Code|phidget21.lib}} into {{Code|C:\Program Files\Phidgets}}, so you can either point your compiler to that location, or copy and link to it in a directory for your project workspace. {{Code|phidget21.lib}} is written to be compatible with most compilers - but your specific compiler may need a different format. Check our documentation for your specific compiler for details. Please note that we provide versions of the {{Code|phidget21.lib}} that are specifically optimized for 32-bit or 64-bit systems. If you are using a 64 bit versions of Windows, the {{Code|phidget21.lib}} is placed in {{Code|C:\Program Files\Phidgets}}; The 32 bit version of {{Code|phidget21.lib}} is placed in {{Code|C:\Program Files\Phidgets\x86}}.
* <b>{{Code|phidget21.h}}</b> lists all the Phidget API function calls available to your code. Your compiler also has to know where this file is. By default, our installer puts {{Code|phidget21.h}} into {{Code|C:\Program Files\Phidgets}} so 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 all three [{{SERVER}}/downloads/libraries/phidget21-x86.zip files] and manually install them where you want; refer to our [[OS_-_Windows#Manual_File_Installation | Manual Installation Instructions]].

Running the examples and writing your own code can be fairly compiler-specific, so we include instructions for [[#Visual Studio 2005/2008/2010 | Visual Studio 2005/2008/2010]], [[#Visual Studio 2003 | Visual Studio 2003]], [[#Visual Studio C++ 6.0 | Visual Studio 6]], [[#Borland| Borland]], [[#Cygwin/MinGW | Cygwin/MinGW]], and [[#Dev C++ | Dev C++]].

===Visual Studio===

C++/CLI (which used to be called Managed C++) is very different from mainstream C/C++. If you must use C++/CLI, consider calling the Phidget .NET library, instead of the C API normally used from C/C++. We have no documentation for using C++/CLI.

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.

====Visual Studio 2005/2008/2010====

=====Use Our Examples=====

To run the examples, you first download the [{{SERVER}}/downloads/examples/VCpp.zip examples] and unpack them into a folder. To load all projects in Visual Studio, go to File → Open → Project → Solution, and open {{Code|Visual Studio Phidgets Examples.sln}} in the {{Code|VCpp}} folder of the examples.

Since the examples were written in Visual Studio 2005, if you are opening the examples in Visual Studio 2008/2010, you will need to go through the Visual Studio Conversion Wizard to open and convert the 2005 project.

[[File:VS2005 Conversion Wizard.PNG|link=|alt=Conversion Wizard]]

This will load all of the examples available for C/C++. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

Start by setting the {{Code|HelloWorld}} project as your start up project.

[[File:VS2005 StartUp Project.PNG|link=|alt=Start Up Project]]

To run the example, click on Debug → Start Debugging. Please note that the projects, by default try to find the {{Code|phidget21.h}} and {{Code|phidget21.lib}} in the {{Code|$(SystemDrive)\Program Files\Phidgets}}. If you have these files installed in another location, please change the path to the file's location accordingly. Please see the [[#Write Your Own Code | Write Your Own Code]] section for details.

[[File:VS2005 Run.PNG|link=|alt=Run]]

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:VS2005 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget C/C++ library. To begin:

1. Generate a new Visual C++: Win32 Console Application project with a descriptive name such as PhidgetTest.

[[File:VS2005 New Project.PNG|link=|alt=New Project]]

2. Next, select Console Application.

[[File:VS2005 New Project 2.PNG|link=|alt=New Project]]

3. Open the project properties window.

4. Navigate to Configuration Properties → C/C++.

5. Add {{Code|"C:\Program Files\Phidgets"}} to the additional directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Header.PNG|link=|alt=Header File]]

6. Navigate to Configuration Properties → Linker → Input.

7. Edit the additional dependencies and add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}}. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Library.PNG|link=|alt=Library File]]

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

Then, in your code, you will need to include the Phidget C/C++ library:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

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

====Visual Studio 2003====

=====Use Our Examples=====

1. Start by downloading the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples]. You can import these examples into a Visual Studio 2003 C++ project. Afterwards, unpack them into a folder. Here, you can find example programs for all the devices. You will need this example source code to be copied into your C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. A new project will need to be created. Generate a new Visual C++ empty project(.NET) with a descriptive name such as HelloWorld.

[[File:VS2003 New Project.PNG|link=|alt=New Project]]

3. Create a new C++ file by adding a new item to the source files folder.

[[File:VS2003 New File.PNG|link=|alt=New File]]

[[File:VS2003 New File 2.PNG|link=|alt=New File]]

4. An empty C++ file will pop up. Please copy and paste the contents of the {{Code|HelloWorld.c}} program into here.

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

5. Next, the project setting needs to be set up. Open the project properties window.

6. Navigate to Configuration Properties → C/C++.

7. Add {{Code|"C:\Program Files\Phidgets"}} to the additional include directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2003 Header.PNG|link=|alt=Header File]]

8. Navigate to Configuration Properties → Linker → Input.

9. Add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}} to the additional dependencies field. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2003 Library.PNG|link=|alt=Library File]]

10. Now, you can run the example. Click on Debug → Start Without Debugging.

[[File:VS2003 Run.PNG|link=|alt=Run]]

11. 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:VS2003 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 2 | Use Our Examples]] section for instructions.

Then, in your code, you will need to include the Phidget C/C++ library:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

====Visual Studio C++ 6.0====

=====Use Our Examples=====

1. Download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Here, you can find example programs for all the devices. You will need this example source code to be copied into your C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. Next, a new project will need to be created. Generate a new Win32 Console Application project with a descriptive name such as HelloWorld.

[[File:VS6 New Project.PNG|link=|alt=New Project]]

3. Create an empty project.

[[File:VS6 New Project 2.PNG|link=|alt=New Project]]

4. Next, the project settings needs to be set up. Navigate to Project → Settings → C/C++ → Preprocessor.

5. Add {{Code|C:\Program Files\Phidgets}} to the additional include directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS6 Header.PNG|link=|alt=Header File]]

6. Navigate to Project → Settings → Link → Input → Additional library Path.

7. Add {{Code|phidget21.lib}} to the object/library modules field.

8. Add {{Code|C:\Program Files\Phidgets}} to the additional library path. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS6 Library.PNG|link=|alt=Library File]]

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

To import the example program into your project, please:

9. Create a new C++ file by navigating to File → New → Files → C++ Source File and enter a descriptive name such as HelloWorld.

[[File:VS6 New File.PNG|link=|alt=New File]]

10. An empty C++ file will pop up. Please copy and paste the contents of the {{Code|HelloWorld.c}} program here.

[[File:VS6 Source.PNG|link=|alt=Source Code]]

11. Now, you can run the example. Click on Build → Execute.

[[File:VS6 Run.PNG|link=|alt=Run]]

12. 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:VS6 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 3 | Use Our Examples]] section for instructions.

In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 3 | Use Our Examples]] section.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===Borland===

====Use Our Examples====

In addition to running one of the two [[#Libraries and Drivers:| Windows Installers]] above (which you probably already have if you worked through the ''Getting Started'' page for your device), you will need the [{{SERVER}}/downloads/libraries/phidget21bcc.zip Borland C++ Libraries]. {{Code|phidget21bcc.lib}} is typically placed in {{Code|C:\Program Files\Phidgets}}, but you are free to place it in any directory you wish.

After installing the Phidget C/C++ library, you're ready to download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples] and run the examples.

Afterwards, unpack the examples. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example. Locate the {{Code|HelloWorld.c}} file and type the following to compile the file and link the Phidget C/C++ library:

To compile, link the Phidget C/C++ library and build a binary executable, enter the following in a command line prompt in the directory with {{Code|HelloWorld.c}}:
<div class="source">
<syntaxhighlight lang=bash>
bcc32 -eHelloWorld -I"C:\Program Files\Phidgets" -L"C:\Program Files\Phidgets" phidget21bcc.lib HelloWorld.c
</syntaxhighlight>
</div>

It is assumed that {{Code|phidget21bcc.lib}} and {{Code|phidget21.h}} are placed in {{Code|C:\Program Files\Phidgets}}. If the files are placed in another location, please adjust the paths to both of the file's location accordingly.

In this case, {{Code|HelloWorld.c}} would be the '''.c''' file specific to your device. After using {{Code|bcc32}}, you will have an executable named {{Code|HelloWorld}} that you can run.

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:Borland HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

====Write Your Own Code====

When writing your code from scratch, you start it as you would any C/C++ code with Borland. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the examples [[#Use Our Examples 4 |above]].

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===GCC on Windows===

====Cygwin/MinGW====

=====Use Our Examples=====

Download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Afterwards, unpack the examples. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example. Locate the {{Code|HelloWorld.c}} file and type the following to compile the file and link the Phidget C/C++ library in a command line prompt:

<b>Cygwin</b>

<div class="source">
<syntaxhighlight lang=bash>
gcc example.c -o HelloWorld -I"/cygdrive/c/Program Files/Phidgets" -L"/cygdrive/c/Program Files/Phidgets" -lphidget21
</syntaxhighlight>
</div>

<b>MinGW</b>
<div class="source">
<syntaxhighlight lang=bash>
gcc example.c -o HelloWorld -I"C:\Program Files\Phidgets" -L"C:\Program Files\Phidgets" -lphidget21
</syntaxhighlight>
</div>

After using gcc, you will have an executable named {{Code|HelloWorld}} that you can run.
It is assumed that {{Code|phidget21.h}} and {{Code|phidget21.lib}} are placed in {{Code|C:\Program Files\Phidgets}}. If the files are placed in another location, please adjust the paths to the file's location accordingly.

After using {{Code|gcc}}, you will have an executable named {{Code|HelloWorld}} that you can run.

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:C MinGW HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

=====Write Your Own Code=====

When writing your code from scratch, you start it as you would any C/C++ code with Cygwin/MinGW in your favourite text editor. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 5| Use Our Examples]] section above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===Dev C++===

=====Use Our Examples=====

1. Download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Here, you can find example programs for all the devices. {{FindYourDevice}} You will need this example source code to be copied into your Dev C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. In order to control Phidgets with Dev C++, we will use the {{Code|reimp}} tool to convert the {{Code|phidget21.lib}} to a format that Dev C++ accepts. Download the [http://sourceforge.net/projects/mingw/ reimp tool]. Reimp is part of MinGW, a minimal UNIX emulator for Windows, and it is specifically within the mingw-utils package. You can check MinGW's [http://sourceforge.net/project/shownotes.php?release_id=126568 release notes] to ensure Reimp is in the version you are using.

3. Open up command line and traverse to the directory containing the reimp tool. Type the following command to create {{Code|libphidget21.a}}.
<div class="source">
<syntaxhighlight lang=bash>
reimp.exe "C:\Program Files\Phidgets\phidget21.lib"
</syntaxhighlight>
</div>
The command above assumes that the {{Code|phidget21.lib}} is in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly. Please note that the 64 bit version of {{Code|phidget21.lib}} is not supported on Dev C/C++. Please use the 32 bit version of {{Code|phidget21.lib}}.

4. Place {{Code|libphidget21.a}} in {{Code|<Dev-Cpp Install Directory>/lib}}.

5. Next, a new project will need to be created. Generate a new console application with a descriptive name such as PhidgetTest. Please select C as the project type.

[[File:DevC New Project.PNG|link=|alt=New Project]]

6. Next, the project settings needs to be set up. Navigate to Project Options → Directories → Include Directories.

7. Add a new path to {{Code|C:\Program Files\Phidgets}}. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:DevC Header.PNG|link=|alt=Header File]]

8. Navigate to Project Options → Parameters → Linker.

9. Add {{Code|-lphidget21}} to the field. This step will find the {{Code|libphidget21.a}} file in {{Code|<Dev-Cpp Install Directory>/lib}}.

[[File:DevC Library.PNG|link=|alt=Library File]]

10. To import the {{Code|HelloWorld}} program into your project, please open up {{Code|main.c}} in the editor.

11. An empty C file will pop up. Please copy and paste the contents of the example program.

[[File:DevC Source.PNG|link=|alt=Source Code]]

12. Now, you can run the example. Click on Execute → Compile & Run.

[[File:DevC Run.PNG|link=|alt=Run]]

13. 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:DevC HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 6 | Use Our Examples]] section for instructions.

In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the [[#Use Our Examples 6 | examples]] above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

==OS X==

C/C++ has excellent support on OS X through the gcc compiler.

The first step in using C/C++ on Mac is to install the Phidget C/C++ library. Compile and install them as explained on the Getting Started guide for your device, which you can find on its product page on [{{SERVER}} our main website]. Then, the [[OS - OS X#Description of Library files|OS - OS X]] page also describes the different Phidget files, their installed locations, and their roles.

===Use Our Examples===

After installing the main Phidget library for OS X as above, you're ready to download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples]. Afterwards, unzip the file. To run the example code, you'll need to find the source code ''for your specific device''. Then, compile the code under your platform and run it.

To compile, link the Phidget C/C++ library, and build an executable binary on OS X, do (for example, depending on the Headers location):

<div class="source">
<syntaxhighlight lang=bash>

gcc example.c -o example -framework Phidget21 -I/Library/Frameworks/Phidget21.framework/Headers
</syntaxhighlight>
</div>

After using gcc, you will have an executable named {{Code|example}} that you can run.

===Write Your Own Code===

When writing your code from scratch, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 7|Use Our Example]] section above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples. Even more help and references are provided from there.

==Linux==

C/C++ has support on Linux through the gcc compiler.

The first step in using C/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.

===Use Our Examples===

After installing the Phidget libraries for Linux as above, you're ready to download and run the examples:
*[{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz Generic C/C++ Examples]

To run the example code, you'll need to download and unpack the examples, and then find the source code for your device. {{FindYourDevice}} You can also use the HelloWorld program, which a basic program that can run with any Phidget. Then, compile the code under your platform and run it. When compiling, you need to link to the Phidget library.

To compile, link the Phidget libraries and build a binary executable on Linux, do the following in a terminal in the directory with {{Code|example.c}}:

<div class="source">
<syntaxhighlight lang=bash>
gcc example.c -o example -lphidget21
</syntaxhighlight>
</div>

In this case, {{Code|example.c}} would be the '''.c''' file specific to your device. After using gcc, you will have an executable named {{Code|example}} that you can run.

On Linux, if you have not set up [[OS_-_Linux#Setting_udev_Rules | your udev rules for USB access]], you will need to run the program '''as root''':

<div class="source">
<syntaxhighlight lang=bash>
sudo ./example
</syntaxhighlight>
</div>

===Write Your Own Code===

When writing your code from scratch, you start it as you would any C/C++ code on Linux, such as within a text editor like Emacs, Vi, Gedit, or Kate. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>
#include <phidget21.h>
</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the examples above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

==Windows CE==

===Description of Library Files===
C/C++ programs on Windows CE depend on the following files, which the Windows CE installer puts onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. It is placed in {{Code|\Windows}}.
* <b>{{Code|PhidgetWebService21.exe}}</b> is used to control Phidgets remotely across a network using the [[#WebService | PhidgetWebService]]. It can be placed anywhere on the system.
* <b>{{Code|phidget21.lib}}</b> is used by your compiler to link to the dll. Your compiler has to know where this file is.
* <b>{{Code|phidget21.h}}</b> lists all the Phidget API function calls available to your code. Your compiler also has to know where this file is.
* <b>{{Code|phidget.dll}}</b> is the Phidgets kernel driver. It is placed in {{Code|\Windows}}.

===Visual Studio 2005/2008/2010===

=====Use Our Examples=====

Currently, we have no example code for C/C++ on Windows CE. However, set up is very much the same as what it would be with [[#Visual Studio 2005/2008/2010 |Visual Studio 2005/2008/2010]] in Windows. The {{Code|phidget21.h}} and {{Code|phidget21.lib}} can be downloaded [{{SERVER}}/downloads/libraries/Phidget21-wincedevel.zip here].

=====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 development environment to properly link the Phidget C/C++ library. To begin:

1. Generate a new Visual C++: Win32 Smart Device project with a descriptive name such as PhidgetTest.

[[File:WinCE VS C NewProject 1.PNG|link=|alt=New Project]]

2. Select {{Code|Next}}.

[[File:WinCE VS C NewProject 2.PNG|link=|alt=New Project]]

3. Select the SDK(s) that you want to code against and elect {{Code|Next}}.

[[File:WinCE VS C NewProject 3.PNG|link=|alt=SDKs]]

4. Create a console application and select {{Code|Next}}.

[[File:WinCE VS C NewProject 4.PNG|link=|alt=Create Console Application]]

3. Open the project properties window.

4. Navigate to Configuration Properties → C/C++.

5. Add {{Code|"C:\Program Files\Phidgets"}} to the additional directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Header.PNG|link=|alt=Header File]]

6. Navigate to Configuration Properties → Linker → Input.

7. Edit the additional dependencies and add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}}. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Library.PNG|link=|alt=Library File]]

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

Then, in your code, you will need to include the Phidget C/C++ library:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

The same [[#Follow the Examples|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.

Your main reference for writing C code will be our C/C++ API information, with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|both of which are available in C/C++|[{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++ API]}}

===Example Flow===

{{ExamplePseudocode|In C/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 an object with the {{Code|CPhidgetSpatialHandle}} type, and then initializing it using the {{Code|CPhidgetSpatial_create function}}. The examples show how to do this and other API functions.<br><br>
Other C calls follow a similar syntax - {{Code|CPhidgetXXX_function}}, where XXX is the name of your device, and function is an action available from the API for your specific Phidget.|
[{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++ API]}}

===Code Snippets===

When programming in C/C++, you're in luck. All of our code snippet examples on our [[General Phidget Programming]] page are in both C++ and Java. Therefore, we do not include any here, because that page is much more in-depth, and you won't have to have two pages open at once. So head over there, and start writing code!

==Common Problems and Solutions/Workarounds==

===Issue: I am using a non US-English version of Windows, and the Visual C/C++ examples run into a linker error===
Affected Operating Systems: '''Windows'''

The example projects, by default finds the {{Code|phidget21.h}} and {{Code|phidget21.lib}} in ${SystemDrive}\Program Files\Phidgets. If you are using a non US-English version of Windows, the Phidget drivers may be installed into a different location. To resolve, you will have to modify the paths to these two files. For instructions, please see your environment/compiler section.

Language - C

2012-06-29T19:48:57Z

Cora: /* Quick Downloads */

[[Category:Language]]
{{OSLang|[[File:icon-C++.png|link=|alt=C/C++|64x64px]]|C++ is a general purpose, cross-platform programming language with a vast user base.}}
__TOC__

==Introduction==

{{LanguageSupport|C/C++|the complete Phidget API, including events|all Phidget devices.|Windows 2000/XP/Vista/7(environments include [[#Visual Studio | Visual Studio]], [[#Borland | Borland]], [[#Cygwin/MinGW | Cygwin, and MinGW]]), [[#Windows CE | Windows CE]], [[#OS X | OS X]], and [[#Linux | Linux]]|}}

==Quick Downloads==
{{QuickDownloads|C/C++|
{{APIQuickDownloads|{{SERVER}}/documentation/Phidget21_C_Doc.zip}}
{{ExtraLibraryQuickDownloads|{{SERVER}}/documentation/web/cdoc/index.html|HTML Version of API|}}
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/VCpp.zip Visual Studio 2005/2008/2010|}}
{{ExampleQuickDownloads|{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz Generic|}}|
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/libraries/phidget21bcc.zip|Borland(Windows)|}}
{{WindowsQuickDownloads}}
{{MacQuickDownloads}}
{{LinuxQuickDownloads}}
}}

==Getting started with C/C++==

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

Instructions are divided up by operating system. Choose:
*[[#Windows(2000/XP/Vista/7)|Windows 2000 / XP / Vista / 7]]
*[[#OS X |OS X]]
*[[#Linux | Linux]] (including PhidgetSBC)

==Windows (2000/XP/Vista/7)==

===Description of Library Files===
C/C++ programs on Windows depend on three files, which the installers in [[#Libraries and Drivers|Quick Downloads]] put onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. By default, it is placed in {{Code|C:\Windows\System32}}.
* <b>{{Code|phidget21.lib}}</b> is used by your compiler to link to the dll. Your compiler has to know where this file is, by default our installer puts {{Code|phidget21.lib}} into {{Code|C:\Program Files\Phidgets}}, so you can either point your compiler to that location, or copy and link to it in a directory for your project workspace. {{Code|phidget21.lib}} is written to be compatible with most compilers - but your specific compiler may need a different format. Check our documentation for your specific compiler for details. Please note that we provide versions of the {{Code|phidget21.lib}} that are specifically optimized for 32-bit or 64-bit systems. If you are using a 64 bit versions of Windows, the {{Code|phidget21.lib}} is placed in {{Code|C:\Program Files\Phidgets}}; The 32 bit version of {{Code|phidget21.lib}} is placed in {{Code|C:\Program Files\Phidgets\x86}}.
* <b>{{Code|phidget21.h}}</b> lists all the Phidget API function calls available to your code. Your compiler also has to know where this file is. By default, our installer puts {{Code|phidget21.h}} into {{Code|C:\Program Files\Phidgets}} so 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 all three [{{SERVER}}/downloads/libraries/phidget21-x86.zip files] and manually install them where you want; refer to our [[OS_-_Windows#Manual_File_Installation | Manual Installation Instructions]].

Running the examples and writing your own code can be fairly compiler-specific, so we include instructions for [[#Visual Studio 2005/2008/2010 | Visual Studio 2005/2008/2010]], [[#Visual Studio 2003 | Visual Studio 2003]], [[#Visual Studio C++ 6.0 | Visual Studio 6]], [[#Borland| Borland]], [[#Cygwin/MinGW | Cygwin/MinGW]], and [[#Dev C++ | Dev C++]].

===Visual Studio===

C++/CLI (which used to be called Managed C++) is very different from mainstream C/C++. If you must use C++/CLI, consider calling the Phidget .NET library, instead of the C API normally used from C/C++. We have no documentation for using C++/CLI.

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.

====Visual Studio 2005/2008/2010====

=====Use Our Examples=====

To run the examples, you first download the [{{SERVER}}/downloads/examples/VCpp.zip examples] and unpack them into a folder. To load all projects in Visual Studio, go to File → Open → Project → Solution, and open {{Code|Visual Studio Phidgets Examples.sln}} in the {{Code|VCpp}} folder of the examples.

Since the examples were written in Visual Studio 2005, if you are opening the examples in Visual Studio 2008/2010, you will need to go through the Visual Studio Conversion Wizard to open and convert the 2005 project.

[[File:VS2005 Conversion Wizard.PNG|link=|alt=Conversion Wizard]]

This will load all of the examples available for C/C++. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

Start by setting the {{Code|HelloWorld}} project as your start up project.

[[File:VS2005 StartUp Project.PNG|link=|alt=Start Up Project]]

To run the example, click on Debug → Start Debugging. Please note that the projects, by default try to find the {{Code|phidget21.h}} and {{Code|phidget21.lib}} in the {{Code|$(SystemDrive)\Program Files\Phidgets}}. If you have these files installed in another location, please change the path to the file's location accordingly. Please see the [[#Write Your Own Code | Write Your Own Code]] section for details.

[[File:VS2005 Run.PNG|link=|alt=Run]]

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:VS2005 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget C/C++ library. To begin:

1. Generate a new Visual C++: Win32 Console Application project with a descriptive name such as PhidgetTest.

[[File:VS2005 New Project.PNG|link=|alt=New Project]]

2. Next, select Console Application.

[[File:VS2005 New Project 2.PNG|link=|alt=New Project]]

3. Open the project properties window.

4. Navigate to Configuration Properties → C/C++.

5. Add {{Code|"C:\Program Files\Phidgets"}} to the additional directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Header.PNG|link=|alt=Header File]]

6. Navigate to Configuration Properties → Linker → Input.

7. Edit the additional dependencies and add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}}. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Library.PNG|link=|alt=Library File]]

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

Then, in your code, you will need to include the Phidget C/C++ library:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

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

====Visual Studio 2003====

=====Use Our Examples=====

1. Start by downloading the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples]. You can import these examples into a Visual Studio 2003 C++ project. Afterwards, unpack them into a folder. Here, you can find example programs for all the devices. You will need this example source code to be copied into your C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. A new project will need to be created. Generate a new Visual C++ empty project(.NET) with a descriptive name such as HelloWorld.

[[File:VS2003 New Project.PNG|link=|alt=New Project]]

3. Create a new C++ file by adding a new item to the source files folder.

[[File:VS2003 New File.PNG|link=|alt=New File]]

[[File:VS2003 New File 2.PNG|link=|alt=New File]]

4. An empty C++ file will pop up. Please copy and paste the contents of the {{Code|HelloWorld.c}} program into here.

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

5. Next, the project setting needs to be set up. Open the project properties window.

6. Navigate to Configuration Properties → C/C++.

7. Add {{Code|"C:\Program Files\Phidgets"}} to the additional include directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2003 Header.PNG|link=|alt=Header File]]

8. Navigate to Configuration Properties → Linker → Input.

9. Add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}} to the additional dependencies field. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2003 Library.PNG|link=|alt=Library File]]

10. Now, you can run the example. Click on Debug → Start Without Debugging.

[[File:VS2003 Run.PNG|link=|alt=Run]]

11. 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:VS2003 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 2 | Use Our Examples]] section for instructions.

Then, in your code, you will need to include the Phidget C/C++ library:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

====Visual Studio C++ 6.0====

=====Use Our Examples=====

1. Download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Here, you can find example programs for all the devices. You will need this example source code to be copied into your C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. Next, a new project will need to be created. Generate a new Win32 Console Application project with a descriptive name such as HelloWorld.

[[File:VS6 New Project.PNG|link=|alt=New Project]]

3. Create an empty project.

[[File:VS6 New Project 2.PNG|link=|alt=New Project]]

4. Next, the project settings needs to be set up. Navigate to Project → Settings → C/C++ → Preprocessor.

5. Add {{Code|C:\Program Files\Phidgets}} to the additional include directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS6 Header.PNG|link=|alt=Header File]]

6. Navigate to Project → Settings → Link → Input → Additional library Path.

7. Add {{Code|phidget21.lib}} to the object/library modules field.

8. Add {{Code|C:\Program Files\Phidgets}} to the additional library path. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS6 Library.PNG|link=|alt=Library File]]

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

To import the example program into your project, please:

9. Create a new C++ file by navigating to File → New → Files → C++ Source File and enter a descriptive name such as HelloWorld.

[[File:VS6 New File.PNG|link=|alt=New File]]

10. An empty C++ file will pop up. Please copy and paste the contents of the {{Code|HelloWorld.c}} program here.

[[File:VS6 Source.PNG|link=|alt=Source Code]]

11. Now, you can run the example. Click on Build → Execute.

[[File:VS6 Run.PNG|link=|alt=Run]]

12. 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:VS6 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 3 | Use Our Examples]] section for instructions.

In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 3 | Use Our Examples]] section.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===Borland===

====Use Our Examples====

In addition to running one of the two [[#Libraries and Drivers:| Windows Installers]] above (which you probably already have if you worked through the ''Getting Started'' page for your device), you will need the [{{SERVER}}/downloads/libraries/phidget21bcc.zip Borland C++ Libraries]. {{Code|phidget21bcc.lib}} is typically placed in {{Code|C:\Program Files\Phidgets}}, but you are free to place it in any directory you wish.

After installing the Phidget C/C++ library, you're ready to download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples] and run the examples.

Afterwards, unpack the examples. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example. Locate the {{Code|HelloWorld.c}} file and type the following to compile the file and link the Phidget C/C++ library:

To compile, link the Phidget C/C++ library and build a binary executable, enter the following in a command line prompt in the directory with {{Code|HelloWorld.c}}:
<div class="source">
<syntaxhighlight lang=bash>
bcc32 -eHelloWorld -I"C:\Program Files\Phidgets" -L"C:\Program Files\Phidgets" phidget21bcc.lib HelloWorld.c
</syntaxhighlight>
</div>

It is assumed that {{Code|phidget21bcc.lib}} and {{Code|phidget21.h}} are placed in {{Code|C:\Program Files\Phidgets}}. If the files are placed in another location, please adjust the paths to both of the file's location accordingly.

In this case, {{Code|HelloWorld.c}} would be the '''.c''' file specific to your device. After using {{Code|bcc32}}, you will have an executable named {{Code|HelloWorld}} that you can run.

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:Borland HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

====Write Your Own Code====

When writing your code from scratch, you start it as you would any C/C++ code with Borland. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the examples [[#Use Our Examples 4 |above]].

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===GCC on Windows===

====Cygwin/MinGW====

=====Use Our Examples=====

Download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Afterwards, unpack the examples. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example. Locate the {{Code|HelloWorld.c}} file and type the following to compile the file and link the Phidget C/C++ library in a command line prompt:

<b>Cygwin</b>

<div class="source">
<syntaxhighlight lang=bash>
gcc example.c -o HelloWorld -I"/cygdrive/c/Program Files/Phidgets" -L"/cygdrive/c/Program Files/Phidgets" -lphidget21
</syntaxhighlight>
</div>

<b>MinGW</b>
<div class="source">
<syntaxhighlight lang=bash>
gcc example.c -o HelloWorld -I"C:\Program Files\Phidgets" -L"C:\Program Files\Phidgets" -lphidget21
</syntaxhighlight>
</div>

After using gcc, you will have an executable named {{Code|HelloWorld}} that you can run.
It is assumed that {{Code|phidget21.h}} and {{Code|phidget21.lib}} are placed in {{Code|C:\Program Files\Phidgets}}. If the files are placed in another location, please adjust the paths to the file's location accordingly.

After using {{Code|gcc}}, you will have an executable named {{Code|HelloWorld}} that you can run.

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:C MinGW HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

=====Write Your Own Code=====

When writing your code from scratch, you start it as you would any C/C++ code with Cygwin/MinGW in your favourite text editor. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 5| Use Our Examples]] section above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===Dev C++===

=====Use Our Examples=====

1. Download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Here, you can find example programs for all the devices. {{FindYourDevice}} You will need this example source code to be copied into your Dev C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. In order to control Phidgets with Dev C++, we will use the {{Code|reimp}} tool to convert the {{Code|phidget21.lib}} to a format that Dev C++ accepts. Download the [http://sourceforge.net/projects/mingw/ reimp tool]. Reimp is part of MinGW, a minimal UNIX emulator for Windows, and it is specifically within the mingw-utils package. You can check MinGW's [http://sourceforge.net/project/shownotes.php?release_id=126568 release notes] to ensure Reimp is in the version you are using.

3. Open up command line and traverse to the directory containing the reimp tool. Type the following command to create {{Code|libphidget21.a}}.
<div class="source">
<syntaxhighlight lang=bash>
reimp.exe "C:\Program Files\Phidgets\phidget21.lib"
</syntaxhighlight>
</div>
The command above assumes that the {{Code|phidget21.lib}} is in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly. Please note that the 64 bit version of {{Code|phidget21.lib}} is not supported on Dev C/C++. Please use the 32 bit version of {{Code|phidget21.lib}}.

4. Place {{Code|libphidget21.a}} in {{Code|<Dev-Cpp Install Directory>/lib}}.

5. Next, a new project will need to be created. Generate a new console application with a descriptive name such as PhidgetTest. Please select C as the project type.

[[File:DevC New Project.PNG|link=|alt=New Project]]

6. Next, the project settings needs to be set up. Navigate to Project Options → Directories → Include Directories.

7. Add a new path to {{Code|C:\Program Files\Phidgets}}. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:DevC Header.PNG|link=|alt=Header File]]

8. Navigate to Project Options → Parameters → Linker.

9. Add {{Code|-lphidget21}} to the field. This step will find the {{Code|libphidget21.a}} file in {{Code|<Dev-Cpp Install Directory>/lib}}.

[[File:DevC Library.PNG|link=|alt=Library File]]

10. To import the {{Code|HelloWorld}} program into your project, please open up {{Code|main.c}} in the editor.

11. An empty C file will pop up. Please copy and paste the contents of the example program.

[[File:DevC Source.PNG|link=|alt=Source Code]]

12. Now, you can run the example. Click on Execute → Compile & Run.

[[File:DevC Run.PNG|link=|alt=Run]]

13. 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:DevC HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|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 development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 6 | Use Our Examples]] section for instructions.

In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the [[#Use Our Examples 6 | examples]] above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

==OS X==

C/C++ has excellent support on OS X through the gcc compiler.

The first step in using C/C++ on Mac is to install the Phidget C/C++ library. Compile and install them as explained on the Getting Started guide for your device, which you can find on its product page on [{{SERVER}} our main website]. Then, the [[OS - OS X#Description of Library files|OS - OS X]] page also describes the different Phidget files, their installed locations, and their roles.

===Use Our Examples===

After installing the main Phidget library for OS X as above, you're ready to download the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz examples]. Afterwards, unzip the file. To run the example code, you'll need to find the source code ''for your specific device''. Then, compile the code under your platform and run it.

To compile, link the Phidget C/C++ library, and build an executable binary on OS X, do (for example, depending on the Headers location):

<div class="source">
<syntaxhighlight lang=bash>

gcc example.c -o example -framework Phidget21 -I/Library/Frameworks/Phidget21.framework/Headers
</syntaxhighlight>
</div>

After using gcc, you will have an executable named {{Code|example}} that you can run.

===Write Your Own Code===

When writing your code from scratch, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 7|Use Our Example]] section above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples. Even more help and references are provided from there.

==Linux==

C/C++ has support on Linux through the gcc compiler.

The first step in using C/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.

===Use Our Examples===

After installing the Phidget libraries for Linux as above, you're ready to download and run the examples:
*[{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz Generic C/C++ Examples]

To run the example code, you'll need to download and unpack the examples, and then find the source code for your device. {{FindYourDevice}} You can also use the HelloWorld program, which a basic program that can run with any Phidget. Then, compile the code under your platform and run it. When compiling, you need to link to the Phidget library.

To compile, link the Phidget libraries and build a binary executable on Linux, do the following in a terminal in the directory with {{Code|example.c}}:

<div class="source">
<syntaxhighlight lang=bash>
gcc example.c -o example -lphidget21
</syntaxhighlight>
</div>

In this case, {{Code|example.c}} would be the '''.c''' file specific to your device. After using gcc, you will have an executable named {{Code|example}} that you can run.

On Linux, if you have not set up [[OS_-_Linux#Setting_udev_Rules | your udev rules for USB access]], you will need to run the program '''as root''':

<div class="source">
<syntaxhighlight lang=bash>
sudo ./example
</syntaxhighlight>
</div>

===Write Your Own Code===

When writing your code from scratch, you start it as you would any C/C++ code on Linux, such as within a text editor like Emacs, Vi, Gedit, or Kate. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>
#include <phidget21.h>
</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the examples above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

==Windows CE==

===Description of Library Files===
C/C++ programs on Windows CE depend on the following files, which the Windows CE installer puts onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. It is placed in {{Code|\Windows}}.
* <b>{{Code|PhidgetWebService21.exe}}</b> is used to control Phidgets remotely across a network using the [[#WebService | PhidgetWebService]]. It can be placed anywhere on the system.
* <b>{{Code|phidget21.lib}}</b> is used by your compiler to link to the dll. Your compiler has to know where this file is.
* <b>{{Code|phidget21.h}}</b> lists all the Phidget API function calls available to your code. Your compiler also has to know where this file is.
* <b>{{Code|phidget.dll}}</b> is the Phidgets kernel driver. It is placed in {{Code|\Windows}}.

===Visual Studio 2005/2008/2010===

=====Use Our Examples=====

Currently, we have no example code for C/C++ on Windows CE. However, set up is very much the same as what it would be with [[#Visual Studio 2005/2008/2010 |Visual Studio 2005/2008/2010]] in Windows. The {{Code|phidget21.h}} and {{Code|phidget21.lib}} can be downloaded [{{SERVER}}/downloads/libraries/Phidget21-wincedevel.zip here].

=====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 development environment to properly link the Phidget C/C++ library. To begin:

1. Generate a new Visual C++: Win32 Smart Device project with a descriptive name such as PhidgetTest.

[[File:WinCE VS C NewProject 1.PNG|link=|alt=New Project]]

2. Select {{Code|Next}}.

[[File:WinCE VS C NewProject 2.PNG|link=|alt=New Project]]

3. Select the SDK(s) that you want to code against and elect {{Code|Next}}.

[[File:WinCE VS C NewProject 3.PNG|link=|alt=SDKs]]

4. Create a console application and select {{Code|Next}}.

[[File:WinCE VS C NewProject 4.PNG|link=|alt=Create Console Application]]

3. Open the project properties window.

4. Navigate to Configuration Properties → C/C++.

5. Add {{Code|"C:\Program Files\Phidgets"}} to the additional directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Header.PNG|link=|alt=Header File]]

6. Navigate to Configuration Properties → Linker → Input.

7. Edit the additional dependencies and add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}}. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Library.PNG|link=|alt=Library File]]

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

Then, in your code, you will need to include the Phidget C/C++ library:

<div class="source">
<syntaxhighlight lang=cpp>

#include <phidget21.h>

</syntaxhighlight>
</div>

The same [[#Follow the Examples|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.

Your main reference for writing C code will be our C/C++ API information, with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|both of which are available in C/C++|[{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++ API]}}

===Example Flow===

{{ExamplePseudocode|In C/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 an object with the {{Code|CPhidgetSpatialHandle}} type, and then initializing it using the {{Code|CPhidgetSpatial_create function}}. The examples show how to do this and other API functions.<br><br>
Other C calls follow a similar syntax - {{Code|CPhidgetXXX_function}}, where XXX is the name of your device, and function is an action available from the API for your specific Phidget.|
[{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++ API]}}

===Code Snippets===

When programming in C/C++, you're in luck. All of our code snippet examples on our [[General Phidget Programming]] page are in both C++ and Java. Therefore, we do not include any here, because that page is much more in-depth, and you won't have to have two pages open at once. So head over there, and start writing code!

==Common Problems and Solutions/Workarounds==

===Issue: I am using a non US-English version of Windows, and the Visual C/C++ examples run into a linker error===
Affected Operating Systems: '''Windows'''

The example projects, by default finds the {{Code|phidget21.h}} and {{Code|phidget21.lib}} in ${SystemDrive}\Program Files\Phidgets. If you are using a non US-English version of Windows, the Phidget drivers may be installed into a different location. To resolve, you will have to modify the paths to these two files. For instructions, please see your environment/compiler section.

LED Guide

2012-06-29T18:53:37Z

Cora: /* Controlling LEDs */

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[Image:RBG.jpg|500px]]
|}

<br clear="all" />
==Introduction==

Like normal diodes, Light Emitting Diodes (LEDs) are semiconductor devices designed to conduct current in one direction only. What makes LEDs unique is their internal material makeup: when atoms in an LED release energy due to the flow of forward current, it is released in the form of photons (light). Different construction materials and various phosphor coatings are used to produce numerous colors of light.

LEDs that Phidgets sells are all operable via the [[Digital Output Primer|digital outputs]] on any of our interface kits. However Phidgets also sells a specific [{{SERVER}}/products.php?product_id=1031 PhidgetLED-64 Advanced LED controller] since it is often desirable to control more LEDs than even the [{{SERVER}}/products.php?product_id=1012 1012 Phidget Interface Kit 0/16/16] can operate. It offers some unique features such as brightness control.

==How it works==
[[image:led.png|thumb|350px|Parts of an LED. The flat spot on the epoxy casing, is an anchor to prevent twisting from damaging the leads.]]

LEDs emit light from current flowing through them. As the current flows, the electronics experience a sudden drop in energy level (voltage). When that happens they release energy in the form of light. The amount of light produced is proportional to the current. Depending on the material used to make the LED, different colors can be created. Like a conventional diode, the current can only flow in one direction - from the anode to the cathode.

==Controlling LEDs==

===Forward Voltage===

The materials used within LEDs that cause them to emit different colors of light affect a property called its forward voltage. The forward voltage is the voltage at which current in the forward direction will flow through the device and allow the LED to convert electrical energy into light. If the voltage applied to the LED is below the forward voltage of the LED, very little current (or none) may flow, and therefore very little light will be emitted. Most standard LEDs with colors such as red, amber, orange, yellow, and green have forward voltages below 2.75 Volts, and can be used with a [[Digital Output Primer|digital output]] by simply soldering them to a connector-wire and inserting the wire into the output port. The forward voltage in the [{{SERVER}}/products.php?product_id=1031 1031 - PhidgetLED] will default to 2.75V, and the maximum current defaults to 20mA.

===Supply Voltage===
{|
|- valign="top"
|To be an effective LED controller your digital outputs must be capable of <br />adjusting the forward voltage supplied to the LEDs to 1.7, 2.75, 3.9 and 5 volts<br /> settings allowing you to properly drive blue, white, violet, ultra violet and purple LEDs.<br /> The supply voltage will affect all LEDs. If you set the supplied voltage too high,<br /> power will be wasted and the controller may shut down from thermal overload. If you<br /> set the supply voltage too low, your LEDs will not be driven at the requested<br /> current, and will be dim or non-functional.
|
{| {{table}} border = 1
!colspan="2" style="background:#f0f0f0;"|Typical Forward Voltages
|-
| align="center" style="background:#f0f0f0;"|'''Color'''
| align="center" style="background:#f0f0f0;"|'''Forward Voltage'''
|-
| Infrared||< 1.9
|-
| Red||1.7 to 2.2
|-
| Orange||2.0 to 2.2
|-
| Yellow||2.1 to 2.4
|-
| Green||2 to 2.3
|-
| Blue||3.2 to 4.0
|-
| Ultraviolet||2.1 to 3.8
|-
| White||3.3 to 3.6
|}
|}

===Maximum Current and Brightness Control===

{|
|-valign="top"
|
Most LEDs fall within 20, 40, 60 or 80mA, and applies to all LEDs. The <br />Phidgets DiscreteLED API call can be used to provide more current <br />or control brightness and will adjust the current linearly between 0 <br />and the set maximum. This however does not imply a precise method <br />for controlling the visibility of emitted light, as this is affected by the <br />construction and quality of the LED as well as the eyes of the viewer. <br />Be cautious when changing the current property. Many small LEDs are <br />designed for a maximum 20mA, and can be destroyed if driven at higher <br />currents.
|
[[image:Ledcurrent.png|400px]]
|}

===Choosing Current and Voltage Settings===

Make sure to choose the minimum supply voltage setting to drive the LED that requires the most voltage during operation. Any extra voltage not required by the LED will be converted to heat by the 1031. For example, a Blue LED being driven at 20mA, 3.9V Supply, that requires 3.7 volts will cause (3.9V-3.7V + 0.4V) * 0.02A = 12 milliwatts of heat to be produced on the 1031. If this example instead uses a high power, 1.5V infrared LED at 80mA, this will create (3.9V-1.5V+0.4V)*0.08 Amps = 224 milliwatts of heat. See the Heat Dissipation and Thermal Protection section later on in this manual for more information about this issue.

==Multiplexed LEDs==
Multiplexing is a system wherein the entire display is not active at the same time. Instead, sub-units of the display are driven one at a time and the electronics combine with human persistence of vision (the phenomenon of the eye by which an afterimage is thought to persist for approximately one twenty-fifth of a second on the retina) to make the viewer believe the entire display is continuously active. Many controllers use this architecture to reduce power consumption. 7 segment display clocks are an example of this.

In an effort to reduce electrical noise in the system the PhidgetLED does not use multiplexing. All 64 anodes are connected to the same power supply and the cathode of each LED connection is attached to an individual constant current sink. Also, the LEDs are not controlled by PWM - they are driven at a constant current.

==Other uses for LED controllers==

LED controllers are typically just a set of special digital outputs. This means they aren't limited to just controlling LEDs. They can be used to control relays, solenoids and even very small motors. The PhidgetLED can also be used to drive opto-isolators and MOSFET SSRs. A diode integrated into the 1031 on each cathode will clamp inductive surges to the anode supply voltage.

==Power Requirements and Power Supply Selection==

The power supply that is included with the 1031 is rated at 12V and 2A (max). If your application requires more power, a larger power supply may be necessary. The on-board voltage regulator is able to supply up to 6A for each LED supply voltage setting, as long as the power supply is able to provide enough voltage and current to the regulator. Assume an efficiency of 80% for the on-board voltage regulator when determining if a different power supply is required.

==Heat Dissipation and Thermal Protection==

Projects that require a high supply voltage, or have a lot of heat being produced from over voltage settings, will have over-temperature problems. This can be mitigated somewhat by understanding how channels are grouped and how the heat is distributed around the controller. On the 1031 channels are split into four groups: (0-7,24-31), (8-23), (32-39, 56-63) and (40-55); each controlled by their own individual IC. Evenly distributing the LEDs that may produce a lot of heat across these groups will balance the load on the ICs and reduce the risk of thermal overload. When thermal overload occurs, the integrated circuit (IC) controlling the involved LEDs will disable the output of all the channels it controls. For example, if an over-temperature occurs due to channel 12, all of the channels 8 through 23 will be disabled by the IC until the temperature back within the operating range. Thermal protection is activated when the die of the IC reaches approximately 160 degrees Celsius. Once the over-temperature fault has been corrected (ie, the IC has cooled down), the output channels will be re-enabled with the same settings as before the thermal shutdown. An error message will be produced during an over-temperature.

==Products that fall under this category==

*[{{SERVER}}/products.php?product_id=1031 1031 - PhidgetLED-64 Advanced]

*[{{SERVER}}/products.php?product_id=3601 3601 - 10mm Red LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3602 3602 - 10mm Green LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3603 3603 - 10mm Blue LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3604 3604 - 10mm Yellow LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3605 3605 - 10mm White LED (Bag of 20)]

*[{{SERVER}}/products.php?product_id=3606 3606 - 5mm Four Chip Super Flux Red (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3607 3607 - 5mm Four Chip Super Flux Green (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3608 3608 - 5mm Four Chip Super Flux Blue (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3609 3609 - 5mm Four Chip Super Flux Yellow (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3610 3610 - 5mm Four Chip Super Flux White (Bag of 5)]

*[{{SERVER}}/products.php?product_id=3611 3611 - 5mm Diffused Red (Bag of 30)]
*[{{SERVER}}/products.php?product_id=3612 3612 - 5mm Diffused Yellow/Green (Bag of 30)]
*[{{SERVER}}/products.php?product_id=3613 - 5mm Diffused Blue (Bag of 30)]

*[{{SERVER}}/products.php?product_id=3614 3614 - Flexible LED Strip Green (5m)]
*[{{SERVER}}/products.php?product_id=3615 3615 - Flexible LED Strip Blue (5m)]
*[{{SERVER}}/products.php?product_id=3616 3616 - Flexible LED Strip White (5m)]

*[{{SERVER}}/products.php?product_id=3618 3618 - RGB LED Modules - String of 10]

LED Guide

2012-06-29T18:53:09Z

Cora: /* Forward Voltage */

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[Image:RBG.jpg|500px]]
|}

<br clear="all" />
==Introduction==

Like normal diodes, Light Emitting Diodes (LEDs) are semiconductor devices designed to conduct current in one direction only. What makes LEDs unique is their internal material makeup: when atoms in an LED release energy due to the flow of forward current, it is released in the form of photons (light). Different construction materials and various phosphor coatings are used to produce numerous colors of light.

LEDs that Phidgets sells are all operable via the [[Digital Output Primer|digital outputs]] on any of our interface kits. However Phidgets also sells a specific [{{SERVER}}/products.php?product_id=1031 PhidgetLED-64 Advanced LED controller] since it is often desirable to control more LEDs than even the [{{SERVER}}/products.php?product_id=1012 1012 Phidget Interface Kit 0/16/16] can operate. It offers some unique features such as brightness control.

==How it works==
[[image:led.png|thumb|350px|Parts of an LED. The flat spot on the epoxy casing, is an anchor to prevent twisting from damaging the leads.]]

LEDs emit light from current flowing through them. As the current flows, the electronics experience a sudden drop in energy level (voltage). When that happens they release energy in the form of light. The amount of light produced is proportional to the current. Depending on the material used to make the LED, different colors can be created. Like a conventional diode, the current can only flow in one direction - from the anode to the cathode.

==Controlling LEDs==

===Forward Voltage===

The materials used within LEDs that cause them to emit different colors of light affect a property called its forward voltage. The forward voltage is the voltage at which current in the forward direction will flow through the device and allow the LED to convert electrical energy into light. If the voltage applied to the LED is below the forward voltage of the LED, very little current (or none) may flow, and therefore very little light will be emitted. Most standard LEDs with colors such as red, amber, orange, yellow, and green have forward voltages below 2.75 Volts, and can be used with a [[Digital Output Primer|digital output]] by simply soldering them to a connector-wire and inserting the wire into the output port. The forward voltage in the [{{SERVER}}/products.php?product_id=1031 1031 - PhidgetLED|PhidgetLED] will default to 2.75V, and the maximum current defaults to 20mA.

===Supply Voltage===
{|
|- valign="top"
|To be an effective LED controller your digital outputs must be capable of <br />adjusting the forward voltage supplied to the LEDs to 1.7, 2.75, 3.9 and 5 volts<br /> settings allowing you to properly drive blue, white, violet, ultra violet and purple LEDs.<br /> The supply voltage will affect all LEDs. If you set the supplied voltage too high,<br /> power will be wasted and the controller may shut down from thermal overload. If you<br /> set the supply voltage too low, your LEDs will not be driven at the requested<br /> current, and will be dim or non-functional.
|
{| {{table}} border = 1
!colspan="2" style="background:#f0f0f0;"|Typical Forward Voltages
|-
| align="center" style="background:#f0f0f0;"|'''Color'''
| align="center" style="background:#f0f0f0;"|'''Forward Voltage'''
|-
| Infrared||< 1.9
|-
| Red||1.7 to 2.2
|-
| Orange||2.0 to 2.2
|-
| Yellow||2.1 to 2.4
|-
| Green||2 to 2.3
|-
| Blue||3.2 to 4.0
|-
| Ultraviolet||2.1 to 3.8
|-
| White||3.3 to 3.6
|}
|}

===Maximum Current and Brightness Control===

{|
|-valign="top"
|
Most LEDs fall within 20, 40, 60 or 80mA, and applies to all LEDs. The <br />Phidgets DiscreteLED API call can be used to provide more current <br />or control brightness and will adjust the current linearly between 0 <br />and the set maximum. This however does not imply a precise method <br />for controlling the visibility of emitted light, as this is affected by the <br />construction and quality of the LED as well as the eyes of the viewer. <br />Be cautious when changing the current property. Many small LEDs are <br />designed for a maximum 20mA, and can be destroyed if driven at higher <br />currents.
|
[[image:Ledcurrent.png|400px]]
|}

===Choosing Current and Voltage Settings===

Make sure to choose the minimum supply voltage setting to drive the LED that requires the most voltage during operation. Any extra voltage not required by the LED will be converted to heat by the 1031. For example, a Blue LED being driven at 20mA, 3.9V Supply, that requires 3.7 volts will cause (3.9V-3.7V + 0.4V) * 0.02A = 12 milliwatts of heat to be produced on the 1031. If this example instead uses a high power, 1.5V infrared LED at 80mA, this will create (3.9V-1.5V+0.4V)*0.08 Amps = 224 milliwatts of heat. See the Heat Dissipation and Thermal Protection section later on in this manual for more information about this issue.

==Multiplexed LEDs==
Multiplexing is a system wherein the entire display is not active at the same time. Instead, sub-units of the display are driven one at a time and the electronics combine with human persistence of vision (the phenomenon of the eye by which an afterimage is thought to persist for approximately one twenty-fifth of a second on the retina) to make the viewer believe the entire display is continuously active. Many controllers use this architecture to reduce power consumption. 7 segment display clocks are an example of this.

In an effort to reduce electrical noise in the system the PhidgetLED does not use multiplexing. All 64 anodes are connected to the same power supply and the cathode of each LED connection is attached to an individual constant current sink. Also, the LEDs are not controlled by PWM - they are driven at a constant current.

==Other uses for LED controllers==

LED controllers are typically just a set of special digital outputs. This means they aren't limited to just controlling LEDs. They can be used to control relays, solenoids and even very small motors. The PhidgetLED can also be used to drive opto-isolators and MOSFET SSRs. A diode integrated into the 1031 on each cathode will clamp inductive surges to the anode supply voltage.

==Power Requirements and Power Supply Selection==

The power supply that is included with the 1031 is rated at 12V and 2A (max). If your application requires more power, a larger power supply may be necessary. The on-board voltage regulator is able to supply up to 6A for each LED supply voltage setting, as long as the power supply is able to provide enough voltage and current to the regulator. Assume an efficiency of 80% for the on-board voltage regulator when determining if a different power supply is required.

==Heat Dissipation and Thermal Protection==

Projects that require a high supply voltage, or have a lot of heat being produced from over voltage settings, will have over-temperature problems. This can be mitigated somewhat by understanding how channels are grouped and how the heat is distributed around the controller. On the 1031 channels are split into four groups: (0-7,24-31), (8-23), (32-39, 56-63) and (40-55); each controlled by their own individual IC. Evenly distributing the LEDs that may produce a lot of heat across these groups will balance the load on the ICs and reduce the risk of thermal overload. When thermal overload occurs, the integrated circuit (IC) controlling the involved LEDs will disable the output of all the channels it controls. For example, if an over-temperature occurs due to channel 12, all of the channels 8 through 23 will be disabled by the IC until the temperature back within the operating range. Thermal protection is activated when the die of the IC reaches approximately 160 degrees Celsius. Once the over-temperature fault has been corrected (ie, the IC has cooled down), the output channels will be re-enabled with the same settings as before the thermal shutdown. An error message will be produced during an over-temperature.

==Products that fall under this category==

*[{{SERVER}}/products.php?product_id=1031 1031 - PhidgetLED-64 Advanced]

*[{{SERVER}}/products.php?product_id=3601 3601 - 10mm Red LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3602 3602 - 10mm Green LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3603 3603 - 10mm Blue LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3604 3604 - 10mm Yellow LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3605 3605 - 10mm White LED (Bag of 20)]

*[{{SERVER}}/products.php?product_id=3606 3606 - 5mm Four Chip Super Flux Red (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3607 3607 - 5mm Four Chip Super Flux Green (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3608 3608 - 5mm Four Chip Super Flux Blue (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3609 3609 - 5mm Four Chip Super Flux Yellow (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3610 3610 - 5mm Four Chip Super Flux White (Bag of 5)]

*[{{SERVER}}/products.php?product_id=3611 3611 - 5mm Diffused Red (Bag of 30)]
*[{{SERVER}}/products.php?product_id=3612 3612 - 5mm Diffused Yellow/Green (Bag of 30)]
*[{{SERVER}}/products.php?product_id=3613 - 5mm Diffused Blue (Bag of 30)]

*[{{SERVER}}/products.php?product_id=3614 3614 - Flexible LED Strip Green (5m)]
*[{{SERVER}}/products.php?product_id=3615 3615 - Flexible LED Strip Blue (5m)]
*[{{SERVER}}/products.php?product_id=3616 3616 - Flexible LED Strip White (5m)]

*[{{SERVER}}/products.php?product_id=3618 3618 - RGB LED Modules - String of 10]

LED Guide

2012-06-29T18:52:48Z

Cora:

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[Image:RBG.jpg|500px]]
|}

<br clear="all" />
==Introduction==

Like normal diodes, Light Emitting Diodes (LEDs) are semiconductor devices designed to conduct current in one direction only. What makes LEDs unique is their internal material makeup: when atoms in an LED release energy due to the flow of forward current, it is released in the form of photons (light). Different construction materials and various phosphor coatings are used to produce numerous colors of light.

LEDs that Phidgets sells are all operable via the [[Digital Output Primer|digital outputs]] on any of our interface kits. However Phidgets also sells a specific [{{SERVER}}/products.php?product_id=1031 PhidgetLED-64 Advanced LED controller] since it is often desirable to control more LEDs than even the [{{SERVER}}/products.php?product_id=1012 1012 Phidget Interface Kit 0/16/16] can operate. It offers some unique features such as brightness control.

==How it works==
[[image:led.png|thumb|350px|Parts of an LED. The flat spot on the epoxy casing, is an anchor to prevent twisting from damaging the leads.]]

LEDs emit light from current flowing through them. As the current flows, the electronics experience a sudden drop in energy level (voltage). When that happens they release energy in the form of light. The amount of light produced is proportional to the current. Depending on the material used to make the LED, different colors can be created. Like a conventional diode, the current can only flow in one direction - from the anode to the cathode.

==Controlling LEDs==

===Forward Voltage===

The materials used within LEDs that cause them to emit different colors of light affect a property called its forward voltage. The forward voltage is the voltage at which current in the forward direction will flow through the device and allow the LED to convert electrical energy into light. If the voltage applied to the LED is below the forward voltage of the LED, very little current (or none) may flow, and therefore very little light will be emitted. Most standard LEDs with colors such as red, amber, orange, yellow, and green have forward voltages below 2.75 Volts, and can be used with a [[Digital Output Primer|digital output]] by simply soldering them to a connector-wire and inserting the wire into the output port. The forward voltage in the [{{SERVER}}/products.php?product_id=1031 1031 - PhidgetLED|PhidgetLED]] will default to 2.75V, and the maximum current defaults to 20mA.

===Supply Voltage===
{|
|- valign="top"
|To be an effective LED controller your digital outputs must be capable of <br />adjusting the forward voltage supplied to the LEDs to 1.7, 2.75, 3.9 and 5 volts<br /> settings allowing you to properly drive blue, white, violet, ultra violet and purple LEDs.<br /> The supply voltage will affect all LEDs. If you set the supplied voltage too high,<br /> power will be wasted and the controller may shut down from thermal overload. If you<br /> set the supply voltage too low, your LEDs will not be driven at the requested<br /> current, and will be dim or non-functional.
|
{| {{table}} border = 1
!colspan="2" style="background:#f0f0f0;"|Typical Forward Voltages
|-
| align="center" style="background:#f0f0f0;"|'''Color'''
| align="center" style="background:#f0f0f0;"|'''Forward Voltage'''
|-
| Infrared||< 1.9
|-
| Red||1.7 to 2.2
|-
| Orange||2.0 to 2.2
|-
| Yellow||2.1 to 2.4
|-
| Green||2 to 2.3
|-
| Blue||3.2 to 4.0
|-
| Ultraviolet||2.1 to 3.8
|-
| White||3.3 to 3.6
|}
|}

===Maximum Current and Brightness Control===

{|
|-valign="top"
|
Most LEDs fall within 20, 40, 60 or 80mA, and applies to all LEDs. The <br />Phidgets DiscreteLED API call can be used to provide more current <br />or control brightness and will adjust the current linearly between 0 <br />and the set maximum. This however does not imply a precise method <br />for controlling the visibility of emitted light, as this is affected by the <br />construction and quality of the LED as well as the eyes of the viewer. <br />Be cautious when changing the current property. Many small LEDs are <br />designed for a maximum 20mA, and can be destroyed if driven at higher <br />currents.
|
[[image:Ledcurrent.png|400px]]
|}

===Choosing Current and Voltage Settings===

Make sure to choose the minimum supply voltage setting to drive the LED that requires the most voltage during operation. Any extra voltage not required by the LED will be converted to heat by the 1031. For example, a Blue LED being driven at 20mA, 3.9V Supply, that requires 3.7 volts will cause (3.9V-3.7V + 0.4V) * 0.02A = 12 milliwatts of heat to be produced on the 1031. If this example instead uses a high power, 1.5V infrared LED at 80mA, this will create (3.9V-1.5V+0.4V)*0.08 Amps = 224 milliwatts of heat. See the Heat Dissipation and Thermal Protection section later on in this manual for more information about this issue.

==Multiplexed LEDs==
Multiplexing is a system wherein the entire display is not active at the same time. Instead, sub-units of the display are driven one at a time and the electronics combine with human persistence of vision (the phenomenon of the eye by which an afterimage is thought to persist for approximately one twenty-fifth of a second on the retina) to make the viewer believe the entire display is continuously active. Many controllers use this architecture to reduce power consumption. 7 segment display clocks are an example of this.

In an effort to reduce electrical noise in the system the PhidgetLED does not use multiplexing. All 64 anodes are connected to the same power supply and the cathode of each LED connection is attached to an individual constant current sink. Also, the LEDs are not controlled by PWM - they are driven at a constant current.

==Other uses for LED controllers==

LED controllers are typically just a set of special digital outputs. This means they aren't limited to just controlling LEDs. They can be used to control relays, solenoids and even very small motors. The PhidgetLED can also be used to drive opto-isolators and MOSFET SSRs. A diode integrated into the 1031 on each cathode will clamp inductive surges to the anode supply voltage.

==Power Requirements and Power Supply Selection==

The power supply that is included with the 1031 is rated at 12V and 2A (max). If your application requires more power, a larger power supply may be necessary. The on-board voltage regulator is able to supply up to 6A for each LED supply voltage setting, as long as the power supply is able to provide enough voltage and current to the regulator. Assume an efficiency of 80% for the on-board voltage regulator when determining if a different power supply is required.

==Heat Dissipation and Thermal Protection==

Projects that require a high supply voltage, or have a lot of heat being produced from over voltage settings, will have over-temperature problems. This can be mitigated somewhat by understanding how channels are grouped and how the heat is distributed around the controller. On the 1031 channels are split into four groups: (0-7,24-31), (8-23), (32-39, 56-63) and (40-55); each controlled by their own individual IC. Evenly distributing the LEDs that may produce a lot of heat across these groups will balance the load on the ICs and reduce the risk of thermal overload. When thermal overload occurs, the integrated circuit (IC) controlling the involved LEDs will disable the output of all the channels it controls. For example, if an over-temperature occurs due to channel 12, all of the channels 8 through 23 will be disabled by the IC until the temperature back within the operating range. Thermal protection is activated when the die of the IC reaches approximately 160 degrees Celsius. Once the over-temperature fault has been corrected (ie, the IC has cooled down), the output channels will be re-enabled with the same settings as before the thermal shutdown. An error message will be produced during an over-temperature.

==Products that fall under this category==

*[{{SERVER}}/products.php?product_id=1031 1031 - PhidgetLED-64 Advanced]

*[{{SERVER}}/products.php?product_id=3601 3601 - 10mm Red LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3602 3602 - 10mm Green LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3603 3603 - 10mm Blue LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3604 3604 - 10mm Yellow LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3605 3605 - 10mm White LED (Bag of 20)]

*[{{SERVER}}/products.php?product_id=3606 3606 - 5mm Four Chip Super Flux Red (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3607 3607 - 5mm Four Chip Super Flux Green (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3608 3608 - 5mm Four Chip Super Flux Blue (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3609 3609 - 5mm Four Chip Super Flux Yellow (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3610 3610 - 5mm Four Chip Super Flux White (Bag of 5)]

*[{{SERVER}}/products.php?product_id=3611 3611 - 5mm Diffused Red (Bag of 30)]
*[{{SERVER}}/products.php?product_id=3612 3612 - 5mm Diffused Yellow/Green (Bag of 30)]
*[{{SERVER}}/products.php?product_id=3613 - 5mm Diffused Blue (Bag of 30)]

*[{{SERVER}}/products.php?product_id=3614 3614 - Flexible LED Strip Green (5m)]
*[{{SERVER}}/products.php?product_id=3615 3615 - Flexible LED Strip Blue (5m)]
*[{{SERVER}}/products.php?product_id=3616 3616 - Flexible LED Strip White (5m)]

*[{{SERVER}}/products.php?product_id=3618 3618 - RGB LED Modules - String of 10]

LED Guide

2012-06-29T18:52:08Z

Cora:

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[Image:RBG.jpg|500px]]
|}

<br clear="all" />
==Introduction==

Like normal diodes, Light Emitting Diodes (LEDs) are semiconductor devices designed to conduct current in one direction only. What makes LEDs unique is their internal material makeup: when atoms in an LED release energy due to the flow of forward current, it is released in the form of photons (light). Different construction materials and various phosphor coatings are used to produce numerous colors of light.

LEDs that Phidgets sells are all operable via the [[Digital Output Primer|digital outputs]] on any of our interface kits. However Phidgets also sells a specific [{{SERVER}}/products.php?product_id=1031 PhidgetLED-64 Advanced LED controller] since it is often desirable to control more LEDs than even the [{{SERVER}}/products.php?product_id=1012 1012 Phidget Interface Kit 0/16/16] can operate. It offers some unique features such as brightness control.

==How it works==
[[image:led.png|thumb|350px|Parts of an LED. The flat spot on the epoxy casing, is an anchor to prevent twisting from damaging the leads.]]

LEDs emit light from current flowing through them. As the current flows, the electronics experience a sudden drop in energy level (voltage). When that happens they release energy in the form of light. The amount of light produced is proportional to the current. Depending on the material used to make the LED, different colors can be created. Like a conventional diode, the current can only flow in one direction - from the anode to the cathode.

==Controlling LEDs==

===Forward Voltage===

The materials used within LEDs that cause them to emit different colors of light affect a property called its forward voltage. The forward voltage is the voltage at which current in the forward direction will flow through the device and allow the LED to convert electrical energy into light. If the voltage applied to the LED is below the forward voltage of the LED, very little current (or none) may flow, and therefore very little light will be emitted. Most standard LEDs with colors such as red, amber, orange, yellow, and green have forward voltages below 2.75 Volts, and can be used with a [[Digital Output Primer|digital output]] by simply soldering them to a connector-wire and inserting the wire into the output port. The forward voltage in the [[1031 - PhidgetLED|PhidgetLED]] will default to 2.75V, and the maximum current defaults to 20mA.

===Supply Voltage===
{|
|- valign="top"
|To be an effective LED controller your digital outputs must be capable of <br />adjusting the forward voltage supplied to the LEDs to 1.7, 2.75, 3.9 and 5 volts<br /> settings allowing you to properly drive blue, white, violet, ultra violet and purple LEDs.<br /> The supply voltage will affect all LEDs. If you set the supplied voltage too high,<br /> power will be wasted and the controller may shut down from thermal overload. If you<br /> set the supply voltage too low, your LEDs will not be driven at the requested<br /> current, and will be dim or non-functional.
|
{| {{table}} border = 1
!colspan="2" style="background:#f0f0f0;"|Typical Forward Voltages
|-
| align="center" style="background:#f0f0f0;"|'''Color'''
| align="center" style="background:#f0f0f0;"|'''Forward Voltage'''
|-
| Infrared||< 1.9
|-
| Red||1.7 to 2.2
|-
| Orange||2.0 to 2.2
|-
| Yellow||2.1 to 2.4
|-
| Green||2 to 2.3
|-
| Blue||3.2 to 4.0
|-
| Ultraviolet||2.1 to 3.8
|-
| White||3.3 to 3.6
|}
|}

===Maximum Current and Brightness Control===

{|
|-valign="top"
|
Most LEDs fall within 20, 40, 60 or 80mA, and applies to all LEDs. The <br />Phidgets DiscreteLED API call can be used to provide more current <br />or control brightness and will adjust the current linearly between 0 <br />and the set maximum. This however does not imply a precise method <br />for controlling the visibility of emitted light, as this is affected by the <br />construction and quality of the LED as well as the eyes of the viewer. <br />Be cautious when changing the current property. Many small LEDs are <br />designed for a maximum 20mA, and can be destroyed if driven at higher <br />currents.
|
[[image:Ledcurrent.png|400px]]
|}

===Choosing Current and Voltage Settings===

Make sure to choose the minimum supply voltage setting to drive the LED that requires the most voltage during operation. Any extra voltage not required by the LED will be converted to heat by the 1031. For example, a Blue LED being driven at 20mA, 3.9V Supply, that requires 3.7 volts will cause (3.9V-3.7V + 0.4V) * 0.02A = 12 milliwatts of heat to be produced on the 1031. If this example instead uses a high power, 1.5V infrared LED at 80mA, this will create (3.9V-1.5V+0.4V)*0.08 Amps = 224 milliwatts of heat. See the Heat Dissipation and Thermal Protection section later on in this manual for more information about this issue.

==Multiplexed LEDs==
Multiplexing is a system wherein the entire display is not active at the same time. Instead, sub-units of the display are driven one at a time and the electronics combine with human persistence of vision (the phenomenon of the eye by which an afterimage is thought to persist for approximately one twenty-fifth of a second on the retina) to make the viewer believe the entire display is continuously active. Many controllers use this architecture to reduce power consumption. 7 segment display clocks are an example of this.

In an effort to reduce electrical noise in the system the PhidgetLED does not use multiplexing. All 64 anodes are connected to the same power supply and the cathode of each LED connection is attached to an individual constant current sink. Also, the LEDs are not controlled by PWM - they are driven at a constant current.

==Other uses for LED controllers==

LED controllers are typically just a set of special digital outputs. This means they aren't limited to just controlling LEDs. They can be used to control relays, solenoids and even very small motors. The PhidgetLED can also be used to drive opto-isolators and MOSFET SSRs. A diode integrated into the 1031 on each cathode will clamp inductive surges to the anode supply voltage.

==Power Requirements and Power Supply Selection==

The power supply that is included with the 1031 is rated at 12V and 2A (max). If your application requires more power, a larger power supply may be necessary. The on-board voltage regulator is able to supply up to 6A for each LED supply voltage setting, as long as the power supply is able to provide enough voltage and current to the regulator. Assume an efficiency of 80% for the on-board voltage regulator when determining if a different power supply is required.

==Heat Dissipation and Thermal Protection==

Projects that require a high supply voltage, or have a lot of heat being produced from over voltage settings, will have over-temperature problems. This can be mitigated somewhat by understanding how channels are grouped and how the heat is distributed around the controller. On the 1031 channels are split into four groups: (0-7,24-31), (8-23), (32-39, 56-63) and (40-55); each controlled by their own individual IC. Evenly distributing the LEDs that may produce a lot of heat across these groups will balance the load on the ICs and reduce the risk of thermal overload. When thermal overload occurs, the integrated circuit (IC) controlling the involved LEDs will disable the output of all the channels it controls. For example, if an over-temperature occurs due to channel 12, all of the channels 8 through 23 will be disabled by the IC until the temperature back within the operating range. Thermal protection is activated when the die of the IC reaches approximately 160 degrees Celsius. Once the over-temperature fault has been corrected (ie, the IC has cooled down), the output channels will be re-enabled with the same settings as before the thermal shutdown. An error message will be produced during an over-temperature.

==Products that fall under this category==

*[{{SERVER}}/products.php?product_id=1031 1031 - PhidgetLED-64 Advanced]

*[{{SERVER}}/products.php?product_id=3601 3601 - 10mm Red LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3602 3602 - 10mm Green LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3603 3603 - 10mm Blue LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3604 3604 - 10mm Yellow LED (Bag of 20)]
*[{{SERVER}}/products.php?product_id=3605 3605 - 10mm White LED (Bag of 20)]

*[{{SERVER}}/products.php?product_id=3606 3606 - 5mm Four Chip Super Flux Red (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3607 3607 - 5mm Four Chip Super Flux Green (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3608 3608 - 5mm Four Chip Super Flux Blue (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3609 3609 - 5mm Four Chip Super Flux Yellow (Bag of 5)]
*[{{SERVER}}/products.php?product_id=3610 3610 - 5mm Four Chip Super Flux White (Bag of 5)]

*[{{SERVER}}/products.php?product_id=3611 3611 - 5mm Diffused Red (Bag of 30)]
*[{{SERVER}}/products.php?product_id=3612 3612 - 5mm Diffused Yellow/Green (Bag of 30)]
*[{{SERVER}}/products.php?product_id=3613 - 5mm Diffused Blue (Bag of 30)]

*[{{SERVER}}/products.php?product_id=3614 3614 - Flexible LED Strip Green (5m)]
*[{{SERVER}}/products.php?product_id=3615 3615 - Flexible LED Strip Blue (5m)]
*[{{SERVER}}/products.php?product_id=3616 3616 - Flexible LED Strip White (5m)]

*[{{SERVER}}/products.php?product_id=3618 3618 - RGB LED Modules - String of 10]

General Phidget Programming

2012-06-29T17:49:31Z

Cora: /* Creating a Software Object */

[[Category:Overview]]
__TOC__

This page presents the general '''concepts''' needed to write code for a Phidget.

By this point, you should have installed the drivers for your [[Software Overview#Operating System Support|operating system]] and the libraries for your [[Software Overview#Language Support|specific programming language]].

==The Basic Functions==

To use your Phidget within code, you'll want to:
# Create a Phidget [[#Creating a Software Object|software <code>object</code>]], which gives you access to the functions specific to that device
# [[#Opening the Phidget|Open the Phidget]] using the <code>object</code>
# Detect when a [[#Attaching the Phidget|Phidget is attached]] (plugged in) by using the <code>object</code>
# Use [[#Do Things with the Phidget|functions that the <code>object</code> provides]], like turning on LEDs, reading sensors, triggering events on data change, etc
# [[#Close the Phidget|Close the <code>object</code>]], when you are done

Small code snippets are provided for each step below. [[Language - C/C++|C++]] and [[Language - Java|Java]] were selected because Java is a relatively high-level language and C++ is a relatively low level language, thereby showing how specific each language API really is. So, the most useful resource for the ''actual functions'' would be the API for [[Software Overview#Language Support | your specific language]]. This page is a high-level introduction, by design.

=== Creating a Software Object ===

Phidget devices are controlled using software objects. All software device objects have a common API and set of functions that allow you to '''open''' it, '''close''' it, and set a few listeners to general events such as '''attach''' (plug in), '''detach''' (unplug), and errors.

But when you create an actual software object, it is a software object '''specific''' to your device.

For example, in Java:

<div class="source">
<syntaxhighlight lang=java>

// Create a new Accelerometer object
AccelerometerPhidget device = new AccelerometerPhidget();

</syntaxhighlight>
</div>
<br>
<div class="source">
<syntaxhighlight lang=java>

// Create a new RFID device object
RFIDPhidget device = new RFIDPhidget();

</syntaxhighlight>
</div>

Or in C:

<div class="source">
<syntaxhighlight lang=c>

// Create a new Accelerometer object
CPhidgetAccelerometerHandle device = 0;
CPhidgetAccelerometer_create(&device);

</syntaxhighlight>
</div>
<br>
<div class="source">
<syntaxhighlight lang=c>

// Create a new RFID device object
CPhidgetRFIDHandle device = 0;
CPhidgetRFID_create(&device);

</syntaxhighlight>
</div>

Each software object has an API and available functions which are specific to that device. For example, the RFID device API includes a function to turn on the RFID antenna. The accelerometer device API includes a function to set the sensitivity on each axis. Other APIs control all of our other Phidgets (i.e. those boards with a USB port), with applicable functions.

=== Opening the Phidget ===

Phidgets can either be opened when attached directly to a computer, or they can be opened remotely using the [[Phidget WebService]]. This section deals primarily with opening Phidgets directly.

Once you have created your [[#Creating a Software Object|software object]] for your specific type of device, you can call the <code>open()</code> function in your language on that object. For example, in Java:

<div class="source">
<syntaxhighlight lang=java>
device.open();
</syntaxhighlight>
</div>

Or in C:

<div class="source">
<syntaxhighlight lang=c>
CPhidget_open((CPhidgetHandle) device, -1);
</syntaxhighlight>
</div>

All specific language calls can be found in the API documentation located on each [[Software Overview#Language Support|individual language page]].

The <code>open()</code> function in any language opens the software object for use, not the hardware itself. Having the software "open" before the hardware means that the software can capture all events, including multiple attach (plug in) and detach (unplug) events for one <code>open()</code> call.

====Details for Open()====

Open will return immediately once called, because it can be called even if the Phidget to be used is not attached to the system. This is known as an asynchronous call. It’s important to understand that most calls on a Phidget will fail if they are calls when the Phidget is not attached - in fact the only calls that are allowed on a detached Phidget are <code>close()</code>, <code>waitForAttachment()</code> and <code>getAttached()</code>.

Open is also pervasive. This means that once open has been called, it will constantly try to stay attached to a Phidget. Even if the Phidget is unplugged from the computer and then plugged back in, you will simply get a Detach event, and then an Attach event. It’s a good idea to handle the Detach event in order to avoid calling the Phidget after it has detached.

The different types of open(), such as openAny(), openRemote(), etc. can be used with parameters to try and get the first device it can find, open based on its serial number, or even open across the network. The list all of the available modes that open provides, and the syntax for your language, can be found in the API for [[Software Overview#Language Support|your specific language]]. If there are more than one of the same type of Phidget attached to a computer, and you use open() with no serial number, there is no way of knowing which Phidget will be opened first.

If you are looking to do a remote open call, to use the [[Phidget WebService]], you usually have to change only the open() call (to a remote open call) to change your program from a locally-running one to one that can control a Phidget over the network. We give an in-depth example of using the WebService on each of our [[Software Overview#Operating System Support|operating system pages]], we have a brief overview of the WebService (with code snippets) in the [[#Using Phidgets over a Network|Using Phidgets over a Network]] section, and we often have WebService code snippets on the [[Software Overview#Language Support|language pages]] which do not easily extend from the examples on this page.

'''Note:''' Once a Phidget is opened by an application, it cannot be opened again in another application until closed by the first. When open and attached in software, no other programs or instances can read data from or change the Phidget. This includes it being open via the Windows Control Panel application! The one exception is if the Phidget is controlled ''only'' over the network with the [[Phidget WebService]], and not directly. Then, you can use multiple remote control programs.

=== Attaching the Phidget ===

Physically, attaching a Phidget means plugging it in. The real guts behind the 'attach' command, however, occur within the software libraries. The 'attach' call is what makes the final connections between the opened software object and the corresponding thread and events. This is why all Phidget object must be attached in software, even those that are not actually plugged in with a cable. This includes Phidgets used remotely via our [[Phidget WebService]], it includes Interface Kits on the same board as our Single Board Computer, and it even includes the [[Phidget Manager]] software object, which is a sort of meta-Phidget from which you can [[#Using the Manager|control other Phidgets]].

In your code, you can detect an attachment either with an '''event''' in [[#Event Driven Code|event-driven programming]], or '''waiting''' for it, in [[#Logic Code|logic programming]].

==== Event Attachment ====

For example, to use an event to detect attachment in Java:

<div class="source">
<syntaxhighlight lang=java>
// After creating a Phidget object called "device":
device.addAttachListener(new AttachListener() {
public void attached(AttachEvent ae) {
System.out.println("A new device has been plugged in!");
// Do things after attachment (i.e. read data, control the device)
}
});
</syntaxhighlight>
</div>

Or to use an event to detect attachment in C:

<div class="source">
<syntaxhighlight lang=c>
int AttachHandler (CPhidgetHandle device, void *userData) {
printf("A new device has been plugged in!");
// Do things after attachment (i.e. read data, control the device)
return 0;
}

// .....Then, in the main code after creating a Phidget object "device":
CPhidget_set_OnAttach_Handler((CPhidgetHandle) device, AttachHandler, NULL);
</syntaxhighlight>
</div>

Both of the code snippets above do the same thing. The function <code>AttachHandler(...)</code> is called automatically when a device is plugged in.

You will want to attach events (via <code>addAttachListener()</code> above, for example) '''before you open the Phidget object'''. Otherwise, triggered events may be lost.

This method for using events to detect attachment can be expanded to other events and more complex control flow. Where possible, all example code downloads from the [[Software Overview#Language Support|specific language pages]] shows event-driven programming.

==== Wait for Attachment ====

Waiting for attachment is a straightforward process. Your code does not handle events, it simply waits for a device to be plugged in before moving on and doing something else.

For example, in Java you wait for attachment on a '''created and open''' software object (called device) like this

<div class="source">
<syntaxhighlight lang=java>
// Wait until a device is plugged in
device.waitForAttachment();
// Do things after attachment (i.e. read data, control the device)
</syntaxhighlight>
</div>

Or in C (again, device has been '''created and opened''') :

<div class="source">
<syntaxhighlight lang=c>
int result;
// Wait up to 10000 ms for a device to be plugged in
if((result = CPhidget_waitForAttachment((CPhidgetHandle) device, 10000))) {
// No attachment, error
}
// Successful attachment
// Do things after attachment (i.e. read data, control the device)
</syntaxhighlight>
</div>

So, unlike the event model above, a Phidget software object should be open before waiting for a device to be plugged in.

=== Do Things with the Phidget ===

After you have a [[#Creating a Software Object|properly created]] Phidget software object, you can actually call function to turn LEDs on, change output state, read data from sensors, etc.

The thing you probably want to do with your Phidget is read data from its sensors or inputs. This might be, say, a sensor plugged in to a [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit] used in the code snippets below. You can do this either by detecting changes via [[#Event Driven Code|event driven code]], or polling for new values via [[#Logic Code|logic code]].

'''Details about data handling:'''

*When a Phidget is opened, its initial state will be read before it is marked as attached. This allows polling of many properties -- including some data -- even during the Attach event, and anytime afterwards.

*Your computer can poll much faster than the Phidget can respond. If you poll in a continuous '''<code>while</code>''' loop in byte code, you will probably swamp the Phidget with requests.

*Similarly, if you set a value and then immediately read the value on the next line in your program, the Phidget may not have time to finish the set. In our examples, we use <code>print()</code> statements within loops. Print functions are relatively slow; you can also use <code>wait()</code> or <code>sleep()</code> depending on your language.

*If you are handling data using events as described below, the data event functions will fire when the device is plugged in and its initial state is read.

*Some properties have default values, but these should not be trusted. Remember: '''always set''', don’t rely on defaults. Trying to read an uninitialized value with no default will result in an Exception.

*Usually, sensor 'sensitivity' will '''not''' be 0 (i.e. set to sense all changes) by default. This can be good because it prevents your screen from being completely overloaded with event output. But, depending on the sensor, it may make your sensor seem to have very high lag, and very poor sensitivity. To capture all events, set the sensitivity to 0.

*Often Phidgets will retain their last state unless power is lost. This can give surprising results as the previous state may not always be what you expect. For example, if you open an InterfaceKit and set an output, this output may stay set even after the Phidget is closed.

====Capture Data Change with Events====

To capture data changes in sensors or inputs as they happen, you need to use [[#Event Driven Code|event driven code]].

Like defining an event function that fires [[#Event Attachment|when the Phidget is plugged in]], you can create functions that automatically run when, for example, a sensor value or input value changes.

For example, for an Interface Kit, you can create a function that gets called when a sensor changes. You would do this '''before''' the Phidget software object has been [[#Opening the Phidget|opened]].

In Java, this would look like:
<div class="source">
<syntaxhighlight lang=java>
// After creating a Phidget object called "device":
device.addSensorChangeListener(new SensorChangeListener() {
public void sensorChanged(SensorChangeEvent sensorEvent) {
System.out.println("New Value: " + sensorEvent.getValue());
}
});
</syntaxhighlight>
</div>

Or to use an event to detect attachment in C:

<div class="source">
<syntaxhighlight lang=cpp>
int SensorChangeHandler (CPhidgetHandle device, void *userData, int boardIndex, int newValue) {
printf("New Value %d from sensor at location %d\n", newValue, boardIndex);
return 0;
}

// .....Then, in the main code after creating a Phidget object "device":
CPhidget_set_OnSensorChange_Handler((CPhidgetHandle) device, SensorChangeHandler, NULL);
</syntaxhighlight>
</div>

====Poll for Data Change====

To poll for sensor data, or output state, you usually want to look for a '''get...Value''' or '''get...State''' function available in the API for your device. (The API can be found on the product page for your device on our [{{SERVER}} main web site].) Then, you simply set up a loop that get the value of a sensor continuously.

To poll your software object, the object must be [[#Opening the Phidget|open]]. This is in contrast to the event-driven method above, where all event functions are declared and attached before opening the object.

Note that when you poll the value of a sensor or another attribute, this will probably be within a loop. When you create this loop, the ''more code'' you have within a loop, the ''more slowly'' your loop will run, and the ''more slowly'' you will be sampling the value in practice. This may make you lose data, as described further in the [[#Data Rate|Data Rate]] section.

This effect is also felt with interpreted languages (Java, Python) versus purely compiled languages, as the interpreted languages sample more slowly even within an otherwise completely empty loop.

So if you want to sample as fast as possible, and capture all of the changes that a sensor produces, you should [[#Capture Data Change with Events|capture data with event programming]]. If you choose not to use the event-driven design, you should keep the code run between polls to a minimum. This way you can sample as quickly as possible.

These code snippets assume <code>device</code> is an [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit 8/8/8]. For example, in Java, for the Sensor at location 5 on the board:
<div class="source">
<syntaxhighlight lang=java>
int val;
for (int i = 0; i < 10; i++) {
val = device.getSensorValue(5);
System.out.println("Value: " + val);
}
</syntaxhighlight>
</div>

Or, in C, for the Sensor at location 5 on the Interface Kit board:
<div class="source">
<syntaxhighlight lang=cpp>

int val;
for (int i = 0; i < 10; i++) {
CPhidgetInterfaceKit_getSensorValue(device, 5, &val);
printf("Value: %d\n", val);
}
</syntaxhighlight>
</div>

====Sensors, Input, and Output====

Often, your Phidget will be something like an [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit] which has either analog inputs (black plug holes), or digital inputs and outputs (green screw attachments), or often both.

* To the analog inputs, you can attach various sensors, including sensors for temperature, humidity, light, sound, and so on.
* To the digital inputs, you can attach various input devices, including switches.
* To the digital outputs, you can attach status tools like LEDs.

You use these sensors in software entirely through the software object for the Phidget plugged in to your USB port. For example, to turn off an LED at output block 1 on on an RFID tag reader, you'll want to set the output at location 1 to "0" (or false). In C, this would be:

<div class="source">
<syntaxhighlight lang=cpp>
// Create the RFID software object:
CPhidgetRFIDHandle device = 0;
CPhidgetRFID_create(&device);

// Open and handle the attachment of the PhidgetRFID object
....

// Then, turn the LED off, passing first the output number, then the new state:
CPhidgetRFID_setOutputState(device, 1, 0);
</syntaxhighlight>
</div>

Or in Java, this would be:

<div class="source">
<syntaxhighlight lang=java>
// Create the RFID software object:
RFIDPhidget device = new RFIDPhidget();

// Open and handle the attachment of the RFID object
....

// Then, turn the LED off, passing first the output number, then the new state:
device.setOutputState(1, 0);
</syntaxhighlight>
</div>

Getting a digital input would follow the same pattern, except you would use the getOutputState function and you would not pass the function a new output state.

Getting an analog input is a little more complicated because:
# You must declare the sensor as one of two types (ratiometric or non-ratiometric)
#* To find out which your sensor is, read the product information for your specific sensor on our [{{SERVER}} main web site].
# You must translate the 1-1000 reading that you get from the input into the data that you need (temperature, etc)
#* If the sensor comes from Phidgets, we provide a translation equation in the product information for your specific sensor on our [{{SERVER}} main web site].

Other than that, reading an analog sensor mirrors reading a digital input. For example, to obtain the lux from the [{{SERVER}}/products.php?product_id=1127 - PrecisionLightSensor], a '''non-ratiometric''' sensor plugged into analog input 5, you would do this in C:

<div class="source">
<syntaxhighlight lang=cpp>
// Change measurement to non-ratiometric style
CPhidgetInterfaceKit_setRatiometric(device, 0);

// Get the data from analog input 5
int sensorValue;
CPhidgetInterfaceKit_getSensorValue(device, 5, &sensorValue);

// In this case, the measured light lux equals the sensor value.
int lux = sensorValue;
</syntaxhighlight>
</div>

Or in Java:

<div class="source">
<syntaxhighlight lang=java>
// Change measurement to non-ratiometric style
device.setRatiometric(0);

// Get the data from analog input 5
int sensorValue = getSensorValue(5);

// In this case, the measured light lux equals the sensor value.
int lux = sensorValue;
</syntaxhighlight>
</div>

====Learning Everything You Can Do====

The things you can do with your particular Phidget are many and varied, so we only include general concepts on this page.

You can go one of two places for more information on what functions are available for your specific device. We provide both documentation on the raw API for each programming language as well as a language-independent description of the calls for each device.
* Read the API for your [[Software Overview#Language Support| specific programming language]], available as a download on each page.
* Read the API overview for your hardware, which can be found on its product page on [{{SERVER}} our main website].

=== Close the Phidget ===

When you are finished with the Phidget software object at the end of your program, you should close and (in some languages) delete it.

For example, in Java:
<div class="source">
<syntaxhighlight lang=java>
device.close();
device = null;
</syntaxhighlight>
</div>

Or, in C:
<div class="source">
<syntaxhighlight lang=cpp>
CPhidget_close((CPhidgetHandle) device);
CPhidget_delete((CPhidgetHandle) device);
</syntaxhighlight>
</div>

The <code>close()</code> call removes the lock that [[#Opening the Phidget|open]] put on the Phidget. Make sure to close your object, so other software can use the Phidget!

The close() function also makes sure the thread associated with the Phidget close properly. Any outstanding writes will block close() until they complete, because writes are guaranteed to complete (unless a device is detached).

Also note that a device should be put into a known state before calling close. For example, if a motor controller is driving a motor and close is called, it will continue to drive the motor even though the application has exited. This may or may not be what you want.

===Using Multiple Phidgets===

It is of course possible to use more than one Phidget within your program. The trick lies in using a unique identifier for each one. You can either hard-code the [[#Using the Serial Number|serial number in by hand]] (the number will be on the bottom of the board, or you can run our example code for the Phidget to obtain it on-screen), or you can use the [[#Using the Manager|Phidget Manager within your program]] to detect attached devices and return their serial numbers and Phidget types.

====Using the Serial Number====

Each Phidget has a unique serial number. Using this serial number, you can use a specific [[General Phidget Programming#Opening the Phidget|open]] call to open by serial number.

For example, in Java, this would be:
<div class="source">
<syntaxhighlight lang=java>
device.open(SerialNumber);
</syntaxhighlight>
</div>

Or in C:
<div class="source">
<syntaxhighlight lang=cpp>
CPhidget_open((CPhidgetHandle) device, serialNumber);
</syntaxhighlight>
</div>

====Using the Label====

If you want to have a human-readable way to reference your Phidget (as opposed to a serial number), or to have multiple different Phidgets of the same type with the same handle (for re-usable system code), you can use the Label feature of Phidgets. In many development setups, you can change the label to whatever you like, get the label within your code, and open a Phidget based on its label, for any newer generation Phidget. The disadvantage of Labels is that they are not available on all operating systems and languages.

Some limitations are:
* You cannot '''set''' a label using any language in [[OS - Windows|Windows]], for any language
**However, you can get the label of a Phidget on Windows, and open a Phidget by its label
* [[Language - Android Java|Android Java]] has support for only a subset of the open() functions that use labels, see the [[Language - Android Java|Android Java language page]] for details
* Older Phidgets do not support labels
* No .COM language on Windows supports opening by Label
** This includes [[Language - AutoIt|AutoIt]], [[Language - Adobe Director|Adobe Director]], [[Language - Delphi|Delphi]], and all of the Visual Basic flavours.
* [[Language - LabVIEW|LabVIEW]] cannot open by label
* [[Language - Python|Python]] cannot open by label
* [[Language - LiveCode|LiveCode]] cannot open by label

When opening by label, you would use the {{Code|openLabel("mylabel")}} function (or similar, check the [[Software Overview#Language Support|API for your language]]) rather than the generic open() function.

Note that setting the label should be done by a separate program. On a Mac OS computer, you can set a label through the Phidget Preference Pane. On a Linux computer, you should write a special short program specifically for setting the label. There are two reasons to '''not''' set a label within your main program:
* If you set a label every time you run that program, when not needing to, you can easily reach the 10,000 re-write limit for the flash that stores the label
* If you are using event driven programming, you cannot set the label from any function called from the attach event, as it will hang (on a mutual exclusion lock).
Because of the second point, your special program to set the label on a Phidget should use {{Code|waitForAttach()}} in [[#Logic Code|logic code]] and not [[#Event Driven Code|event-driven]] programming

====Using the Manager====

The Phidget Manager object can detect all Phidgets attached to a system and return their attributes in a list (or array, vector, etc. - depending on the language). With this, you can obtain the serial numbers and types of Phidgets currently attached. This is the preferred method for systems where you will be using multiple Phidgets and expecting the system to operate long enough (or under harsh enough conditions) that the Phidgets would need to be replaced.

This is especially true for running programs [[OS - Phidget SBC#Running a Program Automatically| automatically at scheduled times on the Single Board Computer]], where you would be replacing Phidgets without the benefit of keyboard or screen.

For example, in Java (note for Enumerations you also need to include {{Code|java.util.*}}):

<div class="source">
<syntaxhighlight lang=java>
// Create and open the manager
Manager manager;
manager = new Manager();
try {
manager.open();
} catch (PhidgetException exception) {
printError(exception.getErrorNumber(), exception.getDescription());
}

// Allow the Phidgets time to attach
Thread.sleep(1000);

// Retrieve the list of attached Phidgets from the manager
Vector phidgetList = manager.getPhidgets();

// Use an enumeration to iterate over the vector
// Vectors also have iterators in Java 2
Enumeration phidgetListEnum = phidgetList.elements();
while(phidgetListEnum.hasMoreElements()) {
Phidget phidgetElement = (Phidget)phidgetListEnum.nextElement();
System.out.print(phidgetElement.getDeviceName() + ", ");
System.out.println(phidgetElement.getSerialNumber());
// Store name and serial number into a persistent variable
....
}

// Close the manager
try {
manager.close();
} catch (PhidgetException exception) {
printError(exception.getErrorNumber(), exception.getDescription());
}
manager = null;

// Do something with names and serial numbers stored above (i.e. open and use Phidget objects)
....
</syntaxhighlight>
</div>

Or, in C (note for sleep you also need to include {{Code|unistd.h}}):

<div class="source">
<syntaxhighlight lang=cpp>
// Create and open the manager
CPhidgetManagerHandle manager = 0;
CPhidgetManager_create(&manager);
CPhidgetManager_open((CPhidgetManagerHandle) manager);

// Allow the Phidgets time to attach
sleep(1);

// Retrieve the list of attached Phidgets from the manager
CPhidgetHandle* phidgetList;
int count;

CPhidgetManager_getAttachedDevices((CPhidgetManagerHandle) manager, &phidgetList, &count);

int serialNumber;
const char *name;

// Iterate over the returned Phidget data
int i;
for (i = 0; i < count; i++) {
CPhidget_getDeviceName(phidgetList[i], &name);
CPhidget_getSerialNumber(phidgetList[i], &serialNumber);
printf("%s, %d\n", name, serialNumber);
// Store name and serial number into a persistent variable
....
}

// Use the Phidget API to free the memory in the phidgetList Array
CPhidgetManager_freeAttachedDevicesArray(phidgetList);

// Close the manager
CPhidgetManager_close((CPhidgetManagerHandle) manager);
CPhidgetManager_delete((CPhidgetManagerHandle) manager);

// Do something with names and serial numbers stored above (i.e. open and use Phidget objects)
....
</syntaxhighlight>
</div>

====Distinguishing Events====

If you are using [[#Event Driven Code|event-driven code]], once you have correctly opened multiple Phidgets of different types, they will have different event handlers and hence you will know what Phidget triggered which event.
If you are using multiple Phidgets of the same type, or you are trying to determine within general events (such as Attach Events) which Phidget triggered the event, you can then check the serial number (or device type) of the triggering device and act accordingly.

For example, in Java, your [[General Phidget Programming#Event Attachment|attach event handler]] might look like this:
<div class="source">
<syntaxhighlight lang=java>
detachHandler = new DetachListener() {
public void detached(DetachEvent event) {
int serialNumber = ((Phidget)event.getSource()).getSerialNumber();
// Do something according to serialNumber
} }
</syntaxhighlight>
</div>

Or in C:
<div class="source">
<syntaxhighlight lang=cpp>
int AttachHandler(CPhidgetHandle device, void *userptr) {
int serialNo;
CPhidget_getSerialNumber(device, &serialNo);
// Do something according to serialNumber
}
</syntaxhighlight>
</div>

===Using Phidgets over a Network===

Control of a Phidget over a network uses the Phidget WebService.

We have an in-depth description of the WebService, with images to illustrate its use, on the main [[Phidget WebService]] page.

In the code on the remote computer where you are receiving Phidget data and controlling the Phidget, you would simply use a different open call, and then the Phidget software object will work as if the object were local and normal.

The different, remote open call in C would be:

<div class="source">
<syntaxhighlight lang=cpp>
int serial_number = 37299;
CPhidget_openRemoteIP ((CPhidgetHandle) device, serial_number, "127.0.0.1", 5001, NULL);
</syntaxhighlight>
</div>

This simply uses the same computer in a 'loopback' connection (127.0.0.1) and the default port 5001. You can replace the serial number with your own Phidget's serial number.

And in Java, the different, remote open call would be:

<div class="source">
<syntaxhighlight lang=java>
openAny("127.0.0.1", 5001, null);
</syntaxhighlight>
</div>

There are other options for opening remotely, including by name rather than IP. You can refer to the [[Software Overview#Language Support|API for your language]] for options and specific syntax.

== Putting It Together ==

User and device actions can be handled by either:
*Letting the program tell you when they happen and then doing something ('''event driven''' code)
*Polling for things to happen then doing something ('''logic''' code)

The style of programming you choose (and hence the language you might prefer) would depend on what you want to do with the Phidget. The two sections, [[#Event Driven Code|Event Driven Code]] and [[#Logic Code|Logic Code]] below give benefits, drawbacks, and general examples of each style.

The styles can also mix. For example, you can take a defined set of steps at first such as turning on an LED or antenna (logic code) and then doing nothing until an output change event is fired (event code).

With languages that support both styles, you can mix and match. For languages that support only logic code (see the [[Software Overview#Language Support|Language Support Categories]] above) you can only use the logic paradigm style.

Examples in pseudo-code are given below for each style type so you can see how your language choice can affect your code design.

=== Logic Code ===

Logic code has use for:
* Simple, single-device applications
* Non-GUI applications (GUIs usually are event driven)
* The user driving the device rather than listening to it

Logic code is relatively easy to design well. For example, using the [[#Creating a Software Object|create]], [[#Opening the Phidget|open]], [[#Attaching the Phidget|attach]], [[#Do Things with the Phidget|do stuff]], and [[#Close the Phidget|close]] concepts introduced above, logic code to handle a Phidget might be written like this:

<br>

[[File:logic.png]]

<br>

Although this design does not explicitly capture every event that fires when data or input changes, by polling the device often enough no data will be lost.

However, logic code cannot handle constant, asynchronous events as cleanly as [[#Event Driven Code|event driven code]] can.

These designs can be mixed. So, if you find that in logic code you have a highly complex <code>if</code> loop driving your program, you should consider changing some of it to event driven code. This type of awkward if-loop might look like this:

<div class="source">
<syntaxhighlight lang=cpp>

Create Device Software Object
Open Device

Loop Until Exit Requested {
if No Device Attached {
Wait For Attachment until Timeout
if Wait Timeout Reached {
break
} else {
Initialize Device
}
} else { // Device Is Attached
if Device Data Type 1 Changed {
Do Something
}
if Device Data Type 2 Changed {
Do Something Else
}
// ... More data change functions here
}
Collect User Input
}

Close Device
Delete Device

</syntaxhighlight>
</div>

On the other hand, you can probably see that if your language does not give the option for events, you can use this structure to mimic what events would enable you to do.

=== Event Driven Code ===

Event driven code allows for clean handling of complex, asynchronous programs:
*Handling multiple Phidgets
*Handling active plugging or unplugging of the Phidget (multiple attach and detach events)
*Working behind a GUI, as many GUIs are already event driven
*Capturing all sensor data - or input and output - without constantly polling

''Without'' event driven code, you will need to constantly poll the device to see if any state has changed. If you poll at a slower rate than your input or output changes, you will not capture all data.

However, event driven code is usually not as useful or efficient for:
*Only one open and close event
*Using only one device
*Having the user (or program) ''put'' changes onto the device (in contrast to reading data ''from'' the device)

Event driven code is relatively hard to design well. It may help to draw out a '''flowchart''', '''state machine''', or at least a '''pseudo-code outline''' of your system design and all events you wish to handle before writing code.

The code examples given for each [[Software Overview#Language Support|specific language]] use events if they are supported by the language.

Using the [[#Creating a Software Object|create]], [[#Opening the Phidget|open]], [[#Attaching the Phidget|attach]], [[#Do Things with the Phidget|do stuff]], and [[#Close the Phidget|close]] concepts introduced above, event code to handle a Phidget might be written like this:

[[File:event.png]]

Once you have written this code flow, the actual order of events that occur within the program look something like this:

[[File:Eventhandler.jpg|160px]]

Note that the device itself initiates the function call, by 'firing' the event. This allows you to update only when events fire, and capture all changes, because the low-level interface is telling you when a change occurs.

==Advanced Concepts==

Now that you have the basic [[#Creating a Software Object|create]], [[#Opening the Phidget|open]], [[#Attaching the Phidget|attach]], [[#Do Things with the Phidget|do stuff]], and [[#Close the Phidget|close]] concepts introduced above, there are other useful concepts which will help you design your code to be persistent and stable.

===Logging===

You can enable logging to get more debugging information. Turning on logging happens through a Phidget API function. This would happen at the very start of your program, before even initializing your software object or opening it. Logging lets you get feedback from the Phidget libraries about every Phidget API call you make.

In C, turning on logging to the command line would look like:

<div class="source">
<syntaxhighlight lang=cpp>

CPhidget_enableLogging(PHIDGET_LOG_DEBUG, NULL);

//... All of your Phidget calls. Events called after enable will also log.

CPhidget_disableLogging();
</syntaxhighlight>
</div>

Or in Java:

<div class="source">
<syntaxhighlight lang=java>
enableLogging(PHIDGET_LOG_DEBUG, null);

//...All of your Phidget calls. Events called after enable will also log.

disableLogging();
</syntaxhighlight>
</div>

The use of null is to indicate that the output is not to a file (and hence to the command line). Otherwise, the second argument would be a string filename.

There are six different logging levels, ranging from "Give me Everything!" to "Tell me only about critical problems". The level in the examples above - '''<code>PHIDGET_LOG_DEBUG</code>''' - is a medium output level. For more information about each level and what it gives you, see the API for [[Software Overview#Language Support|your specific language]].

===Threading===

Due to the use of events, the Phidget library uses threading extensively.

For example:
* Calling <code>open()</code> starts a central thread.
* Closing everything will shut that central thread down (before the final close returns).
* Each device, once attached, starts its own read and write threads.

These threads provide the support to perform your typical [[#The Basic Functions|Basic Functions]]:

* Triggering of data events come from the context of a device read thread.
* Attach and detach events come from the context of the central thread.
* The central thread looks for device attaches and detached, keeping track of which devices are attached internally, and sending out attach and detach events to Phidgets and Managers.
* Writes are performed asynchronously by the write thread. The write queue is only 1 deep so calling a write function while there is a write pending will block.

All Phidget libraries are '''thread safe''', so you don’t need to do any locking on the Phidget objects. If you have a GUI, however, or another program with a separate thread, make sure to use one thread for events, and a separate thread with your GUI, and some form of mutual exclusion if they are both writing to the same thing.

===Exceptions and Errors===

There are two different types of errors that you can use to confirm that your program is running correctly.

====One: An error generated by a function call====

These errors are generated by ''you'' calling a function. For example, you might try to read analog sensor port number 150 on a board that only has eight. The function you used to read port 150 would return an error (in C/C++) or throw an error (in languages that support exceptions like Java, .NET, Python, or AS3).

So, these errors happen ''synchronously'' to function calls, that is, they are returned or thrown right after a function returns. You can handle these by checking the return values on your functions (in C/C++) or using an error catching method like <code>try...catch</code> in languages that support exceptions (e.g., Java, .NET, Python, AS3).

For example, in C, you might write a LocalErrorCatcher function that you can then use on every Phidget function call to detect and deal with errors:

<div class="source">
<syntaxhighlight lang=cpp>
int LocalErrorCatcher (int errorCode) {

if (errorCode != 0) { // Everything is okay if errorCode = 0

switch (errorCode) {
default:
const char *errorDescription;
LocalErrorCatcher(
CPhidget_getErrorDescription (errorCode, &errorDescription));
printf("The description for error %d is: %s\n", errorCode, errorDescription);
break;
}
}
return 0;
}

// ... Then, later, you would use it on any Phidget function:
LocalErrorCatcher(
CPhidget_open((CPhidgetHandle) device, -1));

</syntaxhighlight>
</div>

Note that:
# The function LocalErrorCatcher uses itself to check for errors on getting an error description.
# You can handle individual error codes as they are listed in the API. This only prints a general message.

Or in Java, you would try a Phidget function call, and catch any resulting exception that occurs:

<div class="source">
<syntaxhighlight lang=java>
try {
device.openAny();
} catch (PhidgetException exception) {
system.out.println("The description for error " + Integer.toString(exception.getErrorNumber()) +
" is: ", exception.getDescription());
}

</syntaxhighlight>
</div>

Like C above, you could also use a <code>try...catch</code> statement around the exception.getErrorNumber() and exception.getDescription() functions to catch any errors from those calls.

The consequences of not catching this type of error (on ''every'' function) differ by programming language.
In C/C++ these errors must be ''explicitly'' checked for after each function call, otherwise the program will simply continue on in an incorrect state. In languages that support exceptions (e.g., Java, .NET, Python, AS3), errors are returned using exceptions which will leave you no choice but to catch them, or have your program terminate without warning.

====Two: An error generated by an event====

These errors are generated by the Phidget library during runtime. For example, the Phidget device might be experiencing too high a temperature, and trigger an error. This would not necessarily be due to any one function your program called; rather, the error would appear when the problem appears and would trigger an event.

So, these errors happen ''asynchronously'', that is, something happens apart from any function calls and an error event is triggered. You can handle these by setting up an Error Event Handler.

In C, this would look like:

<div class="source">
<syntaxhighlight lang=cpp>
int ErrorEventHandler (CPhidgetHandle device, void *usrptr, int errorCode, const char *errorDescription) {
printf("The description for error %d is: %s\n", errorCode, errorDescription);
// Do something useful based on the error code
return 0;
}

// Actually hook the Error Event Handler in to receive events
LocalErrorCatcher(
CPhidget_set_OnError_Handler((CPhidgetHandle) device, LibraryErrorHandler, NULL));
</syntaxhighlight>
</div>

You'll note that the '''LibraryErrorHandler''' function is what gets called when an error event occurs, and it gives you an opportunity to handle the error.

You'll also note that there is a second function called '''LocalErrorCatcher'''. This second function handles the return value from setting the error handler. We included it here because, as these are examples on how to handle errors, the example would leave a possibly unhandled error without it. This second type of error handling and the '''LocalErrorCatcher''' function are [[#One: An error generated by a function call|described above]].

In Java, it would look like this:

<div class="source">
<syntaxhighlight lang=java>
try {
device.addErrorListener(new ErrorListener() {
public void error(ErrorEvent event) {
System.out.println(event);
}
});
} catch (PhidgetException exception) {
system.out.println("The description for error " + Integer.toString(exception.getErrorNumber()) +
" is: ", exception.getDescription());
}

</syntaxhighlight>
</div>

Like C above, the act of hooking an error listener in to the device can itself generate an error, which should be caught.

These event-type errors are also how a Phidget being run over a network announces bad passwords, lost packets, and other network problems. Locally, the errors can announce incorrect temperatures, current, and power. So, it is in your best interest to set up an error event handler and take action based on the codes and error types in the API [[Software Overview#Language Support|for your programming language]].

See the API for your [[Software Overview#Language Support|specific programming language]] for error code documentation.

===Sensitivity and Filtering===

Change Triggers are used to filter the number of events that are returned to an Application, by setting a minimum amount of activity before a Change Event is sent to your program.

This is a simple hysteresis - a minimum amount of change has to occur since the last event before another event will be fired.

If your application is implementing its own filtering, setting the ChangeTrigger, or '''sensitivity''' to zero will cause all events to fire. Change triggers are generally available only for sensor inputs events. Change triggers are referred to as ''Sensitivity'' in some device-specific APIs.

===Data Rate===

Some devices support a user-defined data rate for events.

* The data rate is set in milliseconds, with a range from up 1ms to 1000ms, depending on the Phidget.
* Data rates greater then 8ms generally need to be a multiple of 8 (8,16,24,...,496,...,996,1000).
* Data rates lower then 8ms are supported as: 4ms, 2ms, 1ms.
* Data rate is a maximum rate
* Data rate will be superseded by a non-zero sensitivity on devices that support both sensitivity and data rate.

See the main page for your device - found on its product page on [{{SERVER}} our main website] for more details on available data rates and specifications.

Note that this data rate '''is not the rate at which you will receive data'''. Rather, it is the amount of time over which events are averaged before being sent. It may help to think of our specification of data rate as an ''averaging time''. This means that setting a data rate of 24 ms will try to give you data averaged over 24 ms, and send it every 24 ms. Depending on your computer, events may or may not be dropped. If events are dropped, the data points that are received still represent 24 ms (or whatever the data rate is set to). This means data is lost.

Conversely, if you are [[#Logic Code|polling]], and you set the data rate to longer than your polling rate, you will receive duplicate, averaged data. For example, setting the data rate to 24 ms and then polling every 12 ms will give you duplicate readings every other poll. To poll and not miss any data, the rate that your code polls must match the rate that you set for the {{Code|setDataRate()}} function in our API.

===Using the Dictionary===

The Phidget Dictionary is a service provided by the Phidget WebService. The dictionary:
* Is a centralized collection of key-value pairs
* Works only over the webservice
* Can be accessed and changed from any number of webservice clients
* Makes use of extended regular expressions (denoted between two forward slashes) for key matching
* Is also a foundation part of the webservice itself, and controls access of all Phidgets through the {{Code|openRemote}} and {{Code|openRemoteIP}} interfaces
* Can be used as an abstracted or higher-level interface for remotely managing Phidgets

We have a more in-depth description of the Dictionary (with pictures) on the main [[Phidget Dictionary]] page.

The intended use for the dictionary is as a central repository for communication and persistent storage of data between several client applications. For example, the computer directly connected to a Phidget could create and change keys for additional events on top of (or even instead of) those already thrown by the Phidget device API. The dictionary API is very high-level and thus very flexible - essentially any application of adding keys, changing keys (and throwing events), and getting values of keys can be handled by the Dictionary.

Note that you should never add or modify a key that starts with {{Code|/PSK/}} or {{Code|/PCK/}} as these are the keys that Phidgets use. Unless, of course, you want to explicitly modify Phidget specific data - and this is highly discouraged, as it’s very easy to break things. Listening to these keys is fine if so desired.

Refer to the API [[Software Overview#Language Support|for your specific language]] for the full Dictionary API.

===Long Term Code Maintenance===

Thinking long term from the start is incredibly useful. Phidgets as a company is constantly developing and inventing, and our API gets improved and changed to still work with older devices while adding support for new ones.

We release library updates - both for operating systems and languages - on a regular basis. We '''strongly''' recommend updating your own libraries as we release them. This goes for both the libraries and the WebService, as the versions must match.

This form of updating (did we mention that we strongly recommend it?) is the single most important thing you can do to reduce maintenance issues with your Phidget software down the road.

Every so often, customers come to us having run the same code for years, without updating. Then, for some reason, they have to update (say, for an operating system migration). And their code no longer works. What do to then? We can work with these customers to find out which of the many updates was the one to cause the problem - a difficult and very time consuming process. And over the course of multiple years, we may no longer stock or even manufacture that particular Phidget. You can imagine that a process with these limitations can take a very long time to resolve, if it can be resolved at all.

Conversely, if you update every time, this time frame is greatly reduced. We make a serious effort to test every library update, and although some backwards-compatibility problems do (rarely) get through, we have a fresh memory of what was changed and can work with you to quickly either debug the new libraries or get you a working version.

In addition to library updates, here are a few other tips and tricks to reduce your maintenance time:
* If you are using [[#Logging|Logging]], don't remove the logging code when you finalize your release. Simply comment it out so you can turn it on again later and debug quickly.
* Some long-term problems can be detected early by listening to library messages and errors. Handling [[#Exceptions and Errors|Exceptions and Errors]] will allow your code to run silently until something is wrong, in which case you'll know right away.

If you are looking for more help on how to work with our library updating, please feel welcome to [[Contact Us|contact us]].

==Summary==

This page has gone through [[#The Basic Functions|basic]] to [[#Advanced Concepts|advanced]] uses of the Phidget API. We've used C and Java here as example languages. If you're using a different language, we include similar snippets of code (without the in-depth description) in the documentation [[Software Overview#Language Support|for your language]].

If you've read this far and are still hungry for more, try learning more about your hardware; we have a number of [[:Category:Primer|hardware learning pages]] as well.

General Phidget Programming

2012-06-29T17:48:15Z

Cora: /* Summary */

[[Category:Overview]]
__TOC__

This page presents the general '''concepts''' needed to write code for a Phidget.

By this point, you should have installed the drivers for your [[Software Overview#Operating System Support|operating system]] and the libraries for your [[Software Overview#Language Support|specific programming language]].

==The Basic Functions==

To use your Phidget within code, you'll want to:
# Create a Phidget [[#Creating a Software Object|software <code>object</code>]], which gives you access to the functions specific to that device
# [[#Opening the Phidget|Open the Phidget]] using the <code>object</code>
# Detect when a [[#Attaching the Phidget|Phidget is attached]] (plugged in) by using the <code>object</code>
# Use [[#Do Things with the Phidget|functions that the <code>object</code> provides]], like turning on LEDs, reading sensors, triggering events on data change, etc
# [[#Close the Phidget|Close the <code>object</code>]], when you are done

Small code snippets are provided for each step below. [[Language - C/C++|C++]] and [[Language - Java|Java]] were selected because Java is a relatively high-level language and C++ is a relatively low level language, thereby showing how specific each language API really is. So, the most useful resource for the ''actual functions'' would be the API for [[Software Overview#Language Support | your specific language]]. This page is a high-level introduction, by design.

=== Creating a Software Object ===

Phidget devices are controlled using software objects. All software device objects have a common API and set of functions that allow you to '''open''' it, '''close''' it, and set a few listeners to general events such as '''attach''' (plug in), '''detach''' (unplug), and errors.

But when you create an actual software object, it is a software object '''specific''' to your device.

For example, in Java:

<div class="source">
<syntaxhighlight lang=java>

// Create a new Accelerometer object
AccelerometerPhidget device = new AccelerometerPhidget();

</syntaxhighlight>
</div>
<br>
<div class="source">
<syntaxhighlight lang=java>

// Create a new RFID device object
RFIDPhidget device = new RFIDPhidget();

</syntaxhighlight>
</div>

Or in C:

<div class="source">
<syntaxhighlight lang=c>

// Create a new Accelerometer object
CPhidgetAccelerometerHandle device = 0;
CPhidgetAccelerometer_create(&device);

</syntaxhighlight>
</div>
<br>
<div class="source">
<syntaxhighlight lang=c>

// Create a new RFID device object
CPhidgetRFIDHandle device = 0;
CPhidgetRFID_create(&device);

</syntaxhighlight>
</div>

Each software object has an API and available functions which are specific to that device. For example, the RFID device API includes a function to turn on the RFID antenna. The accelerometer device API includes a function to set the sensitivity on each axis.

=== Opening the Phidget ===

Phidgets can either be opened when attached directly to a computer, or they can be opened remotely using the [[Phidget WebService]]. This section deals primarily with opening Phidgets directly.

Once you have created your [[#Creating a Software Object|software object]] for your specific type of device, you can call the <code>open()</code> function in your language on that object. For example, in Java:

<div class="source">
<syntaxhighlight lang=java>
device.open();
</syntaxhighlight>
</div>

Or in C:

<div class="source">
<syntaxhighlight lang=c>
CPhidget_open((CPhidgetHandle) device, -1);
</syntaxhighlight>
</div>

All specific language calls can be found in the API documentation located on each [[Software Overview#Language Support|individual language page]].

The <code>open()</code> function in any language opens the software object for use, not the hardware itself. Having the software "open" before the hardware means that the software can capture all events, including multiple attach (plug in) and detach (unplug) events for one <code>open()</code> call.

====Details for Open()====

Open will return immediately once called, because it can be called even if the Phidget to be used is not attached to the system. This is known as an asynchronous call. It’s important to understand that most calls on a Phidget will fail if they are calls when the Phidget is not attached - in fact the only calls that are allowed on a detached Phidget are <code>close()</code>, <code>waitForAttachment()</code> and <code>getAttached()</code>.

Open is also pervasive. This means that once open has been called, it will constantly try to stay attached to a Phidget. Even if the Phidget is unplugged from the computer and then plugged back in, you will simply get a Detach event, and then an Attach event. It’s a good idea to handle the Detach event in order to avoid calling the Phidget after it has detached.

The different types of open(), such as openAny(), openRemote(), etc. can be used with parameters to try and get the first device it can find, open based on its serial number, or even open across the network. The list all of the available modes that open provides, and the syntax for your language, can be found in the API for [[Software Overview#Language Support|your specific language]]. If there are more than one of the same type of Phidget attached to a computer, and you use open() with no serial number, there is no way of knowing which Phidget will be opened first.

If you are looking to do a remote open call, to use the [[Phidget WebService]], you usually have to change only the open() call (to a remote open call) to change your program from a locally-running one to one that can control a Phidget over the network. We give an in-depth example of using the WebService on each of our [[Software Overview#Operating System Support|operating system pages]], we have a brief overview of the WebService (with code snippets) in the [[#Using Phidgets over a Network|Using Phidgets over a Network]] section, and we often have WebService code snippets on the [[Software Overview#Language Support|language pages]] which do not easily extend from the examples on this page.

'''Note:''' Once a Phidget is opened by an application, it cannot be opened again in another application until closed by the first. When open and attached in software, no other programs or instances can read data from or change the Phidget. This includes it being open via the Windows Control Panel application! The one exception is if the Phidget is controlled ''only'' over the network with the [[Phidget WebService]], and not directly. Then, you can use multiple remote control programs.

=== Attaching the Phidget ===

Physically, attaching a Phidget means plugging it in. The real guts behind the 'attach' command, however, occur within the software libraries. The 'attach' call is what makes the final connections between the opened software object and the corresponding thread and events. This is why all Phidget object must be attached in software, even those that are not actually plugged in with a cable. This includes Phidgets used remotely via our [[Phidget WebService]], it includes Interface Kits on the same board as our Single Board Computer, and it even includes the [[Phidget Manager]] software object, which is a sort of meta-Phidget from which you can [[#Using the Manager|control other Phidgets]].

In your code, you can detect an attachment either with an '''event''' in [[#Event Driven Code|event-driven programming]], or '''waiting''' for it, in [[#Logic Code|logic programming]].

==== Event Attachment ====

For example, to use an event to detect attachment in Java:

<div class="source">
<syntaxhighlight lang=java>
// After creating a Phidget object called "device":
device.addAttachListener(new AttachListener() {
public void attached(AttachEvent ae) {
System.out.println("A new device has been plugged in!");
// Do things after attachment (i.e. read data, control the device)
}
});
</syntaxhighlight>
</div>

Or to use an event to detect attachment in C:

<div class="source">
<syntaxhighlight lang=c>
int AttachHandler (CPhidgetHandle device, void *userData) {
printf("A new device has been plugged in!");
// Do things after attachment (i.e. read data, control the device)
return 0;
}

// .....Then, in the main code after creating a Phidget object "device":
CPhidget_set_OnAttach_Handler((CPhidgetHandle) device, AttachHandler, NULL);
</syntaxhighlight>
</div>

Both of the code snippets above do the same thing. The function <code>AttachHandler(...)</code> is called automatically when a device is plugged in.

You will want to attach events (via <code>addAttachListener()</code> above, for example) '''before you open the Phidget object'''. Otherwise, triggered events may be lost.

This method for using events to detect attachment can be expanded to other events and more complex control flow. Where possible, all example code downloads from the [[Software Overview#Language Support|specific language pages]] shows event-driven programming.

==== Wait for Attachment ====

Waiting for attachment is a straightforward process. Your code does not handle events, it simply waits for a device to be plugged in before moving on and doing something else.

For example, in Java you wait for attachment on a '''created and open''' software object (called device) like this

<div class="source">
<syntaxhighlight lang=java>
// Wait until a device is plugged in
device.waitForAttachment();
// Do things after attachment (i.e. read data, control the device)
</syntaxhighlight>
</div>

Or in C (again, device has been '''created and opened''') :

<div class="source">
<syntaxhighlight lang=c>
int result;
// Wait up to 10000 ms for a device to be plugged in
if((result = CPhidget_waitForAttachment((CPhidgetHandle) device, 10000))) {
// No attachment, error
}
// Successful attachment
// Do things after attachment (i.e. read data, control the device)
</syntaxhighlight>
</div>

So, unlike the event model above, a Phidget software object should be open before waiting for a device to be plugged in.

=== Do Things with the Phidget ===

After you have a [[#Creating a Software Object|properly created]] Phidget software object, you can actually call function to turn LEDs on, change output state, read data from sensors, etc.

The thing you probably want to do with your Phidget is read data from its sensors or inputs. This might be, say, a sensor plugged in to a [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit] used in the code snippets below. You can do this either by detecting changes via [[#Event Driven Code|event driven code]], or polling for new values via [[#Logic Code|logic code]].

'''Details about data handling:'''

*When a Phidget is opened, its initial state will be read before it is marked as attached. This allows polling of many properties -- including some data -- even during the Attach event, and anytime afterwards.

*Your computer can poll much faster than the Phidget can respond. If you poll in a continuous '''<code>while</code>''' loop in byte code, you will probably swamp the Phidget with requests.

*Similarly, if you set a value and then immediately read the value on the next line in your program, the Phidget may not have time to finish the set. In our examples, we use <code>print()</code> statements within loops. Print functions are relatively slow; you can also use <code>wait()</code> or <code>sleep()</code> depending on your language.

*If you are handling data using events as described below, the data event functions will fire when the device is plugged in and its initial state is read.

*Some properties have default values, but these should not be trusted. Remember: '''always set''', don’t rely on defaults. Trying to read an uninitialized value with no default will result in an Exception.

*Usually, sensor 'sensitivity' will '''not''' be 0 (i.e. set to sense all changes) by default. This can be good because it prevents your screen from being completely overloaded with event output. But, depending on the sensor, it may make your sensor seem to have very high lag, and very poor sensitivity. To capture all events, set the sensitivity to 0.

*Often Phidgets will retain their last state unless power is lost. This can give surprising results as the previous state may not always be what you expect. For example, if you open an InterfaceKit and set an output, this output may stay set even after the Phidget is closed.

====Capture Data Change with Events====

To capture data changes in sensors or inputs as they happen, you need to use [[#Event Driven Code|event driven code]].

Like defining an event function that fires [[#Event Attachment|when the Phidget is plugged in]], you can create functions that automatically run when, for example, a sensor value or input value changes.

For example, for an Interface Kit, you can create a function that gets called when a sensor changes. You would do this '''before''' the Phidget software object has been [[#Opening the Phidget|opened]].

In Java, this would look like:
<div class="source">
<syntaxhighlight lang=java>
// After creating a Phidget object called "device":
device.addSensorChangeListener(new SensorChangeListener() {
public void sensorChanged(SensorChangeEvent sensorEvent) {
System.out.println("New Value: " + sensorEvent.getValue());
}
});
</syntaxhighlight>
</div>

Or to use an event to detect attachment in C:

<div class="source">
<syntaxhighlight lang=cpp>
int SensorChangeHandler (CPhidgetHandle device, void *userData, int boardIndex, int newValue) {
printf("New Value %d from sensor at location %d\n", newValue, boardIndex);
return 0;
}

// .....Then, in the main code after creating a Phidget object "device":
CPhidget_set_OnSensorChange_Handler((CPhidgetHandle) device, SensorChangeHandler, NULL);
</syntaxhighlight>
</div>

====Poll for Data Change====

To poll for sensor data, or output state, you usually want to look for a '''get...Value''' or '''get...State''' function available in the API for your device. (The API can be found on the product page for your device on our [{{SERVER}} main web site].) Then, you simply set up a loop that get the value of a sensor continuously.

To poll your software object, the object must be [[#Opening the Phidget|open]]. This is in contrast to the event-driven method above, where all event functions are declared and attached before opening the object.

Note that when you poll the value of a sensor or another attribute, this will probably be within a loop. When you create this loop, the ''more code'' you have within a loop, the ''more slowly'' your loop will run, and the ''more slowly'' you will be sampling the value in practice. This may make you lose data, as described further in the [[#Data Rate|Data Rate]] section.

This effect is also felt with interpreted languages (Java, Python) versus purely compiled languages, as the interpreted languages sample more slowly even within an otherwise completely empty loop.

So if you want to sample as fast as possible, and capture all of the changes that a sensor produces, you should [[#Capture Data Change with Events|capture data with event programming]]. If you choose not to use the event-driven design, you should keep the code run between polls to a minimum. This way you can sample as quickly as possible.

These code snippets assume <code>device</code> is an [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit 8/8/8]. For example, in Java, for the Sensor at location 5 on the board:
<div class="source">
<syntaxhighlight lang=java>
int val;
for (int i = 0; i < 10; i++) {
val = device.getSensorValue(5);
System.out.println("Value: " + val);
}
</syntaxhighlight>
</div>

Or, in C, for the Sensor at location 5 on the Interface Kit board:
<div class="source">
<syntaxhighlight lang=cpp>

int val;
for (int i = 0; i < 10; i++) {
CPhidgetInterfaceKit_getSensorValue(device, 5, &val);
printf("Value: %d\n", val);
}
</syntaxhighlight>
</div>

====Sensors, Input, and Output====

Often, your Phidget will be something like an [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit] which has either analog inputs (black plug holes), or digital inputs and outputs (green screw attachments), or often both.

* To the analog inputs, you can attach various sensors, including sensors for temperature, humidity, light, sound, and so on.
* To the digital inputs, you can attach various input devices, including switches.
* To the digital outputs, you can attach status tools like LEDs.

You use these sensors in software entirely through the software object for the Phidget plugged in to your USB port. For example, to turn off an LED at output block 1 on on an RFID tag reader, you'll want to set the output at location 1 to "0" (or false). In C, this would be:

<div class="source">
<syntaxhighlight lang=cpp>
// Create the RFID software object:
CPhidgetRFIDHandle device = 0;
CPhidgetRFID_create(&device);

// Open and handle the attachment of the PhidgetRFID object
....

// Then, turn the LED off, passing first the output number, then the new state:
CPhidgetRFID_setOutputState(device, 1, 0);
</syntaxhighlight>
</div>

Or in Java, this would be:

<div class="source">
<syntaxhighlight lang=java>
// Create the RFID software object:
RFIDPhidget device = new RFIDPhidget();

// Open and handle the attachment of the RFID object
....

// Then, turn the LED off, passing first the output number, then the new state:
device.setOutputState(1, 0);
</syntaxhighlight>
</div>

Getting a digital input would follow the same pattern, except you would use the getOutputState function and you would not pass the function a new output state.

Getting an analog input is a little more complicated because:
# You must declare the sensor as one of two types (ratiometric or non-ratiometric)
#* To find out which your sensor is, read the product information for your specific sensor on our [{{SERVER}} main web site].
# You must translate the 1-1000 reading that you get from the input into the data that you need (temperature, etc)
#* If the sensor comes from Phidgets, we provide a translation equation in the product information for your specific sensor on our [{{SERVER}} main web site].

Other than that, reading an analog sensor mirrors reading a digital input. For example, to obtain the lux from the [{{SERVER}}/products.php?product_id=1127 - PrecisionLightSensor], a '''non-ratiometric''' sensor plugged into analog input 5, you would do this in C:

<div class="source">
<syntaxhighlight lang=cpp>
// Change measurement to non-ratiometric style
CPhidgetInterfaceKit_setRatiometric(device, 0);

// Get the data from analog input 5
int sensorValue;
CPhidgetInterfaceKit_getSensorValue(device, 5, &sensorValue);

// In this case, the measured light lux equals the sensor value.
int lux = sensorValue;
</syntaxhighlight>
</div>

Or in Java:

<div class="source">
<syntaxhighlight lang=java>
// Change measurement to non-ratiometric style
device.setRatiometric(0);

// Get the data from analog input 5
int sensorValue = getSensorValue(5);

// In this case, the measured light lux equals the sensor value.
int lux = sensorValue;
</syntaxhighlight>
</div>

====Learning Everything You Can Do====

The things you can do with your particular Phidget are many and varied, so we only include general concepts on this page.

You can go one of two places for more information on what functions are available for your specific device. We provide both documentation on the raw API for each programming language as well as a language-independent description of the calls for each device.
* Read the API for your [[Software Overview#Language Support| specific programming language]], available as a download on each page.
* Read the API overview for your hardware, which can be found on its product page on [{{SERVER}} our main website].

=== Close the Phidget ===

When you are finished with the Phidget software object at the end of your program, you should close and (in some languages) delete it.

For example, in Java:
<div class="source">
<syntaxhighlight lang=java>
device.close();
device = null;
</syntaxhighlight>
</div>

Or, in C:
<div class="source">
<syntaxhighlight lang=cpp>
CPhidget_close((CPhidgetHandle) device);
CPhidget_delete((CPhidgetHandle) device);
</syntaxhighlight>
</div>

The <code>close()</code> call removes the lock that [[#Opening the Phidget|open]] put on the Phidget. Make sure to close your object, so other software can use the Phidget!

The close() function also makes sure the thread associated with the Phidget close properly. Any outstanding writes will block close() until they complete, because writes are guaranteed to complete (unless a device is detached).

Also note that a device should be put into a known state before calling close. For example, if a motor controller is driving a motor and close is called, it will continue to drive the motor even though the application has exited. This may or may not be what you want.

===Using Multiple Phidgets===

It is of course possible to use more than one Phidget within your program. The trick lies in using a unique identifier for each one. You can either hard-code the [[#Using the Serial Number|serial number in by hand]] (the number will be on the bottom of the board, or you can run our example code for the Phidget to obtain it on-screen), or you can use the [[#Using the Manager|Phidget Manager within your program]] to detect attached devices and return their serial numbers and Phidget types.

====Using the Serial Number====

Each Phidget has a unique serial number. Using this serial number, you can use a specific [[General Phidget Programming#Opening the Phidget|open]] call to open by serial number.

For example, in Java, this would be:
<div class="source">
<syntaxhighlight lang=java>
device.open(SerialNumber);
</syntaxhighlight>
</div>

Or in C:
<div class="source">
<syntaxhighlight lang=cpp>
CPhidget_open((CPhidgetHandle) device, serialNumber);
</syntaxhighlight>
</div>

====Using the Label====

If you want to have a human-readable way to reference your Phidget (as opposed to a serial number), or to have multiple different Phidgets of the same type with the same handle (for re-usable system code), you can use the Label feature of Phidgets. In many development setups, you can change the label to whatever you like, get the label within your code, and open a Phidget based on its label, for any newer generation Phidget. The disadvantage of Labels is that they are not available on all operating systems and languages.

Some limitations are:
* You cannot '''set''' a label using any language in [[OS - Windows|Windows]], for any language
**However, you can get the label of a Phidget on Windows, and open a Phidget by its label
* [[Language - Android Java|Android Java]] has support for only a subset of the open() functions that use labels, see the [[Language - Android Java|Android Java language page]] for details
* Older Phidgets do not support labels
* No .COM language on Windows supports opening by Label
** This includes [[Language - AutoIt|AutoIt]], [[Language - Adobe Director|Adobe Director]], [[Language - Delphi|Delphi]], and all of the Visual Basic flavours.
* [[Language - LabVIEW|LabVIEW]] cannot open by label
* [[Language - Python|Python]] cannot open by label
* [[Language - LiveCode|LiveCode]] cannot open by label

When opening by label, you would use the {{Code|openLabel("mylabel")}} function (or similar, check the [[Software Overview#Language Support|API for your language]]) rather than the generic open() function.

Note that setting the label should be done by a separate program. On a Mac OS computer, you can set a label through the Phidget Preference Pane. On a Linux computer, you should write a special short program specifically for setting the label. There are two reasons to '''not''' set a label within your main program:
* If you set a label every time you run that program, when not needing to, you can easily reach the 10,000 re-write limit for the flash that stores the label
* If you are using event driven programming, you cannot set the label from any function called from the attach event, as it will hang (on a mutual exclusion lock).
Because of the second point, your special program to set the label on a Phidget should use {{Code|waitForAttach()}} in [[#Logic Code|logic code]] and not [[#Event Driven Code|event-driven]] programming

====Using the Manager====

The Phidget Manager object can detect all Phidgets attached to a system and return their attributes in a list (or array, vector, etc. - depending on the language). With this, you can obtain the serial numbers and types of Phidgets currently attached. This is the preferred method for systems where you will be using multiple Phidgets and expecting the system to operate long enough (or under harsh enough conditions) that the Phidgets would need to be replaced.

This is especially true for running programs [[OS - Phidget SBC#Running a Program Automatically| automatically at scheduled times on the Single Board Computer]], where you would be replacing Phidgets without the benefit of keyboard or screen.

For example, in Java (note for Enumerations you also need to include {{Code|java.util.*}}):

<div class="source">
<syntaxhighlight lang=java>
// Create and open the manager
Manager manager;
manager = new Manager();
try {
manager.open();
} catch (PhidgetException exception) {
printError(exception.getErrorNumber(), exception.getDescription());
}

// Allow the Phidgets time to attach
Thread.sleep(1000);

// Retrieve the list of attached Phidgets from the manager
Vector phidgetList = manager.getPhidgets();

// Use an enumeration to iterate over the vector
// Vectors also have iterators in Java 2
Enumeration phidgetListEnum = phidgetList.elements();
while(phidgetListEnum.hasMoreElements()) {
Phidget phidgetElement = (Phidget)phidgetListEnum.nextElement();
System.out.print(phidgetElement.getDeviceName() + ", ");
System.out.println(phidgetElement.getSerialNumber());
// Store name and serial number into a persistent variable
....
}

// Close the manager
try {
manager.close();
} catch (PhidgetException exception) {
printError(exception.getErrorNumber(), exception.getDescription());
}
manager = null;

// Do something with names and serial numbers stored above (i.e. open and use Phidget objects)
....
</syntaxhighlight>
</div>

Or, in C (note for sleep you also need to include {{Code|unistd.h}}):

<div class="source">
<syntaxhighlight lang=cpp>
// Create and open the manager
CPhidgetManagerHandle manager = 0;
CPhidgetManager_create(&manager);
CPhidgetManager_open((CPhidgetManagerHandle) manager);

// Allow the Phidgets time to attach
sleep(1);

// Retrieve the list of attached Phidgets from the manager
CPhidgetHandle* phidgetList;
int count;

CPhidgetManager_getAttachedDevices((CPhidgetManagerHandle) manager, &phidgetList, &count);

int serialNumber;
const char *name;

// Iterate over the returned Phidget data
int i;
for (i = 0; i < count; i++) {
CPhidget_getDeviceName(phidgetList[i], &name);
CPhidget_getSerialNumber(phidgetList[i], &serialNumber);
printf("%s, %d\n", name, serialNumber);
// Store name and serial number into a persistent variable
....
}

// Use the Phidget API to free the memory in the phidgetList Array
CPhidgetManager_freeAttachedDevicesArray(phidgetList);

// Close the manager
CPhidgetManager_close((CPhidgetManagerHandle) manager);
CPhidgetManager_delete((CPhidgetManagerHandle) manager);

// Do something with names and serial numbers stored above (i.e. open and use Phidget objects)
....
</syntaxhighlight>
</div>

====Distinguishing Events====

If you are using [[#Event Driven Code|event-driven code]], once you have correctly opened multiple Phidgets of different types, they will have different event handlers and hence you will know what Phidget triggered which event.
If you are using multiple Phidgets of the same type, or you are trying to determine within general events (such as Attach Events) which Phidget triggered the event, you can then check the serial number (or device type) of the triggering device and act accordingly.

For example, in Java, your [[General Phidget Programming#Event Attachment|attach event handler]] might look like this:
<div class="source">
<syntaxhighlight lang=java>
detachHandler = new DetachListener() {
public void detached(DetachEvent event) {
int serialNumber = ((Phidget)event.getSource()).getSerialNumber();
// Do something according to serialNumber
} }
</syntaxhighlight>
</div>

Or in C:
<div class="source">
<syntaxhighlight lang=cpp>
int AttachHandler(CPhidgetHandle device, void *userptr) {
int serialNo;
CPhidget_getSerialNumber(device, &serialNo);
// Do something according to serialNumber
}
</syntaxhighlight>
</div>

===Using Phidgets over a Network===

Control of a Phidget over a network uses the Phidget WebService.

We have an in-depth description of the WebService, with images to illustrate its use, on the main [[Phidget WebService]] page.

In the code on the remote computer where you are receiving Phidget data and controlling the Phidget, you would simply use a different open call, and then the Phidget software object will work as if the object were local and normal.

The different, remote open call in C would be:

<div class="source">
<syntaxhighlight lang=cpp>
int serial_number = 37299;
CPhidget_openRemoteIP ((CPhidgetHandle) device, serial_number, "127.0.0.1", 5001, NULL);
</syntaxhighlight>
</div>

This simply uses the same computer in a 'loopback' connection (127.0.0.1) and the default port 5001. You can replace the serial number with your own Phidget's serial number.

And in Java, the different, remote open call would be:

<div class="source">
<syntaxhighlight lang=java>
openAny("127.0.0.1", 5001, null);
</syntaxhighlight>
</div>

There are other options for opening remotely, including by name rather than IP. You can refer to the [[Software Overview#Language Support|API for your language]] for options and specific syntax.

== Putting It Together ==

User and device actions can be handled by either:
*Letting the program tell you when they happen and then doing something ('''event driven''' code)
*Polling for things to happen then doing something ('''logic''' code)

The style of programming you choose (and hence the language you might prefer) would depend on what you want to do with the Phidget. The two sections, [[#Event Driven Code|Event Driven Code]] and [[#Logic Code|Logic Code]] below give benefits, drawbacks, and general examples of each style.

The styles can also mix. For example, you can take a defined set of steps at first such as turning on an LED or antenna (logic code) and then doing nothing until an output change event is fired (event code).

With languages that support both styles, you can mix and match. For languages that support only logic code (see the [[Software Overview#Language Support|Language Support Categories]] above) you can only use the logic paradigm style.

Examples in pseudo-code are given below for each style type so you can see how your language choice can affect your code design.

=== Logic Code ===

Logic code has use for:
* Simple, single-device applications
* Non-GUI applications (GUIs usually are event driven)
* The user driving the device rather than listening to it

Logic code is relatively easy to design well. For example, using the [[#Creating a Software Object|create]], [[#Opening the Phidget|open]], [[#Attaching the Phidget|attach]], [[#Do Things with the Phidget|do stuff]], and [[#Close the Phidget|close]] concepts introduced above, logic code to handle a Phidget might be written like this:

<br>

[[File:logic.png]]

<br>

Although this design does not explicitly capture every event that fires when data or input changes, by polling the device often enough no data will be lost.

However, logic code cannot handle constant, asynchronous events as cleanly as [[#Event Driven Code|event driven code]] can.

These designs can be mixed. So, if you find that in logic code you have a highly complex <code>if</code> loop driving your program, you should consider changing some of it to event driven code. This type of awkward if-loop might look like this:

<div class="source">
<syntaxhighlight lang=cpp>

Create Device Software Object
Open Device

Loop Until Exit Requested {
if No Device Attached {
Wait For Attachment until Timeout
if Wait Timeout Reached {
break
} else {
Initialize Device
}
} else { // Device Is Attached
if Device Data Type 1 Changed {
Do Something
}
if Device Data Type 2 Changed {
Do Something Else
}
// ... More data change functions here
}
Collect User Input
}

Close Device
Delete Device

</syntaxhighlight>
</div>

On the other hand, you can probably see that if your language does not give the option for events, you can use this structure to mimic what events would enable you to do.

=== Event Driven Code ===

Event driven code allows for clean handling of complex, asynchronous programs:
*Handling multiple Phidgets
*Handling active plugging or unplugging of the Phidget (multiple attach and detach events)
*Working behind a GUI, as many GUIs are already event driven
*Capturing all sensor data - or input and output - without constantly polling

''Without'' event driven code, you will need to constantly poll the device to see if any state has changed. If you poll at a slower rate than your input or output changes, you will not capture all data.

However, event driven code is usually not as useful or efficient for:
*Only one open and close event
*Using only one device
*Having the user (or program) ''put'' changes onto the device (in contrast to reading data ''from'' the device)

Event driven code is relatively hard to design well. It may help to draw out a '''flowchart''', '''state machine''', or at least a '''pseudo-code outline''' of your system design and all events you wish to handle before writing code.

The code examples given for each [[Software Overview#Language Support|specific language]] use events if they are supported by the language.

Using the [[#Creating a Software Object|create]], [[#Opening the Phidget|open]], [[#Attaching the Phidget|attach]], [[#Do Things with the Phidget|do stuff]], and [[#Close the Phidget|close]] concepts introduced above, event code to handle a Phidget might be written like this:

[[File:event.png]]

Once you have written this code flow, the actual order of events that occur within the program look something like this:

[[File:Eventhandler.jpg|160px]]

Note that the device itself initiates the function call, by 'firing' the event. This allows you to update only when events fire, and capture all changes, because the low-level interface is telling you when a change occurs.

==Advanced Concepts==

Now that you have the basic [[#Creating a Software Object|create]], [[#Opening the Phidget|open]], [[#Attaching the Phidget|attach]], [[#Do Things with the Phidget|do stuff]], and [[#Close the Phidget|close]] concepts introduced above, there are other useful concepts which will help you design your code to be persistent and stable.

===Logging===

You can enable logging to get more debugging information. Turning on logging happens through a Phidget API function. This would happen at the very start of your program, before even initializing your software object or opening it. Logging lets you get feedback from the Phidget libraries about every Phidget API call you make.

In C, turning on logging to the command line would look like:

<div class="source">
<syntaxhighlight lang=cpp>

CPhidget_enableLogging(PHIDGET_LOG_DEBUG, NULL);

//... All of your Phidget calls. Events called after enable will also log.

CPhidget_disableLogging();
</syntaxhighlight>
</div>

Or in Java:

<div class="source">
<syntaxhighlight lang=java>
enableLogging(PHIDGET_LOG_DEBUG, null);

//...All of your Phidget calls. Events called after enable will also log.

disableLogging();
</syntaxhighlight>
</div>

The use of null is to indicate that the output is not to a file (and hence to the command line). Otherwise, the second argument would be a string filename.

There are six different logging levels, ranging from "Give me Everything!" to "Tell me only about critical problems". The level in the examples above - '''<code>PHIDGET_LOG_DEBUG</code>''' - is a medium output level. For more information about each level and what it gives you, see the API for [[Software Overview#Language Support|your specific language]].

===Threading===

Due to the use of events, the Phidget library uses threading extensively.

For example:
* Calling <code>open()</code> starts a central thread.
* Closing everything will shut that central thread down (before the final close returns).
* Each device, once attached, starts its own read and write threads.

These threads provide the support to perform your typical [[#The Basic Functions|Basic Functions]]:

* Triggering of data events come from the context of a device read thread.
* Attach and detach events come from the context of the central thread.
* The central thread looks for device attaches and detached, keeping track of which devices are attached internally, and sending out attach and detach events to Phidgets and Managers.
* Writes are performed asynchronously by the write thread. The write queue is only 1 deep so calling a write function while there is a write pending will block.

All Phidget libraries are '''thread safe''', so you don’t need to do any locking on the Phidget objects. If you have a GUI, however, or another program with a separate thread, make sure to use one thread for events, and a separate thread with your GUI, and some form of mutual exclusion if they are both writing to the same thing.

===Exceptions and Errors===

There are two different types of errors that you can use to confirm that your program is running correctly.

====One: An error generated by a function call====

These errors are generated by ''you'' calling a function. For example, you might try to read analog sensor port number 150 on a board that only has eight. The function you used to read port 150 would return an error (in C/C++) or throw an error (in languages that support exceptions like Java, .NET, Python, or AS3).

So, these errors happen ''synchronously'' to function calls, that is, they are returned or thrown right after a function returns. You can handle these by checking the return values on your functions (in C/C++) or using an error catching method like <code>try...catch</code> in languages that support exceptions (e.g., Java, .NET, Python, AS3).

For example, in C, you might write a LocalErrorCatcher function that you can then use on every Phidget function call to detect and deal with errors:

<div class="source">
<syntaxhighlight lang=cpp>
int LocalErrorCatcher (int errorCode) {

if (errorCode != 0) { // Everything is okay if errorCode = 0

switch (errorCode) {
default:
const char *errorDescription;
LocalErrorCatcher(
CPhidget_getErrorDescription (errorCode, &errorDescription));
printf("The description for error %d is: %s\n", errorCode, errorDescription);
break;
}
}
return 0;
}

// ... Then, later, you would use it on any Phidget function:
LocalErrorCatcher(
CPhidget_open((CPhidgetHandle) device, -1));

</syntaxhighlight>
</div>

Note that:
# The function LocalErrorCatcher uses itself to check for errors on getting an error description.
# You can handle individual error codes as they are listed in the API. This only prints a general message.

Or in Java, you would try a Phidget function call, and catch any resulting exception that occurs:

<div class="source">
<syntaxhighlight lang=java>
try {
device.openAny();
} catch (PhidgetException exception) {
system.out.println("The description for error " + Integer.toString(exception.getErrorNumber()) +
" is: ", exception.getDescription());
}

</syntaxhighlight>
</div>

Like C above, you could also use a <code>try...catch</code> statement around the exception.getErrorNumber() and exception.getDescription() functions to catch any errors from those calls.

The consequences of not catching this type of error (on ''every'' function) differ by programming language.
In C/C++ these errors must be ''explicitly'' checked for after each function call, otherwise the program will simply continue on in an incorrect state. In languages that support exceptions (e.g., Java, .NET, Python, AS3), errors are returned using exceptions which will leave you no choice but to catch them, or have your program terminate without warning.

====Two: An error generated by an event====

These errors are generated by the Phidget library during runtime. For example, the Phidget device might be experiencing too high a temperature, and trigger an error. This would not necessarily be due to any one function your program called; rather, the error would appear when the problem appears and would trigger an event.

So, these errors happen ''asynchronously'', that is, something happens apart from any function calls and an error event is triggered. You can handle these by setting up an Error Event Handler.

In C, this would look like:

<div class="source">
<syntaxhighlight lang=cpp>
int ErrorEventHandler (CPhidgetHandle device, void *usrptr, int errorCode, const char *errorDescription) {
printf("The description for error %d is: %s\n", errorCode, errorDescription);
// Do something useful based on the error code
return 0;
}

// Actually hook the Error Event Handler in to receive events
LocalErrorCatcher(
CPhidget_set_OnError_Handler((CPhidgetHandle) device, LibraryErrorHandler, NULL));
</syntaxhighlight>
</div>

You'll note that the '''LibraryErrorHandler''' function is what gets called when an error event occurs, and it gives you an opportunity to handle the error.

You'll also note that there is a second function called '''LocalErrorCatcher'''. This second function handles the return value from setting the error handler. We included it here because, as these are examples on how to handle errors, the example would leave a possibly unhandled error without it. This second type of error handling and the '''LocalErrorCatcher''' function are [[#One: An error generated by a function call|described above]].

In Java, it would look like this:

<div class="source">
<syntaxhighlight lang=java>
try {
device.addErrorListener(new ErrorListener() {
public void error(ErrorEvent event) {
System.out.println(event);
}
});
} catch (PhidgetException exception) {
system.out.println("The description for error " + Integer.toString(exception.getErrorNumber()) +
" is: ", exception.getDescription());
}

</syntaxhighlight>
</div>

Like C above, the act of hooking an error listener in to the device can itself generate an error, which should be caught.

These event-type errors are also how a Phidget being run over a network announces bad passwords, lost packets, and other network problems. Locally, the errors can announce incorrect temperatures, current, and power. So, it is in your best interest to set up an error event handler and take action based on the codes and error types in the API [[Software Overview#Language Support|for your programming language]].

See the API for your [[Software Overview#Language Support|specific programming language]] for error code documentation.

===Sensitivity and Filtering===

Change Triggers are used to filter the number of events that are returned to an Application, by setting a minimum amount of activity before a Change Event is sent to your program.

This is a simple hysteresis - a minimum amount of change has to occur since the last event before another event will be fired.

If your application is implementing its own filtering, setting the ChangeTrigger, or '''sensitivity''' to zero will cause all events to fire. Change triggers are generally available only for sensor inputs events. Change triggers are referred to as ''Sensitivity'' in some device-specific APIs.

===Data Rate===

Some devices support a user-defined data rate for events.

* The data rate is set in milliseconds, with a range from up 1ms to 1000ms, depending on the Phidget.
* Data rates greater then 8ms generally need to be a multiple of 8 (8,16,24,...,496,...,996,1000).
* Data rates lower then 8ms are supported as: 4ms, 2ms, 1ms.
* Data rate is a maximum rate
* Data rate will be superseded by a non-zero sensitivity on devices that support both sensitivity and data rate.

See the main page for your device - found on its product page on [{{SERVER}} our main website] for more details on available data rates and specifications.

Note that this data rate '''is not the rate at which you will receive data'''. Rather, it is the amount of time over which events are averaged before being sent. It may help to think of our specification of data rate as an ''averaging time''. This means that setting a data rate of 24 ms will try to give you data averaged over 24 ms, and send it every 24 ms. Depending on your computer, events may or may not be dropped. If events are dropped, the data points that are received still represent 24 ms (or whatever the data rate is set to). This means data is lost.

Conversely, if you are [[#Logic Code|polling]], and you set the data rate to longer than your polling rate, you will receive duplicate, averaged data. For example, setting the data rate to 24 ms and then polling every 12 ms will give you duplicate readings every other poll. To poll and not miss any data, the rate that your code polls must match the rate that you set for the {{Code|setDataRate()}} function in our API.

===Using the Dictionary===

The Phidget Dictionary is a service provided by the Phidget WebService. The dictionary:
* Is a centralized collection of key-value pairs
* Works only over the webservice
* Can be accessed and changed from any number of webservice clients
* Makes use of extended regular expressions (denoted between two forward slashes) for key matching
* Is also a foundation part of the webservice itself, and controls access of all Phidgets through the {{Code|openRemote}} and {{Code|openRemoteIP}} interfaces
* Can be used as an abstracted or higher-level interface for remotely managing Phidgets

We have a more in-depth description of the Dictionary (with pictures) on the main [[Phidget Dictionary]] page.

The intended use for the dictionary is as a central repository for communication and persistent storage of data between several client applications. For example, the computer directly connected to a Phidget could create and change keys for additional events on top of (or even instead of) those already thrown by the Phidget device API. The dictionary API is very high-level and thus very flexible - essentially any application of adding keys, changing keys (and throwing events), and getting values of keys can be handled by the Dictionary.

Note that you should never add or modify a key that starts with {{Code|/PSK/}} or {{Code|/PCK/}} as these are the keys that Phidgets use. Unless, of course, you want to explicitly modify Phidget specific data - and this is highly discouraged, as it’s very easy to break things. Listening to these keys is fine if so desired.

Refer to the API [[Software Overview#Language Support|for your specific language]] for the full Dictionary API.

===Long Term Code Maintenance===

Thinking long term from the start is incredibly useful. Phidgets as a company is constantly developing and inventing, and our API gets improved and changed to still work with older devices while adding support for new ones.

We release library updates - both for operating systems and languages - on a regular basis. We '''strongly''' recommend updating your own libraries as we release them. This goes for both the libraries and the WebService, as the versions must match.

This form of updating (did we mention that we strongly recommend it?) is the single most important thing you can do to reduce maintenance issues with your Phidget software down the road.

Every so often, customers come to us having run the same code for years, without updating. Then, for some reason, they have to update (say, for an operating system migration). And their code no longer works. What do to then? We can work with these customers to find out which of the many updates was the one to cause the problem - a difficult and very time consuming process. And over the course of multiple years, we may no longer stock or even manufacture that particular Phidget. You can imagine that a process with these limitations can take a very long time to resolve, if it can be resolved at all.

Conversely, if you update every time, this time frame is greatly reduced. We make a serious effort to test every library update, and although some backwards-compatibility problems do (rarely) get through, we have a fresh memory of what was changed and can work with you to quickly either debug the new libraries or get you a working version.

In addition to library updates, here are a few other tips and tricks to reduce your maintenance time:
* If you are using [[#Logging|Logging]], don't remove the logging code when you finalize your release. Simply comment it out so you can turn it on again later and debug quickly.
* Some long-term problems can be detected early by listening to library messages and errors. Handling [[#Exceptions and Errors|Exceptions and Errors]] will allow your code to run silently until something is wrong, in which case you'll know right away.

If you are looking for more help on how to work with our library updating, please feel welcome to [[Contact Us|contact us]].

==Summary==

This page has gone through [[#The Basic Functions|basic]] to [[#Advanced Concepts|advanced]] uses of the Phidget API. We've used C and Java here as example languages. If you're using a different language, we include similar snippets of code (without the in-depth description) in the documentation [[Software Overview#Language Support|for your language]].

If you've read this far and are still hungry for more, try learning more about your hardware; we have a number of [[:Category:Primer|hardware learning pages]] as well.

General Phidget Programming

2012-06-29T17:46:52Z

Cora: /* Do Things with the Phidget */

[[Category:Overview]]
__TOC__

This page presents the general '''concepts''' needed to write code for a Phidget.

By this point, you should have installed the drivers for your [[Software Overview#Operating System Support|operating system]] and the libraries for your [[Software Overview#Language Support|specific programming language]].

==The Basic Functions==

To use your Phidget within code, you'll want to:
# Create a Phidget [[#Creating a Software Object|software <code>object</code>]], which gives you access to the functions specific to that device
# [[#Opening the Phidget|Open the Phidget]] using the <code>object</code>
# Detect when a [[#Attaching the Phidget|Phidget is attached]] (plugged in) by using the <code>object</code>
# Use [[#Do Things with the Phidget|functions that the <code>object</code> provides]], like turning on LEDs, reading sensors, triggering events on data change, etc
# [[#Close the Phidget|Close the <code>object</code>]], when you are done

Small code snippets are provided for each step below. [[Language - C/C++|C++]] and [[Language - Java|Java]] were selected because Java is a relatively high-level language and C++ is a relatively low level language, thereby showing how specific each language API really is. So, the most useful resource for the ''actual functions'' would be the API for [[Software Overview#Language Support | your specific language]]. This page is a high-level introduction, by design.

=== Creating a Software Object ===

Phidget devices are controlled using software objects. All software device objects have a common API and set of functions that allow you to '''open''' it, '''close''' it, and set a few listeners to general events such as '''attach''' (plug in), '''detach''' (unplug), and errors.

But when you create an actual software object, it is a software object '''specific''' to your device.

For example, in Java:

<div class="source">
<syntaxhighlight lang=java>

// Create a new Accelerometer object
AccelerometerPhidget device = new AccelerometerPhidget();

</syntaxhighlight>
</div>
<br>
<div class="source">
<syntaxhighlight lang=java>

// Create a new RFID device object
RFIDPhidget device = new RFIDPhidget();

</syntaxhighlight>
</div>

Or in C:

<div class="source">
<syntaxhighlight lang=c>

// Create a new Accelerometer object
CPhidgetAccelerometerHandle device = 0;
CPhidgetAccelerometer_create(&device);

</syntaxhighlight>
</div>
<br>
<div class="source">
<syntaxhighlight lang=c>

// Create a new RFID device object
CPhidgetRFIDHandle device = 0;
CPhidgetRFID_create(&device);

</syntaxhighlight>
</div>

Each software object has an API and available functions which are specific to that device. For example, the RFID device API includes a function to turn on the RFID antenna. The accelerometer device API includes a function to set the sensitivity on each axis.

=== Opening the Phidget ===

Phidgets can either be opened when attached directly to a computer, or they can be opened remotely using the [[Phidget WebService]]. This section deals primarily with opening Phidgets directly.

Once you have created your [[#Creating a Software Object|software object]] for your specific type of device, you can call the <code>open()</code> function in your language on that object. For example, in Java:

<div class="source">
<syntaxhighlight lang=java>
device.open();
</syntaxhighlight>
</div>

Or in C:

<div class="source">
<syntaxhighlight lang=c>
CPhidget_open((CPhidgetHandle) device, -1);
</syntaxhighlight>
</div>

All specific language calls can be found in the API documentation located on each [[Software Overview#Language Support|individual language page]].

The <code>open()</code> function in any language opens the software object for use, not the hardware itself. Having the software "open" before the hardware means that the software can capture all events, including multiple attach (plug in) and detach (unplug) events for one <code>open()</code> call.

====Details for Open()====

Open will return immediately once called, because it can be called even if the Phidget to be used is not attached to the system. This is known as an asynchronous call. It’s important to understand that most calls on a Phidget will fail if they are calls when the Phidget is not attached - in fact the only calls that are allowed on a detached Phidget are <code>close()</code>, <code>waitForAttachment()</code> and <code>getAttached()</code>.

Open is also pervasive. This means that once open has been called, it will constantly try to stay attached to a Phidget. Even if the Phidget is unplugged from the computer and then plugged back in, you will simply get a Detach event, and then an Attach event. It’s a good idea to handle the Detach event in order to avoid calling the Phidget after it has detached.

The different types of open(), such as openAny(), openRemote(), etc. can be used with parameters to try and get the first device it can find, open based on its serial number, or even open across the network. The list all of the available modes that open provides, and the syntax for your language, can be found in the API for [[Software Overview#Language Support|your specific language]]. If there are more than one of the same type of Phidget attached to a computer, and you use open() with no serial number, there is no way of knowing which Phidget will be opened first.

If you are looking to do a remote open call, to use the [[Phidget WebService]], you usually have to change only the open() call (to a remote open call) to change your program from a locally-running one to one that can control a Phidget over the network. We give an in-depth example of using the WebService on each of our [[Software Overview#Operating System Support|operating system pages]], we have a brief overview of the WebService (with code snippets) in the [[#Using Phidgets over a Network|Using Phidgets over a Network]] section, and we often have WebService code snippets on the [[Software Overview#Language Support|language pages]] which do not easily extend from the examples on this page.

'''Note:''' Once a Phidget is opened by an application, it cannot be opened again in another application until closed by the first. When open and attached in software, no other programs or instances can read data from or change the Phidget. This includes it being open via the Windows Control Panel application! The one exception is if the Phidget is controlled ''only'' over the network with the [[Phidget WebService]], and not directly. Then, you can use multiple remote control programs.

=== Attaching the Phidget ===

Physically, attaching a Phidget means plugging it in. The real guts behind the 'attach' command, however, occur within the software libraries. The 'attach' call is what makes the final connections between the opened software object and the corresponding thread and events. This is why all Phidget object must be attached in software, even those that are not actually plugged in with a cable. This includes Phidgets used remotely via our [[Phidget WebService]], it includes Interface Kits on the same board as our Single Board Computer, and it even includes the [[Phidget Manager]] software object, which is a sort of meta-Phidget from which you can [[#Using the Manager|control other Phidgets]].

In your code, you can detect an attachment either with an '''event''' in [[#Event Driven Code|event-driven programming]], or '''waiting''' for it, in [[#Logic Code|logic programming]].

==== Event Attachment ====

For example, to use an event to detect attachment in Java:

<div class="source">
<syntaxhighlight lang=java>
// After creating a Phidget object called "device":
device.addAttachListener(new AttachListener() {
public void attached(AttachEvent ae) {
System.out.println("A new device has been plugged in!");
// Do things after attachment (i.e. read data, control the device)
}
});
</syntaxhighlight>
</div>

Or to use an event to detect attachment in C:

<div class="source">
<syntaxhighlight lang=c>
int AttachHandler (CPhidgetHandle device, void *userData) {
printf("A new device has been plugged in!");
// Do things after attachment (i.e. read data, control the device)
return 0;
}

// .....Then, in the main code after creating a Phidget object "device":
CPhidget_set_OnAttach_Handler((CPhidgetHandle) device, AttachHandler, NULL);
</syntaxhighlight>
</div>

Both of the code snippets above do the same thing. The function <code>AttachHandler(...)</code> is called automatically when a device is plugged in.

You will want to attach events (via <code>addAttachListener()</code> above, for example) '''before you open the Phidget object'''. Otherwise, triggered events may be lost.

This method for using events to detect attachment can be expanded to other events and more complex control flow. Where possible, all example code downloads from the [[Software Overview#Language Support|specific language pages]] shows event-driven programming.

==== Wait for Attachment ====

Waiting for attachment is a straightforward process. Your code does not handle events, it simply waits for a device to be plugged in before moving on and doing something else.

For example, in Java you wait for attachment on a '''created and open''' software object (called device) like this

<div class="source">
<syntaxhighlight lang=java>
// Wait until a device is plugged in
device.waitForAttachment();
// Do things after attachment (i.e. read data, control the device)
</syntaxhighlight>
</div>

Or in C (again, device has been '''created and opened''') :

<div class="source">
<syntaxhighlight lang=c>
int result;
// Wait up to 10000 ms for a device to be plugged in
if((result = CPhidget_waitForAttachment((CPhidgetHandle) device, 10000))) {
// No attachment, error
}
// Successful attachment
// Do things after attachment (i.e. read data, control the device)
</syntaxhighlight>
</div>

So, unlike the event model above, a Phidget software object should be open before waiting for a device to be plugged in.

=== Do Things with the Phidget ===

After you have a [[#Creating a Software Object|properly created]] Phidget software object, you can actually call function to turn LEDs on, change output state, read data from sensors, etc.

The thing you probably want to do with your Phidget is read data from its sensors or inputs. This might be, say, a sensor plugged in to a [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit] used in the code snippets below. You can do this either by detecting changes via [[#Event Driven Code|event driven code]], or polling for new values via [[#Logic Code|logic code]].

'''Details about data handling:'''

*When a Phidget is opened, its initial state will be read before it is marked as attached. This allows polling of many properties -- including some data -- even during the Attach event, and anytime afterwards.

*Your computer can poll much faster than the Phidget can respond. If you poll in a continuous '''<code>while</code>''' loop in byte code, you will probably swamp the Phidget with requests.

*Similarly, if you set a value and then immediately read the value on the next line in your program, the Phidget may not have time to finish the set. In our examples, we use <code>print()</code> statements within loops. Print functions are relatively slow; you can also use <code>wait()</code> or <code>sleep()</code> depending on your language.

*If you are handling data using events as described below, the data event functions will fire when the device is plugged in and its initial state is read.

*Some properties have default values, but these should not be trusted. Remember: '''always set''', don’t rely on defaults. Trying to read an uninitialized value with no default will result in an Exception.

*Usually, sensor 'sensitivity' will '''not''' be 0 (i.e. set to sense all changes) by default. This can be good because it prevents your screen from being completely overloaded with event output. But, depending on the sensor, it may make your sensor seem to have very high lag, and very poor sensitivity. To capture all events, set the sensitivity to 0.

*Often Phidgets will retain their last state unless power is lost. This can give surprising results as the previous state may not always be what you expect. For example, if you open an InterfaceKit and set an output, this output may stay set even after the Phidget is closed.

====Capture Data Change with Events====

To capture data changes in sensors or inputs as they happen, you need to use [[#Event Driven Code|event driven code]].

Like defining an event function that fires [[#Event Attachment|when the Phidget is plugged in]], you can create functions that automatically run when, for example, a sensor value or input value changes.

For example, for an Interface Kit, you can create a function that gets called when a sensor changes. You would do this '''before''' the Phidget software object has been [[#Opening the Phidget|opened]].

In Java, this would look like:
<div class="source">
<syntaxhighlight lang=java>
// After creating a Phidget object called "device":
device.addSensorChangeListener(new SensorChangeListener() {
public void sensorChanged(SensorChangeEvent sensorEvent) {
System.out.println("New Value: " + sensorEvent.getValue());
}
});
</syntaxhighlight>
</div>

Or to use an event to detect attachment in C:

<div class="source">
<syntaxhighlight lang=cpp>
int SensorChangeHandler (CPhidgetHandle device, void *userData, int boardIndex, int newValue) {
printf("New Value %d from sensor at location %d\n", newValue, boardIndex);
return 0;
}

// .....Then, in the main code after creating a Phidget object "device":
CPhidget_set_OnSensorChange_Handler((CPhidgetHandle) device, SensorChangeHandler, NULL);
</syntaxhighlight>
</div>

====Poll for Data Change====

To poll for sensor data, or output state, you usually want to look for a '''get...Value''' or '''get...State''' function available in the API for your device. (The API can be found on the product page for your device on our [{{SERVER}} main web site].) Then, you simply set up a loop that get the value of a sensor continuously.

To poll your software object, the object must be [[#Opening the Phidget|open]]. This is in contrast to the event-driven method above, where all event functions are declared and attached before opening the object.

Note that when you poll the value of a sensor or another attribute, this will probably be within a loop. When you create this loop, the ''more code'' you have within a loop, the ''more slowly'' your loop will run, and the ''more slowly'' you will be sampling the value in practice. This may make you lose data, as described further in the [[#Data Rate|Data Rate]] section.

This effect is also felt with interpreted languages (Java, Python) versus purely compiled languages, as the interpreted languages sample more slowly even within an otherwise completely empty loop.

So if you want to sample as fast as possible, and capture all of the changes that a sensor produces, you should [[#Capture Data Change with Events|capture data with event programming]]. If you choose not to use the event-driven design, you should keep the code run between polls to a minimum. This way you can sample as quickly as possible.

These code snippets assume <code>device</code> is an [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit 8/8/8]. For example, in Java, for the Sensor at location 5 on the board:
<div class="source">
<syntaxhighlight lang=java>
int val;
for (int i = 0; i < 10; i++) {
val = device.getSensorValue(5);
System.out.println("Value: " + val);
}
</syntaxhighlight>
</div>

Or, in C, for the Sensor at location 5 on the Interface Kit board:
<div class="source">
<syntaxhighlight lang=cpp>

int val;
for (int i = 0; i < 10; i++) {
CPhidgetInterfaceKit_getSensorValue(device, 5, &val);
printf("Value: %d\n", val);
}
</syntaxhighlight>
</div>

====Sensors, Input, and Output====

Often, your Phidget will be something like an [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit] which has either analog inputs (black plug holes), or digital inputs and outputs (green screw attachments), or often both.

* To the analog inputs, you can attach various sensors, including sensors for temperature, humidity, light, sound, and so on.
* To the digital inputs, you can attach various input devices, including switches.
* To the digital outputs, you can attach status tools like LEDs.

You use these sensors in software entirely through the software object for the Phidget plugged in to your USB port. For example, to turn off an LED at output block 1 on on an RFID tag reader, you'll want to set the output at location 1 to "0" (or false). In C, this would be:

<div class="source">
<syntaxhighlight lang=cpp>
// Create the RFID software object:
CPhidgetRFIDHandle device = 0;
CPhidgetRFID_create(&device);

// Open and handle the attachment of the PhidgetRFID object
....

// Then, turn the LED off, passing first the output number, then the new state:
CPhidgetRFID_setOutputState(device, 1, 0);
</syntaxhighlight>
</div>

Or in Java, this would be:

<div class="source">
<syntaxhighlight lang=java>
// Create the RFID software object:
RFIDPhidget device = new RFIDPhidget();

// Open and handle the attachment of the RFID object
....

// Then, turn the LED off, passing first the output number, then the new state:
device.setOutputState(1, 0);
</syntaxhighlight>
</div>

Getting a digital input would follow the same pattern, except you would use the getOutputState function and you would not pass the function a new output state.

Getting an analog input is a little more complicated because:
# You must declare the sensor as one of two types (ratiometric or non-ratiometric)
#* To find out which your sensor is, read the product information for your specific sensor on our [{{SERVER}} main web site].
# You must translate the 1-1000 reading that you get from the input into the data that you need (temperature, etc)
#* If the sensor comes from Phidgets, we provide a translation equation in the product information for your specific sensor on our [{{SERVER}} main web site].

Other than that, reading an analog sensor mirrors reading a digital input. For example, to obtain the lux from the [{{SERVER}}/products.php?product_id=1127 - PrecisionLightSensor], a '''non-ratiometric''' sensor plugged into analog input 5, you would do this in C:

<div class="source">
<syntaxhighlight lang=cpp>
// Change measurement to non-ratiometric style
CPhidgetInterfaceKit_setRatiometric(device, 0);

// Get the data from analog input 5
int sensorValue;
CPhidgetInterfaceKit_getSensorValue(device, 5, &sensorValue);

// In this case, the measured light lux equals the sensor value.
int lux = sensorValue;
</syntaxhighlight>
</div>

Or in Java:

<div class="source">
<syntaxhighlight lang=java>
// Change measurement to non-ratiometric style
device.setRatiometric(0);

// Get the data from analog input 5
int sensorValue = getSensorValue(5);

// In this case, the measured light lux equals the sensor value.
int lux = sensorValue;
</syntaxhighlight>
</div>

====Learning Everything You Can Do====

The things you can do with your particular Phidget are many and varied, so we only include general concepts on this page.

You can go one of two places for more information on what functions are available for your specific device. We provide both documentation on the raw API for each programming language as well as a language-independent description of the calls for each device.
* Read the API for your [[Software Overview#Language Support| specific programming language]], available as a download on each page.
* Read the API overview for your hardware, which can be found on its product page on [{{SERVER}} our main website].

=== Close the Phidget ===

When you are finished with the Phidget software object at the end of your program, you should close and (in some languages) delete it.

For example, in Java:
<div class="source">
<syntaxhighlight lang=java>
device.close();
device = null;
</syntaxhighlight>
</div>

Or, in C:
<div class="source">
<syntaxhighlight lang=cpp>
CPhidget_close((CPhidgetHandle) device);
CPhidget_delete((CPhidgetHandle) device);
</syntaxhighlight>
</div>

The <code>close()</code> call removes the lock that [[#Opening the Phidget|open]] put on the Phidget. Make sure to close your object, so other software can use the Phidget!

The close() function also makes sure the thread associated with the Phidget close properly. Any outstanding writes will block close() until they complete, because writes are guaranteed to complete (unless a device is detached).

Also note that a device should be put into a known state before calling close. For example, if a motor controller is driving a motor and close is called, it will continue to drive the motor even though the application has exited. This may or may not be what you want.

===Using Multiple Phidgets===

It is of course possible to use more than one Phidget within your program. The trick lies in using a unique identifier for each one. You can either hard-code the [[#Using the Serial Number|serial number in by hand]] (the number will be on the bottom of the board, or you can run our example code for the Phidget to obtain it on-screen), or you can use the [[#Using the Manager|Phidget Manager within your program]] to detect attached devices and return their serial numbers and Phidget types.

====Using the Serial Number====

Each Phidget has a unique serial number. Using this serial number, you can use a specific [[General Phidget Programming#Opening the Phidget|open]] call to open by serial number.

For example, in Java, this would be:
<div class="source">
<syntaxhighlight lang=java>
device.open(SerialNumber);
</syntaxhighlight>
</div>

Or in C:
<div class="source">
<syntaxhighlight lang=cpp>
CPhidget_open((CPhidgetHandle) device, serialNumber);
</syntaxhighlight>
</div>

====Using the Label====

If you want to have a human-readable way to reference your Phidget (as opposed to a serial number), or to have multiple different Phidgets of the same type with the same handle (for re-usable system code), you can use the Label feature of Phidgets. In many development setups, you can change the label to whatever you like, get the label within your code, and open a Phidget based on its label, for any newer generation Phidget. The disadvantage of Labels is that they are not available on all operating systems and languages.

Some limitations are:
* You cannot '''set''' a label using any language in [[OS - Windows|Windows]], for any language
**However, you can get the label of a Phidget on Windows, and open a Phidget by its label
* [[Language - Android Java|Android Java]] has support for only a subset of the open() functions that use labels, see the [[Language - Android Java|Android Java language page]] for details
* Older Phidgets do not support labels
* No .COM language on Windows supports opening by Label
** This includes [[Language - AutoIt|AutoIt]], [[Language - Adobe Director|Adobe Director]], [[Language - Delphi|Delphi]], and all of the Visual Basic flavours.
* [[Language - LabVIEW|LabVIEW]] cannot open by label
* [[Language - Python|Python]] cannot open by label
* [[Language - LiveCode|LiveCode]] cannot open by label

When opening by label, you would use the {{Code|openLabel("mylabel")}} function (or similar, check the [[Software Overview#Language Support|API for your language]]) rather than the generic open() function.

Note that setting the label should be done by a separate program. On a Mac OS computer, you can set a label through the Phidget Preference Pane. On a Linux computer, you should write a special short program specifically for setting the label. There are two reasons to '''not''' set a label within your main program:
* If you set a label every time you run that program, when not needing to, you can easily reach the 10,000 re-write limit for the flash that stores the label
* If you are using event driven programming, you cannot set the label from any function called from the attach event, as it will hang (on a mutual exclusion lock).
Because of the second point, your special program to set the label on a Phidget should use {{Code|waitForAttach()}} in [[#Logic Code|logic code]] and not [[#Event Driven Code|event-driven]] programming

====Using the Manager====

The Phidget Manager object can detect all Phidgets attached to a system and return their attributes in a list (or array, vector, etc. - depending on the language). With this, you can obtain the serial numbers and types of Phidgets currently attached. This is the preferred method for systems where you will be using multiple Phidgets and expecting the system to operate long enough (or under harsh enough conditions) that the Phidgets would need to be replaced.

This is especially true for running programs [[OS - Phidget SBC#Running a Program Automatically| automatically at scheduled times on the Single Board Computer]], where you would be replacing Phidgets without the benefit of keyboard or screen.

For example, in Java (note for Enumerations you also need to include {{Code|java.util.*}}):

<div class="source">
<syntaxhighlight lang=java>
// Create and open the manager
Manager manager;
manager = new Manager();
try {
manager.open();
} catch (PhidgetException exception) {
printError(exception.getErrorNumber(), exception.getDescription());
}

// Allow the Phidgets time to attach
Thread.sleep(1000);

// Retrieve the list of attached Phidgets from the manager
Vector phidgetList = manager.getPhidgets();

// Use an enumeration to iterate over the vector
// Vectors also have iterators in Java 2
Enumeration phidgetListEnum = phidgetList.elements();
while(phidgetListEnum.hasMoreElements()) {
Phidget phidgetElement = (Phidget)phidgetListEnum.nextElement();
System.out.print(phidgetElement.getDeviceName() + ", ");
System.out.println(phidgetElement.getSerialNumber());
// Store name and serial number into a persistent variable
....
}

// Close the manager
try {
manager.close();
} catch (PhidgetException exception) {
printError(exception.getErrorNumber(), exception.getDescription());
}
manager = null;

// Do something with names and serial numbers stored above (i.e. open and use Phidget objects)
....
</syntaxhighlight>
</div>

Or, in C (note for sleep you also need to include {{Code|unistd.h}}):

<div class="source">
<syntaxhighlight lang=cpp>
// Create and open the manager
CPhidgetManagerHandle manager = 0;
CPhidgetManager_create(&manager);
CPhidgetManager_open((CPhidgetManagerHandle) manager);

// Allow the Phidgets time to attach
sleep(1);

// Retrieve the list of attached Phidgets from the manager
CPhidgetHandle* phidgetList;
int count;

CPhidgetManager_getAttachedDevices((CPhidgetManagerHandle) manager, &phidgetList, &count);

int serialNumber;
const char *name;

// Iterate over the returned Phidget data
int i;
for (i = 0; i < count; i++) {
CPhidget_getDeviceName(phidgetList[i], &name);
CPhidget_getSerialNumber(phidgetList[i], &serialNumber);
printf("%s, %d\n", name, serialNumber);
// Store name and serial number into a persistent variable
....
}

// Use the Phidget API to free the memory in the phidgetList Array
CPhidgetManager_freeAttachedDevicesArray(phidgetList);

// Close the manager
CPhidgetManager_close((CPhidgetManagerHandle) manager);
CPhidgetManager_delete((CPhidgetManagerHandle) manager);

// Do something with names and serial numbers stored above (i.e. open and use Phidget objects)
....
</syntaxhighlight>
</div>

====Distinguishing Events====

If you are using [[#Event Driven Code|event-driven code]], once you have correctly opened multiple Phidgets of different types, they will have different event handlers and hence you will know what Phidget triggered which event.
If you are using multiple Phidgets of the same type, or you are trying to determine within general events (such as Attach Events) which Phidget triggered the event, you can then check the serial number (or device type) of the triggering device and act accordingly.

For example, in Java, your [[General Phidget Programming#Event Attachment|attach event handler]] might look like this:
<div class="source">
<syntaxhighlight lang=java>
detachHandler = new DetachListener() {
public void detached(DetachEvent event) {
int serialNumber = ((Phidget)event.getSource()).getSerialNumber();
// Do something according to serialNumber
} }
</syntaxhighlight>
</div>

Or in C:
<div class="source">
<syntaxhighlight lang=cpp>
int AttachHandler(CPhidgetHandle device, void *userptr) {
int serialNo;
CPhidget_getSerialNumber(device, &serialNo);
// Do something according to serialNumber
}
</syntaxhighlight>
</div>

===Using Phidgets over a Network===

Control of a Phidget over a network uses the Phidget WebService.

We have an in-depth description of the WebService, with images to illustrate its use, on the main [[Phidget WebService]] page.

In the code on the remote computer where you are receiving Phidget data and controlling the Phidget, you would simply use a different open call, and then the Phidget software object will work as if the object were local and normal.

The different, remote open call in C would be:

<div class="source">
<syntaxhighlight lang=cpp>
int serial_number = 37299;
CPhidget_openRemoteIP ((CPhidgetHandle) device, serial_number, "127.0.0.1", 5001, NULL);
</syntaxhighlight>
</div>

This simply uses the same computer in a 'loopback' connection (127.0.0.1) and the default port 5001. You can replace the serial number with your own Phidget's serial number.

And in Java, the different, remote open call would be:

<div class="source">
<syntaxhighlight lang=java>
openAny("127.0.0.1", 5001, null);
</syntaxhighlight>
</div>

There are other options for opening remotely, including by name rather than IP. You can refer to the [[Software Overview#Language Support|API for your language]] for options and specific syntax.

== Putting It Together ==

User and device actions can be handled by either:
*Letting the program tell you when they happen and then doing something ('''event driven''' code)
*Polling for things to happen then doing something ('''logic''' code)

The style of programming you choose (and hence the language you might prefer) would depend on what you want to do with the Phidget. The two sections, [[#Event Driven Code|Event Driven Code]] and [[#Logic Code|Logic Code]] below give benefits, drawbacks, and general examples of each style.

The styles can also mix. For example, you can take a defined set of steps at first such as turning on an LED or antenna (logic code) and then doing nothing until an output change event is fired (event code).

With languages that support both styles, you can mix and match. For languages that support only logic code (see the [[Software Overview#Language Support|Language Support Categories]] above) you can only use the logic paradigm style.

Examples in pseudo-code are given below for each style type so you can see how your language choice can affect your code design.

=== Logic Code ===

Logic code has use for:
* Simple, single-device applications
* Non-GUI applications (GUIs usually are event driven)
* The user driving the device rather than listening to it

Logic code is relatively easy to design well. For example, using the [[#Creating a Software Object|create]], [[#Opening the Phidget|open]], [[#Attaching the Phidget|attach]], [[#Do Things with the Phidget|do stuff]], and [[#Close the Phidget|close]] concepts introduced above, logic code to handle a Phidget might be written like this:

<br>

[[File:logic.png]]

<br>

Although this design does not explicitly capture every event that fires when data or input changes, by polling the device often enough no data will be lost.

However, logic code cannot handle constant, asynchronous events as cleanly as [[#Event Driven Code|event driven code]] can.

These designs can be mixed. So, if you find that in logic code you have a highly complex <code>if</code> loop driving your program, you should consider changing some of it to event driven code. This type of awkward if-loop might look like this:

<div class="source">
<syntaxhighlight lang=cpp>

Create Device Software Object
Open Device

Loop Until Exit Requested {
if No Device Attached {
Wait For Attachment until Timeout
if Wait Timeout Reached {
break
} else {
Initialize Device
}
} else { // Device Is Attached
if Device Data Type 1 Changed {
Do Something
}
if Device Data Type 2 Changed {
Do Something Else
}
// ... More data change functions here
}
Collect User Input
}

Close Device
Delete Device

</syntaxhighlight>
</div>

On the other hand, you can probably see that if your language does not give the option for events, you can use this structure to mimic what events would enable you to do.

=== Event Driven Code ===

Event driven code allows for clean handling of complex, asynchronous programs:
*Handling multiple Phidgets
*Handling active plugging or unplugging of the Phidget (multiple attach and detach events)
*Working behind a GUI, as many GUIs are already event driven
*Capturing all sensor data - or input and output - without constantly polling

''Without'' event driven code, you will need to constantly poll the device to see if any state has changed. If you poll at a slower rate than your input or output changes, you will not capture all data.

However, event driven code is usually not as useful or efficient for:
*Only one open and close event
*Using only one device
*Having the user (or program) ''put'' changes onto the device (in contrast to reading data ''from'' the device)

Event driven code is relatively hard to design well. It may help to draw out a '''flowchart''', '''state machine''', or at least a '''pseudo-code outline''' of your system design and all events you wish to handle before writing code.

The code examples given for each [[Software Overview#Language Support|specific language]] use events if they are supported by the language.

Using the [[#Creating a Software Object|create]], [[#Opening the Phidget|open]], [[#Attaching the Phidget|attach]], [[#Do Things with the Phidget|do stuff]], and [[#Close the Phidget|close]] concepts introduced above, event code to handle a Phidget might be written like this:

[[File:event.png]]

Once you have written this code flow, the actual order of events that occur within the program look something like this:

[[File:Eventhandler.jpg|160px]]

Note that the device itself initiates the function call, by 'firing' the event. This allows you to update only when events fire, and capture all changes, because the low-level interface is telling you when a change occurs.

==Advanced Concepts==

Now that you have the basic [[#Creating a Software Object|create]], [[#Opening the Phidget|open]], [[#Attaching the Phidget|attach]], [[#Do Things with the Phidget|do stuff]], and [[#Close the Phidget|close]] concepts introduced above, there are other useful concepts which will help you design your code to be persistent and stable.

===Logging===

You can enable logging to get more debugging information. Turning on logging happens through a Phidget API function. This would happen at the very start of your program, before even initializing your software object or opening it. Logging lets you get feedback from the Phidget libraries about every Phidget API call you make.

In C, turning on logging to the command line would look like:

<div class="source">
<syntaxhighlight lang=cpp>

CPhidget_enableLogging(PHIDGET_LOG_DEBUG, NULL);

//... All of your Phidget calls. Events called after enable will also log.

CPhidget_disableLogging();
</syntaxhighlight>
</div>

Or in Java:

<div class="source">
<syntaxhighlight lang=java>
enableLogging(PHIDGET_LOG_DEBUG, null);

//...All of your Phidget calls. Events called after enable will also log.

disableLogging();
</syntaxhighlight>
</div>

The use of null is to indicate that the output is not to a file (and hence to the command line). Otherwise, the second argument would be a string filename.

There are six different logging levels, ranging from "Give me Everything!" to "Tell me only about critical problems". The level in the examples above - '''<code>PHIDGET_LOG_DEBUG</code>''' - is a medium output level. For more information about each level and what it gives you, see the API for [[Software Overview#Language Support|your specific language]].

===Threading===

Due to the use of events, the Phidget library uses threading extensively.

For example:
* Calling <code>open()</code> starts a central thread.
* Closing everything will shut that central thread down (before the final close returns).
* Each device, once attached, starts its own read and write threads.

These threads provide the support to perform your typical [[#The Basic Functions|Basic Functions]]:

* Triggering of data events come from the context of a device read thread.
* Attach and detach events come from the context of the central thread.
* The central thread looks for device attaches and detached, keeping track of which devices are attached internally, and sending out attach and detach events to Phidgets and Managers.
* Writes are performed asynchronously by the write thread. The write queue is only 1 deep so calling a write function while there is a write pending will block.

All Phidget libraries are '''thread safe''', so you don’t need to do any locking on the Phidget objects. If you have a GUI, however, or another program with a separate thread, make sure to use one thread for events, and a separate thread with your GUI, and some form of mutual exclusion if they are both writing to the same thing.

===Exceptions and Errors===

There are two different types of errors that you can use to confirm that your program is running correctly.

====One: An error generated by a function call====

These errors are generated by ''you'' calling a function. For example, you might try to read analog sensor port number 150 on a board that only has eight. The function you used to read port 150 would return an error (in C/C++) or throw an error (in languages that support exceptions like Java, .NET, Python, or AS3).

So, these errors happen ''synchronously'' to function calls, that is, they are returned or thrown right after a function returns. You can handle these by checking the return values on your functions (in C/C++) or using an error catching method like <code>try...catch</code> in languages that support exceptions (e.g., Java, .NET, Python, AS3).

For example, in C, you might write a LocalErrorCatcher function that you can then use on every Phidget function call to detect and deal with errors:

<div class="source">
<syntaxhighlight lang=cpp>
int LocalErrorCatcher (int errorCode) {

if (errorCode != 0) { // Everything is okay if errorCode = 0

switch (errorCode) {
default:
const char *errorDescription;
LocalErrorCatcher(
CPhidget_getErrorDescription (errorCode, &errorDescription));
printf("The description for error %d is: %s\n", errorCode, errorDescription);
break;
}
}
return 0;
}

// ... Then, later, you would use it on any Phidget function:
LocalErrorCatcher(
CPhidget_open((CPhidgetHandle) device, -1));

</syntaxhighlight>
</div>

Note that:
# The function LocalErrorCatcher uses itself to check for errors on getting an error description.
# You can handle individual error codes as they are listed in the API. This only prints a general message.

Or in Java, you would try a Phidget function call, and catch any resulting exception that occurs:

<div class="source">
<syntaxhighlight lang=java>
try {
device.openAny();
} catch (PhidgetException exception) {
system.out.println("The description for error " + Integer.toString(exception.getErrorNumber()) +
" is: ", exception.getDescription());
}

</syntaxhighlight>
</div>

Like C above, you could also use a <code>try...catch</code> statement around the exception.getErrorNumber() and exception.getDescription() functions to catch any errors from those calls.

The consequences of not catching this type of error (on ''every'' function) differ by programming language.
In C/C++ these errors must be ''explicitly'' checked for after each function call, otherwise the program will simply continue on in an incorrect state. In languages that support exceptions (e.g., Java, .NET, Python, AS3), errors are returned using exceptions which will leave you no choice but to catch them, or have your program terminate without warning.

====Two: An error generated by an event====

These errors are generated by the Phidget library during runtime. For example, the Phidget device might be experiencing too high a temperature, and trigger an error. This would not necessarily be due to any one function your program called; rather, the error would appear when the problem appears and would trigger an event.

So, these errors happen ''asynchronously'', that is, something happens apart from any function calls and an error event is triggered. You can handle these by setting up an Error Event Handler.

In C, this would look like:

<div class="source">
<syntaxhighlight lang=cpp>
int ErrorEventHandler (CPhidgetHandle device, void *usrptr, int errorCode, const char *errorDescription) {
printf("The description for error %d is: %s\n", errorCode, errorDescription);
// Do something useful based on the error code
return 0;
}

// Actually hook the Error Event Handler in to receive events
LocalErrorCatcher(
CPhidget_set_OnError_Handler((CPhidgetHandle) device, LibraryErrorHandler, NULL));
</syntaxhighlight>
</div>

You'll note that the '''LibraryErrorHandler''' function is what gets called when an error event occurs, and it gives you an opportunity to handle the error.

You'll also note that there is a second function called '''LocalErrorCatcher'''. This second function handles the return value from setting the error handler. We included it here because, as these are examples on how to handle errors, the example would leave a possibly unhandled error without it. This second type of error handling and the '''LocalErrorCatcher''' function are [[#One: An error generated by a function call|described above]].

In Java, it would look like this:

<div class="source">
<syntaxhighlight lang=java>
try {
device.addErrorListener(new ErrorListener() {
public void error(ErrorEvent event) {
System.out.println(event);
}
});
} catch (PhidgetException exception) {
system.out.println("The description for error " + Integer.toString(exception.getErrorNumber()) +
" is: ", exception.getDescription());
}

</syntaxhighlight>
</div>

Like C above, the act of hooking an error listener in to the device can itself generate an error, which should be caught.

These event-type errors are also how a Phidget being run over a network announces bad passwords, lost packets, and other network problems. Locally, the errors can announce incorrect temperatures, current, and power. So, it is in your best interest to set up an error event handler and take action based on the codes and error types in the API [[Software Overview#Language Support|for your programming language]].

See the API for your [[Software Overview#Language Support|specific programming language]] for error code documentation.

===Sensitivity and Filtering===

Change Triggers are used to filter the number of events that are returned to an Application, by setting a minimum amount of activity before a Change Event is sent to your program.

This is a simple hysteresis - a minimum amount of change has to occur since the last event before another event will be fired.

If your application is implementing its own filtering, setting the ChangeTrigger, or '''sensitivity''' to zero will cause all events to fire. Change triggers are generally available only for sensor inputs events. Change triggers are referred to as ''Sensitivity'' in some device-specific APIs.

===Data Rate===

Some devices support a user-defined data rate for events.

* The data rate is set in milliseconds, with a range from up 1ms to 1000ms, depending on the Phidget.
* Data rates greater then 8ms generally need to be a multiple of 8 (8,16,24,...,496,...,996,1000).
* Data rates lower then 8ms are supported as: 4ms, 2ms, 1ms.
* Data rate is a maximum rate
* Data rate will be superseded by a non-zero sensitivity on devices that support both sensitivity and data rate.

See the main page for your device - found on its product page on [{{SERVER}} our main website] for more details on available data rates and specifications.

Note that this data rate '''is not the rate at which you will receive data'''. Rather, it is the amount of time over which events are averaged before being sent. It may help to think of our specification of data rate as an ''averaging time''. This means that setting a data rate of 24 ms will try to give you data averaged over 24 ms, and send it every 24 ms. Depending on your computer, events may or may not be dropped. If events are dropped, the data points that are received still represent 24 ms (or whatever the data rate is set to). This means data is lost.

Conversely, if you are [[#Logic Code|polling]], and you set the data rate to longer than your polling rate, you will receive duplicate, averaged data. For example, setting the data rate to 24 ms and then polling every 12 ms will give you duplicate readings every other poll. To poll and not miss any data, the rate that your code polls must match the rate that you set for the {{Code|setDataRate()}} function in our API.

===Using the Dictionary===

The Phidget Dictionary is a service provided by the Phidget WebService. The dictionary:
* Is a centralized collection of key-value pairs
* Works only over the webservice
* Can be accessed and changed from any number of webservice clients
* Makes use of extended regular expressions (denoted between two forward slashes) for key matching
* Is also a foundation part of the webservice itself, and controls access of all Phidgets through the {{Code|openRemote}} and {{Code|openRemoteIP}} interfaces
* Can be used as an abstracted or higher-level interface for remotely managing Phidgets

We have a more in-depth description of the Dictionary (with pictures) on the main [[Phidget Dictionary]] page.

The intended use for the dictionary is as a central repository for communication and persistent storage of data between several client applications. For example, the computer directly connected to a Phidget could create and change keys for additional events on top of (or even instead of) those already thrown by the Phidget device API. The dictionary API is very high-level and thus very flexible - essentially any application of adding keys, changing keys (and throwing events), and getting values of keys can be handled by the Dictionary.

Note that you should never add or modify a key that starts with {{Code|/PSK/}} or {{Code|/PCK/}} as these are the keys that Phidgets use. Unless, of course, you want to explicitly modify Phidget specific data - and this is highly discouraged, as it’s very easy to break things. Listening to these keys is fine if so desired.

Refer to the API [[Software Overview#Language Support|for your specific language]] for the full Dictionary API.

===Long Term Code Maintenance===

Thinking long term from the start is incredibly useful. Phidgets as a company is constantly developing and inventing, and our API gets improved and changed to still work with older devices while adding support for new ones.

We release library updates - both for operating systems and languages - on a regular basis. We '''strongly''' recommend updating your own libraries as we release them. This goes for both the libraries and the WebService, as the versions must match.

This form of updating (did we mention that we strongly recommend it?) is the single most important thing you can do to reduce maintenance issues with your Phidget software down the road.

Every so often, customers come to us having run the same code for years, without updating. Then, for some reason, they have to update (say, for an operating system migration). And their code no longer works. What do to then? We can work with these customers to find out which of the many updates was the one to cause the problem - a difficult and very time consuming process. And over the course of multiple years, we may no longer stock or even manufacture that particular Phidget. You can imagine that a process with these limitations can take a very long time to resolve, if it can be resolved at all.

Conversely, if you update every time, this time frame is greatly reduced. We make a serious effort to test every library update, and although some backwards-compatibility problems do (rarely) get through, we have a fresh memory of what was changed and can work with you to quickly either debug the new libraries or get you a working version.

In addition to library updates, here are a few other tips and tricks to reduce your maintenance time:
* If you are using [[#Logging|Logging]], don't remove the logging code when you finalize your release. Simply comment it out so you can turn it on again later and debug quickly.
* Some long-term problems can be detected early by listening to library messages and errors. Handling [[#Exceptions and Errors|Exceptions and Errors]] will allow your code to run silently until something is wrong, in which case you'll know right away.

If you are looking for more help on how to work with our library updating, please feel welcome to [[Contact Us|contact us]].

==Summary==

This page has gone through [[#The Basic Functions|basic]] to [[#Advanced Concepts|advanced]] uses of the Phidget API. We've used C and Java here as example languages. If you're using a different language, we include similar snippets of code (without the in-depth description) in the documentation [[Software Overview#Language Support|for your language]].

If you've read this far and are still hungry for more, try learning more about your hardware; we have a number of [[Primers|high level teaching pages]] about hardware as well.

General Phidget Programming

2012-06-29T17:45:05Z

Cora:

[[Category:Overview]]
__TOC__

This page presents the general '''concepts''' needed to write code for a Phidget.

By this point, you should have installed the drivers for your [[Software Overview#Operating System Support|operating system]] and the libraries for your [[Software Overview#Language Support|specific programming language]].

==The Basic Functions==

To use your Phidget within code, you'll want to:
# Create a Phidget [[#Creating a Software Object|software <code>object</code>]], which gives you access to the functions specific to that device
# [[#Opening the Phidget|Open the Phidget]] using the <code>object</code>
# Detect when a [[#Attaching the Phidget|Phidget is attached]] (plugged in) by using the <code>object</code>
# Use [[#Do Things with the Phidget|functions that the <code>object</code> provides]], like turning on LEDs, reading sensors, triggering events on data change, etc
# [[#Close the Phidget|Close the <code>object</code>]], when you are done

Small code snippets are provided for each step below. [[Language - C/C++|C++]] and [[Language - Java|Java]] were selected because Java is a relatively high-level language and C++ is a relatively low level language, thereby showing how specific each language API really is. So, the most useful resource for the ''actual functions'' would be the API for [[Software Overview#Language Support | your specific language]]. This page is a high-level introduction, by design.

=== Creating a Software Object ===

Phidget devices are controlled using software objects. All software device objects have a common API and set of functions that allow you to '''open''' it, '''close''' it, and set a few listeners to general events such as '''attach''' (plug in), '''detach''' (unplug), and errors.

But when you create an actual software object, it is a software object '''specific''' to your device.

For example, in Java:

<div class="source">
<syntaxhighlight lang=java>

// Create a new Accelerometer object
AccelerometerPhidget device = new AccelerometerPhidget();

</syntaxhighlight>
</div>
<br>
<div class="source">
<syntaxhighlight lang=java>

// Create a new RFID device object
RFIDPhidget device = new RFIDPhidget();

</syntaxhighlight>
</div>

Or in C:

<div class="source">
<syntaxhighlight lang=c>

// Create a new Accelerometer object
CPhidgetAccelerometerHandle device = 0;
CPhidgetAccelerometer_create(&device);

</syntaxhighlight>
</div>
<br>
<div class="source">
<syntaxhighlight lang=c>

// Create a new RFID device object
CPhidgetRFIDHandle device = 0;
CPhidgetRFID_create(&device);

</syntaxhighlight>
</div>

Each software object has an API and available functions which are specific to that device. For example, the RFID device API includes a function to turn on the RFID antenna. The accelerometer device API includes a function to set the sensitivity on each axis.

=== Opening the Phidget ===

Phidgets can either be opened when attached directly to a computer, or they can be opened remotely using the [[Phidget WebService]]. This section deals primarily with opening Phidgets directly.

Once you have created your [[#Creating a Software Object|software object]] for your specific type of device, you can call the <code>open()</code> function in your language on that object. For example, in Java:

<div class="source">
<syntaxhighlight lang=java>
device.open();
</syntaxhighlight>
</div>

Or in C:

<div class="source">
<syntaxhighlight lang=c>
CPhidget_open((CPhidgetHandle) device, -1);
</syntaxhighlight>
</div>

All specific language calls can be found in the API documentation located on each [[Software Overview#Language Support|individual language page]].

The <code>open()</code> function in any language opens the software object for use, not the hardware itself. Having the software "open" before the hardware means that the software can capture all events, including multiple attach (plug in) and detach (unplug) events for one <code>open()</code> call.

====Details for Open()====

Open will return immediately once called, because it can be called even if the Phidget to be used is not attached to the system. This is known as an asynchronous call. It’s important to understand that most calls on a Phidget will fail if they are calls when the Phidget is not attached - in fact the only calls that are allowed on a detached Phidget are <code>close()</code>, <code>waitForAttachment()</code> and <code>getAttached()</code>.

Open is also pervasive. This means that once open has been called, it will constantly try to stay attached to a Phidget. Even if the Phidget is unplugged from the computer and then plugged back in, you will simply get a Detach event, and then an Attach event. It’s a good idea to handle the Detach event in order to avoid calling the Phidget after it has detached.

The different types of open(), such as openAny(), openRemote(), etc. can be used with parameters to try and get the first device it can find, open based on its serial number, or even open across the network. The list all of the available modes that open provides, and the syntax for your language, can be found in the API for [[Software Overview#Language Support|your specific language]]. If there are more than one of the same type of Phidget attached to a computer, and you use open() with no serial number, there is no way of knowing which Phidget will be opened first.

If you are looking to do a remote open call, to use the [[Phidget WebService]], you usually have to change only the open() call (to a remote open call) to change your program from a locally-running one to one that can control a Phidget over the network. We give an in-depth example of using the WebService on each of our [[Software Overview#Operating System Support|operating system pages]], we have a brief overview of the WebService (with code snippets) in the [[#Using Phidgets over a Network|Using Phidgets over a Network]] section, and we often have WebService code snippets on the [[Software Overview#Language Support|language pages]] which do not easily extend from the examples on this page.

'''Note:''' Once a Phidget is opened by an application, it cannot be opened again in another application until closed by the first. When open and attached in software, no other programs or instances can read data from or change the Phidget. This includes it being open via the Windows Control Panel application! The one exception is if the Phidget is controlled ''only'' over the network with the [[Phidget WebService]], and not directly. Then, you can use multiple remote control programs.

=== Attaching the Phidget ===

Physically, attaching a Phidget means plugging it in. The real guts behind the 'attach' command, however, occur within the software libraries. The 'attach' call is what makes the final connections between the opened software object and the corresponding thread and events. This is why all Phidget object must be attached in software, even those that are not actually plugged in with a cable. This includes Phidgets used remotely via our [[Phidget WebService]], it includes Interface Kits on the same board as our Single Board Computer, and it even includes the [[Phidget Manager]] software object, which is a sort of meta-Phidget from which you can [[#Using the Manager|control other Phidgets]].

In your code, you can detect an attachment either with an '''event''' in [[#Event Driven Code|event-driven programming]], or '''waiting''' for it, in [[#Logic Code|logic programming]].

==== Event Attachment ====

For example, to use an event to detect attachment in Java:

<div class="source">
<syntaxhighlight lang=java>
// After creating a Phidget object called "device":
device.addAttachListener(new AttachListener() {
public void attached(AttachEvent ae) {
System.out.println("A new device has been plugged in!");
// Do things after attachment (i.e. read data, control the device)
}
});
</syntaxhighlight>
</div>

Or to use an event to detect attachment in C:

<div class="source">
<syntaxhighlight lang=c>
int AttachHandler (CPhidgetHandle device, void *userData) {
printf("A new device has been plugged in!");
// Do things after attachment (i.e. read data, control the device)
return 0;
}

// .....Then, in the main code after creating a Phidget object "device":
CPhidget_set_OnAttach_Handler((CPhidgetHandle) device, AttachHandler, NULL);
</syntaxhighlight>
</div>

Both of the code snippets above do the same thing. The function <code>AttachHandler(...)</code> is called automatically when a device is plugged in.

You will want to attach events (via <code>addAttachListener()</code> above, for example) '''before you open the Phidget object'''. Otherwise, triggered events may be lost.

This method for using events to detect attachment can be expanded to other events and more complex control flow. Where possible, all example code downloads from the [[Software Overview#Language Support|specific language pages]] shows event-driven programming.

==== Wait for Attachment ====

Waiting for attachment is a straightforward process. Your code does not handle events, it simply waits for a device to be plugged in before moving on and doing something else.

For example, in Java you wait for attachment on a '''created and open''' software object (called device) like this

<div class="source">
<syntaxhighlight lang=java>
// Wait until a device is plugged in
device.waitForAttachment();
// Do things after attachment (i.e. read data, control the device)
</syntaxhighlight>
</div>

Or in C (again, device has been '''created and opened''') :

<div class="source">
<syntaxhighlight lang=c>
int result;
// Wait up to 10000 ms for a device to be plugged in
if((result = CPhidget_waitForAttachment((CPhidgetHandle) device, 10000))) {
// No attachment, error
}
// Successful attachment
// Do things after attachment (i.e. read data, control the device)
</syntaxhighlight>
</div>

So, unlike the event model above, a Phidget software object should be open before waiting for a device to be plugged in.

=== Do Things with the Phidget ===

After you have a [[#Creating a Software Object|properly created]] Phidget software object, you can actually call function to turn LEDs on, change output state, read data from sensors, etc.

The thing you probably want to do with your Phidget is read data from its sensors or inputs. This might be, say, a sensor plugged in to a [[Product - 1018 - PhidgetInterfaceKit 8/8/8 | 1018 - Interface Kit 8/8/8]] used in the code snippets below. You can do this either by detecting changes via [[#Event Driven Code|event driven code]], or polling for new values via [[#Logic Code|logic code]].

'''Details about data handling:'''

*When a Phidget is opened, its initial state will be read before it is marked as attached. This allows polling of many properties -- including some data -- even during the Attach event, and anytime afterwards.

*Your computer can poll much faster than the Phidget can respond. If you poll in a continuous '''<code>while</code>''' loop in byte code, you will probably swamp the Phidget with requests.

*Similarly, if you set a value and then immediately read the value on the next line in your program, the Phidget may not have time to finish the set. In our examples, we use <code>print()</code> statements within loops. Print functions are relatively slow; you can also use <code>wait()</code> or <code>sleep()</code> depending on your language.

*If you are handling data using events as described below, the data event functions will fire when the device is plugged in and its initial state is read.

*Some properties have default values, but these should not be trusted. Remember: '''always set''', don’t rely on defaults. Trying to read an uninitialized value with no default will result in an Exception.

*Usually, sensor 'sensitivity' will '''not''' be 0 (i.e. set to sense all changes) by default. This can be good because it prevents your screen from being completely overloaded with event output. But, depending on the sensor, it may make your sensor seem to have very high lag, and very poor sensitivity. To capture all events, set the sensitivity to 0.

*Often Phidgets will retain their last state unless power is lost. This can give surprising results as the previous state may not always be what you expect. For example, if you open an InterfaceKit and set an output, this output may stay set even after the Phidget is closed.

====Capture Data Change with Events====

To capture data changes in sensors or inputs as they happen, you need to use [[#Event Driven Code|event driven code]].

Like defining an event function that fires [[#Event Attachment|when the Phidget is plugged in]], you can create functions that automatically run when, for example, a sensor value or input value changes.

For example, for an Interface Kit, you can create a function that gets called when a sensor changes. You would do this '''before''' the Phidget software object has been [[#Opening the Phidget|opened]].

In Java, this would look like:
<div class="source">
<syntaxhighlight lang=java>
// After creating a Phidget object called "device":
device.addSensorChangeListener(new SensorChangeListener() {
public void sensorChanged(SensorChangeEvent sensorEvent) {
System.out.println("New Value: " + sensorEvent.getValue());
}
});
</syntaxhighlight>
</div>

Or to use an event to detect attachment in C:

<div class="source">
<syntaxhighlight lang=cpp>
int SensorChangeHandler (CPhidgetHandle device, void *userData, int boardIndex, int newValue) {
printf("New Value %d from sensor at location %d\n", newValue, boardIndex);
return 0;
}

// .....Then, in the main code after creating a Phidget object "device":
CPhidget_set_OnSensorChange_Handler((CPhidgetHandle) device, SensorChangeHandler, NULL);
</syntaxhighlight>
</div>

====Poll for Data Change====

To poll for sensor data, or output state, you usually want to look for a '''get...Value''' or '''get...State''' function available in the API for your device. (The API can be found on the product page for your device on our [{{SERVER}} main web site].) Then, you simply set up a loop that get the value of a sensor continuously.

To poll your software object, the object must be [[#Opening the Phidget|open]]. This is in contrast to the event-driven method above, where all event functions are declared and attached before opening the object.

Note that when you poll the value of a sensor or another attribute, this will probably be within a loop. When you create this loop, the ''more code'' you have within a loop, the ''more slowly'' your loop will run, and the ''more slowly'' you will be sampling the value in practice. This may make you lose data, as described further in the [[#Data Rate|Data Rate]] section.

This effect is also felt with interpreted languages (Java, Python) versus purely compiled languages, as the interpreted languages sample more slowly even within an otherwise completely empty loop.

So if you want to sample as fast as possible, and capture all of the changes that a sensor produces, you should [[#Capture Data Change with Events|capture data with event programming]]. If you choose not to use the event-driven design, you should keep the code run between polls to a minimum. This way you can sample as quickly as possible.

These code snippets assume <code>device</code> is an [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit 8/8/8]. For example, in Java, for the Sensor at location 5 on the board:
<div class="source">
<syntaxhighlight lang=java>
int val;
for (int i = 0; i < 10; i++) {
val = device.getSensorValue(5);
System.out.println("Value: " + val);
}
</syntaxhighlight>
</div>

Or, in C, for the Sensor at location 5 on the Interface Kit board:
<div class="source">
<syntaxhighlight lang=cpp>

int val;
for (int i = 0; i < 10; i++) {
CPhidgetInterfaceKit_getSensorValue(device, 5, &val);
printf("Value: %d\n", val);
}
</syntaxhighlight>
</div>

====Sensors, Input, and Output====

Often, your Phidget will be something like an [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit] which has either analog inputs (black plug holes), or digital inputs and outputs (green screw attachments), or often both.

* To the analog inputs, you can attach various sensors, including sensors for temperature, humidity, light, sound, and so on.
* To the digital inputs, you can attach various input devices, including switches.
* To the digital outputs, you can attach status tools like LEDs.

You use these sensors in software entirely through the software object for the Phidget plugged in to your USB port. For example, to turn off an LED at output block 1 on on an RFID tag reader, you'll want to set the output at location 1 to "0" (or false). In C, this would be:

<div class="source">
<syntaxhighlight lang=cpp>
// Create the RFID software object:
CPhidgetRFIDHandle device = 0;
CPhidgetRFID_create(&device);

// Open and handle the attachment of the PhidgetRFID object
....

// Then, turn the LED off, passing first the output number, then the new state:
CPhidgetRFID_setOutputState(device, 1, 0);
</syntaxhighlight>
</div>

Or in Java, this would be:

<div class="source">
<syntaxhighlight lang=java>
// Create the RFID software object:
RFIDPhidget device = new RFIDPhidget();

// Open and handle the attachment of the RFID object
....

// Then, turn the LED off, passing first the output number, then the new state:
device.setOutputState(1, 0);
</syntaxhighlight>
</div>

Getting a digital input would follow the same pattern, except you would use the getOutputState function and you would not pass the function a new output state.

Getting an analog input is a little more complicated because:
# You must declare the sensor as one of two types (ratiometric or non-ratiometric)
#* To find out which your sensor is, read the product information for your specific sensor on our [{{SERVER}} main web site].
# You must translate the 1-1000 reading that you get from the input into the data that you need (temperature, etc)
#* If the sensor comes from Phidgets, we provide a translation equation in the product information for your specific sensor on our [{{SERVER}} main web site].

Other than that, reading an analog sensor mirrors reading a digital input. For example, to obtain the lux from the [[Product - 1127 - PrecisionLightSensor | Precision Light Sensor]], a '''non-ratiometric''' sensor plugged into analog input 5, you would do this in C:

<div class="source">
<syntaxhighlight lang=cpp>
// Change measurement to non-ratiometric style
CPhidgetInterfaceKit_setRatiometric(device, 0);

// Get the data from analog input 5
int sensorValue;
CPhidgetInterfaceKit_getSensorValue(device, 5, &sensorValue);

// In this case, the measured light lux equals the sensor value.
int lux = sensorValue;
</syntaxhighlight>
</div>

Or in Java:

<div class="source">
<syntaxhighlight lang=java>
// Change measurement to non-ratiometric style
device.setRatiometric(0);

// Get the data from analog input 5
int sensorValue = getSensorValue(5);

// In this case, the measured light lux equals the sensor value.
int lux = sensorValue;
</syntaxhighlight>
</div>

====Learning Everything You Can Do====

The things you can do with your particular Phidget are many and varied, so we only include general concepts on this page.

You can go one of two places for more information on what functions are available for your specific device. We provide both documentation on the raw API for each programming language as well as a language-independent description of the calls for each device.
* Read the API for your [[Software Overview#Language Support| specific programming language]], available as a download on each page.
* Read the API overview for your hardware, which can be found on its product page on [{{SERVER}} our main website].

=== Close the Phidget ===

When you are finished with the Phidget software object at the end of your program, you should close and (in some languages) delete it.

For example, in Java:
<div class="source">
<syntaxhighlight lang=java>
device.close();
device = null;
</syntaxhighlight>
</div>

Or, in C:
<div class="source">
<syntaxhighlight lang=cpp>
CPhidget_close((CPhidgetHandle) device);
CPhidget_delete((CPhidgetHandle) device);
</syntaxhighlight>
</div>

The <code>close()</code> call removes the lock that [[#Opening the Phidget|open]] put on the Phidget. Make sure to close your object, so other software can use the Phidget!

The close() function also makes sure the thread associated with the Phidget close properly. Any outstanding writes will block close() until they complete, because writes are guaranteed to complete (unless a device is detached).

Also note that a device should be put into a known state before calling close. For example, if a motor controller is driving a motor and close is called, it will continue to drive the motor even though the application has exited. This may or may not be what you want.

===Using Multiple Phidgets===

It is of course possible to use more than one Phidget within your program. The trick lies in using a unique identifier for each one. You can either hard-code the [[#Using the Serial Number|serial number in by hand]] (the number will be on the bottom of the board, or you can run our example code for the Phidget to obtain it on-screen), or you can use the [[#Using the Manager|Phidget Manager within your program]] to detect attached devices and return their serial numbers and Phidget types.

====Using the Serial Number====

Each Phidget has a unique serial number. Using this serial number, you can use a specific [[General Phidget Programming#Opening the Phidget|open]] call to open by serial number.

For example, in Java, this would be:
<div class="source">
<syntaxhighlight lang=java>
device.open(SerialNumber);
</syntaxhighlight>
</div>

Or in C:
<div class="source">
<syntaxhighlight lang=cpp>
CPhidget_open((CPhidgetHandle) device, serialNumber);
</syntaxhighlight>
</div>

====Using the Label====

If you want to have a human-readable way to reference your Phidget (as opposed to a serial number), or to have multiple different Phidgets of the same type with the same handle (for re-usable system code), you can use the Label feature of Phidgets. In many development setups, you can change the label to whatever you like, get the label within your code, and open a Phidget based on its label, for any newer generation Phidget. The disadvantage of Labels is that they are not available on all operating systems and languages.

Some limitations are:
* You cannot '''set''' a label using any language in [[OS - Windows|Windows]], for any language
**However, you can get the label of a Phidget on Windows, and open a Phidget by its label
* [[Language - Android Java|Android Java]] has support for only a subset of the open() functions that use labels, see the [[Language - Android Java|Android Java language page]] for details
* Older Phidgets do not support labels
* No .COM language on Windows supports opening by Label
** This includes [[Language - AutoIt|AutoIt]], [[Language - Adobe Director|Adobe Director]], [[Language - Delphi|Delphi]], and all of the Visual Basic flavours.
* [[Language - LabVIEW|LabVIEW]] cannot open by label
* [[Language - Python|Python]] cannot open by label
* [[Language - LiveCode|LiveCode]] cannot open by label

When opening by label, you would use the {{Code|openLabel("mylabel")}} function (or similar, check the [[Software Overview#Language Support|API for your language]]) rather than the generic open() function.

Note that setting the label should be done by a separate program. On a Mac OS computer, you can set a label through the Phidget Preference Pane. On a Linux computer, you should write a special short program specifically for setting the label. There are two reasons to '''not''' set a label within your main program:
* If you set a label every time you run that program, when not needing to, you can easily reach the 10,000 re-write limit for the flash that stores the label
* If you are using event driven programming, you cannot set the label from any function called from the attach event, as it will hang (on a mutual exclusion lock).
Because of the second point, your special program to set the label on a Phidget should use {{Code|waitForAttach()}} in [[#Logic Code|logic code]] and not [[#Event Driven Code|event-driven]] programming

====Using the Manager====

The Phidget Manager object can detect all Phidgets attached to a system and return their attributes in a list (or array, vector, etc. - depending on the language). With this, you can obtain the serial numbers and types of Phidgets currently attached. This is the preferred method for systems where you will be using multiple Phidgets and expecting the system to operate long enough (or under harsh enough conditions) that the Phidgets would need to be replaced.

This is especially true for running programs [[OS - Phidget SBC#Running a Program Automatically| automatically at scheduled times on the Single Board Computer]], where you would be replacing Phidgets without the benefit of keyboard or screen.

For example, in Java (note for Enumerations you also need to include {{Code|java.util.*}}):

<div class="source">
<syntaxhighlight lang=java>
// Create and open the manager
Manager manager;
manager = new Manager();
try {
manager.open();
} catch (PhidgetException exception) {
printError(exception.getErrorNumber(), exception.getDescription());
}

// Allow the Phidgets time to attach
Thread.sleep(1000);

// Retrieve the list of attached Phidgets from the manager
Vector phidgetList = manager.getPhidgets();

// Use an enumeration to iterate over the vector
// Vectors also have iterators in Java 2
Enumeration phidgetListEnum = phidgetList.elements();
while(phidgetListEnum.hasMoreElements()) {
Phidget phidgetElement = (Phidget)phidgetListEnum.nextElement();
System.out.print(phidgetElement.getDeviceName() + ", ");
System.out.println(phidgetElement.getSerialNumber());
// Store name and serial number into a persistent variable
....
}

// Close the manager
try {
manager.close();
} catch (PhidgetException exception) {
printError(exception.getErrorNumber(), exception.getDescription());
}
manager = null;

// Do something with names and serial numbers stored above (i.e. open and use Phidget objects)
....
</syntaxhighlight>
</div>

Or, in C (note for sleep you also need to include {{Code|unistd.h}}):

<div class="source">
<syntaxhighlight lang=cpp>
// Create and open the manager
CPhidgetManagerHandle manager = 0;
CPhidgetManager_create(&manager);
CPhidgetManager_open((CPhidgetManagerHandle) manager);

// Allow the Phidgets time to attach
sleep(1);

// Retrieve the list of attached Phidgets from the manager
CPhidgetHandle* phidgetList;
int count;

CPhidgetManager_getAttachedDevices((CPhidgetManagerHandle) manager, &phidgetList, &count);

int serialNumber;
const char *name;

// Iterate over the returned Phidget data
int i;
for (i = 0; i < count; i++) {
CPhidget_getDeviceName(phidgetList[i], &name);
CPhidget_getSerialNumber(phidgetList[i], &serialNumber);
printf("%s, %d\n", name, serialNumber);
// Store name and serial number into a persistent variable
....
}

// Use the Phidget API to free the memory in the phidgetList Array
CPhidgetManager_freeAttachedDevicesArray(phidgetList);

// Close the manager
CPhidgetManager_close((CPhidgetManagerHandle) manager);
CPhidgetManager_delete((CPhidgetManagerHandle) manager);

// Do something with names and serial numbers stored above (i.e. open and use Phidget objects)
....
</syntaxhighlight>
</div>

====Distinguishing Events====

If you are using [[#Event Driven Code|event-driven code]], once you have correctly opened multiple Phidgets of different types, they will have different event handlers and hence you will know what Phidget triggered which event.
If you are using multiple Phidgets of the same type, or you are trying to determine within general events (such as Attach Events) which Phidget triggered the event, you can then check the serial number (or device type) of the triggering device and act accordingly.

For example, in Java, your [[General Phidget Programming#Event Attachment|attach event handler]] might look like this:
<div class="source">
<syntaxhighlight lang=java>
detachHandler = new DetachListener() {
public void detached(DetachEvent event) {
int serialNumber = ((Phidget)event.getSource()).getSerialNumber();
// Do something according to serialNumber
} }
</syntaxhighlight>
</div>

Or in C:
<div class="source">
<syntaxhighlight lang=cpp>
int AttachHandler(CPhidgetHandle device, void *userptr) {
int serialNo;
CPhidget_getSerialNumber(device, &serialNo);
// Do something according to serialNumber
}
</syntaxhighlight>
</div>

===Using Phidgets over a Network===

Control of a Phidget over a network uses the Phidget WebService.

We have an in-depth description of the WebService, with images to illustrate its use, on the main [[Phidget WebService]] page.

In the code on the remote computer where you are receiving Phidget data and controlling the Phidget, you would simply use a different open call, and then the Phidget software object will work as if the object were local and normal.

The different, remote open call in C would be:

<div class="source">
<syntaxhighlight lang=cpp>
int serial_number = 37299;
CPhidget_openRemoteIP ((CPhidgetHandle) device, serial_number, "127.0.0.1", 5001, NULL);
</syntaxhighlight>
</div>

This simply uses the same computer in a 'loopback' connection (127.0.0.1) and the default port 5001. You can replace the serial number with your own Phidget's serial number.

And in Java, the different, remote open call would be:

<div class="source">
<syntaxhighlight lang=java>
openAny("127.0.0.1", 5001, null);
</syntaxhighlight>
</div>

There are other options for opening remotely, including by name rather than IP. You can refer to the [[Software Overview#Language Support|API for your language]] for options and specific syntax.

== Putting It Together ==

User and device actions can be handled by either:
*Letting the program tell you when they happen and then doing something ('''event driven''' code)
*Polling for things to happen then doing something ('''logic''' code)

The style of programming you choose (and hence the language you might prefer) would depend on what you want to do with the Phidget. The two sections, [[#Event Driven Code|Event Driven Code]] and [[#Logic Code|Logic Code]] below give benefits, drawbacks, and general examples of each style.

The styles can also mix. For example, you can take a defined set of steps at first such as turning on an LED or antenna (logic code) and then doing nothing until an output change event is fired (event code).

With languages that support both styles, you can mix and match. For languages that support only logic code (see the [[Software Overview#Language Support|Language Support Categories]] above) you can only use the logic paradigm style.

Examples in pseudo-code are given below for each style type so you can see how your language choice can affect your code design.

=== Logic Code ===

Logic code has use for:
* Simple, single-device applications
* Non-GUI applications (GUIs usually are event driven)
* The user driving the device rather than listening to it

Logic code is relatively easy to design well. For example, using the [[#Creating a Software Object|create]], [[#Opening the Phidget|open]], [[#Attaching the Phidget|attach]], [[#Do Things with the Phidget|do stuff]], and [[#Close the Phidget|close]] concepts introduced above, logic code to handle a Phidget might be written like this:

<br>

[[File:logic.png]]

<br>

Although this design does not explicitly capture every event that fires when data or input changes, by polling the device often enough no data will be lost.

However, logic code cannot handle constant, asynchronous events as cleanly as [[#Event Driven Code|event driven code]] can.

These designs can be mixed. So, if you find that in logic code you have a highly complex <code>if</code> loop driving your program, you should consider changing some of it to event driven code. This type of awkward if-loop might look like this:

<div class="source">
<syntaxhighlight lang=cpp>

Create Device Software Object
Open Device

Loop Until Exit Requested {
if No Device Attached {
Wait For Attachment until Timeout
if Wait Timeout Reached {
break
} else {
Initialize Device
}
} else { // Device Is Attached
if Device Data Type 1 Changed {
Do Something
}
if Device Data Type 2 Changed {
Do Something Else
}
// ... More data change functions here
}
Collect User Input
}

Close Device
Delete Device

</syntaxhighlight>
</div>

On the other hand, you can probably see that if your language does not give the option for events, you can use this structure to mimic what events would enable you to do.

=== Event Driven Code ===

Event driven code allows for clean handling of complex, asynchronous programs:
*Handling multiple Phidgets
*Handling active plugging or unplugging of the Phidget (multiple attach and detach events)
*Working behind a GUI, as many GUIs are already event driven
*Capturing all sensor data - or input and output - without constantly polling

''Without'' event driven code, you will need to constantly poll the device to see if any state has changed. If you poll at a slower rate than your input or output changes, you will not capture all data.

However, event driven code is usually not as useful or efficient for:
*Only one open and close event
*Using only one device
*Having the user (or program) ''put'' changes onto the device (in contrast to reading data ''from'' the device)

Event driven code is relatively hard to design well. It may help to draw out a '''flowchart''', '''state machine''', or at least a '''pseudo-code outline''' of your system design and all events you wish to handle before writing code.

The code examples given for each [[Software Overview#Language Support|specific language]] use events if they are supported by the language.

Using the [[#Creating a Software Object|create]], [[#Opening the Phidget|open]], [[#Attaching the Phidget|attach]], [[#Do Things with the Phidget|do stuff]], and [[#Close the Phidget|close]] concepts introduced above, event code to handle a Phidget might be written like this:

[[File:event.png]]

Once you have written this code flow, the actual order of events that occur within the program look something like this:

[[File:Eventhandler.jpg|160px]]

Note that the device itself initiates the function call, by 'firing' the event. This allows you to update only when events fire, and capture all changes, because the low-level interface is telling you when a change occurs.

==Advanced Concepts==

Now that you have the basic [[#Creating a Software Object|create]], [[#Opening the Phidget|open]], [[#Attaching the Phidget|attach]], [[#Do Things with the Phidget|do stuff]], and [[#Close the Phidget|close]] concepts introduced above, there are other useful concepts which will help you design your code to be persistent and stable.

===Logging===

You can enable logging to get more debugging information. Turning on logging happens through a Phidget API function. This would happen at the very start of your program, before even initializing your software object or opening it. Logging lets you get feedback from the Phidget libraries about every Phidget API call you make.

In C, turning on logging to the command line would look like:

<div class="source">
<syntaxhighlight lang=cpp>

CPhidget_enableLogging(PHIDGET_LOG_DEBUG, NULL);

//... All of your Phidget calls. Events called after enable will also log.

CPhidget_disableLogging();
</syntaxhighlight>
</div>

Or in Java:

<div class="source">
<syntaxhighlight lang=java>
enableLogging(PHIDGET_LOG_DEBUG, null);

//...All of your Phidget calls. Events called after enable will also log.

disableLogging();
</syntaxhighlight>
</div>

The use of null is to indicate that the output is not to a file (and hence to the command line). Otherwise, the second argument would be a string filename.

There are six different logging levels, ranging from "Give me Everything!" to "Tell me only about critical problems". The level in the examples above - '''<code>PHIDGET_LOG_DEBUG</code>''' - is a medium output level. For more information about each level and what it gives you, see the API for [[Software Overview#Language Support|your specific language]].

===Threading===

Due to the use of events, the Phidget library uses threading extensively.

For example:
* Calling <code>open()</code> starts a central thread.
* Closing everything will shut that central thread down (before the final close returns).
* Each device, once attached, starts its own read and write threads.

These threads provide the support to perform your typical [[#The Basic Functions|Basic Functions]]:

* Triggering of data events come from the context of a device read thread.
* Attach and detach events come from the context of the central thread.
* The central thread looks for device attaches and detached, keeping track of which devices are attached internally, and sending out attach and detach events to Phidgets and Managers.
* Writes are performed asynchronously by the write thread. The write queue is only 1 deep so calling a write function while there is a write pending will block.

All Phidget libraries are '''thread safe''', so you don’t need to do any locking on the Phidget objects. If you have a GUI, however, or another program with a separate thread, make sure to use one thread for events, and a separate thread with your GUI, and some form of mutual exclusion if they are both writing to the same thing.

===Exceptions and Errors===

There are two different types of errors that you can use to confirm that your program is running correctly.

====One: An error generated by a function call====

These errors are generated by ''you'' calling a function. For example, you might try to read analog sensor port number 150 on a board that only has eight. The function you used to read port 150 would return an error (in C/C++) or throw an error (in languages that support exceptions like Java, .NET, Python, or AS3).

So, these errors happen ''synchronously'' to function calls, that is, they are returned or thrown right after a function returns. You can handle these by checking the return values on your functions (in C/C++) or using an error catching method like <code>try...catch</code> in languages that support exceptions (e.g., Java, .NET, Python, AS3).

For example, in C, you might write a LocalErrorCatcher function that you can then use on every Phidget function call to detect and deal with errors:

<div class="source">
<syntaxhighlight lang=cpp>
int LocalErrorCatcher (int errorCode) {

if (errorCode != 0) { // Everything is okay if errorCode = 0

switch (errorCode) {
default:
const char *errorDescription;
LocalErrorCatcher(
CPhidget_getErrorDescription (errorCode, &errorDescription));
printf("The description for error %d is: %s\n", errorCode, errorDescription);
break;
}
}
return 0;
}

// ... Then, later, you would use it on any Phidget function:
LocalErrorCatcher(
CPhidget_open((CPhidgetHandle) device, -1));

</syntaxhighlight>
</div>

Note that:
# The function LocalErrorCatcher uses itself to check for errors on getting an error description.
# You can handle individual error codes as they are listed in the API. This only prints a general message.

Or in Java, you would try a Phidget function call, and catch any resulting exception that occurs:

<div class="source">
<syntaxhighlight lang=java>
try {
device.openAny();
} catch (PhidgetException exception) {
system.out.println("The description for error " + Integer.toString(exception.getErrorNumber()) +
" is: ", exception.getDescription());
}

</syntaxhighlight>
</div>

Like C above, you could also use a <code>try...catch</code> statement around the exception.getErrorNumber() and exception.getDescription() functions to catch any errors from those calls.

The consequences of not catching this type of error (on ''every'' function) differ by programming language.
In C/C++ these errors must be ''explicitly'' checked for after each function call, otherwise the program will simply continue on in an incorrect state. In languages that support exceptions (e.g., Java, .NET, Python, AS3), errors are returned using exceptions which will leave you no choice but to catch them, or have your program terminate without warning.

====Two: An error generated by an event====

These errors are generated by the Phidget library during runtime. For example, the Phidget device might be experiencing too high a temperature, and trigger an error. This would not necessarily be due to any one function your program called; rather, the error would appear when the problem appears and would trigger an event.

So, these errors happen ''asynchronously'', that is, something happens apart from any function calls and an error event is triggered. You can handle these by setting up an Error Event Handler.

In C, this would look like:

<div class="source">
<syntaxhighlight lang=cpp>
int ErrorEventHandler (CPhidgetHandle device, void *usrptr, int errorCode, const char *errorDescription) {
printf("The description for error %d is: %s\n", errorCode, errorDescription);
// Do something useful based on the error code
return 0;
}

// Actually hook the Error Event Handler in to receive events
LocalErrorCatcher(
CPhidget_set_OnError_Handler((CPhidgetHandle) device, LibraryErrorHandler, NULL));
</syntaxhighlight>
</div>

You'll note that the '''LibraryErrorHandler''' function is what gets called when an error event occurs, and it gives you an opportunity to handle the error.

You'll also note that there is a second function called '''LocalErrorCatcher'''. This second function handles the return value from setting the error handler. We included it here because, as these are examples on how to handle errors, the example would leave a possibly unhandled error without it. This second type of error handling and the '''LocalErrorCatcher''' function are [[#One: An error generated by a function call|described above]].

In Java, it would look like this:

<div class="source">
<syntaxhighlight lang=java>
try {
device.addErrorListener(new ErrorListener() {
public void error(ErrorEvent event) {
System.out.println(event);
}
});
} catch (PhidgetException exception) {
system.out.println("The description for error " + Integer.toString(exception.getErrorNumber()) +
" is: ", exception.getDescription());
}

</syntaxhighlight>
</div>

Like C above, the act of hooking an error listener in to the device can itself generate an error, which should be caught.

These event-type errors are also how a Phidget being run over a network announces bad passwords, lost packets, and other network problems. Locally, the errors can announce incorrect temperatures, current, and power. So, it is in your best interest to set up an error event handler and take action based on the codes and error types in the API [[Software Overview#Language Support|for your programming language]].

See the API for your [[Software Overview#Language Support|specific programming language]] for error code documentation.

===Sensitivity and Filtering===

Change Triggers are used to filter the number of events that are returned to an Application, by setting a minimum amount of activity before a Change Event is sent to your program.

This is a simple hysteresis - a minimum amount of change has to occur since the last event before another event will be fired.

If your application is implementing its own filtering, setting the ChangeTrigger, or '''sensitivity''' to zero will cause all events to fire. Change triggers are generally available only for sensor inputs events. Change triggers are referred to as ''Sensitivity'' in some device-specific APIs.

===Data Rate===

Some devices support a user-defined data rate for events.

* The data rate is set in milliseconds, with a range from up 1ms to 1000ms, depending on the Phidget.
* Data rates greater then 8ms generally need to be a multiple of 8 (8,16,24,...,496,...,996,1000).
* Data rates lower then 8ms are supported as: 4ms, 2ms, 1ms.
* Data rate is a maximum rate
* Data rate will be superseded by a non-zero sensitivity on devices that support both sensitivity and data rate.

See the main page for your device - found on its product page on [{{SERVER}} our main website] for more details on available data rates and specifications.

Note that this data rate '''is not the rate at which you will receive data'''. Rather, it is the amount of time over which events are averaged before being sent. It may help to think of our specification of data rate as an ''averaging time''. This means that setting a data rate of 24 ms will try to give you data averaged over 24 ms, and send it every 24 ms. Depending on your computer, events may or may not be dropped. If events are dropped, the data points that are received still represent 24 ms (or whatever the data rate is set to). This means data is lost.

Conversely, if you are [[#Logic Code|polling]], and you set the data rate to longer than your polling rate, you will receive duplicate, averaged data. For example, setting the data rate to 24 ms and then polling every 12 ms will give you duplicate readings every other poll. To poll and not miss any data, the rate that your code polls must match the rate that you set for the {{Code|setDataRate()}} function in our API.

===Using the Dictionary===

The Phidget Dictionary is a service provided by the Phidget WebService. The dictionary:
* Is a centralized collection of key-value pairs
* Works only over the webservice
* Can be accessed and changed from any number of webservice clients
* Makes use of extended regular expressions (denoted between two forward slashes) for key matching
* Is also a foundation part of the webservice itself, and controls access of all Phidgets through the {{Code|openRemote}} and {{Code|openRemoteIP}} interfaces
* Can be used as an abstracted or higher-level interface for remotely managing Phidgets

We have a more in-depth description of the Dictionary (with pictures) on the main [[Phidget Dictionary]] page.

The intended use for the dictionary is as a central repository for communication and persistent storage of data between several client applications. For example, the computer directly connected to a Phidget could create and change keys for additional events on top of (or even instead of) those already thrown by the Phidget device API. The dictionary API is very high-level and thus very flexible - essentially any application of adding keys, changing keys (and throwing events), and getting values of keys can be handled by the Dictionary.

Note that you should never add or modify a key that starts with {{Code|/PSK/}} or {{Code|/PCK/}} as these are the keys that Phidgets use. Unless, of course, you want to explicitly modify Phidget specific data - and this is highly discouraged, as it’s very easy to break things. Listening to these keys is fine if so desired.

Refer to the API [[Software Overview#Language Support|for your specific language]] for the full Dictionary API.

===Long Term Code Maintenance===

Thinking long term from the start is incredibly useful. Phidgets as a company is constantly developing and inventing, and our API gets improved and changed to still work with older devices while adding support for new ones.

We release library updates - both for operating systems and languages - on a regular basis. We '''strongly''' recommend updating your own libraries as we release them. This goes for both the libraries and the WebService, as the versions must match.

This form of updating (did we mention that we strongly recommend it?) is the single most important thing you can do to reduce maintenance issues with your Phidget software down the road.

Every so often, customers come to us having run the same code for years, without updating. Then, for some reason, they have to update (say, for an operating system migration). And their code no longer works. What do to then? We can work with these customers to find out which of the many updates was the one to cause the problem - a difficult and very time consuming process. And over the course of multiple years, we may no longer stock or even manufacture that particular Phidget. You can imagine that a process with these limitations can take a very long time to resolve, if it can be resolved at all.

Conversely, if you update every time, this time frame is greatly reduced. We make a serious effort to test every library update, and although some backwards-compatibility problems do (rarely) get through, we have a fresh memory of what was changed and can work with you to quickly either debug the new libraries or get you a working version.

In addition to library updates, here are a few other tips and tricks to reduce your maintenance time:
* If you are using [[#Logging|Logging]], don't remove the logging code when you finalize your release. Simply comment it out so you can turn it on again later and debug quickly.
* Some long-term problems can be detected early by listening to library messages and errors. Handling [[#Exceptions and Errors|Exceptions and Errors]] will allow your code to run silently until something is wrong, in which case you'll know right away.

If you are looking for more help on how to work with our library updating, please feel welcome to [[Contact Us|contact us]].

==Summary==

This page has gone through [[#The Basic Functions|basic]] to [[#Advanced Concepts|advanced]] uses of the Phidget API. We've used C and Java here as example languages. If you're using a different language, we include similar snippets of code (without the in-depth description) in the documentation [[Software Overview#Language Support|for your language]].

If you've read this far and are still hungry for more, try learning more about your hardware; we have a number of [[Primers|high level teaching pages]] about hardware as well.

InterfaceKit Digital Outputs

2012-06-29T15:27:28Z

Cora:

[[Category: Primer]]

==Introduction==

Digital Outputs can be used to drive LEDs, solid state relays, and transistors (or anything that will accept a CMOS signal).
Digital outputs can be used to control devices that accept a +5V control signal.
With transistors and some electronics experience, other devices can be controlled, such as buzzers, lights, larger LEDs, relays.

==Specifications and Features==

[[Image:digital_output.jpg|right|thumb|A Phidgets digital output.]]

The 250 ohm resistance is internal to the PhidgetInterfaceKit 8/8/8, and limits the current that can flow through the output.
This is intended to protect the device from being damaged if there is a short to ground or if an LED is used.
Ultimately this means the maximum current output of the digital outputs is 16mA. In practice you should not try to draw 16mA from the outputs for extended periods of time though as this can lead to damaged components. You should try to limit your current draw to less than 5mA though up to 10 would not cause any immediate concerns.
The output is intended to drive TTL or CMOS inputs; it is not designed to provide power to an external circuit.

In practice the frequency at which these outputs can be switched is highly dependent on system properties such as OS, USB hardware, and cabling. However, it is a good bet that the majority of systems will be able to achieve 1kHz.

<br clear="all">
===Ground Protection===
Ground terminals on the InterfaceKit share a common ground with USB ground.
Because they are not internally isolated, these terminals will expose the USB ground potential of the PC to which they are connected.
Be sure you are completely familiar with any circuit you intend to connect to the InterfaceKit before it is connected.
If a reverse voltage or dangerously high voltage is applied to the input or output terminals, damage to the Phidget or the PC may result.

===5 Volt Terminal Block===
For users who need it, we provide 5V on the terminal block next to Digital Output 7.

==Using the Digital Outputs==
Here are some circuit diagrams that illustrate how to connect various devices to the digital outputs on your Phidget.

===Driving an LED with the Digital Output===

[[Image:LED_digital_output.jpg|right|thumb|Schematic for connecting to an LED.]]

Connecting an LED to a digital output is simple. Wire the anode to a digital output labeled 0 to 7 on the Interface Kit, and the cathode to a supplied ground, labeled G.

<br clear="all">
===Using a 3052 SSR Board with a Digital Output===

[[Image:3052_digital_output.jpg|right|thumb|Schematic for connecting a 3052 board.]]

Setting the digital output to true causes the output of the 3052 to turn on.
This can be used to control AC or DC devices.

The load can also be switched with the 3052 on the high side.
High side switching is helpful for powering more complicated circuitry that cannot tolerate having multiple grounds.

<br clear="all">
===Isolating a Digital Output with a MOSFET based SSR===

[[Image:isolating_digital_output_ssr.jpg|right|thumb|Schematic for isolating a digital input with an SSR.]]

It’s possible to wire up your own Solid State Relay to the digital output.
MOSFET based SSRs have the advantage that they can be understood as being a simple switch.

There are many other types of SSRs that are more suitable for controlling higher power, higher voltage AC devices that can also be controlled in the same fashion.

<br clear="all">
===Isolating a Digital Output with an Optocoupler===

[[Image:isolating_digital_output_optocoupler.jpg|right|thumb|Schematic for isolating a digital input with an optocoupler.]]

In some applications, particularly where there is a lot of electrical noise (automotive), or where you want maximum protection of the circuitry (interactive installations, kiosks), electrical isolation buys you a huge margin of protection.
Driving the LED causes the output transistor to sink current.

The maximum current through the transistor will depend in part on the characteristics of the optocoupler.

<br clear="all">
===Controlling a Relay with a N-Channel MOSFET===

[[Image:relay_nmos.jpg|right|thumb|Schematic for using a relay with an NMOS transistor.]]

A inexpensive mosfet and flyback diode can be used to control larger loads - relays for example - directly from the digital output.
Be sure to use a Logic-Level MOSFET so that the +5V Digital Output is able to turn it on.

<br clear="all">
===Controlling a Relay with a NPN Transistor===

[[Image:relay_npn.jpg|right|thumb|Schematic for using a relay with an NPN transistor.]]

This circuit is very similar to the N-channel mosfet - but you may already have NPN transistors on hand.

<br clear="all">
===Using a 3051 Dual Relay Board with one or two Digital Outputs===

[[Image:3051_digital_outputs.jpg|right|thumb|Schematic for using a 3051 board.]]

The 3051 Dual Relay Board is designed to be used with the PhidgetInterfaceKit 8/8/8.
An Analog Input can be used to supply power to the relays, and one or two digital outputs used to control the relays.
The 3051 is a good option if you need a couple relays in your project.
<br clear="all">

==Update Rate==

Please check the specification for the maximum rate of sampling that the Digital input can measure. This is often slower than your program can change it. So, if you change the output one way and then flip it back immediately in your code, the interface kit may not register the change.

Digital Input Guide

2012-06-29T15:24:38Z

Cora: /* Specifications */

[[Category: Primer]]

==Introduction==

Digital Inputs can be used to convey the state of various devices such as push buttons, limit switches, relays, or logic level outputs.
They have two states: Low (or TRUE), and High (or FALSE).
Any signal that is expected to interact with more than just these 2 states is inappropriate for this type of input.

Digital inputs are one of the easiest components to work with, since all that is required is a simple check to see which state they are in when an event triggers.

==Specifications==

===Digital Input Hardware Filter===
There is built-in filtering on the digital input, to eliminate false triggering from electrical noise.
The digital input is first RC filtered by a 15K/100nF node, which will reject noise of higher frequency than 1Khz.
This filter generally eliminates the need to shield the digital input from inductive and capacitive coupling likely to occur in wiring harnesses.
You can further reduce noise by externally filtering the input signal, but you will lose sensitivity in the process.

===Digital Input Hysteresis===
The digital input has hysteresis - that is, it will hold its current state (false or true), unless a large change occurs.
To guarantee FALSE, the digital input must be at least 3.75V, and to guarantee TRUE, the digital input must be less than 1.25V.

===Digital Input Sampling Characteristics===
The state of the digital inputs are reported back to the PC periodically.
During this sampling period, if a digital input was true for greater than 4.0ms, the digital input is guaranteed to be reported as true in software.
This makes the digital input much more sensitive to reporting TRUE state, and makes it useful to watch for short events.
Any Digital Input True events of less than 1.5ms are never reported.

===Electrical Specifications===

[[Image:digital_input.jpg|right|thumb|Schematic for a Phidgets digital input.]]

The digital inputs have a built in 15K pull-up resistor.
By connecting external circuitry, and forcing the input to Ground, the Digital Input in software will read as TRUE.
The default state is FALSE - when you have nothing connected, or your circuitry (switch, etc) is not pulling the input to ground.

<br clear="all">

==Using the Digital Inputs==
Here are some circuit diagrams that illustrate how to connect various devices to the digital inputs on your Phidget.

===Wiring a switch to a Digital Input===

[[Image:switch_digital_input.jpg|right|thumb|Schematic for connecting a switch to a digital input.]]

Closing the switch causes the digital input to report TRUE.

<br clear="all">
===Monitoring the Position of a Relay===

[[Image:relay_position.jpg|right|thumb|Schematic for connecting to a relay.]]

The relay contact can be treated as a switch, and wired up similarly.
When the relay contact is closed, the Digital Input will report TRUE.

<br clear="all">
===Detecting an External Voltage with an N-Channel MOSFET===

[[Image:external_voltage_mosfet.jpg|right|thumb|Schematic for detecting voltage with a NMOS transistor.]]

A MOSFET can be used to detect the presence of an external voltage.
The external voltage will turn on the MOSFET, causing it to short the Digital Input to Ground.
If the MOSFET is conducting > 270uA, the Digital Input is guaranteed to report TRUE.
If the MOSFET is conducting < 67uA, the Digital Input is guaranteed to report FALSE.
The voltage level required to turn on the MOSFET depends on the make of of MOSFET you are using. Typical values are 2V-6V.

<br clear="all">
===Isolating a Digital Input with an Optocoupler===

[[Image:isolating_digital_input_optocoupler.jpg|right|thumb|Schematic showing isolation of a digital input with an optocoupler.]]

When driving current through the LED, the Digital Input will report TRUE.
The amount of current required will depend on the optocoupler used.
Design to sink at least 270uA to cause the digital input to report TRUE, and less than 67uA to report FALSE.

<br clear="all">
===Detecting an External Voltage with an NPN Transistor===

[[Image:external_voltage_npn.jpg|right|thumb|Schematic for detecting voltage with an NPN transistor.]]

This circuit can be used to measure if a battery is connected, or if 12V (for example) is on a wire.
By designing to have Collector-Emitter current > 270uA, the digital input will report TRUE.

<br clear="all">
===Using a Capacitive or Inductive Proximity Switch===

[[Image:proximity_switch.jpg|right|thumb|Schematic for connecting to a proximity switch.]]

Capacitive proximity switches can detect the presence of nearby non-metallic objects, whereas inductive proximity switches can detect only the presence of metallic objects.
To properly interface one of these proximity switches to the digital inputs, a 3-wire proximity switch is required, as well as an external power supply.
We have checked the following switch from Automation Direct to verify that it works with the Digital Inputs.
Similar capacitive or inductive proximity switches from other manufacturers should work just as well.

{|border=1
|+'''Switches'''
|-
! Manufacturer
! Web Page
! Capacitive Part No.
! Inductive Part No.
|-
| Automation Direct
| www.automationdirect.com
| CT1 Series
| AM1 Series
|}

<br clear="all">
===Using an FSR or Variable Resistor as a Switch===

[[Image:fsr_switch.jpg|right|thumb|Schematic for using an FSR as a switch.]]

The digital inputs can be easily wired to use many variable resistors as switches.
If the resistance falls below 3.75k Ohms, the Digital Input will go TRUE.
If the resistance rises above 75k Ohms, the Digital Input will go FALSE.

<br clear="all">

==Helpful Tips==
===Update Rate===
*125 samples/sec is for each individual channel, not split between all channels.
*You can't "turn off" unused channels to improve update rate on the active channels.
*This value is already close to the spec for our USB processor, so there isn't much room to tinker.

Digital Input Guide

2012-06-29T15:24:24Z

Cora: /* Helpful Tips */

[[Category: Primer]]

==Introduction==

Digital Inputs can be used to convey the state of various devices such as push buttons, limit switches, relays, or logic level outputs.
They have two states: Low (or TRUE), and High (or FALSE).
Any signal that is expected to interact with more than just these 2 states is inappropriate for this type of input.

Digital inputs are one of the easiest components to work with, since all that is required is a simple check to see which state they are in when an event triggers.

==Specifications==

===Digital Input Hardware Filter===
There is built-in filtering on the digital input, to eliminate false triggering from electrical noise.
The digital input is first RC filtered by a 15K/100nF node, which will reject noise of higher frequency than 1Khz.
This filter generally eliminates the need to shield the digital input from inductive and capacitive coupling likely to occur in wiring harnesses.
You can further reduce noise by externally filtering the input signal, but you will lose sensitivity in the process.

===Digital Input Hysteresis===
The digital input has hysteresis - that is, it will hold it’s current state (false or true), unless a large change occurs.
To guarantee FALSE, the digital input must be at least 3.75V, and to guarantee TRUE, the digital input must be less than 1.25V.

===Digital Input Sampling Characteristics===
The state of the digital inputs are reported back to the PC periodically.
During this sampling period, if a digital input was true for greater than 4.0ms, the digital input is guaranteed to be reported as true in software.
This makes the digital input much more sensitive to reporting TRUE state, and makes it useful to watch for short events.
Any Digital Input True events of less than 1.5ms are never reported.

===Electrical Specifications===

[[Image:digital_input.jpg|right|thumb|Schematic for a Phidgets digital input.]]

The digital inputs have a built in 15K pull-up resistor.
By connecting external circuitry, and forcing the input to Ground, the Digital Input in software will read as TRUE.
The default state is FALSE - when you have nothing connected, or your circuitry (switch, etc) is not pulling the input to ground.

<br clear="all">
==Using the Digital Inputs==
Here are some circuit diagrams that illustrate how to connect various devices to the digital inputs on your Phidget.

===Wiring a switch to a Digital Input===

[[Image:switch_digital_input.jpg|right|thumb|Schematic for connecting a switch to a digital input.]]

Closing the switch causes the digital input to report TRUE.

<br clear="all">
===Monitoring the Position of a Relay===

[[Image:relay_position.jpg|right|thumb|Schematic for connecting to a relay.]]

The relay contact can be treated as a switch, and wired up similarly.
When the relay contact is closed, the Digital Input will report TRUE.

<br clear="all">
===Detecting an External Voltage with an N-Channel MOSFET===

[[Image:external_voltage_mosfet.jpg|right|thumb|Schematic for detecting voltage with a NMOS transistor.]]

A MOSFET can be used to detect the presence of an external voltage.
The external voltage will turn on the MOSFET, causing it to short the Digital Input to Ground.
If the MOSFET is conducting > 270uA, the Digital Input is guaranteed to report TRUE.
If the MOSFET is conducting < 67uA, the Digital Input is guaranteed to report FALSE.
The voltage level required to turn on the MOSFET depends on the make of of MOSFET you are using. Typical values are 2V-6V.

<br clear="all">
===Isolating a Digital Input with an Optocoupler===

[[Image:isolating_digital_input_optocoupler.jpg|right|thumb|Schematic showing isolation of a digital input with an optocoupler.]]

When driving current through the LED, the Digital Input will report TRUE.
The amount of current required will depend on the optocoupler used.
Design to sink at least 270uA to cause the digital input to report TRUE, and less than 67uA to report FALSE.

<br clear="all">
===Detecting an External Voltage with an NPN Transistor===

[[Image:external_voltage_npn.jpg|right|thumb|Schematic for detecting voltage with an NPN transistor.]]

This circuit can be used to measure if a battery is connected, or if 12V (for example) is on a wire.
By designing to have Collector-Emitter current > 270uA, the digital input will report TRUE.

<br clear="all">
===Using a Capacitive or Inductive Proximity Switch===

[[Image:proximity_switch.jpg|right|thumb|Schematic for connecting to a proximity switch.]]

Capacitive proximity switches can detect the presence of nearby non-metallic objects, whereas inductive proximity switches can detect only the presence of metallic objects.
To properly interface one of these proximity switches to the digital inputs, a 3-wire proximity switch is required, as well as an external power supply.
We have checked the following switch from Automation Direct to verify that it works with the Digital Inputs.
Similar capacitive or inductive proximity switches from other manufacturers should work just as well.

{|border=1
|+'''Switches'''
|-
! Manufacturer
! Web Page
! Capacitive Part No.
! Inductive Part No.
|-
| Automation Direct
| www.automationdirect.com
| CT1 Series
| AM1 Series
|}

<br clear="all">
===Using an FSR or Variable Resistor as a Switch===

[[Image:fsr_switch.jpg|right|thumb|Schematic for using an FSR as a switch.]]

The digital inputs can be easily wired to use many variable resistors as switches.
If the resistance falls below 3.75k Ohms, the Digital Input will go TRUE.
If the resistance rises above 75k Ohms, the Digital Input will go FALSE.

<br clear="all">

==Helpful Tips==
===Update Rate===
*125 samples/sec is for each individual channel, not split between all channels.
*You can't "turn off" unused channels to improve update rate on the active channels.
*This value is already close to the spec for our USB processor, so there isn't much room to tinker.

Digital Input Guide

2012-06-29T15:23:07Z

Cora: /* Helpful Tips */

[[Category: Primer]]

==Introduction==

Digital Inputs can be used to convey the state of various devices such as push buttons, limit switches, relays, or logic level outputs.
They have two states: Low (or TRUE), and High (or FALSE).
Any signal that is expected to interact with more than just these 2 states is inappropriate for this type of input.

Digital inputs are one of the easiest components to work with, since all that is required is a simple check to see which state they are in when an event triggers.

==Specifications==

===Digital Input Hardware Filter===
There is built-in filtering on the digital input, to eliminate false triggering from electrical noise.
The digital input is first RC filtered by a 15K/100nF node, which will reject noise of higher frequency than 1Khz.
This filter generally eliminates the need to shield the digital input from inductive and capacitive coupling likely to occur in wiring harnesses.
You can further reduce noise by externally filtering the input signal, but you will lose sensitivity in the process.

===Digital Input Hysteresis===
The digital input has hysteresis - that is, it will hold it’s current state (false or true), unless a large change occurs.
To guarantee FALSE, the digital input must be at least 3.75V, and to guarantee TRUE, the digital input must be less than 1.25V.

===Digital Input Sampling Characteristics===
The state of the digital inputs are reported back to the PC periodically.
During this sampling period, if a digital input was true for greater than 4.0ms, the digital input is guaranteed to be reported as true in software.
This makes the digital input much more sensitive to reporting TRUE state, and makes it useful to watch for short events.
Any Digital Input True events of less than 1.5ms are never reported.

===Electrical Specifications===

[[Image:digital_input.jpg|right|thumb|Schematic for a Phidgets digital input.]]

The digital inputs have a built in 15K pull-up resistor.
By connecting external circuitry, and forcing the input to Ground, the Digital Input in software will read as TRUE.
The default state is FALSE - when you have nothing connected, or your circuitry (switch, etc) is not pulling the input to ground.

<br clear="all">
==Using the Digital Inputs==
Here are some circuit diagrams that illustrate how to connect various devices to the digital inputs on your Phidget.

===Wiring a switch to a Digital Input===

[[Image:switch_digital_input.jpg|right|thumb|Schematic for connecting a switch to a digital input.]]

Closing the switch causes the digital input to report TRUE.

<br clear="all">
===Monitoring the Position of a Relay===

[[Image:relay_position.jpg|right|thumb|Schematic for connecting to a relay.]]

The relay contact can be treated as a switch, and wired up similarly.
When the relay contact is closed, the Digital Input will report TRUE.

<br clear="all">
===Detecting an External Voltage with an N-Channel MOSFET===

[[Image:external_voltage_mosfet.jpg|right|thumb|Schematic for detecting voltage with a NMOS transistor.]]

A MOSFET can be used to detect the presence of an external voltage.
The external voltage will turn on the MOSFET, causing it to short the Digital Input to Ground.
If the MOSFET is conducting > 270uA, the Digital Input is guaranteed to report TRUE.
If the MOSFET is conducting < 67uA, the Digital Input is guaranteed to report FALSE.
The voltage level required to turn on the MOSFET depends on the make of of MOSFET you are using. Typical values are 2V-6V.

<br clear="all">
===Isolating a Digital Input with an Optocoupler===

[[Image:isolating_digital_input_optocoupler.jpg|right|thumb|Schematic showing isolation of a digital input with an optocoupler.]]

When driving current through the LED, the Digital Input will report TRUE.
The amount of current required will depend on the optocoupler used.
Design to sink at least 270uA to cause the digital input to report TRUE, and less than 67uA to report FALSE.

<br clear="all">
===Detecting an External Voltage with an NPN Transistor===

[[Image:external_voltage_npn.jpg|right|thumb|Schematic for detecting voltage with an NPN transistor.]]

This circuit can be used to measure if a battery is connected, or if 12V (for example) is on a wire.
By designing to have Collector-Emitter current > 270uA, the digital input will report TRUE.

<br clear="all">
===Using a Capacitive or Inductive Proximity Switch===

[[Image:proximity_switch.jpg|right|thumb|Schematic for connecting to a proximity switch.]]

Capacitive proximity switches can detect the presence of nearby non-metallic objects, whereas inductive proximity switches can detect only the presence of metallic objects.
To properly interface one of these proximity switches to the digital inputs, a 3-wire proximity switch is required, as well as an external power supply.
We have checked the following switch from Automation Direct to verify that it works with the Digital Inputs.
Similar capacitive or inductive proximity switches from other manufacturers should work just as well.

{|border=1
|+'''Switches'''
|-
! Manufacturer
! Web Page
! Capacitive Part No.
! Inductive Part No.
|-
| Automation Direct
| www.automationdirect.com
| CT1 Series
| AM1 Series
|}

<br clear="all">
===Using an FSR or Variable Resistor as a Switch===

[[Image:fsr_switch.jpg|right|thumb|Schematic for using an FSR as a switch.]]

The digital inputs can be easily wired to use many variable resistors as switches.
If the resistance falls below 3.75k Ohms, the Digital Input will go TRUE.
If the resistance rises above 75k Ohms, the Digital Input will go FALSE.

<br clear="all">

==Helpful Tips==
===Update Rate===
*125 samples/sec is for each individual channel, not split between all channels.
*You can't "turn off" unused channels to improve update rate on the active channels.
*This value is already close to the spec for our USB processor, so there isn't much room to tinker with this spec.

Digital Input Guide

2012-06-29T15:22:54Z

Cora: /* Glossary */

[[Category: Primer]]

==Introduction==

Digital Inputs can be used to convey the state of various devices such as push buttons, limit switches, relays, or logic level outputs.
They have two states: Low (or TRUE), and High (or FALSE).
Any signal that is expected to interact with more than just these 2 states is inappropriate for this type of input.

Digital inputs are one of the easiest components to work with, since all that is required is a simple check to see which state they are in when an event triggers.

==Specifications==

===Digital Input Hardware Filter===
There is built-in filtering on the digital input, to eliminate false triggering from electrical noise.
The digital input is first RC filtered by a 15K/100nF node, which will reject noise of higher frequency than 1Khz.
This filter generally eliminates the need to shield the digital input from inductive and capacitive coupling likely to occur in wiring harnesses.
You can further reduce noise by externally filtering the input signal, but you will lose sensitivity in the process.

===Digital Input Hysteresis===
The digital input has hysteresis - that is, it will hold it’s current state (false or true), unless a large change occurs.
To guarantee FALSE, the digital input must be at least 3.75V, and to guarantee TRUE, the digital input must be less than 1.25V.

===Digital Input Sampling Characteristics===
The state of the digital inputs are reported back to the PC periodically.
During this sampling period, if a digital input was true for greater than 4.0ms, the digital input is guaranteed to be reported as true in software.
This makes the digital input much more sensitive to reporting TRUE state, and makes it useful to watch for short events.
Any Digital Input True events of less than 1.5ms are never reported.

===Electrical Specifications===

[[Image:digital_input.jpg|right|thumb|Schematic for a Phidgets digital input.]]

The digital inputs have a built in 15K pull-up resistor.
By connecting external circuitry, and forcing the input to Ground, the Digital Input in software will read as TRUE.
The default state is FALSE - when you have nothing connected, or your circuitry (switch, etc) is not pulling the input to ground.

<br clear="all">
==Using the Digital Inputs==
Here are some circuit diagrams that illustrate how to connect various devices to the digital inputs on your Phidget.

===Wiring a switch to a Digital Input===

[[Image:switch_digital_input.jpg|right|thumb|Schematic for connecting a switch to a digital input.]]

Closing the switch causes the digital input to report TRUE.

<br clear="all">
===Monitoring the Position of a Relay===

[[Image:relay_position.jpg|right|thumb|Schematic for connecting to a relay.]]

The relay contact can be treated as a switch, and wired up similarly.
When the relay contact is closed, the Digital Input will report TRUE.

<br clear="all">
===Detecting an External Voltage with an N-Channel MOSFET===

[[Image:external_voltage_mosfet.jpg|right|thumb|Schematic for detecting voltage with a NMOS transistor.]]

A MOSFET can be used to detect the presence of an external voltage.
The external voltage will turn on the MOSFET, causing it to short the Digital Input to Ground.
If the MOSFET is conducting > 270uA, the Digital Input is guaranteed to report TRUE.
If the MOSFET is conducting < 67uA, the Digital Input is guaranteed to report FALSE.
The voltage level required to turn on the MOSFET depends on the make of of MOSFET you are using. Typical values are 2V-6V.

<br clear="all">
===Isolating a Digital Input with an Optocoupler===

[[Image:isolating_digital_input_optocoupler.jpg|right|thumb|Schematic showing isolation of a digital input with an optocoupler.]]

When driving current through the LED, the Digital Input will report TRUE.
The amount of current required will depend on the optocoupler used.
Design to sink at least 270uA to cause the digital input to report TRUE, and less than 67uA to report FALSE.

<br clear="all">
===Detecting an External Voltage with an NPN Transistor===

[[Image:external_voltage_npn.jpg|right|thumb|Schematic for detecting voltage with an NPN transistor.]]

This circuit can be used to measure if a battery is connected, or if 12V (for example) is on a wire.
By designing to have Collector-Emitter current > 270uA, the digital input will report TRUE.

<br clear="all">
===Using a Capacitive or Inductive Proximity Switch===

[[Image:proximity_switch.jpg|right|thumb|Schematic for connecting to a proximity switch.]]

Capacitive proximity switches can detect the presence of nearby non-metallic objects, whereas inductive proximity switches can detect only the presence of metallic objects.
To properly interface one of these proximity switches to the digital inputs, a 3-wire proximity switch is required, as well as an external power supply.
We have checked the following switch from Automation Direct to verify that it works with the Digital Inputs.
Similar capacitive or inductive proximity switches from other manufacturers should work just as well.

{|border=1
|+'''Switches'''
|-
! Manufacturer
! Web Page
! Capacitive Part No.
! Inductive Part No.
|-
| Automation Direct
| www.automationdirect.com
| CT1 Series
| AM1 Series
|}

<br clear="all">
===Using an FSR or Variable Resistor as a Switch===

[[Image:fsr_switch.jpg|right|thumb|Schematic for using an FSR as a switch.]]

The digital inputs can be easily wired to use many variable resistors as switches.
If the resistance falls below 3.75k Ohms, the Digital Input will go TRUE.
If the resistance rises above 75k Ohms, the Digital Input will go FALSE.

<br clear="all">

==Helpful Tips==
===Update Rate===
*125 samples/sec is for each individual channel, not split between all channels.
*You can't "turn off" unused channels to improve update rate on the active channels.
*This value is already close to the spec for our USB processor, so there isn't much room for users to tinker with this spec.