|
|
Tech Note 05: SerialTools Reference for NS Basic
September 8, 2009
|
The information in the document is for the most part copied from the official SerialTools documentation on Franson's website. For further information, please refer to the official documentation. The information on this page is copyright Franson Technology AB and published with their permission.
A good place to get started is to read about the Port class.
We have included sample NS Basic code for some of the commands. If you have additional sample code we can add, please send it to support@nsbasic.com.
A License key is necessary to use SerialTools. The license key is contained in the same email as your NS Basic license key. Please keep this key confidential. You may distribute SerialTools with your NS Basic application for no additional charge.
Additional Technical support can be found in Franson's user forums:
To instantiate SerialTools in an NS Basic/CE program, use the following code:
AddObject "serialce.port.1","objPort"
AddObject "serialce.license","objlicense"
objLicense.LicenseKey = "substitute licence key here"
To instantiate SerialTools in an NS Basic/Desktop program, use the following code:
AddObject "serialxp.port.1","objPort"
AddObject "serialxp.license","objlicense"
objLicense.LicenseKey = "substitute licence key here"
With the exception of the InfraRed property, all the Properties, Methods and Events in SerialTools work the same way in NS Basic/CE and NS Basic/Desktop.
There have been reports of running out of memory messages when using this control on Windows Mobile devices. The workaround is to close and reopen the port from time to time.
Class
Properties
Methods
Events
Port
The Port class contains the core functionallity to access the serial port.
Set a baudrate using Port.BaudRate and the port number using Port.ComPort. Port.Enabled opens the specified serial port for reading and writing.
Data is read from the port with the Port.OnRead event or the Port.Read method and you write data using Port.Write.
By using Port.StartTrigger and Port.EndTrigger SerialTools can help you with simple parsing of the data.
Port.Timeout can be used for timeout handling.
If you want to read and write binary data take a closer look at Port.ByteArrayToString and Port.StringToByteArray.
For more advanced control of the serial port and handshaking options see methods and properties.
BaudRate
Sets the baud rate of the serial port. The default value is 9600 baud.
See also Port.ComPort and Port.Enabled.
Syntax
object.BaudRate = Value
Value = object.BaudRate
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Long (Variant) |
Baud rate. |
Break
Inserts and removes break for serial port.
Syntax
object.Break = Value
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Boolean (Variant) |
Enable/Disable break. |
BufferSize
Sets the input buffer size. Default value is 0.
BufferSize returns the number of bytes in the serial buffer that are still not parsed.
NOTE! If you set BufferSize to a value different from 0 then OnRead will not be called
until BufferSize bytes of data has been
received. By default BufferSize is set to 0, which means this feature is disabled.
See Port.OnRead for how this functionallity is used.
Syntax
object.BufferSize = Value
Value = object.BufferSize
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Long (Variant) |
Input buffer size. |
ByteSize
Sets number of bits in one byte, can be set ot 7 or 8. Default value is 8.
Syntax
object.ByteSize = Value
Value = object.ByteSize
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Long (Variant) |
Number of bits in one byte. |
ComPort
Specifies which serial port to use. The default value is 1.
On Windows CE / Pocket PC this is a value between 0 and 9. Note that COM0: is a possible
COM port in Windows CE!
For Windows this is a value between 1 and 255.
See also Port.BaudRate and Port.Enabled.
Syntax
object.ComPort = Value
Value = object.ComPort
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Long (Variant) |
Comm port. |
CTS
Reads the value of CTS (Clear To Send).
See Port.OnCTS for more info.
Syntax
Value = object.CTS
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Boolean (Variant) |
State of CTS. |
DCD
Reads the value of DCD (Data Carrier Detected).
See Port.OnDCD for more info.
Syntax
Value = object.DCD
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Boolean (Variant) |
State of DCD. |
DSR
Reads the value of DSR (Data Set Ready).
See Port.OnDSR for more info.
Syntax
Value = object.DSR
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Boolean (Variant) |
State of DSR. |
DTR
Sets the value of DTR (Data Termial Ready). Cannot be set if Port.Handshake
is set to Handshake.DTR
Note! Some devices and terminal programs demands this property to be set to true or else
they will not transmit any data to be received by SerialTools.
In SerialTools 1.20 (and later) DTR is set to true by default.
Syntax
object.DTR = Value
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Boolean (Variant) |
State of DTR. |
Enabled
Opens or closes the serial port specified by Port.ComPort.
Sample:
objPort.BaudRate = 4800
objPort.ComPort = 2
objPort.Enabled = True ' Starts serial port.
objPort.Write("Some data written to serial port")
|
If the component is running inside a browser a dialog box will be shown to the user when
Enabled is set to true. This dialog box asks the user if he allows a connection to the serial port
or not.
NOTE! You must disable the port by setting Enabled to false before you
unload the form you got the Port.OnRead event handler on.
NOTE! COM3 on Windows CE is often a infra red port. You will need to determine which port your specific device uses for IR serial communications: it differs from device to device. Port.InfraRed must be set to
true for IR ports on Windows CE.
See also Port.OnRead and Port.Write.
Syntax
object.Enabled = Value
Value = object.Enabled
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Boolean (Variant) |
true |
EndTrigger
Sets end trigger. Default value is null.
See Port.OnRead for how this functionallity is used.
Syntax
object.EndTrigger = Value
Value = object.EndTrigger
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
String (Variant) |
End trigger. |
HandShake
Sets low level handshake method. Default value is Handshake.None.
RTS/CTS. Low level method of controlling sending of data. Set this property
to Handshake.RTS to use RTS/CTS.
DSR/DTR. Low level method of controlling reception of data. Set this property
to Handshake.DSR to use DSR/DTR.
XON/XOFF. Set this property to Handshake.XonXoff
The values can be or:ed together.
See also the Handshake enumaration.
Syntax
object.Handshake = Value
Value = object.Handshake
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Handshake |
Type of used low level handshake. 0=None, 1=RTS, 2=DTR, 4=XonXoff |
InfraRed
Enables communication with a IR port on Windows CE.
Syntax
object.InfraRed = Value
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Boolean (Variant) |
Enable/Disable IR on Windows CE. |
List
Port enumaration. Returns a byte array of all available ports in the system.
Very useful when making a dropdown
or similar for the user to select a serial port from.
Syntax
list = object.List
| Part |
Type |
Description |
| list |
Byte() |
Byte array containing the index of all available ports in the system. |
NoEvents
Set this to true (default false) if you won't use events.
If NoEvents is set to true you can use Port.Read.
If NoEvents is set to false (default) you can use the events Port.OnRead,
Port.OnWritten, etc.
Syntax
object.NoEvents = Value
Value = object.NoEvents
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Boolean (Variant) |
Events on or off. |
Parity
Sets parity. Default value is Parity.No.
Syntax
object.Parity = Value
Value = object.Parity
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Parity |
Type of parity. 0=No, 1=Odd, 2=Even, 3=Mark, 4=Space |
RI
Reads the value of RI (Ring Indicator).
See Port.OnRI for more info.
Syntax
Value = object.RI
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Boolean (Variant) |
State of RI. |
RTS
Sets the value of RTS (Request To Send). Cannot be set if Port.Handshake
is set to Handshake.RTS
Syntax
object.RTS = Value
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Boolean (Variant) |
State of RTS. |
StartTrigger
Sets start trigger. Default value is null.
See Port.OnRead for how this functionallity is used.
Syntax
object.StartTrigger = Value
Value = object.StartTrigger
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
String (Variant) |
String (Variant) to trigger reception of data on. |
StopBits
Sets number of stop bits. Default value is StopBits.One.
Syntax
object.StopBits = Value
Value = object.StopBits
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
StopBits |
Number of stop bits. Use 0 for 1 bit, 1 for 1.5 bits, 2 for 2 bits. |
TimeOut
Time in miliseconds before a timeout event is generated.
A value of 0 means that the timeout functionallity is disabled.
Default value is 0.
See Port.OnRead and Port.OnWritten for more info.
Syntax
object.Timeout = Value
Value = object.Timeout
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
Long (Variant) |
Timeout in miliseconds. 0 to disable. |
Methods...
ByteArrayToString
If you want to write anything else than ascii strings
(ascii value equals 1-127) you first need to create a byte array and then convert the
array to a string using this static function. The string can then be used in
Port.Write, Port.StartTrigger and
Port.EndTrigger.
Sample:
objPort.BaudRate = 4800
objPort.ComPort = 2
objPort.Enabled = True ' Starts serial port.
binary_data = Array(&H81, &H82)
' Write binary data
objPort.Write(objPort.ByteArrayToString(binary_data))
|
Note that it will not work to build your own "binary string" using chr(). You must use this function!
See also Port.StringToByteArray.
Syntax
str = object.ByteArrayToString ( ByteArray )
| Part |
Type |
Description |
| str |
String (Variant) |
Byte array converted to a string. |
| ByteArray |
byte[] |
Byte array to be converted. |
Purge
Resets all data in input and output buffers.
Syntax
object.Purge ( )
object.Purge ( InBuffer, OutBuffer )
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| InBuffer |
Long (Variant) |
Purge in buffer if true. |
| OutBuffer |
Long (Variant) |
Purge out buffer if true. |
Read
Reads data from the serialport. Cannot be used if Port.NoEvents is set to true (ActiveX).
Read has two versions. The first takes a BufferSize and TimeOut as arguments.
Setting BufferSize to 0 will return all data in serial buffer. But if the serial
buffer is empty it will wait until something has arrived. TimeOut determines how long to wait (in miliseconds).
Set TimeOut to 0 to disable time out.
The second version takes StartTrigger, EndTrigger and TimeOut as arguments.
Read will parse the serial buffer and return data according to the rules specified for
Port.OnRead. If no matching data is found in the serial buffer TimeOut determines
how long to wait before returning null / Nothing.
On time out Read() always returns null / Nothing.
If a Bluetooth connection is interrupted during Read, an exception is thrown and the port is closed. A Bluetooth connection
is typically interrupted if the Bluetooth device is turned of or if it gets out of reach.
See also Port.OnForceClose for more info on how to handle Bluetooth interruption.
Syntax 1
Value = object.Read ( BufferSize, Timeout )
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
String (Variant) |
Data received from serial port. Nothing/null if no data received. |
| BufferSize |
Long (Variant) |
See OnRead for details. |
| Timeout |
Long (Variant) |
See OnRead for details. |
Syntax 2
Value = object.Read2 ( StartTrigger, EndTrigger, Timeout )
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
String (Variant) |
Data received from serial port. Nothing/null if no data received. |
| StartTrigger |
String (Variant) |
See OnRead for details. |
| EndTrigger |
String (Variant) |
See OnRead for details. |
| Timeout |
Long (Variant) |
See OnRead for details. |
StringToByteArray
If you want to read anything else than ascii strings
(that is ascii value 0-127) you need to convert the received string to a byte array
using this static function. The string has been received by
Port.Read or Port.OnRead.
Sample:
objPort.BaudRate = 4800
objPort.ComPort = 2
objPort.Enabled = True ' Starts serial port.
string_data = objPort.Read(0, 5000)
' Received binary data
binary_data = objPort.StringToByteArray(string_data)
|
Note that it will not work to build your own byte array, e.g. using String.ToCharArray().
You must use this function.
See also Port.ByteArrayToString.
Syntax
ByteArray = object.StringToByteArray ( Str )
| Part |
Type |
Description |
| ByteArray |
byte[] |
Byte array converted from a string. |
| Str |
String (Variant) |
String (Variant) to be converted. |
Write
Writes data to the serial port. Write returns after data is written to the port.
Write takes a string as an argument, to convert binary data to a string see
Port.ByteArrayToString.
Write returns the number of bytes actually written. If write fails zero is returned.
Write will time out and return after the time specified in Port.Timeout
If an event handler for Port.OnWritten is specified, then Write will
return instantly with zero as return code, and OnWritten will be called with the number of
bytes actually written to the serial port driver. If the attempt to write timed out
OnWritten will have zero as argument.
See also Port.Enabled and Port.OnWritten.
Syntax
BytesWritten = object.Write ( Value )
| Part |
Type |
Description |
| object |
SerialCE.Port |
An object that evaluates to an SerialCE.Port object. |
| Value |
String (Variant) |
Data to be written to the serial port. |
| BytesWritten |
Long (Variant) |
Bytes written. |
Events...
OnCTS
Event that is called when CTS (Clear To Send) changes value. CTS is traditionally used by modems
to answer a RTS (Request To Send) request from the computer.
See Port.Handshake for more info on RTS/CTS handshake.
For most cases you don't need to bother about this event.
See also Port.CTS.
Syntax
obj_OnCTS ( State )
| Part |
Type |
Description |
| obj |
|
Event source. |
| State |
Boolean (Variant) |
State of CTS. |
OnDCD
Event that is called when DCD (Data Carrier Detected) changes value. DCD is traditionally used by modems
to make the computer aware of that a valid carrier is found on the phone line.
DCD is also known as RLSD (Receive Line Signal Detected).
For most cases you don't need to bother about this event.
See also Port.DCD.
Syntax
obj_OnDCD ( State )
| Part |
Type |
Description |
| obj |
|
Event source. |
| State |
Boolean (Variant) |
State of DCD. |
OnDSR
Called when DSR (Data Set Ready) changes value. DSR is traditionally used by modems
when they are ready to transmitt data from the modem to the computer. The computer then
answers by setting DTR to true. See Port.Handshake for more info
on DTR/DSR handshake.
For most cases you don't need to bother about this event.
See also Port.DSR.
Syntax
obj_OnDSR ( State )
| Part |
Type |
Description |
| obj |
|
Event source. |
| State |
Boolean (Variant) |
State of DSR. |
OnForceClose
This event is very useful to handle Bluetooth errors, removed USB serial adapters and simular
none static serial ports.
Event that is called when a serial port is closed in an unexpected way.
If you are using a Bluetooth serial port this will happen if the Bluetooth device is
turned off or gets out of reach. Before this event is called the port has been closed.
To reestablish the connection you need to reopen the port.
OnForceClose is called with the Win32 error code that caused serial port to fail.
When a Bluetooth device is turned of or gets out of reach this value is typically 31.
Not all BT/USB serial port drivers generate a Win32 error when the device is removed
from the system, therefor should you application also check for timeouts.
Syntax
obj_OnForceClose ( Value )
| Part |
Type |
Description |
| obj |
|
Event source. |
| Value |
Long (Variant) |
Win32 error code that was the cause of the closed port. |
OnRead
Event that is raised when data is received on the serial port.
OnRead is called when data has been received on the serial port.
Timeout. If Port.Timeout is set to a value different from 0 (default)
OnRead is called with null as argument if no data has been received during the
time interval specified by Timeout. Timeout is specified in miliseconds.
Buffer size. Use Port.BufferSize to specify how many bytes should be received
before OnRead is called (default 0 - disabled).
Simple parsing. If Port.EndTrigger is set to a value different from null (default).
OnRead will be called when the specified string is found in the input from the serial port.
This is very usefull if you got data with a known format coming in to the serial port.
If EndTrigger is used BufferSize is ignored.
If Port.StartTrigger is set to a value different from null (default). All data is ignored
until the specified string is found in the serial port input. If both StartTrigger and
EndTrigger is used only data between (including the triggers themself) the triggers will
be passed on to OnRead. If EndTrigger is null, OnRead will be called when BufferSize
bytes has been received. If EndTrigger is null StartTrigger must be "retriggered"
each time OnRead is called or else OnRead will be called with data each time the input buffer is full.
OnRead is called with a string as argument.
To convert this string to binary data see Port.StringToByteArray
and to convert from binary data to a string see Port.ByteArrayToString
See also Port.OnForceClose for more info on how to handle Bluetooth interruption.
See also Port.Enabled and Port.Read.
Syntax
obj_OnRead ( Value )
| Part |
Type |
Description |
| obj |
|
Event source. |
| Value |
String (Variant) |
Data read from the serial port. |
OnRI
Event that is called when RI (Ring Indicator) changes value. RI is traditionally used by modems
to make the computer aware of that someone is calling the modem.
For most cases you don't need to bother about this event.
See also Port.RI.
Syntax
obj_OnRI ( State )
| Part |
Type |
Description |
| obj |
|
Event source. |
| State |
Boolean (Variant) |
State of RI. |
OnWritten
Called when data has been sucessfully written to the serial driver using
Port.Write or the write operation has timed out.
Note that this does not mean the data has been written to the serial port, only that it has been
successfully passed on to the serial port driver. However in most cases this is the same thing.
Syntax
obj_OnWritten ( BytesWritten )
| Part |
Type |
Description |
| obj |
|
Event source. |
| BytesWritten |
Long (Variant) |
Number of bytes written. Zero on error. |