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

Message	Windows	MacOSX	MacOS9
General
New	•	•	•
Openport	•	•	•
ClosePort	•	•	•
IsPortOpen	•	•	•
FindPorts	•	•	•
Control
SetProtocol	•	•	•
SetBaudRate	•	•	•
SetParity	•	•	•
SetDatabits	•	•	•
SetStopBits	•	•	•
SetHandshakeMode	•	•	•
GetProtocol	•	•	•
Modem pins
AssertDTR	•	•	•
GetCTSState	•	•	•
GetRingState	•	•	•
GetDSRState	•	•	•
GetCDState	•	•	•
AssertRTS	•	•	•
Writing to the serial port
WriteNumber	•	•	•
WriteString	•	•	•
WriteHex	•	•	•
WriteBuffer	•	•	•
WriteList	NYI	NYI	NYI
SetBufferSize	•	•	•
EnableBufferedWrites	•	•	•
FlushOutputBuffer	•	•	•
Reading from the serial port
ReadNumber	•	•	•
ReadChar	•	•	•
ReadString	•	•	•
ReadStringToToken	•	•	•
ReadHex	•	•	•
ReadBuffer	•	•	•
ReadBufferToToken	•	•	•
ReadUsingCallback	•	•	•
ReadUsingCallbackOnToken	•	•	•
ReadUsingGlobalVariable	•	•	•
ReadUsingGlobalVariableOnToken	•	•	•
CharsAvailable	•	•	•
FlushInputBuffer	•	•	•
Special
CalcCRC16	•	•	•
CalcCrcCCITT	•	•	•
HexToDec	•	•	•
DecToHex	•	•	•
SplitNumber	•	•	•
JoinNumber	•	•	•
Misc
ShowErrorsAsDialogs	•	•	•
GetVersionString	•	•	•
GetLicensetype	•	•	•
GetDemoDaysRemaining	•	NYI	NYI
privateInstance	•	•	•
privateGlobal	•	•	•

Version release history

New

Command format	new (xtra "SerialXtra")
Description	Standard command to create a new instance of an object.
Parameters
Notes	You can use showxlib in the message window to check the xtra is available.
Return value	Instance id or ""
Example	put thextra = new ( xtra "SerialXtra")

Openport

Command format	OpenPort object me string portName
Description	Opens a serial port for reading and writing. PortName is the name of the port, eg "com3", using "" opens the default port.
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
Example	theXtra.OpenPort("USA911P4.4")

ClosePort

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

IsPortOpen

Command format	IsPortOpen object me
Description	Check to see if a port has been opened sucessfully with OpenPort, returns true (1) if open, else false (0)
Parameters	object me: The value returned from new
Notes
Return value	Returns 1, true, if open, else 0, false.
Example	put theXtra.IsPortOpen()

FindPorts

Command format	FindPorts optionalAsynch
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	object me: The value returned from new
Notes	The optional asynch parameter was released in 1.0.19 If you call with FindPorts(1) then the command executes in parallel with Director. If the list of ports is not yet ready the call returns "not complete". Keep calling until it returns a list
Return value	List of property lists or error messages starting with
Example	put FindPorts()

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	object me: The value 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
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.SetProtocol(9600,"n",8,1)

SetBaudRate

Command format	SetBaudRate object me
Description	This command allows you to set the communication baud rate, the maximum can be found using the FindPorts command. Default is 9600
Parameters	object me: The value 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.
Notes	Some serial ports allow setting of higher baud rates and single baud increments. Please check with the documentation supplied with your serial port hardware.
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.SetBaudRate(9600)

SetParity

Command format	SetParity object me, stringParity
Description	This command allows you to set the communication parity. Default is none ("n").
Parameters	object me: The value returned from new string Parity: a string of one character "e"=even, "o"=odd and "n"=none. Sets the parity.
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.SetParity("e")

SetDatabits

Command format	SetDatabits object me, integer databits
Description	This command allows you to set the number of databits is each word in or out of the serial port. The default is 8
Parameters	object me: The value returned from new integer databits the number of bits in the data word, either 7 or 8
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.SetDatabits(7)

SetStopBits

Command format	SetStopBits object me, integer stopbits
Description	This command allows you to set the number of stop bits to use with each data word. Default is 1
Parameters	object me: The value returned from new integer stopbits:the number of stop bits, either 1 or 2
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.SetStopBits(2)

SetHandshakeMode

