SerialXtra
Windows:1.0.19 Released:2008-03-28
Mac OSX:1.0.17 Released:2006-10-03
Mac OS9:1.0.11 Released:2005-01-12
Copyright Geoff Smith 1999-2006
This page last updated Tuesday 02nd of December 2008

Want to read how to use the SerialXtra with Macromedia? Dan O'sullivan and Tom Igoe have published a book on Physical Computing which has a chapter on communicating via the serial port. Goto Amazon for details

• FAQ
• Basic approach
• Error return values
• Lingo error handler
• Moving to a projector
• Shockwave problems
• When you contact PhysicalBits
• Flow through xtra reporting
• Internal error reporting

 

FAQ

Problem/question	Solutions?
I get the error message: Script error : xtra not found or Script error: symbol expected	Director has not found the xtra. Use "showxlib" and check the xtra is in the resulting list. Check the xtra file (x32,xtr or os9) is in the xtras directory in the Macromedia directory . If using openxlib make sure you have the correct path. If you see the filename but no xtra, the file maybe corrupt
What messages are available in the xtra?	Use put mmessagelist( xtra "xtraname") to see a lst of the xtra messages you can use
I purchased the xtra and it still says it cannot be used in a projector	The file you recieved when you purchased the xtra is a special build thta is enabled to be used in projectors. That specific one must be used and included with the projector. Check the Director manual on embedding xtras within the projector.

 

Things to check if you are having problems

Always check error returns from messages, errors normally start with Error. Check the documentation on messages for specifics
When you create a new instance check that it is valid with objectp - if objectp(theXtra) then .... See ErrorReturn for more information

 

Debugging advice

Always check error returns.
Turn on all forms of error handling

• Error reporting popup dialogs, ( on by default )
• Error returns*
• Internal errors*
• Flow reporting*

You can also have the items marked * sent to a disk file be using a hidden message, eg theXtra.privatefunction(3,1,"c:\afile").

When you hit a problem try simplifing the lingo; maybe even starting a new movie that just does the section you are having problems with. Before contacting PhysicalBits support please see the section titled Support


Error return values

Always check the return values from a call. If there has been an issue it will return "Error" as the first word, and then go onto describe the problem. To get more detailed information, or to monitor those messages that normally return data, and therefore cannot always return an error value, please try using the lingo callback error handler.

 

Lingo handler for xtra errors

When an error occurs within the xtra a lingo function is always called with as much details as possible. This is a callback, and will occur between the call to the xtra message and the return from the message. To interact with the callback define a handler in a movie script as below. It is named SerialXtra_XtraError, and is supplied one parameter, a list.

-- Error callback
on SerialXtra_XtraError msg
  put "Error :"&&msg
end

The returned property list wil include the following items:

#XtraName	SerialXtra
#Type	normally #Error, but may be #Warning
#id	an instance id, two instances of the same xtra will have different #id's
#Description	A description of the error
#Help	Any suggestions to correct the problem.

During development I would suggest always having this defined and putting the output to the message window. This does not report all errors, see "internal errors" to trap the complete set.

 

Examining Flow

During execution of your movie xtras are called many times. An xtra may call many functions internally. If you enable flow reporting a lingo handler will be called at most important junctures in the execution. This is primarily designed for PhysicalBits use during coding, but users might want to enable it if there is a sticky problem; or if requested by PhysicalBits to debug an issue. PrivateInstance is a hidden message and does not appear in the xtra's message list.

To interact with the callback define a handler in a movie script as below. It is named SerialXtra_XtraFlow, and is supplied two parameters, a list. The first parameter is the section of the code, the next is an auxillary message, often "enter" or "exit"

To use define the following handler in a movie script.

-- Flow callback 
on SerialXtra_XtraFlow msg, msg2 
		put "Flow :"&&msg&&msg2 
end

This message is fully enabled generates LOTS of calls to the lingo handler. To control this, all flow messages are given a "importance" value between 1 and 100 - when you enable the flow reporting you supply a value and only messages above that level call the lingo handler.

• 0 = all messages
• 50 = average importance messages
• 100 = only the most important

And enable by executing the following xtra message,

			theXtra.PrivateInstance(2,1,theLevel) -- flow reporting on 0 - all 50 - medium 100 few

To disable use this message

      	theXtra.PrivateInstance(2,0) -- flow  reporting off


Examining internal errors

This is used by PhysicalBits for debugging and can be requested of a user to assist in a problem. The output from this technique can be misleading, often errors are not fatal; in fact a natural part of the program. This generates a call to a lingo handler every time a value is assigned to an internal error value, even if it is dealt with correctly later on in the xtra. PrivateInstance is a hidden message and does not appear in the xtra's message list.

To use define the following handler in a movie script.

-- Error callback
     on SerialXtra_InternalError msg
 put "Internal Error :"&&msg
 end

And enable by executing the following xtra message,

			theXtra.PrivateInstance(1,1) -- internal error reporting on 

To disable use this message

			theXtra.PrivateInstance(1,0) -- internal error reporting off


  

 

Support

PhysicalBits offers email support on all it's xtras. If you are having problems using the xtra please read the website information first. If you are still having a problem please email support@physicalbits.com,. Please include:

• The name of the xtra , SerialXtra
• The version of the xtra
• The platform the problem occured, and if it happens on multiple platforms
• A description of the problem
• If possible, the Director movie where it occured, or a small movie that demostartes the issue
• If puchased the order number
• An email address to contact you

Shockwave issues

SerialXtra may be used in Shockwave. To use an xtra in Shockwave you need the xtra file to be placed in the following location.

Location of Shockwave Xtras folder (versions 8 and above):

Macintosh 9.x

System Folder > Extensions > Macromedia > Shockwave 8 > Xtras

Macintosh OS X (version 8.5 and above only)

Library > Application Support > Macromedia > Xtras

Windows 95 and Windows 98 ME

Windows > System > Macromed > Shockwave 8 > Xtras

Windows NT4 and 2000

Winnt > System32 > Macromed > Shockwave 8 > Xtras

Windows XP (version 8.5 and above only)

Windows> System32 > Macromed > Shockwave 8 > Xtras

None of he PhysicalBits xtras are auto-downloadable, your user wll need to download the xtra and place it in the appropriate location.

 

Moving to a projector

When you create a projector you will need a full purchased version of the xtra. When you puchase the xtra you will download or be sent a new file that has been enabled to be sed in a projector - use that on only. The full version works exactly the same as the orignal one ( assuming you used a similar version). 99% of all issues when moving to a projector are that the wrong file wa used or in the wrong place.
Once you are sure things are workin correctly you might want to turn off the error dialogs generated by the xtra (ShowErrorsAsDialogs(false)) and handle any errors within the lingo code.

 

 

 

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.