Serial Interface

Serial Overview

Serial interfaces serve as fundamental communication interfaces facilitating the transfer of data between devices one bit at a time. Unlike parallel transmission, where multiple bits are sent simultaneously over multiple channels, serial communication operates sequentially over a single wire or pair of wires. This method of data transfer, widely adopted across embedded systems, computer peripherals, networking devices, and various other applications, owes its popularity to its simplicity, versatility, and ease of implementation.

Supported Communication Modes

The following modes of serial communication are supported:

  • Blocking - Here the read/write function waits(blocked) till the operation is performed or time out

  • Non-Blocking - The read/write function returns immediately and the registered callback is invoked after the completion of operation or time out

Application Interface

The below table captures the functions that are to be called from the application layer.

API Functions

Function

Description

rs_serial_open

To open the serial interface.

rs_serial_set_config

To configure the serial interface.

rs_serial_handle_timeouts

To handle the read/write timeouts for a non-blocking call.

rs_serial_write

To write the data to the serial interface.

rs_serial_read

To read the data from the serial interface.

rs_serial_set_inter_char_timeout

To set the inter character timeout for the serial interface.

rs_serial_set_callbacks

To set the callback function for the serial interface.

rs_serial_close

To close the serial interface.

The below table contains callback functions that are to be performed from the HAL.

Callback Functions

Function

Description

rcb_hal_uart_callback

It is called if a character is received from the serial interface through an interrupt or transmit done.

Error Code

  • Every API’s for the Serial returns some success or failure values. Please refer below section,

Implementation Guide

This section explains how to implement the Serial interface using the RAPIDSEA stack, the steps to be followed are

  • Configure the preferred method of RX or TX communication(FIFO / Direct and Blocking / Non-Blocking).

  • Allocate the RX and TX buffers that are to be used for the FIFO method.

  • Configure the serial interface(Baud rate, Parity, Flow control, Data length, Stop bits and Address).

  • Then call the initialize call of the serial interface.

  • Set the callback function and inter character timeout using the provided serial interface functions.

  • Perform the read and write functions as required and handle the error codes.

  • Close the Serial interface.

Note:

The configurations are done by loading the provided serial structure(rs_serial_config_t) from the application layer.

Documentation from the relevant header as follows:

Serial Port Specific APIs.

Defines macros and functions specific to Serial Port functionality

Author

Embien RAPIDSEA Team

Copyright

Embien Technologies India Pvt. Ltd.

Defines

RS_SERIAL_PORT_NAME_MAX_LEN

Maximum length of Port name.

RS_SERIAL_PORT_BAUD_600

Baudrate of 600 bps.

RS_SERIAL_PORT_BAUD_1200

Baudrate of 1200 bps.

RS_SERIAL_PORT_BAUD_2400

Baudrate of 2400 bps.

RS_SERIAL_PORT_BAUD_4800

Baudrate of 4800 bps.

RS_SERIAL_PORT_BAUD_9600

Baudrate of 9600 bps.

RS_SERIAL_PORT_BAUD_19200

Baudrate of 19200 bps.

RS_SERIAL_PORT_BAUD_57600

Baudrate of 57600 bps.

RS_SERIAL_PORT_BAUD_115200

Baudrate of 115200 bps.

RS_SERIAL_PORT_PARITY_DISABLED

Parity Disabled.

RS_SERIAL_PORT_PARITY_ODD

Odd Parity.

RS_SERIAL_PORT_PARITY_EVEN

Even Parity.

RS_SERIAL_PORT_FLOW_CTRL_DISABLED

Flow control Disabled.

RS_SERIAL_PORT_FLOW_CTRL_RTS_CTS

Flow control with RTS and CTS Only.

RS_SERIAL_PORT_FLOW_CTRL_FULL

Flow control with all control signals.

RS_SERIAL_PORT_DATA_LENGTH_5BITS

5 Data bits

