SerialXtra
current version 0.9i
Copyright Geoff Smith 1999-2001
page last updated:20th November 2001
SerialXtra
current version 0.9i
Copyright Geoff Smith 1999-2001
page last updated:20th November 2001
 |
 |
and |
 |
|
|
 |
|
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. It should work in Director 5, 6 & 7. Although it has only been tested in 6 & 7.
For updates on this and my other XObjects/Xtras check out my web page:Note Mac G4 USB users. The Xtra will work with USB to serial convertors. It has been tested on the Keyspan single and 4 way USB to serial adaptor (USA-49A)
To assist you to use the SerialXtra in Shockwave I have added a SerialXtra Shockwave section that explains how to and where install files. It includes a set of demo files.
Compatibility
Microsoft© Windows 95 98 2000 XP NT 4 Apple Macintosh Classic (OS9) OSX
Installation
There are two methods to install and use this Xtra for Macromedia Director.
Copy the SerialXtra.x32 (PC) or SerialXtra.xtr (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 Directors 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.To check that the xtra is loaded enter lingo "showxlib" command into Directors message window, this lists all the available xtras. If the xtra is not named in the list some error has occured. 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 afer openxlib and interface lingo commands have been executed
(Varies with different versions)
Commands
| General | |
| New | |
| Control | |
|
SetProtocol |
|
| Writing to the serial port | |
| Reading from the serial port | |
|
|
ReadNumber ReadChar ReadString ReadHex |
| Special | |
| AssertRTS-
Windows only SetMidiMode - Mac only |
| Command format | new string portName |
| Description | Standard command to create a new instance of an object. It requires one parameter that indicates the serial port to use |
| Parameters |
portName: the
name of the port to use. |
| Notes | To discover the name of a port use "put findports()" |
| Return value | instance value or error number. Test with Lingo objectP command |
| 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. |
| Return value | either "Ok" or error message starting with the word "Error :" |
| 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. |
| Return value | either "OK" or error message starting with the word "Error :" |
| 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. |
| Return value | either "OK" or error message starting with the word "Error :" |
| 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. |
| Return value | either "OK" or error message starting with the word "Error :" |
| 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. |
| Return value | either "OK" or error message starting with the word "Error :" |
| Command format | SetBufferSize object me, integer newBufferSize |
| 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. |
| Return value | either "OK" or error message starting with the word "Error :" |
| 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. |
| Return value | either "OK" or error message starting with the word "Error :" |
| Command format | WriteString object me, string data |
| Description | Writes a string to the open serial port. |
| Parameters |
me: the identifier
returned from new. |
| Return value | either "OK" or error message starting with the word "Error :" |
| 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. |
| Return value | either "OK" or error message starting with the word "Error :" |
| 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. |
| 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. |
Command format ReadString object me Description Reads all the characters currently waiting in the serial port buffer and returns then as a string. Beware, if there are any 0's in the data incorrect data will be returned. 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.
Command format ReadHex object me Description Reads all the characters currently waiting in the serial port buffer and returns then as a string of hex digits each separated by a space. Parameters me: the identifier returned from new.
Return value Returns all the characters in the serial buffer as a hex string or "" if no data waiting in the buffer. E.g. "4A 56 8F"
| 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. |
| 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 :" |
| 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. E.g. [ ["COM1",19200] , ["COM2",9600] ] |
| Parameters |
None |
| Return value | A list of lists as described above or error message starting with the word "Error :" |
| 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. |
| Return value | either "OK" or error message starting with the word "Error :" |
| 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. |
| Return value | either "OK" or error message starting with the word "Error :" |
| 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 apadtors will not support this. |
| Parameters |
me: the identifier returned from new. |
| Return value | either "OK" or error message starting with the word "Error :" |
| Version | Date | Notes |
| 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 |
| 0.9a | 12/99 | Initial |
Using the SerialXtra in Shockwave requires no additonal commands. Note that the xtra is NOT autodownloadable. Get the user to download it and put it in the correct place. If you require a downloadable version I will assist and produce a packaged version that can be certified, but you will have to obtain your own Verisign(TM) certificate and host it on a server.
The user manual describes the placement of the xtra to be used in Shockwave.
Windows 95/98 = \windows\system\Macromed\Shockwave 8\Xtras
Windows NT = \Winnt\system32\Macromed\Shockwave 8\Xtras
Mac = System folder:Extensions:Macromedia:Shockwave:XtrasUse the publish command to create the dcr that runs under Shockwave. I produced a set of demo files to assist in exploring using the xtra in Shockwave. Download the zip for Windows or for Macintosh (coming soon).
Filename SerialXtraShock.dir A Director movie so that you can examine all the required lingo. SerialXtraShock.dcr The Director movie saved as a Shockwave dcr SerialXtraShock.htm A html file with the embed command. Once you have the Xtra in the correct place (when you start the html document a message diplays if it has found the xtra) you can read and write to the serial port.
Contact details
Email: support@physicalBits.com
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. |
