UART Library

mikroC PRO for PIC Libraries > Hardware Libraries >

UART Library
The UART hardware module is available with a number of PIC compliant MCUs. The mikroC PRO for PIC UART Library provides comfortable work with the
Asynchronous (full duplex) mode.
You can easily communicate with other devices via RS-232 protocol (for example with PC, see the figure at the end of the topic RS-232 HW connection). You
need a PIC MCU with hardware integrated UART, for example 16F887. Then, simply use the functions listed below.
Important :
UART library routines require you to specify the module you want to use. To select the desired UART module, simply change the letter x in the
routine prototype for a number from 1 to 2.
Switching between the UART modules in the UART library is done by the UART_Set_Active function (UART modules have to be previously
initialized).
Number of UART modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.
Library Routines
UARTx_Init
UARTx_Data_Ready
UARTx_Tx_Idle
UARTx_Read
UARTx_Read_Text
UARTx_Write
UARTx_Write_Text
UART_Set_Active
Generic Routines
UART_Data_Ready
UART_Tx_Idle
UART_Read
UART_Read_Text
UART_Write
UART_Write_Text
UARTx_Init
UARTx_Data_Ready
Prototype void UARTx_I ni t ( const unsigned long baud_r at e) ;
Returns Nothing.
Description Initializes desired hardware UART module with the desired baud rate. Refer to the device data sheet for baud rates allowed for specific
Fosc. If you specify the unsupported baud rate, compiler will report an error.
Requires You need PIC MCU with hardware UART.
UARTx_I ni t needs to be called before using other functions from UART Library.
Parameters :
baud_r at e: requested baud rate
Refer to the device data sheet for baud rates allowed for specific Fosc.
Note : Calculation of the UART baud rate value is carried out by the compiler, as it would produce a relatively large code if
performed on the library level.
Therefore, compiler needs to know the value of the parameter in the compile time. That is why this parameter needs to be a constant,
and not a variable.
Example // Initialize hardware UART1 and establish communication at 9600 bps
UART1_I ni t ( 9600) ;
Prototype char UARTx_Dat a_Ready( ) ;
Returns
1 if data is ready for reading
0 if there is no data in the receive register
Page 1of 6 UART Library
25-Apr-14 mk:@MSITStore:C:\Users\Public\Documents\Mikroelektronika\mikroC%20PRO%20for...
UARTx_Tx_Idle
UARTx_Read
UARTx_Read_Text
UARTx_Write
Description Use the function to test if data in receive buffer is ready for reading.
Requires UART HW module must be initialized and communication established before using this function. See UARTx_Init.
Example // If data is ready, read it:
if ( UART1_Dat a_Ready( ) == 1) {
r ecei ve = UART1_Read( ) ;
}
Prototype char UARTx_Tx_I dl e( ) ;
Returns
1 if the data has been transmitted
0 otherwise
Description Use the function to test if the transmit shift register is empty or not.
Requires UART HW module must be initialized and communication established before using this function. See UARTx_Init.
Example // If the previous data has been shifted out, send next data:
if ( UART1_Tx_I dl e( ) == 1) {
UART1_Wr i t e( _dat a) ;
}
Prototype char UARTx_Read( ) ;
Returns Returns the received byte.
Description Function receives a byte via UART. Use the function UARTx_Data_Ready to test if data is ready first.
Requires UART HW module must be initialized and communication established before using this function. See UARTx_Init.
Example // If data is ready, read it:
if ( UART1_Dat a_Ready( ) == 1) {
r ecei ve = UART1_Read( ) ;
}
Prototype void UARTx_Read_Text ( char *Out put , char *Del i mi t er , char At t empt s) ;
Returns Nothing.
Description Reads characters received via UART until the delimiter sequence is detected. The read sequence is stored in the parameter out put ;
delimiter sequence is stored in the parameter del i mi t er .
This is a blocking call: the delimiter sequence is expected, otherwise the procedure exits (if the delimiter is not found).
Parameters :
Out put : received text
Del i mi t er : sequence of characters that identifies the end of a received string
At t empt s: defines number of received characters in which Del i mi t er sequence is expected. If At t empt s is set to 255, this routine
will continuously try to detect the Del i mi t er sequence.
Requires UART HW module must be initialized and communication established before using this function. See UARTx_Init.
Example Read text until the sequence OK is received, and send back whats been received:
UART1_I ni t ( 4800) ; / / initialize UART1 module
Del ay_ms( 100) ;