RS_SERIAL_PORT_DATA_LENGTH_6BITS

6 Data bits

RS_SERIAL_PORT_DATA_LENGTH_7BITS

7 Data bits

RS_SERIAL_PORT_DATA_LENGTH_8BITS

8 Data bits

RS_SERIAL_PORT_STOP_BITS_ONE

One Stop bit.

RS_SERIAL_PORT_STOP_BITS_TWO

Two Stop bits*/.

RS_SERIAL_BLOCKING

Blocking Mode operation.

RS_SERIAL_NON_BLOCKING

Non-Blocking Mode operation.

RS_SERIAL_RX_MODE_FIFO

Receive in FIFO mode.

RS_SERIAL_RX_MODE_DIRECT

Receive in direct mode.

RS_SERIAL_TX_MODE_FIFO

Transmit in FIFO mode.

RS_SERIAL_TX_MODE_DIRECT

Transmit in direct mode.

RS_SERIAL_CALLBACK_ON_TRANSMIT_COMPLETE

Called on successful transmission.

RS_SERIAL_CALLBACK_ON_RECEIVE_COMPLETE

Called on successful reception.

RS_SERIAL_CALLBACK_ON_RX_OVERRUN

Called on receive overrun.

RS_SERIAL_CALLBACK_ON_TRANSMIT_TIMEOUT

Called on transmit timeout.

RS_SERIAL_CALLBACK_ON_CHAR_RECEIVE

Called on char receive.

RS_SERIAL_CALLBACK_ON_TRANSMIT_ERROR

Called on transmission error.

RS_SERIAL_CALLBACK_ON_RECEIVE_TIMEOUT

Called on receive timeout.

RS_SERIAL_CALLBACK_ON_RECEIVE_ERROR

Called on receive error.

Typedefs

typedef struct tag_rs_serial_config rs_serial_config_t

Structure for configuring the UART interface.

typedef void (*rs_serial_callback)(rs_handle_t handle, rs_ret_val_t reason, void *ptr_args)

Serial callback function.

typedef struct tag_rs_serial_instance rs_serial_instance_t

Structure for the UART instance information.

Functions

rs_handle_t rs_serial_open(rs_serial_instance_t *ptr_instance, rs_serial_config_t *ptr_config)

Configures the Serial port.

This function configures/re-configures the serial port as per the given configuration

Parameters:

  • ptr_instance – [in] - Pointer to the run time information structure

  • ptr_config – [in] - Pointer to the configuration structure

Returns:

0 on success or error code on failure

rs_ret_val_t rs_serial_set_config(rs_serial_config_t *ptr_uart_config, uint32_t u32_baud_rate, uint8_t u8_parity, uint8_t u8_flow_ctrl, uint8_t u8_data_len, uint8_t u8_stop_bits, uint8_t *ptr_port_name)

Updates the serial port’s communication settings.

This function configures the serial port with the given communication settings

Parameters:

  • ptr_uart_config – [out] - Pointer to the UART configuration structure

  • u32_baud_rate – [in] - Baud rate

  • u8_parity – [in] - Parity

  • u8_flow_ctrl – [in] - Flow control

  • u8_data_len – [in] - Number of data bits

  • u8_stop_bits – [in] - Number of stop bits

  • ptr_port_name – [in] - Pointer to the port name

Returns:

0 on success or error code on failure

rs_ret_val_t rs_serial_read(rs_handle_t handle, uint8_t *ptr_buf, uint32_t u32_num_bytes, uint32_t u32_time_out)

Reads data from serial port.

This function received data over the serial port on to the given buffer

Parameters:

  • handle – [in] - Handle to the serial port

  • ptr_buf – [in] - Pointer to buffer holding transmit data

  • u32_num_bytes – [in] - Number of bytes to be transmitted

  • u32_time_out – [in] - Time out in ms to wait for transmit complete

Returns:

Number of bytes received or error code on failure