Command format	SetHandshakeMode object me, symbol newMode
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
Parameters	object me: The value returned from new symbol newMode: see above
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.SetHandshakeMode(#HARDWARE_DTR)

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	object me: The value returned from new
Notes
Return value	Property list of current settings or error messages starting with "Error :"
Example	put theXtra.GetProtocol()

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	object me: The value returned from new integer trueOrFalse: 1=set it on, 0=set it off
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.AssertDTR(true)

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	object me: The value returned from new
Notes
Return value	0 or 1 or error messages starting with "Error :"
Example	put theXtra.GetCTSState()

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	object me: The value returned from new
Notes
Return value	1 if active, 0 if inactive or error messages starting with "Error :"
Example	put theXtra.GetRingState()

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	object me: The value returned from new
Notes
Return value	1 if active, 0 if inactive or error messages starting with "Error :"
Example	put theXtra.GetDSRState()

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	object me: The value returned from new
Notes
Return value	1 if active, 0 if inactive or error messages starting with "Error :"
Example	put theXtra.GetCDState()

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	object me: The value returned from new integer trueOrFalse 1=set it on, 0 to turn it off
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.AssertRTS(1)

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	object me: The value returned from new integer data: a number between 0 and 255
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.WriteNumber(14)

WriteString

Command format	WriteString object me, string data
Description	Write the contents of a string to the serial port.
Parameters	object me: The value returned from new string data: The string to send.
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.WriteString("Hello")

WriteHex

Command format	WriteHex object me, string data
Description	Send to the serial port bytes that are representted as hex digits. 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".
Parameters	object me: The value returned from new string Data: A string of "hex" numbers.
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.WriteHex("23 AF 1F")

WriteBuffer

Command format	WriteBuffer object me, list data
Description	Writes a linear list of numbers to the serial output.
Parameters	object me: The value returned from new list data: A list of numbers between 0 and 255.
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.WriteBuffer([2,67,23,1,78])

WriteList

Command format	WriteList object me, list data
Description	Writes the contents of a list to the serial port. The 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.
Parameters	object me: The value returned from new. list data: The list of data items of variable length.
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.WriteList([ "Hello",12,13,0,15,65536,"the end" ])

SetBufferSize

Command format	SetBufferSize object me, integer newInBufferSize, integer newOutBufferSize
Description	Sets the size of the buffer for receiving and sending 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	object me: The value 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.
Notes
Return value
Example	put theXtra.SetBufferSize(3000,3000)

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. The default is true.
Parameters	object me: The value returned from new integer trueOrFalse: 1 enables buffered writes, 0 disables it.
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.EnableBufferedWrites(false)

FlushOutputBuffer

Command format	FlushOutputBuffer object me
Description	Discards any characters waiting in the output buffer
Parameters	object me: The value returned from new
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.FlushOutputBuffer()

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	object me: The value returned from new
Notes
Return value	Returns the number, range 0-255, or 'void' if no data waiting in the buffer.
Example	put theXtra.ReadNumber()

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	object me: The value returned from new
Notes
Return value	Returns a single character string or "" if no data waiting in the buffer.
Example	put theXtra.ReadChar()

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	object me: The value returned from new
Notes
Return value	Returns all the characters in the serial buffer as a string or "" if no data waiting in the buffer.
Example	put theXtra.ReadString()

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. The first character of the string is used as the token, all others are ignored. Any zero's in the stream are converted to a "."
Parameters	object me: The value returned from new string token The character to read upto.
Notes
Return value	Returns all the characters in the serial buffer as a string or "" if no data waiting in the buffer.
Example	put theXtra.ReadStringToToken("*")

ReadHex

Command format	ReadHex object me
Description	Returns all the characters in the serial buffer as a string or [] if no data waiting in the buffer.
Parameters	object me: The value returned from new
Notes
Return value	Returns all the characters in the serial buffer as a hex strings in a list or []
Example	put theXtra.ReadHex()

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	object me: The value returned from new
Notes
Return value	Returns all the characters in the serial buffer as numbers in a linear list or []
Example	put theXtra.ReadBuffer()

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	object me: The value returned from new integer token: The token to read upto.
Notes
Return value
Example	put theXtra.ReadBufferToToken(42)

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 supplying it with the contents of the serial buffer. See callbacks section for more detail.
Parameters	object me: The value returned from new string handlerName: The lingo handler to call when the buffer exceeds the level integer triggerLevel: The level at which to call the handler
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.ReadUsingCallback("AHAndler",10)

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	object me: The value returned from new handlerName: The lingo handler to call when the buffer exceeds the level triggerToken: The character arriving that triggers the lingo handler
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.ReadUsingCallbackOnToken("Handler", 42)

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	object me: The value returned from new variableName: The lingo global varaible to be used for the data triggerLevel: The level at which to call the handler
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.ReadUsingGlobalVariable("variableName", 10)

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	object me: The value returned from new variableName: The lingo global varaible to be used for the data triggerToken: The character arriving that triggers the transfer to the global variable
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.ReadUsingGlobalVariableOnToken("variableName",42)

CharsAvailable

Command format	CharsAvailable object me
Description	Returns the number of characters currently waiting in the serial port input buffer to be read
Parameters	object me: The value returned from new
Notes
Return value	Returns the number of characters currently waiting in the serial port input buffer to be read.
Example	put theXtra.CharsAvailable()

FlushInputBuffer

Command format	FlushInputBuffer object me
Description	Discards any characters waiting in the input buffer
Parameters	object me: The value returned from new
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put theXtra.FlushInputBuffer()

CalcCRC16

Command format	CalcCRC16 list data
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
Notes	list data: Linear list of numbers
Return value	either property list with #crcLo and #crcHi or error message starting with the word "Error :"
Example	reply = CalcCRC16([1,2,3,4,5,6,7]) put reply.crcLo put reply.crcHi

CalcCrcCCITT

Command format	CalcCrcCCITT list data
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>4)^(q*0x1081); q=(crcval^(c>>4)) & 0x0F; crcval=(crcval>>4)^(q*0x1081); } }
Parameters	list data: A linear list of numbers
Notes
Return value	either property list with #crcLo and #crcHi or error message starting with the word
Example	reply = CalcCrcCCITT([1,2,3,4,5,6,7]) put reply.crcLo put reply.crcHi

