3.24 UART Driver
Overview
Universal Asynchronous Receiver Transmitter (UART) is a flexible serial communication module used to interface microcontrollers with other peripherals. It features a full duplex, asynchronous communication channel that can be used to implement protocols, such as RS-232 and RS-485.
Features
- Supports Polling Mode, Interrupt mode and Interrupt mode with software buffer
- Full or Half-Duplex Operation
- 8-Bit or 9-Bit Data Width
- Configurable Stop Bit Length
- Parity, Framing and Buffer Overrun Error Detection
3.24.1 How to use the UART Driver
The UART driver generates a portable API interface. For an example of how to use the interface to write and read data, refer to this examples linked below. Click the links to view the code snippets associated with each
Instructions common for all code snippets: 2.28.5.1.1 UART Use Case Code Snippet Instructions.
- 2.28.5.1.2 UART Use Case 1: Printf with Variable Counter This example uses printf to print: "x Hello World!" to a terminal, where x is a counter.
- 2.28.5.1.3 UART Use Case 2: Write String Write any message, by calling UART_write_string(msg), passing the message to print on the terminal. Can be a light-weight alternative to printf.
- 2.28.5.1.4 UART Use Case 3: Control Commands - Using Interrupt Mode This example shows how to implement a basic Command Line Interface (CLI). Here a LED is controlled using commands from a terminal. Send "ON" to turn the LED on, and "OFF" to turn it off using Interrupt Mode.
- 2.28.5.1.5 UART Use Case 4: Control Commands - Using Polling Mode This example shows how to implement a basic Command Line Interface (CLI). Here a LED is controlled using commands from a terminal. Send "ON" to turn the LED on, and "OFF" to turn it off using Polling Mode.
- 2.28.5.1.6 UART Use Case 5: Mirror Back Typed Characters This example demonstrates how to send and receive data byte using UART read and write functions. A catch for a read error, if any, in the received byte is also implemented.
3.24.2 Module Documentation
3.24.2.1 UART Driver
Universal Asynchronous Receiver Transmitter driver using dsPIC MCUs.
3.24.2.1.1 Module description
Universal Asynchronous Receiver Transmitter driver using dsPIC MCUs.
Data structures
struct UART_INTERFACE
Structure containing the function pointers of UART driver.
Definitions
#define UART1_Drv_Initialize UART1_Initialize
This macro defines the Custom Name for UART1_Initialize API.
#define UART1_Drv_Deinitialize UART1_Deinitialize
This macro defines the Custom Name for UART1_Deinitialize API.
#define UART1_Drv_Read UART1_Read
This macro defines the Custom Name for UART1_Read API.
#define UART1_Drv_Write UART1_Write
This macro defines the Custom Name for UART1_Write API.
#define UART1_Drv_IsRxReady UART1_IsRxReady
This macro defines the Custom Name for UART1_IsRxReady API.
#define UART1_Drv_IsTxReady UART1_IsTxReady
This macro defines the Custom Name for UART1_IsTxReady API.
#define UART1_Drv_IsTxDone UART1_IsTxDone
This macro defines the Custom Name for UART1_IsTxDone API.
#define UART1_Drv_TransmitEnable UART1_TransmitEnable
This macro defines the Custom Name for UART1_TransmitEnable API.
#define UART1_Drv_TransmitDisable UART1_TransmitDisable
This macro defines the Custom Name for UART1_TransmitDisable API.
#define UART1_Drv_AutoBaudSet UART1_AutoBaudSet
This macro defines the Custom Name for UART1_AutoBaudSet API.
#define UART1_Drv_AutoBaudQuery UART1_AutoBaudQuery
This macro defines the Custom Name for UART1_AutoBaudQuery API.
#define UART1_Drv_AutoBaudEventEnableGet UART1_AutoBaudEventEnableGet
This macro defines the Custom Name for UART1_AutoBaudEventEnableGet API.
#define UART1_Drv_ErrorGet UART1_ErrorGet
This macro defines the Custom Name for UART1_ErrorGet API.
#define UART1_Drv_BRGCountSet UART1_BRGCountSet
This macro defines the Custom Name for UART1_BRGCountSet API.
#define UART1_Drv_BRGCountGet UART1_BRGCountGet
This macro defines the Custom Name for UART1_BRGCountGet API.
#define UART1_Drv_BaudRateSet UART1_BaudRateSet
This macro defines the Custom Name for UART1_BaudRateSet API.
#define UART1_Drv_BaudRateGet UART1_BaudRateGet
This macro defines the Custom Name for UART1_BaudRateGet API.
#define UART1_Drv_RxCompleteCallbackRegister UART1_RxCompleteCallbackRegister
This macro defines the Custom Name for UART1_RxCompleteCallbackRegister API.
#define UART1_Drv_TxCompleteCallbackRegister UART1_TxCompleteCallbackRegister
This macro defines the Custom Name for UART1_TxCompleteCallbackRegister API.
#define UART1_Drv_TxCollisionCallbackRegister UART1_TxCollisionCallbackRegister
This macro defines the Custom Name for UART1_TxCollisionCallbackRegister API.
#define UART1_Drv_FramingErrorCallbackRegister UART1_FramingErrorCallbackRegister
This macro defines the Custom Name for UART1_FramingErrorCallbackRegister API.
#define UART1_Drv_OverrunErrorCallbackRegister UART1_OverrunErrorCallbackRegister
This macro defines the Custom Name for UART1_OverrunErrorCallbackRegister API.
#define UART1_Drv_ParityErrorCallbackRegister UART1_ParityErrorCallbackRegister
This macro defines the Custom Name for UART1_ParityErrorCallbackRegister API.
Enumerations
enum UART_ERROR_MASKS { UART_ERROR_FRAMING_MASK = 0x1, UART_ERROR_PARITY_MASK = 0x2, UART_ERROR_RX_OVERRUN_MASK = 0x4, UART_ERROR_TX_COLLISION_MASK = 0x8, UART_ERROR_AUTOBAUD_OVERFLOW_MASK = 0x10 }
This Enum can be used to know UART error type using UARTx_ErrorGet function e.g. UART1_ErrorGet.
Functions
void UART1_Initialize (void)
Initializes the UART driver.
void UART1_Deinitialize (void)
Deinitializes the UART to POR values.
uint8_t UART1_Read (void)
Reads a byte of data from the UART1.
void UART1_Write (uint8_t data)
Writes a byte of data to the UART1.
bool UART1_IsRxReady (void)
Returns a boolean value if data is available to read.
bool UART1_IsTxReady (void)
Returns a boolean value if data can be written.
bool UART1_IsTxDone (void)
Indicates if all bytes have been transferred.
void UART1_TransmitEnable (void)
Enables UART1 transmit.
void UART1_TransmitDisable (void)
Disables UART1 transmit.
void UART1_AutoBaudSet (bool enable)
Enables or disables UART1 Auto-Baud detection.
bool UART1_AutoBaudQuery (void)
Returns the status of Auto-Baud detection.
bool UART1_AutoBaudEventEnableGet (void)
Returns enable state of the Auto-Baud feature.
void UART1_BRGCountSet (uint32_t brgValue)
Sets the BRG value of UART1.
uint32_t UART1_BRGCountGet (void)
Gets the BRG value of UART1.
void UART1_BaudRateSet (uint32_t baudRate)
Sets the calculated Baud-Rate of UART1.
uint32_t UART1_BaudRateGet (void)
Gets the actual Baud-Rate of UART1.
size_t UART1_ErrorGet (void)
Returns the error status of UART1.
void UART1_RxCompleteCallbackRegister (void(*handler)(void))
This function can be used to override default callback UART1_RxCompleteCallback and to define custom callback for UART1 RxComplete event.
void UART1_RxCompleteCallback (void)
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_RxCompleteCallbackRegister.
void UART1_TxCompleteCallbackRegister (void(*handler)(void))
This function can be used to override default callback UART1_TxCompleteCallback and to define custom callback for UART1 TxComplete event.
void UART1_TxCompleteCallback (void)
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_TxCompleteCallbackRegister.
void UART1_TxCollisionCallbackRegister (void(*handler)(void))
This function can be used to override default callback UART1_TxCollisionCallback and to define custom callback for UART1 TxCollision event.
void UART1_TxCollisionCallback (void)
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_TxCollisionCallbackRegister.
void UART1_FramingErrorCallbackRegister (void(*handler)(void))
This function can be used to override default callback UART1_FramingErrorCallback and to define custom callback for UART1 FramingError event.
void UART1_FramingErrorCallback (void)
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_FramingErrorCallbackRegister.
void UART1_OverrunErrorCallbackRegister (void(*handler)(void))
This function can be used to override default callback UART1_OverrunErrorCallback and to define custom callback for UART1 OverrunError event.
void UART1_OverrunErrorCallback (void)
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_OverrunErrorCallbackRegister.
void UART1_ParityErrorCallbackRegister (void(*handler)(void))
This function can be used to override default callback UART1_ParityErrorCallback and to define custom callback for UART1 ParityError event.
void UART1_ParityErrorCallback (void)
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_ParityErrorCallbackRegister.
Variables
const struct UART_INTERFACE UART1_Drv
Structure object of type UART_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. UART1 can be changed by the user in the UART user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.
3.24.2.1.2 Definition Documentation
UART1_Drv_AutoBaudEventEnableGet
#define UART1_Drv_AutoBaudEventEnableGet UART1_AutoBaudEventEnableGet
This macro defines the Custom Name for UART1_AutoBaudEventEnableGet API.
UART1_Drv_AutoBaudQuery
#define UART1_Drv_AutoBaudQuery UART1_AutoBaudQuery
This macro defines the Custom Name for UART1_AutoBaudQuery API.
UART1_Drv_AutoBaudSet
#define UART1_Drv_AutoBaudSet UART1_AutoBaudSet
This macro defines the Custom Name for UART1_AutoBaudSet API.
UART1_Drv_BaudRateGet
#define UART1_Drv_BaudRateGet UART1_BaudRateGet
This macro defines the Custom Name for UART1_BaudRateGet API.
UART1_Drv_BaudRateSet
#define UART1_Drv_BaudRateSet UART1_BaudRateSet
This macro defines the Custom Name for UART1_BaudRateSet API.
UART1_Drv_BRGCountGet
#define UART1_Drv_BRGCountGet UART1_BRGCountGet
This macro defines the Custom Name for UART1_BRGCountGet API.
UART1_Drv_BRGCountSet
#define UART1_Drv_BRGCountSet UART1_BRGCountSet
This macro defines the Custom Name for UART1_BRGCountSet API.
UART1_Drv_Deinitialize
#define UART1_Drv_Deinitialize UART1_Deinitialize
This macro defines the Custom Name for UART1_Deinitialize API.
UART1_Drv_ErrorGet
#define UART1_Drv_ErrorGet UART1_ErrorGet
This macro defines the Custom Name for UART1_ErrorGet API.
UART1_Drv_FramingErrorCallbackRegister
#define UART1_Drv_FramingErrorCallbackRegister UART1_FramingErrorCallbackRegister
This macro defines the Custom Name for UART1_FramingErrorCallbackRegister API.
UART1_Drv_Initialize
#define UART1_Drv_Initialize UART1_Initialize
This macro defines the Custom Name for UART1_Initialize API.
UART1_Drv_IsRxReady
#define UART1_Drv_IsRxReady UART1_IsRxReady
This macro defines the Custom Name for UART1_IsRxReady API.
UART1_Drv_IsTxDone
#define UART1_Drv_IsTxDone UART1_IsTxDone
This macro defines the Custom Name for UART1_IsTxDone API.
UART1_Drv_IsTxReady
#define UART1_Drv_IsTxReady UART1_IsTxReady
This macro defines the Custom Name for UART1_IsTxReady API.
UART1_Drv_OverrunErrorCallbackRegister
#define UART1_Drv_OverrunErrorCallbackRegister UART1_OverrunErrorCallbackRegister
This macro defines the Custom Name for UART1_OverrunErrorCallbackRegister API.
UART1_Drv_ParityErrorCallbackRegister
#define UART1_Drv_ParityErrorCallbackRegister UART1_ParityErrorCallbackRegister
This macro defines the Custom Name for UART1_ParityErrorCallbackRegister API.
UART1_Drv_Read
#define UART1_Drv_Read UART1_Read
This macro defines the Custom Name for UART1_Read API.
UART1_Drv_RxCompleteCallbackRegister
#define UART1_Drv_RxCompleteCallbackRegister UART1_RxCompleteCallbackRegister
This macro defines the Custom Name for UART1_RxCompleteCallbackRegister API.
UART1_Drv_TransmitDisable
#define UART1_Drv_TransmitDisable UART1_TransmitDisable
This macro defines the Custom Name for UART1_TransmitDisable API.
UART1_Drv_TransmitEnable
#define UART1_Drv_TransmitEnable UART1_TransmitEnable
This macro defines the Custom Name for UART1_TransmitEnable API.
UART1_Drv_TxCollisionCallbackRegister
#define UART1_Drv_TxCollisionCallbackRegister UART1_TxCollisionCallbackRegister
This macro defines the Custom Name for UART1_TxCollisionCallbackRegister API.
UART1_Drv_TxCompleteCallbackRegister
#define UART1_Drv_TxCompleteCallbackRegister UART1_TxCompleteCallbackRegister
This macro defines the Custom Name for UART1_TxCompleteCallbackRegister API.
UART1_Drv_Write
#define UART1_Drv_Write UART1_Write
This macro defines the Custom Name for UART1_Write API.
3.24.2.1.3 Function Documentation
UART1_AutoBaudEventEnableGet()
bool UART1_AutoBaudEventEnableGet (void )
Returns enable state of the Auto-Baud feature.
none |
true - Auto-Baud is enabled false - Auto-Baud is disabled |
UART1_AutoBaudQuery()
bool UART1_AutoBaudQuery (void )
Returns the status of Auto-Baud detection.
none |
true - Auto-Baud detection in progress or counter overflow occurred false - Auto-Baud detection is complete or disabled |
UART1_AutoBaudSet()
void UART1_AutoBaudSet (bool enable)
Enables or disables UART1 Auto-Baud detection.
in | enable |
- true, starts the auto-baud detection |
in | enable |
- false, disables the auto-baud detection |
none |
UART1_BaudRateGet()
uint32_t UART1_BaudRateGet (void )
Gets the actual Baud-Rate of UART1.
none |
Actual baud-rate of UART1 |
UART1_BaudRateSet()
void UART1_BaudRateSet (uint32_t baudRate)
Sets the calculated Baud-Rate of UART1.
in | baudRate |
- Value of Baud-Rate to be set |
none |
Make sure the is no transmission in progress using UART1_IsTxDone function
UART1_BRGCountGet()
uint32_t UART1_BRGCountGet (void )
Gets the BRG value of UART1.
none |
Combined BRG value upto 20 bits |
UART1_BRGCountSet()
void UART1_BRGCountSet (uint32_t brgValue)
Sets the BRG value of UART1.
in | baudRate |
- BRG value upto 20 bits |
none |
Make sure the is no transmission in progress using UART1_IsTxDone function
UART1_Deinitialize()
void UART1_Deinitialize (void )
Deinitializes the UART to POR values.
none |
none |
UART1_ErrorGet()
size_t UART1_ErrorGet (void )
Returns the error status of UART1.
none |
Errors with masking as per UART1_ERROR_MASKS |
UART1_FramingErrorCallback()
void UART1_FramingErrorCallback (void )
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_FramingErrorCallbackRegister.
none |
none |
UART1_FramingErrorCallbackRegister()
void UART1_FramingErrorCallbackRegister (void(*)(void) handler)
This function can be used to override default callback UART1_FramingErrorCallback and to define custom callback for UART1 FramingError event.
UART1_Initialize()
void UART1_Initialize (void )
Initializes the UART driver.
none |
none |
UART1_IsRxReady()
bool UART1_IsRxReady (void )
Returns a boolean value if data is available to read.
none |
true - Data available to read false - Data not available to read |
UART1_IsTxDone()
bool UART1_IsTxDone (void )
Indicates if all bytes have been transferred.
none |
true - All bytes transferred false - Data transfer is pending |
UART1_IsTxReady()
bool UART1_IsTxReady (void )
Returns a boolean value if data can be written.
none |
true - Data can be written false - Data can not be written |
UART1_OverrunErrorCallback()
void UART1_OverrunErrorCallback (void )
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_OverrunErrorCallbackRegister.
none |
none |
UART1_OverrunErrorCallbackRegister()
void UART1_OverrunErrorCallbackRegister (void(*)(void) handler)
This function can be used to override default callback UART1_OverrunErrorCallback and to define custom callback for UART1 OverrunError event.
UART1_ParityErrorCallback()
void UART1_ParityErrorCallback (void )
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_ParityErrorCallbackRegister.
none |
none |
UART1_ParityErrorCallbackRegister()
void UART1_ParityErrorCallbackRegister (void(*)(void) handler)
This function can be used to override default callback UART1_ParityErrorCallback and to define custom callback for UART1 ParityError event.
UART1_Read()
uint8_t UART1_Read (void )
Reads a byte of data from the UART1.
Check receive status using UART1_IsRxReady function before calling this function or call this function within the UART1_RxCompleteCallback. |
none |
A data byte received by the driver. |
UART1_RxCompleteCallback()
void UART1_RxCompleteCallback (void )
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_RxCompleteCallbackRegister.
none |
none |
UART1_RxCompleteCallbackRegister()
void UART1_RxCompleteCallbackRegister (void(*)(void) handler)
This function can be used to override default callback UART1_RxCompleteCallback and to define custom callback for UART1 RxComplete event.
UART1_TransmitDisable()
void UART1_TransmitDisable (void )
Disables UART1 transmit.
none |
none |
UART1_TransmitEnable()
void UART1_TransmitEnable (void )
Enables UART1 transmit.
none |
none |
UART1_TxCollisionCallback()
void UART1_TxCollisionCallback (void )
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_TxCollisionCallbackRegister.
none |
none |
UART1_TxCollisionCallbackRegister()
void UART1_TxCollisionCallbackRegister (void(*)(void) handler)
This function can be used to override default callback UART1_TxCollisionCallback and to define custom callback for UART1 TxCollision event.
UART1_TxCompleteCallback()
void UART1_TxCompleteCallback (void )
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_TxCompleteCallbackRegister.
none |
none |
This callback is triggerred if there is data in the software buffer and there is atleast one byte space in hardware transmit FIFO
UART1_TxCompleteCallbackRegister()
void UART1_TxCompleteCallbackRegister (void(*)(void) handler)
This function can be used to override default callback UART1_TxCompleteCallback and to define custom callback for UART1 TxComplete event.
UART1_Write()
void UART1_Write (uint8_t data)
Writes a byte of data to the UART1.
UART1_Initialize function should have been called before calling this function. The transfer status should be checked to see if transmitter is not full before calling this function. |
in | data |
- Data byte to write to the UART1 |
none |
3.24.2.1.4 Enumeration Type Documentation
UART_ERROR_MASKS
enum UART_ERROR_MASKS
This Enum can be used to know UART error type using UARTx_ErrorGet function e.g. UART1_ErrorGet.
UART_ERROR_FRAMING_MASK | |
UART_ERROR_PARITY_MASK | |
UART_ERROR_RX_OVERRUN_MASK | |
UART_ERROR_TX_COLLISION_MASK | |
UART_ERROR_AUTOBAUD_OVERFLOW_MASK |
3.24.2.1.5 Variable Documentation
UART1_Drv
const struct UART_INTERFACE UART1_Drv
Structure object of type UART_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. UART1 can be changed by the user in the UART user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.
3.24.3 Data Structure Documentation
3.24.3.1 UART_INTERFACE Struct Reference
Structure containing the function pointers of UART driver.
3.24.3.1.1 Detailed Description
Structure containing the function pointers of UART driver.
#include <uart_interface.h>
Data Fields
void(* Initialize )(void)
Pointer to UARTx_Initialize e.g. UART1_Initialize.
void(* Deinitialize )(void)
Pointer to UARTx_Deinitialize e.g. UART1_Deinitialize.
uint8_t(* Read )(void)
Pointer to UARTx_Read e.g. UART1_Read.
void(* Write )(uint8_t)
Pointer to UARTx_Write e.g. UART1_Write.
bool(* IsRxReady )(void)
Pointer to UARTx_IsRxReady e.g. UART1_IsRxReady.
bool(* IsTxReady )(void)
Pointer to UARTx_IsTxReady e.g. UART1_IsTxReady.
bool(* IsTxDone )(void)
Pointer to UARTx_IsTxDone e.g. UART1_IsTxDone.
void(* TransmitEnable )(void)
Pointer to UARTx_TransmitEnable e.g. UART1_TransmitEnable.
void(* TransmitDisable )(void)
Pointer to UARTx_TransmitDisable e.g. UART1_TransmitDisable.
void(* TransmitInterruptEnable )(void)
Pointer to UARTx_TransmitInterruptEnable e.g. UART1_TransmitInterruptEnable.
void(* TransmitInterruptDisable )(void)
Pointer to UARTx_TransmitInterruptDisable e.g. UART1_TransmitInterruptDisable.
void(* AutoBaudSet )(bool enable)
Pointer to UARTx_AutoBaudSet e.g. UART1_AutoBaudSet.
bool(* AutoBaudQuery )(void)
Pointer to UARTx_AutoBaudQuery e.g. UART1_AutoBaudQuery.
bool(* AutoBaudEventEnableGet )(void)
Pointer to UARTx_AutoBaudEventEnableGet e.g. UART1_AutoBaudEventEnableGet.
void(* BRGCountSet )(uint32_t brgValue)
Pointer to UARTx_BRGCountSet e.g. UART1_BRGCountSet.
uint32_t(* BRGCountGet )(void)
Pointer to UARTx_BRGCOuntGet e.g. UART1_BRGCountGet.
void(* BaudRateSet )(uint32_t baudRate)
Pointer to UARTx_BaudRateSet e.g. UART1_BaudRateSet.
uint32_t(* BaudRateGet )(void)
Pointer to UARTx_BaudRateGet e.g. UART1_BaudRateGet.
size_t(* ErrorGet )(void)
Pointer to UARTx_ErrorGet e.g. UART1_ErrorGet.
void(* RxCompleteCallbackRegister )(void(*CallbackHandler)(void))
Pointer to UARTx_RxCompleteCallbackRegister e.g. UART1_RxCompleteCallbackRegister (defined only in interrupt mode)
void(* TxCompleteCallbackRegister )(void(*CallbackHandler)(void))
Pointer to UARTx_TxCompleteCallbackRegister e.g. UART1_TxCompleteCallbackRegister (defined only in interrupt mode)
void(* TxCollisionCallbackRegister )(void(*CallbackHandler)(void))
Pointer to UARTx_TxCollisionCallbackRegister e.g. UART1_TxCollisionCallbackRegister (defined only in interrupt mode)
void(* FramingErrorCallbackRegister )(void(*CallbackHandler)(void))
Pointer to UARTx_FramingErrorCallbackRegister e.g. UART1_FramingErrorCallbackRegister (defined only in interrupt mode)
void(* OverrunErrorCallbackRegister )(void(*CallbackHandler)(void))
Pointer to UARTx_OverrunErrorCallbackRegister e.g. UART1_OverrunErrorCallbackRegister (defined only in interrupt mode)
void(* ParityErrorCallbackRegister )(void(*CallbackHandler)(void))
Pointer to UARTx_ParityErrorCallbackRegister e.g. UART1_ParityErrorCallbackRegister (defined only in interrupt mode)
3.24.3.1.2 Field Documentation
AutoBaudEventEnableGet
bool(* AutoBaudEventEnableGet) (void)
Pointer to UARTx_AutoBaudEventEnableGet e.g. UART1_AutoBaudEventEnableGet.
AutoBaudQuery
bool(* AutoBaudQuery) (void)
Pointer to UARTx_AutoBaudQuery e.g. UART1_AutoBaudQuery.
AutoBaudSet
void(* AutoBaudSet) (bool enable)
Pointer to UARTx_AutoBaudSet e.g. UART1_AutoBaudSet.
BaudRateGet
uint32_t(* BaudRateGet) (void)
Pointer to UARTx_BaudRateGet e.g. UART1_BaudRateGet.
BaudRateSet
void(* BaudRateSet) (uint32_t baudRate)
Pointer to UARTx_BaudRateSet e.g. UART1_BaudRateSet.
BRGCountGet
uint32_t(* BRGCountGet) (void)
Pointer to UARTx_BRGCOuntGet e.g. UART1_BRGCountGet.
BRGCountSet
void(* BRGCountSet) (uint32_t brgValue)
Pointer to UARTx_BRGCountSet e.g. UART1_BRGCountSet.
Deinitialize
void(* Deinitialize) (void)
Pointer to UARTx_Deinitialize e.g. UART1_Deinitialize.
ErrorGet
size_t(* ErrorGet) (void)
Pointer to UARTx_ErrorGet e.g. UART1_ErrorGet.
FramingErrorCallbackRegister
void(* FramingErrorCallbackRegister) (void(*CallbackHandler)(void))
Pointer to UARTx_FramingErrorCallbackRegister e.g. UART1_FramingErrorCallbackRegister (defined only in interrupt mode)
Initialize
void(* Initialize) (void)
Pointer to UARTx_Initialize e.g. UART1_Initialize.
IsRxReady
bool(* IsRxReady) (void)
Pointer to UARTx_IsRxReady e.g. UART1_IsRxReady.
IsTxDone
bool(* IsTxDone) (void)
Pointer to UARTx_IsTxDone e.g. UART1_IsTxDone.
IsTxReady
bool(* IsTxReady) (void)
Pointer to UARTx_IsTxReady e.g. UART1_IsTxReady.
OverrunErrorCallbackRegister
void(* OverrunErrorCallbackRegister) (void(*CallbackHandler)(void))
Pointer to UARTx_OverrunErrorCallbackRegister e.g. UART1_OverrunErrorCallbackRegister (defined only in interrupt mode)
ParityErrorCallbackRegister
void(* ParityErrorCallbackRegister) (void(*CallbackHandler)(void))
Pointer to UARTx_ParityErrorCallbackRegister e.g. UART1_ParityErrorCallbackRegister (defined only in interrupt mode)
Read
uint8_t(* Read) (void)
Pointer to UARTx_Read e.g. UART1_Read.
RxCompleteCallbackRegister
void(* RxCompleteCallbackRegister) (void(*CallbackHandler)(void))
Pointer to UARTx_RxCompleteCallbackRegister e.g. UART1_RxCompleteCallbackRegister (defined only in interrupt mode)
TransmitDisable
void(* TransmitDisable) (void)
Pointer to UARTx_TransmitDisable e.g. UART1_TransmitDisable.
TransmitEnable
void(* TransmitEnable) (void)
Pointer to UARTx_TransmitEnable e.g. UART1_TransmitEnable.
TransmitInterruptDisable
void(* TransmitInterruptDisable) (void)
Pointer to UARTx_TransmitInterruptDisable e.g. UART1_TransmitInterruptDisable.
TransmitInterruptEnable
void(* TransmitInterruptEnable) (void)
Pointer to UARTx_TransmitInterruptEnable e.g. UART1_TransmitInterruptEnable.
TxCollisionCallbackRegister
void(* TxCollisionCallbackRegister) (void(*CallbackHandler)(void))
Pointer to UARTx_TxCollisionCallbackRegister e.g. UART1_TxCollisionCallbackRegister (defined only in interrupt mode)
TxCompleteCallbackRegister
void(* TxCompleteCallbackRegister) (void(*CallbackHandler)(void))
Pointer to UARTx_TxCompleteCallbackRegister e.g. UART1_TxCompleteCallbackRegister (defined only in interrupt mode)
Write
void(* Write) (uint8_t)
Pointer to UARTx_Write e.g. UART1_Write.
3.24.4 File Documentation
3.24.4.1 source/uart1.h File Reference
This is the generated driver header file for the UART1 driver.
#include <stdbool.h> #include <stdint.h> #include <stddef.h> #include "uart_interface.h"
3.24.4.1.1 Functions
void UART1_Initialize (void)
Initializes the UART driver.
void UART1_Deinitialize (void)
Deinitializes the UART to POR values.
uint8_t UART1_Read (void)
Reads a byte of data from the UART1.
void UART1_Write (uint8_t data)
Writes a byte of data to the UART1.
bool UART1_IsRxReady (void)
Returns a boolean value if data is available to read.
bool UART1_IsTxReady (void)
Returns a boolean value if data can be written.
bool UART1_IsTxDone (void)
Indicates if all bytes have been transferred.
void UART1_TransmitEnable (void)
Enables UART1 transmit.
void UART1_TransmitDisable (void)
Disables UART1 transmit.
void UART1_AutoBaudSet (bool enable)
Enables or disables UART1 Auto-Baud detection.
bool UART1_AutoBaudQuery (void)
Returns the status of Auto-Baud detection.
bool UART1_AutoBaudEventEnableGet (void)
Returns enable state of the Auto-Baud feature.
void UART1_BRGCountSet (uint32_t brgValue)
Sets the BRG value of UART1.
uint32_t UART1_BRGCountGet (void)
Gets the BRG value of UART1.
void UART1_BaudRateSet (uint32_t baudRate)
Sets the calculated Baud-Rate of UART1.
uint32_t UART1_BaudRateGet (void)
Gets the actual Baud-Rate of UART1.
size_t UART1_ErrorGet (void)
Returns the error status of UART1.
void UART1_RxCompleteCallbackRegister (void(*handler)(void))
This function can be used to override default callback UART1_RxCompleteCallback and to define custom callback for UART1 RxComplete event.
void UART1_RxCompleteCallback (void)
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_RxCompleteCallbackRegister.
void UART1_TxCompleteCallbackRegister (void(*handler)(void))
This function can be used to override default callback UART1_TxCompleteCallback and to define custom callback for UART1 TxComplete event.
void UART1_TxCompleteCallback (void)
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_TxCompleteCallbackRegister.
void UART1_TxCollisionCallbackRegister (void(*handler)(void))
This function can be used to override default callback UART1_TxCollisionCallback and to define custom callback for UART1 TxCollision event.
void UART1_TxCollisionCallback (void)
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_TxCollisionCallbackRegister.
void UART1_FramingErrorCallbackRegister (void(*handler)(void))
This function can be used to override default callback UART1_FramingErrorCallback and to define custom callback for UART1 FramingError event.
void UART1_FramingErrorCallback (void)
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_FramingErrorCallbackRegister.
void UART1_OverrunErrorCallbackRegister (void(*handler)(void))
This function can be used to override default callback UART1_OverrunErrorCallback and to define custom callback for UART1 OverrunError event.
void UART1_OverrunErrorCallback (void)
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_OverrunErrorCallbackRegister.
void UART1_ParityErrorCallbackRegister (void(*handler)(void))
This function can be used to override default callback UART1_ParityErrorCallback and to define custom callback for UART1 ParityError event.
void UART1_ParityErrorCallback (void)
This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using UART1_ParityErrorCallbackRegister.
3.24.4.1.2 Macros
#define UART1_Drv_Initialize UART1_Initialize
This macro defines the Custom Name for UART1_Initialize API.
#define UART1_Drv_Deinitialize UART1_Deinitialize
This macro defines the Custom Name for UART1_Deinitialize API.
#define UART1_Drv_Read UART1_Read
This macro defines the Custom Name for UART1_Read API.
#define UART1_Drv_Write UART1_Write
This macro defines the Custom Name for UART1_Write API.
#define UART1_Drv_IsRxReady UART1_IsRxReady
This macro defines the Custom Name for UART1_IsRxReady API.
#define UART1_Drv_IsTxReady UART1_IsTxReady
This macro defines the Custom Name for UART1_IsTxReady API.
#define UART1_Drv_IsTxDone UART1_IsTxDone
This macro defines the Custom Name for UART1_IsTxDone API.
#define UART1_Drv_TransmitEnable UART1_TransmitEnable
This macro defines the Custom Name for UART1_TransmitEnable API.
#define UART1_Drv_TransmitDisable UART1_TransmitDisable
This macro defines the Custom Name for UART1_TransmitDisable API.
#define UART1_Drv_AutoBaudSet UART1_AutoBaudSet
This macro defines the Custom Name for UART1_AutoBaudSet API.
#define UART1_Drv_AutoBaudQuery UART1_AutoBaudQuery
This macro defines the Custom Name for UART1_AutoBaudQuery API.
#define UART1_Drv_AutoBaudEventEnableGet UART1_AutoBaudEventEnableGet
This macro defines the Custom Name for UART1_AutoBaudEventEnableGet API.
#define UART1_Drv_ErrorGet UART1_ErrorGet
This macro defines the Custom Name for UART1_ErrorGet API.
#define UART1_Drv_BRGCountSet UART1_BRGCountSet
This macro defines the Custom Name for UART1_BRGCountSet API.
#define UART1_Drv_BRGCountGet UART1_BRGCountGet
This macro defines the Custom Name for UART1_BRGCountGet API.
#define UART1_Drv_BaudRateSet UART1_BaudRateSet
This macro defines the Custom Name for UART1_BaudRateSet API.
#define UART1_Drv_BaudRateGet UART1_BaudRateGet
This macro defines the Custom Name for UART1_BaudRateGet API.
#define UART1_Drv_RxCompleteCallbackRegister UART1_RxCompleteCallbackRegister
This macro defines the Custom Name for UART1_RxCompleteCallbackRegister API.
#define UART1_Drv_TxCompleteCallbackRegister UART1_TxCompleteCallbackRegister
This macro defines the Custom Name for UART1_TxCompleteCallbackRegister API.
#define UART1_Drv_TxCollisionCallbackRegister UART1_TxCollisionCallbackRegister
This macro defines the Custom Name for UART1_TxCollisionCallbackRegister API.
#define UART1_Drv_FramingErrorCallbackRegister UART1_FramingErrorCallbackRegister
This macro defines the Custom Name for UART1_FramingErrorCallbackRegister API.
#define UART1_Drv_OverrunErrorCallbackRegister UART1_OverrunErrorCallbackRegister
This macro defines the Custom Name for UART1_OverrunErrorCallbackRegister API.
#define UART1_Drv_ParityErrorCallbackRegister UART1_ParityErrorCallbackRegister
This macro defines the Custom Name for UART1_ParityErrorCallbackRegister API.
3.24.4.1.3 Variables
const struct UART_INTERFACE UART1_Drv
Structure object of type UART_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. UART1 can be changed by the user in the UART user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.
3.24.4.1.4 Detailed Description
This is the generated driver header file for the UART1 driver.
UART1 Generated Driver Header File
3.24.4.2 source/uart_interface.h File Reference
#include <stdbool.h> #include <stdint.h> #include <stddef.h> #include "uart_types.h"
3.24.4.2.1 Data structures
struct UART_INTERFACE
Structure containing the function pointers of UART driver.
3.24.4.2.2 Detailed Description
UART Generated Driver Interface Header File
3.24.4.3 source/uart_types.h File Reference
This is the generated driver types header file for the UART driver.
3.24.4.3.1 Enumerations
enum UART_ERROR_MASKS { UART_ERROR_FRAMING_MASK = 0x1, UART_ERROR_PARITY_MASK = 0x2, UART_ERROR_RX_OVERRUN_MASK = 0x4, UART_ERROR_TX_COLLISION_MASK = 0x8, UART_ERROR_AUTOBAUD_OVERFLOW_MASK = 0x10 }
This Enum can be used to know UART error type using UARTx_ErrorGet function e.g. UART1_ErrorGet.
3.24.4.3.2 Detailed Description
This is the generated driver types header file for the UART driver.
UART Generated Driver Types Header File
3.24.5 Module Documentation
3.24.5.1 UART Use Cases
3.24.5.1.1 UART Use Case Code Snippet Instructions
-
Add UART to the project
-
Configure:
-
The UART as described in the example.
-
Any other peripherals or pins needed for the use case.
-
-
Generate the code
-
Add the code snippet(s) to the application code
-
Program the board
3.24.5.1.2 UART Use Case 1: Printf with Variable Counter
This example uses printf to print: "x Hello World!" to a terminal, where x is a counter.
-
UART:
-
UART Dependency Selection: Select the UART connected to Serial/CDC port.
-
Redirect STDIO to UART (for printf support): Yes
-
-
System > Pins, for all pins check board schematics:
-
Pin Grid View: Select pin for UART Transmit - Tx and Receive - Rx.
-
After configuring the components as described above, click 'Generate' to generate the code. Then add the following code snippets to your application:
This use case prints the following to a terminal:
0. Hello World! 1. Hello World! 2. Hello World! 3. Hello World! 4. Hello World!#include "mcc_generated_files/system/system.h" #include "mcc_generated_files/uart/uart1.h" #include "mcc_generated_files/system/pins.h" #include "string.h" const struct UART_INTERFACE *UartSerial = &UART1_Drv;
/* Add the code snippet to the application code, e.g. main.c */ void UART_Print_Loop(uint8_t count) { uint8_t index; for(index = 0; index < count; index++) { printf("%d. Hello World!\n",index); } }
int main() { SYSTEM_Initialize(); UART_Print_Loop(5); //Function call while(1) { } }
3.24.5.1.3 UART Use Case 2: Write String
Write the string ‘Hello World!’ or any message, by calling UART_String_Write(msg), passing the message to print on the terminal. This can be a light-weight alternative to printf, e.g., for a string of ASCII characters.
-
UART:
-
UART Dependency Selection: Select the UART connected to Serial/CDC port.
-
-
System > Pins, for all pins check board schematics:
-
Pin Grid View: Select pin for UART Transmit - Tx and Receive - Rx.
-
After configuring the components as described above, click 'Generate' to generate the code. Then add the following code snippets to your application:
#include "mcc_generated_files/system/system.h" #include "mcc_generated_files/uart/uart1.h" #include "mcc_generated_files/system/pins.h" #include "string.h" const struct UART_INTERFACE *UartSerial = &UART1_Drv;
char msg[] = "Hello World!\r\n"; void UART_String_Write(const char *msg) { uint8_t index; for(index = 0; index < strlen(msg); index++) { while(!UartSerial->IsTxReady()); UartSerial->Write(msg[index]); } }
int main() { SYSTEM_Initialize(); UART_String_Write(msg); //Function Call while(1) { } }
3.24.5.1.4 UART Use Case 3: Control Commands - Using Interrupt Mode
This example shows how to implement a basic Command Line Interface (CLI) using Interrupt Mode, a popular way of sending control commands to the microcontroller over the UART. LED is controlled using commands from a terminal, e.g., on the MPLAB Data Visualizer.
-
UART:
-
UART Dependency Selection: Select the UART connected to Serial/CDC port.
-
Redirect STDIO to UART (for printf support): Yes
-
Interrupt Driven Mode : Enable
-
-
System > Pins, for all pins check board schematics:
-
Pin Grid View: Select pin for UART Transmit - Tx and Receive - Rx.
-
Pin Grid View: Select LED pin as output.
-
Pins: Rename Custom Name to "LED".
-
After configuring the components as described above, click 'Generate' to generate the code. Then add the following code snippets to your application:
-
Control LED using terminal commands. The commands are case sensitive.
-
Send "ON" to turn the LED.
-
Send "OFF" to turn it off.
-
#include "mcc_generated_files/system/system.h" #include "mcc_generated_files/uart/uart1.h" #include "string.h" #include "mcc_generated_files/system/pins.h" #define MAX_COMMAND_LEN 8 const struct UART_INTERFACE *UartSerial = &UART1_Drv; enum SERIAL_COMMAND { SERIAL_COMMAND_ON = 0, SERIAL_COMMAND_OFF, SERIAL_COMMAND_INVALID, SERIAL_COMMAND_MAX }; bool serial_mutex = false; uint8_t command[MAX_COMMAND_LEN]; uint8_t index = 0; uint8_t read_msg; uint8_t led_status;
void UART_ExecuteCommand(char *command) { if(strcmp(command, "ON") == 0) { LED_SetHigh(); led_status = SERIAL_COMMAND_ON; } else if (strcmp(command, "OFF") == 0) { LED_SetLow(); led_status = SERIAL_COMMAND_OFF; } else { led_status = SERIAL_COMMAND_INVALID; } }
void UART_ProcessCommand_Callback(void) { if(UartSerial->IsRxReady()) { read_msg = UartSerial->Read(); if(read_msg != '\n' && read_msg != '\r') { command[index++] = read_msg; if((index) > MAX_COMMAND_LEN) { (index) = 0; } } if(read_msg == '\n' || read_msg == '\r') { command[index] = '\0'; index = 0; UART_ExecuteCommand(command); serial_mutex = true; } } }
int main(void) { SYSTEM_Initialize(); UartSerial->RxCompleteCallbackRegister(&UART_ProcessCommand_Callback); //Receiver Complete Callback registry printf("In the terminal, send 'ON' to turn the LED on, and 'OFF' to turn it off.\r\n"); printf("Note: commands 'ON' and 'OFF' are case sensitive.\r\n"); while(1) { if(serial_mutex) { switch(led_status) { case SERIAL_COMMAND_ON: printf("OK, LED ON.\r\n"); break; case SERIAL_COMMAND_OFF: printf("OK, LED OFF.\r\n"); break; case SERIAL_COMMAND_INVALID: printf("Incorrect command.\r\n"); break; default: break; } serial_mutex = false; } } }
3.24.5.1.5 UART Use Case 4: Control Commands - Using Polling Mode
This is a continuation of UART Use Case 3 but this time in Polling Mode. Instead of registering interrupt callback for UART_ProcessCommand_Callback, we just modify the main.c as per below given code snippet. Copy the UART_ExecuteCommand, Global variables and defines from the above UART Use Case 3.
-
UART:
-
UART Dependency Selection: Select the UART connected to Serial/CDC port.
-
Redirect STDIO to UART (for printf support): Yes
-
Interrupt Driven Mode : Disabled
-
-
System > Pins, for all pins check board schematics:
-
Pin Grid View: Select pin for UART Transmit - Tx and Receive - Rx.
-
Pin Grid View: Select LED pin as output.
-
Pins: Rename Custom Name to "LED".
-
After configuring the components as described above, click 'Generate' to generate the code. Then add the following code snippets to your application:
-
Control LED using terminal commands. The commands are case sensitive.
-
Send "ON" to turn the LED.
-
Send "OFF" to turn it off.
-
int main(void) { SYSTEM_Initialize(); printf("In the terminal, send 'ON' to turn the LED on, and 'OFF' to turn it off.\r\n"); printf("Note: commands 'ON' and 'OFF' are case sensitive.\r\n"); while(1) { UART_ProcessCommand_Callback(); if(serial_mutex) { switch(led_status) { case SERIAL_COMMAND_ON: printf("OK, LED ON.\r\n"); break; case SERIAL_COMMAND_OFF: printf("OK, LED OFF.\r\n"); break; case SERIAL_COMMAND_INVALID: printf("Incorrect command.\r\n"); break; default: break; } serial_mutex = false; } } }
3.24.5.1.6 UART Use Case 5: Mirror Back Typed Characters
This example demonstrates how to send and receive data byte using UART read and write functions. A catch for a read error, if any, in the received byte is also implemented.
-
UART:
-
UART Dependency Selection: Select the UART connected to Serial/CDC port.
-
Redirect STDIO to UART (for printf support): Yes
-
-
System > Pins, for all pins check board schematics:
-
Pin Grid View: Select pin for UART Transmit - Tx and Receive - Rx.
-
Pins : Transmit pin should be selected as Start High
-
After configuring the components as described above, click 'Generate' to generate the code. Then add the following code snippets to your application:
#include "mcc_generated_files/system/system.h" #include "mcc_generated_files/uart/uart1.h" #include "mcc_generated_files/system/pins.h" #include "string.h" #include "stdio.h" const struct UART_INTERFACE *UartSerial = &UART1_Drv;
/* Echoes back any characters types into terminal. */ void UART_EchoCharacters(void) { if(UartSerial->IsRxReady()) { uint8_t serialCOMRxdByte = 0; serialCOMRxdByte = UartSerial->Read(); size_t stat = UartSerial->ErrorGet(); if((stat == UART_ERROR_TX_COLLISION_MASK) ^ (stat != 0)) { printf("Error %x\r\n",stat); } if(UartSerial->IsTxReady()) { UartSerial->Write(serialCOMRxdByte); } } }
int main(void) { SYSTEM_Initialize(); printf("Hello World!\r\n"); printf("Type characters in the terminal, to have them echoed back ...\r\n"); while(1) { UART_EchoCharacters(); //Function call } }