SerialXtra

SerialXtra for OSX/OS9/Windows
current version 1.0.7f
Copyright Geoff Smith 1999-2004
page last updated:10th April 2004

Description

This is a cross platform Xtra for Macromedia Director(TM) to access the serial port on both the Windows and Mac platforms. There are functions to read from and write to the port in various forms, e.g. string. The Mac has two versions, OS9 and OSX.
For updates on this and my other XObjects/Xtras check out my web page: www.physicalbits.com

Note Mac G4 USB users. The Xtra will work with USB to serial converters. It has been tested on the Keyspan single and 4 way USB to serial adaptor (USA-49A)

Release and Version history

Compatibility

SerialXtra works on Macintosh and Windows operating systems, and has been tested for the following versions:

OS

Version

Yes

No

Not yet available

Untested

Microsoft© Windows 95
•

98
•

2000
•

XP
•

NT 4
•

Apple Macintosh Classic (OS9)
•

OSX
•

This Xtra has been tested on the following USB to serial converters

Make

Model

PC

Mac
OSX

Mac
OS9

Notes

Keyspan USA-49W
•

•

•
www.keyspan.com

Belkin F5U109
•

U

U
www.belkin.com

Belkin F5U103
•

•

U
www.belkin.com

Belkin F5U116
•

U

U
www.belkin.com

FTDI DLP-USB232M
•

U

U
www.ftdichip.com

• = Tested and works
X = Tested and does NOT work
U = untested

Installation

There are two methods to install and use this Xtra for Macromedia Director.

Copy the SerialXtra.x32 (PC) or SerialXtra.xtr/SerialXtra.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 serial xtra is loaded, enter the lingo "showxlib" command into Directors message window. This lists all the available xtras, SerialXtra 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: SerialXtra", 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 "SerialXtra")" 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 SerialXtra

Polled method (requires minimum 1.0.4)

set theXtra to new ( xtra "SerialXtra" )
if objectP(theXtra) then
	theXtra.OpenPort("com1")  -- use put FindPorts() to see ports
	if theXtra.IsPortOpen() then
		theXtra.WriteString("abcdefghijkl")
		repeat while theXtra.CharsAvailable() = 0
		end repeat   
		reply = theXtra.ReadString()
		put reply
	end if
end if

Callback method (requires minimum 1.0.6)

set theXtra to new ( xtra "SerialXtra" )
if objectP(theXtra) then
	theXtra.OpenPort("com1")  -- use put FindPorts() to see ports
	if theXtra.IsPortOpen() then
		theXtra.ReadUsingCallback("ReceivedChars", 10)
		theXtra.WriteString("abcdefghijkl")
		put reply
	end if
end if 