HexToDec

Command format	HexToDec string data
Description	Converts a 2 digit hex string to a decimal number
Parameters	string data: The hex string to convert
Notes
Return value	"ok" or error messages starting with "Error :"
Example	put HexToDec()

DecToHex

Command format	DecToHex integer number
Description	Converts a number to a hex string
Parameters	integer number: The value returned from new
Notes
Return value	The number converted into a string
Example	put DecToHex()

SplitNumber

Command format	SplitNumber integer number
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-(byte1*16777216) byte2 = integer(number/65536) number = number-(byte2*65536) byte3 = integer(number/256) byte4 = number-(number*256)
Parameters	integer number: The value to split
Notes
Return value	linear list of the number split into 4 0-255 bytes
Example	put SplitNumber(104564)

JoinNumber

Command format	JoinNumber list fourNumberList
Description	Given a 4 byte number that has been split by SplitNumber, join it back into the single value. data = [byte1,byte2,byte3,byte4] -- to reassemble number = (byte1*16777216)+(byte2*65536)+(byte3*256)+byte4
Parameters	list fourNumberList: The value to be joind
Notes
Return value	A single number of the joined values
Example	put JoinNumber([34,56,1,34])

ShowErrorsAsDialogs

Command format	ShowErrorsAsDialogs object objectRef, integer truOrFalse
Description	Controls if error dialogs are shwn in addtion to the error return. Turn this off is you want your problem to handle errors without informing the user
Parameters	objectRef: valid instance of UsbAccessXtra created with "new" trueOrFalse: true to turn dialogs on, or false to turn them off
Notes
Return value	"ok" or "Error"
Example	theXtra.ShowErrorsAsDialogs(0)

GetVersionString

Command format	GetVersionString object objectRef
Description	Obtain the version number of the xtra as a string. This may be requested when you are reporting bugs or interacting with PhysicalBits support.
Parameters	objectRef: valid instance of UsbAccessXtra created with "new"
Notes
Return value	A version string.
Example	put theXtra.GetVersionString()

GetLicensetype

Command format	GetLicenseType object objectRef
Description	Returns the license type for this xtra. #Author, #Demo or #Full
Parameters	objectRef: valid instance of UsbAccessXtra created with "new"
Notes
Return value	#Author, #Demo or #Full
Example	put theXtra.GetLicenseType()

GetDemoDaysRemaining

Command format	GetDemoDaysRemaining object me
Description	Returns the number of days remaining on a demo license. Returns 0 if authoring license, or a big number if a full license.
Parameters	object me: The value returned from new
Notes
Return value	Integer number
Example	put theXtra.GetDemoDaysRemaining()

privateInstance

Command format	privateInstance
Description	Private function
Parameters	Private
Notes	for the curious: 0 = invalid: 1 = internal error reporting, 0=off 1=on: 2 = flow control reporting, 0=off 1=on, 0-100 level: 3 = log messages to file, 0=off 1=on, filname:
Return value
Example

privateGlobal

Command format	privateGlobal
Description	Private
Parameters
Notes
Return value
Example

Known Issues

Issue ID	1
Platform	x86
Description	The first write to serial port after new fails. All others are ok
Work around	When you create a new instance do a dummy write.
Date reported	2006-10-03

There are no outstanding issues at this time

Version History

Version	Date	Platform	Notes
1.0.19	2008-03-28	wintel	Release for Director 11
1.0.17	2006-10-03	wintel
1.0.17	2006-10-03	osx
1.0.15	2005-11-16	wintel	New FindPorts and License code.
1.0.14	2005-11-02	wintel	Many bug fixes
1.0.14	2005-11-02	osx	Many bug fixes
1.0.11	2004-11-20	wintel	Bug fix: Callbacks were crashing Director
1.0.11	2004-11-20	osx	Bug fix: Callbacks were crashing Director
1.0.11	2005-01-12	os9	Bug fix: Callbacks were crashing Director
1.0.9	2004-08-28	wintel	Shockwave flag now set.
1.0.8	2004-07-16	wintel
1.0.7	2004-07-18	osx
1.0.7	2004-07-19	os9

---

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.