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

String port - The name of the serial port, e.g., "COM1" or "dev/ttyS0".

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

Integer handshake - Configure the handshake. Valid values are defined by the following constants [optional]:

system.serial.HANDSHAKE_CTS_DTR, system.serial.HANDSHAKE_CTS_RTS, system.serial.HANDSHAKE_DSR_DTR, system.serial.HANDSHAKE_HARD_IN, system.serial.HANDSHAKE_HARD_OUT, system.serial.HANDSHAKE_NONE, system.serial.HANDSHAKE_SOFT_IN, system.serial.HANDSHAKE_SOFT_OUT, system.serial.HANDSHAKE_SPLIT_MASK, system.serial.HANDSHAKE_XON_XOFF

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

  • 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:

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

system serialport, serial.port