SerialXtra for Adobe Director
Messages:
General
| Name | Description |
|---|
|
New | Standard command to create a new instance of an object. |
Openport | Opens a serial port for reading and writing. PortName is the name of the port, eg "com3", using "" opens the default port. |
ClosePort | Close an open serial port. |
IsPortOpen | Check to see if a port has been opened sucessfully with OpenPort, returns true (1) if open, else false (0) |
FindPorts | 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" |
Control
| Name | Description |
|---|
|
SetProtocol | 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. |
SetBaudRate | This command allows you to set the communication baud rate, the maximum can be found using the FindPorts command. Default is 9600 |
SetParity | This command allows you to set the communication parity. Default is none ("n"). |
SetDatabits | This command allows you to set the number of databits is each word in or out of the serial port. The default is 8 |
SetStopBits | This command allows you to set the number of stop bits to use with each data word. Default is 1 |
SetHandshakeMode | 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 |
GetProtocol |
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 |
Modem pins
| Name | Description |
|---|
|
AssertDTR | 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. |
GetCTSState | Returns the current state of the CTS line on the PC serial port. 1= active 0=inactive. This can only be read |
GetRingState | Returns the current state of the ring line on the PC serial port. 1= active 0=inactive. This can only be read |
GetDSRState | 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 |
GetCDState | Returns the current state of the CD (carrier detect) line on the PC serial port. 1= active 0=inactive. This can only be read |
AssertRTS | 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. |
Writing to the serial port
| Name | Description |
|---|
|
WriteNumber | Writes a number to the open serial port. This number has to be in the range 0-255 |
WriteString | Write the contents of a string to the serial port. |
WriteHex | 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". |
WriteBuffer | Writes a linear list of numbers to the serial output. |
WriteList | 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. |
SetBufferSize | 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. |
EnableBufferedWrites | 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. |
FlushOutputBuffer | Discards any characters waiting in the output buffer |
Reading from the serial port
| Name | Description |
|---|
|
ReadNumber | 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. |
ReadChar | Read the next single byte waiting in the serial port buffer and return it as a single character string. |
ReadString | 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 "." |
ReadStringToToken | 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 "." |
ReadHex | Returns all the characters in the serial buffer as a string or [] if no data waiting in the buffer. |
ReadBuffer | Reads all the characters currently waiting in the serial port buffer and returns them as a linear list |
ReadBufferToToken | Reads all the characters, upto and including the token, currently waiting in the serial port buffer and returns them as a linear list |
ReadUsingCallback | 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. |
ReadUsingCallbackOnToken | 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. |
ReadUsingGlobalVariable | 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. |
ReadUsingGlobalVariableOnToken | 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. |
CharsAvailable | Returns the number of characters currently waiting in the serial port input buffer to be read |
FlushInputBuffer | Discards any characters waiting in the input buffer |
Special
| Name | Description |
|---|
|
CalcCRC16 | 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);
}
|
CalcCrcCCITT | 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);
}
}
|
HexToDec | Converts a 2 digit hex string to a decimal number |
DecToHex | Converts a number to a hex string |
SplitNumber | 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)
|
JoinNumber | 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
|
Misc
| Name | Description |
|---|
|
ShowErrorsAsDialogs | 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 |
GetVersionString | Obtain the version number of the xtra as a string. This may be requested when you are reporting bugs or interacting with PhysicalBits support. |
GetLicensetype | Returns the license type for this xtra. #Author, #Demo or #Full |
GetDemoDaysRemaining | Returns the number of days remaining on a demo license. Returns 0 if authoring license, or a big number if a full license. |
privateInstance | Private function |
privateGlobal | Private |
Detailed Useage Information:
| | New |
|---|
Description | Standard command to create a new instance of an object. |
Format | new (xtra "SerialXtra") |
Parameters | |
Return Value | Instance id or "" |
Notes | You can use showxlib in the message window to check the xtra is available. |
Example | put thextra = new ( xtra "SerialXtra") |
| | Openport |
|---|
Description | Opens a serial port for reading and writing. PortName is the name of the port, eg "com3", using "" opens the default port. |
Format | OpenPort object me string 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. |
Return Value | |
Notes | To discover the name of a port use "put findports()". |
Example | theXtra.OpenPort("USA911P4.4") |
| | ClosePort |
|---|
Description | Close an open serial port. |
Format | ClosePort object me |
Parameters | me: the identifier returned from new. |
Return Value | "ok" or error messages starting with "Error :" |
Example | theXtra.closePort() |
| | IsPortOpen |
|---|
Description | Check to see if a port has been opened sucessfully with OpenPort, returns true (1) if open, else false (0) |
Format | IsPortOpen object me |
Parameters | object me: The value returned from new
|
Return Value | Returns 1, true, if open, else 0, false. |
Example | put theXtra.IsPortOpen() |
| | 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" |
Format | FindPorts optionalAsynch |
Parameters | object me: The value returned from new
|
Return Value | List of property lists or error messages starting with |
Notes | The optional asynch parameter was released in 1.0.19
If you call with FindPorts(0) 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 |
Example | put FindPorts() |
| | SetProtocol |
|---|
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. |
Format | SetProtocol object me , integer baud, string parity, integer dataBits, integer stopBits |
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
|
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.SetProtocol(9600,"n",8,1) |
| | SetBaudRate |
|---|
Description | This command allows you to set the communication baud rate, the maximum can be found using the FindPorts command. Default is 9600 |
Format | SetBaudRate object me |
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.
|
Return Value | "ok" or error messages starting with "Error :" |
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. |
Example | put theXtra.SetBaudRate(9600) |
| | SetParity |
|---|
Description | This command allows you to set the communication parity. Default is none ("n"). |
Format | SetParity object me, stringParity |
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.
|
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.SetParity("e") |
| | SetDatabits |
|---|
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 |
Format | SetDatabits object me, integer databits |
Parameters | object me: The value returned from new
integer databits the number of bits in the data word, either 7 or 8
|
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.SetDatabits(7) |
| | SetStopBits |
|---|
Description | This command allows you to set the number of stop bits to use with each data word. Default is 1 |
Format | SetStopBits object me, integer stopbits |
Parameters | object me: The value returned from new
integer stopbits:the number of stop bits, either 1 or 2
|
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.SetStopBits(2) |
| | SetHandshakeMode |
|---|
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 |
Format | SetHandshakeMode object me, symbol newMode |
Parameters | object me: The value returned from new
symbol newMode: see above
|
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.SetHandshakeMode(#HARDWARE_DTR) |
| | GetProtocol |
|---|
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 |
Format | GetProtocol object me |
Parameters | object me: The value returned from new
|
Return Value | Property list of current settings or error messages starting with "Error :" |
Example | put theXtra.GetProtocol() |
| | AssertDTR |
|---|
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. |
Format | AssertDTR object me, integer trueOrFalse |
Parameters | object me: The value returned from new
integer trueOrFalse: 1=set it on, 0=set it off
|
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.AssertDTR(true) |
| | GetCTSState |
|---|
Description | Returns the current state of the CTS line on the PC serial port. 1= active 0=inactive. This can only be read |
Format | GetCTSState object me |
Parameters | object me: The value returned from new
|
Return Value | 0 or 1 or error messages starting with "Error :" |
Example | put theXtra.GetCTSState() |
| | GetRingState |
|---|
Description | Returns the current state of the ring line on the PC serial port. 1= active 0=inactive. This can only be read |
Format | GetRingState object me |
Parameters | object me: The value returned from new
|
Return Value | 1 if active, 0 if inactive or error messages starting with "Error :" |
Example | put theXtra.GetRingState() |
| | GetDSRState |
|---|
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 |
Format | GetDSRState object me |
Parameters | object me: The value returned from new
|
Return Value | 1 if active, 0 if inactive or error messages starting with "Error :" |
Example | put theXtra.GetDSRState() |
| | GetCDState |
|---|
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 |
Format | GetCDState object me |
Parameters | object me: The value returned from new
|
Return Value | 1 if active, 0 if inactive or error messages starting with "Error :" |
Example | put theXtra.GetCDState() |
| | AssertRTS |
|---|
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. |
Format | AssertRTS object me, integer trueOrFalse |
Parameters | object me: The value returned from new
integer trueOrFalse 1=set it on, 0 to turn it off
|
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.AssertRTS(1) |
| | WriteNumber |
|---|
Description | Writes a number to the open serial port. This number has to be in the range 0-255 |
Format | WriteNumber object me, integer data |
Parameters | object me: The value returned from new
integer data: a number between 0 and 255
|
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.WriteNumber(14) |
| | WriteString |
|---|
Description | Write the contents of a string to the serial port. |
Format | WriteString object me, string data |
Parameters | object me: The value returned from new
string data: The string to send. |
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.WriteString("Hello") |
| | WriteHex |
|---|
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". |
Format | WriteHex object me, string data |
Parameters | object me: The value returned from new
string Data: A string of "hex" numbers. |
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.WriteHex("23 AF 1F") |
| | WriteBuffer |
|---|
Description | Writes a linear list of numbers to the serial output. |
Format | WriteBuffer object me, list data |
Parameters | object me: The value returned from new
list data: A list of numbers between 0 and 255. |
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.WriteBuffer([2,67,23,1,78]) |
| | WriteList |
|---|
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. |
Format | WriteList object me, list data |
Parameters | object me: The value returned from new.
list data: The list of data items of variable length. |
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.WriteList([ "Hello",12,13,0,15,65536,"the end" ]) |
| | SetBufferSize |
|---|
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. |
Format | SetBufferSize object me, integer newInBufferSize, integer newOutBufferSize |
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.
|
Return Value | |
Example | put theXtra.SetBufferSize(3000,3000) |
| | EnableBufferedWrites |
|---|
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. |
Format | EnableBufferedWrites object me, integer trueOrFalse |
Parameters | object me: The value returned from new
integer trueOrFalse: 1 enables buffered writes, 0 disables it. |
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.EnableBufferedWrites(false) |
| | FlushOutputBuffer |
|---|
Description | Discards any characters waiting in the output buffer |
Format | FlushOutputBuffer object me |
Parameters | object me: The value returned from new
|
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.FlushOutputBuffer() |
| | ReadNumber |
|---|
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. |
Format | ReadNumber object me |
Parameters | object me: The value returned from new
|
Return Value | Returns the number, range 0-255, or 'void' if no data waiting in the buffer. |
Example | put theXtra.ReadNumber() |
| | ReadChar |
|---|
Description | Read the next single byte waiting in the serial port buffer and return it as a single character string. |
Format | ReadChar object me |
Parameters | object me: The value returned from new
|
Return Value | Returns a single character string or "" if no data waiting in the buffer. |
Example | put theXtra.ReadChar() |
| | ReadString |
|---|
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 "." |
Format | ReadString object me |
Parameters | object me: The value returned from new
|
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 |
|---|
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 "." |
Format | ReadStringToToken object me, string token |
Parameters | object me: The value returned from new
string token The character to read upto. |
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 |
|---|
Description | Returns all the characters in the serial buffer as a string or [] if no data waiting in the buffer. |
Format | ReadHex object me |
Parameters | object me: The value returned from new
|
Return Value | Returns all the characters in the serial buffer as a hex strings in a list or [] |
Example | put theXtra.ReadHex() |
| | ReadBuffer |
|---|
Description | Reads all the characters currently waiting in the serial port buffer and returns them as a linear list |
Format | ReadBuffer object me |
Parameters | object me: The value returned from new
|
Return Value | Returns all the characters in the serial buffer as numbers in a linear list or [] |
Example | put theXtra.ReadBuffer() |
| | ReadBufferToToken |
|---|
Description | Reads all the characters, upto and including the token, currently waiting in the serial port buffer and returns them as a linear list |
Format | ReadBufferToToken object me, integer token |
Parameters | object me: The value returned from new
integer token: The token to read upto. |
Return Value | |
Example | put theXtra.ReadBufferToToken(42) |
| | ReadUsingCallback |
|---|
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. |
Format | ReadUsingCallback object me, string handlerName, integer triggerLevel |
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 |
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.ReadUsingCallback("AHAndler",10) |
| | ReadUsingCallbackOnToken |
|---|
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. |
Format | ReadUsingCallbackOnToken object me, string handlerName, integer triggerToken |
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 |
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.ReadUsingCallbackOnToken("Handler", 42) |
| | ReadUsingGlobalVariable |
|---|
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. |
Format | ReadUsingGlobalVariable object me, string variableName, integer triggerLevel |
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 |
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.ReadUsingGlobalVariable("variableName", 10) |
| | ReadUsingGlobalVariableOnToken |
|---|
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. |
Format | ReadUsingGlobalVariableOnToken object me, string variableName, integer triggerToken |
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 |
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.ReadUsingGlobalVariableOnToken("variableName",42) |
| | CharsAvailable |
|---|
Description | Returns the number of characters currently waiting in the serial port input buffer to be read |
Format | CharsAvailable object me |
Parameters | object me: The value returned from new
|
Return Value | Returns the number of characters currently waiting in the serial port input buffer to be read. |
Example | put theXtra.CharsAvailable() |
| | FlushInputBuffer |
|---|
Description | Discards any characters waiting in the input buffer |
Format | FlushInputBuffer object me |
Parameters | object me: The value returned from new
|
Return Value | "ok" or error messages starting with "Error :" |
Example | put theXtra.FlushInputBuffer() |
| | CalcCRC16 |
|---|
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);
}
|
Format | CalcCRC16 list data |
Parameters | |
Return Value | either property list with #crcLo and #crcHi or error message starting with the word "Error :" |
Notes | list data: Linear list of numbers |
Example | reply = CalcCRC16([1,2,3,4,5,6,7])
put reply.crcLo
put reply.crcHi |
| | CalcCrcCCITT |
|---|
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);
}
}
|
Format | CalcCrcCCITT list data |
Parameters | list data: A linear list of numbers
|
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 |
|---|
Description | Converts a 2 digit hex string to a decimal number |
Format | HexToDec string data |
Parameters | string data: The hex string to convert
|
Return Value | "ok" or error messages starting with "Error :" |
Example | put HexToDec() |
| | DecToHex |
|---|
Description | Converts a number to a hex string |
Format | DecToHex integer number |
Parameters | integer number: The value returned from new
|
Return Value | The number converted into a string |
Example | put DecToHex() |
| | SplitNumber |
|---|
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)
|
Format | SplitNumber integer number |
Parameters | integer number: The value to split
|
Return Value | linear list of the number split into 4 0-255 bytes |
Example | put SplitNumber(104564) |
| | JoinNumber |
|---|
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
|
Format | JoinNumber list fourNumberList |
Parameters | list fourNumberList: The value to be joind
|
Return Value | A single number of the joined values |
Example | put JoinNumber([34,56,1,34]) |
| | ShowErrorsAsDialogs |
|---|
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 |
Format | ShowErrorsAsDialogs object objectRef, integer truOrFalse |
Parameters | objectRef: valid instance of UsbAccessXtra created with "new"
trueOrFalse: true to turn dialogs on, or false to turn them off |
Return Value | "ok" or "Error" |
Example | theXtra.ShowErrorsAsDialogs(0) |
| | GetVersionString |
|---|
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. |
Format | GetVersionString object objectRef |
Parameters | objectRef: valid instance of UsbAccessXtra created with "new" |
Return Value | A version string. |
Example | put theXtra.GetVersionString() |
| | GetLicensetype |
|---|
Description | Returns the license type for this xtra. #Author, #Demo or #Full |
Format | GetLicenseType object objectRef |
Parameters | objectRef: valid instance of UsbAccessXtra created with "new" |
Return Value | #Author, #Demo or #Full |
Example | put theXtra.GetLicenseType() |
| | GetDemoDaysRemaining |
|---|
Description | Returns the number of days remaining on a demo license. Returns 0 if authoring license, or a big number if a full license. |
Format | GetDemoDaysRemaining object me |
Parameters | object me: The value returned from new |
Return Value | Integer number |
Example | put theXtra.GetDemoDaysRemaining() |
| | privateInstance |
|---|
Description | Private function |
Format | privateInstance |
Parameters | Private |
Return Value | |
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:
|
Example | |
| | privateGlobal |
|---|
Description | Private |
Format | privateGlobal |
Parameters | |
Return Value | |
Example | |
