UART Glossary

This C language glossary defines the constants and library functions from the driver code and demo program associated with the UART (Universal Asynchronous Receiver Transmitter) Wildcard.

The UART Wildcard implements two full-duplex serial ports that can be configured for RS232, RS422, and RS485 protocols to implement the communications links that are often needed in instrument control applications. This tiny 2" by 2.5" board is a member of the Wildcard™ series that connects to Mosaic's line of microcontroller-based embedded computers. A UART chip (sometimes called a USART) on the Wildcard implements the conversion between the parallel Wildcard bus and the RS232 and RS485 asynchronous serial links. The Wildcards make it easy to implement instrumentation and automation solutions.

The main glossary entries presented in this document are listed in case-insensitive alphabetical order (the underscore character comes at the end of the alphabet). The keyword name of each entry is in bold typeface. Each function is listed with both a C-style declaration and a Forth-style stack comment declaration as described below. The "C:" and "4th:" tags at the start of the glossary entry distinguish the two declaration styles.

The Forth language is case-insensitive, so Forth programmers are free to use capital or lower case letters when typing keyword names in their program. Because C is case sensitive, C programmers must type the keywords exactly as shown in the glossary. The case conventions are as follows:

• Function names begin with a capital letter, and every letter after an underscore is capitalized. Other letters are lower case, except for capitalized acronyms such as "UART".
• Constant names and C macros use capital letters.
• Variable names use lower case letters.

Each glossary entry starts with C-style and Forth-style declarations, and presents a description of the function. Here is a sample glossary entry:

The C declaration specifies that return data type before the function name, and lists the comma-delimited input parameters between parentheses, showing the type and a descriptive name for each.

The Forth declaration contains a "stack picture" between parentheses; this is recognized as a comment in a Forth program. The items to the left of the double-dash ( -- ) are input parameters, and the item to the right of the double-dash is the output parameter. Forth is stack-based, and the first item shown is lowest on the stack. The backslash ( \ ) character is read as "under" to indicate the relative positions of the input parameters on the stack. In the Forth declaration the parameter names and their data types are combined. All unspecified parameters are 16-bit integers. Forth promotes all characters to integer type.

The presence of both C and Forth declarations is helpful: the C syntax shows the types of the parameters, and the Forth declaration provides a descriptive name of the output parameter.

C: int Ask_Key_UART ( int channel_num, int module_num )
4th: Ask_Key_UART ( channel_num\module_num -- flag )

Returns a flag indicating the receipt of a character on the specified serial channel. The flag is true (-1) if there is at least one character in the input FIFO of the specified channel. Otherwise the returned flag is false (0).

See also Ch1_Ask_Key and Ch2_Ask_Key..

C: int Ch1_Ask_Key ( void )
4th: Ch1_Ask_Key ( -- flag )

Returns a flag indicating the receipt of a character on serial channel 1. The value set by the last execution of Set_UART_Number specifies the module number. The flag is true true (-1) if there is at least one character in the input FIFO. Otherwise the returned flag is false (0). The demonstration program shows how to use this function to revector serial I/O in a task.

See also Ask_Key_UART..

C: void Ch1_Emit ( uchar character )
4th: Ch1_Emit ( char -- )

This function queues the specified character in the output FIFO for transmission on serial channel 1. The value set by the last execution of Set_UART_Number specifies the Wildcard number. If the output FIFO is full, this routine waits and PAUSEs until there is room in the FIF0, then puts the specified character in the FIFO so that it will be transmitted. The demonstration program shows how to use this function to revector serial I/O in a task.

See also Emit_UART..

C: uchar Ch1_Key ( void )
4th: Ch1_Key ( -- char )

Waits (if necessary) for receipt of a character from channel 1, and returns the received character. The value set by the last execution of Set_UART_Number specifies the Wildcard number. PAUSEs while waiting. The returned byte is the next pending character in the FIFO (that is, the oldest unretrieved character in the receive FIFO). The demonstration program shows how to use this function to revector serial I/O in a task.

See also Key_UART..

C: int Ch2_Ask_Key ( void )
4th: Ch2_Ask_Key ( -- flag )

Returns a flag indicating the receipt of a character on serial channel 2. The value set by the last execution of Set_UART_Number specifies the Wildcard number. The flag is true true (-1) if there is at least one character in the input FIFO. Otherwise the returned flag is false (0). The demonstration program shows how to use this function to revector serial I/O in a task.

