Universal Asynchronous Receiver-Transmitter (UART)

Functions
int	radio_uart_config (uint32_t baudrate, uint8_t config)
	Initializes and configures the UART module for the radio chip. More...
size_t	uart_bytes_in_rx_buffer (void)
	Returns the number of bytes that are available to be read from the RX buffer of the UART. More...
int	uart_config (uint32_t baudrate, uint8_t config)
	Initializes and configures the UART module. More...
void	uart_isr (void)
	On reception interrupt service routine of the UART module. Called when any data or error is received by the UART. More...
size_t	uart_read (void *buf, size_t len)
	Reads the specified number of bytes from the RX buffer of the UART. More...
size_t	uart_write (const void *buf, size_t len)
	Writes an array of bytes to the UART. More...

Detailed Description

Platform-specific layer provides a consistent UART API to upper layers of the driver.

UART API Overview

This API contains the functions to configure and control the UART interface of the programmable XBee devices. The device has two universal asynchronous receiver/transmitters, but one of them is directly connected to the UART of the radio chip, so only the first of the UART modules can be externally accessed.

• UART configuration functions:
  • uart_config()
  • radio_uart_config()
• Functions to read/write the UART:
  • uart_bytes_in_rx_buffer()
  • uart_read()
  • uart_write()

• Miscellaneous functions:

  • uart_isr()

  Platform-specific layer provides a consistent UART API to upper layers of the driver.

UART Macros

The uart_config() function needs as second parameter a byte containing the 
configuration masks for the UART. These masks are defined with macros and 
they are the following:

    - Macros to configure the \b parity \b enable:
            - \b UART_CFG_PARITY_DIS        : Disables the parity configuration.
            - \b UART_CFG_PARITY_EN         : Enables the parity configuration.

    - Macros to configure the \b parity \b value:
            - \b UART_CFG_PARITY_EVEN       : Configures the parity to even.
            - \b UART_CFG_PARITY_ODD        : Configures the parity to odd.

    - Macros to configure the number \b data \b bits:
            - \b UART_CFG_BITS_8            : Configures the data bits to 8.
            - \b UART_CFG_BITS_9            : Configures the data bits to 9.

    - Macros to configure the \b parity \b mask:
            - \b UART_CFG_PARITY_MASK       : Enables the UART parity mask.

Usage example:

uart_config(9600, UART_CFG_PARITY_EN | UART_CFG_PARITY_ODD | UART_CFG_BITS_8);

Warning

It is recommended not to use these macros, they are used by the XBee Project Smart Editor of the XBee extensions.

Apart from the configuration macros, there are other macros that configures the number of wires of the UART. These macros should be defined before calling the uart_config() function.

- Macros to configure the number of wires for the UART:
        - \b UART_CFG_MODE_2W           : Configures the UART to use 2 wires (RX and TX)
        - \b UART_CFG_MODE_3W           : Configures the UART to use 3 wires (RX, TX and RTS)
        - \b UART_CFG_MODE_4W           : Configures the UART to use 3 wires (RX, TX, RTS and CTS)

Usage example:

#define UART_CFG_MODE_4W

If none wire macro is defined, the UART will be configured to use 2 wires.

If you define the UART_CFG_MODE_3W or the UART_CFG_MODE_4W macros, you must also define the XBee pins for the RTS, the CTS or both pins:

- If you define the \b UART_CFG_MODE_3W macro you must define the macro 
  to configure the RTS pin:
        - \b UART_CFG_RTS_XPIN          : Defines the XBee pin corresponding to
                                                                  the RTS pin.

- If you define the \b UART_CFG_MODE_4W macro you must define the macro 
  to configure the \b RTS and the \b CTS pins:
        - \b UART_CFG_RTS_XPIN          : Defines the XBee pin corresponding to
                                                                  the RTS pin.
        - \b UART_CFG_CTS_XPIN          : Defines the XBee pin corresponding to
                                                                  the CTS pin.

Usage examples:

 #define UART_CFG_RTS_XPIN         XPIN_4
#define UART_CFG_CTS_XPIN                       XPIN_7

Function Documentation

int radio_uart_config	(	uint32_t	baudrate,
		uint8_t	config
	)

Initializes and configures the UART module for the radio chip.

Parameters

[in]	baudrate	the baud rate of the UART, i.e.: 9600, 115200, etc.
[in]	config	a byte containing the configuration masks for the UART. See the UART Macros for more information.

Return values

0	on success.
EDOM	invalid uint32_t parameter (the baud rate value is out of range)

size_t uart_bytes_in_rx_buffer

(

void

)

Returns the number of bytes that are available to be read from the RX buffer of the UART.

Return values

size_t

the number of bytes contained in the RX buffer.

int uart_config	(	uint32_t	baudrate,
		uint8_t	config
	)

Initializes and configures the UART module.

Parameters

[in]	baudrate	the baud rate of the UART, i.e.: 9600, 115200, etc.
[in]	config	a byte containing the configuration masks for the UART. See the UART Macros for more information.

Return values

0	on success.
EDOM	invalid uint32_t parameter (the baud rate value is out of range)

void uart_isr

(

void

)

On reception interrupt service routine of the UART module. Called when any data or error is received by the UART.

Parameters

None.

Return values

None.

size_t uart_read	(	void *	buf,
		size_t	len
	)

Reads the specified number of bytes from the RX buffer of the UART.

Parameters

[out]	buf	buffer where the read bytes will be stored.
[in]	len	number of bytes to read from the RX buffer of the UART.

Return values

size_t

the number of bytes read.

size_t uart_write	(	const void *	buf,
		size_t	len
	)

Writes an array of bytes to the UART.

Parameters

[in]	buf	buffer containing the bytes to be written.
[in]	len	number of bytes to write from the buffer.

Return values

size_t

number of bytes that where written.