General Phidget Programming - Revision history

Mparadis: /* Event Driven Code */

2016-09-27T19:04:45Z

Event Driven Code

← Older revision		Revision as of 19:04, 27 September 2016
Line 666:		Line 666:
	*Having the user (or program) ''put'' changes onto the device (in contrast to reading data ''from'' the device)		*Having the user (or program) ''put'' changes onto the device (in contrast to reading data ''from'' the device)

	Event driven code is relatively hard to design well. It may help to draw out a '''flowchart''', '''state machine''', or at least a '''pseudo-code outline''' of your system design and all events you wish to handle before writing code. One of the most important things to remember when designing event driven code is to keep the amount of code in the actual event handler to a minimum. If events are coming in at a rapid pace and you have large blocks of code in the event handlers, there is a good chance that the events coming in will overwhelm the processor and you will start missing data points. If you have a lot you need to accomplish for each event make separate functions and call them in the event handler. This way new events can continue to come in while the code executes.		Event driven code is relatively hard to design well. It may help to draw out a '''flowchart''', '''state machine''', or at least a '''pseudo-code outline''' of your system design and all events you wish to handle before writing code. One of the most important things to remember when designing event driven code is to keep the amount of code in the actual event handler to a minimum. If events are coming in at a rapid pace and you have large blocks of code in the event handlers, there is a good chance that the events coming in will overwhelm the processor and you will start missing data points. If you have a lot you need to accomplish for each event make separate functions and call them in another thread in the event handler. This way new events can continue to come in while the code executes.

	The code examples given for each [[Software Overview#Language Support\|specific language]] use events if they are supported by the language.		The code examples given for each [[Software Overview#Language Support\|specific language]] use events if they are supported by the language.

Burley: /* Software Errors */

2013-06-03T19:47:52Z

Software Errors

← Older revision		Revision as of 19:47, 3 June 2013
Line 914:		Line 914:
	=====Software Errors=====		=====Software Errors=====

	These codes are returned by Phidget API functions / thrown as exceptions on errors. See the API manual for your language to see which codes can be returned by which functions. In C/C++, a return code of 0 indicates success, any other return code is a failure. In languages supporting exceptions, most functions a will return void, and throw an exception on error.		These codes are returned by Phidget API functions / thrown as exceptions on errors. See the API manual for your language to see which codes can be returned by which functions. In C/C++, a return code of 0 indicates success, any other return code is a failure. In languages supporting exceptions, most functions a will return void, and throw an exception on error. All Phidgets functions will return an integer value that corresponds to one of the following cases or 0 which is a success.

	'''EPHIDGET_NOTFOUND = 1'''		'''EPHIDGET_NOTFOUND = 1'''

Mparadis: /* Do Things with the Phidget */

2013-05-03T17:08:14Z

Do Things with the Phidget

← Older revision		Revision as of 17:08, 3 May 2013
Line 192:		Line 192:
	*Your computer can poll much faster than the Phidget can respond. If you poll in a continuous '''<code>while</code>''' loop in byte code, you will probably swamp the Phidget with requests.		*Your computer can poll much faster than the Phidget can respond. If you poll in a continuous '''<code>while</code>''' loop in byte code, you will probably swamp the Phidget with requests.

	*Similarly, if you set a value and then immediately read the value on the next line in your program, the Phidget may not have time to finish the set. In our examples, we use <code>print()</code> statements within loops. Print functions are relatively slow; you can also use <code>wait()</code> or <code>sleep()</code> depending on your language.		*Similarly, if you set a value and then immediately read the value on the next line in your program, the Phidget may not have time to finish the set. In our examples, we use <code>print()</code> statements within loops. Print functions are relatively slow; you can also use <code>wait()</code> or <code>sleep()</code> depending on your language. This also applies to rapidly changing output properties. For example, if you turn on a digital output and then turn it off in the next line of code, the output will never turn on because the hardware doesn't have time to react. You need to put more instructions between the two to guarantee that both changes actually happen.

	*If you are handling data using events as described below, the data event functions will fire when the device is plugged in and its initial state is read.		*If you are handling data using events as described below, the data event functions will fire when the device is plugged in and its initial state is read.

Burley: /* Close the Phidget */

2013-03-12T16:36:01Z

Close the Phidget

← Older revision		Revision as of 16:36, 12 March 2013
Line 384:		Line 384:
	The close() function also makes sure the thread associated with the Phidget close properly. Any outstanding writes will block close() until they complete, because writes are guaranteed to complete (unless a device is detached).		The close() function also makes sure the thread associated with the Phidget close properly. Any outstanding writes will block close() until they complete, because writes are guaranteed to complete (unless a device is detached).

	Also note that a device should be put into a known state before calling close. For example, if a motor controller is driving a motor and close is called, it will continue to drive the motor even though the application has exited. This may or may not be what you want.		Also note that a device should be put into a known state before calling close. For example, if a motor controller is driving a motor and close is called, it will continue to drive the motor even though the application has exited. This may or may not be what you want. This is a result of the fact that all Phidgets boards will maintain their current state until they are powered down (physically detached from the computer), even when they are closed by the current application.



	===Using Multiple Phidgets===		===Using Multiple Phidgets===

Burley: /* One: An error generated by a function call */

2012-09-26T20:30:30Z

One: An error generated by a function call

← Older revision		Revision as of 20:30, 26 September 2012
Line 825:		Line 825:
	The consequences of not catching this type of error (on ''every'' function) differ by programming language.		The consequences of not catching this type of error (on ''every'' function) differ by programming language.
	In C/C++ these errors must be ''explicitly'' checked for after each function call, otherwise the program will simply continue on in an incorrect state. In languages that support exceptions (e.g., Java, .NET, Python, AS3), errors are returned using exceptions which will leave you no choice but to catch them, or have your program terminate without warning.		In C/C++ these errors must be ''explicitly'' checked for after each function call, otherwise the program will simply continue on in an incorrect state. In languages that support exceptions (e.g., Java, .NET, Python, AS3), errors are returned using exceptions which will leave you no choice but to catch them, or have your program terminate without warning.

			Be careful when trying to determine what is causing the exception. Something that can happen depending on how your code is structured is you can have exceptions that claim to be a particular Phidget exception but are in fact to do with non-Phidgets code that is for example inside a Phidgets event handler.

	====Two: An error generated by an event====		====Two: An error generated by an event====

Mparadis: /* Logging */

2012-09-10T19:32:33Z

Logging

@@ Line 718: / Line 718: @@
 The use of null is to indicate that the output is not to a file (and hence to the command line).  Otherwise, the second argument would be a string filename.
-There are six different logging levels, ranging from "Give me Everything!" to "Tell me only about critical problems".  The level in the examples above - '''<code>PHIDGET_LOG_DEBUG</code>''' - is a medium output level.  For more information about each level and what it gives you, see the API for [[Software Overview#Language Support|your specific language]].
+There are six different logging levels, ranging from "Give me Everything!" to "Tell me only about critical problems".  The level in the examples above - '''<code>PHIDGET_LOG_DEBUG</code>''' - is a medium output level.
 ===Threading===

Mparadis: /* Exceptions and Errors */

2012-09-10T19:11:43Z

Exceptions and Errors

← Older revision		Revision as of 19:11, 10 September 2012
Line 854:		Line 854:
	These codes are used within the Error Event. See the API section in the User Guide for your Phidget 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.		These codes are used within the Error Event. See the API section in the User Guide for your Phidget 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.

	=====Library Errors:=====		=====Library Errors=====

	'''EEPHIDGET_NETWORK = 0x8001'''		'''EEPHIDGET_NETWORK = 0x8001'''
Line 865:		Line 865:
	:Version Mismatch Error. Usually means client and host side of a webservice connection are out of sync.		:Version Mismatch Error. Usually means client and host side of a webservice connection are out of sync.

	=====Device Errors:=====		=====Device Errors=====

	'''EEPHIDGET_OVERRUN = 0x9002'''		'''EEPHIDGET_OVERRUN = 0x9002'''
Line 888:		Line 888:
	:Power supply problem detected. Either the power supply is being overloaded, or it is not powered (ie. not plugged in).		:Power supply problem detected. Either the power supply is being overloaded, or it is not powered (ie. not plugged in).

	=====Software Errors:=====		=====Software Errors=====

	These codes are returned by Phidget API functions / thrown as exceptions on errors. See the API manual for your language to see which codes can be returned by which functions. In C/C++, a return code of 0 indicates success, any other return code is a failure. In languages supporting exceptions, most functions a will return void, and throw an exception on error.		These codes are returned by Phidget API functions / thrown as exceptions on errors. See the API manual for your language to see which codes can be returned by which functions. In C/C++, a return code of 0 indicates success, any other return code is a failure. In languages supporting exceptions, most functions a will return void, and throw an exception on error.

Mparadis: /* Exceptions and Errors */

2012-09-10T19:11:16Z

Exceptions and Errors

@@ Line 850: / Line 850: @@
 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 API [[Software Overview#Language Support|for your programming language]].
-See the API for your [[Software Overview#Language Support|specific programming language]] for error code documentation.
+====Error Codes====
 ===Sensitivity and Filtering===

Burley: /* Event Driven Code */

2012-08-15T15:21:06Z

Event Driven Code

← Older revision		Revision as of 15:21, 15 August 2012
Line 668:		Line 668:
	*Having the user (or program) ''put'' changes onto the device (in contrast to reading data ''from'' the device)		*Having the user (or program) ''put'' changes onto the device (in contrast to reading data ''from'' the device)

	Event driven code is relatively hard to design well. It may help to draw out a '''flowchart''', '''state machine''', or at least a '''pseudo-code outline''' of your system design and all events you wish to handle before writing code.		Event driven code is relatively hard to design well. It may help to draw out a '''flowchart''', '''state machine''', or at least a '''pseudo-code outline''' of your system design and all events you wish to handle before writing code. One of the most important things to remember when designing event driven code is to keep the amount of code in the actual event handler to a minimum. If events are coming in at a rapid pace and you have large blocks of code in the event handlers, there is a good chance that the events coming in will overwhelm the processor and you will start missing data points. If you have a lot you need to accomplish for each event make separate functions and call them in the event handler. This way new events can continue to come in while the code executes.

	The code examples given for each [[Software Overview#Language Support\|specific language]] use events if they are supported by the language.		The code examples given for each [[Software Overview#Language Support\|specific language]] use events if they are supported by the language.
Line 681:		Line 681:

	Note that the device itself initiates the function call, by 'firing' the event. This allows you to update only when events fire, and capture all changes, because the low-level interface is telling you when a change occurs.		Note that the device itself initiates the function call, by 'firing' the event. This allows you to update only when events fire, and capture all changes, because the low-level interface is telling you when a change occurs.



	==Advanced Concepts==		==Advanced Concepts==

Burley: /* Poll for Data Change */

2012-08-09T14:35:18Z

Poll for Data Change

← Older revision		Revision as of 14:35, 9 August 2012
Line 240:		Line 240:
	To poll for sensor data, or output state, you usually want to look for a '''get...Value''' or '''get...State''' function available in the API for your device. (The API can be found in the [[:Category:UserGuide\|user guide]] for your device.) Then, you simply set up a loop that get the value of a sensor continuously.		To poll for sensor data, or output state, you usually want to look for a '''get...Value''' or '''get...State''' function available in the API for your device. (The API can be found in the [[:Category:UserGuide\|user guide]] for your device.) Then, you simply set up a loop that get the value of a sensor continuously.

	To poll your software object, the object must be [[#Opening the Phidget\|open]]. This is in contrast to the event-driven method above, where all event functions are declared and attached before opening the object.		To poll your software object, the object must be [[#Opening the Phidget\|open]]. This is in contrast to the event-driven method above, where all event functions are declared and attached before opening the object. Note though that you do not need to open and close the object each time you want to poll it. The easiest thing to do is open the device at the beginning of your program and not close it until the end of the program. You can poll it any number of times in the intervening period.

	Note that when you poll the value of a sensor or another attribute, this will probably be within a loop. When you create this loop, the ''more code'' you have within a loop, the ''more slowly'' your loop will run, and the ''more slowly'' you will be sampling the value in practice. This may make you lose data, as described further in the [[#Data Rate\|Data Rate]] section.		Note that when you poll the value of a sensor or another attribute, this will probably be within a loop. When you create this loop, the ''more code'' you have within a loop, the ''more slowly'' your loop will run, and the ''more slowly'' you will be sampling the value in practice. This may make you lose data, as described further in the [[#Data Rate\|Data Rate]] section.

← Older revision		Revision as of 14:35, 9 August 2012
Line 240:		Line 240:
	To poll for sensor data, or output state, you usually want to look for a '''get...Value''' or '''get...State''' function available in the API for your device. (The API can be found in the [[:Category:UserGuide\|user guide]] for your device.) Then, you simply set up a loop that get the value of a sensor continuously.		To poll for sensor data, or output state, you usually want to look for a '''get...Value''' or '''get...State''' function available in the API for your device. (The API can be found in the [[:Category:UserGuide\|user guide]] for your device.) Then, you simply set up a loop that get the value of a sensor continuously.

	To poll your software object, the object must be [[#Opening the Phidget\|open]]. This is in contrast to the event-driven method above, where all event functions are declared and attached before opening the object.		To poll your software object, the object must be [[#Opening the Phidget\|open]]. This is in contrast to the event-driven method above, where all event functions are declared and attached before opening the object. Note though that you do not need to open and close the object each time you want to poll it. The easiest thing to do is open the device at the beginning of your program and not close it until the end of the program. You can poll it any number of times in the intervening period.

	Note that when you poll the value of a sensor or another attribute, this will probably be within a loop. When you create this loop, the ''more code'' you have within a loop, the ''more slowly'' your loop will run, and the ''more slowly'' you will be sampling the value in practice. This may make you lose data, as described further in the [[#Data Rate\|Data Rate]] section.		Note that when you poll the value of a sensor or another attribute, this will probably be within a loop. When you create this loop, the ''more code'' you have within a loop, the ''more slowly'' your loop will run, and the ''more slowly'' you will be sampling the value in practice. This may make you lose data, as described further in the [[#Data Rate\|Data Rate]] section.