Phidgets Support - User contributions [en]

Phidget Manager

2017-07-13T22:12:27Z

Chad: /* Opening a Manager Channel */

Phidget Manager

2017-07-13T17:18:41Z

Chad: /* General Overview */

Phidget Manager

2017-07-13T17:15:29Z

Chad: /* Using the Phidget Manager */

Phidget Manager

2017-07-13T17:13:32Z

Chad: /* Opening a Manager Channel= */

Phidget Manager

2017-07-13T17:04:43Z

Chad:

Phidget Manager

2017-07-13T17:04:00Z

Chad: /* Using the Phidget Manager */

Phidget Manager

2017-07-13T16:42:03Z

Chad: /* Purpose */

[[Category:Overview]]
==General Overview==

The Phidget Manager is an interface into the device channels available to the Phidget library. The API is strictly asynchronous, a continuously monitors channels as they attach and detach. Each Phidget exports one or more device channels, and when a Phidget is plugged into a system (or become available over the network), an attach event is fired for each channel available on that Phidget.

It is important to understand the concepts of '''attach''' and '''detach''' as the they relate to the manager. A manager attach does not imply that a user channel has attached to a device channel, but that the device channel have become available. The device channel is now ready to be attached to a user channel. When a user channel closes and detaches from a device channel a manager event will not be fired. A manager '''detach''' event is fired when the Phidget device is removed from the system.

==Purpose==

The primary function of a Phidget Manager is to fire an attach event for each new device channel when a Phidget becomes available to a system, and to fire a detach event for each device channel that is no longer available when the Phidget is removed from the system. For example, when a 1044_0 - PhidgetSpatial is connected, a Phidget Manager would fire three attach events, one for each device channel, as illustrated below:

[[Image:manager22.jpg|link=|1000px|alt=]]

==Using the Phidget Manager==