See also Ask_Key_UART..

C: void Ch2_Emit ( uchar character )
4th: Ch2_Emit ( char -- )

This function queues the specified character in the output FIFO for transmission on serial channel 2. The value set by the last execution of Set_UART_Number specifies the Wildcard number. If the output FIFO is full, this routine waits and PAUSEs until there is room in the FIF0, then puts the specified character in the FIFO so that it will be transmitted. The demonstration program shows how to use this function to revector serial I/O in a task.

See also Emit_UART..

C: uchar Ch2_Key ( void )
4th: Ch2_Key ( -- char )

Waits (if necessary) for receipt of a character from channel 2, and returns the received character. The value set by the last execution of Set_UART_Number specifies the Wildcard number. PAUSEs while waiting. The returned byte is the next pending character in the FIFO (that is, the oldest unretrieved character in the receive FIFO). The demonstration program shows how to use this function to revector serial I/O in a task.

See also Key_UART..

C: CHANNEL1
4th: CHANNEL1 ( -- 1 )

A constant equal to 1, used as a channel specifier.

C: CHANNEL2
4th: CHANNEL2 ( -- 2 )

A constant equal to 2, used as a channel specifier.

C: DEFAULT_BAUDRATE
4th: DEFAULT_BAUDRATE ( -- n )

A constant in the demonstration program whose value sets the baud rate for channels 1 and 2 in the Default_UART_Init function. The user should set this to the desired value. Standard baud rates are 300, 1200, 2400, 4800, 9600, 19200, 38400, and 56000 baud. The suggested value in the demo source code is 19200 baud. See Default_UART_Init and Set_Baud.

C: DEFAULT_BITS_PER_CHAR
4th: DEFAULT_BITS_PER_CHAR ( -- n )

A constant in the demonstration program whose value sets the number of data bits per character for channels 1 and 2 in the Default_UART_Init function. Allowed values are 5, 6, 7, or 8. The user should set this to the desired value. The suggested value in the demo source code is 8. See Default_UART_Init and Set_Data_Format.

C: DEFAULT_PROTOCOL
4th: DEFAULT_PROTOCOL ( -- n )

A constant in the demonstration program whose value sets the protocol for channels 1 and 2 in the Default_UART_Init function. The user should set this to the desired value. Allowed values are given by the constants RS232, RS422, RS485, or NOT_USED; see their glossary entries. The suggested value in the demo source code is RS232. See Default_UART_Init and Set_Protocols.

C: DEFAULT_MODEM_SUPPORT
4th: DEFAULT_MODEM_SUPPORT ( -- n )

A constant in the demonstration program whose value sets the modem support flag for channel 1 in the Default_UART_Init function. Allowed values are TRUE (nonzero) or FALSE (0). The user should set this to the desired value. The suggested value in the demo source code is FALSE. See Default_UART_Init and Set_Protocols.

C: DEFAULT_PARITY
4th: DEFAULT_PARITY ( -- n )

A constant in the demonstration program whose value sets the parity type for channels 1 and 2 in the Default_UART_Init function. The user should set this to the desired value. Allowed values are given by the constants NO_PARITY, EVEN_PARITY, ODD_PARITY, HIGH_PARITY, or LOW_PARITY; see their glossary entries. The suggested value in the demo source code is NO_PARITY. See Default_UART_Init and Set_Data_Format.

C: DEFAULT_STOP_BITS
4th: DEFAULT_STOP_BITS ( -- n )

A constant in the demonstration program whose value sets the number of stop bits for channels 1 and 2 in the Default_UART_Init function. Allowed values are 1 or 2. The user should set this to the desired value. The suggested value in the demo source code is 1. See Default_UART_Init and Set_Data_Format.

C: int Default_UART_Init ( int module_num )
4th: Default_UART_Init ( module_num -- error )

A function in the demonstration program that sets the protocols, data formats, and baud rates for both channel 1 and channel 2 according to a set of default parameter constants. This function passes the parameters DEFAULT_BITS_PER_CHAR, DEFAULT_STOP_BITS, and DEFAULT_PARITY to the Set_Data_Format function for each channel in the specified Wildcard. It passes the parameter DEFAULT_BAUDRATE to Set_Baud for each channel in the specified Wildcard. It passes the parameters DEFAULT_MODEM_SUPPORT and DEFAULT_PROTOCOL to Set_Protocols. If an invalid protocol combination is specified as described below, this function returns a nonzero error flag. Otherwise, a result of zero is returned. This function is provided in source form to illustrate how to initialize the UART Wildcard. The values of the default parameters and the source code of this function can be customized to meet the needs of your application.