on  ReceivedChars theData
	put theData.getProp(#String)
end

What are these callbacks and how do they work?

Part A - Reading from the serial port

Firstly, do not use callbacks unless you have a good reason to, you should normally use the standrad polling technique. 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 SerialXtra

You 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 SerialXtra

Using 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

Use the strandard polling whenever you can, use callbacks where necessary.
Callabacks share the computer with Director, if Director uses all the processing time the background processing required for callbacks cannot happen. Do not use tight repeat loops while waiting for data, in this instance use the normal Read functions.
Do not use the lingo debugger in a callback - will crash Director!!!

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

Commands

Command	Windows	MacOSX	MacOS9
General
New	•	•	•
GetLicenseType	•
OpenPort	•	•	•
ClosePort (Modified 1.0.6)	*	*	*
IsPortOpen	•	•	•
CharsAvailable	•	•	•
SpaceRemainingInOutputBuffer	•	•	•
FlushInputBuffer	•	•	•
FlushOutputBuffer	•	•	•
FindPorts	•	•	•
Control
SetProtocol	•	•	•
SetBaudRate	•	•	•
SetParity	•	•	•
SetDatabits	•	•	•
SetStopbits	•	•	•
SetHandshakeMode	*	*	NYI
SetBufferSize	•	•	•
GetProtocol	•	•	•
Modem pins
AssertDTR	•	•	NYI
GetDTRState	•	•	X
GetCTSState	•	•	NYI
GetDSRState	•	•	X
GetRingState	•	•	X
GetCDState	•	•	X
AssertRTS	•	•	X
Writing to the serial port
WriteNumber	•	•	•
WriteString	•	•	•
WriteHex	•	•	•
WriteBuffer	•	•	•
EnableBufferedWrites (New 1.0.7)	•	•	•
WriteList	NYI	NYI	NYI
Reading from the serial port
ReadNumber	•	•	•
ReadChar	•	•	•
ReadString (Modified 1.0.6)	*	*	*
ReadStringToToken (New 1.0.6)	•	•	NYI
ReadHex (Modified 1.0.6)	*	*	*
ReadBuffer	•	•	•
ReadBufferToToken (New 1.0.6)	•	•	NYI
Callbacks (Reading and error)
ReadUsingCallback (New 1.0.6)	•	•	NYI
ReadUsingCallbackOnToken (New 1.0.6)	•	•	NYI
ReadUsingGlobalVariable (New 1.0.7)	•	NYI	NYI
ReadUsingGlobalVariableOnToken (New 1.0.7)	•	NYI	NYI
Error callback (New 1.0.6)	•	•	NYI
Special
CalcCrc16	•	•	•
CalcCrcCCITT (New 1.0.6)	•	•	•
HexToDec	•	•	•
DecToHex	•	•	•
SplitNumber	NYI	NYI	NYI
JoinNumber	NYI	NYI	NYI
SetMidiMode	X	X	NYI
SendWithNoWait	X	X	NYI

• = Implemented and available on this platform
* = Modified this release
X = Cannot be implemented on this platform
NYI = Not yet implemented

Version release history

New

Command format	new xtra "SerialXtra
Description	Standard command to create a new instance of an object.
Parameters
Notes	New can take between .3 to 3 seconds to complete. Recommend you open once and use throughout scripts.
Return value	The object, or a minus number is an error. Test with Lingo objectP command
Example	set gObj to new( xtra "SerialXtra")

GetLicenseType

Command format	GetLicenseType object me
Description	Query the current license for this xtra
Parameters
Notes
Return value	"Author", "Demo" or "Full"
Example	put gObj.GetLicenseType()

OpenPort

Command format	OpenPort object me string portName
Description	Open a port with the name portName
Parameters	me: the identifier returned from new. portName: the name of the port to use. Standard Windows ones are "COM1", "COM2". On the classic Mac "modem" and "printer" are normal. If you have a USB serial port adaptor use "put findports()' The default protocol is 9600, 8 databits, 1 stop bit and no parity.
Notes	To discover the name of a port use "put findports()".
Return value	"ok" or error messages starting with "Error :"
Example	gObj.Open("USA911P4.4")

ClosePort

Command format	ClosePort object me
Description	Close an open port
Parameters	me: the identifier returned from new.
Notes
Return value	"ok" or error messages starting with "Error :"

IsPortOpen

Command format	IsPortOpen object me
Description	Check to see if a port is open, returns true (1) if open, else false (0)
Parameters	me: the identifier returned from new.
Notes
Return value	"ok" or error messages starting with "Error :"

SetProtocol

Command format	SetProtocol object me, integer baud, string parity, integer dataBits, integer stopBits
Description	This command allows you to set the communication protocol to use, all are set at the same time. The default protocol is 9600, 8 databits, 1 stop bit and no parity.
Parameters	me: the identifier returned from new. baud: the communication speed - the maximum can be found using the FindPorts command. parity: a string of one character "e"=even, "o"=odd and "n"=none. Sets the parity. dataBits: the number of bits in the data word, either 7 or 8 stopBits: the number of stop bits, either 1 or 2
Return value	either "Ok" or error message starting with the word "Error :"
Example	gObj.SetProtocol( 19200,"e",8,1)

SetBaudRate

Command format	SetBaudRate object me, integer newBaudRate
Description	This command allows you to set the communication baud rate, the maximum can be found using the FindPorts command. Default is 9600
Parameters	me: the identifier returned from new. newBaudRate: the new speed. Only certain speeds are valid, normally 300, 1200, 2400, 4800, 9600, 19200, 38400,57600,115200,230400. Not all machines/cards support all speeds.
Return value	either "OK" or error message starting with the word "Error :"
Example	gObj.SetBaudrate(2400)

SetParity

Command format	SetParity object me, string parity
Description	This command allows you to set the communication parity. Default is none.
Parameters	me: the identifier returned from new. Parity: a string of one character "e"=even, "o"=odd and "n"=none. Sets the parity.
Return value	either "OK" or error message starting with the word "Error :"
Example	gObj.SetParity("n") -- set parity to none

SetDatabits

Command format	SetDataBits object me, integer dataBits
Description	This command allows you to set the number of databits is each word. The default is 8
Parameters	me: the identifier returned from new. dataBits: the number of bits in the data word, either 7 or 8
Return value	either "OK" or error message starting with the word "Error :"
Example	gObj.SetDatabits(7) -- set the number of data bits in a "letter" to 7

SetStopbits

Command format	SetStopBits object me, integer numStopBits
Description	This command allows you to set the number of stop bits to use with each data word. Default is 1
Parameters	me: the identifier returned from new. stopBits: the number of stop bits, either 1 or 2
Return value	either "OK" or error message starting with the word "Error :"
Example	gObj.SetStopbits(2) -- set the number of stopbits to 2

SetHandshakeMode

Command format	SetHandshakeMode object me, symbol newModeType
Description	This command sets the handshaking mode used in the serial communications to control to flow of bytes to/from the serial port. The default is HARDWARE_DTR. newModeType is one of: #HARDWARE_DTR - use the DTR line #NO_HANDSHAKE - do not use handshaking #XON_XOFF - use XON/XOFF chars when buffer is too full
	me: the identifier returned from new. newModeType: see above
Return value	either "OK" or error message starting with the word "Error :"
Example	gObj.SetHandshakeMode( #XON_XOFF)

SetBufferSize

Command format	SetBufferSize object me, integer newInBufferSize, integer newOutBufferSize
Description	Sets the size of the buffer for receiving characters. The default is 1024, but if you are receiving lots of data or are only occasionally going to read the information into Director, then increase this size.
Parameters	me: the identifier returned from new. newInBufferSize: a number that is the new size for the input buffer. newOutBufferSize: a number that is the new size for the output buffer.
Return value	either "OK" or error message starting with the word "Error :"
Example	gObj.SetBufferSize( 3000,3000)

GetProtocol

Command format	GetProtocol object me
Description	Returns a property list with the following items: #BaudRate/"BaudRate" - the current baud rate setting #Parity/"Parity" - the current parity settin #StopBits/"Stopbits" - current number of stopbits
Parameters	me: the identifier returned from new.
Return value	either property list of current serial port settings or error message starting with the word "Error :"

WriteNumber

Command format	WriteNumber object me, integer data
Description	Writes a number to the open serial port. This number has to be in the range 0-255
Parameters	me: the identifier returned from new. data: a number between 0 and 255
Return value	either "OK" or error message starting with the word "Error :"
Example	gObj.WriteNumber( 12)

WriteString

Command format	WriteString object me, string data
Description	Writes a string to the open serial port.
Parameters	me: the identifier returned from new. Data: a string of any length.
Return value	either "OK" or error message starting with the word "Error :"
Example	gObj.WriteString( "Hello world")

WriteHex

Command format	WriteHex object me, string data
Description	Writes a 1 or more numbers supplied as a "hex string" to the open serial port
Parameters	me: the identifier returned from new. Data: a string of "hex" numbers. The string is composed of sets/pairs of hex digits. eg "3A 4D 06". There may be 1 or more sets - the space between them is optional, but if left out the digits must occur in pairs. eg "3A4D06".
Return value	either "OK" or error message starting with the word "Error :"

WriteList - NOT YET IMPLEMENTED

Command format	WriteHex object me, linear list data
Description	Writes the contents of a list to the serial port
Parameters	me: the identifier returned from new. Data: A linear list that can be a mixture of numbers and strings. Note, any numbers greater than 255 will be converted to consecutive bytes using SplitNumber.
Return value	either "OK" or error message starting with the word "Error :"
Example	gObj.WriteList( [ "Hello",12,13,0,15,65536,"the end" ] )

WriteBuffer

Command format	WriteBuffer object me, linear list
Description	Writes a linear list of numbers to the serial output. Both do the same
Parameters	me: the identifier returned from new. Linear list: A list of numbers between 0 and 255.
Return value	either "OK" or error message starting with the word "Error :"

EnableBufferedWrites

Command format	EnableBufferedWrites object me, integer trueOrFalse
Description	When enabled with true(1) data being written to the serial port is placed in buffer, then control is returned to Director. In the background the data is sent. If false (0), the default setting, control is not returned to Director until the last character is sent from the serial port. In some applications this may interfere with the smoothness of the movie.
Parameters	me: the identifier returned from new. Integer: Either true(1) or false(0)
Return value	either "OK" or error message starting with the word "Error :"

ReadNumber

Command format	ReadNumber object me
Description	Read the next single byte waiting in the serial port buffer, returns 0-255 or void. If the expected data will have any '0's in it, use this command. If you try to read a string and there is a '0' Director will have problems.
Parameters	me: the identifier returned from new.
Return value	Returns the number, range 0-255, or 'void' if no data waiting in the buffer.

ReadChar

Command format	ReadChar object me
Description	Read the next single byte waiting in the serial port buffer and return it as a single character string.
Parameters	me: the identifier returned from new.
Return value	Returns a single character string or "" if no data waiting in the buffer.

ReadString

Command format	ReadString object me
Description	Reads all the characters currently waiting in the serial port buffer and returns then as a string. Any zero's in the stream are converted to a "."
Parameters	me: the identifier returned from new.
Return value	Returns all the characters in the serial buffer as a string or "" if no data waiting in the buffer.

ReadStringToToken

Command format	ReadStringToToken object me, string token
Description	Reads all the characters currently waiting in the serial port buffer upto, and including, the specified token. Any zero's in the stream are converted to a "."
Parameters	me: the identifier returned from new. token: The character to read upto.
Usage	theXtra.ReadStringToToken( "*")	ReadStringToToken( theXtra, "*")
Return value	Returns all the characters in the serial buffer as a string or "" if no data waiting in the buffer.

ReadHex

Command format	ReadHex object me
Description	Reads all the characters currently waiting in the serial port buffer and returns them as a list of hex digits.
Parameters	me: the identifier returned from new.
Return value	Returns all the characters in the serial buffer as a hex string or []

ReadBuffer

Command format	ReadBuffer object me
Description	Reads all the characters currently waiting in the serial port buffer and returns them as a linear list
Parameters	me: the identifier returned from new.
Return value	Returns all the characters in the serial buffer as numbers in a linear list or []

ReadBufferToToken

Command format	ReadBufferToToken object me, integer token
Description	Reads all the characters, upto and including the token, currently waiting in the serial port buffer and returns them as a linear list
Parameters	me: the identifier returned from new. token: A value between 0-255
Usage	theXtra.ReadBufferToToken( 42 )	ReadBufferToToken( theXtra, 42 )
Return value	Returns all the characters in the serial buffer as numbers in a linear list.

ReadUsingCallback

Command format	ReadUsingCallback object me, string handlerName, integer triggerLevel
Description	The serial port is monitored for new characters, each new character is placed into a buffer. When the buffer exceeds the trigger level the lingo handler is called. See callbacks section for more detail.
Parameters	me: the identifier returned from new. handlerName: The lingo handler to call when the buffer exceeds the level triggerLevel: The level at which to call the handler
Usage	theXtra.ReadUsingCallback("handler",10)	ReadUsingCallback(theXtra,"handler",10)
Return value	"Ok" or message starting with "Error :"

ReadUsingCallbackOnToken

Command format	ReadUsingCallbackOnToken object me, string handlerName, integer triggerToken
Description	The serial port is monitored for new characters, each new character is placed into an input buffer. When the trigger token enters the serial port all the current contents of the input buffer are sent to the lingo handler. See callbacks section for more detail.
Parameters	me: the identifier returned from new. handlerName: The lingo handler to call when the buffer exceeds the level triggerToken: The character arriving that triggers the lingo handler
Usage	theXtra.ReadUsingCallbackOnToken("handler",42)	ReadUsingCallbackOnToken(theXtra,"handler",42)
Return value	"Ok" or message starting with "Error :"

ReadUsingGlobalVariable

Command format	ReadUsingGlobalVariable object me, string variableName, integer triggerLevel
Description	The serial port is monitored for new characters, each new character is placed into an input buffer. When the buffer exceeds the trigger level the data is added to the global variable. See callbacks section for more detail.
Parameters	me: the identifier returned from new. variableName: The lingo global varaible to be used for the data triggerLevel: The level at which to call the handler
Usage	theXtra.ReadUsingGlobalVariable("aVariable",10)	ReadUsingGlobalVariable(theXtra,"aVariable",10)
Return value	"Ok" or message starting with "Error :"

ReadUsingGlobalVariableOnToken

Command format	ReadUsingGlobalVariableOnToken object me, string variableName, integer triggerToken
Description	The serial port is monitored for new characters, each new character is placed into an input buffer. When the trigger token enters the serial port all the current contents of the input buffer are added to the global variable. See callbacks section for more detail.
Parameters	me: the identifier returned from new. variableName: variableName: The lingo global varaible to be used for the data triggerToken: The character arriving that triggers the transfer to the global variable
Usage	theXtra.ReadUsingGlobalVariableOnToken("aVariable",42)	ReadUsingGlobalVariableOnToken(theXtra,"aVariable",42)
Return value	"Ok" or message starting with "Error :"

CharsAvailable

Command format	CharsAvailable object me
Description	Returns the number of characters currently waiting in the serial port input buffer to be read
Parameters	me: the identifier returned from new.
Return value	Returns the number of characters currently waiting in the serial port input buffer to be read.

FlushInputBuffer

Command format	FlushInputBuffer object me
Description	Discards any characters waiting in the input buffer
Parameters	me: the identifier returned from new.
Return value	either "OK" or error message starting with the word "Error :"

FlushOutputBuffer

Command format	FlushOutputBuffer object me
Description	Discards any characters waiting in the output buffer
Parameters	me: the identifier returned from new.
Return value	either "OK" or error message starting with the word "Error :"

FindPorts

Command format	FindPorts
Description	Returns the number and name of the serial ports installed on the machine. It returns a list of lists, the count is the number of ports. Each item in the list is a list of the name of the port, used in the new message and the maximum speed of the port. If the max speed is -1 then the port is in use and the maximum speed cannot be determined. Returns the following symbols (Not all platforms) #PortName #MaxBaudrate #Fullname #InUse - is "Yes" or "No"
Parameters	None
Return value	A list of lists as described above or error message starting with the word "Error :"

AssertDTR

Command format	AssertDTR object me, integer trueOrFalse
Description	The DTR line is a pin on the serial connector. When set the device on the other end of the serial cable knows that it can send information. Originally a form of speed control for slow computers. Today it is rarely used, but some devices require this to be set.
Parameters	me: the identifier returned from new. trueOrFalse: 1=set it on, 0=set it off
Return value	either "OK" or error message starting with the word "Error :"

GetCTSState

Command format	GetCTSState object me
Description	Returns the current state of the CTS line on the PC serial port. 1= active 0=inactive. This can only be read
Parameters	me: the identifier returned from new.
Return value	either 1 or 0 - or error string

GetRingState

Command format	GetRINGState object me
Description	Returns the current state of the ring line on the PC serial port. 1= active 0=inactive. This can only be read
Parameters	me: the identifier returned from new.
Return value	either 1 or 0 - or error string

GetDSRState

Command format	GetDSRState object me
Description	Returns the current state of the DSR (Data Set Ready) line on the PC serial port. 1= active 0=inactive. This can only be read
Parameters	me: the identifier returned from new.
Return value	either 1 or 0 - or error string

GetCDState

Command format	GetCDState object me
Description	Returns the current state of the CD (carrier detect) line on the PC serial port. 1= active 0=inactive. This can only be read
Parameters	me: the identifier returned from new.
Return value	either 1 or 0 - or error string

CalcCRC16

Command format	CalcCRC16 linearList
Description	This function calculates a common 16 bit CRC using the following function: int CalcCRC16( const char ptr, const long len ) { int crc, i; long count = len; crc = 0; while (--count >= 0) { crc = crc ^ (int)ptr++ << 8; for (i = 0; i < 8; ++i) if (crc & 0x8000) crc = crc << 1 ^ 0x1021; else crc = crc << 1; } return (crc & 0xFFFF); }
Parameters	me: the identifier returned from new. linearList:
Example	reply = CalcCRC16([1,2,3,4,5,6,7]) put reply.crcLo put reply.crcHi
Return value	either property list with #crcLo and #crcHi or error message starting with the word "Error :"

CalcCrcCCITT

Command format	CalcCrcCCITT linearList
Description	This function calculates a common CRC CCITT using the following function: unsigned calc_crc(unsigned char data, unsigned n, unsigned start) { unsigned I, k, q, c, crcval; crcval=start; for (I=0; I<n; I++) { c=data(I) & 0xFF; q=(crcval^c) & 0x0F; crcval=(crcval>>4)^(q0x1081); q=(crcval^(c>>4)) & 0x0F; crcval=(crcval>>4)^(q*0x1081); } }
Parameters	me: the identifier returned from new. linearList:
Example	reply = CalcCrcCCITT([1,2,3,4,5,6,7]) put reply.crcLo put reply.crcHi
Return value	either property list with #crcLo and #crcHi or error message starting with the word "Error :"

AssertRTS

Command format	AssertRTS object me, integer trueOrFalse
Description	The RTS line is a pin on the serial connector. This informs any device on the other end of the cable that you want to send some information. Rarely used these days. Not setable on a Mac.
Parameters	me: the identifier returned from new. trueOrFalse: 1=set it on, 0=set it off
Return value	either "OK" or error message starting with the word "Error :"

HexToDec

Command format	HexToDec string hex
Description	Converts a 2 digit hex string to a decimal number
Parameters	hex: a two digit hex string to convert to a decimal eg 4F
Example	put HexToDec("A1")
Return value	either "OK" or error message starting with the word "Error :"

DecToHex

Command format	DecToHex integer number
Description	Converts a number to a hex string
Parameters	number: a decimal number
Example	put DecToHex(3200)
Return value	either "OK" or error message starting with the word "Error :"

SplitNumber/JoinNumber

Command format	SplitNumber integer number JoinNumber linear list of four numbers
Description	SerialXtra accepts and sends data in bytes/chars. Each value ranges from 0-255. If you want to send a bigger number you need to spilt this number in separate bytes and send them. SplitNumber does this work for you, returning a linear list of numbers in the range 0-255. An integer number in Director can range from -2,147,483,648 to 2,147,483,647; this is 4 numbers, or bytes, in length. Split converts the Director into 4 number suitable for sending down the serial port, it returns a linear list of the numbers. JoinNumber takes a linear list of 4 numbers that have been split and converts them into an integer. The lingo equivalent of this is: byte1 = integer(number/16777216) number=number-(byte116777216) byte2 = integer(number/65536) number = number-(byte265536) byte3 = integer(number/256) byte4 = number-(number256) data = [byte1,byte2,byte3,byte4] -- to reassemble number = (byte116777216)+(byte265536)+(byte3256)+byte4
Parameters	number: a decimal number linear list: a list of four number in the range 0-255
Example	put SplitNumber(18000314) put JoinNumber( [1,45,6,1])
Return value	Either linear list or "Error:"

Error Callback

Command format
Description	The error callback handler is always enabled and does not have a to be called. To use define a global handler named "SerialXtra_XtraError". Whenever an error occurs within the xtra this handler will be called. It is passed one parameter, a property list that has the following properties: #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 See callbacks for more detail.
Parameters
Usage
Return value

SetMidiMode - Mac only

Command format	SetMidiMode object me
Description	Puts the serial port into midi mode. Attach a standard Mac midi interface and you can receive the raw midi data using the ReadNumber command. This will most probably only work with "true" Mac RS422 serial ports - the USB to serial converters will not support this.
Parameters	me: the identifier returned from new.
Return value	either "OK" or error message starting with the word "Error :"

SendWithNoWait - Mac only

Command format	SendWithNoWait object me, integer trueOrFalse
Description	Normally control is only returned to Director once the data has been sent out the serial port, allowing errors to be reported as they occur. Setting this to true/1 forces return to Director once the data has been put in the serial output buffer. The default value for this is false/0.
Parameters	me: the identifier returned from new trueOrFalse: true/1 to return immediately, false/0 to wait until data is sent
Return value	either "OK" or error message starting with the word "Error :"

Known Issues

ID	Descrition	Status
A1	Using Write command with data to be sent over 5000 will crash Director. Data over 10,000 chars will be discarded.	Temporary fix in place. Need to rework to remove any limitation on a single write.
A2	When used in a projector the write may fail	Workaround, use DoAsyncWrites(false)

Version History

Version	Date	MacOSX	MacOS9	PC	Notes
1.0.7f	4/10/04	•	•	•	Removed feature: No license key requires Bug fix: ShowDialog was not updating settings Change: Parrtiy now has #Mark and #Space settings Bug fix:RTS was not being set on hardware handshake Bug fix: DTR and RTS now on always
1.0.7e	1/31/04	•	•	•	New handler:EnableBufferedWrites - default is non-buffered Bug fix:Buffer count rollover was loosing data Bug fix :Crash on second run of Director Change:Improved messages threading Bug fix:Removed protection from full license Bug fix:Code was not handling opening twice correctly
1.0.7c	1/4/04	•	•	•	Emergency fix for licence code issue
1.0.7a	10/10/03	•	•	•	Added ReadUsingGlobalVariable/OnToken Bug fix:ReadUsingCallback was ignoring level value Bug fix:ReadNumber was crashing Director Bug fix:Large WriteXXX were overunning buffer BugFix SpaceRemainingInOutputBuffer was returning input buffer space
1.0.6b	10/7/03	•	•	•	Bug fix: Default buffer size changed, now 50,000
1.0.6a	10/1/03	•	•	•	Added ReadOnCallback/ToToken Aded ReadString/BufferToToken Added CalcCrcCCITT Callback on error added Changed default handshaking to #NO_HS Bug fix:crash if 0 in string Bug fix: readhex returning negative numbers Bug fix: Xtra was being delelted incorrectly Bug fix: Close port not returning ok
1.0.4	8/24/03	•		•	Added modem control pins for OSX Added AsertDTR/RTS to OSX Bug fix: Readhex dropped leading 0 Modifed findports to return #MaxBaudRate Added SetHandshakeMode Re-organised New to increase speed Added global function to calculate CRC16 Added WriteBuffer Modified GetProtocol to return symbols for properties Added IsSerialPortOpen function Added HexToDec (All) Added DecToHex (All)
1.0.3	7/18/03	•	•	•	Added ReadBuffer Added GetVersionString Fixed AssertRTS bug (PC) Modified write to work asynchronously (PC) Bug fix on large writes (PC)
1.0.2	6/8/03	•	•	•	Changed the Findports to return symbols in property list Changed readBuffer to return 0-255 Changed to "release"
1.0.1.2	5/15/03			•	Added FULL support, added new message "GetLicenseType
1.0.1	4/15/03	•	•	•	Initial Mac OS9 and PC releases
1.0.0	3/15/03	•			Initial MacOSX releases
0.9l	12/02/02			•	PC:Modified FindPorts to support wider platforms
0.9k	11/8/02		•	•	Mac: Added new messages SendWithNoWait PC & MAC: Modified WriteHex to send out all chars at once, rther than decoding the number and sending that one byte.
0.9j	6/19/02			•	PC: Added getCTS/DSR/RING/CD line states
0.9i	11/18/01		•		Added support for Mac 115200 and 230400 baud rate setings
0.9h
0.9g	1/6/01				Re-fixed the SetProtocol bug
0.9f	10/00				Fixed SetProtocol bug
0.9e	4/00				Marked shockwave safe
0.9d	3/28				Added ReadHex and WriteHex
0.9c	3/00				Bug fix: \0 not sent by WriteNumber
0.9b	1/99				Bug fixes Added RTS/CTS control Added Mac midi mode
0.9a	12

OS	Version	Yes	No	Not yet available	Untested
Microsoft© Windows	95				•
	98				•
	2000	•
	XP	•
	NT 4				•
Apple Macintosh	Classic (OS9)	•
Apple Macintosh	OSX	•

Make	Model	PC	Mac OSX	Mac OS9	Notes
Keyspan	USA-49W	•	•	•	www.keyspan.com
Belkin	F5U109	•	U	U	www.belkin.com
Belkin	F5U103	•	•	U	www.belkin.com
Belkin	F5U116	•	U	U	www.belkin.com
FTDI	DLP-USB232M	•	U	U	www.ftdichip.com