24U Phidgets Plug-In 3.1 Specification

Specification revision: 10, 2020-03-05.

Known limitations

iOS version only supports Phidgets through a network connection

After using Phidget_Connect( address ; password {; port } ) function device may act as connected even though the communication with plugin may not be set yet. You may want to add Pause into onAttach set script event as workaround. Please see Examples inside Distribution Archive.

It is not possible to downgrade the plugin through the function Install Plug-In file.

Complete syntax of plugin functions

Phidget_Version ( { versionFormat } )

Returns version string of the active 24U Phidgets Plug-In, formatted as requested by the parameter.

Parameters

Parameter values for versionFormat

Examples

Phidget_Version("phidgetlib")
This will return for example: "Phidget21 - Version 2.1.8 - Built Aug 21 2015 10:20:29"

Phidget_Register(selector)

Provides special functionality to operate with plugin serial numbers.

Parameters

Parameter values for selector

Description

Use this function to register or unregister 24U Phidgets Plug-In, to get information about current registration state, or to invoke GUI providing basic registration information and purchase capabilities.

Result

Returns zero or error code depending on the selector.

Examples

Phidget_Register( "address@example.com" )
This will send email on address@example.com for confirmation, if you confirm than you will get trial version on this product verified by this email.

Phidget_Register( "PHD30C666-4B7B-37PH-Q2E6-1UKY" )
This will register this product with key: "PHD30C666-4B7B-37PH-Q2E6-1UKY".

Phidget_Register( "Unregister" )
This will remove all registered keys. After this call product is no longer registered.

Phidget_Read ( phidgetSNdevice ; valueID { ; index ; { extra } } )

Reads data from the Phidget.

Parameters

Parameter values for valueID

Description

The "General" Phidget Type can be used with all Phidgets. The default input for all Phidgets is the first valueID for each phidget in this list. For example calling Phidget_Read( -1 ; "inputValue" ) is the same as Phidget_Read( -1 ; "motorPosition" ) for PhidgetServo.

Result

Function returns data from Phidget if everything is OK. In case of error the function returns "?". You can use Phidget_Get("lastError") for more detailed error description.

Examples

Phidget_Read(-1 ; "inputValue")
The most basic reading. This command will read an "inputValue" from a connected Phidget. If more than one device is connected the plug-in will choose the first device which was connected.

Phidget_Read(335882 ; "sensorValue" ; 3)
Reads a value from the fourth sensor of the InterfaceKit. If the field phidgetSNdevice does not contain correct serial number of the the Interface Kit Phidget (which must be connected in the time of reading) than the function will fail and returns "?".

Phidget_Read(335882:3"335882:3"; "bridgeValue" ; 1)
Reads value from port 1 on Phidget Bridge with Phidget serial number 335882 connected to 3rd VINT port. If the port is disabled or any other error occured than the function will fail and returns "?".

Phidget_Read(335882 ; "tag")
Reads tag value from Phidget RFID.

Phidget_Read(335882 ; "tag")
Assume, that tag contains value "hello world!" using protocol PHIDGET. Because "autoDetect" is not used, output value is converted to "68656c6c6f".

Phidget_Read(335882 ; "tag" ; 0 ; "autoDetect")
Assume, that tag contains value "hello world!" using protocol PHIDGET. This returns "hello world!".

Phidget_Write( phidgetSNdevice ; valueID ; data { ; index { ; tagProtocol { ; tagLocking } } } )

Data to the Phidget are written or set.

Parameters

Parameter values for valueID

Description

The "General" valueIDs can be used with all sensors. The default output for all Phidgets is the first valueID for each Phidget in this list. For example calling Phidget_Write( -1 ; "outputState" ; 20 ) is the same as Phidget_Write( -1 ; "motorPosition" ; 20 ) for PhidgetServo.

Result

Function returns 0 if everything is OK. In case of error the function returns negative error code or Phidget Error code"?". You can use Phidget_Get("lastError") for more detailed error description.

Examples

Phidget_Write(-1 ; "outputState" ; 20)
This will write a value "20" to the first connected phidget if it is possible.

Phidget_Write( phidgetSNDevice ; "motorPosition" ; 215)
It rotates the servo in PhidgetServo to 215 degrees. PhidgetSNDevice parameter should contain a valid serial number of connected servo phidget.

Phidget_Write( 69418 ; "outputState" ; 1 ; 5)
Sets the sixth output of the interface kit phidget with serial number 69418 to 1.

Phidget_Write( 335882 ; "tag" ; "Your text." )
New tag is written. Used tag protocol: PHIDGETS (See tag protocols for more information.)

Phidget_Write( phidgetSNDevice ; "tag" ; "999123456789012"; 0 ; "ISO11785_FDX_B" )
New tag is written. Used tag protocol: ISO11785_FDX_B (See tag protocols for more information.)

Phidget_Write( phidgetSNDevice ; "tag" ; "123456789a"; 0 ; "EM4100" )
New tag is written. Used tag protocol: EM4100 (See tag protocols for more information.)

