Serial Interfaces

Topics
	Serial Port Error Codes
	UART Error Register Bits

Macros
#define	ADDR_ESCAPE_CHAR   (0xFF)
	Address escape character.
#define	SimpleOpenSerial(p, b)   OpenSerial(p, b, 1, 8, eParityNone)
	Simple open a serial port.

Enumerations
enum	parity_mode {   eParityNone , eParityOdd , eParityEven , eParityMulti ,   eParityMultiOdd , eParityMultiEven }
	Serial Parity Modes. More...

Functions
int	OpenSerial (int portnum, unsigned int baudrate, int stop_bits, int data_bits, parity_mode parity)
	Open a serial port.
int	OpenDefaultSerial ()
	Opens the Default serial port as defined by the Boot Config settings.
void	SerialExpandRxBuffer (int fd, int nb)
	Expand the received serial buffer.
int	SerialClose (int portnum)
	Close a serial port.
void	SerialEnableTxFlow (int port, int enab)
	Enable transmit software flow control on the specified UART.
void	SerialEnableRxFlow (int port, int enab)
	Enable receive software flow control on the specified UART.
void	SerialEnableHwTxFlow (int port, int enab)
	Enable clear-to-send hardware flow control on transmit (TxCTS).
void	SerialEnableHwRxFlow (int port, int enab)
	Enable request-to-send hardware flow control on receive (RxRTS).
void	Serial485HalfDupMode (int port, int enab)
	Enable or disable RS-485 half-duplex mode.
void	SendBreak (int port, uint32_t time)
	Send a break condition on the specified UART.
int	serwriteaddress (int fd, const char c)
	Send an address character in multidrop mode.
int	GetUartErrorReg (int fd)
	Get and clear the accumulated UART error register.
void	SetRTS (int port, bool val)
	Set or clear the Request To Send (RTS) signal.
BOOL	SerialSendComplete (int fd)
	Check whether serial transmission is complete.

Detailed Description

#include< serial.h>

Serial Port to UART Mapping Reference

The OpenSerial() and SimpleOpenSerial() functions in serial.h take a portnum parameter that maps to different hardware UART peripherals depending on the platform. This document provides the mapping for each supported platform.

MODM7AE70 / SBE70LC (SAME70)

These platforms share an identical mapping with two peripheral types (USART and UART).

Port	Peripheral	Type
0	USART0	USART
1	USART1	USART
2	UART0	UART
3	UART1	UART
4	UART2	UART
5	UART3	UART
6	UART4	UART

Note

USART vs UART differences

USART ports (0-1) and UART ports (2-6) do NOT have the same capabilities:

Feature	USART (ports 0-1)	UART (ports 2-6)
Data bits	5, 6, 7, 8, 9	8 only
Stop bits	1 or 2	1 only
Parity	All modes	None, odd, even
HW flow control (RTS/CTS)	Yes	No

OpenSerial() will return SERIAL_ERR_PARAM_ERROR if you request unsupported settings on a UART port (e.g. 2 stop bits or non-8 data bits).

SOMRT1061 (i.MX RT1061)

All ports use LPUART peripherals. The mapping is non-sequential – use the SER_PORT_LPUARTx defines for readability.

Port	Peripheral	Convenience Define
0	LPUART3	SER_PORT_LPUART3
1	LPUART2	SER_PORT_LPUART2
2	LPUART4	SER_PORT_LPUART4
3	LPUART5	SER_PORT_LPUART5
4	LPUART6	SER_PORT_LPUART6
5	LPUART7	SER_PORT_LPUART7
6	LPUART8	SER_PORT_LPUART8

MODRT1171 (i.MX RT1171)

All ports use LPUART peripherals. LPUART4 is not available. Use the SER_PORT_LPUARTx defines for readability.

