Phidget Manager: Difference between revisions

From Phidgets Support
No edit summary
 
(9 intermediate revisions by 2 users not shown)
Line 2: Line 2:
==General 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.  
The Phidget Manager is an interface into the device channels available to the Phidget library.  The API is strictly asynchronous, and continuously monitors channels as they attach and detach.


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.
Each Phidget exports one or more device channels, and when a Phidget is plugged into a system (or becomes available over the network), a manager attach event is fired for each channel available from the Phidget.  When the Phidget is removed from the system, a manger detach event is fired for each channel that is no longer available.  


==Object Structure==
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 has ''appeared'', and 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 is not fired. A manager '''detach''' event is fired when the Phidget is removed from the system.
 
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==
==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:
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=]]
[[Image:manager22.jpg|link=|850px|alt=]]


==Using the Phidget Manager==


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.
Much like a Phidget channel, a Phidget Manager must be created and opened. Refer to the {{Phidget22API}} for details.


==Using the Phidget Manager==
As soon as a manager is opened the Phidget library will fire an event for each device channel that is currently know to the system.  After those initial events, '''attach''' and '''detach''' events will be fired when new Phidgets become available or existing Phidget are removed.


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:
In the C programming language, it is not safe to refer to a {{Code|PhidgetHandle}} after an event handler returns, unless {{Code|Phidget_retain()}} is first called ({{Code|Phidget_open()}} and {{Code|Phidget_close()}} retain and release handlers automatically).  The {{Code|PhidgetHandle}} must be released with {{Code|Phidget_release()}} if it has been retained. The object oriented languages supported in the {{Phidget22API}} automatically retain and release handles.


What follows is an example of how to use a manager in C:


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


    // Define the manager handle and create
static void CCONV
    PhidgetManagerHandle device = 0;
mgrAttachHandler(PhidgetManagerHandle mgr, void *ctx, PhidgetHandle mgrch) {
    PhidgetManager_create(&device);


    // Set up event handlers
    PhidgetLog_log("%P attached", mgrch);
    PhidgetManager_setOnAttachHandler(device, AttachHandler, NULL);
}
    PhidgetManager_setOnDetachHandler(device, DetachHandler, NULL);


    // Open the Phidget Manager
static void CCONV
    PhidgetManager_open(device);
mgrDetachHandler(PhidgetManagerHandle mgr, void *ctx, PhidgetHandle mgrch) {


    // Wait for attach/detach events
    PhidgetLog_log("%P detached", mgrch);
    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) {
int
 
main(int argc, char **argv) {
    const char *chanClass;
    PhidgetManagerHandle mgr;
    // 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
    PhidgetManager_create(&mgr);
          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:
    PhidgetManager_setOnAttachHandler(mgr, mgrAttachHandler, NULL);
    if(strcmp(chanClass,"PhidgetGyroscope") == 0) {
    PhidgetManager_setOnDetachHandler(mgr, mgrDetachHandler, NULL);


          // Cast the generic Phidget object into a Phidget Gyroscope object
    PhidgetManager_open(mgr);
          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:
    /* Do something long running, like run a GUI threads */
    if(strcmp(chanClass,"PhidgetMagnetometer") == 0) {
 
    /* Now close and delete the manager */
          // Cast the generic Phidget object into a Phidget Magnetometer object
    PhidgetManager_close(mgr);
          magHandle = (PhidgetMagnetometerHandle) device;
    PhidgetManager_delete(&mgr);
          // Now that the channel is cast, we can call Magnetometer-specific methods like getFieldStrength:
    exit(0);
          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>


A further example would be "HelloWorld" for most [[Programming_Resources|supported languages]] uses the Phidget Manager.


==Opening a Manager Channel==


</syntaxhighlight>
A manager channel passed to a Phidget Manager attach handler is assigned all of the matching parameters for the Phidget device and the device channel the manager channel refers to; however, the manager channel is not attached to the device channel, and is not receiving data and status information from the device.
</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]].
User code may {{Code|Open()}} a manager channel, and just like a channel created by the user code, the Phidget library will begin trying to match the manager channel with a device channel.  User code may also set attach and detach handlers on the manager channel, and set change event handlers.  The manager channel can be treated exactly the same as a user channel.

Latest revision as of 16:41, 24 March 2022

General Overview

The Phidget Manager is an interface into the device channels available to the Phidget library. The API is strictly asynchronous, and 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 becomes available over the network), a manager attach event is fired for each channel available from the Phidget. When the Phidget is removed from the system, a manger detach event is fired for each channel that is no longer available.

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 has appeared, and 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 is not fired. A manager detach event is fired when the Phidget 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:

Using the Phidget Manager

Much like a Phidget channel, a Phidget Manager must be created and opened. Refer to the Phidget22 API for details.

As soon as a manager is opened the Phidget library will fire an event for each device channel that is currently know to the system. After those initial events, attach and detach events will be fired when new Phidgets become available or existing Phidget are removed.

In the C programming language, it is not safe to refer to a PhidgetHandle after an event handler returns, unless Phidget_retain() is first called (Phidget_open() and Phidget_close() retain and release handlers automatically). The PhidgetHandle must be released with Phidget_release() if it has been retained. The object oriented languages supported in the Phidget22 API automatically retain and release handles.

What follows is an example of how to use a manager in C: 

static void CCONV
mgrAttachHandler(PhidgetManagerHandle mgr, void *ctx, PhidgetHandle mgrch) {

    PhidgetLog_log("%P attached", mgrch);
}

static void CCONV
mgrDetachHandler(PhidgetManagerHandle mgr, void *ctx, PhidgetHandle mgrch) {

    PhidgetLog_log("%P detached", mgrch);
}

int
main(int argc, char **argv) {
    PhidgetManagerHandle mgr;

    PhidgetManager_create(&mgr);

    PhidgetManager_setOnAttachHandler(mgr, mgrAttachHandler, NULL);
    PhidgetManager_setOnDetachHandler(mgr, mgrDetachHandler, NULL);

    PhidgetManager_open(mgr);

    /* Do something long running, like run a GUI threads */
 
    /* Now close and delete the manager */
    PhidgetManager_close(mgr);
    PhidgetManager_delete(&mgr);
    exit(0);
}

A further example would be "HelloWorld" for most supported languages uses the Phidget Manager.

Opening a Manager Channel

A manager channel passed to a Phidget Manager attach handler is assigned all of the matching parameters for the Phidget device and the device channel the manager channel refers to; however, the manager channel is not attached to the device channel, and is not receiving data and status information from the device.

User code may Open() a manager channel, and just like a channel created by the user code, the Phidget library will begin trying to match the manager channel with a device channel. User code may also set attach and detach handlers on the manager channel, and set change event handlers. The manager channel can be treated exactly the same as a user channel.

Retrieved from "https://www.phidgets.com/docs/index.php?title=Phidget_Manager&oldid=33127"