C: void Emit_UART ( uchar character, int channel_num, int module_num )
4th: Emit_UART ( char\channel_num\module_num -- )

Queues the specified character in the output FIFO for transmission on the specified serial channel. If the output FIFO is full, this routine waits and PAUSEs until there is room in the FIF0, then puts the specified character in the FIFO so that it will be transmitted.

See also Ch1_Emit and Ch2_Emit..

C: void End_Break ( int channel_num, int module_num )
4th: End_Break ( channel_num\module_num -- )

Ends the break sequence that was initiated by Send_Break on the specified channel, thereby returning the specified output to the idle high (mark) state at the UART.

C: EVEN_PARITY
4th: EVEN_PARITY ( -- n )

A constant (= 0x18) that, when passed as a parameter to the Set_Data_Format function, configures the channel’s data format for even parity, meaning that the sum of the bits is constrained to be even.

C: HIGH_PARITY
4th: HIGH_PARITY ( -- n )

A constant (= 0x28) that, when passed as a parameter to the Set_Data_Format function, configures the channel’s data format for high parity, meaning that the parity bit is high at the UART. This is also known as "mark parity".

C: void Is_DTR ( int desired_state, int module_num )
4th: Is_DTR ( desired_state\module_num -- )

Writes the specified state to the DTR (Data Terminal Ready) output on channel1. If the specified state is true (nonzero), the signal is made active (i.e., high in UART register, low at the UART output pin, and high on the RS232 cable). If the specified state is false (zero), the signal is made inactive (i.e., low in the UART register, high at the UART output pin, and low on the RS232 cable). This signal is typically used for modem handshaking.

C: void Is_RTS ( int desired_state, int module_num )
4th: Is_RTS ( desired_state\module_num -- )

Writes the specified state to the RTS (Request To Send) output on channel1. If the specified state is true (nonzero), the signal is made active (i.e., high in UART register, low at the UART output pin, and high on the RS232 cable). If the specified state is false (zero), the signal is made inactive (i.e., low in the UART register, high at the UART output pin, and low on the RS232 cable). This signal is typically used for modem handshaking.

C: uchar Key_UART ( int channel_num, int module_num )
4th: Key_UART ( channel_num\module_num -- char )

Waits (if necessary) for receipt of a character from the specified channel and module, and returns the received character. PAUSEs while waiting. The returned byte is the next pending character in the FIFO (that is, the oldest unretrieved character in the receive FIFO).

See also Ch1_Key and Ch2_Key..

C: LOW_PARITY
4th: LOW_PARITY ( -- n )

A constant (= 0x38) that, when passed as a parameter to the Set_Data_Format function, configures the channel’s data format for low parity, meaning that the parity bit is low at the UART. This is also known as "space parity".

C: NOT_USED
4th: NOT_USED ( -- n )

A constant (= 0) that, when passed as a parameter to the Set_Protocols function, indicates that the specified channel is not in use.

C: NO_PARITY
4th: NO_PARITY ( -- n )

A constant (= 0) that, when passed as a parameter to the Set_Data_Format function, configures the channel’s data format for no parity.

C: ODD_PARITY
4th: ODD_PARITY ( -- n )

A constant (= 0x08) that, when passed as a parameter to the Set_Data_Format function, configures the channel’s data format for odd parity, meaning that the sum of the bits is constrained to be odd.

C: int Read_CTS ( int module_num )
4th: Read_CTS ( module_num -- flag )

Returns the current state of the CTS (Clear To Send) input on channel1. Returns true (-1) if the signal is active (i.e., high in UART register, low at the UART output pin, and high on the RS232 cable). Returns false (zero) if the signal is inactive (i.e., low in the UART register, high at the UART output pin, and low on the RS232 cable). This signal is typically used for modem handshaking.

C: int Read_DCD ( int module_num )
4th: Read_DCD ( module_num -- flag )

Returns the current state of the DCD (Data Carrier Detect) input on channel1. Returns a true (-1) flag if the signal is active (i.e., high in UART register, low at the UART output pin, and high on the RS232 cable). Returns false (zero) if the signal is inactive (i.e., low in the UART register, high at the UART output pin, and low on the RS232 cable). This signal is typically used for modem interfacing.

