OpenComPortEx

Purpose

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.

If you need to control the hardware handshaking signals Request To Send (RTS) or Data Terminal Ready (DTR), please refer to the SetComPortRTSDTR command

Parameters

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).

Parameter: resource (optional)  
Type: integer
Description: Resource Number (see below).  This parameter is not used in HomeSeer 2.0 but is included for backward-compatibility with scripts created in older versions of HomeSeer.

Returns

The function returns an empty string if it was successful, otherwise it returns a text string describing the error.

Example

None

Port Configuration

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.

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

Operating Mode

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.

Port Data Handling Script

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

Function in Port Data Handling Script

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.

Termination String

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).

Resource Number

This parameter is no longer necessary in HomeSeer 2.0 but is included for backward-compatibility with scripts created in older versions of HomeSeer.

This is a resource number to allocate OpenComPortEx resources so that OpenComPortEx can be used with COM ports above 8.   There are 8 resources available between OpenComPort and OpenComPortEx.  When you wish to use COM ports above 8 you can specify the higher COM port number for the port parameter, but then you must specify a resource number with this parameter.   HomeSeer does NOT keep track of used resource numbers.  If COM3 is opened with OpenComPort, which means resource 3 was assigned to it, you must remember not to use resource 3 with OpenComPortEx.