Preliminary Phidget21.NET API Manual Describes the Application Program Interface (API) for each Phidget device. The API can be used by a number of languages; this manual discusses use via C# and the code examples reflect this.
How to use Phidgets Phidgets are an easy to use set of building blocks for low cost sensing and control from your PC. Using the Universal Serial Bus (USB) as the basis for all Phidgets, the complexity is managed behind this easy to use and robust Application Program Interface (API) library. This library is a managed layer on top of the Phidget21 C API. As of July 2006, there is no network functionality available. Currently, this library is intended to be used by CLR languages (VB.NET, C#, etc.) to control phidgets on the local computer. Installing the Library To access the Phidget.NET software components, you must first install the library on your computer: To install the library go to www.phidgets.com >> Dowloads >> Release Select the PHIDGET.msi file. A dialog box will appear, asking if you would like to open the file or save it to your computer. You can do either, but if you are unsure just select Open and follow the instructions. Now, to use Phidgets from the Visual Studio 2005 IDE, open Project >> Add Reference, and browse for Phidget21.NET.dll. This should be listed in the.net library section, but installs by default into C:\Program Files\Phidgets and can be selected manually from there if necessary. Plug in your hardware, and you are ready to go! For older versions of Visual Studio you will have use the COM Interop and reference the Phidget COM library. There are plans to release a.net 1.1 library eventually. Events All devices share three common events: Attach, Detach and Error. There are also many device specific events. These events have been implemented in a standard way for.net. Essentially, you need to create a new event handler delegate that points to a specific function that you want run when the event occurs, and then add that to the event to register the callback. You can see an example of this in the Phidget Manager section. Each event has an associated delegate and argument class for passing data to event handlers. For example, the Attach event uses the AttachEventHandler delegate and the AttachEventArgs class. So to add a callback to the Attach event: Attach += new AttachEventHandler(attachEvent); Where you have created the attachevent function: void attachevent(object sender, AttachEventArgs e) { //do something on an attach... } Each argument class defines properties for accessing data passed to the event handler: ie: e.device.name; //Name of the attached device You can add as many event handling functions as you like to each event, and also add each event handling function to as many events as you like. www.phidgets.com January 2007 2
Exceptions Every functions that is part of this API has the ability to throw a PhidgetException. This exception means that a call to one of the underlying C functions failed, and the PhidgetException will contain the error code and message from the C library. www.phidgets.com January 2007 3
The Phidget Manager The Phidget Manager (Phidgets.Manager class) allows you to get attach and detach events for every device, without actually opening them. Also, a list of device is made available. void open() This will open the PhidgetManager. Generally you would first register the Attach and Detach handlers and then call open() to start the polling this way you will receive notification events for every device, even phidgets that were plugged in prior to the call. void open(string IPAddress, int port, string password [Optional]) Opens a remote PhidgetManager using IP Address (or hostname) and port number. The Password is only required if the Phidget Webservice is running with authentication active. void open(string ServerID, string password [Optional]) This method is not yet implemented and will throw a PhidgetException. void close() Closes the manager. After close is called, the object will no longer send events. string Address { get; } Gets the address of the Phidget Webservice when this manager is opened as remote. int Port { get; } Gets the port of the Phidget Webservice when this manager is opened as remote. string ServerID { get; } This method is not yet implemented and will throw a PhidgetException. Gets the Server ID of the Phidget Webservice when this manager is opened as remote. bool AttachedToServer { get; } Gets the status of the connection to the Webservice when this manager is opened as remote. int Devices.Count { get; } Get count of the attached devices. Phidget Devices[int Index] { get; } Get a specific device from the list of attached devices. This list is maintained as devices are attached and removed. event DetachEventHandler Detach; Occurs when a device is unplugged. event AttachEventHandler Attach; Occurs when a device is plugged in, or discovered from software. event ErrorEventHandler Error; Occurs when an asynchronous error happens usually related to network problems. www.phidgets.com January 2007 4
The Phidget Dictionary The Phidget Dictionary (Phidgets.Dictionary class) is a service provided by the Phidget Webservice. The Webservice maintains a centralized dictionary of key-value pairs that can be accessed and changed from any number of clients though the CPhidgetDictionary interface available in phidget21. Note that the Webservice uses this dictionary to control access to Phidgets through the openremote and openremoteip interfaces, and as such, you should never add or modify a key that starts with /PSK/ or /PCK/, unless you want to explicitly modify Phidget specific data and this is highly discouraged, as it s very easy to break things. Listening to these keys is fine if so desired. The intended use for the dictionary is as a central repository for communication and persistent storage of data between several client applications. As an example - a higher level interface exposed by one application which controls the Phidgets, for others to access rather then every client talking directly to the Phidgets themselves. The dictionary makes use of extended regular expressions for key matching. void open(string IPAddress, int port, string password [Optional]) Opens a remote PhidgetDictionary using IP Address (or hostname) and port number. The Password is only required if the Phidget Webservice is running with authentication active. void open(string ServerID, string password [Optional]) This method is not yet implemented and will throw a PhidgetException. void close() Closes the connection to the Dictionary. void add(string key, string value, bool persistent [Optional]) Adds a new key to the Dictionary, or modifies the value of an existing key. The key can only contain numbers, letters, /,., -, _, and must begin with a letter, _ or /. The value can contain any value. The persistent value controls whether a key will stay in the dictionary after the client that created it disconnects. If persistent == false, the key is removed when the connection closes. Otherwise the key remains in the dictionary until it is explicitly removed. Persistent is optional and by default set to true. void remove(string keypattern) Removes a key, or set of keys, from the Dictionary. The key name is a regular expressions pattern, so care must be taken to only have it match the specific keys you want to remove. string get(string key) This method is not yet implemented and will throw a PhidgetException. Note that currently, the only way to get a key value is using the key event listener (described below). string Address { get; } Gets the address of the Phidget Webservice when this Dictionary is opened as remote. int Port { get; } Gets the port of the Phidget Webservice when this Dictionary is opened as remote. www.phidgets.com January 2007 5
string ServerID { get; } This method is not yet implemented and will throw a PhidgetException. Gets the Server ID of the Phidget Webservice when this Dictionary is opened as remote. bool AttachedToServer { get; } Gets the status of the connection to the Webservice when this Dictionary is opened as remote. event ErrorEventHandler Error; Occurs when an asynchronous error happens usually related to network problems. Dictionary Key Events The dictionary supports events for key add, remove and change, and this is the prefered method for getting a key s value. To support this, the Phidgets.KeyListener class is used. One KeyListener object should be created for each set of keys that need to be listened for (using regular expression matching). KeyListener(Phidgets.Dictionary Dict, string keypattern) This is the only supported constructor for this object, and sets up the dictionary reference and keypattern for matching. Dict should be the dictionary object that will connect to (or is already connected to) a remote Webservice. KeyPattern is a regular expression matching the set of keys that should be matched. void start() Starts throwing events. void stop() Stops throwing events. readonly string KeyPattern gets the value of the keypattern string. Note that this can only be set with the constructor. event KeyEventHandle KeyChange This event occurs when a key is added, or changed. I the key exists before the events are started, this event will be called once with the initial value. event KeyEventHandle KeyRemoval This event occurs when a key is removed. www.phidgets.com January 2007 6
Methods, Properties and Events common to each device The following calls, properties and events are common to all Phidget components: void open(int SerialNumber [Optional]) Attempts to locate a Phidget matching the serialnumber provided. If a serialnumber is not provided, the first device found will be opened. The open call is persistent if the device is lost, it is not necessary to attempt to reopen it, as the Attach Handler will fire when the device is available again. The call is also asynchronous, and will return immediately, even if the device is not plugged in. Open can be called on a device that is not physically attached and will simply read as an unattached open handle until the device is plugged in. void open(int SerialNumber [Optional], string IPAddress, int port, string password [Optional]) Opens a remote Phidget using IP Address (or hostname) and port number. The Password is only required if the Phidget Webservice is running with authentication active. void open(int SerialNumber [Optional], string ServerID, string password [Optional]) This method is not yet implemented and will throw a PhidgetException. void close() Closes this software object. After close is called, the object will no longer attempt to find the Phidget specified with the open call. void waitforattachment(int milliseconds [optional]) Waits for an opened Phidget to attach. This can be called before the Phidget is plugged in and will only return when the Phidget is plugged in and available. If a timeout is specified, and elapses, a PhidgetException will be thrown. If no timeout is specified, the timeout is infinite. bool Attached { get; } Returns a bool indicating the status of this device. True = connected and functioning, False = not connected and waiting. string Name { get; } Gets a string describing this Phidget. This could be for example "Phidget InterfaceKit 8/8/8" or "Phidget Servo Controller 4-motor". long SerialNumber { get; } Returns the unique serial number of this Phidget. This number is set during manufacturing, and is unique across all Phidgets. string Label { get; set; } Returns a string containing the Label of this Phidget. Labels are user defined strings that are stored in the flash on the newest Phidgets. This label cannot currently be set on Windows. To set the label, use Linux, MacOS, or Windows CE. string Type { get; } Gets a string describing the class of this Phidget. This could be for example "PhidgetInterfaceKit" or "PhidgetServo". int Version { get; } Returns the device version of this Phidget. string Address { get; } Gets the address of the Phidget Webservice when this Phidget is opened as remote. www.phidgets.com January 2007 7
int Port { get; } Gets the port of the Phidget Webservice when this Phidget is opened as remote. string ServerID { get; } This method is not yet implemented and will throw a PhidgetException. Gets the Server ID of the Phidget Webservice when this Phidget is opened as remote. bool AttachedToServer { get; } Gets the status of the connection to the Webservice when this Phidget is opened as remote. event DetachEventHandler Detach; Occurs when the device is unplugged. event AttachEventHandler Attach; Occurs when the device is plugged in, or discovered from software. event ErrorEventHandler Error; Occurs whenever an unexpected condition occurs. www.phidgets.com January 2007 8
Specific devices Each Phidget component is described along with its API. PhidgetAccelerometer The PhidgetAccelerometer is a component that provides a high-level programmer interface to control a PhidgetAccelerometer device connected through a USB port. The product is available as a dual axis or a 3-axis module. With this component, the programmer can: Measure up to 5 Gravity (9.8 m/s2) change per axis, depending on unit purchased. Measures both dynamic acceleration (e.g., vibration) and static acceleration (e.g., gravity or tilt). int axes.count { get; } Get the number of axes available from the PhidgetAccelerometer. double axes[int Index].Acceleration { get; } Gets the last acceleration value received from the PhidgetAccelerometer for a particular axis. double axes[int Index].Sensitivity { set; get; } Gets / sets the amount of change that should exist between the last reported value and the current value before an OnAccelerationChange event is fired. event AccelerationChangeEventHandler AccelerationChange; Occurs when the acceleration changes by more than the Acceleration trigger. www.phidgets.com January 2007 9
PhidgetEncoder The PhidgetEncoder is a component that provides a high-level programmer interface to control a PhidgetEncoder device connected through a USB port. With this component, the programmer can: Detect changes in position of incremental and absolute encoders. Easily track the changes with respect to time. int encoders.count { get; } Gets the number of encoders available on the Phidget. int inputs.count { get; } Returns the number of inputs on this particular Phidget device. Please see the hardware description for the details of device variations. int encoders[int Index] { set; get; } Gets the last position value received from the encoder for the particular encoder selected, or sets the position value for a specific encoder. bool inputs[int Index] { get; } Returns the state of the designated input. In the case of a switch or button which is normally open, True would correspond to when the switch is pressed. event InputChangeEventHandler InputChange; Occurs when an input changes. event PositionChangeEventHandler PositionChange; Occurs when the encoder changes position. www.phidgets.com January 2007 10
PhidgetInterfaceKit The PhidgetInterfaceKit is a component that provides a high-level programmer interface to control a PhidgetInterfaceKit device connected through a USB port. With this component, the programmer can: Turn particular outputs on and off. Get notified of changes of state of the inputs as events. Configure events to fire when the analog inputs change. The PhidgetInterfaceKit devices provide a combination of Digital outputs. Digital inputs. Analog inputs. int outputs.count { get; } Returns the number of outputs on this particular Phidget device. Please see the hardware description for the details of device variations. int inputs.count { get; } Returns the number of inputs on this particular Phidget device. Please see the hardware description for the details of device variations. int sensors.count { get; } Gets the number of analog inputs available on the given PhidgetInterface Kit. bool inputs[int Index] { get; } Returns the state of the designated input. In the case of a switch or button which is normally open. True would correspond to when the switch is pressed. bool outputs[int Index] { set; get; } Gets or sets the state of the designated output to True or False. Depending on the type of output available the specified output goes to a high value or completes a connection. Please see the hardware description for details on different outputs. int sensors[int Index].Value { get; } Gets the last reported sensor value for the given index. int sensors[int Index].RawValue { get; } Gets the last reported sensor value for the given index, in raw (12 bit over-sampled) form. int sensors[int Index].Sensitivity { set; get; } Sets or Gets the amount of change that should exist between the last reported value and the current value before an OnSensorChange event is fired. bool ratiometric { set; get; } Sets or gets the state of the ratiometric property. This can affect the way that some sensors are interpreted. See the website for more information. www.phidgets.com January 2007 11
event InputChangeEventHandler InputChange; Occurs when an input changes. event OutputChangeEventHandler OutputChange; Occurs when an output changes. event SensorChangeEventHandler SensorChange; Occurs when a sensor value changes by more than the OnSensorChange trigger. www.phidgets.com January 2007 12
PhidgetLED The PhidgetLED is a component that provides a high-level programmer interface to control a PhidgetLED device connected through a USB port. With this component, the programmer can: Control each led individually, On/Off and Brightness. int leds.count { get; } Gets the number of LED positions available in this Phidget. int leds[int Index] { set; get; } Sets or gets the brightness of an individual LED. Range of brightness is 0-100. www.phidgets.com January 2007 13
PhidgetMotorControl The PhidgetMotorControl is a component that provides a high-level programmer interface to control a PhidgetMotorControl device connected through a USB port. With this component, the programmer can: Control direction, and start and stop DC motors. Control the velocity and acceleration of each DC motor. Read the limit switch. int motors.count { get; } Returns the maximum number of motors on this particular Phidget device. This depends on the actual hardware. Please see the hardware description for the details of device variations. Note: that there is no way of programmatically determining how many motors are actually plugged into the hardware. int inputs.count { get; } Returns the number of inputs on this particular Phidget device. Please see the hardware description for the details of device variations. bool inputs[int Index] { get; } Returns the state of the designated input. In the case of a switch or button which is normally open, True would correspond to when the switch is pressed. int motors[int Index].Acceleration { set; get; } Sets or gets the acceleration of a specific motor. This corresponds to how fast a motor will changes it speed over time. The range is (0 100). int motors[int Index].Velocity { set; get; } Sets or gets the velocity of a specific motor. This corresponds to the PWM rate. The range is (-100 100). event InputChangeEventHandler InputChange; Occurs when an input changes. event MotorVelocityChangeEventHandler VelocityChange; Occurs when the motor speed changes. event MotorCurrentChangeEventHandler CurrentChange; Occurs when the motor current usage changes. This is not available with all motors controllers. www.phidgets.com January 2007 14
PhidgetPHSensor The PhidgetPHSensor is a component that provides a high-level programmer interface to control a PhidgetPHSensor device connected through a USB port. With this component, the programmer can: Read the PH of a solution with a PH probe. double sensor.ph { get; } Returns the current ph. double sensor.poptential { get; } Returns the current potential (voltage). double sensor.sensitivity { set; get; } Sets or gets the amount of change that should exist between the last reported value and the current value before an OnPHChange event is fired. event PHChangeEventHandler PHChange; Occurs when the PH changes by more than the PH trigger. www.phidgets.com January 2007 15
PhidgetRFID The PhidgetRFID is a component that provides a high-level programmer interface to control a PhidgetRFID device connected through a USB port. With this component, the programmer can: Read Radio Frequency Identification tags. Radio Frequency Identification or RFID, is a non-contact identification technology which uses a reader to read data stored on low cost tags. The particular instance of the technology we use stores a 40-bit number on the tag. Every tag that is purchased from Phidgets Inc. is guaranteed unique. When a RFID tag is read, the component returns the unique number contained in the RFID tag. int outputs.count { get; } Returns the number of outputs on this particular Phidget device. Please see the hardware description for the details of device variations. bool outputs[int Index] { set; get; } Set of gets the state of the designated output to True or False. Depending on the type of output available the specified output goes to a high value or completes a connection. Please see the hardware description for details on different outputs. bool Antenna { set; get; } Set of gets the state of the Antenna. True turns the antenna on. This is not available on the very old readers. bool LED { set; get; } Set of gets the state of the LED. True turns the LED on. This is not available on the very old readers. event TagEventHandler Tag; Occurs when a Tag is placed on the reader. event TagEventHandler TagLost; Occurs when a Tag is removed from the reader. event OutputChangeEventHandler OutputChange; Occurs when an output changes. www.phidgets.com January 2007 16
PhidgetServo The PhidgetServo is a component that provides a high-level programmer interface to control a PhidgetServo device connected through a USB port. With this component, the programmer can: Set the desired position for a servo motor, ranging from 0 to 180 degrees. int servos.count { get; } Returns the maximum number of motors on this particular Phidget device. This depends on the actual hardware. Please see the hardware description for the details of device variations. Note that there is no way of programmatically determining how many motors are actually plugged into the hardware. double servos[int Index].Position { set; get; } Sets the desired servo motor position for a particular servo motor, or gets its current position. This value may range from -23 to 231, corresponding to time width of the control pulse, the angle that the Servo motor moves to depends on the characteristic of individual motors. Please read the PhidgetServo documentation to understand what behavior you can expect from your motors. event ServoPositionChangeEventHandler PositionChange; Occurs when the servo position changes. www.phidgets.com January 2007 17
PhidgetTemperatureSensor The PhidgetTemperatureSensor is a component that provides a high-level programmer interface to control a PhidgetTemperatureSensor device connected through a USB port. With this component, the programmer can: Read the temperature of Thermocouple device. Read cold junction temperature. Get notification of temperature change. Use metric or imperial units. int thermocouples.count { get; } Returns the integer value of the number of thermocouple inputs, not including the ambient sensor. double thermocouple[int Index].Temperature { get; } Returns the current temperature in Celsius. Index = 0 returns the temperature of the thermocouple. Future devices may offer more then one thermocouple input. double thermocouple[int Index].Sensitivity { set; get; } Set or gets the amount of change that should exist between the last reported value and the current value before an OnTemperatureChange event is fired. double ambientsensor.temperature { get; } Returns the current temperature in Celsius of the ambient (cold joint) temperature sensor ic. double ambientsensor.sensitivity { set; get; } Set or gets the amount of change that should exist between the last reported value and the current value before an OnTemperatureChange event is fired, for the ambient sensor. event TemperatureChangeEventHandler TemperatureChange; Occurs when the Temperature changes by more than the Temperature trigger. Index 0 is the ambient sensor. Index 1 is the thermocouple. www.phidgets.com January 2007 18
PhidgetTextLCD The PhidgetTextLCD is a component that provides a high-level programmer interface to control a PhidgetTextLCD device connected through a USB port. With this component, the programmer can: Display text on a PhidgetTextLCD module. int rows.count { get; } Returns number of rows of text that may be presented on the display. int rows[int Index].MaximumLength { get; } Returns number of columns of text that may be used on the display row specified. string rows[int Index].DisplayString { set; } Sets the text to display on a particular row of the display. The text will be clipped at the right edge of the display. bool Backlight { set; get; } Gets or sets the status of the backlight. True = on. int Contrast { set; get; } Sets or gets the contrast level. Range is (0-255). bool Cursor { set; get; } Sets or gets the status of the cursor. True = on. bool CursorBlink { set; get; } Sets or gets the status of the cursor blink. True = blinking. www.phidgets.com January 2007 19
PhidgetTextLED The PhidgetTextLED is a component that provides a high-level programmer interface to control a PhidgetTextLED device connected through a USB port. With this component, the programmer can: Display text and numbers on segment type LED modules. Brightness can be controlled for the entire display. In the case of 7-segment LED characters numbers are displayed easily and text can be displayed with some restrictions. int rows.count { get; } Returns number of rows of text that may be presented on the display. int rows[int Index].MaximumLength { get; } Returns number of columns of text that may be used on the display row specified. string rows[int Index].DisplayString { set; } Sets the text to display on a particular row of the display. The text will be clipped at the right edge of the display. int Brightness { set; get; } Sets or gets the brightness of the LED display. Varying this property will control the brightness uniformly across all digits in the display. www.phidgets.com January 2007 20
PhidgetWeightSensor The PhidgetWeightSensor is a component that provides a high-level programmer interface to control a PhidgetWeightSensor device connected through a USB port. With this component, the programmer can: Read the weight of an item or person on the weight scale. double sensor.weight { get; } Returns the current weight in Kilograms. double sensor.sensitivity { set; get; } Gets or sets the amount of change that should exist between the last reported value and the current value before an OnWeightChange event is fired. event WeightChangeEventHandler WeightChange; Occurs when the Weight changes by more than the Weight trigger. www.phidgets.com January 2007 21