Port	Peripheral	Convenience Define
0	LPUART1	SER_PORT_LPUART1
1	LPUART2	SER_PORT_LPUART2
2	LPUART3	SER_PORT_LPUART3
3	LPUART5	SER_PORT_LPUART5
4	LPUART6	SER_PORT_LPUART6
5	LPUART7	SER_PORT_LPUART7
6	LPUART8	SER_PORT_LPUART8
7	LPUART9	SER_PORT_LPUART9
8	LPUART10	SER_PORT_LPUART10
9	LPUART11	SER_PORT_LPUART11
10	LPUART12	SER_PORT_LPUART12

MOD5441X / NANO54415 (ColdFire MCF5441X)

Direct 1:1 mapping – port N = UART N. The MCF5441X CPU has 10 UARTs (0-9); not all may be physically routed on every board variant. Some higher-numbered UARTs share pins with other peripherals (see notes).

Port	Peripheral	Notes
0	UART0
1	UART1
2	UART2
3	UART3
4	UART4	Shares pins with UART0 RTS/CTS
5	UART5	Shares pins with UART1 RTS/CTS
6	UART6	Shares pins with UART2 CTS/RTS
7	UART7
8	UART8	Shares pins with I2C0 SCL/SDA
9	UART9	Shares pins with CAN1 RX/TX

SB800EX (ColdFire MCF5441X)

Uses the same MCF5441X CPU as MOD5441X but only 2 UARTs are physically routed on this board. Direct 1:1 mapping – port N = UART N.

Port	Peripheral
0	UART0
1	UART1

Macro Definition Documentation

SimpleOpenSerial

#define SimpleOpenSerial	(		p,
			b )   OpenSerial(p, b, 1, 8, eParityNone)

#include <serial.h>

Simple open a serial port.

Select the UART number and baud rate, default parameters will be 1 stop bit, no parity, 8 data bits.

Parameters

p	The UART to open. First port is 0. The maximum number is platform dependent. See: Serial Port to UART Mapping Reference
b	The speed of the serial port in bits per second

See also

OpenSerial()

Enumeration Type Documentation

parity_mode

enum parity_mode

#include <serial.h>

Serial Parity Modes.

Enumerator
eParityNone	No parity.
eParityOdd	Odd parity.
eParityEven	Even parity.
eParityMulti	Multi parity.
eParityMultiOdd	Multi mode, Odd parity.
eParityMultiEven	Multi mode, Even parity.

Function Documentation

GetUartErrorReg()

int GetUartErrorReg

(

int

fd

)

#include <serial.h>

Get and clear the accumulated UART error register.

Returns the accumulated error status bits for the serial port associated with the given file descriptor. Errors are accumulated using a logical OR between calls, so multiple error types may be reported simultaneously. Reading the error register clears it; the next call will return 0 unless new errors have occurred.

The returned value is a bitmask of UART Error Register Bits :

Bit	Mask	Description
3	UART_ERR_BREAK	Received break
2	UART_ERR_FRAME	Framing error
1	UART_ERR_PARITY	Parity error
0	UART_ERR_OVERRUN	Overrun error

---

Expand for Example Usage

Examples

Example: Poll for Serial Errors

int fd = SimpleOpenSerial(0, 115200);
 
// Periodically check for errors
int err = GetUartErrorReg(fd);
if (err > 0)
{
    if (err & UART_ERR_OVERRUN) { iprintf("Overrun error\r\n"); }
    if (err & UART_ERR_PARITY)  { iprintf("Parity error\r\n"); }
    if (err & UART_ERR_FRAME)   { iprintf("Framing error\r\n"); }
    if (err & UART_ERR_BREAK)   { iprintf("Break received\r\n"); }
}
// err is now cleared; next call returns 0 unless new errors occur

---

Parameters

fd	The file descriptor associated with the UART serial port

Returns

The accumulated error bitmask (>= 0) if successful, or a Serial Port Error Codes value on failure.

OpenDefaultSerial()

int OpenDefaultSerial

(

)

#include <serial.h>

Opens the Default serial port as defined by the Boot Config settings.

This function opens the Default serial port as defined by the Boot Config settings. It is called automatically by the system as part of the system initialization process. Unlike OpenSerial and SimpleOpenSerial, OpenDefaultSerial will configure the Tx and Rx pins to the Boot Config settings.