Phidget_Write( phidgetSNDevice ; "displayString" ; "Hello World!"; 0)
This example shows how to use PhidgetTextLCD 20X2 : White : Integrated PhidgetInterfaceKit 8/8/8
New text is written on the first row. Note: Rows are indexed from zero. If text is not visible, please check backlight, brightness and contrast.

Phidget_Write( phidgetSNDevice ; "displayString" ; "special chars: "& char(224) & char(225) & char(226) & char(227) ; 1)
This example shows how to use PhidgetTextLCD 20X2 : White : Integrated PhidgetInterfaceKit 8/8/8
Special characters on the first row are written. More about special characters can be found here.

Phidget_Write(-1 ; "displayString" ; "Hello World!" ; "2:1">
This example shows how to use PhidgetTextLCD Adapter with LCD Screen 4x20. connected to port LCD-1
Before you can write on the LCD connected to the PhidgetTextLCD Adapter, you should first set up screen size and activate the screen (see Phidget_Set).
New text is written on the 3rd row.

Phidget_Write( phidgetSNDevice ; "outputState" ; 2,6 ; 1)
Set output voltage to 2,6V on port 1 (assuming this port is enabled).

Phidget_SetScriptEvent( phidgetSNdevice ; event/time ; scriptName { ; index { ; changeAmount { ; threshold } } } )

Tell the plug-in to launch the script when specified event is triggered by the Phidget or in specified time intervals.

Parameters

Parameter values for event

Description

Some events are the same for more Phidgets. The "General" event "onInputChange" can be installed to all listed Phidgets and it will behave as their default input event. For example: Phidget_SetScriptEvent( -1 ; "onInputChange" ; "Do Something" ) has the same meaning as Phidget_SetScriptEvent( -1 ; "onMotorPosChange" ; "Do Something" ) for PhidgetServo or Phidget_SetScriptEvent( -1 ; "onTag" ; "Do Something" ) for PhidgetRFID. If "onInputChange" is used, the phidget type is detected automatically and the event is installed to it.
Param changeAmount can be used only on onSensorChange event. On other events it is ignored.

In both cases (event/time) the script will receive a parameter containing the value list with phidgetSNdevice, inputIndex and inputValue. Values for digital input can be "0" or "1" for analog it varies by the type of the event.

To remove event call Phidget_SetScriptEvent( phidgetSNdevice ; event/time ; "" ).
To remove all events from some phidget call Phidget_SetScriptEvent( phidgetSNdevice ; "" ; "" ).
To remove all events from all Phidgets call Phidget_SetScriptEvent( "" ; "" ; "" ) or Phidget_SetScriptEvent( "all" ; "" ; "" ).

Result

Function returns 0 if event is successfully installed or uninstalled. In case of error the function returns negative error code or Phidget Error code"?". You can use Phidget_Get("lastError") for more detailed error description.

Examples

Phidget_SetScriptEvent(-1 ; 1.2 ; "Default Script")
This will install the script named "Default Script" to the first available connected phidget. The script will run every 1.2 second and it will obtain a parameter which consist of serial number, "0" and input value. Each on new line. The "0" signals that the input on index 0 is beeing read.

Phidget_SetScriptEvent(phidgetSNdevice ; "onTag" ; "Process new tag")
The script "Process new tag" will be triggered every time the new RFID tag is in the vicinity of the RFID phidget. The script will receive a parameter with phidget serial number, "0" and RFID value of the tag. Each on the new line. The zero means, that the first input of RFID phidget is used.

Phidget_SetScriptEvent(69418 ; "onSensorChange" ; "Read sensor" ; 6 ; 10 ; 5)
This will install "onSensorChange" event to the interface kit phidget with serial number 69418. The phidget must be connected. The "Read sensor" script will be triggered when the seventh sensor's value on the interface kit phidget with SN 69418 will change more than 10 points and will be higher than 5. The script will receive the parameter which will contain: "69418", "6" and sensor value. Each on the new line.

Phidget_SetScriptEvent("all" ; "onAttach" ; "New phidget attached")
The script "New phidget attached" will be called every time when user will connect a new phidget to the system. The script will receive a parameter with serial number of the new connected phidget.

Phidget_Get( what { ; more ; index } )

Function to get plug-in or phidget settings and other useful data.

Parameters

Parameter values for what

Description

The "more" parameter is usually used to specify Phidget Serial Number. Some commands need specific PhidgetSNDevice (of specific type) otherwise they will fail. Some commands are more general. You can use PhigetSN value "-1" to specify the default Phidget.

The boolean values are returned in number form. For example Phidget_Get("antennaOn" ; -1) returns 0 if backlight is off and 1 if backlight is on.

Result

Function returns data if everything is OK. In case of error the function returns "?". You can use Phidget_Get("lastError") for more detailed error description.

Examples

Phidget_Get("attachedDevices")
This will return the number of attached devices. If no phidget is attached to the machine it will return 0. It is a good command to start with to check if any phidget is connected.

Phidget_Get("serialNumber" ; 3)
If you have four Phidgets connected to the machine this will return the serial number of the fourth one. Use this command in the loop (along with previous one) to enumerate serial numbers of all Phidgets connected to the machine.

Phidget_Get("deviceType" ; 69418)
This will check the connected phidget with SN 69418 and returns its type. The types are textual in human readable form. For the supported types the result can be: "PhidgetInterfaceKit", "PhidgetRFID" and "PhidgetServo". In general the type names are the same as the official ones.

Phidget_Get("deviceType" ; 120538 ; 1)
This will return device type of given PhidgetSNDevice, however it will try to locate the second type of given PhidgetSNDevice. Example: you have TextLCD combined with InterfaceKit, this allows you to get device type of the second device.

Phidget_Get("enabled" ; 140923 ; 2)
This will check if port 2 on Phidget Bridge is enabled. Port has to be enabled, if we want to read data.

Phidget_Get("dataRateMin" ; 140923)
This will return minimal rate in Phidget Bridge. Value is in ms and if you set data rate, it should be lesser or equal.

Phidget_Get("numColumns" ; 120538)
This will return number of columns of Text LCD with SN 120538.

Phidget_Get("numRows ; 120538)
This will return number of rows of Text LCD with SN 120538.

Phidget_Get("numRows" ; 329701 ; 1)
This will return number of rows of LCD connected to TextLCD Adapter to port LCD-1 with SN 329701.

Phidget_Get("contrast" ; 120538)
This will return current value of contrast of Text LCD with SN 120538.

Phidget_Get("brightness" ; 120538)
This will return current value of brightness of Text LCD with SN 120538.

Phidget_Get("backlight" ; -1)
This will return backlight status of the first found Text LCD.

Phidget_Get("backlight" ; 120538)
This will return current value of backlightm brightness (within range of 0-255) of Text LCD with SN 120538.

Phidget_Set( what ; value { ; phidgetSNdevice ; index } )

Function to set plug-in or phidget settings and other useful data.

Parameters

Parameter values for what

Description

Use this funtion to set various value on Phidgets.

Result

Function returns set value if everything is OK. In case of error the function returns "?". You can use Phidget_Get("lastError") for more detailed error description.

Examples

Phidget_Set("ratiometric" ; 1 ; 69418)
This will set the ratiometric value to 1 (turns on) in the phidget with SN 69418. This phidget must be interface kit phidget otherwise "?" is returned.

Phidget_Set("ratiometric" ; 1 ; -1)
This will set the ratiometric value to 1 (turns on) in the first phidget it founds. This phidget must be interface kit phidget otherwise "?" is returned. Use this form if you have only one phidget connected to the computer and you are sure that you will never connect any other phidget otherwise the result can be unpredictable.

Phidget_Set( "backlight" ; 1 ; 120538)
This will set the state of the backlight. Possible values 0 (off) or 1 (on).

Phidget_Set( "backlight" ; 127,5 ; 120538)
This will set the backlight brightness value. Possible values 0-255.

Phidget_Set( "contrast" ; 155 ; 120538)
This will set the contrast value. Possible values 0-255.

Phidget_Set( "motorOn" ; 1 ; 170192 ; 3)
This will turn on the fourth motor.

Phidget_Set( "motorOn" ; 0 ; 170192 ; 0)
This will turn off the first motor.

Phidget_Set( "enabled" ; 1 ; 140912 ; 3)
This will enable port 3 on Bridge.

Phidget_Set( "dataRate" ; 200 ; 140923)
This will set data rate of Phidget Bridge on 200 ms. Be careful - data rate should be between data rate min and data rate max.

Phidget_Set( "enabled" ; 1 ; 131907 ; 3)
This will enable port 3 on Analog (assuming proper phidgetSN was given).

Phidget_Set( "portMode" ; "digitalOutput" ; "335882:3")
This will set digital output mode on port 3 on VINT Hub with serial number 335882. You can use the port as digital output the same way as with the Interface kit.

Phidget_Set( "portMode" ; "vintDevice" ; "335882:3")
This will set VINT device mode on port 3 on VINT Hub with serial number 335882. After you set port, you can connect to the port one of the supported VINT devices.

Phidget_Set( "screenSize" ; "4x20" ; "329701" ; "1")
This example shows how to use PhidgetTextLCD Adapter with LCD Screen 4x20. connected to port LCD-1
This will prepare the plugin for use of the this lcd. Not setting the size before writting to the lcd will lead to unexpected behavior.

Phidget_Set( "activeScreen" ; "1" ; "329701" ; "1")
This will activate lcd connected to the port LCD-1 of PhidgetTextLCD Adapter. After activating the screen you can start use function Phidget_Write with this LCD.

Phidget_Connect( address ; password {; port } )

Function to connect to an SBC or a computer running athe Phidget Network Server via network.

Parameters

Description

Use this function to connect to an SBC or Phidget Network Server.

Result

Function return 0, if everything OK, if function returns "?". You can use Phidget_Get("lastError") for more detailed error description. However, even if function returns 0, it doesn't mean that SBC is already connected. If you have slow network, then it can take some time. Connected SBC will trigger "onAttach" script (if set).

Examples

Phidget_Connect("10.0.3.51" ; "111111")
Try to establish connection to address 10.0.3.51 with password "111111" on port 50015661.

FileMaker example of using this feature can be found here.