This function opens a communication port. If the port is already open by another application, an error occurs. Once a port is opened, it remains open until the CloseComPort function is called. The port is not closed when the script terminates. However, the port will close when the application terminates.
In previous versions of HomeSeer, the OpenComPort function was limited to COM ports 1 to 8 and OpenComPortEx was for ports above 8. Beginning with HomeSeer Version 2.0, there is no limit on the number of COM ports, so these functions can be used interchangeably. The "Resource" parameter in the OpenComPortEX function is not used in HomeSeer 2.0, but the parameter is included in order to support scripts created with older versions of HomeSeer.
If you need to control the hardware handshaking signals Request To Send (RTS) or Data Terminal Ready (DTR), please refer to the SetComPortRTSDTR command.
Parameter: port
Type: integer
Description: This is the port number to open. An
error is returned if the port is already open or is not installed on the
system. To
use port numbers above 8, see the resource description below.
Parameter: config
Type: string
Description: Port Configuration (see below).
Parameter: mode
Type: integer
Description: Operating Mode (see below).
Parameter: cb_script
Type: string
Description: Port Data Handling Script (see below).
Parameter: cb_func
Type: string
Description: Function in Port Handling Script (see below).
Parameter: term
(optional)
Type: string
Descripton: Termination String (see below).
The function returns an empty string if it was successful, otherwise it returns a text string describing the error.
The config parameter is composed of four settings and has the format BBBB,P,D,S.
BBBB is the baud rate, P is the parity, D is the number of data bits, and S is the number of stop bits. For example, to set the port to 9600 baud, no parity, 8 bit and no stop bits, the config string would be 9600,N,8,1.
The valid baud rates are listed below.
|
110 |
2400 |
19200 |
57600 |
The parity values are:
E = Even
M = Mark
N = None
O = Odd
S = Space
The data bit values are:
5
6
7
8
The stop bit values are:
1
1.5
2
This parameter affects the way data is received on the COM port. Two modes are available:
0 = raw mode
In this mode, each character that is received on the COM port causes the specified script and function to be called. It is up to the called function to call GetComPortData to actually get the characters.
1 = strings mode
This mode buffers up characters until a terminator is received. At this point the specified script and function are called with the data. This mode makes it easy to deal with devices that send text data terminated with known characters. To specify the terminator characters, see the term parameter description below. If you do not specify a terminator, the default terminator of carriage return and line-feed (CrLf) are used.
This parameter is the name of the script that will be called when COM port data arrives. The script will be called with a single parameter, which is the received text string. If you do not wish to be called back when data is received, leave this parameter as an empty string. You can still use the GetComPortData function to poll for data yourself. The following example shows what your called script should look like.
sub callback(data)
' handle the data
end sub
This is the function that will be called in the specified script. If your script was defined as above, the cb_func parameter would be set to callback. If this parameter is omitted, the main function will be called by default.
This is the terminator string for mode 1 operation. Characters will be received into the COM port buffer until this termination string is found in the buffer. If this parameter is not provided, then the default value is the character pair of carriage return and line-feed (CrLf).