Returns

The file descriptor of the default serial port ( > 0), or Serial Port Error Codes

See also

OpenSerial()

OpenSerial()

int OpenSerial	(	int	portnum,
		unsigned int	baudrate,
		int	stop_bits,
		int	data_bits,
		parity_mode	parity )

#include <serial.h>

Open a serial port.

This function opens a serial port. Note that functions to open a serial port, such as OpenSerial() and SimpleOpenSerial(), must be called before any functions or pin assignments that configure the operation of the serial port. You must also configure all pins that have the same UART capability. For example, if UART 1 TX can be configured to come out on more than one pin (as a second or third alternate function), you must set those pins to some function other than UART 1 TX. This is because the functions that open a serial port will configure all serial port functions to default operation and default pins. For example, hardware flow control will be off, and the default pin assignments will be used on those platform that have multiple outputs.

Note

MODM7AE70 and SBE70LC platforms have two UART types: USART for serial ports 0 and 1, and two wire UARTs for serial ports 2 that support RS-232, 1 stop bit , 8 data bits, and parity: even, odd, none.

---

Expand for Example Usage

Examples

Example: Open a Serial Port with Full Parameters

// Open UART 0 at 115200 baud, 1 stop bit, 8 data bits, no parity
int fd = OpenSerial(0, 115200, 1, 8, eParityNone);
if (fd > 0)
{
    writestring(fd, "Hello Serial World!\r\n");
}

Example: Open with Even Parity

// Open UART 1 at 9600 baud with even parity
int fd = OpenSerial(1, 9600, 1, 8, eParityEven);
if (fd <= 0)
{
    iprintf("Failed to open serial port: %d\r\n", fd);
}

---

Parameters

portnum	The UART to open. First port is 0. The maximum number is platform dependent. See: Serial Port to UART Mapping Reference
baudrate	The speed of the serial port in bits per second
stop_bits	The number of stop bits, 1 or 2 (Hardware may not support all values)
data_bits	The number of data bits sent per character or frame: 5, 6, 7 or 8 (Hardware may not support all values)
parity	The type of parity checking to use: eParityNone, eParityEven, eParityOdd or eParityMulti

Returns

The file descriptor of the serial port ( > 0), or Serial Port Error Codes

See also

SimpleOpenSerial()

SendBreak()

void SendBreak	(	int	port,
		uint32_t	time )

#include <serial.h>

Send a break condition on the specified UART.

Sets a break in the UART transmission for a given period of time. The break starts when character transmission completes. The break is delayed until any character in the transmitter shift register is sent. Any character in the transmitter holding register is sent after the break.

Note

This feature may not be supported on all UART modules. Please refer to the processor's datasheet for details on supported features.

Parameters

port	The UART whose transmitter will be forced low (start break)
time	The amount of time in ticks that the break will hold; when time expires, the break will be stopped. TICKS_PER_SECOND ticks equal 1 second by default (typically 20).

Serial485HalfDupMode()

void Serial485HalfDupMode	(	int	port,
		int	enab )

#include <serial.h>

Enable or disable RS-485 half-duplex mode.

Full-duplex mode is automatically enabled when half-duplex mode is disabled. This must be explicitly called before RS-485 functionality can be used. Jumpers may also be needed depending on the hardware device and/or development board used.

Parameters

port	The UART port to use; the UART that can only be used for RS-485 depends on the platform (e.g., MOD52xx mounted on the MOD-DEV-100 development board uses only UART 0 for RS-485, CB34-EX uses only UART 1 for RS-485)
enab	0 disables half-duplex (enables full-duplex), 1 enables half-duplex (disables full-duplex)

SerialClose()

int SerialClose

(

int

portnum

)

#include <serial.h>

Close a serial port.

Parameters

portnum

The UART to close. First port is 0. The maximum number is platform dependent

Returns

0 if successful, otherwise Serial Port Error Codes

See also

OpenSerial()

SerialEnableHwRxFlow()