while ( 1) {
if ( UART1_Dat a_Ready( ) == 1) { / / if data is received
UART1_Read_Text ( out put , " OK" , 10) ; / / reads text until 'OK' is found
UART1_Wr i t e_Text ( out put ) ; / / sends back text
}
}
Prototype
Page 2of 6 UART Library
25-Apr-14 mk:@MSITStore:C:\Users\Public\Documents\Mikroelektronika\mikroC%20PRO%20for...
UARTx_Write_Text
UART_Set_Active
UART_Data_Ready
void UARTx_Wr i t e( char dat a_) ;
Returns Nothing.
Description The function transmits a byte via the UART module.
Parameters :
_dat a: data to be sent
Requires UART HW module must be initialized and communication established before using this function. See UARTx_Init.
Example unsigned char _dat a = 0x1E;
. . .
UART1_Wr i t e( _dat a) ;
Prototype void UARTx_Wr i t e_Text ( char * UART_t ext ) ;
Returns Nothing.
Description Sends text via UART. Text should be zero terminated.
Parameters :
UART_t ext : text to be sent
Requires UART HW module must be initialized and communication established before using this function. See UARTx_Init.
Example Read text until the sequence OK is received, and send back whats been received:
UART1_I ni t ( 4800) ; / / initialize UART1 module
Del ay_ms( 100) ;

while ( 1) {
if ( UART1_Dat a_Ready( ) == 1) { / / if data is received
UART1_Read_Text ( out put , " OK" , 10) ; / / reads text until 'OK' is found
UART1_Wr i t e_Text ( out put ) ; / / sends back text
}
}
Prototype void UART_Set _Act i ve( char ( *r ead_pt r ) ( ) , void ( *wr i t e_pt r ) ( unsigned char dat a_) , char ( *r eady_pt r ) ( ) , char
( *t x_i dl e_pt r ) ( ) )
Returns Nothing.
Description Sets active UART module which will be used by the UART library routines.
Parameters :
r ead_pt r : UARTx_Read handler
wr i t e_pt r : UARTx_Write handler
r eady_pt r : UARTx_Data_Ready handler
t x_i dl e_pt r : UARTx_Tx_Idle handler
Requires Routine is available only for MCUs with two UART modules.
Used UART module must be initialized before using this routine. See UARTx_Init routine
Example UART1_I ni t ( 9600) ; // initialize UART1 module
UART2_I ni t ( 9600) ; // initialize UART2 module

RS485Mast er _I ni t ( ) ; // initialize MCU as Master

UART_Set _Act i ve( &UART1_Read, &UART1_Wr i t e, &UART1_Dat a_Ready, &UART1_Tx_I dl e) ; // set UART1 active
RS485Mast er _Send( dat , 1, 160) ; // send message through UART1

UART_Set _Act i ve( &UART2_Read, &UART2_Wr i t e, &UART2_Dat a_Ready, &UART2_Tx_I dl e) ; // set UART2 active
RS485Mast er _Send( dat , 1, 160) ; // send through UART2
Prototype char UART_Dat a_Ready( ) ;
Page 3of 6 UART Library
25-Apr-14 mk:@MSITStore:C:\Users\Public\Documents\Mikroelektronika\mikroC%20PRO%20for...
UART_Tx_Idle
UART_Read
UART_Read_Text
Returns
1 if data is ready for reading
0 if there is no data in the receive register
Description Use the function to test if data in receive buffer is ready for reading.
This is a generic routine which uses the active UART module previously activated by the UART_Set_Active routine.
Requires UART HW module must be initialized and communication established before using this function. See UARTx_Init.
Example // If data is ready, read it:
if ( UART_Dat a_Ready( ) == 1) {
r ecei ve = UART_Read( ) ;
}
Prototype char UART_Tx_I dl e( ) ;
Returns
1 if the data has been transmitted
0 otherwise
Description Use the function to test if the transmit shift register is empty or not.
This is a generic routine which uses the active UART module previously activated by the UART_Set_Active routine.
Requires UART HW module must be initialized and communication established before using this function. See UARTx_Init.
Example // If the previous data has been shifted out, send next data:
if ( UART_Tx_I dl e( ) == 1) {
UART_Wr i t e( _dat a) ;
}
Prototype char UART_Read( ) ;
Returns Returns the received byte.
Description Function receives a byte via UART. Use the function UART_Data_Ready to test if data is ready first.
This is a generic routine which uses the active UART module previously activated by the UART_Set_Active routine.
Requires UART HW module must be initialized and communication established before using this function. See UARTx_Init.
Example // If data is ready, read it:
if ( UART_Dat a_Ready( ) == 1) {
r ecei ve = UART_Read( ) ;
}
Prototype void UART_Read_Text ( char *Out put , char *Del i mi t er , char At t empt s) ;
Returns Nothing.
Description Reads characters received via UART until the delimiter sequence is detected. The read sequence is stored in the parameter out put ;
delimiter sequence is stored in the parameter del i mi t er .
This is a blocking call: the delimiter sequence is expected, otherwise the procedure exits (if the delimiter is not found).
This is a generic routine which uses the active UART module previously activated by the UART_Set_Active routine.
Parameters :
Out put : received text
Del i mi t er : sequence of characters that identifies the end of a received string
At t empt s: defines number of received characters in which Del i mi t er sequence is expected. If At t empt s is set to 255, this routine
will continuously try to detect the Del i mi t er sequence.
Requires UART HW module must be initialized and communication established before using this function. See UARTx_Init.
Example Read text until the sequence OK is received, and send back whats been received:
UART1_I ni t ( 4800) ; / / initialize UART1 module
Del ay_ms( 100) ;

