Phidget Manager

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:

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.

You can find the complete API for the Phidget Manager in the Phidget22 API. 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:

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 getChannelClassName() (or the channelClassName 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 opened, then attached within your code. Here's an example of how the manager is used in 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);
}

For more sample code that uses the Phidget Manager, have a look at our "HelloWorld" programming examples, which are available for most of the languages we support.