void SerialEnableHwRxFlow	(	int	port,
		int	enab )

#include <serial.h>

Enable request-to-send hardware flow control on receive (RxRTS).

Enables or disables request-to-send hardware flow control on receive. When enabled, receive throttles the transmitter on the other end. Jumpers may also be needed to enable the RxRTS line depending on the device and/or development board used.

(NB Device)    Rx <--<--< Tx    (Other Device)
(NB Device) RxRTS >-->--> TxCTS (Other Device)

Parameters

port	The UART whose flow control will be toggled
enab	0 disables flow control, non-zero enables flow control

SerialEnableHwTxFlow()

void SerialEnableHwTxFlow	(	int	port,
		int	enab )

#include <serial.h>

Enable clear-to-send hardware flow control on transmit (TxCTS).

Enables or disables clear-to-send hardware flow control on transmit. When enabled, transmit is throttled by the receiver on the other end. Jumpers may also be needed to enable the TxCTS line depending on the device and/or development board used.

(NB Device)    Tx >-->--> Rx    (Other Device)
(NB Device) TxCTS <--<--< RxRTS (Other Device)

Note

Calling this function to disable Tx hardware flow control after enabling RS-485 full-duplex mode configures for RS-422 mode (Tx stays actively driven).

Parameters

port	The UART whose flow control will be toggled
enab	0 disables flow control, non-zero enables flow control

SerialEnableRxFlow()

void SerialEnableRxFlow	(	int	port,
		int	enab )

#include <serial.h>

Enable receive software flow control on the specified UART.

Enables or disables software flow control (XON/XOFF) on receive. When enabled, the NetBurner device will send special XON and XOFF characters to another device in order to control the flow of incoming data.

Parameters

port	The UART whose flow control will be toggled
enab	0 disables flow control, non-zero enables flow control

SerialEnableTxFlow()

void SerialEnableTxFlow	(	int	port,
		int	enab )

#include <serial.h>

Enable transmit software flow control on the specified UART.

Enables or disables software flow control (XON/XOFF) on transmit. When enabled, the NetBurner device will recognize the special XON and XOFF characters being sent from another device in order to throttle the output.

Parameters

port	UART number
enab	0 disables flow control, 1 enables flow control

SerialExpandRxBuffer()

void SerialExpandRxBuffer	(	int	fd,
		int	nb )

#include <serial.h>

Expand the received serial buffer.

This function expands the number of buffer descriptors the specific serial port is allowed to use. Each buffer descriptor counts for 1500 bytes, so setting nb to 10 would make the serial Rx buffer 15000 bytes.

Parameters

fd	The file descriptor of the serial port returned by OpenSerial() or SimpleOpenSerial()
nb	The number of buffer descriptors to allow (each is 1500 bytes)

SerialSendComplete()

BOOL SerialSendComplete

(

int

fd

)

#include <serial.h>

Check whether serial transmission is complete.

Determines if all data waiting in the transmitter holding and shift registers has been sent.

Parameters

fd	The file descriptor of the serial port

Returns

TRUE if all data has been sent, FALSE if data is still being transmitted

serwriteaddress()

int serwriteaddress	(	int	fd,
		const char	c )

#include <serial.h>

Send an address character in multidrop mode.

Sends an address character via the UART port number associated with the given file descriptor. This function can only be utilized if the UART is initialized in multidrop mode (eParityMulti, eParityMultiOdd, or eParityMultiEven).

Parameters

fd	The file descriptor associated with the UART serial port
c	The address character to be sent

Returns

1 if successful, otherwise a Serial Port Error Codes value. SERIAL_ERR_PORT_NOTOPEN is also returned if the UART is not initialized in multidrop mode.

SetRTS()

void SetRTS	(	int	port,
		bool	val )

#include <serial.h>

Set or clear the Request To Send (RTS) signal.

Sets or clears the Request To Send signal for the specified serial port.

Parameters

port	The UART port whose RTS signal will be set or cleared (0 or 1)
val	true sets the RTS signal, false clears it