UART Entity¶
API Documentation: [cpp] [python] [.NET] [CCA] [REST]
The UART entity is a class which allows a user to configure and control an arbitrary stream of serial data. These streams can represent a number of different transports, including a RS232 external interface, a virtual COM port, and onboard UART interfaces from system components. This entity allows each transport to be configured as either an endpoint, or as a passthrough between transports, similar to a switchboard of a telephone operator.
Products may implement any number of UART entities for the specific capabilities of that product. Consult the product specific reference material for details about the exact capabilities of the product.
Channel Enable (Get/Set)¶
uart [ index ] . setEnable => (unsigned char) enable
uart [ index ] . getEnable <= (unsigned char) enable
Enables the uart channel for the specified index.
Change Linked Channel (Get/Set)¶
uart [ index ] . setLinkChannel => (unsigned char) index
uart [ index ] . getLinkChannel <= (unsigned char) index
Sets a UART channel to pass data to and from another UART channel. If the channel index is set to the current index, the UART channel will operate as an endpoint with a specific protocol.
Note
Channel linking must be set up on both ends of the connection. That is, setting Channel A’s link channel to Channel B will not pass data through until Channel B’s link channel is also set to channel A.
Change Protocol (Get/Set)¶
uart [ index ] . setProtocol => (unsigned char) protocol
uart [ index ] . getProtocol <= (unsigned char) protocol
Sets the protocol of the UART when operating as an endpoint. The protocols supported by the API are listed below. Note that not all products or indexes are required to support all protocols. The list of protocols that may be assigned can be queried using getCapableProtocols and getAvailableProtocols.
Enumeration |
Name |
Description |
|---|---|---|
0 |
Undefined |
Entity will drop incoming data and will not send data |
1 |
Extron Responder |
Entity will respond to incoming Extron-like commands (see product details) |
2 |
BrainStem Transport |
Connection can be opened to this entity from the BrainStem API |
3 |
Extron Initiator |
Entity will initiate Extron-like commands on certain events (see product details) |
4 |
Reserved |
Reserved for future use |
5 |
Reserved |
Reserved for future use |
6 |
Loopback |
Entity will write back any received data |
uart [ index ] . getCapableProtocols => (unsigned int) protocols
Returns an integer containing a bitmask where each bit represents a protocol enumeration value that the channel may be able to be configured with. This does not guarantee that attempting to set the protocol will succeed, as there may not be sufficient resources to assign to this channel.
uart [ index ] . getAvailableProtocols => (unsigned int) protocols
Returns an integer containing a bitmask where each bit represents a protocol enumeration value that the channel both supports and has an available resource to assign for this protocol.
Value |
Name |
Description |
|---|---|---|
0 |
Undefined |
Disabled/Undefined protocol |
1 |
Extron Responder |
Extron Compatible Protocol (backward compatibility) |
2 |
Brainstem Transport |
Brainstem Transport protocol |
6 |
Loopback |
Loopback mode for testing |
Note
Protocol availability may vary by device. Use getCapableProtocols() and getAvailableProtocols() to determine which protocols are supported on a specific device and channel.
Set Link Channel (Get/Set)¶
uart [ index ] . setLinkChannel => (unsigned char) channel
uart [ index ] . getLinkChannel <= (unsigned char) channel
Sets or gets the index of another UART Entity that should be linked to this UART. If set to the index of this entity, the channel will not be linked. If set to the index of another UART entity, data will be sent between the two UART entities with no additional processing.
Note
Linking VCOM to Hardware UART/RS232: A common use case is to link a VCOM (Virtual COM port) channel to the hardware UART/RS232 connector. This allows USB-based serial communication to be transparently forwarded to the physical RS232 interface. For example, linking UART[1] (VCOM) to UART[0] (hardware RS232) will forward all data received on the VCOM channel directly to the RS232 connector, and vice versa. This is useful for remote serial access or bridging USB serial connections to physical serial devices.
Set Stop Bits (Get/Set)¶
uart [ index ] . setStopBits => (unsigned char) stopBits
uart [ index ] . getStopBits <= (unsigned char) stopBits
Sets or gets the UART stop bit configuration.
Value |
Description |
|---|---|
0 |
1 Stop Bit |
1 |
1.5 Stop Bits |
2 |
2 Stop Bits |
Set Parity (Get/Set)¶
uart [ index ] . setParity => (unsigned char) parity
uart [ index ] . getParity <= (unsigned char) parity
Sets or gets the UART parity configuration.
Value |
Description |
|---|---|
0 |
No Parity Bit |
1 |
Odd Parity Bit |
2 |
Even Parity Bit |
3 |
Mark Parity Bit |
4 |
Space Parity Bit |
Set Data Bits (Get/Set)¶
uart [ index ] . setDataBits => (unsigned char) dataBits
uart [ index ] . getDataBits <= (unsigned char) dataBits
Sets or gets the number of data bits per character for the UART channel.
Set Flow Control (Get/Set)¶
uart [ index ] . setFlowControl => (unsigned char) flowControl
uart [ index ] . getFlowControl <= (unsigned char) flowControl
Sets or gets the UART flow control configuration as a bitmask. Multiple flow control methods can be enabled simultaneously.
Bit |
Description |
|---|---|
0 |
RTS/CTS Enable |
1 |
DSR/DTR Enable |
2 |
XON/XOFF Enable |
Get Capable Protocols¶
uart [ index ] . getCapableProtocols <= (unsigned int) protocols
Returns a bitmask indicating which protocols are capable of being used on this UART channel. The value of the protocol is mapped to the bit index (e.g., protocol 0 is bit 0, protocol 1 is bit 1, etc.).
Get Available Protocols¶
uart [ index ] . getAvailableProtocols <= (unsigned int) protocols
Returns a bitmask indicating which protocols are currently available for use on this UART channel. This takes into account resource availability (e.g., whether Brainstem Transport resources are available). The value of the protocol is mapped to the bit index (e.g., protocol 0 is bit 0, protocol 1 is bit 1, etc.).
Change Line Coding (Get/Set)¶
These APIs are all used to set the UART line coding parameters. Note that not all parameters may be changed for certain indexes, nor may all options for line coding be specified.
uart [ index ] . setBaudRate => (unsigned int) rate
uart [ index ] . getBaudRate <= (unsigned int) rate
Sets the baud rate of the transport in bits per second.
Note
A baudrate of 0 will perform automatic baudrate selection if supported on the specified index.
uart [ index ] . setParity => (unsigned char) parity
uart [ index ] . getParity <= (unsigned char) parity
Sets the parity bit configuration:
Enumeration |
Name |
Description |
|---|---|---|
0 |
uartParity_None_Value |
Parity bit is not used |
1 |
uartParity_Odd_Value |
Parity bit is set to 1 if the number of 1s in the data bits is odd |
2 |
uartParity_Even_Value |
Parity bit is set to 1 if the number of 1s in the data bits is even |
3 |
uartParity_Mark_Value |
Forces parity bit to a binary 1 |
4 |
uartParity_Space_Value |
Forces parity bit to a binary 0 |
uart [ index ] . setStopBits => (unsigned char) stopBits
uart [ index ] . getStopBits <= (unsigned char) stopBits
Sets the stop bit configuration:
Enumeration |
Name |
Number of Stop Bits |
|---|---|---|
0 |
uartStopBits_1_Value |
1 |
1 |
uartStopBits_1p5_Value |
1.5 |
2 |
uartStopBits_2_Value |
2 |
uart [ index ] . setDataBits => (unsigned char) dataBits
uart [ index ] . getDataBits <= (unsigned char) dataBits
Sets the number of bits in a single payload (e.g. 7, 8, 9)
uart [ index ] . setFlowControl => (unsigned char) flowControl
uart [ index ] . getFlowControl <= (unsigned char) flowControl
Sets the flow control configuration:
Bit |
Name |
Description |
|---|---|---|
0 |
uartFlowControl_RTS_CTS_Bit |
Enable RTS/CTS Flow Control |
1 |
uartFlowControl_DSR_DTR_Bit |
Enable DSR/DTR Flow Control |
2 |
uartFlowControl_XON_XOFF_Bit |
Enable XON/XOFF Flow Control |
Code Examples¶
C++¶
// All commands return aErr values when errors are encountered and aErrNone on
// success. Get calls will fill the variable with the returned value.
err = stem.uart[0].setEnable(1);
err = stem.uart[1].setEnable(1);
err = stem.uart[0].getEnable(&enable);
err = stem.uart[1].getEnable(&enable);
err = stem.uart[0].setBaudRate(115200);
err = stem.uart[0].setProtocol(1); // Extron Compatible Protocol
err = stem.uart[0].setEnable(0);
err = stem.uart[1].setEnable(0);
// Loopback Protocol Example
// Configure UART[0] for loopback testing
err = stem.uart[0].setEnable(1);
err = stem.uart[0].setBaudRate(115200);
err = stem.uart[0].setProtocol(6); // Loopback protocol
// Data sent to UART[0] will be echoed back
// VCOM to Hardware UART Link Example
// Link VCOM channel (UART[1]) to hardware RS232 (UART[0])
err = stem.uart[0].setEnable(1); // Enable hardware UART
err = stem.uart[1].setEnable(1); // Enable VCOM channel
err = stem.uart[1].setLinkChannel(0); // Link VCOM to hardware UART
err = stem.uart[0].setLinkChannel(1); // Link hardware UART to VCOM
// Data received on VCOM will be forwarded to RS232, and vice versa
Python¶
err = stem.uart[0].setEnable(1)
err = stem.uart[1].setEnable(1)
result = stem.uart[0].getEnable()
print result.value
result = stem.uart[1].getEnable()
print result.value
err = stem.uart[0].setBaudRate(115200)
err = stem.uart[0].setProtocol(1) # Extron Compatible Protocol
err = stem.uart[0].setEnable(0)
err = stem.uart[1].setEnable(0)
# Loopback Protocol Example
# Configure UART[0] for loopback testing
err = stem.uart[0].setEnable(1)
err = stem.uart[0].setBaudRate(115200)
err = stem.uart[0].setProtocol(6) # Loopback protocol
# Data sent to UART[0] will be echoed back
# VCOM to Hardware UART Link Example
# Link VCOM channel (UART[1]) to hardware RS232 (UART[0])
err = stem.uart[0].setEnable(1) # Enable hardware UART
err = stem.uart[1].setEnable(1) # Enable VCOM channel
err = stem.uart[1].setLinkChannel(0) # Link VCOM to hardware UART
# Data received on VCOM will be forwarded to RS232, and vice versa