UsbAccessXtra(Beta)
Windows:1.0.8 Released:2006-11-09
Mac OSX:1.0.0 Released:2004-12-07
Mac OS9:1.0.0 Released:2004-12-28
Copyright Geoff Smith 1999-2006
This page last updated Tuesday 02nd of December 2008
Information |
The UsbAccess Xtra allows HID access to a USB device attached to the computer using Macromedia Director(TM). You are able to read and write between the device and the computer. Note that system devices, like the keyboard and mouse, are not accessable.
For updates on this and my other XObjects/Xtras check out my web page: www.physicalbits.com
UsbAccessXtra is available for the Microsoft Windows and Apple Macintosh platforms.Comptiability with various versions of the plaforms is out lined below:
Microsoft© Windows 95 98 2000 XP NT 4 Apple Macintosh Classic (OS9) OSX
There are two methods to install and use this Xtra for Macromedia Director.
Copy the UsbAccessXtra.x32 (PC) or UsbAccessXtra.xtr/UsbAccessXtra.OS9 (Mac) into the Xtras folder inside the folder with the Director main program. When you start Director it looks inside, and makes available, any xtras inside the Xtras folder.
The other method is to place the xtra in some folder, and use Director's openxlib command before trying to use it. I use this method in my demo movies. If you put the xtra in the Xtras folder you do not need to use the openxlib command. Refer to the Director documentation for further information.If you want to check that the xtra is loaded, enter the lingo "showxlib" command into Directors message window. This lists all the available xtras, UsbAccessXtra should be in the list, if not then some error has occurred. Check the location of the file or use the openxlib command (see above). The figure below shows the presence of the xtra, "-- Xtra: UsbAccessXtra", and because openxlib was used the name of the file that it was read from is shown.
Is the xtra is on the list use "put interface(xtra "UsbAccessXtra")" to list all the messages available in the xtra. It also shows the version of the xtra and if it can be used in a projector.
Example of message window after openxlib and interface lingo commands have been executed
(Varies with different versions)
Simple Example Director Lingo for UsbAccessXtra
What are these callbacks and how do they work?
Firstly, do not use callbacks unless you have a good reason to, you should normally use the standrad polling technique.
Normally you use handlers in Lingo that call messages in an xtra,
Lingo -> handler ->xtra message->internal xtra code-> reply from xtra->handler
If you are wating for some data from the xtra you gave to call it often to see when it arrives, this is callled polling. The xtra buffers data until you request it. You can have your code take responsibility for checking by constantly polling the the xtra to see when data arrives.
This is equivalent to continually calling a friend on the phone to see when they return home, it would be a lot easier for you to leave a message on their voicemail asking them to call you back
Some of the xtra commands use a different technique, callbacks.
Receiving messages can be difficult with serial communication because it is asynchronous, meaning you never know exactly when a message will come in. Luckily your computer has a serial buffer that will hold the incoming messages until your software gets around to checking but eventually you have to check. You can have your code take responsibility for checking by constantly polling the serial port using the "charsAvailable" method and then the various "read" methods probably in the exitframe script. This is equivalent to continually calling a friend on the phone to see when they return home, it would be a lot easier for you to leave a message on their voicemail asking them to call you back.
Traditional polling with Director and the SerialXtraYou can make the same request of the SerialXtra, and offload the responsibility for checking the serial port status to the Xtra, creating a "callback." You tell the Xtra to call you back, that is call one of your handlers when the right amount of stuff has come in the from the serial port. In the background, the xtra will then do all the work you would do in the exitframe, and call the handler you specified with the incoming data delivered as a parameter variable. If you have done internet programming you are probably already familiar with these two ways of dealing with the asynchronous nature of the communication, netlingo uses polling but the multiuser Xtra uses a callback, actionscript uses callbacks for everything.
Callback into Director from the SerialXtraUsing callbacks frees you to concentrate on other things, but has a problem. If there is an error with the SerialXtra it would normally return an error when you poll, now a separate callback, "SerialXtra_XtraError" message is sent. See section below on "Extended error reporting"
Another view of the callback process - ReadUsingCallback
Detail - Callback during normal Director operation (asynchronous)
- In this case the SerialXtra monitors the serial port, and when data arrives the users lingo handler is called. It passes one parameter which is the data that arrived.
- You no longer have to use the "ReadXX" messages.
- ReadUsingCallback - when the serial port buffer size exceeds the user supplied level the user supplied function is called that contains ALL the contents of the serial buffer.
- ReadUsingCallbackOnToken - when the user supplied token value is placed into the serial port buffer, the user supplied lingo handler is called with all the data upto, and including, the token. A token is any value between 0-255, you might use 13, which would return a single "line" of data. You choose the appropriate token value that separates the elements of data you are interested in. Another example is a comma, charToNum(","), which often separates items.
- The functions are passed one parameter, a property list containing #Buffer, the contents in buffer list format and #String, the contents in string format. Note the #string format will have any 0s in the string changed to ".", else Director will crash.
- To use:
--Enable in your code:
theXtra.ReadUsingCallbackOnToken( "ALingoFunctionName", 42 ) --Define as a global handler on ALingoFunctionName thedata
put theData
end
-- [#Buffer:[65,65,66,42],#String:"AAB*"] , assuming token = "*" ( numtochar(42) )
NOTES on Callbacks
Part B - Extended error reporting
- Callback during a call into the xtra (synchronous)
- The lingo handler SerialXtra_XtraError is called whenever an error occurs with the xtra. This is in addition to the normal return value.
- These error messages are more detailed
- SerialXtra_XtraError has one parameter that is a property list containing:
- #Xtraname, SerialXtra
- #Type, at the moment this is always #Error.
- #Description, a description of the error
- #Help, if possible a possible way to resolve the problem
- #Id, an id for this instance of the xtra
- To use define a new lingo global handler as below:
on SerialXtra_XtraError theMsg
put theMsg
end
Conditions of use
In this document Xtra refers to this Xtra, and me refers to Geoff Smith. All rights to the XObject/Xtra are retained by me. The XObject may be used in any MacroMedia Director document for personal use and given to your friends. All documentation must be included when passing on the XObject/Xtra. Unless licensed you may NOT do the following ·distribute for profit without prior permission. ·distribute for profit within a Director presentation without prior permission ·distribute by CD-ROM without prior permission. ·distribute as part of a collection without prior permission ·be used in a public presentation without prior permission.
Financial liabilty for this product is limited to the purchase price or $1, whichever is greater.
All legal proceeding must be carried out under the auspices of the court of Santa Clara, California, USA. These conditions may be modified at any time. Please refer to the physicalbits website for the latest conditions.