C: int Read_DSR ( int module_num )
4th: Read_DSR ( module_num -- flag )

Returns the current state of the DSR (Data Set Ready) input on channel1. Returns true (-1) if the signal is active (i.e., high in UART register, low at the UART output pin, and high on the RS232 cable). Returns false (zero) if the signal is inactive (i.e., low in the UART register, high at the UART output pin, and low on the RS232 cable). This signal is typically used for modem handshaking.

C: int Read_UART_Number ( void )
4th: Read_UART_Number ( -- module_num )

Returns the module number that was set by the last execution of Set_UART_Number; see its glossary entry.

C: RS232
4th: RS232 ( -- n )

A constant (= 2) that, when passed as a parameter to the Set_Protocols function, configures the specified channel’s data format for RS232.

C: RS422
4th: RS422 ( -- n )

A constant (= 1) that, when passed as a parameter to the Set_Protocols function, configures the specified channel’s data format for RS422.

C: RS485
4th: RS485 ( -- n )

A constant (= 0x21) that, when passed as a parameter to the Set_Protocols function, configures the specified channel’s data format for RS485.

C: void RS485_Rcv_UART ( int channel_num, int module_num )
4th: RS485_Rcv_UART ( channel_num\module_num -- )

Puts the specified RS485 channel into receive mode. Turns on the receiver and turns off the transmitter of the RS485 driver chip on the specified channel. The application program is responsible for making sure that all pending outgoing characters have been transmitted before invoking this function, as characters that have not yet been transmitted will be lost when the transmitter is disabled. To avoid this problem, use the higher level function named RS485_Rcv_When_Xmit_Done.

C: void RS485_Rcv_When_Xmit_Done ( int channel_num, int module_num )
4th: RS485_Rcv_When_Xmit_Done ( channel_num\module_num -- )

Puts the specified RS485 channel into receive mode. Waits and PAUSEs until the transmit FIFO is empty, then turns on the receiver and turns off the transmitter of the RS485 driver chip on the specified channel. This function ensures that pending outgoing characters are fully transmitted before disabling the RS485 transmitter.

C: void RS485_Xmit_UART ( int channel_num, int module_num )
4th: RS485_Xmit_UART ( channel_num\module_num -- )

Puts the specified RS485 channel into transmit mode. Turns on the transmitter and turns off the receiver of the RS485 driver chip on the specified channel. The application program is responsible for making sure that all expected characters have been received before invoking this function, as incoming characters that have not yet been queued in the receiver FIFO will be lost when the receiver is disabled.

C: void Run_Demo ( void )
4th: Run_Demo ( -- )

The top level function in the demonstration program. When called, it builds and activates two tasks named CH1_TASK and CH2_TASK. Each task runs the interactive monitor using a channel on the UART Wildcard. The initialization is performed by Default_UART_Init (see its glossary entry). Each task revectors the Emit, Key and Ask_Key (also called ?KEY) primitives so that all task I/O is implemented via the UART Wildcard. The default QED-Forth task stays active using the serial port on the Mosaic Controller. Thus, invoking this function allows you to simultaneously run three serial connections on the Mosaic Controller.

C: void Send_Break ( int channel_num, int module_num )
4th: Send_Break ( channel_num\module_num -- )

Waits and PAUSEs until the transmitter FIF0 is empty, then transmits a break on the specified serial channel. Break forces the output at the UART to the low (space) state. Use End_Break to end the break sequence.

C: void Set_Baud ( uint baudrate, int channel, int module )
4th: Set_Baud ( baudrate\channel\module -- )

Sets the baud rate of the specified channel on the specified Wildcard. The actual baud rate differs from that requested by a small error owing to rounding of an internal divisor. The baud rate produced is,

   Baud_actual = 500000 / Round(500000/Baud_desired)

where Baud_desired is an unsigned integer from 1 to 56000, 500000 is the frequency of the UART's internal clock and Round(500000/Baud_desired) is an internal integer divisor. So long as the error between the actual baud rate and that specified is less than 1.5% (or the error between transmitter and receiver is less than 3%) there should be no communication errors.