rs_ret_val_t rs_serial_write(rs_handle_t handle, uint8_t *ptr_buf, uint32_t u32_num_bytes, uint32_t u32_time_out)

Writes data to serial port.

This function transmits the given data over the serial port

Parameters:

  • handle – [in] - Handle to the serial port

  • ptr_buf – [in] - Pointer to buffer holding transmit data

  • u32_num_bytes – [in] - Number of bytes to be transmitted

  • u32_time_out – [in] - Time out in ms to wait for transmit complete

Returns:

Number of bytes transmitted or error code on failure

rs_ret_val_t rs_serial_close(rs_handle_t handle)

Closes the given serial port.

This function closes the serial port and perform clean up operations

Parameters:

handle – [in] - Handle to the serial port

Returns:

0 on success or error code on failure

rs_ret_val_t rs_serial_set_inter_char_timeout(rs_handle_t handle, uint32_t u32_timeout)

Set the inter character timeout value in UART configuration structure.

This function sets the inter character timeout value in UART configuration structure

Parameters:

  • handle – [in] - Handle to the serial port

  • u32_timeout – [in] - Timeout value in milliseconds

Returns:

0 on success or error code on failure

rs_ret_val_t rs_serial_set_callback(rs_handle_t handle, void *ptr_rx_cb, void *ptr_arg)
rs_ret_val_t rs_serial_handle_timeouts(rs_handle_t handle)

Handle RX & TX timeouts.

This function handles the RX & TX timeouts

Parameters:

handle – [in] - Handle to the serial port

Returns:

0 on success

struct tag_rs_serial_config
#include <rs_serial.h>

Structure for configuring the UART interface.

Public Members

uint8_t str_port_name[RS_SERIAL_PORT_NAME_MAX_LEN]

Port name.

uint32_t baud_rate

Baud rate.

uint8_t parity

Parity.

uint8_t flow_ctrl

Flow control.

uint8_t data_len

Data Length.

uint8_t stop_bits

Stop bits.

uint8_t rx_mode

RX Mode - FIFO, Direct.

uint8_t tx_mode

TX Mode - FIFO, Direct.

uint8_t non_blocking

Blocking / Non-blocking.

uint8_t rs485_mode

Enable RS485 mode.

uint8_t *ptr_rx_fifo_buf

RX FIFO buffer to use in FIFO mode.

uint32_t rx_fifo_buf_len

RX FIFO Buffer length.

uint8_t *ptr_tx_fifo_buf

TX FIFO buffer.

uint32_t tx_fifo_buf_len

TX FIFO Buffer length.

uint32_t inter_char_timeout

Timeout allowed between 2 characters.

struct tag_rs_serial_instance
#include <rs_serial.h>

Structure for the UART instance information.

Public Members

rs_serial_config_t *ptr_config

Pointer to the configuration structure.

uint32_t u32_uart_handle

UART handle.

uint8_t *ptr_rx_buf

RX buffer to read data into.

uint32_t rx_exp_buf_len

Expected RX Buffer length.

uint32_t rxed_buf_len

RXed Buffer length.

uint32_t last_rxed_time

Last received char time.

uint32_t rx_fifo_read_index

RX read index.

uint32_t rx_fifo_write_index

RX Write index.

uint32_t rx_timeout_time

Last received char time.

uint8_t *ptr_tx_buf

TX buffer.

uint32_t tx_exp_buf_len

Expected TX Buffer length.

uint32_t txed_buf_len

TXed Buffer length.

uint32_t tx_timeout_time

Last received char time.

uint32_t tx_fifo_read_index

TX FIFO Read index.

uint32_t tx_fifo_write_index

TX FIFO Write index.

rs_fevent_t fevent_rx_char

RX Char receive Event handler.

rs_fevent_t fevent_tx_complete

TX Complete Event handler.

rs_serial_callback ptr_cb

Pointer to the callback function.

void *ptr_arg

Pointer to the callback function argument.