Alert.png

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

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

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

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


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

Alert.png

Language - iOS: Difference between revisions

From Phidgets Legacy Support
No edit summary
No edit summary
 
(61 intermediate revisions by 5 users not shown)
Line 1: Line 1:
[[Category:Language]]
[[Category:Language]]
[[File:icon-iOS.png|64x64px]] application are built using the Cocoa Touch framework and the Objective C programming language, both developed by [http://www.apple.com Apple].  
{{OSLang|[[File:icon-iOS.png|64x64px|alt=|link=]]|applications are built using the Cocoa Touch framework and the Objective C programming language, both developed by [http://www.apple.com Apple].}}
 
 
 
__TOC__
__TOC__


==Introduction==
==Introduction==


{{LanguageSupport|iOS|nearly the complete Phidget API, including events|the Phidget InterfaceKit, Hello World examples and a Skeleton starter project.|Xcode on OS X.|}}
{{LanguageSupport|iOS|nearly the complete Phidget API, including events. As iOS devices do not have USB ports, Phidgets can only be remotely controlled over a network, by using the [[Phidget WebService]]|the Phidget InterfaceKit, Hello World examples and a Skeleton starter project.|Xcode on OS X|}}


==Quick Downloads==
==Quick Downloads==
{{QuickDownloads|iOS|
{{QuickDownloads|iOS|
* [http://www.phidgets.com/documentation/Phidget21_C_Doc.zip C API]|
* [{{SERVER}}/documentation/Phidget21_C_Doc.zip C API]|
{{ExampleQuickDownloads|http://www.phidgets.com/downloads/libraries/Phidget-iPhone_2.1.8.20120216.zip|(same file as iOS libraries)}}|
{{ExampleQuickDownloads|{{SERVER}}/downloads/phidget21/libraries/ios/Phidget-iPhone.zip|(same file as iOS libraries)}}|
{{ExtraLibraryQuickDownloads|http://www.phidgets.com/downloads/libraries/Phidget-iPhone_2.1.8.20120216.zip|iOS|(same file as iOS examples)}}
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/phidget21/libraries/ios/Phidget-iPhone.zip|iOS|(same file as iOS examples)}}
{{MacQuickDownloads}}
{{MacQuickDownloads}}
}}
}}


==Getting Started with Cocoa Touch and Objective C==
==Getting Started with Cocoa Touch==


If you are new to writing code for Phidgets, we recommend starting by running, then modifying existing examples. This will allow you to:
If you are new to writing code for Phidgets, we recommend starting by running, then modifying existing examples. This will allow you to:
{{ExampleCodeReasons}}
* Make sure your libraries are properly linked
* Go from source code to a test application as quickly as possible
 
As iOS development is primarily done on Xcode, we provide instructions for Xcode, specifically version 4.0.


As iOS development is primarily done on xCode, we provide instructions for xCode, specifically version 4.0.
====Use Our Examples====


For basic differences on installing and setting up Eclipse on your development system, you can try the [[OS - iOS|iOS 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.
Start by ensuring that the WebService is running on the computer that the Phidget is physically plugged in and connected to. This computer needs to have an USB port and can be an OS X system or any other [[Software Overview#Operating System Support|operating systems]] we support. For directions on how to set up and run the WebService, refer to the page [[Software Overview#Operating System Support|for that operating system]]


iOS devices can control a Phidget remotely over a network, by using the [[Phidget Webservice]]
Then on the the OS X system that will be used for developing iOS applications, download and unpack the [{{SERVER}}/downloads/phidget21/libraries/ios/Phidget-iPhone.zip Phidget Examples for iOS]. The easiest way to confirm that your environment is set up properly will be to compile and run the HelloWorld iOS example.
Start by opening the HelloWorld.xcodeproj in Xcode.


====Use Our Examples====
Next, select your target destination that you want the application be ran on: an iOS device or simulator. For the purpose of this section, we will be using the simulator.


Download and unpack the [http://www.phidgets.com/downloads/examples/android-examples_2.1.8.20120216.tar.gz Phidget Examples for iOS].  There are two Hello World examples: {{Code|HelloWorldRemote}} (the one you want), and {{Code|HelloWorld}} (for tablets with a USB port).
[[Image:IOS Xcode Destination.png||alt=|link=]]


Import the {{Code|HelloWorldRemote}} example into Eclipse:
To run the example, click on the {{Code|Run}} button.  
* 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:
[[Image:IOS Xcode Run.png||alt=|link=]]
<div class="source">
<syntaxhighlight lang=java>
device.open("192.168.3.133", 5001);
</syntaxhighlight>
</div>


Also, note that the HelloWorldRemote example was written for iOS version 3.0 or greater.  If needed, you can change this in:
This program will detect for Phidgets that are attached/detached on the host computer. Go ahead, and attach or detach your devices! Here is an example output:
(Right Click on Project) &rarr; Properties &rarr; Resource (on left) &rarr; Android


To run the example: Right-click on project in Package Explorer (To open the Package Explorer, use Window &rarr; Show View &rarr; Package Explorer)
[[Image:IOS Webservice Example HelloWorld Output.png||alt=|link=]]


Select Run As... &rarr; Android Application
After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your specific device. {{FindYourDevice}} Currently, the only device we provide example code for is the PhidgetInterfaceKit.


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.
Once you have the iOS examples running, we have a [[#Follow the Examples|teaching]] section below to help you follow them.


After the {{Code|HelloWorldRemote}} application starts running on your Android device:
====Write Your Own Code====
# 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:
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 iOS library. To begin:  


[[Image:android_helloworld_remotehello.png|700px|alt=|link=]]
1. Generate a new iOS Windows-based application project with a descriptive name such as PhidgetTest.  


And when you unplug that Phidget from the remote computer, you should see something like this on your Android device:
[[File:IOS NewProject 1.png|link=|alt=New Project]]


[[Image:android_helloworld_remotegoodbye.png|700px|alt=|link=]]
[[File:IOS NewProject 2.png|link=|alt=New Project]]


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.
A {{Code|.xcodeproj}} project file will be created.  


To envision the system in the background, you can refer to the Webservice section on the [[OS - Android]] page.
2. Set up the Provisioning Profiles and Code Signing settings, if necessary.


====Write Your Own Code====
3. Download the [{{SERVER}}/downloads/phidget21/libraries/ios/Phidget-iPhone.zip Phidget iOS library] and extract it.


To write your own code from scratch, start with an Android project in Eclipse (File &rarr; New &rarr; Android Project).  Then....
4. Inside, you will find the {{Code|iphoneos}} and the {{Code|iphonesimulator}} folders. Move the two folders as well as the {{Code|phidget21.h}} into the same directory as the newly created {{Code|.xcodeproj}} file.


=====Step One: Link the Phidget Libraries to your Project=====
5. In Xcode, open up the Project Settings &rarr; Build Settings.


When you download and unzip the [http://www.phidgets.com/downloads/examples/android-examples_2.1.8.20120216.tar.gz Phidget Examples for Android], each project folder will (in addition to the project files themselves) contain three things:
6. In Linking &rarr; Other Linker Flags, follow these steps for both the Debug, and Release sections:  
# 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.
Select {{Code|Any iOS Simulator SDK}} and enter: {{Code|$(SRCROOT)/iphonesimulator/libPhidget21.a}}.


To install libraries to run a Phidget '''remotely''' over a network using the Webservice:
Select {{Code|Any iOS SDK}} and enter: {{Code|$(SRCROOT)/iphoneos/libPhidget21.a}}.
# 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 &rarr; Properties &rarr; Java Build Path &rarr; Libraries (tab) &rarr; Add JAR


=====Step Two: Give your Program Permission to use the Internet=====
[[File:IOS Add Library.png|link=|alt=Add Library]]


Add the following to your <code>AndroidManifest.xml</code> file:
7. In Search Paths &rarr; Header Search Paths, enter: {{Code|$(SRCROOT)}}.


<div class="source"><syntaxhighlight lang=xml>
[[File:IOS Add Header.png|link=|alt=Add Header]]
    <uses-permission android:name="android.permission.INTERNET"></uses-permission>
</syntaxhighlight></div>


=====Step Three: Include the Phidget Libraries in your Source=====
8. In the header file, add a reference to {{Code|phidget21.h}}:
<div class="source">
<syntaxhighlight lang=objc>
  #import "phidget21.h"
</syntaxhighlight>
</div>


Then, in your code, include an {{Code|import}} reference to the library. In Xcode:
The project now has access to Phidgets and we are ready to begin coding.


<div class="source"><syntaxhighlight lang=java>
Please note that the Phidget iPhone library also contains a sample skeleton xCode project for iOS. This project already contains project settings similar to those discussed above and it lets you quickly start on Phidgets development.
  // 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!
The same [[#Follow the Examples|teaching]] section which describes the examples also has further resources for programming your Phidget.


==Follow the Examples==
==Follow the Examples==
Line 115: Line 95:
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.
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 MATLAB makes extensive use of the mainstream Java Phidgets library, so the Java API reference will be helpful:
Your main reference for writing iOS applications will be our C API information, with syntax for all of our functions:


{{UsingAPhidgetInCodeGeneral|although you can only use the event code in Android|[http://www.phidgets.com/documentation/JavaDoc.zip Java API]}}
{{UsingAPhidgetInCodeGeneral|both of which are available in iOS|[{{SERVER}}/documentation/Phidget21_C_Doc.zip C API]}}


===API Support===
===API Support===
Line 124: Line 104:


The following open calls are unsupported:
The following open calls are unsupported:
<div class="source"><syntaxhighlight lang=c>
<div class="source"><syntaxhighlight lang=objc>
int CPhidget_open(CPhidgetHandle phid, int serialNumber)
  int CPhidget_open(CPhidgetHandle phid, int serialNumber)
int CPhidget_openLabel(CPhidgetHandle phid, const char * label)
  int CPhidget_openLabel(CPhidgetHandle phid, const char * label)
</syntaxhighlight></div>
</syntaxhighlight></div>
===Code Snippets===
===Code Snippets===
Line 132: Line 112:
Specific calls in iOS will differ in syntax from those on the [[General Phidget Programming]] page, but the concepts stay the same.   
Specific calls in iOS 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.
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 Cocoa Touch syntax, as described on this page.  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 [[Product - 1018 - PhidgetInterfaceKit 8/8/8 | Phidget Interface Kit]] as our device, the general calls would look like this:
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====
====Step One: Initialize and Open====


For opening a remote Phidget over the network using the Webservice:
For opening a remote Phidget over the network using the WebService:


<div class="source"><syntaxhighlight lang=java>
<div class="source"><syntaxhighlight lang=objc>
   InterfaceKitPhidget device;
   CPhidgetInterfaceKitHandle device;
  device = new InterfaceKitPhidget();
 
 
   // Open first detected Interface Kit, remotely with IP address and port
   // Open first detected Interface Kit, remotely with IP address and port
  device.open("192.168.3.33", 5001);
  CPhidget_openRemoteIP((CPhidgetHandle)device, -1, "192.168.3.33", 5001, NULL);
</syntaxhighlight></div>
</syntaxhighlight></div>


For opening a Phidget directly attached to the tablet's USB port:
Since the WebService is used to connect to the Phidget, the one connection per device limit does not apply.


<div class="source"><syntaxhighlight lang=java>
The 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.
 InterfaceKitPhidget device;
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 attach events and detach events.
com.phidgets.usb.Manager.Initialize(this);
device = new InterfaceKitPhidget();


// Open locally, with Phidget in tablet USB port
====Step Two: Wait for Attachment (plugging in) of the Phidget====
 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.  
To use the Phidget, it must be plugged in (attached).  We can handle this simply by calling {{Code|CPhidget_waitForAttachment}}. This function works for any Phidget. {{Code|CPhidget_waitForAttachment}} will block indefinitely until a connection is made to the Phidget, or an optional timeout is exceeded:
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.
<div class="source">
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....
<syntaxhighlight lang=objc>
  int serialNum;
  CPhidget_waitForAttachment(10000);
  CPhidget_getSerialNumber((CPhidgetHandle)device, &serialNum);
  NSLog("%d attached!", serialNum);
</syntaxhighlight>
</div>


====Step Two: Wait for Attachment (plugging in) of the Phidget====
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.


To use the Phidget, it must be plugged in and a software event caught (i.e. attached).  
First, you hook an event handler with the following code:
<div class="source">
<syntaxhighlight lang=objc>
  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    ..
    CPhidgetManager_set_OnAttach_Handler(manager, gotAttach, self);
    ...
  }
</syntaxhighlight>
</div>


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.
Next, the callback method needs to be set up:
<div class="source">
<syntaxhighlight lang=objc>
  // ========== Event Handling Setup Functions ==========
  int gotAttach(CPhidgetHandle phid, void *context) {
    NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
   
    //invokes the DeviceAttach event method on the main thread and block the main thread until after the DeviceAttach method finishes
    //A bad access exception may occur if you set waitUntilDone to No
    [(id)context performSelectorOnMainThread:@selector(DeviceAttach:)
        withObject:[NSValue valueWithPointer:phid]
                                            waitUntilDone:YES];
    [pool release];
    return 0;
  }
</syntaxhighlight>
</div>


First, let's write our handler:
Above, the {{Code|DeviceAttach}} method is invoked on the main thread. The {{Code|NSAutoreleasePool}} object is created to clean up released objects on the event thread, and is released at the end of the method. The {{Code|DeviceAttach}} method is defined as follows:


<div class="source"><syntaxhighlight lang=java>
<div class="source">
   class AttachEventHandler implements Runnable {  
<syntaxhighlight lang=objc>
     Phidget device;  
   // ========== Event Handling Functions ==========
     TextView eventOutput;
  - (void)DeviceAttach:(NSValue *)phid
  {
     int phidgetSerial;
    const char * phidgetName;
   
    CPhidget_getSerialNumber((CPhidgetHandle)[phid pointerValue], &phidgetSerial);
    CPhidget_getDeviceName((CPhidgetHandle)[phid pointerValue], &phidgetName);
      
    outputField.text = [NSString stringWithFormat:@"%@Hello Device %@, Serial Number: %d\n\n", outputField.text, [NSString stringWithCString:phidgetName encoding:NSASCIIStringEncoding], phidgetSerial];
  }
</syntaxhighlight>
</div>


    public AttachEventHandler(Phidget device, TextView eventOutput) {
With this function, the code inside {{Code|DeviceAttach}} will get executed every time the PhidgetInterfaceKit is attaches to the computer. Some events such as Attach and Detach belong to the base Phidget object and thus are common to all types of Phidgets. Please refer to the API manual and the iOS examples for a list of events and their usage.
      this.device = device;
      this.eventOutput = eventOutput; }


    public void run() {
====Step Three: Do Things with the Phidget====
      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:
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.
# 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:
For our [http://www.phidgets.com/products.php?product_id=1018 PhidgetInterfaceKit 8/8/8], the polling method of getting the current sensor state and setting an output state looks something like this:


<div class="source"><syntaxhighlight lang=java>
<div class="source">
device.addAttachListener(new AttachListener() {
<syntaxhighlight lang=objc>
  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
  # Get a data point from Analog Port 0
    synchronized(handler) {
  int sensorValue;
  CPhidgetInterfaceKit_getSensorValue(device, 0, &sensorValue);
  [sensorValueTxt setintValue: sensorValue];


      runOnUiThread(handler);
  # Set digital output port 0 to be on
      try { handler.wait(); } catch (InterruptedException e) { e.printStackTrace(); }
  CPhidgetInterfaceKit_setOutputState(device, 0, 1);  
    }
  }
});
</syntaxhighlight></div>


====Step Three: Do Things with the Phidget====
</syntaxhighlight>
 
</div>
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====
====Step Four: Close and Delete====


At the end of your program, don’t forget to call close to free any locks on the Phidget.
At the end of your program, don’t forget to call {{Code|CPhidget_close()}} and {{Code|CPhidget_delete()}} to free any locks on the Phidget that the {{Code|CPhidget_open()}} call put in place!


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=objc>
  CPhidget_close((CPhidgetHandle)ifkit);
  CPhidget_delete((CPhidgetHandle)ifkit);
</syntaxhighlight>
</div>


<div class="source"><syntaxhighlight lang=java>
{{MoreHowTos}}
  @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 [http://www.phidgets.com/documentation/JavaDoc.zip Java API]. You can also find more description on any device-specific function either in the [[Device List|Device API]] page for calls available only on your specific Phidget.
The ''complete'' set of functions you have available for all Phidgets can be found in the [{{SERVER}}/documentation/Phidget21_C_Doc.zip C API]. You can also find more description on any device-specific function in the Device API for your specific Phidget, which can be found in its [[:Category:UserGuide|user guide]].


==Common Problems and Solutions/Workarounds==
==Common Problems and Solutions/Workarounds==
None at this time.

Latest revision as of 19:19, 6 June 2017

applications are built using the Cocoa Touch framework and the Objective C programming language, both developed by Apple.

Introduction

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

iOS is capable of using nearly the complete Phidget API, including events. As iOS devices do not have USB ports, Phidgets can only be remotely controlled over a network, by using the Phidget WebService. We also provide example code in iOS for the Phidget InterfaceKit, Hello World examples and a Skeleton starter project.

iOS can be developed with Xcode on OS X.

You can compare iOS with our other supported languages.

Quick Downloads

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

Documentation

Example Code

Libraries and Drivers


Getting Started with Cocoa Touch

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

  • Make sure your libraries are properly linked
  • Go from source code to a test application as quickly as possible

As iOS development is primarily done on Xcode, we provide instructions for Xcode, specifically version 4.0.

Use Our Examples

Start by ensuring that the WebService is running on the computer that the Phidget is physically plugged in and connected to. This computer needs to have an USB port and can be an OS X system or any other operating systems we support. For directions on how to set up and run the WebService, refer to the page for that operating system

Then on the the OS X system that will be used for developing iOS applications, download and unpack the Phidget Examples for iOS. The easiest way to confirm that your environment is set up properly will be to compile and run the HelloWorld iOS example. Start by opening the HelloWorld.xcodeproj in Xcode.

Next, select your target destination that you want the application be ran on: an iOS device or simulator. For the purpose of this section, we will be using the simulator.

To run the example, click on the Run button.

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

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

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

Write Your Own Code

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget iOS library. To begin:

1. Generate a new iOS Windows-based application project with a descriptive name such as PhidgetTest.

New Project

New Project

A .xcodeproj project file will be created.

2. Set up the Provisioning Profiles and Code Signing settings, if necessary.

3. Download the Phidget iOS library and extract it.

4. Inside, you will find the iphoneos and the iphonesimulator folders. Move the two folders as well as the phidget21.h into the same directory as the newly created .xcodeproj file.

5. In Xcode, open up the Project Settings → Build Settings.

6. In Linking → Other Linker Flags, follow these steps for both the Debug, and Release sections:

Select Any iOS Simulator SDK and enter: $(SRCROOT)/iphonesimulator/libPhidget21.a.

Select Any iOS SDK and enter: $(SRCROOT)/iphoneos/libPhidget21.a.

Add Library

7. In Search Paths → Header Search Paths, enter: $(SRCROOT).

Add Header

8. In the header file, add a reference to phidget21.h:

  #import "phidget21.h"

The project now has access to Phidgets and we are ready to begin coding.

Please note that the Phidget iPhone library also contains a sample skeleton xCode project for iOS. This project already contains project settings similar to those discussed above and it lets you quickly start on Phidgets development.

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

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.

Your main reference for writing iOS applications will be our C API information, with syntax for all of our functions:

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

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

API Support

Most of the C API is supported in iOS, with the exception of the local open calls. This is because there are no USB ports on iOS devices, so only the remote open calls can be used.

The following open calls are unsupported:

  int CPhidget_open(CPhidgetHandle phid, int serialNumber)
  int CPhidget_openLabel(CPhidgetHandle phid, const char * label)

Code Snippets

Specific calls in iOS 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 Cocoa Touch syntax, as described on this page. However, many additional concepts are covered on the General Phidget Programming page on a high level, such as using multiple Phidgets, handling errors, and different styles of programming.

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

Step One: Initialize and Open

For opening a remote Phidget over the network using the WebService:

  CPhidgetInterfaceKitHandle device;
 
  // Open first detected Interface Kit, remotely with IP address and port
  CPhidget_openRemoteIP((CPhidgetHandle)device, -1, "192.168.3.33", 5001, NULL);

Since the WebService is used to connect to the Phidget, the one connection per device limit does not apply.

The 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 attach events and detach events.

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 CPhidget_waitForAttachment. This function works for any Phidget. CPhidget_waitForAttachment will block indefinitely until a connection is made to the Phidget, or an optional timeout is exceeded:

  int serialNum;
  CPhidget_waitForAttachment(10000);
  CPhidget_getSerialNumber((CPhidgetHandle)device, &serialNum);
  NSLog("%d attached!", serialNum);

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.

First, you hook an event handler with the following code:

  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    ...   
    CPhidgetManager_set_OnAttach_Handler(manager, gotAttach, self);
    ...
  }

Next, the callback method needs to be set up:

  // ========== Event Handling Setup Functions ==========
  int gotAttach(CPhidgetHandle phid, void *context) {
    NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
    
    //invokes the DeviceAttach event method on the main thread and block the main thread until after the DeviceAttach method finishes
    //A bad access exception may occur if you set waitUntilDone to No
    [(id)context performSelectorOnMainThread:@selector(DeviceAttach:)
     					     withObject:[NSValue valueWithPointer:phid]
                                             waitUntilDone:YES];
    [pool release];
    return 0;
  }

Above, the DeviceAttach method is invoked on the main thread. The NSAutoreleasePool object is created to clean up released objects on the event thread, and is released at the end of the method. The DeviceAttach method is defined as follows:

  // ========== Event Handling Functions ==========
  - (void)DeviceAttach:(NSValue *)phid
  {
    int phidgetSerial;
    const char * phidgetName;
    
    CPhidget_getSerialNumber((CPhidgetHandle)[phid pointerValue], &phidgetSerial);
    CPhidget_getDeviceName((CPhidgetHandle)[phid pointerValue], &phidgetName);
    
    outputField.text = [NSString stringWithFormat:@"%@Hello Device %@, Serial Number: %d\n\n", outputField.text, [NSString stringWithCString:phidgetName encoding:NSASCIIStringEncoding], phidgetSerial];
  }

With this function, the code inside DeviceAttach will get executed every time the PhidgetInterfaceKit is attaches to the computer. Some events such as Attach and Detach belong to the base Phidget object and thus are common to all types of Phidgets. Please refer to the API manual and the iOS examples for a list of events and their usage.

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 PhidgetInterfaceKit 8/8/8, the polling method of getting the current sensor state and setting an output state looks something like this:

  # Get a data point from Analog Port 0
  int sensorValue;
  CPhidgetInterfaceKit_getSensorValue(device, 0, &sensorValue);
  [sensorValueTxt setintValue: sensorValue];

  # Set digital output port 0 to be on
  CPhidgetInterfaceKit_setOutputState(device, 0, 1);

Step Four: Close and Delete

At the end of your program, don’t forget to call CPhidget_close() and CPhidget_delete() to free any locks on the Phidget that the CPhidget_open() call put in place!

  CPhidget_close((CPhidgetHandle)ifkit);
  CPhidget_delete((CPhidgetHandle)ifkit);

More How-To's

The General Phidget Programming page gives more information about:

The complete set of functions you have available for all Phidgets can be found in the C API. You can also find more description on any device-specific function in the Device API for your specific Phidget, which can be found in its user guide.

Common Problems and Solutions/Workarounds

None at this time.