|
|
| (260 intermediate revisions by 10 users not shown) |
| Line 1: |
Line 1: |
| Phidgets can run on a variety of Operating Systems, and be driven by a variety of Programming Languages.
| | #REDIRECT [[Phidget Programming Basics]] |
| | |
| To simply plug a Phidget in to your computer and have basic data printed to your computer screen, you can use the [[Phidget Manager]] on Windows and Mac OSX.
| |
| | |
| To '''work directly''' with a Phidget and do things with the data you collect from it, you will need to write code.
| |
| | |
| This page provides links to all of the Phidget-supported [[#Operating System Support|operating systems]] and [[#Language Support|languages]]. It also provides an overview of [[#General Phidget Programming|general Phidget use in code]], and of the two [[#Different Code Styles|different types of code design]] you can use to create your project.
| |
| | |
| To control a Phidget via code, you will need:
| |
| #The Phidget '''Basic Drivers''' and [[#Operating System Support|software libraries]] (also called the Phidget Manager on Windows and Mac)
| |
| #'''Tools and Libraries''' for your [[#Language Support|programming language]]
| |
| #'''Example Code''' in your [[#Language Support|programming language]]
| |
| #An '''API Reference''' list of functions you can use in [[#Language Support|your language]] to drive your device
| |
| | |
| <br>
| |
| | |
| == Operating System Support ==
| |
| | |
| On these pages you will find the basic drivers and code libraries for using your Phidget either directly through USB or remotely via the [[Phidget Webservice]].
| |
| | |
| Phidgets can '''run directly''' on these operating systems:
| |
| | |
| * [[OS - Windows]]
| |
| * [[OS - Mac OSX]]
| |
| * [[OS - Linux]]
| |
| * [[OS - Windows CE]] ??
| |
| * [[OS - Android]] (3.1 and above)
| |
| | |
| Phidgets can be '''driven remotely''' by these operating systems:
| |
| | |
| * [[OS - Windows]]
| |
| * [[OS - Mac OSX]]
| |
| * [[OS - Linux]]
| |
| * [[OS - Windows CE]]
| |
| * [[OS - iOS]]
| |
| * [[OS - Android]]
| |
| | |
| == Language Support ==
| |
| | |
| We provide a variety of supported languages for using Phidgets.
| |
| | |
| Although each language has its own drivers, many languages also depend on the '''high-level drivers''' being installed as well. These can be found on the [[#Operating System Support|operating system pages]] above.
| |
| | |
| Phidgets can be programmed either by an '''event-driven''' model, or by traditional '''logic code'''. All languages below support logic code. Some languages support our complete API, which includes support for event-driven design.
| |
| | |
| If you are flexible on what language you can use, we suggest choosing a language which supports event-driven code.
| |
| | |
| Phidgets have libraries to support [[#Event Driven Code|Event Driven Code]] in the following languages:
| |
| | |
| * [[Language - C/C++]]
| |
| * ...
| |
| | |
| Phidgets have libraries to support only [[#Logic Code|Logic Code]] in the following languages:
| |
| | |
| * [[Language - MATLAB]]
| |
| * ...
| |
| | |
| == General Phidget Programming ==
| |
| | |
| 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>
| |
| # Ensure a [[#Attaching the Phidget|Phidget is attached]] (plugged in) by using the <code>object</code>
| |
| # Use functions that the <code>object</code> provides, like turning on LEDs, reading sensors, triggering events on data change, etc
| |
| # When you are done, close and delete the <code>object</code>
| |
| | |
| === 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 style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source lang=java>
| |
| | |
| // Create a new Accelerometer object
| |
| AccelerometerPhidget device = new AccelerometerPhidget();
| |
| | |
| </source>
| |
| </font>
| |
| </div>
| |
| <br>
| |
| <div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source lang=java>
| |
| | |
| | |
| // Create a new RFID device object
| |
| RFIDPhidget device = new RFIDPhidget();
| |
| | |
| </source>
| |
| </font>
| |
| </div>
| |
| | |
| Or in C:
| |
| | |
| <div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source lang=c>
| |
| | |
| // Create a new Accelerometer object
| |
| CPhidgetAccelerometerHandle device = 0;
| |
| CPhidgetAccelerometer_create(&device);
| |
| | |
| </source>
| |
| </font>
| |
| </div>
| |
| <br>
| |
| <div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source lang=c>
| |
| | |
| // Create a new RFID device object
| |
| CPhidgetRFIDHandle device = 0;
| |
| CPhidgetRFID_create(&device);
| |
| | |
| </source>
| |
| </font>
| |
| </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 style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source lang=java>
| |
| device.open();
| |
| </source>
| |
| </font>
| |
| </div>
| |
| | |
| Or in C:
| |
| | |
| <div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source lang=c>
| |
| CPhidget_open((CPhidgetHandle) device, -1);
| |
| </source>
| |
| </font>
| |
| </div>
| |
| | |
| All specific language calls can be found in the API documentation located on each [[#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.
| |
| | |
| === Attaching the Phidget ===
| |
| | |
| Physically, attaching a Phidget means plugging it in. 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 style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source 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!");
| |
| }
| |
| });
| |
| </source>
| |
| </font>
| |
| </div>
| |
| | |
| Or to use an event to detect attachment in C:
| |
| | |
| <div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source lang=c>
| |
| int AttachHandler (CPhidgetHandle device, void *userData) {
| |
| printf("A new device has been plugged in!");
| |
| return 0;
| |
| }
| |
| | |
| // .....Then, in the main code after creating a Phidget object "device":
| |
| CPhidget_set_OnAttach_Handler((CPhidgetHandle) device, AttachHandler, NULL);
| |
| </source>
| |
| </font>
| |
| </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 downloadable from the [[#Language Pages|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 style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source lang=java>
| |
| // Wait until a device is plugged in
| |
| device.waitForAttachment();
| |
| </source>
| |
| </font>
| |
| </div>
| |
| | |
| Or in C (again, device has been '''created and opened''') :
| |
| | |
| <div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source 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
| |
| </source>
| |
| </font>
| |
| </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 Phidget software object (named, for example, <code>device</code> as above) that is:
| |
| *Created
| |
| *Properly attached to any events
| |
| *Opened
| |
| *Attached (plugged in)
| |
| | |
| ...Then, you can actually call function to turn LEDs on, change output state, read data from sensors, etc.
| |
| | |
| Software information on this step can be found in the individual language APIs on the [[#Language Support|specific language pages]].
| |
| | |
| === 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 style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source lang=java>
| |
| device.close();
| |
| device = null;
| |
| </source>
| |
| </font>
| |
| </div>
| |
| | |
| Or, in C:
| |
| <div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source lang=c>
| |
| CPhidget_close((CPhidgetHandle) device);
| |
| CPhidget_delete((CPhidgetHandle) device);
| |
| </source>
| |
| </font>
| |
| </div>
| |
| | |
| == Different Code Styles ==
| |
| | |
| 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)
| |
| | |
| === Choosing A Code Style ===
| |
| | |
| 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 [[#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.
| |
| | |
| === Event Driven Code ===
| |
| | |
| Event driven code allows for ''smooth handling of complex programs''. Event driven code '''is''' useful for:
| |
| *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 - device changes
| |
| | |
| 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.
| |
| | |
| 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)
| |
| | |
| In addition, 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.
| |
| | |
| All [[#Language Support|Supported Languages]] that handle event driven code have examples of how to write such code on the specific language pages. Event driven examples follow this structure, and places to start changing this structure are noted:
| |
| | |
| <div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source lang=text>
| |
| | |
| // --- Event Functions ---
| |
| | |
| Create any Language-Specific Functions (error handling, etc)
| |
| | |
| Create General Attach, Detach, and Error Handling Functions
| |
| On attach: Initialize hardware (antennas, etc)
| |
| On detach: Reset any state variables (attached boolean, etc)
| |
| | |
| Create Hardware-Specific Functions
| |
| // ****** Add your own handling code for these data change events ******
| |
| On data input change: Notify using basic output (screen message, turn on LED, etc)
| |
| | |
| // --- Main Code ---
| |
| | |
| Create Device Software Object
| |
| Attach Event Functions created above to Device
| |
| Open Device
| |
| | |
| // ****** Change the look and structure of this loop for your GUI ******
| |
| Loop waiting for events and user input:
| |
| If device attached:
| |
| Get and Print various device statuses on request via user input
| |
| Exit upon specific user input
| |
| | |
| Close Device
| |
| Delete Device
| |
| | |
| </source>
| |
| </font>
| |
| </div>
| |
| | |
| | |
| === Logic Code ===
| |
| | |
| Logic code is often more compact and straightforward compared to event driven code. But, logic code cannot easily handle the same level of complexity that event-driven code can. Logic code is more useful 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. When the code example in the [[#Event Driven Code|Event Driven Code]] section above is translated into logic code, we lose the ability to handle multiple attach and detach events (plugging and unplugging of the Phidget). We also lose the ability to have all of the sensor data or event changes come to us, instead we have to ask for them. However, the code structure is much simpler:
| |
| | |
| <div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source lang=text>
| |
| | |
| Create Device Software Object
| |
| Open Device
| |
| Wait for Device Attachment
| |
| Initialize any hardware (antennas, etc)
| |
| | |
| Loop waiting for requests from user input:
| |
| Get and Print various device statuses on request by input
| |
| Exit upon specific user input
| |
| | |
| Close Device
| |
| Delete Device
| |
| | |
| </source>
| |
| </font>
| |
| </div>
| |
| | |
| <br>
| |
| If you find that in logic code you have a highly complex <code>if</code> loop driving your program, you should consider switching to event driven code. This type of awkward if-loop might look like this:
| |
| | |
| <div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
| |
| <font size="3">
| |
| <source lang=c>
| |
| | |
| 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
| |
| | |
| </source>
| |
| </font>
| |
| </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.
| |
