system.serial.port

This function is used in Python Scripting.

Description

Returns a context manager wrapping a serial port, allowing the rest of the system to interact with that port. This function effectively combines the system.serial.configureSerialPort, system.serial.openSerialPort, and system.serial.closeSerialPort functions into a single call.

Intended to be used with the Python 'with' statement. The object aliased in the 'with' statement has special access to all of the other system.serial functions, allowing for reads and writes.

Closing the port happens automatically once the 'with' statement ends.

Accepts the same arguments as configureSerialPort, and access to constants must be prefixed by "system.serial." (as shown in the parameter descriptions).

Client Permission Restrictions

This scripting function has no Client Permission restrictions.

Syntax

system.serial.port(port, [bitRate], [dataBits], [handshake], [hardwareFlowControl], [parity], [stopBits])

Parameters

Type	Parameter	Description
String	port	The name of the serial port, e.g., "COM1" or "/dev/ttyS0". This parameter is required.
Integer	bitRate	Configure the bit rate. Valid values are defined by the following constants [optional]: system.serial.BIT_RATE_110, system.serial.BIT_RATE_150, system.serial.BIT_RATE_300, system.serial.BIT_RATE_600, system.serial.BIT_RATE_1200, system.serial.BIT_RATE_2400, system.serial.BIT_RATE_4800, system.serial.BIT_RATE_9600, system.serial.BIT_RATE_19200, system.serial.BIT_RATE_38400, system.serial.BIT_RATE_57600, system.serial.BIT_RATE_115200, system.serial.BIT_RATE_230400, system.serial.BIT_RATE_460800, system.serial.BIT_RATE_921600
Integer	dataBits	Configure the data bits. Valid values are defined by the following constants [optional]: system.serial.DATA_BITS_5, system.serial.DATA_BITS_6, system.serial.DATA_BITS_7, system.serial.DATA_BITS_8
Boolean	hardwareFlowControl	Configure hardware flow control. On or off. [optional]
Integer	parity	Configure parity. Valid values are defined by the following constants [optional]: system.serial.PARITY_EVEN, system.serial.PARITY_ODD, system.serial.PARITY_MARK, system.serial.PARITY_SPACE, system.serial.PARITY_NONE
Integer	stopBits	Configure stop bits.Valid values are defined by the following constants [optional]: system.serial.STOP_BITS_1, system.serial.STOP_BITS_2

note

The serial library was updated in 8.0. Any constants, like HANDSHAKE, that do not have an equivalent value will result in a value of 0.

Returns

PortManager - A wrapper around the configured port, that can be entered by using a 'with' statement. The port will automatically close on exiting the 'with' statement scope.

Scope

Gateway, Vision Client, Perspective Session

Using the PortManager

The PortManager is the primary way to interact with a serial port when using this function. It has special access to the other system serial functions. Specifically:

• system.serial.readBytes
• system.serial.readBytesAsString
• system.serial.readLine
• system.serial.readUntil
• system.serial.sendBreak
• system.serial.write
• system.serial.writeBytes

Calling these functions from the PortManager does not require the 'port' parameter, as the port is implied by system.serial.port. However all other parameters are available (see the linked pages in the bullet list above).

In addition, you do not include 'system.serial.' when accessing the other serial functions mentioned above, as the aliased object has access to them. Thus:

# Correct
with system.serial.port("COM1") as port:
    port.write("some string")
 
# Incorrect
with system.serial.port("COM1") as port:
    system.serial.write("COM1", "some string")

Code Examples

Example 1: Simple Example with Descriptions

# Reads a value from a port.
 
# First we call the function using a 'with' statement, and create an aliased object named 'port'
with system.serial.port("COM1", bitRate=system.serial.BIT_RATE_9600) as port:
 
    # Within the 'with' statement, we can call other serial functions by referencing the aliased object.
    # Meaning, in this example, 'port' can easily call the system.serial.readLine() function with the following:
    line = port.readLine(60000)

Example 2: Using all Parameters

# Same idea as example one, but uses all available parameters.
with system.serial.port(
        port = "COM1",
        bitRate = system.serial.BIT_RATE_110,
        dataBits = system.serial.DATA_BITS_5,
        handshake = system.serial.HANDSHAKE_CTS_DTR,
        hardwareFlowControl = False,
        parity = system.serial.PARITY_EVEN,
        stopBits = system.serial.STOP_BITS_1) as port:
     
    line = port.readLine(60000)