Baud rates up to 56,000 baud are supported. There are different sets of standard baud rates in use depending on the application. Modem to phone line communications use rates of 110, 150, 300, 600, 1200, 2400, 3000, and 3200 baud. Modem to modem lines often use 1200, 4800, 9600, 14400, 28800, 33600, and 56000 baud. Port to modem communications usually use 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600 and 115200 baud.

Of these baud rates in common use, the UART Wildcard can produce the following at high accuracy:

Both the local and remote UARTs must be configured for the same baud rate. You may use nonstandard baud rates if both devices support them. The UART Wildcard supports any baud rate produced by the above formula.

C: void Set_Data_Format ( int numbits, int stopBits, int parity, int channel, int module )
4th: Set_Data_Format ( numbits\stopBits\parity\channel\module -- )

Sets the data format of the specified channel on the specified Wildcard according to the specified input parameters. Sets the number of data bits per character to equal the numbits parameter, where numbits must equal 5, 6, 7, or 8. Sets the number of stop bits to 1 if stopBits = 1; otherwise sets the number of stop bits to 2. Sets the parity as specified by the parity parameter; allowed values are NO_PARITY, EVEN_PARITY, ODD_PARITY, HIGH_PARITY, or LOW_PARITY (see their glossary entries).

Notes: This function stops any in-progress break transmission.

If numbits = 5 and stopBits=2, the UART hardware implements 1.5 stop bits.

C: int Set_Protocols ( int ch1_modem, int ch1_protocol, int ch2_protocol, int module )
4th: Set_Protocols ( ch1_modem\ch1_protocol\ch2_protocol\module -- error )

Sets the protocols for each channel according to the specified parameters. If an invalid protocol combination is specified as described below, this function exits and returns a nonzero error flag. Otherwise, this function initializes the UART Wildcard hardware, configuring channel 1 for the specified ch1_protocol, and channel 2 for the specified ch2_protocol. Allowed protocol parameters are the constants RS232, RS422, RS485, and NOT_USED; see their glossary entries. The ch1_modem parameter is a flag that determines whether the modem handshaking signals are enabled on channel 1. If the ch1_modem flag is true (nonzero), the handshaking is enabled; otherwise, it is disabled. The DTR and RTS handshaking outputs are set to the active state; see Is_DTR and Is_RTS. The UART hardware is configured with all FIFO’s active, and interrupts disabled (polling is used to monitor the UART). If RS485 is specified on a channel, that channel is put in receiving mode. If RS232 or RS422 is specified on a channel, that channel’s transmitters & receivers are enabled. An invalid protocol combination occurs: (1) if ch1_modem is true AND ch1_protocol is not RS232; or, (2) if ch1_modem is true AND ch2_protocol is RS232. See the "UART Wildcard Hardware: Modem Handshaking Signals" section for more details.

C: void Set_UART_Number ( int module_num )
4th: Set_UART_Number ( module_num -- )

Saves the specified module number in a variable that is accessed by the channel-specific serial I/O primitives Ch1_Emit, Ch2_Emit, Ch1_Ask_Key, Ch2_Ask_Key, Ch1_Key, and Ch2_Key.

See also Read_UART_Number..

C: UART_MODULE_NUM
4th: UART_MODULE_NUM ( -- n )

A constant in the demonstration program whose value equals the Wildcard number. This value must correspond to the jumper settings as shown in Table 1-1. This constant is used by the demonstration program functions Ch1_Emit, Ch2_Emit, Ch1_Ask_Key, Ch2_Ask_Key, Ch1_Key, Ch2_Key, and Run_Demo. The default value in the demonstration source code is 4.

C: void Use_Uart_Ch1 ( void )
4th: Use_Uart_Ch1 ( -- )

Revectors the Emit, Key and Ask_Key (also called ?KEY) primitives so that all I/O for the current task is implemented via the UART Wildcard on Channel 1.

C: void Use_Uart_Ch2 ( void )
4th: Use_Uart_Ch2 ( -- )

Revectors the Emit, Key and Ask_Key (also called ?KEY) primitives so that all I/O for the current task is implemented via UART Wildcard on Channel 2.

C: void Wait_Until_Xmit_Done ( int channel_num, int module_num )
4th: Wait_Until_Xmit_Done ( channel_num\module_num -- )

Waits and PAUSEs until the transmitter FIF0 on the specified channel is empty.

See also →

• UART Forth Demo
• UART C Demo
• UART Wildcard User Guide