Page 4of 6 UART Library
25-Apr-14 mk:@MSITStore:C:\Users\Public\Documents\Mikroelektronika\mikroC%20PRO%20for...
UART_Write
UART_Write_Text
Library Example
The example demonstrates a simple data exchange via UART. When PIC MCU receives data, it immediately sends it back. If PIC is connected to the PC (see the
figure below), you can test the example from the mikroC PRO for PIC terminal for RS-232 communication, menu choice Tools Terminal.
char uar t _r d;

void mai n( ) {
ANSEL = 0; // Configure AN pins as digital
ANSELH = 0;

UART1_I ni t ( 9600) ; // Initialize UART module at 9600 bps
Del ay_ms( 100) ; // Wait for UART module to stabilize

UART1_Wr i t e_Text ( " St ar t " ) ;
UART1_Wr i t e( 10) ;
UART1_Wr i t e( 13) ;

while ( 1) { // Endless loop
if ( UART1_Dat a_Ready( ) ) { // If data is received,
uar t _r d = UART1_Read( ) ; // read the received data,
while ( 1) {
if ( UART_Dat a_Ready( ) == 1) { / / if data is received
UART_Read_Text ( out put , " OK" , 10) ; / / reads text until 'OK' is found
UART_Wr i t e_Text ( out put ) ; / / sends back text
}
}
Prototype void UART_Wr i t e( char dat a_) ;
Returns Nothing.
Description The function transmits a byte via the UART module.
This is a generic routine which uses the active UART module previously activated by the UART_Set_Active routine.
Parameters :
_dat a: data to be sent
Requires UART HW module must be initialized and communication established before using this function. See UARTx_Init.
Example unsigned char _dat a = 0x1E;
. . .
UART_Wr i t e( _dat a) ;
Prototype void UART_Wr i t e_Text ( char * UART_t ext ) ;
Returns Nothing.
Description Sends text via UART. Text should be zero terminated.
This is a generic routine which uses the active UART module previously activated by the UART_Set_Active routine.
Parameters :
UART_t ext : text to be sent
Requires UART HW module must be initialized and communication established before using this function. See UARTx_Init.
Example Read text until the sequence OK is received, and send back whats been received:
UART1_I ni t ( 4800) ; / / initialize UART1 module
Del ay_ms( 100) ;

while ( 1) {
if ( UART_Dat a_Ready( ) == 1) { / / if data is received
UART_Read_Text ( out put , " OK" , 10) ; / / reads text until 'OK' is found
UART_Wr i t e_Text ( out put ) ; / / sends back text
}
}

Copy Code To Clipboard
Page 5of 6 UART Library
25-Apr-14 mk:@MSITStore:C:\Users\Public\Documents\Mikroelektronika\mikroC%20PRO%20for...
UART1_Wr i t e( uar t _r d) ; // and send data via UART
}
}
}
HW Connection

RS-232 HW connection
Copyright (c) 2002-2012 mikroElektronika. All rights reserved.
What do you think about this topic ? Send us feedback!
Want more examples and libraries?
Find them on
Page 6of 6 UART Library
25-Apr-14 mk:@MSITStore:C:\Users\Public\Documents\Mikroelektronika\mikroC%20PRO%20for...