As with any other Phidget software object, the Phidget Manager must be [[General Phidget Programming#Opening the Phidget|opened]], then [[General Phidget Programming#Attaching the Phidget|attached]] within your code. Here's an example of how the manager is used in C:

<div class="source">
<syntaxhighlight lang=c>
int main() {

// Define the manager handle and create
PhidgetManagerHandle device = 0;
PhidgetManager_create(&device);

// Set up event handlers
PhidgetManager_setOnAttachHandler(device, AttachHandler, NULL);
PhidgetManager_setOnDetachHandler(device, DetachHandler, NULL);

// Open the Phidget Manager
PhidgetManager_open(device);

// Wait for attach/detach events
printf("Press Enter to end anytime...\n");
getchar();

// Close and clean up manager object
PhidgetManager_close(device);
PhidgetManager_delete(&device);
return 0;
}

void CCONV AttachHandler(PhidgetManagerHandle manager, void *userptr, PhidgetHandle device) {

const char *chanClass;
// Define handles and spatial variables
PhidgetAccelerometerHandle accHandle;
PhidgetGyroscopeHandle gyrHandle;
PhidgetMagnetometerHandle magHandle;
double acceleration[3];
double angularRate[3];
double fieldStrength[3];

// Get the class of this generic Phidget object that has just attached
Phidget_getChannelClassName(device, &chanClass);

// If the channel is an accelerometer, handle it accordingly:
if(strcmp(chanClass,"PhidgetAccelerometer") == 0) {

// Cast the generic Phidget object into a Phidget Accelerometer object
accHandle = (PhidgetAccelerometerHandle) device;
// Now that the channel is cast, we can call Accelerometer-specific methods like getAcceleration:
PhidgetAccelerometer_getAcceleration(accHandle, &acceleration);
// Print out the acceleration values and close the object
printf("Accelerometer attached! X:%f Y:%f Z:%f \n", acceleration[0], acceleration[1], acceleration[2]);
Phidget_close(accHandle);
}

// If the channel is a gyroscope, handle it accordingly:
if(strcmp(chanClass,"PhidgetGyroscope") == 0) {

// Cast the generic Phidget object into a Phidget Gyroscope object
gyrHandle = (PhidgetGyroscopeHandle) device;
// Now that the channel is cast, we can call Gyroscope-specific methods like getAngularRate:
PhidgetGyroscope_getAngularRate(gyrHandle, &angularRate);
// Print out the angular rate values and close the object
printf("Gyroscope attached! X:%f Y:%f Z:%f \n", angularRate[0], angularRate[1], angularRate[2]);
Phidget_close(gyrHandle);
}

// If the channel is a magnetometer, handle it accordingly:
if(strcmp(chanClass,"PhidgetMagnetometer") == 0) {

// Cast the generic Phidget object into a Phidget Magnetometer object
magHandle = (PhidgetMagnetometerHandle) device;
// Now that the channel is cast, we can call Magnetometer-specific methods like getFieldStrength:
PhidgetMagnetometer_getFieldStrength(magHandle, &fieldStrength);
// Print out the field strength values and close the object
printf("Magnetometer attached! X:%f Y:%f Z:%f \n", fieldStrength[0], fieldStrength[1], fieldStrength[2]);
Phidget_close(magHandle);
}
}

void CCONV DetachHandler(PhidgetManagerHandle manager, void *userptr, PhidgetHandle device) {

const char *chanClass;

// Get an print the class of this generic Phidget object that has just detached
Phidget_getChannelClassName(device, &chanClass);
printf("%s detached!\n",chanClass);
}

</syntaxhighlight>
</div>

For more sample code that uses the Phidget Manager, have a look at our "HelloWorld" programming examples, which are available for most of [[Software Overview#Language Support|the languages we support]].

Phidget Manager

2017-07-13T16:38:02Z

Chad: /* Object Structure */

[[Category:Overview]]
==General Overview==

The Phidget Manager is an interface into the device channels available to the Phidget library. The API is strictly asynchronous, a continuously monitors channels as they attach and detach. Each Phidget exports one or more device channels, and when a Phidget is plugged into a system (or become available over the network), an attach event is fired for each channel available on that Phidget.

It is important to understand the concepts of '''attach''' and '''detach''' as the they relate to the manager. A manager attach does not imply that a user channel has attached to a device channel, but that the device channel have become available. The device channel is now ready to be attached to a user channel. When a user channel closes and detaches from a device channel a manager event will not be fired. A manager '''detach''' event is fired when the Phidget device is removed from the system.

==Purpose==

The main function of the Phidget Manager is to launch events when a Phidget attaches or detaches, so you can execute code to prepare those Phidgets for use. For Phidgets that have multiple objects and/or channels (which happens to be most of them), a separate attach and detach event will trigger for each one. For example, when the 1044_0 - PhidgetSpatial is connected, the Phidget Manager would launch three attach events, one for each distinct object, as illustrated below:

[[Image:manager22.jpg|link=|1000px|alt=]]

Once an attach event triggers, the attach event handler will be called and your code will run. In order to interact with the object, you need to cast it as the correct type and open it. You can determine the correct type by using <code>getChannelClassName()</code> (or the <code>channelClassName </code> property if you're using and object-oriented language). Once cast, you can open it and begin to use methods and properties that belong to that specific object. In the next section we'll look at an example of a program implementing the process described by this diagram.

==Using the Phidget Manager==

As with any other Phidget software object, the Phidget Manager must be [[General Phidget Programming#Opening the Phidget|opened]], then [[General Phidget Programming#Attaching the Phidget|attached]] within your code. Here's an example of how the manager is used in C:

<div class="source">
<syntaxhighlight lang=c>
int main() {

// Define the manager handle and create
PhidgetManagerHandle device = 0;
PhidgetManager_create(&device);

// Set up event handlers
PhidgetManager_setOnAttachHandler(device, AttachHandler, NULL);
PhidgetManager_setOnDetachHandler(device, DetachHandler, NULL);

// Open the Phidget Manager
PhidgetManager_open(device);

// Wait for attach/detach events
printf("Press Enter to end anytime...\n");
getchar();

// Close and clean up manager object
PhidgetManager_close(device);
PhidgetManager_delete(&device);
return 0;
}

void CCONV AttachHandler(PhidgetManagerHandle manager, void *userptr, PhidgetHandle device) {

const char *chanClass;
// Define handles and spatial variables
PhidgetAccelerometerHandle accHandle;
PhidgetGyroscopeHandle gyrHandle;
PhidgetMagnetometerHandle magHandle;
double acceleration[3];
double angularRate[3];
double fieldStrength[3];

// Get the class of this generic Phidget object that has just attached
Phidget_getChannelClassName(device, &chanClass);

// If the channel is an accelerometer, handle it accordingly:
if(strcmp(chanClass,"PhidgetAccelerometer") == 0) {

// Cast the generic Phidget object into a Phidget Accelerometer object
accHandle = (PhidgetAccelerometerHandle) device;
// Now that the channel is cast, we can call Accelerometer-specific methods like getAcceleration:
PhidgetAccelerometer_getAcceleration(accHandle, &acceleration);
// Print out the acceleration values and close the object
printf("Accelerometer attached! X:%f Y:%f Z:%f \n", acceleration[0], acceleration[1], acceleration[2]);
Phidget_close(accHandle);
}

// If the channel is a gyroscope, handle it accordingly:
if(strcmp(chanClass,"PhidgetGyroscope") == 0) {

// Cast the generic Phidget object into a Phidget Gyroscope object
gyrHandle = (PhidgetGyroscopeHandle) device;
// Now that the channel is cast, we can call Gyroscope-specific methods like getAngularRate:
PhidgetGyroscope_getAngularRate(gyrHandle, &angularRate);
// Print out the angular rate values and close the object
printf("Gyroscope attached! X:%f Y:%f Z:%f \n", angularRate[0], angularRate[1], angularRate[2]);
Phidget_close(gyrHandle);
}

// If the channel is a magnetometer, handle it accordingly:
if(strcmp(chanClass,"PhidgetMagnetometer") == 0) {

// Cast the generic Phidget object into a Phidget Magnetometer object
magHandle = (PhidgetMagnetometerHandle) device;
// Now that the channel is cast, we can call Magnetometer-specific methods like getFieldStrength:
PhidgetMagnetometer_getFieldStrength(magHandle, &fieldStrength);
// Print out the field strength values and close the object
printf("Magnetometer attached! X:%f Y:%f Z:%f \n", fieldStrength[0], fieldStrength[1], fieldStrength[2]);
Phidget_close(magHandle);
}
}

void CCONV DetachHandler(PhidgetManagerHandle manager, void *userptr, PhidgetHandle device) {

const char *chanClass;

// Get an print the class of this generic Phidget object that has just detached
Phidget_getChannelClassName(device, &chanClass);
printf("%s detached!\n",chanClass);
}

</syntaxhighlight>
</div>

For more sample code that uses the Phidget Manager, have a look at our "HelloWorld" programming examples, which are available for most of [[Software Overview#Language Support|the languages we support]].

Phidget Manager

2017-07-13T16:37:40Z

Chad: /* General Overview */

[[Category:Overview]]
==General Overview==

The Phidget Manager is an interface into the device channels available to the Phidget library. The API is strictly asynchronous, a continuously monitors channels as they attach and detach. Each Phidget exports one or more device channels, and when a Phidget is plugged into a system (or become available over the network), an attach event is fired for each channel available on that Phidget.

It is important to understand the concepts of '''attach''' and '''detach''' as the they relate to the manager. A manager attach does not imply that a user channel has attached to a device channel, but that the device channel have become available. The device channel is now ready to be attached to a user channel. When a user channel closes and detaches from a device channel a manager event will not be fired. A manager '''detach''' event is fired when the Phidget device is removed from the system.

==Object Structure==

You are probably already familiar with Phidgets software objects, where a single set of functions for a class of hardware are contained in one object. For example, the VoltageInput object:

[[Image:voltageInput_object.jpg|300px|link=|alt=]]

The methods for the Phidget Manager are contained in the same way, but it does not belong to any particular Phidget device. It exists separately, so you can have an active Phidget Manager object even when there are no Phidgets attached.

[[Image:manager.jpg|300px|link=|alt=]]

You can find the complete API for the Phidget Manager in the {{Phidget22API}}. Select your language from the first drop-down box and select '''Manager API''' from the second box.

==Purpose==

The main function of the Phidget Manager is to launch events when a Phidget attaches or detaches, so you can execute code to prepare those Phidgets for use. For Phidgets that have multiple objects and/or channels (which happens to be most of them), a separate attach and detach event will trigger for each one. For example, when the 1044_0 - PhidgetSpatial is connected, the Phidget Manager would launch three attach events, one for each distinct object, as illustrated below:

[[Image:manager22.jpg|link=|1000px|alt=]]

Once an attach event triggers, the attach event handler will be called and your code will run. In order to interact with the object, you need to cast it as the correct type and open it. You can determine the correct type by using <code>getChannelClassName()</code> (or the <code>channelClassName </code> property if you're using and object-oriented language). Once cast, you can open it and begin to use methods and properties that belong to that specific object. In the next section we'll look at an example of a program implementing the process described by this diagram.

==Using the Phidget Manager==

As with any other Phidget software object, the Phidget Manager must be [[General Phidget Programming#Opening the Phidget|opened]], then [[General Phidget Programming#Attaching the Phidget|attached]] within your code. Here's an example of how the manager is used in C:

<div class="source">
<syntaxhighlight lang=c>
int main() {

// Define the manager handle and create
PhidgetManagerHandle device = 0;
PhidgetManager_create(&device);

// Set up event handlers
PhidgetManager_setOnAttachHandler(device, AttachHandler, NULL);
PhidgetManager_setOnDetachHandler(device, DetachHandler, NULL);

// Open the Phidget Manager
PhidgetManager_open(device);

// Wait for attach/detach events
printf("Press Enter to end anytime...\n");
getchar();

// Close and clean up manager object
PhidgetManager_close(device);
PhidgetManager_delete(&device);
return 0;
}

void CCONV AttachHandler(PhidgetManagerHandle manager, void *userptr, PhidgetHandle device) {

const char *chanClass;
// Define handles and spatial variables
PhidgetAccelerometerHandle accHandle;
PhidgetGyroscopeHandle gyrHandle;
PhidgetMagnetometerHandle magHandle;
double acceleration[3];
double angularRate[3];
double fieldStrength[3];

// Get the class of this generic Phidget object that has just attached
Phidget_getChannelClassName(device, &chanClass);

// If the channel is an accelerometer, handle it accordingly:
if(strcmp(chanClass,"PhidgetAccelerometer") == 0) {

// Cast the generic Phidget object into a Phidget Accelerometer object
accHandle = (PhidgetAccelerometerHandle) device;
// Now that the channel is cast, we can call Accelerometer-specific methods like getAcceleration:
PhidgetAccelerometer_getAcceleration(accHandle, &acceleration);
// Print out the acceleration values and close the object
printf("Accelerometer attached! X:%f Y:%f Z:%f \n", acceleration[0], acceleration[1], acceleration[2]);
Phidget_close(accHandle);
}

// If the channel is a gyroscope, handle it accordingly:
if(strcmp(chanClass,"PhidgetGyroscope") == 0) {

// Cast the generic Phidget object into a Phidget Gyroscope object
gyrHandle = (PhidgetGyroscopeHandle) device;
// Now that the channel is cast, we can call Gyroscope-specific methods like getAngularRate:
PhidgetGyroscope_getAngularRate(gyrHandle, &angularRate);
// Print out the angular rate values and close the object
printf("Gyroscope attached! X:%f Y:%f Z:%f \n", angularRate[0], angularRate[1], angularRate[2]);
Phidget_close(gyrHandle);
}

// If the channel is a magnetometer, handle it accordingly:
if(strcmp(chanClass,"PhidgetMagnetometer") == 0) {

// Cast the generic Phidget object into a Phidget Magnetometer object
magHandle = (PhidgetMagnetometerHandle) device;
// Now that the channel is cast, we can call Magnetometer-specific methods like getFieldStrength:
PhidgetMagnetometer_getFieldStrength(magHandle, &fieldStrength);
// Print out the field strength values and close the object
printf("Magnetometer attached! X:%f Y:%f Z:%f \n", fieldStrength[0], fieldStrength[1], fieldStrength[2]);
Phidget_close(magHandle);
}
}

void CCONV DetachHandler(PhidgetManagerHandle manager, void *userptr, PhidgetHandle device) {

const char *chanClass;

// Get an print the class of this generic Phidget object that has just detached
Phidget_getChannelClassName(device, &chanClass);
printf("%s detached!\n",chanClass);
}

</syntaxhighlight>
</div>

For more sample code that uses the Phidget Manager, have a look at our "HelloWorld" programming examples, which are available for most of [[Software Overview#Language Support|the languages we support]].

Phidget Dictionary

2017-07-13T15:16:16Z

Chad: /* General Overview */

[[Category:Overview]]
==General Overview==

Dictionary is Phidget channel class that exports a key-value pair database. Dictionaries are created and made accessible by the [[Phidget Network Server]]. A Dictionary channel is created and opened like any other Phidget channel. Matching is done using either the serial number or the label assigned to the dictionary.

The backing pseudo-device that exports the Dictionary device channel is maintained by the [[Phidget Network Server]], and is created when the server starts. When the server exits, the pseudo-device is deleted, and any changes made to a dictionary are lost.

The basic functionality of a Dictionary is to maintain configuration information in a central location. Multiple clients can attach to the same dictionary, and set handlers for ''add'', ''update'' and ''delete'' events, making the dictionary useful for monitoring and communicating state.

==Creating a Dictionary==
Dictionaries are managed by the [[Phidget Network Server]]. To create a dictionary, go to the [[Phidget Control Panel]] and click on the '''Network Server''' tab. There are options to create and manage dictionaries. The server must be enabled for clients to access dictionaries.

On Linux, refer to the README for information on how to enable the dictionary feature in the [[Phidget Network Server]], and for the syntax of dictionary configuration files.

==Using The Dictionary==

To access a dictionary, create a channel, set the serial number or the label, and open the channel.
To "listen" for changes to the Dictionary, {{Code|onAdd()}}, {{Code|onRemove()}}, and {{Code|onUpdate()}} event handlers can be set. Refer to the {{Phidget22API}} to see the methods supported by Dictionary.

Here's an example of how you might use the dictionary in a C program:

<div class="source">
<syntaxhighlight lang=c>

PhidgetDictionaryHandle dict;
char val[32];

PhidgetDictionary_create(&dict);

// Open connection to the dictionary using the serial number
Phidget_setDeviceSerialNumber(dict, 5000);
Phidget_open(dict);

PhidgetDictionary_add(dict, "my_key", "my_value"); // add a key that does not already exist
PhidgetDictionary_get(dict, "my_key", val, sizeof (val)); // get the value back
printf("Value: %s\n",newValue);

PhidgetDictionary_remove(dict, "my_key"); // remove the key

Phidget_close(dict);
PhidgetDictionary_delete(&dict);

</syntaxhighlight>
</div>

==Notes==

A common mistake is to assume an event will be delivered to the channel that triggered the event. This is not the case. For example, when a channel adds a key, that channel's add event handler is not called.

It is an error to {{Code|Add()}} a key that already exists in the dictionary. {{Code|Set()}} should be used to update existing keys, creating the key if it does not already exist.

There is no way to directly list all of the keys in a dictionary. The {{Code|Scan()}} method allows code to access the existing keys, but only returns the number of keys that can be held in a limited sized buffer. This interface was chosen as the dictionary could contain more keys than could reasonably returned in a single network request.

Phidget Dictionary

2017-07-12T20:48:11Z

Chad: /* Notes */

[[Category:Overview]]
==General Overview==

Dictionary is Phidget channel class that exports a key-value pair database. Dictionaries are create and made accessible by the [[Phidget Network Server]]. A Dictionary channel is created and opened like any other Phidget channel. Matching is done using either the serial number or the label assigned to the dictionary.

The backing pseudo-device that exports the Dictionary device channel is maintained by the [[Phidget Network Server]], and is created when the server starts. When the server exits, the pseudo-device is deleted, and any changes made to a dictionary are lost.

The basic functionality of a Dictionary is to maintain configuration information in a central location. Multiple clients can attach to the same dictionary, and set handlers for ''add'', ''update'' and ''delete'' events, making the dictionary useful for monitoring and communicating state.

==Creating a Dictionary==
Dictionaries are managed by the [[Phidget Network Server]]. To create a dictionary, go to the [[Phidget Control Panel]] and click on the '''Network Server''' tab. There are options to create and manage dictionaries. The server must be enabled for clients to access dictionaries.

On Linux, refer to the README for information on how to enable the dictionary feature in the [[Phidget Network Server]], and for the syntax of dictionary configuration files.

==Using The Dictionary==

To access a dictionary, create a channel, set the serial number or the label, and open the channel.
To "listen" for changes to the Dictionary, {{Code|onAdd()}}, {{Code|onRemove()}}, and {{Code|onUpdate()}} event handlers can be set. Refer to the {{Phidget22API}} to see the methods supported by Dictionary.

Here's an example of how you might use the dictionary in a C program:

<div class="source">
<syntaxhighlight lang=c>

PhidgetDictionaryHandle dict;
char val[32];

PhidgetDictionary_create(&dict);

// Open connection to the dictionary using the serial number
Phidget_setDeviceSerialNumber(dict, 5000);
Phidget_open(dict);

PhidgetDictionary_add(dict, "my_key", "my_value"); // add a key that does not already exist
PhidgetDictionary_get(dict, "my_key", val, sizeof (val)); // get the value back
printf("Value: %s\n",newValue);

PhidgetDictionary_remove(dict, "my_key"); // remove the key

Phidget_close(dict);
PhidgetDictionary_delete(&dict);

</syntaxhighlight>
</div>

==Notes==

A common mistake is to assume an event will be delivered to the channel that triggered the event. This is not the case. For example, when a channel adds a key, that channel's add event handler is not called.

It is an error to {{Code|Add()}} a key that already exists in the dictionary. {{Code|Set()}} should be used to update existing keys, creating the key if it does not already exist.

There is no way to directly list all of the keys in a dictionary. The {{Code|Scan()}} method allows code to access the existing keys, but only returns the number of keys that can be held in a limited sized buffer. This interface was chosen as the dictionary could contain more keys than could reasonably returned in a single network request.

Phidget Dictionary

2017-07-12T20:34:50Z

Chad: /* Using The Dictionary */

Phidget Dictionary

2017-07-12T20:34:05Z

Chad: /* Using The Dictionary */

Phidget Dictionary

2017-07-12T20:33:06Z

Chad: /* Creating a Dictionary */

Phidget Dictionary

2017-07-12T20:28:49Z

Chad: /* General Overview */

Phidget Dictionary

2017-07-12T20:26:30Z

Chad: /* Using The Dictionary */

Phidget Dictionary

2017-07-12T20:12:57Z

Chad: /* General Overview */

[[Category:Overview]]
==General Overview==

Dictionary is Phidget channel class that exports a key-value pair database. Dictionaries are create and made accessible by the [[Phidget Network Server]]. A Dictionary channel is created and opened like any other Phidget channel. Matching is done using either the serial number or the label assigned to the dictionary.

The backing pseudo-device that exports the Dictionary device channel is maintained by the [[Phidget Network Server]], and is created when the server starts. When the server exits, the pseudo-device is deleted, and any changes to dictionaries are lost.

The basic functionality of a Dictionary is to maintain configuration information in a central location. Multiple clients can attach to the same dictionary, and set handlers for ''add'', ''update'' and ''delete'' events, making the dictionary useful for monitoring and communicating state.

==Using The Dictionary==

To use the Dictionary, you would create a Dictionary object within your code, just like you would any other Phidget software object. To "listen" to changes of the value associated with a key, the Dictionary has a {{Code|onAdd()}}, {{Code|onRemove()}}, and {{Code|onUpdate()}} event functions (exact name dependant on programming language used). You can write code in these event handlers to react differently depending on which pair is being changed.

Go into the [[Phidget Control Panel]] and click on the '''Network Server'' tab and ensure the server is started.

Here's an example of how you might use the dictionary in a C program:

<div class="source">
<syntaxhighlight lang=c>

// Declare the dictionary handle
PhidgetDictionaryHandle dict;

// Create the new dictionary object using the handle
PhidgetDictionary_create(&dict);
PhidgetDictionary_addDictionary(5000,"myDictionary"); //set a serial number and label for the dictionary

// Open connection to the dictionary using the serial number
Phidget_setDeviceSerialNumber(dict, 5000);
Phidget_open(dict);

// Add a key-value pair to the dictionary
char *key1 = "001";
char *val1 = "first";
PhidgetDictionary_add(dict,key1,val1);

// Access and print a value from the dictionary based on a given key
char newValue[20];
PhidgetDictionary_get(dict, key1, &newValue,20); // '20' refers to the length of the buffer used to store the result
printf("Value: %s",newValue);

// Remove a pair from the dictionary based on a given key
PhidgetDictionary_remove(dict, key1);

// Close and clean up the dictionary object
Phidget_close(dict);
PhidgetDictionary_delete(&dict);

</syntaxhighlight>
</div>

Have a look at the {{Phidget22API}} documentation to learn how to use these methods in the language of your choice. Select your preferred language from the first drop-down box, and select '''Dictionary API''' from the second box.

When you create a dictionary in your code, the [[Phidget Control Panel]] will also be able to see it if you have remote Phidgets enabled in the options. Here's what it will look like:

[[File:dictionary-panel.jpg|link=|420px|left]]
[[File:dictionary-example.jpg|420px|link=]]
<br clear="all">

On the left, you can see that dictionaries appear just like attached and remote Phidget devices do. On the right, you can see the contents of the dictionary after double-clicking on it. You can add and remove tags from here as well.

Interestingly, you don't even need a Phidget to use the Dictionary! You can use our libraries and the [[Phidget Network Server]] without any Phidgets. Usually, there's not much to broadcast on the Network Server without a Phidget, but the Dictionary is the exception. With it, you'll have access to centralized key-value pair database management, pre-written, that can work across many computers on a local network.

Language - C

2017-07-12T19:24:47Z

Chad: /* Getting started with C/C++ */

[[Category:Language]]
__TOC__

== Quick Downloads ==

=== Documentation ===

*{{Phidget22API}} (select C from the drop-down menu)

=== Example Code ===

*{{SampleCode|C|C/C++ Examples}}

===Libraries===

{{AllQuickDownloads}}

== Getting started with C/C++ ==
Welcome to using Phidgets with C/C++! By using C/C++, you will have access to the complete Phidget22 API, including events. Example code is also provided for each Phidget channel class.

If developing for Windows, keep reading; otherwise, select an operating system:
*[[#macOS | macOS]]
*[[#Linux | Linux]]

== Windows ==
{{Windows_Languages}}

===Visual Studio===
====Use our examples====
One of the best ways to start programming with Phidgets is to use our example code as a guide. In order to run the examples, you will need to download and install [https://www.visualstudio.com/ Microsoft Visual Studio].

Now that you have Microsoft Visual Studio installed, select an example that will work with your Phidget:
*{{SampleCode|C|C/C++ Examples}}

Open the example project and start the example by pressing the ''Local Windows Debugger'' button:

[[Image: c_vs_run.png|link=|center]]

The application will open the Phidget, list basic information about the Phidget, and demonstrate the Phidget's functionality. Here is an example of an Accelerometer channel on a Spatial Phidget:

[[Image: c_vs_output.PNG|link=|center]]

You should now have the example up and running for your device. Play around with the device and experiment with some of the functionality. When you are ready, the next step is configuring your project and writing your own code!

====Configure your project====
When you are building a project from scratch, or adding Phidget functionality to an existing project, you'll need to configure your development environment to properly link the Phidget C/C++ library. To begin:

Create a new Win32 Console application:

[[Image:C_vs_newproject.PNG|link=|center]]

After creating a project with the default settings, access the project's properties:

[[Image:C_vs_properties.png|link=|center]]

Next, navigate to Configuration Properties -> C/C++ -> General and add the following line to the additional include directories:
*C:\Program Files\Phidgets\Phidget22

[[Image:C_vs_additionalinclude.png|link=|center]]

Navigate to Configuration Properties -> Linker -> Input and add the following line to the additional dependencies:
*C:\Program Files\Phidgets\Phidget22\phidget22.lib

[[Image:C_vs_additionadepend.png|link=|center]]

Finally, include the Phidget library in your code:

<syntaxhighlight lang='C'>
#include <phidget22.h>
</syntaxhighlight>

Success! The project now has access to Phidgets. Next, view the [[#Write Code | write your own code]] section located below.

===GCC===
====Cygwin/MinGW====
=====Use our examples=====
One of the best ways to start programming with Phidgets is to use our example code as a guide. In order to run the examples, you will need to download and install either [http://www.mingw.org/ MinGW] or [https://www.cygwin.com/ Cygwin].

Now that you have either MinGW or Cygwin installed, select an example that will work with your Phidget:
*{{SampleCode|C|C/C++ Examples}}

If you are using Cygwin, navigate to the folder where the example is and open the command prompt. Enter the following command to compile the example:
<syntaxhighlight lang='bash'>
gcc example.c -o example -I"/cygdrive/c/Program Files/Phidgets/Phidget22" -L"/cygdrive/c/Program Files/Phidgets/Phidget22/x86" -lphidget22
</syntaxhighlight>

If you are using MinGW, navigate to the folder where the example is and open the command prompt. Enter the following command to compile the example:
<syntaxhighlight lang='bash'>
gcc example.c -o example -I"C:/Program Files/Phidgets/Phidget22" -L"C:/Program Files/Phidgets/Phidget22/x86" -lphidget22
</syntaxhighlight>

After running the commands above for either Cygwin or MinGW, an executable file called ''example.exe'' will be created. Enter the following command to run the example:
<syntaxhighlight lang='bash'>
example.exe
</syntaxhighlight>

You should now have the example up and running. When you are ready, the next step is configuring your project and writing your own code!

=====Configure your project=====
When you are building a project from scratch, or adding Phidget functionality to an exisiting project, you'll need to configure your development environment to properly link the Phidget C/C++ library.

To include the Phidget C/C++ library, add the following line to your code:
<syntaxhighlight lang='C'>
#include <phidget22.h>
</syntaxhighlight>

You can now compile the file as shown in the previous section.

The project now has access to Phidgets. Next, view the [[#Write Code | write your own code]] section located below.

===Code::Blocks===
====Use our examples====
One of the best ways to start programming with Phidgets is to use our example code as a guide. In order to run the examples, you will need to download and install [http://www.codeblocks.org/downloads Code::Blocks].

Now that you have Code::Blocks installed, select an example that will work with your Phidget:
*{{SampleCode|C|C/C++ Examples}}

Open the example in Code::Blocks (you do not need to create a new project) and navigate to Settings -> Compiler... as shown in the image below:

[[Image:C_codeblocks_settings.png|link=|center]]

From the Global compiler settings screen, navigate to Search directories -> Compiler and add the following directory:
*C:\Program Files\Phidgets\Phidget22

[[Image:C_codeblocks_compiler.PNG|link=|center]]

Next, select Search directories -> Linker and add the following directory:
*C:\Program Files\Phidgets\Phidget22\x86

[[Image:C_codeblocks_linker.PNG|link=|center]]

Finally, from the Global compiler settings screen, navigate to Linker settings and add the following line:
*phidget22

[[Image:C_codeblocks_libraries.PNG|link=|center]]

You can now build and run the example:

[[Image:C_codeblocks_run.png|link=|center]]

You should now have the example up and running for your device. Play around with the device and experiment with some of the functionality. When you are ready, the next step is configuring your project and writing your own code!

====Configure your project====
When you are building a project from scratch, or adding Phidget functionality to an existing project, you'll need to configure your development environment to properly link the Phidget C/C++ library.

To include the Phidget C/C++ library, add the following line to your code:
<syntaxhighlight lang='C'>
#include <phidget22.h>
</syntaxhighlight>

You can now compile the file as shown in the previous section.

The project now has access to Phidgets. Next, view the [[#Write Code | write your own code]] section located below.

==macOS==
{{macOS_Languages}}
===GCC===
====Use our examples====
One of the best ways to start programming with Phidgets is to use our example code as a guide. You likely have gcc installed on your macOS machine already, but if not, you can easily get it by downloading [https://developer.apple.com/xcode/ Xcode].

Next, select an example that will work with your Phidget:
*{{SampleCode|C|C/C++ Examples}}

To compile the example program, enter the following command in the terminal:
<syntaxhighlight lang='bash'>
gcc example.c -o example -F /Library/Frameworks -framework Phidget22 -I /Library/Frameworks/Phidget22.framework/Headers
</syntaxhighlight>

Finally, run the program by entering the following command in the terminal:
<syntaxhighlight lang='bash'>
./example
</syntaxhighlight>

[[Image:c_mac_gcc.png|link=|center]]

You should now have the example up and running for your device. Play around with the device and experiment with some of the functionality. When you are ready, the next step is configuring your project and writing your own code!

====Configure your project====
When you are building a project from scratch, or adding Phidget functionality to an exisiting project, you'll need to configure your development environment to properly link the Phidget C/C++ library.

To include the Phidget C/C++ library, simply add the following line to your code:
<syntaxhighlight lang='C'>
#include <phidget22.h>
</syntaxhighlight>

You can now compile the file as shown in the previous section.

The project now has access to Phidgets. Next, view the [[#Write Code | write your own code]] section located below.

==Linux==
{{Linux_Languages}}
===GCC===
====Use our examples====
One of the best ways to start programming with Phidgets is to use our example code as a guide. You likely have gcc installed on your Linux machine already, but if not, you can easily get it by entering the following command in the terminal:
<syntaxhighlight lang='C'>
apt-get install gcc
</syntaxhighlight>

Next, select an example that will work with your Phidget:
*{{SampleCode|C|C/C++ Examples}}

To compile the example, enter the following command in the terminal:

<syntaxhighlight lang='bash'>
gcc example.c -o example -lphidget22
</syntaxhighlight>

After compiling, you can run the program by entering the following command in the terminal:
<syntaxhighlight lang='bash'>
./example
</syntaxhighlight>

You should now have the example up and running. When you are ready, the next step is configuring your project and writing your own code!

====Configure your project====
When you are building a project from scratch, or adding Phidget functionality to an exisiting project, you'll need to configure your development environment to properly link the Phidget C/C++ library.

To include the Phidget C/C++ library, simply add the following line to your code:
<syntaxhighlight lang='C'>
#include <phidget22.h>
</syntaxhighlight>

You can now compile the file as shown in the previous section.

The project now has access to Phidgets. Next, view the [[#Write Code | write your own code]] section located below.

==Write Code==
You've followed the instructions above for your operating system and now have a working example. Next, we will show you how the example was created and how it works by getting into the code. When you are ready, head to our [[Phidget Programming Basics]] page. There you will find code examples writen in C/C++ and you will be writing your own code in no time!

== Further Reading ==

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

Best Phidgets Practices

2017-07-12T19:21:21Z

Chad: /* Use Event Handlers */

[[Category:Programming]]
The purpose of this page is to provide a list of "Best Practices" to follow when writing code that uses Phidgets. These "Best Practices" are designed to eliminate common mistakes made when using the {{Phidget22API}}, and to help maintain an stable structure while build more complicated systems.

== Check Results ==
Almost every method in the {{Phidget22API}} returns a result code, or throws an exception if the language supports exceptions. The result code must be checked, and any exception caught, to ensure each operation is successful. Ignoring results will in the best case cause programs to crash, and in the worst, lead to invalid or unexpected behavior.

== Use Event Handlers ==
The Phidget library supports both polling channel properties to determine state and to get current data values, and the library supports firing events when states change and data is received. Reading channel properties directly is useful to determine the state or current data value at a point in time, but is difficult to implement correctly. Event handlers are more predicable and easier to implement correctly. Unless a program has a specific and obvious reason to access properties directly, event handlers should be used.

== Keep Event Handlers Short ==

Events handlers are called from special dispatch threads within the Phidget library. Each channel maintains its own queue of events, and these events are processed in order and one at a time. If a user event handler blocks, or takes longer than the <code>DataInterval</code> of the channel, events will become 'stale', and eventually the system will begin throwing away events.

For example, if an Accelerometer channel has been configured to receive data every 20 milliseconds and the event handler averages 21ms to execute, the next change event will be ready before the previous one is finished being processed. Eventually the channel's event queue will fill and the library will begin throwing away events.

A common mistake is to update a GUI, or wait for user input from within an event handler. Most GUI APIs have support for dispatching updates to the GUI thread, and those should be used. Waiting for user input will block the event handler, and should never be done. Instead, a flag should be set and a loop in another thread should wait for the input.

== Be Specific With Open() ==

When you use {{Code|Open()}} to access a Phidget device channel, the library will first try to match a channel of the class that you're using. After the class, there are a number of other matching properties can be set to further filter which device channel is matched. For example:

* The '''serial number''' of a device or VINT Hub
* The '''hub port''' a VINT device is plugged into
* The '''channel''' number of a device channel, when a device has multiple channels of the same class
* If a channel '''is remote''' or '''is local'''
* The '''server name''', if a device channel is being accessed over the [[Phidget Network Server]]

If none of the matching properties are set, the Phidget library will match the first channel of the same class. In simple cases this will be fine. For example, if a Phidget temperature sensor is the only device connected to a computer, opening a {{Code|TemperatureSensor}} channel without setting any matching properties will match that temperature sensor; however, if a DC motor controller is connected to the computer, the on-board temperature sensor on the motor control may match. Setting the {{Code|DeviceSerialNumber}} will force the channel to match the desired device channel.

Since there's no way to predict what other Phidgets may be plugged into a computer (or become available over the network), you should be as specific as possible before opening a channel.

== When In Doubt, Open Remotely ==
When the [[Phidget Network Server|Network Server]] is enabled, a channel can match both a local device channel and a remote channel. The end result would be functionally the same; however, most remote channels support being attached to multiple clients, while a local device channel can only be attached once. Unless the desire is to only allow the device channel to be attached once, or performance is critical, it is more flexible to match the network channel as other clients will still be able to attach to the device channel.

See the <code>IsRemote</code> and <code>IsLocal</code> Phidget properties in the {{Phidget22API}}.

== Set Properties in the Attach Handler ==

An attach event will occur each time a channel is matched. This makes the attach handler the perfect place to initialize properties such as {{Code|DataInterval}}, {{Code|ChangeTrigger}}, gain values, and ranges. If properties are initialize elsewhere, in a situation where the channel detaches temporarily, those properties will revert to defaults during the next attach. Setting properties within the attach handler ensures they are always the expected values.

== Don't Forget to Close() ==

Calling {{Code|Close()}} on a channel releases the channel so that it can be matched again. In most cases, it's not technically necessary to call {{Code|Close()}} because when a program exits, the channel will be released; however, it is good practice to close the channel when you are finished as some environments will not release the channel automatically. For example in [[Language_-_LabVIEW|LabVIEW]], the runtime environment executes a program internally, so if {{Code|Close()}} is not called, the LabVIEW environment will continue to tie up the channel despite the program having been stopped.

== Further Reading ==

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

Best Phidgets Practices

2017-07-12T19:12:49Z

Chad: /* Don't Forget to Close() */

[[Category:Programming]]
The purpose of this page is to provide a list of "Best Practices" to follow when writing code that uses Phidgets. These "Best Practices" are designed to eliminate common mistakes made when using the {{Phidget22API}}, and to help maintain an stable structure while build more complicated systems.

== Use Event Handlers ==
The Phidget library supports both polling channel properties to determine state and to get current data values, and the library supports firing events when states change and data is received. Reading channel properties directly is useful to determine the state or current data value at a point in time, but is difficult to implement correctly. Event handlers are more predicable and easier to implement correctly. Unless a program has a specific and obvious reason to access properties directly, event handlers should be used.

== Keep Event Handlers Short ==

Events handlers are called from special dispatch threads within the Phidget library. Each channel maintains its own queue of events, and these events are processed in order and one at a time. If a user event handler blocks, or takes longer than the <code>DataInterval</code> of the channel, events will become 'stale', and eventually the system will begin throwing away events.

For example, if an Accelerometer channel has been configured to receive data every 20 milliseconds and the event handler averages 21ms to execute, the next change event will be ready before the previous one is finished being processed. Eventually the channel's event queue will fill and the library will begin throwing away events.

A common mistake is to update a GUI, or wait for user input from within an event handler. Most GUI APIs have support for dispatching updates to the GUI thread, and those should be used. Waiting for user input will block the event handler, and should never be done. Instead, a flag should be set and a loop in another thread should wait for the input.

== Be Specific With Open() ==

When you use {{Code|Open()}} to access a Phidget device channel, the library will first try to match a channel of the class that you're using. After the class, there are a number of other matching properties can be set to further filter which device channel is matched. For example:

* The '''serial number''' of a device or VINT Hub
* The '''hub port''' a VINT device is plugged into
* The '''channel''' number of a device channel, when a device has multiple channels of the same class
* If a channel '''is remote''' or '''is local'''
* The '''server name''', if a device channel is being accessed over the [[Phidget Network Server]]

If none of the matching properties are set, the Phidget library will match the first channel of the same class. In simple cases this will be fine. For example, if a Phidget temperature sensor is the only device connected to a computer, opening a {{Code|TemperatureSensor}} channel without setting any matching properties will match that temperature sensor; however, if a DC motor controller is connected to the computer, the on-board temperature sensor on the motor control may match. Setting the {{Code|DeviceSerialNumber}} will force the channel to match the desired device channel.

Since there's no way to predict what other Phidgets may be plugged into a computer (or become available over the network), you should be as specific as possible before opening a channel.

== When In Doubt, Open Remotely ==
When the [[Phidget Network Server|Network Server]] is enabled, a channel can match both a local device channel and a remote channel. The end result would be functionally the same; however, most remote channels support being attached to multiple clients, while a local device channel can only be attached once. Unless the desire is to only allow the device channel to be attached once, or performance is critical, it is more flexible to match the network channel as other clients will still be able to attach to the device channel.

See the <code>IsRemote</code> and <code>IsLocal</code> Phidget properties in the {{Phidget22API}}.

== Set Properties in the Attach Handler ==

An attach event will occur each time a channel is matched. This makes the attach handler the perfect place to initialize properties such as {{Code|DataInterval}}, {{Code|ChangeTrigger}}, gain values, and ranges. If properties are initialize elsewhere, in a situation where the channel detaches temporarily, those properties will revert to defaults during the next attach. Setting properties within the attach handler ensures they are always the expected values.

== Don't Forget to Close() ==

Calling {{Code|Close()}} on a channel releases the channel so that it can be matched again. In most cases, it's not technically necessary to call {{Code|Close()}} because when a program exits, the channel will be released; however, it is good practice to close the channel when you are finished as some environments will not release the channel automatically. For example in [[Language_-_LabVIEW|LabVIEW]], the runtime environment executes a program internally, so if {{Code|Close()}} is not called, the LabVIEW environment will continue to tie up the channel despite the program having been stopped.

== Further Reading ==

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

Best Phidgets Practices

2017-07-12T19:08:31Z

Chad: /* Set Properties in the Attach Handler */

[[Category:Programming]]
The purpose of this page is to provide a list of "Best Practices" to follow when writing code that uses Phidgets. These "Best Practices" are designed to eliminate common mistakes made when using the {{Phidget22API}}, and to help maintain an stable structure while build more complicated systems.

== Use Event Handlers ==
The Phidget library supports both polling channel properties to determine state and to get current data values, and the library supports firing events when states change and data is received. Reading channel properties directly is useful to determine the state or current data value at a point in time, but is difficult to implement correctly. Event handlers are more predicable and easier to implement correctly. Unless a program has a specific and obvious reason to access properties directly, event handlers should be used.

== Keep Event Handlers Short ==

Events handlers are called from special dispatch threads within the Phidget library. Each channel maintains its own queue of events, and these events are processed in order and one at a time. If a user event handler blocks, or takes longer than the <code>DataInterval</code> of the channel, events will become 'stale', and eventually the system will begin throwing away events.

For example, if an Accelerometer channel has been configured to receive data every 20 milliseconds and the event handler averages 21ms to execute, the next change event will be ready before the previous one is finished being processed. Eventually the channel's event queue will fill and the library will begin throwing away events.

A common mistake is to update a GUI, or wait for user input from within an event handler. Most GUI APIs have support for dispatching updates to the GUI thread, and those should be used. Waiting for user input will block the event handler, and should never be done. Instead, a flag should be set and a loop in another thread should wait for the input.

== Be Specific With Open() ==

When you use {{Code|Open()}} to access a Phidget device channel, the library will first try to match a channel of the class that you're using. After the class, there are a number of other matching properties can be set to further filter which device channel is matched. For example:

* The '''serial number''' of a device or VINT Hub
* The '''hub port''' a VINT device is plugged into
* The '''channel''' number of a device channel, when a device has multiple channels of the same class
* If a channel '''is remote''' or '''is local'''
* The '''server name''', if a device channel is being accessed over the [[Phidget Network Server]]

If none of the matching properties are set, the Phidget library will match the first channel of the same class. In simple cases this will be fine. For example, if a Phidget temperature sensor is the only device connected to a computer, opening a {{Code|TemperatureSensor}} channel without setting any matching properties will match that temperature sensor; however, if a DC motor controller is connected to the computer, the on-board temperature sensor on the motor control may match. Setting the {{Code|DeviceSerialNumber}} will force the channel to match the desired device channel.

Since there's no way to predict what other Phidgets may be plugged into a computer (or become available over the network), you should be as specific as possible before opening a channel.

== When In Doubt, Open Remotely ==
When the [[Phidget Network Server|Network Server]] is enabled, a channel can match both a local device channel and a remote channel. The end result would be functionally the same; however, most remote channels support being attached to multiple clients, while a local device channel can only be attached once. Unless the desire is to only allow the device channel to be attached once, or performance is critical, it is more flexible to match the network channel as other clients will still be able to attach to the device channel.

See the <code>IsRemote</code> and <code>IsLocal</code> Phidget properties in the {{Phidget22API}}.

== Set Properties in the Attach Handler ==

An attach event will occur each time a channel is matched. This makes the attach handler the perfect place to initialize properties such as {{Code|DataInterval}}, {{Code|ChangeTrigger}}, gain values, and ranges. If properties are initialize elsewhere, in a situation where the channel detaches temporarily, those properties will revert to defaults during the next attach. Setting properties within the attach handler ensures they are always the expected values.

== Don't Forget to Close() ==

Calling {{Code|Close()}} on a channel releases the channel so that it can be matched again. In most cases, it's not technically necessary to call {{Code|Close()}} because when your program exits, the channel will be released; however, it is good practice to close a channel when you are finished with it as some environments will not release the channel automatically. For example in [[Language_-_LabVIEW|LabVIEW]], the runtime environment merely interprets your program, so if you do not call {{Code|Close()}}, the LabVIEW environment will continue to tie up the channel despite having stopped the program you're working on.

== Further Reading ==

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

Best Phidgets Practices

2017-07-12T19:05:56Z

Chad: /* When In Doubt, Open Remotely */

[[Category:Programming]]
The purpose of this page is to provide a list of "Best Practices" to follow when writing code that uses Phidgets. These "Best Practices" are designed to eliminate common mistakes made when using the {{Phidget22API}}, and to help maintain an stable structure while build more complicated systems.

== Use Event Handlers ==
The Phidget library supports both polling channel properties to determine state and to get current data values, and the library supports firing events when states change and data is received. Reading channel properties directly is useful to determine the state or current data value at a point in time, but is difficult to implement correctly. Event handlers are more predicable and easier to implement correctly. Unless a program has a specific and obvious reason to access properties directly, event handlers should be used.

== Keep Event Handlers Short ==

Events handlers are called from special dispatch threads within the Phidget library. Each channel maintains its own queue of events, and these events are processed in order and one at a time. If a user event handler blocks, or takes longer than the <code>DataInterval</code> of the channel, events will become 'stale', and eventually the system will begin throwing away events.

For example, if an Accelerometer channel has been configured to receive data every 20 milliseconds and the event handler averages 21ms to execute, the next change event will be ready before the previous one is finished being processed. Eventually the channel's event queue will fill and the library will begin throwing away events.

A common mistake is to update a GUI, or wait for user input from within an event handler. Most GUI APIs have support for dispatching updates to the GUI thread, and those should be used. Waiting for user input will block the event handler, and should never be done. Instead, a flag should be set and a loop in another thread should wait for the input.

== Be Specific With Open() ==

When you use {{Code|Open()}} to access a Phidget device channel, the library will first try to match a channel of the class that you're using. After the class, there are a number of other matching properties can be set to further filter which device channel is matched. For example:

* The '''serial number''' of a device or VINT Hub
* The '''hub port''' a VINT device is plugged into
* The '''channel''' number of a device channel, when a device has multiple channels of the same class
* If a channel '''is remote''' or '''is local'''
* The '''server name''', if a device channel is being accessed over the [[Phidget Network Server]]

If none of the matching properties are set, the Phidget library will match the first channel of the same class. In simple cases this will be fine. For example, if a Phidget temperature sensor is the only device connected to a computer, opening a {{Code|TemperatureSensor}} channel without setting any matching properties will match that temperature sensor; however, if a DC motor controller is connected to the computer, the on-board temperature sensor on the motor control may match. Setting the {{Code|DeviceSerialNumber}} will force the channel to match the desired device channel.

Since there's no way to predict what other Phidgets may be plugged into a computer (or become available over the network), you should be as specific as possible before opening a channel.

== When In Doubt, Open Remotely ==
When the [[Phidget Network Server|Network Server]] is enabled, a channel can match both a local device channel and a remote channel. The end result would be functionally the same; however, most remote channels support being attached to multiple clients, while a local device channel can only be attached once. Unless the desire is to only allow the device channel to be attached once, or performance is critical, it is more flexible to match the network channel as other clients will still be able to attach to the device channel.

See the <code>IsRemote</code> and <code>IsLocal</code> Phidget properties in the {{Phidget22API}}.

== Set Properties in the Attach Handler ==

An '''attach''' event will occur each time a channel is matched. This makes the attach handler the perfect place to initialize properties such as {{Code|DataInterval}}, {{Code|ChangeTrigger}}, gain values, and ranges. If properties are initialize elsewhere, in a situation where the channel detaches those properties will revert to defaults. Setting properties within the '''attach''' handler ensures they are always the expected values.

== Don't Forget to Close() ==

Calling {{Code|Close()}} on a channel releases the channel so that it can be matched again. In most cases, it's not technically necessary to call {{Code|Close()}} because when your program exits, the channel will be released; however, it is good practice to close a channel when you are finished with it as some environments will not release the channel automatically. For example in [[Language_-_LabVIEW|LabVIEW]], the runtime environment merely interprets your program, so if you do not call {{Code|Close()}}, the LabVIEW environment will continue to tie up the channel despite having stopped the program you're working on.

== Further Reading ==

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

Best Phidgets Practices

2017-07-12T19:02:57Z

Chad: /* Be Specific With Open() */

[[Category:Programming]]
The purpose of this page is to provide a list of "Best Practices" to follow when writing code that uses Phidgets. These "Best Practices" are designed to eliminate common mistakes made when using the {{Phidget22API}}, and to help maintain an stable structure while build more complicated systems.

== Use Event Handlers ==
The Phidget library supports both polling channel properties to determine state and to get current data values, and the library supports firing events when states change and data is received. Reading channel properties directly is useful to determine the state or current data value at a point in time, but is difficult to implement correctly. Event handlers are more predicable and easier to implement correctly. Unless a program has a specific and obvious reason to access properties directly, event handlers should be used.

== Keep Event Handlers Short ==

Events handlers are called from special dispatch threads within the Phidget library. Each channel maintains its own queue of events, and these events are processed in order and one at a time. If a user event handler blocks, or takes longer than the <code>DataInterval</code> of the channel, events will become 'stale', and eventually the system will begin throwing away events.

For example, if an Accelerometer channel has been configured to receive data every 20 milliseconds and the event handler averages 21ms to execute, the next change event will be ready before the previous one is finished being processed. Eventually the channel's event queue will fill and the library will begin throwing away events.

A common mistake is to update a GUI, or wait for user input from within an event handler. Most GUI APIs have support for dispatching updates to the GUI thread, and those should be used. Waiting for user input will block the event handler, and should never be done. Instead, a flag should be set and a loop in another thread should wait for the input.

== Be Specific With Open() ==

When you use {{Code|Open()}} to access a Phidget device channel, the library will first try to match a channel of the class that you're using. After the class, there are a number of other matching properties can be set to further filter which device channel is matched. For example:

* The '''serial number''' of a device or VINT Hub
* The '''hub port''' a VINT device is plugged into
* The '''channel''' number of a device channel, when a device has multiple channels of the same class
* If a channel '''is remote''' or '''is local'''
* The '''server name''', if a device channel is being accessed over the [[Phidget Network Server]]

If none of the matching properties are set, the Phidget library will match the first channel of the same class. In simple cases this will be fine. For example, if a Phidget temperature sensor is the only device connected to a computer, opening a {{Code|TemperatureSensor}} channel without setting any matching properties will match that temperature sensor; however, if a DC motor controller is connected to the computer, the on-board temperature sensor on the motor control may match. Setting the {{Code|DeviceSerialNumber}} will force the channel to match the desired device channel.

Since there's no way to predict what other Phidgets may be plugged into a computer (or become available over the network), you should be as specific as possible before opening a channel.

== When In Doubt, Open Remotely ==
When the [[Phidget Network Server|Network Server]] is enabled, a channel can match both a local device channel and a remote channel. The end result would be the same as the same actual device channel would be attached; however, most remote channels support being attached to multiple clients, while a local device channel can only be attached once. Unless the desire is to only allow the device channel to be attached once, or performance is critical, it is more flexible to match the network channel.

See the <code>IsRemote</code> and <code>IsLocal</code> Phidget properties in the {{Phidget22API}}.

== Set Properties in the Attach Handler ==

An '''attach''' event will occur each time a channel is matched. This makes the attach handler the perfect place to initialize properties such as {{Code|DataInterval}}, {{Code|ChangeTrigger}}, gain values, and ranges. If properties are initialize elsewhere, in a situation where the channel detaches those properties will revert to defaults. Setting properties within the '''attach''' handler ensures they are always the expected values.

== Don't Forget to Close() ==

Calling {{Code|Close()}} on a channel releases the channel so that it can be matched again. In most cases, it's not technically necessary to call {{Code|Close()}} because when your program exits, the channel will be released; however, it is good practice to close a channel when you are finished with it as some environments will not release the channel automatically. For example in [[Language_-_LabVIEW|LabVIEW]], the runtime environment merely interprets your program, so if you do not call {{Code|Close()}}, the LabVIEW environment will continue to tie up the channel despite having stopped the program you're working on.

== Further Reading ==

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

Best Phidgets Practices

2017-07-12T19:00:48Z

Chad: /* Keep Event Handlers Short */

[[Category:Programming]]
The purpose of this page is to provide a list of "Best Practices" to follow when writing code that uses Phidgets. These "Best Practices" are designed to eliminate common mistakes made when using the {{Phidget22API}}, and to help maintain an stable structure while build more complicated systems.

== Use Event Handlers ==
The Phidget library supports both polling channel properties to determine state and to get current data values, and the library supports firing events when states change and data is received. Reading channel properties directly is useful to determine the state or current data value at a point in time, but is difficult to implement correctly. Event handlers are more predicable and easier to implement correctly. Unless a program has a specific and obvious reason to access properties directly, event handlers should be used.

== Keep Event Handlers Short ==

Events handlers are called from special dispatch threads within the Phidget library. Each channel maintains its own queue of events, and these events are processed in order and one at a time. If a user event handler blocks, or takes longer than the <code>DataInterval</code> of the channel, events will become 'stale', and eventually the system will begin throwing away events.

For example, if an Accelerometer channel has been configured to receive data every 20 milliseconds and the event handler averages 21ms to execute, the next change event will be ready before the previous one is finished being processed. Eventually the channel's event queue will fill and the library will begin throwing away events.

A common mistake is to update a GUI, or wait for user input from within an event handler. Most GUI APIs have support for dispatching updates to the GUI thread, and those should be used. Waiting for user input will block the event handler, and should never be done. Instead, a flag should be set and a loop in another thread should wait for the input.

== Be Specific With Open() ==

When you use {{Code|Open()}} to access a Phidget device channel, the library will first try to match a channel of the class that you're using. There are a number of other matching properties can be set to further filter which device channel is matched. For example:

* The '''serial number''' of a device or VINT Hub
* The '''port''' a VINT device is plugged into
* The '''channel''' number of a device channel, when a device has multiple channels of the same class
* If a channel '''is remote''' or '''is local'''
* The '''server name''', if a device channel is being accessed over the [[Phidget Network Server]]

If none of the matching properties are set, the Phidget library will match the first channel of the same class. In simple cases this will be fine. For example, if a Phidget temperature sensor is the only device connected to a computer, opening a {{Code|TemperatureSensor}} channel without setting any matching properties will match that temperature sensor; however, if a DC motor controller is connected to the computer, the on-board temperature sensor on the motor control may match. Setting the {{Code|DeviceSerialNumber}} will force the channel to match the desired device channel.

Since there's no way to predict what other Phidgets may be plugged into a computer (or become available over the network), you should be as specific as possible before opening a channel.

== When In Doubt, Open Remotely ==
When the [[Phidget Network Server|Network Server]] is enabled, a channel can match both a local device channel and a remote channel. The end result would be the same as the same actual device channel would be attached; however, most remote channels support being attached to multiple clients, while a local device channel can only be attached once. Unless the desire is to only allow the device channel to be attached once, or performance is critical, it is more flexible to match the network channel.

See the <code>IsRemote</code> and <code>IsLocal</code> Phidget properties in the {{Phidget22API}}.

== Set Properties in the Attach Handler ==

An '''attach''' event will occur each time a channel is matched. This makes the attach handler the perfect place to initialize properties such as {{Code|DataInterval}}, {{Code|ChangeTrigger}}, gain values, and ranges. If properties are initialize elsewhere, in a situation where the channel detaches those properties will revert to defaults. Setting properties within the '''attach''' handler ensures they are always the expected values.

== Don't Forget to Close() ==

Calling {{Code|Close()}} on a channel releases the channel so that it can be matched again. In most cases, it's not technically necessary to call {{Code|Close()}} because when your program exits, the channel will be released; however, it is good practice to close a channel when you are finished with it as some environments will not release the channel automatically. For example in [[Language_-_LabVIEW|LabVIEW]], the runtime environment merely interprets your program, so if you do not call {{Code|Close()}}, the LabVIEW environment will continue to tie up the channel despite having stopped the program you're working on.

== Further Reading ==

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

Best Phidgets Practices

2017-07-12T18:53:26Z

Chad:

[[Category:Programming]]
The purpose of this page is to provide a list of "Best Practices" to follow when writing code that uses Phidgets. These "Best Practices" are designed to eliminate common mistakes made when using the {{Phidget22API}}, and to help maintain an stable structure while build more complicated systems.

== Keep Event Handlers Short ==

User events handlers are called from special dispatch threads within the Phidget library. Each channel maintains its own queue of events, and these events are processed in order and one at a time. If a user event handler blocks, or takes longer than the <code>DataInterval</code> of the channel, events will become 'stale', and eventually the system will begin throwing away events.

For example, if an Accelerometer channel has been configured to receive data every 20 milliseconds and the event handler averages 21ms to execute, the next change event will be ready before the previous one is finished being processed. Eventually the channel's event queue will fill and the library will begin throwing away events.

A common mistake is to update a GUI, or wait for user input from within an event handler. Most GUI APIs have support for dispatching updates to the GUI thread, and those should be used. Waiting for user input will block the event handler, and should never be done. Instead, a flag should be set and a loop in the main of the program (or another thread) should wait for the input.

== Be Specific With Open() ==

When you use {{Code|Open()}} to access a Phidget device channel, the library will first try to match a channel of the class that you're using. There are a number of other matching properties can be set to further filter which device channel is matched. For example:

* The '''serial number''' of a device or VINT Hub
* The '''port''' a VINT device is plugged into
* The '''channel''' number of a device channel, when a device has multiple channels of the same class
* If a channel '''is remote''' or '''is local'''
* The '''server name''', if a device channel is being accessed over the [[Phidget Network Server]]

If none of the matching properties are set, the Phidget library will match the first channel of the same class. In simple cases this will be fine. For example, if a Phidget temperature sensor is the only device connected to a computer, opening a {{Code|TemperatureSensor}} channel without setting any matching properties will match that temperature sensor; however, if a DC motor controller is connected to the computer, the on-board temperature sensor on the motor control may match. Setting the {{Code|DeviceSerialNumber}} will force the channel to match the desired device channel.

Since there's no way to predict what other Phidgets may be plugged into a computer (or become available over the network), you should be as specific as possible before opening a channel.

== When In Doubt, Open Remotely ==
When the [[Phidget Network Server|Network Server]] is enabled, a channel can match both a local device channel and a remote channel. The end result would be the same as the same actual device channel would be attached; however, most remote channels support being attached to multiple clients, while a local device channel can only be attached once. Unless the desire is to only allow the device channel to be attached once, or performance is critical, it is more flexible to match the network channel.

See the <code>IsRemote</code> and <code>IsLocal</code> Phidget properties in the {{Phidget22API}}.

== Set Properties in the Attach Handler ==

An '''attach''' event will occur each time a channel is matched. This makes the attach handler the perfect place to initialize properties such as {{Code|DataInterval}}, {{Code|ChangeTrigger}}, gain values, and ranges. If properties are initialize elsewhere, in a situation where the channel detaches those properties will revert to defaults. Setting properties within the '''attach''' handler ensures they are always the expected values.

== Don't Forget to Close() ==

Calling {{Code|Close()}} on a channel releases the channel so that it can be matched again. In most cases, it's not technically necessary to call {{Code|Close()}} because when your program exits, the channel will be released; however, it is good practice to close a channel when you are finished with it as some environments will not release the channel automatically. For example in [[Language_-_LabVIEW|LabVIEW]], the runtime environment merely interprets your program, so if you do not call {{Code|Close()}}, the LabVIEW environment will continue to tie up the channel despite having stopped the program you're working on.

== Further Reading ==

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

Phidget Programming Basics

2017-07-12T18:48:06Z

Chad: /* Close a Channel */

[[Category:Programming]]
__TOC__

It is important to understand what a Phidget is, and how the hardware and software relate to one another before writing software using the {{Phidget22API}}. Please refer to [[What is a Phidget?]] for an introduction.

The Phidget software library matches a Phidget device channel with a software channel that is created by a user.
Software channels are each of a class, where that class defines a set of methods, properties, events and errors. Phidget devices are aware of the channel classes, and expose access to features of the device through the class interface.

To use a Phidget, you'll want to:
# '''[[#Creating a Channel|Create]]''' an instance of the channel class that provides access to the device you want to control.
# '''[[#Opening a Channel|Open]]''' the channel.
# Detect when the channel is '''[[#Attaching a Channel|attached]]''' to the Phidget.
# Use '''[[#Do Things with a Channel|methods and properties]]''' of the attached channel.
# '''[[#Close a Channel|Close]]''' the channel.

Small code snippets are provided for each step in the sections below. [[Language - Java|Java]] and [[Language - C/C++|C]] were selected because Java is a high-level language and C is a low level language. The best reference to the ''features'' each channel class is the {{Phidget22API}} for your specific language. This page is intended to be a high-level introduction.

== Creating a Channel ==

A Phidget device exposes one or more device channels where each channel is an interface to a feature of the hardware. A channel class defines an interface to control and query a channel of the Phidget device. For example, a 1018 - Phidget InterfaceKit device includes support
for digital input and digital out, and therefore exports <code>DigitalInput</code> and <code>DigitalOutput</code> channels.

Phidget devices are controlled by creating an instance of a Phidget channel class. Each channel class has a function that allows you to '''create''' an instance, and a function to later '''delete''' the instance.

For example, in Java:

<syntaxhighlight lang=java>
// Create a new Accelerometer channel
Accelerometer accel = new Accelerometer();
</syntaxhighlight>
<syntaxhighlight lang=java>
// Create a new RFID channel
RFID rfid = new RFID();
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
// Create a new Accelerometer channel
PhidgetAccelerometerHandle accel;
PhidgetAccelerometer_create(&accel);
</syntaxhighlight>
<syntaxhighlight lang=c>
// Create a new RFID channel
PhidgetRFIDHandle rfid;
PhidgetRFID_create(&rfid);
</syntaxhighlight>

A channel class will have properties and methods specific to the feature they belong to. For example, the <code>VoltageInput</code> class has a <code>Voltage</code> property that lets you access the current voltage measured by the device, the <code>Accelerometer</code> class has properties to set the sensitivity on each axis and the <code>RFID</code> has a method that writes to a writable RFID tag.

== Opening a Channel ==

After you have created a [[#Creating a Channel| channel instance]], you can call the <code>open()</code> method to begin the process of matching the channel to a Phidget device channel.

For example, with the <code>Accelerometer</code> channel in Java:

<syntaxhighlight lang=java>
accel.open();
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
Phidget_open((PhidgetHandle) accel);
</syntaxhighlight>

To see how to use <code>open()</code> in other languages, please refer to the {{Phidget22API}}.

The <code>open()</code> function begins the process of matching the channel handle you created to a channel of a Phidget device, and does not actually ''open'' the Phidget itself. An open channel may match a new Phidget device when it is plugged in if that channel has not already found a Phidget device channel that meets its criteria.

===Details for Open()===

Because <code>open()</code> simply enables the process of matching a channel to a Phidget device channel, <code>open()</code> returns immediately and does not wait for the channel to attach to a Phidget device channel. The channel changes state to ''open'', but is not necessarily ''attached''. Until the channel actually becomes ''attached'' to a Phidget device channel, most of the channel class interface will not be available.

As long as the channel is open (and not ''attached''), the system will continue to try to match it with a
Phidget device channel that has not already been matched with a channel. The channel can only be matched once, and the Phidget device channel can only be matched once. For example, if you connected a single Phidget Accelerometer to a computer, and you created and opened two <code>Accelerometer</code> channels, only one of the channels would attach while the other would remain ''open'' but not ''attached''. If the ''attached'' channel were to be closed, the other channel would then attach to the Accelerometer.

When the channels is matched with a Phidget device channel, the channel state is changed to ''attached'' and an event is fired.

'''Note:''' Once a Phidget device channel is matched to a channel, it will not be available to match another channel until the first channel is closed. The one exception is if the Phidget device channel is ''attached'' over the network through the [[Phidget Network Server]]. In that case, multiple channels are allowed to match and attach to the Phidget device channel. Some Phidgets, such as motor controllers will never match more than one channel at a time.

===Channel Matching===

<code>open()</code> can be used without specifying any matching properties. In this case the system will match a channel with the first Phidget device channel that matches the channel class. The channel class itself is an implied matching parameter.

If there is more than one Phidget connected to the computer that supports the channel class, the <code>DeviceSerialNumber</code> property must be set determine which Phidget will match.

If the Phidget connected to the computer has more than one channel of the same classes, the <code>Channel</code> property must be set to determine which Phidget device channel will match.

If the Phidget Network Server is enabled on the computer, the <code>IsRemote</code> and <code>IsLocal</code> properties can be used to determine if the channel will match the Phidget device channel or the network channel.

Please refer to the {{Phidget22API}}, and [[Best Phidgets Practices|Best Practices]] for more information on matching channels to Phidget device channels.

==== Opening a Channel on a USB Phidget ====

[[Image:channel-matching-1.jpg|link=|500px]]

In this example, a [{{SERVER}}/products.php?product_id=1018 1018 PhidgetInterfaceKit 8/8/8] is connected to a computer. A [{{SERVER}}/products.php?product_id=1108 1108 Magnetic Sensor] is connected to analog port 3 on the 1018. Here's how you would open the channel for the magnetic sensor in Java:

<syntaxhighlight lang=java>
VoltageRatioInput ch = new VoltageRatioInput();
ch.setDeviceSerialNumber(324781);
ch.setChannel(3);
ch.open();
</syntaxhighlight>

If you wanted to open digital input 5 in the same example, it would look like this:

<syntaxhighlight lang=java>
DigitalInput ch = new DigitalInput();
ch.setDeviceSerialNumber(324781);
ch.setChannel(5);
ch.open();
</syntaxhighlight>

==== Opening a VINT Hub Port as a Channel ====

The ports on a [[What is VINT?|VINT]] Hub can be opened as Digital Inputs, Digital Outputs, Voltage Inputs, or Voltage Ratio Inputs. Suppose you had a [{{SERVER}}/products.php?product_id=HUB0000 HUB0000 VINT Hub] with a [{{SERVER}}/products.php?product_id=1133 1133 Sound Sensor] connected to its sixth port.

[[Image:channel-matching-2.jpg|link=|500px]]

Here's how you would open it in Java:

<syntaxhighlight lang=java>
VoltageInput ch = new VoltageInput();
ch.setDeviceSerialNumber(370181);
ch.setIsHubPortDevice(true);
ch.setHubPort(6);
ch.open();
</syntaxhighlight>

==== Opening a Channel on a VINT Device ====

In this example, we have a [{{SERVER}}/products.php?product_id=TMP1101 TMP1101 4x Thermocouple Phidget] and a [{{SERVER}}/products.php?product_id=HUB0000 HUB0000 VINT Hub].

[[Image:channel-matching-3.jpg|link=|500px]]

If we wanted to open both the thermocouple connected to port 0 and the integrated temperature sensor on the board, we first need to figure out which channels those are. Go to the [{{SERVER}}/products.php?product_id=TMP1101 product page for the TMP1101] and click on the API tab. From the table at the top of the tab, we can see that the integrated temperature sensor is TemperatureSensor channel 4. In Java, opening these channels would look like this:

<syntaxhighlight lang=java>
TemperatureSensor tc = new TemperatureSensor(); // Handle for the thermocouple
TemperatureSensor ic = new TemperatureSensor(); // Handle for the integrated temperature chip

tc.setDeviceSerialNumber();
ic.setDeviceSerialNumber();
tc.setHubPort(2);
ic.setHubPort(2);
tc.setChannel(0);
ic.setChannel(4);

tc.open();
ic.open();
</syntaxhighlight>

==== Opening a Channel on a Remote Phidget ====

Suppose you wanted to open a locally connected Phidget remotely over the Network Service, so that you could have multiple programs connecting to it at the same time. In this example, we have a [{{SERVER}}/products.php?product_id=1024 1024 PhidgetRFID] connected to a computer that has the Phidget Network Server enabled.

[[Image:channel-matching-4.jpg|link=|600px]]

You could open the RFID reader channel remotely with the following code in Java:

<syntaxhighlight lang=java>
RFID ch = new RFID();
ch.setDeviceSerialNumber(388624);
ch.setIsRemote(true);
ch.open();
</syntaxhighlight>

== Attaching a Channel ==

When a channel is open (and not ''attached''), the system will continue to try to match it with a
Phidget device channel until either a match is found, or the channel is closed. When the channels is matched with a Phidget device channel, the channel state is changed to ''attached'' and an event is fired.

An event handler can be registered to catch the ''attach event'' through the channel's <code>Attach</code> event. Each channel also has a <code>Attached</code> property that can be read to determine if the class has
been matched to a Phidget device channel.

To set an event handler to detect the attach in Java:

<syntaxhighlight lang=java>
//create a Phidget accelerometer channel:
Accelerometer accel = new Accelerometer();
accel.addAttachListener((AttachEvent ae) -> {
Accelerometer accel = (Accelerometer) ae.getSource();
// Do things after attachment (i.e. read data, control the device)
}
});
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
// Define the attach handler function
void CCONV
onAttachedEventHandler(PhidgetHandle channel, void *userPtr) {
printf("A channel has been attached\n");
// Do things after attachment (i.e. read data, control the device)
}

int
main(int argc, char **argv) {
// .....Then, in the main code create the channel and set the attach handler:
PhidgetAccelerometerHandle accel;
PhidgetAccelerometer_create(&accel);
Phidget_setOnAttachHandler((PhidgetHandle)accel, onAttachedEventHandler, NULL);

// other stuff in main
}
</syntaxhighlight>

The attach event handler should be set '''before''' the channel is opened; otherwise, the attach event could occur before the handler is set.

== Do Things with a Channel ==

After a channel has been ''opened'' and ''attached'', software can control the Phidget device via the channel class interface.

Like setting an event handler that executes [[#Attaching a Channel|when the channels is attached]], handlers can be set to receive events when a state change occurs, or sensor data is received.

A Voltage Input channel for example, like one supported by the [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit], can set an event handler that gets called as the voltage is processed.

In Java, this would look like:

<syntaxhighlight lang=java>
// After creating and opening a VoltageInput channel called "sensorIn"
sensorIn.addVoltageChangeListener((VoltageInputVoltageChangeEvent de) -> {
System.out.println("Voltage: " + de.getVoltage());
});
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
void CCONV
onVoltageChangeHandler(PhidgetVoltageInputHandle voltageInput, void *ctx, double voltage) {
printf("Voltage: %lf V\n", voltage);
}

// .....Then, in the main code:
// After creating and opening a VoltageInput channel called "sensorIn"
PhidgetVoltageInput_setOnVoltageChangeHandler(sensorIn, onVoltageChangeHandler, NULL);
</syntaxhighlight>

The voltage value delivered in the above snippets could also be accessed via the <code>Voltage</code> property of the channel. Properties that have related events are automatically updated each time the event is received by the channel, and calls between events always return the value set by the last event.

<syntaxhighlight lang=java>
double val = sensorIn.getVoltage();
</syntaxhighlight>

Or, in C:

<syntaxhighlight lang=c>
double val;
PhidgetVoltageInput_getVoltage(sensorIn, &val);
</syntaxhighlight>

===Sensors, Input, and Output===

Often, your Phidget will support more than one channel class. For example a [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit] has voltage inputs (black sensor ports), digital inputs and digital outputs (green terminal blocks). You can determine the channel classes supported by your Phidget from the product page and the {{Phidget22API}}.

For InterfaceKits like the 1018:

* To the voltage inputs, you can attach various sensors (temperature, humidity, light, sound)
* To the digital inputs, you can attach various input devices (switches)
* To the digital outputs, you can attach simple indicators (LEDs, buzzers, relays)

The features and channels supported by each Phidget are many and varied, and we only include general concepts on this page. You can view the complete list of channels supported by a Phidget in the {{Phidget22API}}. Select a device at the top of the screen, select your preferred programming language, and then select which channel class you want to view the documentation for.

== Close a Channel ==

When you are finished with a channel, you should close and (in some languages) delete it. Once closed, the Phidget device channel the channel was matched to will be released and made available for another channel to match.

For example, in Java:

<syntaxhighlight lang=java>
device.close();
device = null;
</syntaxhighlight>

Or, in C:

<syntaxhighlight lang=c>
Phidget_close((PhidgetHandle)channel);
Phidget_release((PhidgetHandle *)&channel); // will NULL the pointer
</syntaxhighlight>

== Further Reading ==

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - How to know you are attaching to the Phidget you want.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Phidget Programming Basics

2017-07-12T18:45:26Z

Chad: /* Attaching a Channel */

[[Category:Programming]]
__TOC__

It is important to understand what a Phidget is, and how the hardware and software relate to one another before writing software using the {{Phidget22API}}. Please refer to [[What is a Phidget?]] for an introduction.

The Phidget software library matches a Phidget device channel with a software channel that is created by a user.
Software channels are each of a class, where that class defines a set of methods, properties, events and errors. Phidget devices are aware of the channel classes, and expose access to features of the device through the class interface.

To use a Phidget, you'll want to:
# '''[[#Creating a Channel|Create]]''' an instance of the channel class that provides access to the device you want to control.
# '''[[#Opening a Channel|Open]]''' the channel.
# Detect when the channel is '''[[#Attaching a Channel|attached]]''' to the Phidget.
# Use '''[[#Do Things with a Channel|methods and properties]]''' of the attached channel.
# '''[[#Close a Channel|Close]]''' the channel.

Small code snippets are provided for each step in the sections below. [[Language - Java|Java]] and [[Language - C/C++|C]] were selected because Java is a high-level language and C is a low level language. The best reference to the ''features'' each channel class is the {{Phidget22API}} for your specific language. This page is intended to be a high-level introduction.

== Creating a Channel ==

A Phidget device exposes one or more device channels where each channel is an interface to a feature of the hardware. A channel class defines an interface to control and query a channel of the Phidget device. For example, a 1018 - Phidget InterfaceKit device includes support
for digital input and digital out, and therefore exports <code>DigitalInput</code> and <code>DigitalOutput</code> channels.

Phidget devices are controlled by creating an instance of a Phidget channel class. Each channel class has a function that allows you to '''create''' an instance, and a function to later '''delete''' the instance.

For example, in Java:

<syntaxhighlight lang=java>
// Create a new Accelerometer channel
Accelerometer accel = new Accelerometer();
</syntaxhighlight>
<syntaxhighlight lang=java>
// Create a new RFID channel
RFID rfid = new RFID();
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
// Create a new Accelerometer channel
PhidgetAccelerometerHandle accel;
PhidgetAccelerometer_create(&accel);
</syntaxhighlight>
<syntaxhighlight lang=c>
// Create a new RFID channel
PhidgetRFIDHandle rfid;
PhidgetRFID_create(&rfid);
</syntaxhighlight>

A channel class will have properties and methods specific to the feature they belong to. For example, the <code>VoltageInput</code> class has a <code>Voltage</code> property that lets you access the current voltage measured by the device, the <code>Accelerometer</code> class has properties to set the sensitivity on each axis and the <code>RFID</code> has a method that writes to a writable RFID tag.

== Opening a Channel ==

After you have created a [[#Creating a Channel| channel instance]], you can call the <code>open()</code> method to begin the process of matching the channel to a Phidget device channel.

For example, with the <code>Accelerometer</code> channel in Java:

<syntaxhighlight lang=java>
accel.open();
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
Phidget_open((PhidgetHandle) accel);
</syntaxhighlight>

To see how to use <code>open()</code> in other languages, please refer to the {{Phidget22API}}.

The <code>open()</code> function begins the process of matching the channel handle you created to a channel of a Phidget device, and does not actually ''open'' the Phidget itself. An open channel may match a new Phidget device when it is plugged in if that channel has not already found a Phidget device channel that meets its criteria.

===Details for Open()===

Because <code>open()</code> simply enables the process of matching a channel to a Phidget device channel, <code>open()</code> returns immediately and does not wait for the channel to attach to a Phidget device channel. The channel changes state to ''open'', but is not necessarily ''attached''. Until the channel actually becomes ''attached'' to a Phidget device channel, most of the channel class interface will not be available.

As long as the channel is open (and not ''attached''), the system will continue to try to match it with a
Phidget device channel that has not already been matched with a channel. The channel can only be matched once, and the Phidget device channel can only be matched once. For example, if you connected a single Phidget Accelerometer to a computer, and you created and opened two <code>Accelerometer</code> channels, only one of the channels would attach while the other would remain ''open'' but not ''attached''. If the ''attached'' channel were to be closed, the other channel would then attach to the Accelerometer.

When the channels is matched with a Phidget device channel, the channel state is changed to ''attached'' and an event is fired.

'''Note:''' Once a Phidget device channel is matched to a channel, it will not be available to match another channel until the first channel is closed. The one exception is if the Phidget device channel is ''attached'' over the network through the [[Phidget Network Server]]. In that case, multiple channels are allowed to match and attach to the Phidget device channel. Some Phidgets, such as motor controllers will never match more than one channel at a time.

===Channel Matching===

<code>open()</code> can be used without specifying any matching properties. In this case the system will match a channel with the first Phidget device channel that matches the channel class. The channel class itself is an implied matching parameter.

If there is more than one Phidget connected to the computer that supports the channel class, the <code>DeviceSerialNumber</code> property must be set determine which Phidget will match.

If the Phidget connected to the computer has more than one channel of the same classes, the <code>Channel</code> property must be set to determine which Phidget device channel will match.

If the Phidget Network Server is enabled on the computer, the <code>IsRemote</code> and <code>IsLocal</code> properties can be used to determine if the channel will match the Phidget device channel or the network channel.

Please refer to the {{Phidget22API}}, and [[Best Phidgets Practices|Best Practices]] for more information on matching channels to Phidget device channels.

==== Opening a Channel on a USB Phidget ====

[[Image:channel-matching-1.jpg|link=|500px]]

In this example, a [{{SERVER}}/products.php?product_id=1018 1018 PhidgetInterfaceKit 8/8/8] is connected to a computer. A [{{SERVER}}/products.php?product_id=1108 1108 Magnetic Sensor] is connected to analog port 3 on the 1018. Here's how you would open the channel for the magnetic sensor in Java:

<syntaxhighlight lang=java>
VoltageRatioInput ch = new VoltageRatioInput();
ch.setDeviceSerialNumber(324781);
ch.setChannel(3);
ch.open();
</syntaxhighlight>

If you wanted to open digital input 5 in the same example, it would look like this:

<syntaxhighlight lang=java>
DigitalInput ch = new DigitalInput();
ch.setDeviceSerialNumber(324781);
ch.setChannel(5);
ch.open();
</syntaxhighlight>

==== Opening a VINT Hub Port as a Channel ====

The ports on a [[What is VINT?|VINT]] Hub can be opened as Digital Inputs, Digital Outputs, Voltage Inputs, or Voltage Ratio Inputs. Suppose you had a [{{SERVER}}/products.php?product_id=HUB0000 HUB0000 VINT Hub] with a [{{SERVER}}/products.php?product_id=1133 1133 Sound Sensor] connected to its sixth port.

[[Image:channel-matching-2.jpg|link=|500px]]

Here's how you would open it in Java:

<syntaxhighlight lang=java>
VoltageInput ch = new VoltageInput();
ch.setDeviceSerialNumber(370181);
ch.setIsHubPortDevice(true);
ch.setHubPort(6);
ch.open();
</syntaxhighlight>

==== Opening a Channel on a VINT Device ====

In this example, we have a [{{SERVER}}/products.php?product_id=TMP1101 TMP1101 4x Thermocouple Phidget] and a [{{SERVER}}/products.php?product_id=HUB0000 HUB0000 VINT Hub].

[[Image:channel-matching-3.jpg|link=|500px]]

If we wanted to open both the thermocouple connected to port 0 and the integrated temperature sensor on the board, we first need to figure out which channels those are. Go to the [{{SERVER}}/products.php?product_id=TMP1101 product page for the TMP1101] and click on the API tab. From the table at the top of the tab, we can see that the integrated temperature sensor is TemperatureSensor channel 4. In Java, opening these channels would look like this:

<syntaxhighlight lang=java>
TemperatureSensor tc = new TemperatureSensor(); // Handle for the thermocouple
TemperatureSensor ic = new TemperatureSensor(); // Handle for the integrated temperature chip

tc.setDeviceSerialNumber();
ic.setDeviceSerialNumber();
tc.setHubPort(2);
ic.setHubPort(2);
tc.setChannel(0);
ic.setChannel(4);

tc.open();
ic.open();
</syntaxhighlight>

==== Opening a Channel on a Remote Phidget ====

Suppose you wanted to open a locally connected Phidget remotely over the Network Service, so that you could have multiple programs connecting to it at the same time. In this example, we have a [{{SERVER}}/products.php?product_id=1024 1024 PhidgetRFID] connected to a computer that has the Phidget Network Server enabled.

[[Image:channel-matching-4.jpg|link=|600px]]

You could open the RFID reader channel remotely with the following code in Java:

<syntaxhighlight lang=java>
RFID ch = new RFID();
ch.setDeviceSerialNumber(388624);
ch.setIsRemote(true);
ch.open();
</syntaxhighlight>

== Attaching a Channel ==

When a channel is open (and not ''attached''), the system will continue to try to match it with a
Phidget device channel until either a match is found, or the channel is closed. When the channels is matched with a Phidget device channel, the channel state is changed to ''attached'' and an event is fired.

An event handler can be registered to catch the ''attach event'' through the channel's <code>Attach</code> event. Each channel also has a <code>Attached</code> property that can be read to determine if the class has
been matched to a Phidget device channel.

To set an event handler to detect the attach in Java:

<syntaxhighlight lang=java>
//create a Phidget accelerometer channel:
Accelerometer accel = new Accelerometer();
accel.addAttachListener((AttachEvent ae) -> {
Accelerometer accel = (Accelerometer) ae.getSource();
// Do things after attachment (i.e. read data, control the device)
}
});
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
// Define the attach handler function
void CCONV
onAttachedEventHandler(PhidgetHandle channel, void *userPtr) {
printf("A channel has been attached\n");
// Do things after attachment (i.e. read data, control the device)
}

int
main(int argc, char **argv) {
// .....Then, in the main code create the channel and set the attach handler:
PhidgetAccelerometerHandle accel;
PhidgetAccelerometer_create(&accel);
Phidget_setOnAttachHandler((PhidgetHandle)accel, onAttachedEventHandler, NULL);

// other stuff in main
}
</syntaxhighlight>

The attach event handler should be set '''before''' the channel is opened; otherwise, the attach event could occur before the handler is set.

== Do Things with a Channel ==

After a channel has been ''opened'' and ''attached'', software can control the Phidget device via the channel class interface.

Like setting an event handler that executes [[#Attaching a Channel|when the channels is attached]], handlers can be set to receive events when a state change occurs, or sensor data is received.

A Voltage Input channel for example, like one supported by the [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit], can set an event handler that gets called as the voltage is processed.

In Java, this would look like:

<syntaxhighlight lang=java>
// After creating and opening a VoltageInput channel called "sensorIn"
sensorIn.addVoltageChangeListener((VoltageInputVoltageChangeEvent de) -> {
System.out.println("Voltage: " + de.getVoltage());
});
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
void CCONV
onVoltageChangeHandler(PhidgetVoltageInputHandle voltageInput, void *ctx, double voltage) {
printf("Voltage: %lf V\n", voltage);
}

// .....Then, in the main code:
// After creating and opening a VoltageInput channel called "sensorIn"
PhidgetVoltageInput_setOnVoltageChangeHandler(sensorIn, onVoltageChangeHandler, NULL);
</syntaxhighlight>

The voltage value delivered in the above snippets could also be accessed via the <code>Voltage</code> property of the channel. Properties that have related events are automatically updated each time the event is received by the channel, and calls between events always return the value set by the last event.

<syntaxhighlight lang=java>
double val = sensorIn.getVoltage();
</syntaxhighlight>

Or, in C:

<syntaxhighlight lang=c>
double val;
PhidgetVoltageInput_getVoltage(sensorIn, &val);
</syntaxhighlight>

===Sensors, Input, and Output===

Often, your Phidget will support more than one channel class. For example a [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit] has voltage inputs (black sensor ports), digital inputs and digital outputs (green terminal blocks). You can determine the channel classes supported by your Phidget from the product page and the {{Phidget22API}}.

For InterfaceKits like the 1018:

* To the voltage inputs, you can attach various sensors (temperature, humidity, light, sound)
* To the digital inputs, you can attach various input devices (switches)
* To the digital outputs, you can attach simple indicators (LEDs, buzzers, relays)

The features and channels supported by each Phidget are many and varied, and we only include general concepts on this page. You can view the complete list of channels supported by a Phidget in the {{Phidget22API}}. Select a device at the top of the screen, select your preferred programming language, and then select which channel class you want to view the documentation for.

== Close a Channel ==

When you are finished with a channel, you should close and (in some languages) delete it. Once closed, the Phidget device channel the channel was matched to will be released and made available for another channel to match.

For example, in Java:

<syntaxhighlight lang=java>
device.close();
device = null;
</syntaxhighlight>

Or, in C:

<syntaxhighlight lang=c>
Phidget_close((PhidgetHandle)channel);
Phidget_release((PhidgetHandle)&channel); // will NULL the pointer
</syntaxhighlight>

== Further Reading ==

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - How to know you are attaching to the Phidget you want.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Phidget Programming Basics

2017-07-12T18:42:44Z

Chad: /* Attaching a Channel */

[[Category:Programming]]
__TOC__

It is important to understand what a Phidget is, and how the hardware and software relate to one another before writing software using the {{Phidget22API}}. Please refer to [[What is a Phidget?]] for an introduction.

The Phidget software library matches a Phidget device channel with a software channel that is created by a user.
Software channels are each of a class, where that class defines a set of methods, properties, events and errors. Phidget devices are aware of the channel classes, and expose access to features of the device through the class interface.

To use a Phidget, you'll want to:
# '''[[#Creating a Channel|Create]]''' an instance of the channel class that provides access to the device you want to control.
# '''[[#Opening a Channel|Open]]''' the channel.
# Detect when the channel is '''[[#Attaching a Channel|attached]]''' to the Phidget.
# Use '''[[#Do Things with a Channel|methods and properties]]''' of the attached channel.
# '''[[#Close a Channel|Close]]''' the channel.

Small code snippets are provided for each step in the sections below. [[Language - Java|Java]] and [[Language - C/C++|C]] were selected because Java is a high-level language and C is a low level language. The best reference to the ''features'' each channel class is the {{Phidget22API}} for your specific language. This page is intended to be a high-level introduction.

== Creating a Channel ==

A Phidget device exposes one or more device channels where each channel is an interface to a feature of the hardware. A channel class defines an interface to control and query a channel of the Phidget device. For example, a 1018 - Phidget InterfaceKit device includes support
for digital input and digital out, and therefore exports <code>DigitalInput</code> and <code>DigitalOutput</code> channels.

Phidget devices are controlled by creating an instance of a Phidget channel class. Each channel class has a function that allows you to '''create''' an instance, and a function to later '''delete''' the instance.

For example, in Java:

<syntaxhighlight lang=java>
// Create a new Accelerometer channel
Accelerometer accel = new Accelerometer();
</syntaxhighlight>
<syntaxhighlight lang=java>
// Create a new RFID channel
RFID rfid = new RFID();
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
// Create a new Accelerometer channel
PhidgetAccelerometerHandle accel;
PhidgetAccelerometer_create(&accel);
</syntaxhighlight>
<syntaxhighlight lang=c>
// Create a new RFID channel
PhidgetRFIDHandle rfid;
PhidgetRFID_create(&rfid);
</syntaxhighlight>

A channel class will have properties and methods specific to the feature they belong to. For example, the <code>VoltageInput</code> class has a <code>Voltage</code> property that lets you access the current voltage measured by the device, the <code>Accelerometer</code> class has properties to set the sensitivity on each axis and the <code>RFID</code> has a method that writes to a writable RFID tag.

== Opening a Channel ==

After you have created a [[#Creating a Channel| channel instance]], you can call the <code>open()</code> method to begin the process of matching the channel to a Phidget device channel.

For example, with the <code>Accelerometer</code> channel in Java:

<syntaxhighlight lang=java>
accel.open();
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
Phidget_open((PhidgetHandle) accel);
</syntaxhighlight>

To see how to use <code>open()</code> in other languages, please refer to the {{Phidget22API}}.

The <code>open()</code> function begins the process of matching the channel handle you created to a channel of a Phidget device, and does not actually ''open'' the Phidget itself. An open channel may match a new Phidget device when it is plugged in if that channel has not already found a Phidget device channel that meets its criteria.

===Details for Open()===

Because <code>open()</code> simply enables the process of matching a channel to a Phidget device channel, <code>open()</code> returns immediately and does not wait for the channel to attach to a Phidget device channel. The channel changes state to ''open'', but is not necessarily ''attached''. Until the channel actually becomes ''attached'' to a Phidget device channel, most of the channel class interface will not be available.

As long as the channel is open (and not ''attached''), the system will continue to try to match it with a
Phidget device channel that has not already been matched with a channel. The channel can only be matched once, and the Phidget device channel can only be matched once. For example, if you connected a single Phidget Accelerometer to a computer, and you created and opened two <code>Accelerometer</code> channels, only one of the channels would attach while the other would remain ''open'' but not ''attached''. If the ''attached'' channel were to be closed, the other channel would then attach to the Accelerometer.

When the channels is matched with a Phidget device channel, the channel state is changed to ''attached'' and an event is fired.

'''Note:''' Once a Phidget device channel is matched to a channel, it will not be available to match another channel until the first channel is closed. The one exception is if the Phidget device channel is ''attached'' over the network through the [[Phidget Network Server]]. In that case, multiple channels are allowed to match and attach to the Phidget device channel. Some Phidgets, such as motor controllers will never match more than one channel at a time.

===Channel Matching===

<code>open()</code> can be used without specifying any matching properties. In this case the system will match a channel with the first Phidget device channel that matches the channel class. The channel class itself is an implied matching parameter.

If there is more than one Phidget connected to the computer that supports the channel class, the <code>DeviceSerialNumber</code> property must be set determine which Phidget will match.

If the Phidget connected to the computer has more than one channel of the same classes, the <code>Channel</code> property must be set to determine which Phidget device channel will match.

If the Phidget Network Server is enabled on the computer, the <code>IsRemote</code> and <code>IsLocal</code> properties can be used to determine if the channel will match the Phidget device channel or the network channel.

Please refer to the {{Phidget22API}}, and [[Best Phidgets Practices|Best Practices]] for more information on matching channels to Phidget device channels.

==== Opening a Channel on a USB Phidget ====

[[Image:channel-matching-1.jpg|link=|500px]]

In this example, a [{{SERVER}}/products.php?product_id=1018 1018 PhidgetInterfaceKit 8/8/8] is connected to a computer. A [{{SERVER}}/products.php?product_id=1108 1108 Magnetic Sensor] is connected to analog port 3 on the 1018. Here's how you would open the channel for the magnetic sensor in Java:

<syntaxhighlight lang=java>
VoltageRatioInput ch = new VoltageRatioInput();
ch.setDeviceSerialNumber(324781);
ch.setChannel(3);
ch.open();
</syntaxhighlight>

If you wanted to open digital input 5 in the same example, it would look like this:

<syntaxhighlight lang=java>
DigitalInput ch = new DigitalInput();
ch.setDeviceSerialNumber(324781);
ch.setChannel(5);
ch.open();
</syntaxhighlight>

==== Opening a VINT Hub Port as a Channel ====

The ports on a [[What is VINT?|VINT]] Hub can be opened as Digital Inputs, Digital Outputs, Voltage Inputs, or Voltage Ratio Inputs. Suppose you had a [{{SERVER}}/products.php?product_id=HUB0000 HUB0000 VINT Hub] with a [{{SERVER}}/products.php?product_id=1133 1133 Sound Sensor] connected to its sixth port.

[[Image:channel-matching-2.jpg|link=|500px]]

Here's how you would open it in Java:

<syntaxhighlight lang=java>
VoltageInput ch = new VoltageInput();
ch.setDeviceSerialNumber(370181);
ch.setIsHubPortDevice(true);
ch.setHubPort(6);
ch.open();
</syntaxhighlight>

==== Opening a Channel on a VINT Device ====

In this example, we have a [{{SERVER}}/products.php?product_id=TMP1101 TMP1101 4x Thermocouple Phidget] and a [{{SERVER}}/products.php?product_id=HUB0000 HUB0000 VINT Hub].

[[Image:channel-matching-3.jpg|link=|500px]]

If we wanted to open both the thermocouple connected to port 0 and the integrated temperature sensor on the board, we first need to figure out which channels those are. Go to the [{{SERVER}}/products.php?product_id=TMP1101 product page for the TMP1101] and click on the API tab. From the table at the top of the tab, we can see that the integrated temperature sensor is TemperatureSensor channel 4. In Java, opening these channels would look like this:

<syntaxhighlight lang=java>
TemperatureSensor tc = new TemperatureSensor(); // Handle for the thermocouple
TemperatureSensor ic = new TemperatureSensor(); // Handle for the integrated temperature chip

tc.setDeviceSerialNumber();
ic.setDeviceSerialNumber();
tc.setHubPort(2);
ic.setHubPort(2);
tc.setChannel(0);
ic.setChannel(4);

tc.open();
ic.open();
</syntaxhighlight>

==== Opening a Channel on a Remote Phidget ====

Suppose you wanted to open a locally connected Phidget remotely over the Network Service, so that you could have multiple programs connecting to it at the same time. In this example, we have a [{{SERVER}}/products.php?product_id=1024 1024 PhidgetRFID] connected to a computer that has the Phidget Network Server enabled.

[[Image:channel-matching-4.jpg|link=|600px]]

You could open the RFID reader channel remotely with the following code in Java:

<syntaxhighlight lang=java>
RFID ch = new RFID();
ch.setDeviceSerialNumber(388624);
ch.setIsRemote(true);
ch.open();
</syntaxhighlight>

== Attaching a Channel ==

When a channel is open (and not ''attached''), the system will continue to try to match it with a
Phidget device channel until either a match is found, or the channel is closed. When the channels is matched with a Phidget device channel, the channel state is changed to ''attached'' and an event is fired.

An event handler can be registered to catch the ''attach event'' through the channel's <code>Attach</code> event. Each channel also has a <code>Attached</code> property that can be read to determine if the class has
been matched to a Phidget device channel.

To set an event handler to detect the attach in Java:

<syntaxhighlight lang=java>
//create a Phidget accelerometer channel:
Accelerometer accel = new Accelerometer();
accel.addAttachListener((AttachEvent ae) -> {
Accelerometer accel = (Accelerometer) ae.getSource();
// Do things after attachment (i.e. read data, control the device)
}
});
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
// Define the attach handler function
void CCONV
onAttachedEventHandler(PhidgetHandle channel, void *userPtr) {
printf("A channel has been attached\n");
// Do things after attachment (i.e. read data, control the device)
}

int
main(int argc, char **argv) {
// .....Then, in the main code create the channel and set the attach handler:
PhidgetAccelerometerHandle accel;
PhidgetAccelerometer_create(&accel);
Phidget_setOnAttachHandler((PhidgetHandle)accel, onAttachedEventHandler, NULL);

// other stuff in main
}
</syntaxhighlight>

You should set the attach event handler '''before''' you <code>open()</code> the channel; otherwise, you may miss attach event if it occurs between opening the channel and setting the handler.

== Do Things with a Channel ==

After a channel has been ''opened'' and ''attached'', software can control the Phidget device via the channel class interface.

Like setting an event handler that executes [[#Attaching a Channel|when the channels is attached]], handlers can be set to receive events when a state change occurs, or sensor data is received.

A Voltage Input channel for example, like one supported by the [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit], can set an event handler that gets called as the voltage is processed.

In Java, this would look like:

<syntaxhighlight lang=java>
// After creating and opening a VoltageInput channel called "sensorIn"
sensorIn.addVoltageChangeListener((VoltageInputVoltageChangeEvent de) -> {
System.out.println("Voltage: " + de.getVoltage());
});
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
void CCONV
onVoltageChangeHandler(PhidgetVoltageInputHandle voltageInput, void *ctx, double voltage) {
printf("Voltage: %lf V\n", voltage);
}

// .....Then, in the main code:
// After creating and opening a VoltageInput channel called "sensorIn"
PhidgetVoltageInput_setOnVoltageChangeHandler(sensorIn, onVoltageChangeHandler, NULL);
</syntaxhighlight>

The voltage value delivered in the above snippets could also be accessed via the <code>Voltage</code> property of the channel. Properties that have related events are automatically updated each time the event is received by the channel, and calls between events always return the value set by the last event.

<syntaxhighlight lang=java>
double val = sensorIn.getVoltage();
</syntaxhighlight>

Or, in C:

<syntaxhighlight lang=c>
double val;
PhidgetVoltageInput_getVoltage(sensorIn, &val);
</syntaxhighlight>

===Sensors, Input, and Output===

Often, your Phidget will support more than one channel class. For example a [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit] has voltage inputs (black sensor ports), digital inputs and digital outputs (green terminal blocks). You can determine the channel classes supported by your Phidget from the product page and the {{Phidget22API}}.

For InterfaceKits like the 1018:

* To the voltage inputs, you can attach various sensors (temperature, humidity, light, sound)
* To the digital inputs, you can attach various input devices (switches)
* To the digital outputs, you can attach simple indicators (LEDs, buzzers, relays)

The features and channels supported by each Phidget are many and varied, and we only include general concepts on this page. You can view the complete list of channels supported by a Phidget in the {{Phidget22API}}. Select a device at the top of the screen, select your preferred programming language, and then select which channel class you want to view the documentation for.

== Close a Channel ==

When you are finished with a channel, you should close and (in some languages) delete it. Once closed, the Phidget device channel the channel was matched to will be released and made available for another channel to match.

For example, in Java:

<syntaxhighlight lang=java>
device.close();
device = null;
</syntaxhighlight>

Or, in C:

<syntaxhighlight lang=c>
Phidget_close((PhidgetHandle)channel);
Phidget_release((PhidgetHandle)&channel); // will NULL the pointer
</syntaxhighlight>

== Further Reading ==

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - How to know you are attaching to the Phidget you want.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Polling vs. Events

2017-07-12T16:38:11Z

Chad:

[[Category:Programming]]

The Phidget library operates asynchronously. The library fires attach and detach events when a device channel appears and disappears (plugged in or unplugged). After a user channel is attached, data and status updates from the device channel begin being delivered. These events cause the library to update properties of the user channel, and to call any event handlers set by the program.

===Discussion===

====Attach====
Once a channel is opened, the Phidget library begins attempting to match the channel to a device channel. While the channel is not '''attached''', the {{Code|Attached}} property of the channel will be '''false'''. As soon as the Phidget library matches the channel with a device channel the {{Code|Attached}} property is updated to be '''true'''. A program could poll the {{Code|Attached}} property to determine when the channel becomes '''attached''', or set an attach handler to be notified asynchronously.

====Detach====
While a channel is '''open''' and '''attached''', the device channel could disappear for some reason (could be unplugged). As a result, the Phidget library would '''detach''' the user channel, and update the {{Code|Attached}} property to be '''false'''. A program could poll the {{Code|Attached}} property to detect when the channel becomes '''dettached''', or set a detach handler to be notified asynchronously.

====Data====
While a channel is '''open''' and '''attached''', data and status updates received by the Phidget library are delivered to the channel. A program could poll data and status properties (for example, {{Code|Acceleration}}, {{Code|Temperature}}, and {{Code|State}}), or set handlers that would be called when the data or state changes.

===Recommendations===
Generally, setting event handlers is preferred and the most flexible. The code required to poll for attach and detach states, and to detect data and state changes can be complicated and error prone. Event handlers are simple and work in a very predicable manor.

A simple program that only wants to read a small amount of data from a device could simply open a channel and wait for attachment, read a data or state property, and then close the channel. In that case, the code to implement and set event handlers might not be worth the effort. Error checking however becomes very important, as accessing some channel properties while the channel is '''detached''' will result in an error or exception that could kill the program. There will always be a race between checking the {{Code|Attached}} property and accessing a data or state property.

All but the most simple program should set handlers that will be called when a channel attaches or detaches, and when the channel receives data or changes state. The channel will only receive change events while '''attached''', and no external calls are required to access the changed data, which eliminates a chance for error. In addition, change triggers and data interval settings will not get reset accidentally if they are always set from within an attach handler, eliminating another common mistake.

When in doubt, use event handlers.

=== Further Reading ===

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Logging, Exceptions, and Errors

2017-07-11T21:01:02Z

Chad: /* Error Codes */

[[Category:Programming]]
You've written your code, fixed the compiler errors, and yet, the program still isn't behaving as intended. The tools described on this page will help you further debug your program and figure out where in the code things are going wrong.

==Logging==

The {{Phidget22API}} supports a general logging API that supports log levels, named sources of logs, and the writing of logs to a file or to a Phidget Network Server. The Phidget software library uses this logging system internally, so in addition to being able to log within your own software, information about what the Phidget software is doing is also available. Refer to the ''Logging API'' in the {{Phidget22API}} for language specific information.

To begin, logging must be enabled

<syntaxhighlight lang=c>
PhidgetLog_enable(PHIDGET_LOG_DEBUG, NULL);
</syntaxhighlight>

Or in Java:

<syntaxhighlight lang=java>
Log.enable(LogLevel.DEBUG, null);
</syntaxhighlight>

When <code>NULL</code> is passed to <code>enable()</code> in the above examples, the logging system will output to <code>STDERR</code>.

There are five different logging levels, ranging from "Give me Everything!" to "Tell me only about critical problems".

'''CRITICAL'''
:Critical error messages.
:Errors at this level are generally non-recoverable and indicate either hardware problems, library bugs, or other serious issues.

'''ERROR'''
:Non-critical error messages.
:Errors at this level are generally automatically recoverable, but may help to track down issues.

'''WARNING'''
:Warning messages.
:Warnings are used to log behavior that is not necessarily in error, but is nevertheless odd or unexpected.

'''INFO'''
:Informational messages.
:Informational messages communicate useful operations and states changes within the software

'''VERBOSE'''
:Verbose messages.
:Verbose messages are informational messages that are expected to happen so frequently that they tend to drown out other log messages.

These are available in the '''Enumerations''' section of Logging API in the {{Phidget22API}} documentation.

=== Logging in Your Program ===

Logging is performed using the <code>log()</code> method from the Logging API.

For example, in C:

<syntaxhighlight lang=c>
PhidgetLog_log(PHIDGET_LOG_INFO, "Something happened in loop iteration %d!", i);
</syntaxhighlight>

Or in Java:

<syntaxhighlight lang=java>
Log.log(LogLevel.INFO, "Something happened in loop iteration " + i + "!");
</syntaxhighlight>

The logging API supports the concept of a ''log source'', were the ''log source'' is a textual identifier of where the log message originated. The ''log source'' is output to log the log file along with the log message to help organize the data.

The following examples define and create a log source, and then write a log message using that source.

<syntaxhighlight lang=c>
#define MYSOURCE "mysource"
PhidgetLog_addSource(MYSOURCE, PHIDGET_LOG_INFO);
PhidgetLog_log(__FILE__, __LINE__, __func__, MYSOURCE, PHIDGET_LOG_INFO, "Something happened");
</syntaxhighlight>

Or in Java:

<syntaxhighlight lang=java>
public static final String MYSOURCE = "mysource";
Log.addSource(MYSOURCE, LogLevel.INFO);
Log.log(LogLevel.INFO, MYSOURCE, "Something happened);
</syntaxhighlight>

==Exceptions and Errors==

There are two different types of errors that you can use to determine where a problem exists in your program.

===Error Generated By Methods===

When an error occurs during a method invocation, either a language specific exception is thrown, or an error is returned. It is important to check the return value from each method call, and to catch and handle exceptions.

For example, in C:

<syntaxhighlight lang=c>
int
main(int argc, char **argv) {
PhidgetReturnCode res;

res = PhidgetLog_enable(PHIDGET_LOG_ERROR, NULL);
if (res != EPHIDGET_OK) {
fprintf(stderr, "failed to enable Phidget logging: %d\n", res);
exit(1);
}
exit(0);
}
</syntaxhighlight>

Or in Java:

<syntaxhighlight lang=java>
try {
Log.enable(LogLevel.INFO, null);
} catch (PhidgetException ex) {
System.out.println("Failed to enable Phidget logging: " + ex.getMessage());
}
</syntaxhighlight>

The consequence of not handling errors correctly ranges from the program crashing if an unhandled exception occurs to improper behavior. Program should check for errors on each method call, and handle any errors.

====Error Codes====

A list of error codes can be found in the {{Phidget22API}}. Refer to language specific exceptions in languages that support them.

===Error Events===

Error events are asynchronously generated by Phidget devices, and the Phidget library isself, during runtime. A Phidget device might experience an excessive value (temperature, voltage, acceleration etc.), and trigger an error event to inform the program that is attached. This would not necessarily be due to any operation the program performed; instead, the operating environment of the Phidget device would likely be the cause. Error events are also fired when network errors occur, or the library is unable to handle incoming change events quickly enough (event handlers could be too slow).

Error events are handled by setting an error event handler.

In C:

<syntaxhighlight lang=c>
void CCONV
errorEventHandler(PhidgetHandle ch, void *ctx, Phidget_ErrorEventCode code,
const char *errorDescription) {
Phidget_log(PHIDGET_LOG_ERROR, "Error Event [%d] %s", code, errorDescription);
}

// set the error event handler before opening the channel
res = Phidget_setOnErrorHandler((PhidgetHandle) ch, errorEventHandler, NULL);
if (res != EPHIDGET_OK) {
Phidget_log(PHIDGET_LOG_ERROR, "Failed to set error handler for %P", ch);
// XXX handle the error
}
</syntaxhighlight>

In Java:

<syntaxhighlight lang=java>
ch.addErrorListener((ErrorEvent ee) -> {
System.err.println("Error: " + ee.getDescription());
});
</syntaxhighlight>

====Error Codes====

These codes are passed to an error event handler. See the {{Phidget22API}} documentation for your device to see which error event codes are supported. The error event codes are generic, and the error description passed to the error event handler may contain more detailed information about the actual cause of the error event.

'''BADVERSION'''
:Version Mismatch Error. Usually means client and server library versions are out of sync. Update to the latest version of the Phidget software.

'''BUSY'''
:The Phidget device channel has already been locally attached. Only one channel may attach locally to a device channel.

'''NETWORK'''
:An error occurred with the network communications. See the error description for more details.

'''DISPATCH'''
:An error occurred when trying to dispatch an event. It's possible that the data rate is too fast for the computer (or network) and the event queue has filled up.

'''OK'''
: An error state has ended. You can use the <code>getDescription</code> method of the error event to get more information.

'''OVERRUN'''
:Sampling overrun. Some samples were lost in firmware because the queue filled up. This error is exclusive to Phidget InterfaceKits.

'''PACKETLOST'''
:Packet(s) were lost. This error is often an indication that your event handlers are not executing fast enough. Try to remove slow processes like GUI updates or user input from your handlers.

'''WRAP'''
:A variable has wrapped. For example, the encoder position can wrap from 2,147,483,647 to -2,147,483,648 because of an integer overflow.

'''OVERTEMP'''
:Over-Temperature condition detected. See error description for more details.

'''OVERCURRENT'''
:Over-Current condition detected. See error description for more details.

'''OUTOFRANGE'''
:Out of range condition detected. Usually an input on the board is reporting a value that is outside of the allowed range.

'''BADPOWER'''
:Power supply problem detected. Either the power supply is being overloaded, or it is under-powered (possibly not plugged in).

'''SATURATION'''
:A sensor's value has reached the maximum or minimum of its sensing range. For example, a 1000 lux light sensor will throw this error event when a value greater than 1000 lux is detected. The sensor will still be reporting 1000 lux, but this error tells you that you don't know for certain how much higher than 1000 the real reading is.

'''OVERVOLTAGE'''
:Over-Voltage condition detected. Occurs in power-providing Phidgets when the output voltage exceeds the set value.

'''VOLTAGEERROR'''
:A voltage error occurs when a Phidget that provides a voltage output has the value drop below what what specified. This can happen if the device being powered draws too much current, which causes a voltage drop. Stay within output current specifications to avoid voltage errors.

'''ENERGYDUMP'''
:An energy dump occurs when a power-providing Phidget needs to dissipate its extra energy. See the [[:Category:UserGuide|User Guide]] for your device for more information.

== Other Problems ==

If your Phidget is still not behaving as expected after handling errors and exceptions, have a look at our [[General Troubleshooting]] guide to track down the problem.

== Further Reading ==

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Logging, Exceptions, and Errors

2017-07-11T20:58:38Z

Chad: /* Error Generated From The Device */

[[Category:Programming]]
You've written your code, fixed the compiler errors, and yet, the program still isn't behaving as intended. The tools described on this page will help you further debug your program and figure out where in the code things are going wrong.

==Logging==

The {{Phidget22API}} supports a general logging API that supports log levels, named sources of logs, and the writing of logs to a file or to a Phidget Network Server. The Phidget software library uses this logging system internally, so in addition to being able to log within your own software, information about what the Phidget software is doing is also available. Refer to the ''Logging API'' in the {{Phidget22API}} for language specific information.

To begin, logging must be enabled

<syntaxhighlight lang=c>
PhidgetLog_enable(PHIDGET_LOG_DEBUG, NULL);
</syntaxhighlight>

Or in Java:

<syntaxhighlight lang=java>
Log.enable(LogLevel.DEBUG, null);
</syntaxhighlight>

When <code>NULL</code> is passed to <code>enable()</code> in the above examples, the logging system will output to <code>STDERR</code>.

There are five different logging levels, ranging from "Give me Everything!" to "Tell me only about critical problems".

'''CRITICAL'''
:Critical error messages.
:Errors at this level are generally non-recoverable and indicate either hardware problems, library bugs, or other serious issues.

'''ERROR'''
:Non-critical error messages.
:Errors at this level are generally automatically recoverable, but may help to track down issues.

'''WARNING'''
:Warning messages.
:Warnings are used to log behavior that is not necessarily in error, but is nevertheless odd or unexpected.

'''INFO'''
:Informational messages.
:Informational messages communicate useful operations and states changes within the software

'''VERBOSE'''
:Verbose messages.
:Verbose messages are informational messages that are expected to happen so frequently that they tend to drown out other log messages.

These are available in the '''Enumerations''' section of Logging API in the {{Phidget22API}} documentation.

=== Logging in Your Program ===

Logging is performed using the <code>log()</code> method from the Logging API.

For example, in C:

<syntaxhighlight lang=c>
PhidgetLog_log(PHIDGET_LOG_INFO, "Something happened in loop iteration %d!", i);
</syntaxhighlight>

Or in Java:

<syntaxhighlight lang=java>
Log.log(LogLevel.INFO, "Something happened in loop iteration " + i + "!");
</syntaxhighlight>

The logging API supports the concept of a ''log source'', were the ''log source'' is a textual identifier of where the log message originated. The ''log source'' is output to log the log file along with the log message to help organize the data.

The following examples define and create a log source, and then write a log message using that source.

<syntaxhighlight lang=c>
#define MYSOURCE "mysource"
PhidgetLog_addSource(MYSOURCE, PHIDGET_LOG_INFO);
PhidgetLog_log(__FILE__, __LINE__, __func__, MYSOURCE, PHIDGET_LOG_INFO, "Something happened");
</syntaxhighlight>

Or in Java:

<syntaxhighlight lang=java>
public static final String MYSOURCE = "mysource";
Log.addSource(MYSOURCE, LogLevel.INFO);
Log.log(LogLevel.INFO, MYSOURCE, "Something happened);
</syntaxhighlight>

==Exceptions and Errors==

There are two different types of errors that you can use to determine where a problem exists in your program.

===Error Generated By Methods===

When an error occurs during a method invocation, either a language specific exception is thrown, or an error is returned. It is important to check the return value from each method call, and to catch and handle exceptions.

For example, in C:

<syntaxhighlight lang=c>
int
main(int argc, char **argv) {
PhidgetReturnCode res;

res = PhidgetLog_enable(PHIDGET_LOG_ERROR, NULL);
if (res != EPHIDGET_OK) {
fprintf(stderr, "failed to enable Phidget logging: %d\n", res);
exit(1);
}
exit(0);
}
</syntaxhighlight>

Or in Java:

<syntaxhighlight lang=java>
try {
Log.enable(LogLevel.INFO, null);
} catch (PhidgetException ex) {
System.out.println("Failed to enable Phidget logging: " + ex.getMessage());
}
</syntaxhighlight>

The consequence of not handling errors correctly ranges from the program crashing if an unhandled exception occurs to improper behavior. Program should check for errors on each method call, and handle any errors.

====Error Codes====

A list of error codes can be found in the {{Phidget22API}}. Refer to language specific exceptions in language that support them.

===Error Events===

Error events are asynchronously generated by Phidget devices, and the Phidget library isself, during runtime. A Phidget device might experience an excessive value (temperature, voltage, acceleration etc.), and trigger an error event to inform the program that is attached. This would not necessarily be due to any operation the program performed; instead, the operating environment of the Phidget device would likely be the cause. Error events are also fired when network errors occur, or the library is unable to handle incoming change events quickly enough (event handlers could be too slow).

Error events are handled by setting an error event handler.

In C:

<syntaxhighlight lang=c>
void CCONV
errorEventHandler(PhidgetHandle ch, void *ctx, Phidget_ErrorEventCode code,
const char *errorDescription) {
Phidget_log(PHIDGET_LOG_ERROR, "Error Event [%d] %s", code, errorDescription);
}

// set the error event handler before opening the channel
res = Phidget_setOnErrorHandler((PhidgetHandle) ch, errorEventHandler, NULL);
if (res != EPHIDGET_OK) {
Phidget_log(PHIDGET_LOG_ERROR, "Failed to set error handler for %P", ch);
// XXX handle the error
}
</syntaxhighlight>

In Java:

<syntaxhighlight lang=java>
ch.addErrorListener((ErrorEvent ee) -> {
System.err.println("Error: " + ee.getDescription());
});
</syntaxhighlight>

====Error Codes====

These codes are passed to an error event handler. See the {{Phidget22API}} documentation for your device to see which error event codes are supported. The error event codes are generic, and the error description passed to the error event handler may contain more detailed information about the actual cause of the error event.

'''BADVERSION'''
:Version Mismatch Error. Usually means client and server library versions are out of sync. Update to the latest version of the Phidget software.

'''BUSY'''
:The Phidget device channel has already been locally attached. Only one channel may attach locally to a device channel.

'''NETWORK'''
:An error occurred with the network communications. See the error description for more details.

'''DISPATCH'''
:An error occurred when trying to dispatch an event. It's possible that the data rate is too fast for the computer (or network) and the event queue has filled up.

'''OK'''
: An error state has ended. You can use the <code>getDescription</code> method of the error event to get more information.

'''OVERRUN'''
:Sampling overrun. Some samples were lost in firmware because the queue filled up. This error is exclusive to Phidget InterfaceKits.

'''PACKETLOST'''
:Packet(s) were lost. This error is often an indication that your event handlers are not executing fast enough. Try to remove slow processes like GUI updates or user input from your handlers.

'''WRAP'''
:A variable has wrapped. For example, the encoder position can wrap from 2,147,483,647 to -2,147,483,648 because of an integer overflow.

'''OVERTEMP'''
:Over-Temperature condition detected. See error description for more details.

'''OVERCURRENT'''
:Over-Current condition detected. See error description for more details.

'''OUTOFRANGE'''
:Out of range condition detected. Usually an input on the board is reporting a value that is outside of the allowed range.

'''BADPOWER'''
:Power supply problem detected. Either the power supply is being overloaded, or it is under-powered (possibly not plugged in).

'''SATURATION'''
:A sensor's value has reached the maximum or minimum of its sensing range. For example, a 1000 lux light sensor will throw this error event when a value greater than 1000 lux is detected. The sensor will still be reporting 1000 lux, but this error tells you that you don't know for certain how much higher than 1000 the real reading is.

'''OVERVOLTAGE'''
:Over-Voltage condition detected. Occurs in power-providing Phidgets when the output voltage exceeds the set value.

'''VOLTAGEERROR'''
:A voltage error occurs when a Phidget that provides a voltage output has the value drop below what what specified. This can happen if the device being powered draws too much current, which causes a voltage drop. Stay within output current specifications to avoid voltage errors.

'''ENERGYDUMP'''
:An energy dump occurs when a power-providing Phidget needs to dissipate its extra energy. See the [[:Category:UserGuide|User Guide]] for your device for more information.

== Other Problems ==

If your Phidget is still not behaving as expected after handling errors and exceptions, have a look at our [[General Troubleshooting]] guide to track down the problem.

== Further Reading ==

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Logging, Exceptions, and Errors

2017-07-11T19:56:33Z

Chad:

[[Category:Programming]]
You've written your code, fixed the compiler errors, and yet, the program still isn't behaving as intended. The tools described on this page will help you further debug your program and figure out where in the code things are going wrong.

==Logging==

The {{Phidget22API}} supports a general logging API that supports log levels, named sources of logs, and the writing of logs to a file or to a Phidget Network Server. The Phidget software library uses this logging system internally, so in addition to being able to log within your own software, information about what the Phidget software is doing is also available. Refer to the ''Logging API'' in the {{Phidget22API}} for language specific information.

To begin, logging must be enabled

<syntaxhighlight lang=c>
PhidgetLog_enable(PHIDGET_LOG_DEBUG, NULL);
</syntaxhighlight>

Or in Java:

<syntaxhighlight lang=java>
Log.enable(LogLevel.DEBUG, null);
</syntaxhighlight>

When <code>NULL</code> is passed to <code>enable()</code> in the above examples, the logging system will output to <code>STDERR</code>.

There are five different logging levels, ranging from "Give me Everything!" to "Tell me only about critical problems".

'''CRITICAL'''
:Critical error messages.
:Errors at this level are generally non-recoverable and indicate either hardware problems, library bugs, or other serious issues.

'''ERROR'''
:Non-critical error messages.
:Errors at this level are generally automatically recoverable, but may help to track down issues.

'''WARNING'''
:Warning messages.
:Warnings are used to log behavior that is not necessarily in error, but is nevertheless odd or unexpected.

'''INFO'''
:Informational messages.
:Informational messages communicate useful operations and states changes within the software

'''VERBOSE'''
:Verbose messages.
:Verbose messages are informational messages that are expected to happen so frequently that they tend to drown out other log messages.

These are available in the '''Enumerations''' section of Logging API in the {{Phidget22API}} documentation.

=== Logging in Your Program ===

Logging is performed using the <code>log()</code> method from the Logging API.

For example, in C:

<syntaxhighlight lang=c>
PhidgetLog_log(PHIDGET_LOG_INFO, "Something happened in loop iteration %d!", i);
</syntaxhighlight>

Or in Java:

<syntaxhighlight lang=java>
Log.log(LogLevel.INFO, "Something happened in loop iteration " + i + "!");
</syntaxhighlight>

The logging API supports the concept of a ''log source'', were the ''log source'' is a textual identifier of where the log message originated. The ''log source'' is output to log the log file along with the log message to help organize the data.

The following examples define and create a log source, and then write a log message using that source.

<syntaxhighlight lang=c>
#define MYSOURCE "mysource"
PhidgetLog_addSource(MYSOURCE, PHIDGET_LOG_INFO);
PhidgetLog_log(__FILE__, __LINE__, __func__, MYSOURCE, PHIDGET_LOG_INFO, "Something happened");
</syntaxhighlight>

Or in Java:

<syntaxhighlight lang=java>
public static final String MYSOURCE = "mysource";
Log.addSource(MYSOURCE, LogLevel.INFO);
Log.log(LogLevel.INFO, MYSOURCE, "Something happened);
</syntaxhighlight>

==Exceptions and Errors==

There are two different types of errors that you can use to determine where a problem exists in your program.

===Error Generated By Methods===

When an error occurs during a method invocation, either a language specific exception is thrown, or an error is returned. It is important to check the return value from each method call, and to catch and handle exceptions.

For example, in C:

<syntaxhighlight lang=c>
int
main(int argc, char **argv) {
PhidgetReturnCode res;

res = PhidgetLog_enable(PHIDGET_LOG_ERROR, NULL);
if (res != EPHIDGET_OK) {
fprintf(stderr, "failed to enable Phidget logging: %d\n", res);
exit(1);
}
exit(0);
}
</syntaxhighlight>

Or in Java:

<syntaxhighlight lang=java>
try {
Log.enable(LogLevel.INFO, null);
} catch (PhidgetException ex) {
System.out.println("Failed to enable Phidget logging: " + ex.getMessage());
}
</syntaxhighlight>

The consequence of not handling errors correctly ranges from the program crashing if an unhandled exception occurs to improper behavior. Program should check for errors on each method call, and handle any errors.

====Error Codes====

A list of error codes can be found in the {{Phidget22API}}. Refer to language specific exceptions in language that support them.

===Error Generated From The Device===

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:

<syntaxhighlight lang=cpp>
int ErrorEventHandler (PhidgetHandle device, void *usrptr, Phidget_ErrorEventCode 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;
}

// At the beginning of your program, hook the Error Event Handler in to receive events
LocalErrorCatcher(
Phidget_setOnErrorHandler((PhidgetHandle) device, ErrorEventHandler, NULL));
</syntaxhighlight>

You'll note that the '''ErrorEventHandler''' 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 [[#Phidget Return Codes|described above]].

In Java, it would look like this:

<syntaxhighlight lang=java>
try {
device.addErrorListener((ErrorEvent ee) -> {
System.out.println("Error: " + ee.getDescription());
});
});
} catch (PhidgetException exception) {
system.out.println("The description for error " + Integer.toString(exception.getErrorCode()) + " is: ", exception.getDescription());
}

</syntaxhighlight>

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 {{Phidget22API}}.

====Error Codes====

These codes are used within the Error Event. See the {{Phidget22API}} documentation for your device to see which codes can be returned by which functions. These codes can be very generalized so it’s important to look at the accompanying description. These codes are broken down into errors that stem from within the library, errors which are directly reported by Phidget hardware, and errors that occur in your software.

'''BADVERSION'''
:Version Mismatch Error. Usually means client and host side of a network connection are out of sync. Update the latest versions of the Phidget drivers on both the client and the host.

'''BUSY'''
:The Phidget channel has already been opened locally by another process, so it can't be opened. You can have multiple processes open the same channel if they all open it remotely (with the exception of some Phidgets like motor controllers, which only allow a single connection regardless of whether it's local or remote).

'''NETWORK'''
:An error occurred with the network communications. See the error description for more details.

'''DISPATCH'''
:An error occurred when trying to dispatch an event. It's possible that the data rate is too fast for the computer you're using and the event queue has filled up.

'''OK'''
: An error state has ended. You can use the <code>getDescription</code> method of the error event to get more information. For example, if there is an over-voltage condition occurring, this error code will be thrown when the voltage returns to acceptable levels.

'''OVERRUN'''
:Sampling overrun. Some samples were lost in firmware because the queue filled up. This error is exclusive to Phidget InterfaceKits.

'''PACKETLOST'''
:Packet(s) were lost. This error is often an indication that your event handlers are not executing fast enough. Try to remove slow processes like GUI updates or user input from your handlers.

'''WRAP'''
:A variable has wrapped. For example, the encoder position can wrap from 2,147,483,647 to -2,147,483,648 because of an integer overflow.

'''OVERTEMP'''
:Over-Temperature condition detected. See error description for more details.

'''OVERCURRENT'''
:Over-Current condition detected. See error description for more details.

'''OUTOFRANGE'''
:Out of range condition detected. Usually an input on the board is reporting a value that is outside of the allowed range.

'''BADPOWER'''
:Power supply problem detected. Either the power supply is being overloaded, or it is under-powered (possibly not plugged in).

'''SATURATION'''
:A sensor's value has reached the maximum or minimum of its sensing range. For example, a 1000 lux light sensor will throw this error event when a value greater than 1000 lux is detected. The sensor will still be reporting 1000 lux, but this error tells you that you don't know for certain how much higher than 1000 the real reading is.

'''OVERVOLTAGE'''
:Over-Voltage condition detected. Occurs in power-providing Phidgets when the output voltage exceeds the set value.

'''VOLTAGEERROR'''
:A voltage error occurs when a Phidget that provides a voltage output has the value drop below what what specified. This can happen if the device being powered draws too much current, which causes a voltage drop. Stay within output current specifications to avoid voltage errors.

'''ENERGYDUMP'''
:An energy dump occurs when a power-providing Phidget needs to dissipate its extra energy. See the [[:Category:UserGuide|User Guide]] for your device for more information.

== Other Problems ==

If your Phidget is still not behaving as expected after handling errors and exceptions, have a look at our [[General Troubleshooting]] guide to track down the problem.

== Further Reading ==

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Using Multiple Phidgets

2017-07-11T18:51:52Z

Chad:

[[Category:Programming]]

When only one Phidget is connected to a computer, it is pretty easy for a simple program to open and attach to the channels on that one Phidget; however, when the program becomes more complicated or more than one Phidget is connected, attaching to the correct channel can be more difficult.

Before opening a channel, it is important to set enough of the matching properties to ensure the desired device channel is matched. By default, the matching code in the Phidget library will match the first available device channel that is of the correct class. For example, if two temperature sensor devices are connected to a computer, it is undefined which will attach when the device serial number is not specified before the channel is opened.

The best practice is to always specify at least the device serial number and the channel ID of the device channel that should be attached to the user channel. Even when not strictly necessary, setting as many matching properties as possible can ensure that code will not break in the future.

===Using the Channel ID===

Each channel exported by a Phidget device has an id, normally starting at 0. The {{Code|channel}} property must be set to ensure the device channel the Phidget software library matches is right one. If a 4-channel temperature sensor is connected, and the {{Code|channel}} property is not specified, the matching code will attach to channel 0 if available, and the next available channel if not.

Set the '''channel id''' with the {{Code|Channel}} property.

===Using the Hub Port===

VINT hubs have a number of ports that VINT devices can be connected to. To ensure the correct VINT device is attached, the hub port must be specified. If two temperature sensors are attached to the same hub, and the hub port is not specified prior to opening a channel, it is undefined which temperature sensor will be attached.

Set the '''hub port''' with the {{Code|HubPort}} property.

===Using the Serial Number===

Each Phidget has a unique serial number (VINT devices inherit the serial number of the hub). When there is more than one device that exports the same channel class, the device serial number must be specified to ensure the channel on the desired device is matched. The device serial number can be found on a label on the bottom of the Phidget, or determined by reading the {{Code|DeviceSerialNumber}} property.

Set the '''device serial number''' with the {{Code|DeviceSerialNumber}} property.

===Using the Label===

Most Phidgets can be assigned a label that may be used as a human-readable way to reference them (VINT devices inherit the serial number of the hub). In software that will be distributed, or cannot easily be modified it is useful to attach to channels based on the label of the device. This way, the device can be labelled prior to running the software, and the new device will be matched

Set the '''device label''' with the {{Code|DeviceLabel}} property.

Some limitations are:
* In [[OS - Windows|Windows]], label can be read on any Phidget that has a serial number, but label can only be written for Phidgets that support firmware upgrading.
* Some programming languages do not support writing to labels. See the {{Phidget22API}}.

===Code Examples===

For example, in Java, this would be:
<div class="source">
<syntaxhighlight lang=java>
ch.setDeviceSerialNumber(12345); // match device 12345
ch.setHubPort(4); // match hub port 4
ch.setChannel(1); // match channel 1 port 4 dev 12345
ch.open(); // start matching
</syntaxhighlight>
</div>

Or in C:
<div class="source">
<syntaxhighlight lang=c>
Phidget_setDeviceSerialNumber((PhidgetHandle)ch, 12345); // match device 12345
Phidget_setHubPort((PhidgetHandle)ch, 4); // match hub port 4
Phidget_setChannel((PhidgetHandle)ch, 1); // match channel 1 port 4 dev 12345
Phidget_open((PhidgetHandle)ch); // start matching
</syntaxhighlight>
</div>

===Distinguishing Events===

When using [[Polling vs. Events|events]], it is recommended that a different event handler be used for each channel to simplify the code and prevent programming errors. In the case where it is not practical to write an individual handler for each channel, the matching properties of the channel can be read to determine what device channel the event is from.

Prior to the channel being attached to a device channel, the matching properties will return the values that will be used to perform the match; however, once the channel is attached, the matching properties will return the physical values from the device channel. For example, if '''serial number''' has not been specified, {{Code|DeviceSerialNumber}} would be {{Code|PHIDGET_SERIALNUMBER_ANY}}, but once attached {{Code|DeviceSerialNumber}} would be the serial number of the attached device.

=== Further Reading ===

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Using Multiple Phidgets

2017-07-11T18:42:59Z

Chad: /* Code Examples */

[[Category:Programming]]

Before opening a channel, it is important to set enough of the matching properties to ensure the desired device channel is matched. By default, the matching code in the Phidget library will match the first available device channel that is of the correct class. For example, if two temperature sensor devices are connected to a computer, it is undefined which will attach when the device serial number is not specified before the channel is opened.

===Using the Channel ID===

Each channel exported by a Phidget device has an id, normally starting at 0. The {{Code|channel}} property must be set to ensure the device channel the Phidget software library matches is right one. If a 4-channel temperature sensor is connected, and the {{Code|channel}} property is not specified, the matching code will attach to channel 0 if available, and the next available channel if not.

Set the '''channel id''' with the {{Code|Channel}} property.

===Using the Hub Port===

VINT hubs have a number of ports that VINT devices can be connected to. To ensure the correct VINT device is attached, the hub port must be specified. If two temperature sensors are attached to the same hub, and the hub port is not specified prior to opening a channel, it is undefined which temperature sensor will be attached.

Set the '''hub port''' with the {{Code|HubPort}} property.

===Using the Serial Number===

Each Phidget has a unique serial number (VINT devices inherit the serial number of the hub). When there is more than one device that exports the same channel class, the device serial number must be specified to ensure the channel on the desired device is matched. The device serial number can be found on a label on the bottom of the Phidget, or determined by reading the {{Code|DeviceSerialNumber}} property.

Set the '''device serial number''' with the {{Code|DeviceSerialNumber}} property.

===Using the Label===

Most Phidgets can be assigned a label that may be used as a human-readable way to reference them (VINT devices inherit the serial number of the hub). In software that will be distributed, or cannot easily be modified it is useful to attach to channels based on the label of the device. This way, the device can be labelled prior to running the software, and the new device will be matched

Set the '''device label''' with the {{Code|DeviceLabel}} property.

Some limitations are:
* In [[OS - Windows|Windows]], label can be read on any Phidget that has a serial number, but label can only be written for Phidgets that support firmware upgrading.
* Some programming languages do not support writing to labels. See the {{Phidget22API}}.

===Code Examples===

For example, in Java, this would be:
<div class="source">
<syntaxhighlight lang=java>
ch.setDeviceSerialNumber(12345); // match device 12345
ch.setHubPort(4); // match hub port 4
ch.setChannel(1); // match channel 1 port 4 dev 12345
ch.open(); // start matching
</syntaxhighlight>
</div>

Or in C:
<div class="source">
<syntaxhighlight lang=c>
Phidget_setDeviceSerialNumber((PhidgetHandle)ch, 12345); // match device 12345
Phidget_setHubPort((PhidgetHandle)ch, 4); // match hub port 4
Phidget_setChannel((PhidgetHandle)ch, 1); // match channel 1 port 4 dev 12345
Phidget_open((PhidgetHandle)ch); // start matching
</syntaxhighlight>
</div>

===Distinguishing Events===

When using [[Polling vs. Events|events]], it is recommended that a different event handler be used for each channel to simplify the code and prevent programming errors. In the case where it is not practical to write an individual handler for each channel, the matching properties of the channel can be read to determine what device channel the event is from.

Prior to the channel being attached to a device channel, the matching properties will return the values that will be used to perform the match; however, once the channel is attached, the matching properties will return the physical values from the device channel. For example, if '''serial number''' has not been specified, {{Code|DeviceSerialNumber}} would be {{Code|PHIDGET_SERIALNUMBER_ANY}}, but once attached {{Code|DeviceSerialNumber}} would be the serial number of the attached device.

=== Further Reading ===

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Using Multiple Phidgets

2017-07-11T18:42:09Z

Chad: /* Distinguishing Events */

[[Category:Programming]]

Before opening a channel, it is important to set enough of the matching properties to ensure the desired device channel is matched. By default, the matching code in the Phidget library will match the first available device channel that is of the correct class. For example, if two temperature sensor devices are connected to a computer, it is undefined which will attach when the device serial number is not specified before the channel is opened.

===Using the Channel ID===

Each channel exported by a Phidget device has an id, normally starting at 0. The {{Code|channel}} property must be set to ensure the device channel the Phidget software library matches is right one. If a 4-channel temperature sensor is connected, and the {{Code|channel}} property is not specified, the matching code will attach to channel 0 if available, and the next available channel if not.

Set the '''channel id''' with the {{Code|Channel}} property.

===Using the Hub Port===

VINT hubs have a number of ports that VINT devices can be connected to. To ensure the correct VINT device is attached, the hub port must be specified. If two temperature sensors are attached to the same hub, and the hub port is not specified prior to opening a channel, it is undefined which temperature sensor will be attached.

Set the '''hub port''' with the {{Code|HubPort}} property.

===Using the Serial Number===

Each Phidget has a unique serial number (VINT devices inherit the serial number of the hub). When there is more than one device that exports the same channel class, the device serial number must be specified to ensure the channel on the desired device is matched. The device serial number can be found on a label on the bottom of the Phidget, or determined by reading the {{Code|DeviceSerialNumber}} property.

Set the '''device serial number''' with the {{Code|DeviceSerialNumber}} property.

===Using the Label===

Most Phidgets can be assigned a label that may be used as a human-readable way to reference them (VINT devices inherit the serial number of the hub). In software that will be distributed, or cannot easily be modified it is useful to attach to channels based on the label of the device. This way, the device can be labelled prior to running the software, and the new device will be matched

Set the '''device label''' with the {{Code|DeviceLabel}} property.

Some limitations are:
* In [[OS - Windows|Windows]], label can be read on any Phidget that has a serial number, but label can only be written for Phidgets that support firmware upgrading.
* Some programming languages do not support writing to labels. See the {{Phidget22API}}.

===Code Examples===

For example, in Java, this would be:
<div class="source">
<syntaxhighlight lang=java>
ch.setDeviceSerialNumber(12345); // match device 12345
ch.setHubPort(4); // match hub port 4
ch.setChannel(1); // match channel 1 port 4 dev 12345
ch.open(); // start matching
</syntaxhighlight>
</div>

Or in C:
<div class="source">
<syntaxhighlight lang=c>
Phidget_setDeviceSerialNumber((PhidgetHandle)ch, 12345); // match device 12345
Phidget_setHubPort((PhidgetHandle)ch, 4); // match hub port 4
Phidget_setChannel((PhidgetHandle)ch, 1); // match channel 1 port 4 dev 12345
Phidget_open((CPhidgetHandle)ch); // start matching
</syntaxhighlight>
</div>

===Distinguishing Events===

When using [[Polling vs. Events|events]], it is recommended that a different event handler be used for each channel to simplify the code and prevent programming errors. In the case where it is not practical to write an individual handler for each channel, the matching properties of the channel can be read to determine what device channel the event is from.

Prior to the channel being attached to a device channel, the matching properties will return the values that will be used to perform the match; however, once the channel is attached, the matching properties will return the physical values from the device channel. For example, if '''serial number''' has not been specified, {{Code|DeviceSerialNumber}} would be {{Code|PHIDGET_SERIALNUMBER_ANY}}, but once attached {{Code|DeviceSerialNumber}} would be the serial number of the attached device.

=== Further Reading ===

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Using Multiple Phidgets

2017-07-11T18:32:27Z

Chad:

[[Category:Programming]]

Before opening a channel, it is important to set enough of the matching properties to ensure the desired device channel is matched. By default, the matching code in the Phidget library will match the first available device channel that is of the correct class. For example, if two temperature sensor devices are connected to a computer, it is undefined which will attach when the device serial number is not specified before the channel is opened.

===Using the Channel ID===

Each channel exported by a Phidget device has an id, normally starting at 0. The {{Code|channel}} property must be set to ensure the device channel the Phidget software library matches is right one. If a 4-channel temperature sensor is connected, and the {{Code|channel}} property is not specified, the matching code will attach to channel 0 if available, and the next available channel if not.

Set the '''channel id''' with the {{Code|Channel}} property.

===Using the Hub Port===

VINT hubs have a number of ports that VINT devices can be connected to. To ensure the correct VINT device is attached, the hub port must be specified. If two temperature sensors are attached to the same hub, and the hub port is not specified prior to opening a channel, it is undefined which temperature sensor will be attached.

Set the '''hub port''' with the {{Code|HubPort}} property.

===Using the Serial Number===

Each Phidget has a unique serial number (VINT devices inherit the serial number of the hub). When there is more than one device that exports the same channel class, the device serial number must be specified to ensure the channel on the desired device is matched. The device serial number can be found on a label on the bottom of the Phidget, or determined by reading the {{Code|DeviceSerialNumber}} property.

Set the '''device serial number''' with the {{Code|DeviceSerialNumber}} property.

===Using the Label===

Most Phidgets can be assigned a label that may be used as a human-readable way to reference them (VINT devices inherit the serial number of the hub). In software that will be distributed, or cannot easily be modified it is useful to attach to channels based on the label of the device. This way, the device can be labelled prior to running the software, and the new device will be matched

Set the '''device label''' with the {{Code|DeviceLabel}} property.

Some limitations are:
* In [[OS - Windows|Windows]], label can be read on any Phidget that has a serial number, but label can only be written for Phidgets that support firmware upgrading.
* Some programming languages do not support writing to labels. See the {{Phidget22API}}.

===Code Examples===

For example, in Java, this would be:
<div class="source">
<syntaxhighlight lang=java>
ch.setDeviceSerialNumber(12345); // match device 12345
ch.setHubPort(4); // match hub port 4
ch.setChannel(1); // match channel 1 port 4 dev 12345
ch.open(); // start matching
</syntaxhighlight>
</div>

Or in C:
<div class="source">
<syntaxhighlight lang=c>
Phidget_setDeviceSerialNumber((PhidgetHandle)ch, 12345); // match device 12345
Phidget_setHubPort((PhidgetHandle)ch, 4); // match hub port 4
Phidget_setChannel((PhidgetHandle)ch, 1); // match channel 1 port 4 dev 12345
Phidget_open((CPhidgetHandle)ch); // start matching
</syntaxhighlight>
</div>

===Distinguishing Events===

If you are using [[Polling vs. Events|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 [[Phidget_Programming_Basics#Attaching_the_Phidget|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>

=== Further Reading ===

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Phidget Network Server

2017-07-11T17:26:08Z

Chad: /* Troubleshooting */

[[Category:Programming]]
__TOC__

==General Overview==
The Phidget Network Server is a feature of Phidgets that makes it possible to control or interact with Phidgets connected to other computers. To understand how it works, let's first take a look at what a system looks like without the Network Server enabled:

[[Image:Phidgets_without_NetworkServer.jpg|link=|500px|right]]

Begin with a local computer with the Phidget software installed and a number of Phidgets and/or [[What_is_VINT?|VINT Hubs]] connected. Connected to the VINT Hubs could be VINT devices.

All of these connected Phidgets have various channels that can be attached, which would allow a program running on the local computer to control or read data from them.

Since the Network Server is disabled in this diagram, the local computer is the only one that will be able to access the connected Phidgets.

<br clear="all">

Enabling the Phidget Network Server will allow software on a remote computer to connect to the local computer and receive the list of available Phidget devices attached. The channels from the remote computer will appear to be local to the local computer.

[[Image:NetworkServer_PhidgetServer.jpg|link=|800px]]

Software can set the {{Code|IsLocal}} and {{Code|IsRemote}} properties of a channel to control if remote or local channels should be considered during matching.

Specifying '''IsLocal''' would instruct the Phidget software to only match Phidgets physically connected to the local computer.

Specifying '''IsRemote''' would instruct the Phidget software to only match Phidgets exported by a remote computer.

Phidget device channels normally can only be attached to a single user channel; however, device channels that are exported by the Phidget Network Server may attach to more than one remote user channel. There are some exceptions (for example motor controllers) where safety could be an issue.

[[Image:NetworkServer_Local_Remote.jpg|link=|800px]]

As can be see in this example, there is a Phidget with four channels connected to a local computer. The local computer has enabled the Phidget Network Server. When the local computer attaches to channel 1, a remote computer is unable to attach to channel 1; furthermore, the local computer cannot attach a second user channel to channel 1 using the network server because channel 1 is already attached locally. On the other hand, both computers are able to attach to channel 2 remotely, because channel 2 hasn't been attached locally by the local computer. Both the local computer and the remote computer could attach several user channels to channel 2.

==Using The Network Server==

Each Operating System page has a section on how to use the Phidget Network Server:

* [[OS - Windows#Phidget Network Server|Windows]]
* [[OS - OS X#Phidget Network Server|Mac OS]]
* [[OS - Linux#Phidget Network Server|Linux]]
* [[OS - Phidget SBC#Phidget Network Server|Linux on the Phidget SBC]]
* [[OS - iOS#Phidget Network Server|iPhone/iPad iOS]]

The OS pages have examples of how to set up the Phidget Network Server and how to use it to remotely control and gather data from Phidgets. The OS pages also describe how to start and stop the Phidget Network Server, and how to run it with or without mDNS (Bonjour, avahi, etc).

== Connecting to a Network Server ==

There are two ways to access to a Phidget Network Server. First, if '''publish''' is enabled in a server, the server will broadcast its existence, and software can enable server discovery to dynamically discover and connect to the server. Second, software can connect directly to a server. To enable server discovery the {{Code|enableServerDiscovery()}} method is used. To connect to a specific server the {{Code|addServer()}} method is used. A list of networking methods can be found in the "Network API" section of the {{Phidget22API}}.

==Network Server on a Phidget Single Board Computer==

The Phidget Single Board Computer (SBC) can provide a compact, inexpensive way to easily run the Network Server. It runs the Network Server in the background automatically from the moment you turn it on, and allows you to read from and control all Phidgets attached to it:

[[Image:network_server_sbc.jpg|link=|900px]]

In this example, a Phidget SBC physically connected to a VINT Hub which is connected to a VINT device. The SBC itself has its own channels corresponding to the on-board ports it has. By using the network server, the SBC makes all of these channels available to any computer connected to the network.

This is convenient because it allows the Phidgets and sensors to be in a remote location, like mounted on a wall or inside of an assembly. The channels of this system could be conveniently accessed by a home computer on the network, a phone running some Phidgets code, or even another Phidget SBC.

The SBC runs Linux, which provides a [[OS - Phidget SBC|full operating system]] on which to develop code, {{ARTICLE|WebPageOnSBC|serve web pages}}, and {{ARTICLE|PhidgetsWirelesslyWithSBC|control Phidgets}}.

For more information on controlling Phidgets with your phone, have a look at the mobile section of our [[Software_Overview#Language_Support|languages]] page, or read {{ARTICLE|MurvRobotIOS|this article}} where we use [[OS_-_iOS|iOS]] to control a robot full of Phidgets.

== Examples ==
Below are some quick examples showing how simple it is to open a Phidget remotely over the Network Server. In each example, a light sensor Phidget is being remotely opened on port 0 of a VINT Hub with serial number 37299.

{{hiddenh3|C/C++}}

<syntaxhighlight lang=cpp>
PhidgetLightSensorHandle ch;
PhidgetLightSensor_create(&ch);

PhidgetNet_enableServerDiscovery(PHIDGETSERVER_DEVICE);

Phidget_setDeviceSerialNumber((PhidgetHandle) ch, 37299);
Phidget_setHubPort((PhidgetHandle) ch, 0);
Phidget_setIsRemote((PhidgetHandle) ch, 1);

Phidget_open((PhidgetHandle) ch);

</syntaxhighlight>

{{hiddenh3|C#}}

<syntaxhighlight lang='CSharp'>
LightSensor ch = new LightSensor();

ch.DeviceSerialNumber = 37299;
ch.HubPort = 0;
ch.IsRemote = true;

ch.Open();

</syntaxhighlight>

{{hiddenh3|Java}}

<syntaxhighlight lang='Java'>
LightSensor ch = new LightSensor();

Net.enableServerDiscovery(ServerType.DEVICE);

ch.setDeviceSerialNumber(37299);
ch.setHubPort(0);
ch.setIsRemote(true);

ch.open();

</syntaxhighlight>

{{hiddenh3|Python}}

<syntaxhighlight lang='python'>
ch = LightSensor()

Net.enableServerDiscovery(PhidgetServerType.PHIDGETSERVER_DEVICE);

ch.setDeviceSerialNumber(37299)
ch.setHubPort(0)
ch.setIsRemote(1)

ch.open();

</syntaxhighlight>

For more information, please refer to the {{Phidget22API}}, and the [[Phidget_Programming_Basics#Opening_the_Phidget|Programming Basics]] page.

== Troubleshooting ==

When using the Network Server, both the '''client and server should have the ''same version''''' of the Phidget software library installed.

For other troubleshooting tips, try our General Troubleshooting page, in its [[General_Troubleshooting#Network_Server_Troubleshooting|Network Server section]].

=== Further Reading ===

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Phidget Network Server

2017-07-11T17:24:54Z

Chad: /* Examples */

[[Category:Programming]]
__TOC__

==General Overview==
The Phidget Network Server is a feature of Phidgets that makes it possible to control or interact with Phidgets connected to other computers. To understand how it works, let's first take a look at what a system looks like without the Network Server enabled:

[[Image:Phidgets_without_NetworkServer.jpg|link=|500px|right]]

Begin with a local computer with the Phidget software installed and a number of Phidgets and/or [[What_is_VINT?|VINT Hubs]] connected. Connected to the VINT Hubs could be VINT devices.

All of these connected Phidgets have various channels that can be attached, which would allow a program running on the local computer to control or read data from them.

Since the Network Server is disabled in this diagram, the local computer is the only one that will be able to access the connected Phidgets.

<br clear="all">

Enabling the Phidget Network Server will allow software on a remote computer to connect to the local computer and receive the list of available Phidget devices attached. The channels from the remote computer will appear to be local to the local computer.

[[Image:NetworkServer_PhidgetServer.jpg|link=|800px]]

Software can set the {{Code|IsLocal}} and {{Code|IsRemote}} properties of a channel to control if remote or local channels should be considered during matching.

Specifying '''IsLocal''' would instruct the Phidget software to only match Phidgets physically connected to the local computer.

Specifying '''IsRemote''' would instruct the Phidget software to only match Phidgets exported by a remote computer.

Phidget device channels normally can only be attached to a single user channel; however, device channels that are exported by the Phidget Network Server may attach to more than one remote user channel. There are some exceptions (for example motor controllers) where safety could be an issue.

[[Image:NetworkServer_Local_Remote.jpg|link=|800px]]

As can be see in this example, there is a Phidget with four channels connected to a local computer. The local computer has enabled the Phidget Network Server. When the local computer attaches to channel 1, a remote computer is unable to attach to channel 1; furthermore, the local computer cannot attach a second user channel to channel 1 using the network server because channel 1 is already attached locally. On the other hand, both computers are able to attach to channel 2 remotely, because channel 2 hasn't been attached locally by the local computer. Both the local computer and the remote computer could attach several user channels to channel 2.

==Using The Network Server==

Each Operating System page has a section on how to use the Phidget Network Server:

* [[OS - Windows#Phidget Network Server|Windows]]
* [[OS - OS X#Phidget Network Server|Mac OS]]
* [[OS - Linux#Phidget Network Server|Linux]]
* [[OS - Phidget SBC#Phidget Network Server|Linux on the Phidget SBC]]
* [[OS - iOS#Phidget Network Server|iPhone/iPad iOS]]

The OS pages have examples of how to set up the Phidget Network Server and how to use it to remotely control and gather data from Phidgets. The OS pages also describe how to start and stop the Phidget Network Server, and how to run it with or without mDNS (Bonjour, avahi, etc).

== Connecting to a Network Server ==

There are two ways to access to a Phidget Network Server. First, if '''publish''' is enabled in a server, the server will broadcast its existence, and software can enable server discovery to dynamically discover and connect to the server. Second, software can connect directly to a server. To enable server discovery the {{Code|enableServerDiscovery()}} method is used. To connect to a specific server the {{Code|addServer()}} method is used. A list of networking methods can be found in the "Network API" section of the {{Phidget22API}}.

==Network Server on a Phidget Single Board Computer==

The Phidget Single Board Computer (SBC) can provide a compact, inexpensive way to easily run the Network Server. It runs the Network Server in the background automatically from the moment you turn it on, and allows you to read from and control all Phidgets attached to it:

[[Image:network_server_sbc.jpg|link=|900px]]

In this example, a Phidget SBC physically connected to a VINT Hub which is connected to a VINT device. The SBC itself has its own channels corresponding to the on-board ports it has. By using the network server, the SBC makes all of these channels available to any computer connected to the network.

This is convenient because it allows the Phidgets and sensors to be in a remote location, like mounted on a wall or inside of an assembly. The channels of this system could be conveniently accessed by a home computer on the network, a phone running some Phidgets code, or even another Phidget SBC.

The SBC runs Linux, which provides a [[OS - Phidget SBC|full operating system]] on which to develop code, {{ARTICLE|WebPageOnSBC|serve web pages}}, and {{ARTICLE|PhidgetsWirelesslyWithSBC|control Phidgets}}.

For more information on controlling Phidgets with your phone, have a look at the mobile section of our [[Software_Overview#Language_Support|languages]] page, or read {{ARTICLE|MurvRobotIOS|this article}} where we use [[OS_-_iOS|iOS]] to control a robot full of Phidgets.

== Examples ==
Below are some quick examples showing how simple it is to open a Phidget remotely over the Network Server. In each example, a light sensor Phidget is being remotely opened on port 0 of a VINT Hub with serial number 37299.

{{hiddenh3|C/C++}}

<syntaxhighlight lang=cpp>
PhidgetLightSensorHandle ch;
PhidgetLightSensor_create(&ch);

PhidgetNet_enableServerDiscovery(PHIDGETSERVER_DEVICE);

Phidget_setDeviceSerialNumber((PhidgetHandle) ch, 37299);
Phidget_setHubPort((PhidgetHandle) ch, 0);
Phidget_setIsRemote((PhidgetHandle) ch, 1);

Phidget_open((PhidgetHandle) ch);

</syntaxhighlight>

{{hiddenh3|C#}}

<syntaxhighlight lang='CSharp'>
LightSensor ch = new LightSensor();

ch.DeviceSerialNumber = 37299;
ch.HubPort = 0;
ch.IsRemote = true;

ch.Open();

</syntaxhighlight>

{{hiddenh3|Java}}

<syntaxhighlight lang='Java'>
LightSensor ch = new LightSensor();

Net.enableServerDiscovery(ServerType.DEVICE);

ch.setDeviceSerialNumber(37299);
ch.setHubPort(0);
ch.setIsRemote(true);

ch.open();

</syntaxhighlight>

{{hiddenh3|Python}}

<syntaxhighlight lang='python'>
ch = LightSensor()

Net.enableServerDiscovery(PhidgetServerType.PHIDGETSERVER_DEVICE);

ch.setDeviceSerialNumber(37299)
ch.setHubPort(0)
ch.setIsRemote(1)

ch.open();

</syntaxhighlight>

For more information, please refer to the {{Phidget22API}}, and the [[Phidget_Programming_Basics#Opening_the_Phidget|Programming Basics]] page.

== Troubleshooting ==

When using the Network Server, both the '''client and server should have the ''same version''''' of the Network Server installed. The easiest way to ensure this is to update your libraries on both ends.

For other troubleshooting tips, try our General Troubleshooting page, in its [[General_Troubleshooting#Network_Server_Troubleshooting|Network Server section]].

=== Further Reading ===

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Phidget Network Server

2017-07-11T17:17:05Z

Chad: /* Network Server on a Phidget Single Board Computer */

[[Category:Programming]]
__TOC__

==General Overview==
The Phidget Network Server is a feature of Phidgets that makes it possible to control or interact with Phidgets connected to other computers. To understand how it works, let's first take a look at what a system looks like without the Network Server enabled:

[[Image:Phidgets_without_NetworkServer.jpg|link=|500px|right]]

Begin with a local computer with the Phidget software installed and a number of Phidgets and/or [[What_is_VINT?|VINT Hubs]] connected. Connected to the VINT Hubs could be VINT devices.

All of these connected Phidgets have various channels that can be attached, which would allow a program running on the local computer to control or read data from them.

Since the Network Server is disabled in this diagram, the local computer is the only one that will be able to access the connected Phidgets.

<br clear="all">

Enabling the Phidget Network Server will allow software on a remote computer to connect to the local computer and receive the list of available Phidget devices attached. The channels from the remote computer will appear to be local to the local computer.

[[Image:NetworkServer_PhidgetServer.jpg|link=|800px]]

Software can set the {{Code|IsLocal}} and {{Code|IsRemote}} properties of a channel to control if remote or local channels should be considered during matching.

Specifying '''IsLocal''' would instruct the Phidget software to only match Phidgets physically connected to the local computer.

Specifying '''IsRemote''' would instruct the Phidget software to only match Phidgets exported by a remote computer.

Phidget device channels normally can only be attached to a single user channel; however, device channels that are exported by the Phidget Network Server may attach to more than one remote user channel. There are some exceptions (for example motor controllers) where safety could be an issue.

[[Image:NetworkServer_Local_Remote.jpg|link=|800px]]

As can be see in this example, there is a Phidget with four channels connected to a local computer. The local computer has enabled the Phidget Network Server. When the local computer attaches to channel 1, a remote computer is unable to attach to channel 1; furthermore, the local computer cannot attach a second user channel to channel 1 using the network server because channel 1 is already attached locally. On the other hand, both computers are able to attach to channel 2 remotely, because channel 2 hasn't been attached locally by the local computer. Both the local computer and the remote computer could attach several user channels to channel 2.

==Using The Network Server==

Each Operating System page has a section on how to use the Phidget Network Server:

* [[OS - Windows#Phidget Network Server|Windows]]
* [[OS - OS X#Phidget Network Server|Mac OS]]
* [[OS - Linux#Phidget Network Server|Linux]]
* [[OS - Phidget SBC#Phidget Network Server|Linux on the Phidget SBC]]
* [[OS - iOS#Phidget Network Server|iPhone/iPad iOS]]

The OS pages have examples of how to set up the Phidget Network Server and how to use it to remotely control and gather data from Phidgets. The OS pages also describe how to start and stop the Phidget Network Server, and how to run it with or without mDNS (Bonjour, avahi, etc).

== Connecting to a Network Server ==

There are two ways to access to a Phidget Network Server. First, if '''publish''' is enabled in a server, the server will broadcast its existence, and software can enable server discovery to dynamically discover and connect to the server. Second, software can connect directly to a server. To enable server discovery the {{Code|enableServerDiscovery()}} method is used. To connect to a specific server the {{Code|addServer()}} method is used. A list of networking methods can be found in the "Network API" section of the {{Phidget22API}}.

==Network Server on a Phidget Single Board Computer==

The Phidget Single Board Computer (SBC) can provide a compact, inexpensive way to easily run the Network Server. It runs the Network Server in the background automatically from the moment you turn it on, and allows you to read from and control all Phidgets attached to it:

[[Image:network_server_sbc.jpg|link=|900px]]

In this example, a Phidget SBC physically connected to a VINT Hub which is connected to a VINT device. The SBC itself has its own channels corresponding to the on-board ports it has. By using the network server, the SBC makes all of these channels available to any computer connected to the network.

This is convenient because it allows the Phidgets and sensors to be in a remote location, like mounted on a wall or inside of an assembly. The channels of this system could be conveniently accessed by a home computer on the network, a phone running some Phidgets code, or even another Phidget SBC.

The SBC runs Linux, which provides a [[OS - Phidget SBC|full operating system]] on which to develop code, {{ARTICLE|WebPageOnSBC|serve web pages}}, and {{ARTICLE|PhidgetsWirelesslyWithSBC|control Phidgets}}.

For more information on controlling Phidgets with your phone, have a look at the mobile section of our [[Software_Overview#Language_Support|languages]] page, or read {{ARTICLE|MurvRobotIOS|this article}} where we use [[OS_-_iOS|iOS]] to control a robot full of Phidgets.

== Examples ==
Below are some quick examples showing how simple it is to open a Phidget remotely over the Network Server. In each example, a light sensor Phidget is being remotely opened on port 0 of a VINT Hub with serial number 37299.

{{hiddenh3|C/C++}}

<syntaxhighlight lang=cpp>
PhidgetLightSensorHandle ch;
PhidgetLightSensor_create(&ch);

Phidget_setDeviceSerialNumber((PhidgetHandle) ch, 37299);
Phidget_setHubPort((PhidgetHandle) ch, 0);
Phidget_setIsRemote((PhidgetHandle) ch, 1);

Phidget_open((PhidgetHandle) ch);

</syntaxhighlight>

{{hiddenh3|C#}}

<syntaxhighlight lang='CSharp'>
LightSensor ch = new LightSensor();

ch.DeviceSerialNumber = 37299;
ch.HubPort = 0;
ch.IsRemote = true;

ch.Open();

</syntaxhighlight>

{{hiddenh3|Java}}

<syntaxhighlight lang='Java'>
LightSensor ch = new LightSensor();

ch.setDeviceSerialNumber(37299);
ch.setHubPort(0);
ch.setIsRemote(true);

ch.open();

</syntaxhighlight>

{{hiddenh3|Python}}

<syntaxhighlight lang='python'>
ch = LightSensor()

ch.setDeviceSerialNumber(37299)
ch.setHubPort(0)
ch.setIsRemote(1)

ch.open();

</syntaxhighlight>

For more information, have a look at the {{Phidget22API}} and select your language from the drop-down menu. You can learn more about opening Phidgets on the [[Phidget_Programming_Basics#Opening_the_Phidget|Programming Basics]] page.

== Troubleshooting ==

When using the Network Server, both the '''client and server should have the ''same version''''' of the Network Server installed. The easiest way to ensure this is to update your libraries on both ends.

For other troubleshooting tips, try our General Troubleshooting page, in its [[General_Troubleshooting#Network_Server_Troubleshooting|Network Server section]].

=== Further Reading ===

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Phidget Network Server

2017-07-11T17:12:38Z

Chad: /* Connecting to a Network Server */

[[Category:Programming]]
__TOC__

==General Overview==
The Phidget Network Server is a feature of Phidgets that makes it possible to control or interact with Phidgets connected to other computers. To understand how it works, let's first take a look at what a system looks like without the Network Server enabled:

[[Image:Phidgets_without_NetworkServer.jpg|link=|500px|right]]

Begin with a local computer with the Phidget software installed and a number of Phidgets and/or [[What_is_VINT?|VINT Hubs]] connected. Connected to the VINT Hubs could be VINT devices.

All of these connected Phidgets have various channels that can be attached, which would allow a program running on the local computer to control or read data from them.

Since the Network Server is disabled in this diagram, the local computer is the only one that will be able to access the connected Phidgets.

<br clear="all">

Enabling the Phidget Network Server will allow software on a remote computer to connect to the local computer and receive the list of available Phidget devices attached. The channels from the remote computer will appear to be local to the local computer.

[[Image:NetworkServer_PhidgetServer.jpg|link=|800px]]

Software can set the {{Code|IsLocal}} and {{Code|IsRemote}} properties of a channel to control if remote or local channels should be considered during matching.

Specifying '''IsLocal''' would instruct the Phidget software to only match Phidgets physically connected to the local computer.

Specifying '''IsRemote''' would instruct the Phidget software to only match Phidgets exported by a remote computer.

Phidget device channels normally can only be attached to a single user channel; however, device channels that are exported by the Phidget Network Server may attach to more than one remote user channel. There are some exceptions (for example motor controllers) where safety could be an issue.

[[Image:NetworkServer_Local_Remote.jpg|link=|800px]]

As can be see in this example, there is a Phidget with four channels connected to a local computer. The local computer has enabled the Phidget Network Server. When the local computer attaches to channel 1, a remote computer is unable to attach to channel 1; furthermore, the local computer cannot attach a second user channel to channel 1 using the network server because channel 1 is already attached locally. On the other hand, both computers are able to attach to channel 2 remotely, because channel 2 hasn't been attached locally by the local computer. Both the local computer and the remote computer could attach several user channels to channel 2.

==Using The Network Server==

Each Operating System page has a section on how to use the Phidget Network Server:

* [[OS - Windows#Phidget Network Server|Windows]]
* [[OS - OS X#Phidget Network Server|Mac OS]]
* [[OS - Linux#Phidget Network Server|Linux]]
* [[OS - Phidget SBC#Phidget Network Server|Linux on the Phidget SBC]]
* [[OS - iOS#Phidget Network Server|iPhone/iPad iOS]]

The OS pages have examples of how to set up the Phidget Network Server and how to use it to remotely control and gather data from Phidgets. The OS pages also describe how to start and stop the Phidget Network Server, and how to run it with or without mDNS (Bonjour, avahi, etc).

== Connecting to a Network Server ==

There are two ways to access to a Phidget Network Server. First, if '''publish''' is enabled in a server, the server will broadcast its existence, and software can enable server discovery to dynamically discover and connect to the server. Second, software can connect directly to a server. To enable server discovery the {{Code|enableServerDiscovery()}} method is used. To connect to a specific server the {{Code|addServer()}} method is used. A list of networking methods can be found in the "Network API" section of the {{Phidget22API}}.

==Network Server on a Phidget Single Board Computer==

The Phidget Single Board Computer (SBC) can provide a compact, inexpensive way to easily run the Network Server. It runs the Network Server in the background automatically from the moment you turn it on, and allows you to read from and control all Phidgets attached to it:

[[Image:network_server_sbc.jpg|link=|900px]]

In this example, a Phidget SBC physically connected to a VINT Hub which is connected to a VINT device. The SBC itself has its own channels corresponding to the on-board ports it has. By using the network server, it makes all of these channels available to any device connected to the same wireless network.

This is convenient because it allows the Phidgets and sensors to be in a remote location, like mounted on a wall or inside some kind of assembly, rather than sitting on your computer desk. The channels of this system could be conveniently accessed by a home computer on the network, a phone running some Phidgets code, or even another Phidget SBC in a different location.

The SBC runs Linux, which provides a [[OS - Phidget SBC|full operating system]] on which to develop code, {{ARTICLE|WebPageOnSBC|serve web pages}}, and {{ARTICLE|PhidgetsWirelesslyWithSBC|control Phidgets}}.

For more information on controlling Phidgets with your phone, have a look at the mobile section of our [[Software_Overview#Language_Support|languages]] page, or read {{ARTICLE|MurvRobotIOS|this article}} where we use [[OS_-_iOS|iOS]] to control a robot full of Phidgets.

== Examples ==
Below are some quick examples showing how simple it is to open a Phidget remotely over the Network Server. In each example, a light sensor Phidget is being remotely opened on port 0 of a VINT Hub with serial number 37299.

{{hiddenh3|C/C++}}

<syntaxhighlight lang=cpp>
PhidgetLightSensorHandle ch;
PhidgetLightSensor_create(&ch);

Phidget_setDeviceSerialNumber((PhidgetHandle) ch, 37299);
Phidget_setHubPort((PhidgetHandle) ch, 0);
Phidget_setIsRemote((PhidgetHandle) ch, 1);

Phidget_open((PhidgetHandle) ch);

</syntaxhighlight>

{{hiddenh3|C#}}

<syntaxhighlight lang='CSharp'>
LightSensor ch = new LightSensor();

ch.DeviceSerialNumber = 37299;
ch.HubPort = 0;
ch.IsRemote = true;

ch.Open();

</syntaxhighlight>

{{hiddenh3|Java}}

<syntaxhighlight lang='Java'>
LightSensor ch = new LightSensor();

ch.setDeviceSerialNumber(37299);
ch.setHubPort(0);
ch.setIsRemote(true);

ch.open();

</syntaxhighlight>

{{hiddenh3|Python}}

<syntaxhighlight lang='python'>
ch = LightSensor()

ch.setDeviceSerialNumber(37299)
ch.setHubPort(0)
ch.setIsRemote(1)

ch.open();

</syntaxhighlight>

For more information, have a look at the {{Phidget22API}} and select your language from the drop-down menu. You can learn more about opening Phidgets on the [[Phidget_Programming_Basics#Opening_the_Phidget|Programming Basics]] page.

== Troubleshooting ==

When using the Network Server, both the '''client and server should have the ''same version''''' of the Network Server installed. The easiest way to ensure this is to update your libraries on both ends.

For other troubleshooting tips, try our General Troubleshooting page, in its [[General_Troubleshooting#Network_Server_Troubleshooting|Network Server section]].

=== Further Reading ===

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Phidget Network Server

2017-07-11T17:00:14Z

Chad: /* Using The Network Server */

[[Category:Programming]]
__TOC__

==General Overview==
The Phidget Network Server is a feature of Phidgets that makes it possible to control or interact with Phidgets connected to other computers. To understand how it works, let's first take a look at what a system looks like without the Network Server enabled:

[[Image:Phidgets_without_NetworkServer.jpg|link=|500px|right]]

Begin with a local computer with the Phidget software installed and a number of Phidgets and/or [[What_is_VINT?|VINT Hubs]] connected. Connected to the VINT Hubs could be VINT devices.

All of these connected Phidgets have various channels that can be attached, which would allow a program running on the local computer to control or read data from them.

Since the Network Server is disabled in this diagram, the local computer is the only one that will be able to access the connected Phidgets.

<br clear="all">

Enabling the Phidget Network Server will allow software on a remote computer to connect to the local computer and receive the list of available Phidget devices attached. The channels from the remote computer will appear to be local to the local computer.

[[Image:NetworkServer_PhidgetServer.jpg|link=|800px]]

Software can set the {{Code|IsLocal}} and {{Code|IsRemote}} properties of a channel to control if remote or local channels should be considered during matching.

Specifying '''IsLocal''' would instruct the Phidget software to only match Phidgets physically connected to the local computer.

Specifying '''IsRemote''' would instruct the Phidget software to only match Phidgets exported by a remote computer.

Phidget device channels normally can only be attached to a single user channel; however, device channels that are exported by the Phidget Network Server may attach to more than one remote user channel. There are some exceptions (for example motor controllers) where safety could be an issue.

[[Image:NetworkServer_Local_Remote.jpg|link=|800px]]

As can be see in this example, there is a Phidget with four channels connected to a local computer. The local computer has enabled the Phidget Network Server. When the local computer attaches to channel 1, a remote computer is unable to attach to channel 1; furthermore, the local computer cannot attach a second user channel to channel 1 using the network server because channel 1 is already attached locally. On the other hand, both computers are able to attach to channel 2 remotely, because channel 2 hasn't been attached locally by the local computer. Both the local computer and the remote computer could attach several user channels to channel 2.

==Using The Network Server==

Each Operating System page has a section on how to use the Phidget Network Server:

* [[OS - Windows#Phidget Network Server|Windows]]
* [[OS - OS X#Phidget Network Server|Mac OS]]
* [[OS - Linux#Phidget Network Server|Linux]]
* [[OS - Phidget SBC#Phidget Network Server|Linux on the Phidget SBC]]
* [[OS - iOS#Phidget Network Server|iPhone/iPad iOS]]

The OS pages have examples of how to set up the Phidget Network Server and how to use it to remotely control and gather data from Phidgets. The OS pages also describe how to start and stop the Phidget Network Server, and how to run it with or without mDNS (Bonjour, avahi, etc).

== Connecting to a Network Server ==

There are two ways to gain access to a Phidget server that's being hosted on your network. If the server is broadcasting itself on mDNS, you can simply enable automatic server discovery in your program. In C#, for example, you would call the {{Code|Net.EnableServerDiscovery(ServerType.Device)}} method in your program. '''Net''' is the object that is used for Phidget Networking. You can find a full list of methods and properties in the {{Phidget22API}} by selecting "Networking API" in the drop-down menu.

If the Phidget server is not broadcasting itself on mDNS, you can connect to it by adding it specifically. In C#, for example, you would do this by calling the {{Code|Net.AddServer()}} method. AddServer takes a number of parameters that help specify the server to connect to (e.g. IP address, port, password). For more details on how to use AddServer, take a look at the "Networking API" in the {{Phidget22API}}.

==Network Server on a Phidget Single Board Computer==

The Phidget Single Board Computer (SBC) can provide a compact, inexpensive way to easily run the Network Server. It runs the Network Server in the background automatically from the moment you turn it on, and allows you to read from and control all Phidgets attached to it:

[[Image:network_server_sbc.jpg|link=|900px]]

In this example, a Phidget SBC physically connected to a VINT Hub which is connected to a VINT device. The SBC itself has its own channels corresponding to the on-board ports it has. By using the network server, it makes all of these channels available to any device connected to the same wireless network.

This is convenient because it allows the Phidgets and sensors to be in a remote location, like mounted on a wall or inside some kind of assembly, rather than sitting on your computer desk. The channels of this system could be conveniently accessed by a home computer on the network, a phone running some Phidgets code, or even another Phidget SBC in a different location.

The SBC runs Linux, which provides a [[OS - Phidget SBC|full operating system]] on which to develop code, {{ARTICLE|WebPageOnSBC|serve web pages}}, and {{ARTICLE|PhidgetsWirelesslyWithSBC|control Phidgets}}.

For more information on controlling Phidgets with your phone, have a look at the mobile section of our [[Software_Overview#Language_Support|languages]] page, or read {{ARTICLE|MurvRobotIOS|this article}} where we use [[OS_-_iOS|iOS]] to control a robot full of Phidgets.

== Examples ==
Below are some quick examples showing how simple it is to open a Phidget remotely over the Network Server. In each example, a light sensor Phidget is being remotely opened on port 0 of a VINT Hub with serial number 37299.

{{hiddenh3|C/C++}}

<syntaxhighlight lang=cpp>
PhidgetLightSensorHandle ch;
PhidgetLightSensor_create(&ch);

Phidget_setDeviceSerialNumber((PhidgetHandle) ch, 37299);
Phidget_setHubPort((PhidgetHandle) ch, 0);
Phidget_setIsRemote((PhidgetHandle) ch, 1);

Phidget_open((PhidgetHandle) ch);

</syntaxhighlight>

{{hiddenh3|C#}}

<syntaxhighlight lang='CSharp'>
LightSensor ch = new LightSensor();

ch.DeviceSerialNumber = 37299;
ch.HubPort = 0;
ch.IsRemote = true;

ch.Open();

</syntaxhighlight>

{{hiddenh3|Java}}

<syntaxhighlight lang='Java'>
LightSensor ch = new LightSensor();

ch.setDeviceSerialNumber(37299);
ch.setHubPort(0);
ch.setIsRemote(true);

ch.open();

</syntaxhighlight>

{{hiddenh3|Python}}

<syntaxhighlight lang='python'>
ch = LightSensor()

ch.setDeviceSerialNumber(37299)
ch.setHubPort(0)
ch.setIsRemote(1)

ch.open();

</syntaxhighlight>

For more information, have a look at the {{Phidget22API}} and select your language from the drop-down menu. You can learn more about opening Phidgets on the [[Phidget_Programming_Basics#Opening_the_Phidget|Programming Basics]] page.

== Troubleshooting ==

When using the Network Server, both the '''client and server should have the ''same version''''' of the Network Server installed. The easiest way to ensure this is to update your libraries on both ends.

For other troubleshooting tips, try our General Troubleshooting page, in its [[General_Troubleshooting#Network_Server_Troubleshooting|Network Server section]].

=== Further Reading ===

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Phidget Network Server

2017-07-11T16:59:17Z

Chad: /* Using The Network Server */

[[Category:Programming]]
__TOC__

==General Overview==
The Phidget Network Server is a feature of Phidgets that makes it possible to control or interact with Phidgets connected to other computers. To understand how it works, let's first take a look at what a system looks like without the Network Server enabled:

[[Image:Phidgets_without_NetworkServer.jpg|link=|500px|right]]

Begin with a local computer with the Phidget software installed and a number of Phidgets and/or [[What_is_VINT?|VINT Hubs]] connected. Connected to the VINT Hubs could be VINT devices.

All of these connected Phidgets have various channels that can be attached, which would allow a program running on the local computer to control or read data from them.

Since the Network Server is disabled in this diagram, the local computer is the only one that will be able to access the connected Phidgets.

<br clear="all">

Enabling the Phidget Network Server will allow software on a remote computer to connect to the local computer and receive the list of available Phidget devices attached. The channels from the remote computer will appear to be local to the local computer.

[[Image:NetworkServer_PhidgetServer.jpg|link=|800px]]

Software can set the {{Code|IsLocal}} and {{Code|IsRemote}} properties of a channel to control if remote or local channels should be considered during matching.

Specifying '''IsLocal''' would instruct the Phidget software to only match Phidgets physically connected to the local computer.

Specifying '''IsRemote''' would instruct the Phidget software to only match Phidgets exported by a remote computer.

Phidget device channels normally can only be attached to a single user channel; however, device channels that are exported by the Phidget Network Server may attach to more than one remote user channel. There are some exceptions (for example motor controllers) where safety could be an issue.

[[Image:NetworkServer_Local_Remote.jpg|link=|800px]]

As can be see in this example, there is a Phidget with four channels connected to a local computer. The local computer has enabled the Phidget Network Server. When the local computer attaches to channel 1, a remote computer is unable to attach to channel 1; furthermore, the local computer cannot attach a second user channel to channel 1 using the network server because channel 1 is already attached locally. On the other hand, both computers are able to attach to channel 2 remotely, because channel 2 hasn't been attached locally by the local computer. Both the local computer and the remote computer could attach several user channels to channel 2.

==Using The Network Server==

Each Operating System page has a section on how to use the Phidget Network Server:

* [[OS - Windows#Phidget Network Server|Windows]]
* [[OS - OS X#Phidget Network Server|Mac OS]]
* [[OS - Linux#Phidget Network Server|Linux]]
* [[OS - Phidget SBC#Phidget Network Server|Linux on the Phidget SBC]]
* [[OS - iOS#Phidget Network Server|iPhone/iPad iOS]]

The OS pages have examples of how to set up the Phidget Network Server and how to using it to remotely control and gather data from Phidgets. The pages also tell you how to start and stop the Phidget Network Server on your computer, and how to run it with or without mDNS (Bonjour, avahi, etc).

== Connecting to a Network Server ==

There are two ways to gain access to a Phidget server that's being hosted on your network. If the server is broadcasting itself on mDNS, you can simply enable automatic server discovery in your program. In C#, for example, you would call the {{Code|Net.EnableServerDiscovery(ServerType.Device)}} method in your program. '''Net''' is the object that is used for Phidget Networking. You can find a full list of methods and properties in the {{Phidget22API}} by selecting "Networking API" in the drop-down menu.

If the Phidget server is not broadcasting itself on mDNS, you can connect to it by adding it specifically. In C#, for example, you would do this by calling the {{Code|Net.AddServer()}} method. AddServer takes a number of parameters that help specify the server to connect to (e.g. IP address, port, password). For more details on how to use AddServer, take a look at the "Networking API" in the {{Phidget22API}}.

==Network Server on a Phidget Single Board Computer==

The Phidget Single Board Computer (SBC) can provide a compact, inexpensive way to easily run the Network Server. It runs the Network Server in the background automatically from the moment you turn it on, and allows you to read from and control all Phidgets attached to it:

[[Image:network_server_sbc.jpg|link=|900px]]

In this example, a Phidget SBC physically connected to a VINT Hub which is connected to a VINT device. The SBC itself has its own channels corresponding to the on-board ports it has. By using the network server, it makes all of these channels available to any device connected to the same wireless network.

This is convenient because it allows the Phidgets and sensors to be in a remote location, like mounted on a wall or inside some kind of assembly, rather than sitting on your computer desk. The channels of this system could be conveniently accessed by a home computer on the network, a phone running some Phidgets code, or even another Phidget SBC in a different location.

The SBC runs Linux, which provides a [[OS - Phidget SBC|full operating system]] on which to develop code, {{ARTICLE|WebPageOnSBC|serve web pages}}, and {{ARTICLE|PhidgetsWirelesslyWithSBC|control Phidgets}}.

For more information on controlling Phidgets with your phone, have a look at the mobile section of our [[Software_Overview#Language_Support|languages]] page, or read {{ARTICLE|MurvRobotIOS|this article}} where we use [[OS_-_iOS|iOS]] to control a robot full of Phidgets.

== Examples ==
Below are some quick examples showing how simple it is to open a Phidget remotely over the Network Server. In each example, a light sensor Phidget is being remotely opened on port 0 of a VINT Hub with serial number 37299.

{{hiddenh3|C/C++}}

<syntaxhighlight lang=cpp>
PhidgetLightSensorHandle ch;
PhidgetLightSensor_create(&ch);

Phidget_setDeviceSerialNumber((PhidgetHandle) ch, 37299);
Phidget_setHubPort((PhidgetHandle) ch, 0);
Phidget_setIsRemote((PhidgetHandle) ch, 1);

Phidget_open((PhidgetHandle) ch);

</syntaxhighlight>

{{hiddenh3|C#}}

<syntaxhighlight lang='CSharp'>
LightSensor ch = new LightSensor();

ch.DeviceSerialNumber = 37299;
ch.HubPort = 0;
ch.IsRemote = true;

ch.Open();

</syntaxhighlight>

{{hiddenh3|Java}}

<syntaxhighlight lang='Java'>
LightSensor ch = new LightSensor();

ch.setDeviceSerialNumber(37299);
ch.setHubPort(0);
ch.setIsRemote(true);

ch.open();

</syntaxhighlight>

{{hiddenh3|Python}}

<syntaxhighlight lang='python'>
ch = LightSensor()

ch.setDeviceSerialNumber(37299)
ch.setHubPort(0)
ch.setIsRemote(1)

ch.open();

</syntaxhighlight>

For more information, have a look at the {{Phidget22API}} and select your language from the drop-down menu. You can learn more about opening Phidgets on the [[Phidget_Programming_Basics#Opening_the_Phidget|Programming Basics]] page.

== Troubleshooting ==

When using the Network Server, both the '''client and server should have the ''same version''''' of the Network Server installed. The easiest way to ensure this is to update your libraries on both ends.

For other troubleshooting tips, try our General Troubleshooting page, in its [[General_Troubleshooting#Network_Server_Troubleshooting|Network Server section]].

=== Further Reading ===

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Phidget Network Server

2017-07-11T16:56:08Z

Chad: /* General Overview */

[[Category:Programming]]
__TOC__

==General Overview==
The Phidget Network Server is a feature of Phidgets that makes it possible to control or interact with Phidgets connected to other computers. To understand how it works, let's first take a look at what a system looks like without the Network Server enabled:

[[Image:Phidgets_without_NetworkServer.jpg|link=|500px|right]]

Begin with a local computer with the Phidget software installed and a number of Phidgets and/or [[What_is_VINT?|VINT Hubs]] connected. Connected to the VINT Hubs could be VINT devices.

All of these connected Phidgets have various channels that can be attached, which would allow a program running on the local computer to control or read data from them.

Since the Network Server is disabled in this diagram, the local computer is the only one that will be able to access the connected Phidgets.

<br clear="all">

Enabling the Phidget Network Server will allow software on a remote computer to connect to the local computer and receive the list of available Phidget devices attached. The channels from the remote computer will appear to be local to the local computer.

[[Image:NetworkServer_PhidgetServer.jpg|link=|800px]]

Software can set the {{Code|IsLocal}} and {{Code|IsRemote}} properties of a channel to control if remote or local channels should be considered during matching.

Specifying '''IsLocal''' would instruct the Phidget software to only match Phidgets physically connected to the local computer.

Specifying '''IsRemote''' would instruct the Phidget software to only match Phidgets exported by a remote computer.

Phidget device channels normally can only be attached to a single user channel; however, device channels that are exported by the Phidget Network Server may attach to more than one remote user channel. There are some exceptions (for example motor controllers) where safety could be an issue.

[[Image:NetworkServer_Local_Remote.jpg|link=|800px]]

As can be see in this example, there is a Phidget with four channels connected to a local computer. The local computer has enabled the Phidget Network Server. When the local computer attaches to channel 1, a remote computer is unable to attach to channel 1; furthermore, the local computer cannot attach a second user channel to channel 1 using the network server because channel 1 is already attached locally. On the other hand, both computers are able to attach to channel 2 remotely, because channel 2 hasn't been attached locally by the local computer. Both the local computer and the remote computer could attach several user channels to channel 2.

==Using The Network Server==

Each Operating System page has a section on how to use the Network Server on that operating system:

* [[OS - Windows#Phidget Network Server|Windows]]
* [[OS - OS X#Phidget Network Server|Mac OS]]
* [[OS - Linux#Phidget Network Server|Linux]]
* [[OS - Phidget SBC#Phidget Network Server|Linux on the Phidget SBC]]
* [[OS - iOS#Phidget Network Server|iPhone/iPad iOS]]

The operating systems pages have complete examples on how to set up a network server process and using it to remotely control or gather data from Phidgets. The pages also tell you how to start and stop the Network Server on your computer, and how to run it with or without mDNS (Bonjour, avahi, etc).

== Connecting to a Network Server ==

There are two ways to gain access to a Phidget server that's being hosted on your network. If the server is broadcasting itself on mDNS, you can simply enable automatic server discovery in your program. In C#, for example, you would call the {{Code|Net.EnableServerDiscovery(ServerType.Device)}} method in your program. '''Net''' is the object that is used for Phidget Networking. You can find a full list of methods and properties in the {{Phidget22API}} by selecting "Networking API" in the drop-down menu.

If the Phidget server is not broadcasting itself on mDNS, you can connect to it by adding it specifically. In C#, for example, you would do this by calling the {{Code|Net.AddServer()}} method. AddServer takes a number of parameters that help specify the server to connect to (e.g. IP address, port, password). For more details on how to use AddServer, take a look at the "Networking API" in the {{Phidget22API}}.

==Network Server on a Phidget Single Board Computer==

The Phidget Single Board Computer (SBC) can provide a compact, inexpensive way to easily run the Network Server. It runs the Network Server in the background automatically from the moment you turn it on, and allows you to read from and control all Phidgets attached to it:

[[Image:network_server_sbc.jpg|link=|900px]]

In this example, a Phidget SBC physically connected to a VINT Hub which is connected to a VINT device. The SBC itself has its own channels corresponding to the on-board ports it has. By using the network server, it makes all of these channels available to any device connected to the same wireless network.

This is convenient because it allows the Phidgets and sensors to be in a remote location, like mounted on a wall or inside some kind of assembly, rather than sitting on your computer desk. The channels of this system could be conveniently accessed by a home computer on the network, a phone running some Phidgets code, or even another Phidget SBC in a different location.

The SBC runs Linux, which provides a [[OS - Phidget SBC|full operating system]] on which to develop code, {{ARTICLE|WebPageOnSBC|serve web pages}}, and {{ARTICLE|PhidgetsWirelesslyWithSBC|control Phidgets}}.

For more information on controlling Phidgets with your phone, have a look at the mobile section of our [[Software_Overview#Language_Support|languages]] page, or read {{ARTICLE|MurvRobotIOS|this article}} where we use [[OS_-_iOS|iOS]] to control a robot full of Phidgets.

== Examples ==
Below are some quick examples showing how simple it is to open a Phidget remotely over the Network Server. In each example, a light sensor Phidget is being remotely opened on port 0 of a VINT Hub with serial number 37299.

{{hiddenh3|C/C++}}

<syntaxhighlight lang=cpp>
PhidgetLightSensorHandle ch;
PhidgetLightSensor_create(&ch);

Phidget_setDeviceSerialNumber((PhidgetHandle) ch, 37299);
Phidget_setHubPort((PhidgetHandle) ch, 0);
Phidget_setIsRemote((PhidgetHandle) ch, 1);

Phidget_open((PhidgetHandle) ch);

</syntaxhighlight>

{{hiddenh3|C#}}

<syntaxhighlight lang='CSharp'>
LightSensor ch = new LightSensor();

ch.DeviceSerialNumber = 37299;
ch.HubPort = 0;
ch.IsRemote = true;

ch.Open();

</syntaxhighlight>

{{hiddenh3|Java}}

<syntaxhighlight lang='Java'>
LightSensor ch = new LightSensor();

ch.setDeviceSerialNumber(37299);
ch.setHubPort(0);
ch.setIsRemote(true);

ch.open();

</syntaxhighlight>

{{hiddenh3|Python}}

<syntaxhighlight lang='python'>
ch = LightSensor()

ch.setDeviceSerialNumber(37299)
ch.setHubPort(0)
ch.setIsRemote(1)

ch.open();

</syntaxhighlight>

For more information, have a look at the {{Phidget22API}} and select your language from the drop-down menu. You can learn more about opening Phidgets on the [[Phidget_Programming_Basics#Opening_the_Phidget|Programming Basics]] page.

== Troubleshooting ==

When using the Network Server, both the '''client and server should have the ''same version''''' of the Network Server installed. The easiest way to ensure this is to update your libraries on both ends.

For other troubleshooting tips, try our General Troubleshooting page, in its [[General_Troubleshooting#Network_Server_Troubleshooting|Network Server section]].

=== Further Reading ===

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Phidget Network Server

2017-07-11T16:53:24Z

Chad: /* General Overview */

[[Category:Programming]]
__TOC__

==General Overview==
The Phidget Network Server is a feature of Phidgets that makes it possible to control or interact with Phidgets connected to other computers. To understand how it works, let's first take a look at what a system looks like without the Network Server enabled:

[[Image:Phidgets_without_NetworkServer.jpg|link=|500px|right]]

Begin with a local computer with the Phidget software installed and a number of Phidgets and/or [[What_is_VINT?|VINT Hubs]] connected. Connected to the VINT Hubs could be VINT devices.

All of these connected Phidgets have various channels that can be attached, which would allow a program running on the local computer to control or read data from them.

Since the Network Server is disabled in this diagram, the local computer is the only one that will be able to access the connected Phidgets.

<br clear="all">

Enabling the Phidget Network Server will allow software on a remote computer to connect to the local computer and receive the list of available Phidget devices attached. The channels from the remote computer will appear to be local to the local computer.

[[Image:NetworkServer_PhidgetServer.jpg|link=|800px]]

Software can set the {{Code|IsLocal}} and {{Code|IsRemote}} properties of a channel to control if remote or local channels should be considered during matching.

Specifying '''IsLocal''' would instruct the Phidget software to only match Phidgets physically connected to the local computer.

Specifying '''IsRemote''' would instruct the Phidget software to only match Phidgets exported by a remote computer.

Phidget device channels normally can only be attached to a single user channel; however, device channels that are exported by the Phidget Network Server may attach to more than one remote user channel. There are some exceptions (for example motor controllers) where safety could be an issue.

[[Image:NetworkServer_Local_Remote.jpg|link=|800px]]

As can be see in this example, there is a Phidget with four channels connected to a local computer. When the local computer attaches to channel 1, a remote computer is unable to attach to channel 1; furthermore, the local computer cannot attach a second user channel to channel 1 using the network server because channel 1 is already attached locally. On the other hand, both computers are able to attach to channel 2 remotely, because channel 2 hasn't been attached locally by the local computer. Both the local computer and the remote computer could attach several user channels to channel 2.

==Using The Network Server==

Each Operating System page has a section on how to use the Network Server on that operating system:

* [[OS - Windows#Phidget Network Server|Windows]]
* [[OS - OS X#Phidget Network Server|Mac OS]]
* [[OS - Linux#Phidget Network Server|Linux]]
* [[OS - Phidget SBC#Phidget Network Server|Linux on the Phidget SBC]]
* [[OS - iOS#Phidget Network Server|iPhone/iPad iOS]]

The operating systems pages have complete examples on how to set up a network server process and using it to remotely control or gather data from Phidgets. The pages also tell you how to start and stop the Network Server on your computer, and how to run it with or without mDNS (Bonjour, avahi, etc).

== Connecting to a Network Server ==

There are two ways to gain access to a Phidget server that's being hosted on your network. If the server is broadcasting itself on mDNS, you can simply enable automatic server discovery in your program. In C#, for example, you would call the {{Code|Net.EnableServerDiscovery(ServerType.Device)}} method in your program. '''Net''' is the object that is used for Phidget Networking. You can find a full list of methods and properties in the {{Phidget22API}} by selecting "Networking API" in the drop-down menu.

If the Phidget server is not broadcasting itself on mDNS, you can connect to it by adding it specifically. In C#, for example, you would do this by calling the {{Code|Net.AddServer()}} method. AddServer takes a number of parameters that help specify the server to connect to (e.g. IP address, port, password). For more details on how to use AddServer, take a look at the "Networking API" in the {{Phidget22API}}.

==Network Server on a Phidget Single Board Computer==

The Phidget Single Board Computer (SBC) can provide a compact, inexpensive way to easily run the Network Server. It runs the Network Server in the background automatically from the moment you turn it on, and allows you to read from and control all Phidgets attached to it:

[[Image:network_server_sbc.jpg|link=|900px]]

In this example, a Phidget SBC physically connected to a VINT Hub which is connected to a VINT device. The SBC itself has its own channels corresponding to the on-board ports it has. By using the network server, it makes all of these channels available to any device connected to the same wireless network.

This is convenient because it allows the Phidgets and sensors to be in a remote location, like mounted on a wall or inside some kind of assembly, rather than sitting on your computer desk. The channels of this system could be conveniently accessed by a home computer on the network, a phone running some Phidgets code, or even another Phidget SBC in a different location.

The SBC runs Linux, which provides a [[OS - Phidget SBC|full operating system]] on which to develop code, {{ARTICLE|WebPageOnSBC|serve web pages}}, and {{ARTICLE|PhidgetsWirelesslyWithSBC|control Phidgets}}.

For more information on controlling Phidgets with your phone, have a look at the mobile section of our [[Software_Overview#Language_Support|languages]] page, or read {{ARTICLE|MurvRobotIOS|this article}} where we use [[OS_-_iOS|iOS]] to control a robot full of Phidgets.

== Examples ==
Below are some quick examples showing how simple it is to open a Phidget remotely over the Network Server. In each example, a light sensor Phidget is being remotely opened on port 0 of a VINT Hub with serial number 37299.

{{hiddenh3|C/C++}}

<syntaxhighlight lang=cpp>
PhidgetLightSensorHandle ch;
PhidgetLightSensor_create(&ch);

Phidget_setDeviceSerialNumber((PhidgetHandle) ch, 37299);
Phidget_setHubPort((PhidgetHandle) ch, 0);
Phidget_setIsRemote((PhidgetHandle) ch, 1);

Phidget_open((PhidgetHandle) ch);

</syntaxhighlight>

{{hiddenh3|C#}}

<syntaxhighlight lang='CSharp'>
LightSensor ch = new LightSensor();

ch.DeviceSerialNumber = 37299;
ch.HubPort = 0;
ch.IsRemote = true;

ch.Open();

</syntaxhighlight>

{{hiddenh3|Java}}

<syntaxhighlight lang='Java'>
LightSensor ch = new LightSensor();

ch.setDeviceSerialNumber(37299);
ch.setHubPort(0);
ch.setIsRemote(true);

ch.open();

</syntaxhighlight>

{{hiddenh3|Python}}

<syntaxhighlight lang='python'>
ch = LightSensor()

ch.setDeviceSerialNumber(37299)
ch.setHubPort(0)
ch.setIsRemote(1)

ch.open();

</syntaxhighlight>

For more information, have a look at the {{Phidget22API}} and select your language from the drop-down menu. You can learn more about opening Phidgets on the [[Phidget_Programming_Basics#Opening_the_Phidget|Programming Basics]] page.

== Troubleshooting ==

When using the Network Server, both the '''client and server should have the ''same version''''' of the Network Server installed. The easiest way to ensure this is to update your libraries on both ends.

For other troubleshooting tips, try our General Troubleshooting page, in its [[General_Troubleshooting#Network_Server_Troubleshooting|Network Server section]].

=== Further Reading ===

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

What is a Phidget?

2017-07-11T16:29:03Z

Chad: /* Network Server */

[[Category:Overview]]

==Introduction==
Phidgets are building-blocks for sensing and control using a computer, tablet, or phone. Users create applications that use Phidgets to interact with the physical world. Phidgets connect via a USB port:
[[Image:wiap-image1.jpg|500px|link=|alt=|center]]

----

Some Phidgets are a complete, self-contained sensing package. An example is then [{{SERVER}}/products.php?product_id=1042 1042]
, which measures motion:
[[Image:wiap-image2-spatial.jpg|500px|link=|alt=|center]]

----

Other Phidgets are a 'building block' to use other sensors. An example is the [{{SERVER}}/products.php?product_id=1048 1048] which allows the use of wire thermocouples:
[[Image:wiap-image2-temp.jpg|700px|link=|alt=|center]]

----

Another Phidget may be a flexible I/O board which can receive analog sensor data and control digital inputs and outputs. An example is the [{{SERVER}}/products.php?product_id=1018 1018], with eight ports of each type:
[[Image:wiap-image2-ifkt.jpg|700px|link=|alt=|center]]

----

Finally, a Phidget may be a [{{SERVER}}/products.php?product_id=HUB0000 VINT Hub], made up of versatile ports that can be used as inputs or outputs, and also connect to smart [[What_is_VINT?|VINT]] devices.
[[Image:wiap-vint.jpg|700px|link=|alt=|center]]

==Data Flow==

Data and control flows up and down the USB connection:
[[Image:wiap-dataflow.jpg|700px|link=|alt=|center]]

== Software Channels ==

A Phidget device exports one or more channels. Each device channel implements a channel class where that class defines the interface used to access the features of the device in a generic fashion. For example, a Phidget device that supports sensing voltage exports a channel that implements the VoltageInput class. The VoltageInput class defines the methods, properties, events and errors relevant to receiving voltage data.

[[Image:voltageInput_object.jpg|300px|link=|alt=|center]]

You can check the {{Phidget22API}} for details about channel classes. For example, the [{{SERVER}}/products.php?product_id=1018 1018] has five channels (with five distinct channel classes):
[[Image:1018_objects.jpg|600px|link=|alt=|center]]

Each Phidget channel class inherits common functionality from the base Phidget class. The Phidget class defines methods like {{Code|open()}} and {{Code|close()}}, and properties like {{Code|DeviceSerialNumber}}.

To help understand the concepts above, we have included a simple C# program that can be used with the [{{SERVER}}/products.php?product_id=1018 1018].

<syntaxhighlight lang=csharp>
using Phidget22;

int main() {
VoltageInput vin; // A user channel of the class VoltageInput

vin = new VoltageInput(); // Create an instance of the class
vin.Channel = 0; // Specify the index of the device channel to attach to
vin.Open(5000); // Begin attempting to attach to the device channel

System.Console.WriteLine("My channel 0 sensor reads " + vin.Voltage); // Get the voltage value

vin.Close(); // Close the channel, which detached it from the device channel
}
</syntaxhighlight>

==Programming==

For the most part, using Phidgets requires writing software. The {{Phidget22API}} is available in many different programming languages:

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

|'''Core Languages''' || |'''Mobile Languages''' || |'''Other Languages'''
|-
|[[Image:Icon-CSharp.png|alt=C Sharp|24x24px|link=Language - C Sharp]] [[Language - C Sharp|C#]] || [[Image:Icon-ObjC.png|24x24px|alt=Objective C|link=Language - Objective C]] [[Language - Objective C|Objective C]] || [[Image:Icon-LabVIEW.png|alt=LabVIEW|24x24px|link=Language - LabVIEW]] [[Language - LabVIEW|LabVIEW]]
|-
|[[Image:Icon-C++.png|alt=C/C++|24x24px|link=Language - C/C++]] [[Language - C/C++|C/C++]] || |[[Image:Icon-Swift.png|alt=Swift|24x24px|link=Language - Swift]] [[Language - Swift|Swift]] || |[[Image:Icon-MaxMSP.png|24x24px|alt=Max/MSP|link=Language - Max/MSP]] [[Language - Max/MSP|Max/MSP]]
|-
|[[Image:Icon-Python.png|alt=Python|24x24px|link=Language - Python]] [[Language - Python|Python]]
|-
|[[Image:Icon-Java.png|alt=Java|24x24px|link=Language - Java]] [[Language - Java|Java]]
|-
|[[Image:Icon-Visual Basic Net.png|alt=Visual Basic .NET|24x24px|link=Language - Visual Basic .NET]] [[Language - Visual Basic .NET|Visual Basic .NET]]
|-
|[[Image:Icon-Javascript.png|alt=JavaScript|24x24px|link=Language - JavaScript]] [[Language - JavaScript|JavaScript]]
|-
|}

The Phidget software libraries are supported on a number of operating systems:
{| style="border:1px solid darkgray;" cellpadding="7px;"
|-style="background: #f0f0f0" align=center
|-

|'''Desktop OSes''' || |'''Mobile/Wireless OSes'''
|-
|[[Image:Icon-Windows.png|alt=OS - Windows|24x24px|link=OS - Windows]][[OS - Windows|Windows]] || |[[Image:Icon-Linux.png|alt=OS - Phidget SBC|24x24px|link=OS_-_Phidget_SBC]][[OS_-_Phidget_SBC|Phidget SBC]]
|-
|[[Image:Icon-Linux.png|alt=OS - Linux|24x24px|link=OS - Linux]][[OS - Linux|Linux]] || [[Image:Icon-iOS.png|alt=OS - iOS|link=OS - iOS|24x24px|link=OS - iOS]][[OS - iOS|iOS]]
|-
|[[Image:Icon-Mac-OS.png|alt=OS - OS X|24x24px|link=OS - OS X]][[OS - OS X|OS X]] 
|}

== Network Server ==

Phidget devices can be accessed remotely by using the [[Phidget Network Server]]. The Network Server exports the channels of each attached Phidget over the network:
[[Image:NetworkServer_PhidgetServer.jpg|link=|800px|center]]

Using the {{Phidget22API}}, clients on remote computers, phones, and [[OS_-_Phidget_SBC|Single Board Computers]] can attach to Phidget devices as if they were local. This includes WWW based applications using the Phidget JavaScript library.

== Further Reading ==
With the combination of events, modular sensors, and network support, your system can range from simple to incredibly complex.

We encourage customers to not only build projects for themselves, but also to design and build real-world products using Phidgets. Our libraries can be distributed with your code to your customers.

And this can all occur with the same devices, and the same flexible software API.

Want to learn more? Check out our:
* [{{SERVER}} Products on our main website]
* [[Software Overview | Languages and Operating Systems]]
* [{{SERVER}}/?view=articles Example Projects and Articles]
* [[:Category:Primer|In-depth hardware information]]

Questions? Please {{ContactUs|contact us}}.

What is a Phidget?

2017-07-11T16:22:56Z

Chad:

[[Category:Overview]]

==Introduction==
Phidgets are building-blocks for sensing and control using a computer, tablet, or phone. Users create applications that use Phidgets to interact with the physical world. Phidgets connect via a USB port:
[[Image:wiap-image1.jpg|500px|link=|alt=|center]]

----

Some Phidgets are a complete, self-contained sensing package. An example is then [{{SERVER}}/products.php?product_id=1042 1042]
, which measures motion:
[[Image:wiap-image2-spatial.jpg|500px|link=|alt=|center]]

----

Other Phidgets are a 'building block' to use other sensors. An example is the [{{SERVER}}/products.php?product_id=1048 1048] which allows the use of wire thermocouples:
[[Image:wiap-image2-temp.jpg|700px|link=|alt=|center]]

----

Another Phidget may be a flexible I/O board which can receive analog sensor data and control digital inputs and outputs. An example is the [{{SERVER}}/products.php?product_id=1018 1018], with eight ports of each type:
[[Image:wiap-image2-ifkt.jpg|700px|link=|alt=|center]]

----

Finally, a Phidget may be a [{{SERVER}}/products.php?product_id=HUB0000 VINT Hub], made up of versatile ports that can be used as inputs or outputs, and also connect to smart [[What_is_VINT?|VINT]] devices.
[[Image:wiap-vint.jpg|700px|link=|alt=|center]]

==Data Flow==

Data and control flows up and down the USB connection:
[[Image:wiap-dataflow.jpg|700px|link=|alt=|center]]

== Software Channels ==

A Phidget device exports one or more channels. Each device channel implements a channel class where that class defines the interface used to access the features of the device in a generic fashion. For example, a Phidget device that supports sensing voltage exports a channel that implements the VoltageInput class. The VoltageInput class defines the methods, properties, events and errors relevant to receiving voltage data.

[[Image:voltageInput_object.jpg|300px|link=|alt=|center]]

You can check the {{Phidget22API}} for details about channel classes. For example, the [{{SERVER}}/products.php?product_id=1018 1018] has five channels (with five distinct channel classes):
[[Image:1018_objects.jpg|600px|link=|alt=|center]]

Each Phidget channel class inherits common functionality from the base Phidget class. The Phidget class defines methods like {{Code|open()}} and {{Code|close()}}, and properties like {{Code|DeviceSerialNumber}}.

To help understand the concepts above, we have included a simple C# program that can be used with the [{{SERVER}}/products.php?product_id=1018 1018].

<syntaxhighlight lang=csharp>
using Phidget22;

int main() {
VoltageInput vin; // A user channel of the class VoltageInput

vin = new VoltageInput(); // Create an instance of the class
vin.Channel = 0; // Specify the index of the device channel to attach to
vin.Open(5000); // Begin attempting to attach to the device channel

System.Console.WriteLine("My channel 0 sensor reads " + vin.Voltage); // Get the voltage value

vin.Close(); // Close the channel, which detached it from the device channel
}
</syntaxhighlight>

==Programming==

For the most part, using Phidgets requires writing software. The {{Phidget22API}} is available in many different programming languages:

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

|'''Core Languages''' || |'''Mobile Languages''' || |'''Other Languages'''
|-
|[[Image:Icon-CSharp.png|alt=C Sharp|24x24px|link=Language - C Sharp]] [[Language - C Sharp|C#]] || [[Image:Icon-ObjC.png|24x24px|alt=Objective C|link=Language - Objective C]] [[Language - Objective C|Objective C]] || [[Image:Icon-LabVIEW.png|alt=LabVIEW|24x24px|link=Language - LabVIEW]] [[Language - LabVIEW|LabVIEW]]
|-
|[[Image:Icon-C++.png|alt=C/C++|24x24px|link=Language - C/C++]] [[Language - C/C++|C/C++]] || |[[Image:Icon-Swift.png|alt=Swift|24x24px|link=Language - Swift]] [[Language - Swift|Swift]] || |[[Image:Icon-MaxMSP.png|24x24px|alt=Max/MSP|link=Language - Max/MSP]] [[Language - Max/MSP|Max/MSP]]
|-
|[[Image:Icon-Python.png|alt=Python|24x24px|link=Language - Python]] [[Language - Python|Python]]
|-
|[[Image:Icon-Java.png|alt=Java|24x24px|link=Language - Java]] [[Language - Java|Java]]
|-
|[[Image:Icon-Visual Basic Net.png|alt=Visual Basic .NET|24x24px|link=Language - Visual Basic .NET]] [[Language - Visual Basic .NET|Visual Basic .NET]]
|-
|[[Image:Icon-Javascript.png|alt=JavaScript|24x24px|link=Language - JavaScript]] [[Language - JavaScript|JavaScript]]
|-
|}

The Phidget software libraries are supported on a number of operating systems:
{| style="border:1px solid darkgray;" cellpadding="7px;"
|-style="background: #f0f0f0" align=center
|-

|'''Desktop OSes''' || |'''Mobile/Wireless OSes'''
|-
|[[Image:Icon-Windows.png|alt=OS - Windows|24x24px|link=OS - Windows]][[OS - Windows|Windows]] || |[[Image:Icon-Linux.png|alt=OS - Phidget SBC|24x24px|link=OS_-_Phidget_SBC]][[OS_-_Phidget_SBC|Phidget SBC]]
|-
|[[Image:Icon-Linux.png|alt=OS - Linux|24x24px|link=OS - Linux]][[OS - Linux|Linux]] || [[Image:Icon-iOS.png|alt=OS - iOS|link=OS - iOS|24x24px|link=OS - iOS]][[OS - iOS|iOS]]
|-
|[[Image:Icon-Mac-OS.png|alt=OS - OS X|24x24px|link=OS - OS X]][[OS - OS X|OS X]] 
|}

== Network Server ==
Not only can you control a Phidget locally, but we also provide a tool called the [[Phidget Network Server]]. The Network Server exports your Phidget's channels over your local network:
[[Image:NetworkServer_PhidgetServer.jpg|link=|800px|center]]

This allows other computers on your network to control the Phidget or read data from it. The network server isn't limited to desktop computers- it can also be used with phones or [[OS_-_Phidget_SBC|Single Board Computers]] that are running Phidgets code.

The Network Server also includes the [[Phidget Dictionary]], which is a central place to store your data in key-value pairs.

== Further Reading ==
With the combination of events, modular sensors, and network support, your system can range from simple to incredibly complex.

We encourage customers to not only build projects for themselves, but also to design and build real-world products using Phidgets. Our libraries can be distributed with your code to your customers.

And this can all occur with the same devices, and the same flexible software API.

Want to learn more? Check out our:
* [{{SERVER}} Products on our main website]
* [[Software Overview | Languages and Operating Systems]]
* [{{SERVER}}/?view=articles Example Projects and Articles]
* [[:Category:Primer|In-depth hardware information]]

Questions? Please {{ContactUs|contact us}}.

Phidget Programming Basics

2017-07-11T15:45:10Z

Chad: /* Sensors, Input, and Output */

[[Category:Programming]]
__TOC__

It is important to understand what a Phidget is, and how the hardware and software relate to one another before writing software using the {{Phidget22API}}. Please refer to [[What is a Phidget?]] for an introduction.

The Phidget software library matches a Phidget device channel with a software channel that is created by a user.
Software channels are each of a class, where that class defines a set of methods, properties, events and errors. Phidget devices are aware of the channel classes, and expose access to features of the device through the class interface.

To use a Phidget, you'll want to:
# '''[[#Creating a Channel|Create]]''' an instance of the channel class that provides access to the device you want to control.
# '''[[#Opening a Channel|Open]]''' the channel.
# Detect when the channel is '''[[#Attaching a Channel|attached]]''' to the Phidget.
# Use '''[[#Do Things with a Channel|methods and properties]]''' of the attached channel.
# '''[[#Close a Channel|Close]]''' the channel.

Small code snippets are provided for each step in the sections below. [[Language - Java|Java]] and [[Language - C/C++|C]] were selected because Java is a high-level language and C is a low level language. The best reference to the ''features'' each channel class is the {{Phidget22API}} for your specific language. This page is intended to be a high-level introduction.

== Creating a Channel ==

A Phidget device exposes one or more device channels where each channel is an interface to a feature of the hardware. A channel class defines an interface to control and query a channel of the Phidget device. For example, a 1018 - Phidget InterfaceKit device includes support
for digital input and digital out, and therefore exports <code>DigitalInput</code> and <code>DigitalOutput</code> channels.

Phidget devices are controlled by creating an instance of a Phidget channel class. Each channel class has a function that allows you to '''create''' an instance, and a function to later '''delete''' the instance.

For example, in Java:

<syntaxhighlight lang=java>
// Create a new Accelerometer channel
Accelerometer accel = new Accelerometer();
</syntaxhighlight>
<syntaxhighlight lang=java>
// Create a new RFID channel
RFID rfid = new RFID();
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
// Create a new Accelerometer channel
PhidgetAccelerometerHandle accel;
PhidgetAccelerometer_create(&accel);
</syntaxhighlight>
<syntaxhighlight lang=c>
// Create a new RFID channel
PhidgetRFIDHandle rfid;
PhidgetRFID_create(&rfid);
</syntaxhighlight>

A channel class will have properties and methods specific to the feature they belong to. For example, the <code>VoltageInput</code> class has a <code>Voltage</code> property that lets you access the current voltage measured by the device, the <code>Accelerometer</code> class has properties to set the sensitivity on each axis and the <code>RFID</code> has a method that writes to a writable RFID tag.

== Opening a Channel ==

After you have created a [[#Creating a Channel| channel instance]], you can call the <code>open()</code> method to begin the process of matching the channel to a Phidget device channel.

For example, with the <code>Accelerometer</code> channel in Java:

<syntaxhighlight lang=java>
accel.open();
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
Phidget_open((PhidgetHandle) accel);
</syntaxhighlight>

To see how to use <code>open()</code> in other languages, please refer to the {{Phidget22API}}.

The <code>open()</code> function begins the process of matching the channel handle you created to a channel of a Phidget device, and does not actually ''open'' the Phidget itself. An open channel may match a new Phidget device when it is plugged in if that channel has not already found a Phidget device channel that meets its criteria.

===Details for Open()===

Because <code>open()</code> simply enables the process of matching a channel to a Phidget device channel, <code>open()</code> returns immediately and does not wait for the channel to attach to a Phidget device channel. The channel changes state to ''open'', but is not necessarily ''attached''. Until the channel actually becomes ''attached'' to a Phidget device channel, most of the channel class interface will not be available.

As long as the channel is open (and not ''attached''), the system will continue to try to match it with a
Phidget device channel that has not already been matched with a channel. The channel can only be matched once, and the Phidget device channel can only be matched once. For example, if you connected a single Phidget Accelerometer to a computer, and you created and opened two <code>Accelerometer</code> channels, only one of the channels would attach while the other would remain ''open'' but not ''attached''. If the ''attached'' channel were to be closed, the other channel would then attach to the Accelerometer.

When the channels is matched with a Phidget device channel, the channel state is changed to ''attached'' and an event is fired.

'''Note:''' Once a Phidget device channel is matched to a channel, it will not be available to match another channel until the first channel is closed. The one exception is if the Phidget device channel is ''attached'' over the network through the [[Phidget Network Server]]. In that case, multiple channels are allowed to match and attach to the Phidget device channel. Some Phidgets, such as motor controllers will never match more than one channel at a time.

===Channel Matching===

<code>open()</code> can be used without specifying any matching properties. In this case the system will match a channel with the first Phidget device channel that matches the channel class. The channel class itself is an implied matching parameter.

If there is more than one Phidget connected to the computer that supports the channel class, the <code>DeviceSerialNumber</code> property must be set determine which Phidget will match.

If the Phidget connected to the computer has more than one channel of the same classes, the <code>Channel</code> property must be set to determine which Phidget device channel will match.

If the Phidget Network Server is enabled on the computer, the <code>IsRemote</code> and <code>IsLocal</code> properties can be used to determine if the channel will match the Phidget device channel or the network channel.

Please refer to the {{Phidget22API}}, and [[Best Phidgets Practices|Best Practices]] for more information on matching channels to Phidget device channels.

==== Opening a Channel on a USB Phidget ====

[[Image:channel-matching-1.jpg|link=|500px]]

In this example, a [{{SERVER}}/products.php?product_id=1018 1018 PhidgetInterfaceKit 8/8/8] is connected to a computer. A [{{SERVER}}/products.php?product_id=1108 1108 Magnetic Sensor] is connected to analog port 3 on the 1018. Here's how you would open the channel for the magnetic sensor in Java:

<syntaxhighlight lang=java>
VoltageRatioInput ch = new VoltageRatioInput();
ch.setDeviceSerialNumber(324781);
ch.setChannel(3);
ch.open();
</syntaxhighlight>

If you wanted to open digital input 5 in the same example, it would look like this:

<syntaxhighlight lang=java>
DigitalInput ch = new DigitalInput();
ch.setDeviceSerialNumber(324781);
ch.setChannel(5);
ch.open();
</syntaxhighlight>

==== Opening a VINT Hub Port as a Channel ====

The ports on a [[What is VINT?|VINT]] Hub can be opened as Digital Inputs, Digital Outputs, Voltage Inputs, or Voltage Ratio Inputs. Suppose you had a [{{SERVER}}/products.php?product_id=HUB0000 HUB0000 VINT Hub] with a [{{SERVER}}/products.php?product_id=1133 1133 Sound Sensor] connected to its sixth port.

[[Image:channel-matching-2.jpg|link=|500px]]

Here's how you would open it in Java:

<syntaxhighlight lang=java>
VoltageInput ch = new VoltageInput();
ch.setDeviceSerialNumber(370181);
ch.setIsHubPortDevice(true);
ch.setHubPort(6);
ch.open();
</syntaxhighlight>

==== Opening a Channel on a VINT Device ====

In this example, we have a [{{SERVER}}/products.php?product_id=TMP1101 TMP1101 4x Thermocouple Phidget] and a [{{SERVER}}/products.php?product_id=HUB0000 HUB0000 VINT Hub].

[[Image:channel-matching-3.jpg|link=|500px]]

If we wanted to open both the thermocouple connected to port 0 and the integrated temperature sensor on the board, we first need to figure out which channels those are. Go to the [{{SERVER}}/products.php?product_id=TMP1101 product page for the TMP1101] and click on the API tab. From the table at the top of the tab, we can see that the integrated temperature sensor is TemperatureSensor channel 4. In Java, opening these channels would look like this:

<syntaxhighlight lang=java>
TemperatureSensor tc = new TemperatureSensor(); // Handle for the thermocouple
TemperatureSensor ic = new TemperatureSensor(); // Handle for the integrated temperature chip

tc.setDeviceSerialNumber();
ic.setDeviceSerialNumber();
tc.setHubPort(2);
ic.setHubPort(2);
tc.setChannel(0);
ic.setChannel(4);

tc.open();
ic.open();
</syntaxhighlight>

==== Opening a Channel on a Remote Phidget ====

Suppose you wanted to open a locally connected Phidget remotely over the Network Service, so that you could have multiple programs connecting to it at the same time. In this example, we have a [{{SERVER}}/products.php?product_id=1024 1024 PhidgetRFID] connected to a computer that has the Phidget Network Server enabled.

[[Image:channel-matching-4.jpg|link=|600px]]

You could open the RFID reader channel remotely with the following code in Java:

<syntaxhighlight lang=java>
RFID ch = new RFID();
ch.setDeviceSerialNumber(388624);
ch.setIsRemote(true);
ch.open();
</syntaxhighlight>

== Attaching a Channel ==

When a channel is open (and not ''attached''), the system will continue to try to match it with a
Phidget device channel until either a match is found, or the channel is closed. When the channels is matched with a Phidget device channel, the channel state is changed to ''attached'' and an event is fired.

An event handler can be registered to catch the ''attach event'' through the channel's <code>Attach</code> event. Each channel also has a <code>Attached</code> property that can be read to determine if the class has
been matched to a Phidget device channel.

To set an event handler to detect the attach in Java:

<syntaxhighlight lang=java>
//create a Phidget accelerometer channel:
Accelerometer accel = new Accelerometer();
accel.addAttachListener((AttachEvent ae) -> {
Accelerometer accel = (Accelerometer) ae.getSource();
// Do things after attachment (i.e. read data, control the device)
}
});
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
// Define the attach handler function
void CCONV onAttachedEventHandler(PhidgetHandle channel, void *userPtr) {
printf("A channel has been attached\n");
// Do things after attachment (i.e. read data, control the device)
}

int main() {
// .....Then, in the main code create the channel and set the attach handler:
PhidgetAccelerometerHandle accel;
PhidgetAccelerometer_create(&accel);
Phidget_setOnAttachHandler((PhidgetHandle)accel, onAttachedEventHandler, NULL);

// other stuff in main
}
</syntaxhighlight>

You should set the attach event handler '''before''' you <code>open()</code> the channel; otherwise, you may miss attach event if it occurs between opening the channel and setting the handler.

== Do Things with a Channel ==

After a channel has been ''opened'' and ''attached'', software can control the Phidget device via the channel class interface.

Like setting an event handler that executes [[#Attaching a Channel|when the channels is attached]], handlers can be set to receive events when a state change occurs, or sensor data is received.

A Voltage Input channel for example, like one supported by the [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit], can set an event handler that gets called as the voltage is processed.

In Java, this would look like:

<syntaxhighlight lang=java>
// After creating and opening a VoltageInput channel called "sensorIn"
sensorIn.addVoltageChangeListener((VoltageInputVoltageChangeEvent de) -> {
System.out.println("Voltage: " + de.getVoltage());
});
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
void CCONV
onVoltageChangeHandler(PhidgetVoltageInputHandle voltageInput, void *ctx, double voltage) {
printf("Voltage: %lf V\n", voltage);
}

// .....Then, in the main code:
// After creating and opening a VoltageInput channel called "sensorIn"
PhidgetVoltageInput_setOnVoltageChangeHandler(sensorIn, onVoltageChangeHandler, NULL);
</syntaxhighlight>

The voltage value delivered in the above snippets could also be accessed via the <code>Voltage</code> property of the channel. Properties that have related events are automatically updated each time the event is received by the channel, and calls between events always return the value set by the last event.

<syntaxhighlight lang=java>
double val = sensorIn.getVoltage();
</syntaxhighlight>

Or, in C:

<syntaxhighlight lang=c>
double val;
PhidgetVoltageInput_getVoltage(sensorIn, &val);
</syntaxhighlight>

===Sensors, Input, and Output===

Often, your Phidget will support more than one channel class. For example a [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit] has voltage inputs (black sensor ports), digital inputs and digital outputs (green terminal blocks). You can determine the channel classes supported by your Phidget from the product page and the {{Phidget22API}}.

For InterfaceKits like the 1018:

* To the voltage inputs, you can attach various sensors (temperature, humidity, light, sound)
* To the digital inputs, you can attach various input devices (switches)
* To the digital outputs, you can attach simple indicators (LEDs, buzzers, relays)

The features and channels supported by each Phidget are many and varied, and we only include general concepts on this page. You can view the complete list of channels supported by a Phidget in the {{Phidget22API}}. Select a device at the top of the screen, select your preferred programming language, and then select which channel class you want to view the documentation for.

== Close a Channel ==

When you are finished with a channel, you should close and (in some languages) delete it. Once closed, the Phidget device channel the channel was matched to will be released and made available for another channel to match.

For example, in Java:

<syntaxhighlight lang=java>
device.close();
device = null;
</syntaxhighlight>

Or, in C:

<syntaxhighlight lang=c>
Phidget_close((PhidgetHandle)channel);
Phidget_release((PhidgetHandle)&channel); // will NULL the pointer
</syntaxhighlight>

== Further Reading ==

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - How to know you are attaching to the Phidget you want.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Phidget Programming Basics

2017-07-11T15:43:43Z

Chad: /* Do Things with a Channel */

[[Category:Programming]]
__TOC__

It is important to understand what a Phidget is, and how the hardware and software relate to one another before writing software using the {{Phidget22API}}. Please refer to [[What is a Phidget?]] for an introduction.

The Phidget software library matches a Phidget device channel with a software channel that is created by a user.
Software channels are each of a class, where that class defines a set of methods, properties, events and errors. Phidget devices are aware of the channel classes, and expose access to features of the device through the class interface.

To use a Phidget, you'll want to:
# '''[[#Creating a Channel|Create]]''' an instance of the channel class that provides access to the device you want to control.
# '''[[#Opening a Channel|Open]]''' the channel.
# Detect when the channel is '''[[#Attaching a Channel|attached]]''' to the Phidget.
# Use '''[[#Do Things with a Channel|methods and properties]]''' of the attached channel.
# '''[[#Close a Channel|Close]]''' the channel.

Small code snippets are provided for each step in the sections below. [[Language - Java|Java]] and [[Language - C/C++|C]] were selected because Java is a high-level language and C is a low level language. The best reference to the ''features'' each channel class is the {{Phidget22API}} for your specific language. This page is intended to be a high-level introduction.

== Creating a Channel ==

A Phidget device exposes one or more device channels where each channel is an interface to a feature of the hardware. A channel class defines an interface to control and query a channel of the Phidget device. For example, a 1018 - Phidget InterfaceKit device includes support
for digital input and digital out, and therefore exports <code>DigitalInput</code> and <code>DigitalOutput</code> channels.

Phidget devices are controlled by creating an instance of a Phidget channel class. Each channel class has a function that allows you to '''create''' an instance, and a function to later '''delete''' the instance.

For example, in Java:

<syntaxhighlight lang=java>
// Create a new Accelerometer channel
Accelerometer accel = new Accelerometer();
</syntaxhighlight>
<syntaxhighlight lang=java>
// Create a new RFID channel
RFID rfid = new RFID();
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
// Create a new Accelerometer channel
PhidgetAccelerometerHandle accel;
PhidgetAccelerometer_create(&accel);
</syntaxhighlight>
<syntaxhighlight lang=c>
// Create a new RFID channel
PhidgetRFIDHandle rfid;
PhidgetRFID_create(&rfid);
</syntaxhighlight>

A channel class will have properties and methods specific to the feature they belong to. For example, the <code>VoltageInput</code> class has a <code>Voltage</code> property that lets you access the current voltage measured by the device, the <code>Accelerometer</code> class has properties to set the sensitivity on each axis and the <code>RFID</code> has a method that writes to a writable RFID tag.

== Opening a Channel ==

After you have created a [[#Creating a Channel| channel instance]], you can call the <code>open()</code> method to begin the process of matching the channel to a Phidget device channel.

For example, with the <code>Accelerometer</code> channel in Java:

<syntaxhighlight lang=java>
accel.open();
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
Phidget_open((PhidgetHandle) accel);
</syntaxhighlight>

To see how to use <code>open()</code> in other languages, please refer to the {{Phidget22API}}.

The <code>open()</code> function begins the process of matching the channel handle you created to a channel of a Phidget device, and does not actually ''open'' the Phidget itself. An open channel may match a new Phidget device when it is plugged in if that channel has not already found a Phidget device channel that meets its criteria.

===Details for Open()===

Because <code>open()</code> simply enables the process of matching a channel to a Phidget device channel, <code>open()</code> returns immediately and does not wait for the channel to attach to a Phidget device channel. The channel changes state to ''open'', but is not necessarily ''attached''. Until the channel actually becomes ''attached'' to a Phidget device channel, most of the channel class interface will not be available.

As long as the channel is open (and not ''attached''), the system will continue to try to match it with a
Phidget device channel that has not already been matched with a channel. The channel can only be matched once, and the Phidget device channel can only be matched once. For example, if you connected a single Phidget Accelerometer to a computer, and you created and opened two <code>Accelerometer</code> channels, only one of the channels would attach while the other would remain ''open'' but not ''attached''. If the ''attached'' channel were to be closed, the other channel would then attach to the Accelerometer.

When the channels is matched with a Phidget device channel, the channel state is changed to ''attached'' and an event is fired.

'''Note:''' Once a Phidget device channel is matched to a channel, it will not be available to match another channel until the first channel is closed. The one exception is if the Phidget device channel is ''attached'' over the network through the [[Phidget Network Server]]. In that case, multiple channels are allowed to match and attach to the Phidget device channel. Some Phidgets, such as motor controllers will never match more than one channel at a time.

===Channel Matching===

<code>open()</code> can be used without specifying any matching properties. In this case the system will match a channel with the first Phidget device channel that matches the channel class. The channel class itself is an implied matching parameter.

If there is more than one Phidget connected to the computer that supports the channel class, the <code>DeviceSerialNumber</code> property must be set determine which Phidget will match.

If the Phidget connected to the computer has more than one channel of the same classes, the <code>Channel</code> property must be set to determine which Phidget device channel will match.

If the Phidget Network Server is enabled on the computer, the <code>IsRemote</code> and <code>IsLocal</code> properties can be used to determine if the channel will match the Phidget device channel or the network channel.

Please refer to the {{Phidget22API}}, and [[Best Phidgets Practices|Best Practices]] for more information on matching channels to Phidget device channels.

==== Opening a Channel on a USB Phidget ====

[[Image:channel-matching-1.jpg|link=|500px]]

In this example, a [{{SERVER}}/products.php?product_id=1018 1018 PhidgetInterfaceKit 8/8/8] is connected to a computer. A [{{SERVER}}/products.php?product_id=1108 1108 Magnetic Sensor] is connected to analog port 3 on the 1018. Here's how you would open the channel for the magnetic sensor in Java:

<syntaxhighlight lang=java>
VoltageRatioInput ch = new VoltageRatioInput();
ch.setDeviceSerialNumber(324781);
ch.setChannel(3);
ch.open();
</syntaxhighlight>

If you wanted to open digital input 5 in the same example, it would look like this:

<syntaxhighlight lang=java>
DigitalInput ch = new DigitalInput();
ch.setDeviceSerialNumber(324781);
ch.setChannel(5);
ch.open();
</syntaxhighlight>

==== Opening a VINT Hub Port as a Channel ====

The ports on a [[What is VINT?|VINT]] Hub can be opened as Digital Inputs, Digital Outputs, Voltage Inputs, or Voltage Ratio Inputs. Suppose you had a [{{SERVER}}/products.php?product_id=HUB0000 HUB0000 VINT Hub] with a [{{SERVER}}/products.php?product_id=1133 1133 Sound Sensor] connected to its sixth port.

[[Image:channel-matching-2.jpg|link=|500px]]

Here's how you would open it in Java:

<syntaxhighlight lang=java>
VoltageInput ch = new VoltageInput();
ch.setDeviceSerialNumber(370181);
ch.setIsHubPortDevice(true);
ch.setHubPort(6);
ch.open();
</syntaxhighlight>

==== Opening a Channel on a VINT Device ====

In this example, we have a [{{SERVER}}/products.php?product_id=TMP1101 TMP1101 4x Thermocouple Phidget] and a [{{SERVER}}/products.php?product_id=HUB0000 HUB0000 VINT Hub].

[[Image:channel-matching-3.jpg|link=|500px]]

If we wanted to open both the thermocouple connected to port 0 and the integrated temperature sensor on the board, we first need to figure out which channels those are. Go to the [{{SERVER}}/products.php?product_id=TMP1101 product page for the TMP1101] and click on the API tab. From the table at the top of the tab, we can see that the integrated temperature sensor is TemperatureSensor channel 4. In Java, opening these channels would look like this:

<syntaxhighlight lang=java>
TemperatureSensor tc = new TemperatureSensor(); // Handle for the thermocouple
TemperatureSensor ic = new TemperatureSensor(); // Handle for the integrated temperature chip

tc.setDeviceSerialNumber();
ic.setDeviceSerialNumber();
tc.setHubPort(2);
ic.setHubPort(2);
tc.setChannel(0);
ic.setChannel(4);

tc.open();
ic.open();
</syntaxhighlight>

==== Opening a Channel on a Remote Phidget ====

Suppose you wanted to open a locally connected Phidget remotely over the Network Service, so that you could have multiple programs connecting to it at the same time. In this example, we have a [{{SERVER}}/products.php?product_id=1024 1024 PhidgetRFID] connected to a computer that has the Phidget Network Server enabled.

[[Image:channel-matching-4.jpg|link=|600px]]

You could open the RFID reader channel remotely with the following code in Java:

<syntaxhighlight lang=java>
RFID ch = new RFID();
ch.setDeviceSerialNumber(388624);
ch.setIsRemote(true);
ch.open();
</syntaxhighlight>

== Attaching a Channel ==

When a channel is open (and not ''attached''), the system will continue to try to match it with a
Phidget device channel until either a match is found, or the channel is closed. When the channels is matched with a Phidget device channel, the channel state is changed to ''attached'' and an event is fired.

An event handler can be registered to catch the ''attach event'' through the channel's <code>Attach</code> event. Each channel also has a <code>Attached</code> property that can be read to determine if the class has
been matched to a Phidget device channel.

To set an event handler to detect the attach in Java:

<syntaxhighlight lang=java>
//create a Phidget accelerometer channel:
Accelerometer accel = new Accelerometer();
accel.addAttachListener((AttachEvent ae) -> {
Accelerometer accel = (Accelerometer) ae.getSource();
// Do things after attachment (i.e. read data, control the device)
}
});
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
// Define the attach handler function
void CCONV onAttachedEventHandler(PhidgetHandle channel, void *userPtr) {
printf("A channel has been attached\n");
// Do things after attachment (i.e. read data, control the device)
}

int main() {
// .....Then, in the main code create the channel and set the attach handler:
PhidgetAccelerometerHandle accel;
PhidgetAccelerometer_create(&accel);
Phidget_setOnAttachHandler((PhidgetHandle)accel, onAttachedEventHandler, NULL);

// other stuff in main
}
</syntaxhighlight>

You should set the attach event handler '''before''' you <code>open()</code> the channel; otherwise, you may miss attach event if it occurs between opening the channel and setting the handler.

== Do Things with a Channel ==

After a channel has been ''opened'' and ''attached'', software can control the Phidget device via the channel class interface.

Like setting an event handler that executes [[#Attaching a Channel|when the channels is attached]], handlers can be set to receive events when a state change occurs, or sensor data is received.

A Voltage Input channel for example, like one supported by the [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit], can set an event handler that gets called as the voltage is processed.

In Java, this would look like:

<syntaxhighlight lang=java>
// After creating and opening a VoltageInput channel called "sensorIn"
sensorIn.addVoltageChangeListener((VoltageInputVoltageChangeEvent de) -> {
System.out.println("Voltage: " + de.getVoltage());
});
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
void CCONV
onVoltageChangeHandler(PhidgetVoltageInputHandle voltageInput, void *ctx, double voltage) {
printf("Voltage: %lf V\n", voltage);
}

// .....Then, in the main code:
// After creating and opening a VoltageInput channel called "sensorIn"
PhidgetVoltageInput_setOnVoltageChangeHandler(sensorIn, onVoltageChangeHandler, NULL);
</syntaxhighlight>

The voltage value delivered in the above snippets could also be accessed via the <code>Voltage</code> property of the channel. Properties that have related events are automatically updated each time the event is received by the channel, and calls between events always return the value set by the last event.

<syntaxhighlight lang=java>
double val = sensorIn.getVoltage();
</syntaxhighlight>

Or, in C:

<syntaxhighlight lang=c>
double val;
PhidgetVoltageInput_getVoltage(sensorIn, &val);
</syntaxhighlight>

===Sensors, Input, and Output===

Often, your Phidget support more than one channel class. For example a [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit] has voltage inputs (black sensor ports), digital inputs and digital outputs (green terminal blocks). You can determine the channel classes supported by your Phidget from the product page and the {{Phidget22API}}.

For InterfaceKits like the 1018:

* To the voltage inputs, you can attach various sensors (temperature, humidity, light, sound)
* To the digital inputs, you can attach various input devices (switches)
* To the digital outputs, you can attach simple indicators (LEDs, buzzers, relays)

The features and channels supported by each Phidget are many and varied, and we only include general concepts on this page. You can view the complete list of channels supported by a Phidget in the {{Phidget22API}}. Select a device at the top of the screen, select your preferred programming language, and then select which channel class you want to view the documentation for.

== Close a Channel ==

When you are finished with a channel, you should close and (in some languages) delete it. Once closed, the Phidget device channel the channel was matched to will be released and made available for another channel to match.

For example, in Java:

<syntaxhighlight lang=java>
device.close();
device = null;
</syntaxhighlight>

Or, in C:

<syntaxhighlight lang=c>
Phidget_close((PhidgetHandle)channel);
Phidget_release((PhidgetHandle)&channel); // will NULL the pointer
</syntaxhighlight>

== Further Reading ==

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - How to know you are attaching to the Phidget you want.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Phidget Programming Basics

2017-07-11T15:42:06Z

Chad:

[[Category:Programming]]
__TOC__

It is important to understand what a Phidget is, and how the hardware and software relate to one another before writing software using the {{Phidget22API}}. Please refer to [[What is a Phidget?]] for an introduction.

The Phidget software library matches a Phidget device channel with a software channel that is created by a user.
Software channels are each of a class, where that class defines a set of methods, properties, events and errors. Phidget devices are aware of the channel classes, and expose access to features of the device through the class interface.

To use a Phidget, you'll want to:
# '''[[#Creating a Channel|Create]]''' an instance of the channel class that provides access to the device you want to control.
# '''[[#Opening a Channel|Open]]''' the channel.
# Detect when the channel is '''[[#Attaching a Channel|attached]]''' to the Phidget.
# Use '''[[#Do Things with a Channel|methods and properties]]''' of the attached channel.
# '''[[#Close a Channel|Close]]''' the channel.

Small code snippets are provided for each step in the sections below. [[Language - Java|Java]] and [[Language - C/C++|C]] were selected because Java is a high-level language and C is a low level language. The best reference to the ''features'' each channel class is the {{Phidget22API}} for your specific language. This page is intended to be a high-level introduction.

== Creating a Channel ==

A Phidget device exposes one or more device channels where each channel is an interface to a feature of the hardware. A channel class defines an interface to control and query a channel of the Phidget device. For example, a 1018 - Phidget InterfaceKit device includes support
for digital input and digital out, and therefore exports <code>DigitalInput</code> and <code>DigitalOutput</code> channels.

Phidget devices are controlled by creating an instance of a Phidget channel class. Each channel class has a function that allows you to '''create''' an instance, and a function to later '''delete''' the instance.

For example, in Java:

<syntaxhighlight lang=java>
// Create a new Accelerometer channel
Accelerometer accel = new Accelerometer();
</syntaxhighlight>
<syntaxhighlight lang=java>
// Create a new RFID channel
RFID rfid = new RFID();
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
// Create a new Accelerometer channel
PhidgetAccelerometerHandle accel;
PhidgetAccelerometer_create(&accel);
</syntaxhighlight>
<syntaxhighlight lang=c>
// Create a new RFID channel
PhidgetRFIDHandle rfid;
PhidgetRFID_create(&rfid);
</syntaxhighlight>

A channel class will have properties and methods specific to the feature they belong to. For example, the <code>VoltageInput</code> class has a <code>Voltage</code> property that lets you access the current voltage measured by the device, the <code>Accelerometer</code> class has properties to set the sensitivity on each axis and the <code>RFID</code> has a method that writes to a writable RFID tag.

== Opening a Channel ==

After you have created a [[#Creating a Channel| channel instance]], you can call the <code>open()</code> method to begin the process of matching the channel to a Phidget device channel.

For example, with the <code>Accelerometer</code> channel in Java:

<syntaxhighlight lang=java>
accel.open();
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
Phidget_open((PhidgetHandle) accel);
</syntaxhighlight>

To see how to use <code>open()</code> in other languages, please refer to the {{Phidget22API}}.

The <code>open()</code> function begins the process of matching the channel handle you created to a channel of a Phidget device, and does not actually ''open'' the Phidget itself. An open channel may match a new Phidget device when it is plugged in if that channel has not already found a Phidget device channel that meets its criteria.

===Details for Open()===

Because <code>open()</code> simply enables the process of matching a channel to a Phidget device channel, <code>open()</code> returns immediately and does not wait for the channel to attach to a Phidget device channel. The channel changes state to ''open'', but is not necessarily ''attached''. Until the channel actually becomes ''attached'' to a Phidget device channel, most of the channel class interface will not be available.

As long as the channel is open (and not ''attached''), the system will continue to try to match it with a
Phidget device channel that has not already been matched with a channel. The channel can only be matched once, and the Phidget device channel can only be matched once. For example, if you connected a single Phidget Accelerometer to a computer, and you created and opened two <code>Accelerometer</code> channels, only one of the channels would attach while the other would remain ''open'' but not ''attached''. If the ''attached'' channel were to be closed, the other channel would then attach to the Accelerometer.

When the channels is matched with a Phidget device channel, the channel state is changed to ''attached'' and an event is fired.

'''Note:''' Once a Phidget device channel is matched to a channel, it will not be available to match another channel until the first channel is closed. The one exception is if the Phidget device channel is ''attached'' over the network through the [[Phidget Network Server]]. In that case, multiple channels are allowed to match and attach to the Phidget device channel. Some Phidgets, such as motor controllers will never match more than one channel at a time.

===Channel Matching===

<code>open()</code> can be used without specifying any matching properties. In this case the system will match a channel with the first Phidget device channel that matches the channel class. The channel class itself is an implied matching parameter.

If there is more than one Phidget connected to the computer that supports the channel class, the <code>DeviceSerialNumber</code> property must be set determine which Phidget will match.

If the Phidget connected to the computer has more than one channel of the same classes, the <code>Channel</code> property must be set to determine which Phidget device channel will match.

If the Phidget Network Server is enabled on the computer, the <code>IsRemote</code> and <code>IsLocal</code> properties can be used to determine if the channel will match the Phidget device channel or the network channel.

Please refer to the {{Phidget22API}}, and [[Best Phidgets Practices|Best Practices]] for more information on matching channels to Phidget device channels.

==== Opening a Channel on a USB Phidget ====

[[Image:channel-matching-1.jpg|link=|500px]]

In this example, a [{{SERVER}}/products.php?product_id=1018 1018 PhidgetInterfaceKit 8/8/8] is connected to a computer. A [{{SERVER}}/products.php?product_id=1108 1108 Magnetic Sensor] is connected to analog port 3 on the 1018. Here's how you would open the channel for the magnetic sensor in Java:

<syntaxhighlight lang=java>
VoltageRatioInput ch = new VoltageRatioInput();
ch.setDeviceSerialNumber(324781);
ch.setChannel(3);
ch.open();
</syntaxhighlight>

If you wanted to open digital input 5 in the same example, it would look like this:

<syntaxhighlight lang=java>
DigitalInput ch = new DigitalInput();
ch.setDeviceSerialNumber(324781);
ch.setChannel(5);
ch.open();
</syntaxhighlight>

==== Opening a VINT Hub Port as a Channel ====

The ports on a [[What is VINT?|VINT]] Hub can be opened as Digital Inputs, Digital Outputs, Voltage Inputs, or Voltage Ratio Inputs. Suppose you had a [{{SERVER}}/products.php?product_id=HUB0000 HUB0000 VINT Hub] with a [{{SERVER}}/products.php?product_id=1133 1133 Sound Sensor] connected to its sixth port.

[[Image:channel-matching-2.jpg|link=|500px]]

Here's how you would open it in Java:

<syntaxhighlight lang=java>
VoltageInput ch = new VoltageInput();
ch.setDeviceSerialNumber(370181);
ch.setIsHubPortDevice(true);
ch.setHubPort(6);
ch.open();
</syntaxhighlight>

==== Opening a Channel on a VINT Device ====

In this example, we have a [{{SERVER}}/products.php?product_id=TMP1101 TMP1101 4x Thermocouple Phidget] and a [{{SERVER}}/products.php?product_id=HUB0000 HUB0000 VINT Hub].

[[Image:channel-matching-3.jpg|link=|500px]]

If we wanted to open both the thermocouple connected to port 0 and the integrated temperature sensor on the board, we first need to figure out which channels those are. Go to the [{{SERVER}}/products.php?product_id=TMP1101 product page for the TMP1101] and click on the API tab. From the table at the top of the tab, we can see that the integrated temperature sensor is TemperatureSensor channel 4. In Java, opening these channels would look like this:

<syntaxhighlight lang=java>
TemperatureSensor tc = new TemperatureSensor(); // Handle for the thermocouple
TemperatureSensor ic = new TemperatureSensor(); // Handle for the integrated temperature chip

tc.setDeviceSerialNumber();
ic.setDeviceSerialNumber();
tc.setHubPort(2);
ic.setHubPort(2);
tc.setChannel(0);
ic.setChannel(4);

tc.open();
ic.open();
</syntaxhighlight>

==== Opening a Channel on a Remote Phidget ====

Suppose you wanted to open a locally connected Phidget remotely over the Network Service, so that you could have multiple programs connecting to it at the same time. In this example, we have a [{{SERVER}}/products.php?product_id=1024 1024 PhidgetRFID] connected to a computer that has the Phidget Network Server enabled.

[[Image:channel-matching-4.jpg|link=|600px]]

You could open the RFID reader channel remotely with the following code in Java:

<syntaxhighlight lang=java>
RFID ch = new RFID();
ch.setDeviceSerialNumber(388624);
ch.setIsRemote(true);
ch.open();
</syntaxhighlight>

== Attaching a Channel ==

When a channel is open (and not ''attached''), the system will continue to try to match it with a
Phidget device channel until either a match is found, or the channel is closed. When the channels is matched with a Phidget device channel, the channel state is changed to ''attached'' and an event is fired.

An event handler can be registered to catch the ''attach event'' through the channel's <code>Attach</code> event. Each channel also has a <code>Attached</code> property that can be read to determine if the class has
been matched to a Phidget device channel.

To set an event handler to detect the attach in Java:

<syntaxhighlight lang=java>
//create a Phidget accelerometer channel:
Accelerometer accel = new Accelerometer();
accel.addAttachListener((AttachEvent ae) -> {
Accelerometer accel = (Accelerometer) ae.getSource();
// Do things after attachment (i.e. read data, control the device)
}
});
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
// Define the attach handler function
void CCONV onAttachedEventHandler(PhidgetHandle channel, void *userPtr) {
printf("A channel has been attached\n");
// Do things after attachment (i.e. read data, control the device)
}

int main() {
// .....Then, in the main code create the channel and set the attach handler:
PhidgetAccelerometerHandle accel;
PhidgetAccelerometer_create(&accel);
Phidget_setOnAttachHandler((PhidgetHandle)accel, onAttachedEventHandler, NULL);

// other stuff in main
}
</syntaxhighlight>

You should set the attach event handler '''before''' you <code>open()</code> the channel; otherwise, you may miss attach event if it occurs between opening the channel and setting the handler.

== Do Things with a Channel ==

After a channel has been ''opened'' and ''attached'', software can control the Phidget device via the channel class interface.

Like setting an event handler that executes [[#Attaching a Channel|when the channels is attached]], handlers can be set to receive events when a state change occurs, or sensor data is received.

A Voltage Input channel for example, like one supported by the [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit], can set an event handler that gets called as the voltage is processed.

In Java, this would look like:

<syntaxhighlight lang=java>
// After creating and opening a VoltageInput channel called "sensorIn"
sensorIn.addVoltageChangeListener((VoltageInputVoltageChangeEvent de) -> {
System.out.println("Voltage: " + de.getVoltage());
});
</syntaxhighlight>

Or in C:

<syntaxhighlight lang=c>
void CCONV onVoltageChangeHandler(PhidgetVoltageInputHandle voltageInput, void *userPtr, double voltage) {
printf("Voltage: %lf V\n", voltage);
}

// .....Then, in the main code:
// After creating and opening a VoltageInput channel called "sensorIn"
PhidgetVoltageInput_setOnVoltageChangeHandler(sensorIn, onVoltageChangeHandler, NULL);
</syntaxhighlight>

The voltage value delivered in the above snippets could also be accessed via the <code>Voltage</code> property of the channel. Properties that have related events are automatically updated each time the event is received by the channel, and calls between events always return the value set by the last event.

<syntaxhighlight lang=java>
double val = sensorIn.getVoltage();
</syntaxhighlight>

Or, in C:

<syntaxhighlight lang=c>
double val;
PhidgetVoltageInput_getVoltage(sensorIn, &val);
</syntaxhighlight>

===Sensors, Input, and Output===

Often, your Phidget support more than one channel class. For example a [{{SERVER}}/products.php?product_id=1018 1018 Phidget Interface Kit] has voltage inputs (black sensor ports), digital inputs and digital outputs (green terminal blocks). You can determine the channel classes supported by your Phidget from the product page and the {{Phidget22API}}.

For InterfaceKits like the 1018:

* To the voltage inputs, you can attach various sensors (temperature, humidity, light, sound)
* To the digital inputs, you can attach various input devices (switches)
* To the digital outputs, you can attach simple indicators (LEDs, buzzers, relays)

The features and channels supported by each Phidget are many and varied, and we only include general concepts on this page. You can view the complete list of channels supported by a Phidget in the {{Phidget22API}}. Select a device at the top of the screen, select your preferred programming language, and then select which channel class you want to view the documentation for.

== Close a Channel ==

When you are finished with a channel, you should close and (in some languages) delete it. Once closed, the Phidget device channel the channel was matched to will be released and made available for another channel to match.

For example, in Java:

<syntaxhighlight lang=java>
device.close();
device = null;
</syntaxhighlight>

Or, in C:

<syntaxhighlight lang=c>
Phidget_close((PhidgetHandle)channel);
Phidget_release((PhidgetHandle)&channel); // will NULL the pointer
</syntaxhighlight>

== Further Reading ==

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - How to know you are attaching to the Phidget you want.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.

[[Best Phidgets Practices]] - Good programming habits that will save you from common problems when writing code for your Phidgets.

Best Phidgets Practices

2017-07-10T18:21:46Z

Chad: /* Don't Forget to Close() */

[[Category:Programming]]
The purpose of this page is to provide you with a list of "Best Practices" to follow when writing code that uses Phidgets. These guidelines are especially important if your program is going to be used by people other than you, or on many different systems. If you follow these guidelines, you'll probably save yourself a few headaches in the future.

== Keep Event Handlers Short ==

User events handlers are called from special dispatch threads within the Phidget library. Each channel maintains its own queue of events, and these events are processed in order and one at a time. If a user event handler blocks, or takes longer than the <code>DataInterval</code> of the channel, events will become 'stale', and eventually the system will begin throwing away events.

For example, if an Accelerometer channel has been configured to receive data every 20 milliseconds and the event handler averages 21ms to execute, the next change event will be ready before the previous one is finished being processed. Eventually the channel's event queue will fill and the library will begin throwing away events.

A common mistake is to update a GUI, or wait for user input from within an event handler. Most GUI APIs have support for dispatching updates to the GUI thread, and those should be used. Waiting for user input will block the event handler, and should never be done. Instead, a flag should be set and a loop in the main of the program (or another thread) should wait for the input.

== Be Specific With Open() ==

When you use {{Code|Open()}} to access a Phidget device channel, the library will first try to match a channel of the class that you're using. There are a number of other matching properties can be set to further filter which device channel is matched. For example:

* The '''serial number''' of a device or VINT Hub
* The '''port''' a VINT device is plugged into
* The '''channel''' number of a device channel, when a device has multiple channels of the same class
* If a channel '''is remote''' or '''is local'''
* The '''server name''', if a device channel is being accessed over the [[Phidget Network Server]]

If none of the matching properties are set, the Phidget library will match the first channel of the same class. In simple cases this will be fine. For example, if a Phidget temperature sensor is the only device connected to a computer, opening a {{Code|TemperatureSensor}} channel without setting any matching properties will match that temperature sensor; however, if a DC motor controller is connected to the computer, the on-board temperature sensor on the motor control may match. Setting the {{Code|DeviceSerialNumber}} will force the channel to match the desired device channel.

Since there's no way to predict what other Phidgets may be plugged into a computer (or become available over the network), you should be as specific as possible before opening a channel.

== When In Doubt, Open Remotely ==
When the [[Phidget Network Server|Network Server]] is enabled, a channel can match both a local device channel and a remote channel. The end result would be the same as the same actual device channel would be attached; however, most remote channels support being attached to multiple clients, while a local device channel can only be attached once. Unless the desire is to only allow the device channel to be attached once, or performance is critical, it is more flexible to match the network channel.

See the <code>IsRemote</code> and <code>IsLocal</code> Phidget properties in the {{Phidget22API}}.

== Set Properties in the Attach Handler ==

An '''attach''' event will occur each time a channel is matched. This makes the attach handler the perfect place to initialize properties such as {{Code|DataInterval}}, {{Code|ChangeTrigger}}, gain values, and ranges. If properties are initialize elsewhere, in a situation where the channel detaches those properties will revert to defaults. Setting properties within the '''attach''' handler ensures they are always the expected values.

== Don't Forget to Close() ==

Calling {{Code|Close()}} on a channel releases the channel so that it can be matched again. In most cases, it's not technically necessary to call {{Code|Close()}} because when your program exits, the channel will be released; however, it is good practice to close a channel when you are finished with it as some environments will not release the channel automatically. For example in [[Language_-_LabVIEW|LabVIEW]], the runtime environment merely interprets your program, so if you do not call {{Code|Close()}}, the LabVIEW environment will continue to tie up the channel despite having stopped the program you're working on.

== Further Reading ==

[[Phidget Programming Basics]] - Here you can find the basic concepts to help you get started with making your own programs that use Phidgets.

[[Data Interval/Change Trigger]] - Learn about these two properties that control how much data comes in from your sensors.

[[Using Multiple Phidgets]] - It can be difficult to figure out how to use more than one Phidget in your program. This page will guide you through the steps.

[[Polling vs. Events]] - Your program can gather data in either a polling-driven or event-driven manner. Learn the difference to determine which is best for your application.

[[Logging, Exceptions, and Errors]] - Learn about all the tools you can use to debug your program.

[[Phidget Network Server]] - Phidgets can be controlled and communicated with over your network- either wirelessly or over ethernet.