22/09/2016

UARTLibrary

UARTLibrary
mikroCPROforPICLibraries>HardwareLibraries>

UARTLibrary
TheUARThardwaremoduleisavailablewithanumberofPICcompliantMCUs.ThemikroCPROforPICUARTLibrary
providescomfortableworkwiththeAsynchronous(fullduplex)mode.
YoucaneasilycommunicatewithotherdevicesviaRS232protocol(forexamplewithPC,seethefigureattheendofthe
topicRS232HWconnection).YouneedaPICMCUwithhardwareintegratedUART,forexample16F887.Then,simply
usethefunctionslistedbelow.
Important:
UARTlibraryroutinesrequireyoutospecifythemoduleyouwanttouse.ToselectthedesiredUARTmodule,
simplychangetheletterxintheroutineprototypeforanumberfrom1to2.
SwitchingbetweentheUARTmodulesintheUARTlibraryisdonebytheUART_Set_Activefunction(UART
moduleshavetobepreviouslyinitialized).
NumberofUARTmodulesperMCUdiffersfromchiptochip.Please,readtheappropriatedatasheetbefore
utilizingthislibrary.

LibraryRoutines
UARTx_Init
UARTx_Data_Ready
UARTx_Tx_Idle
UARTx_Read
UARTx_Read_Text
UARTx_Write
UARTx_Write_Text
UART_Set_Active

GenericRoutines
UART_Data_Ready
UART_Tx_Idle
UART_Read
UART_Read_Text
UART_Write
UART_Write_Text

UARTx_Init
Prototype

voidUARTx_Init(constunsignedlongbaud_rate)

Returns

Nothing.

Description

InitializesdesiredhardwareUARTmodulewiththedesiredbaudrate.Refertothedevicedatasheet
forbaudratesallowedforspecificFosc.Ifyouspecifytheunsupportedbaudrate,compilerwill
reportanerror.

Requires

YouneedPICMCUwithhardwareUART.
UARTx_InitneedstobecalledbeforeusingotherfunctionsfromUARTLibrary.

http://download.mikroe.com/documents/compilers/mikroc/pic/help/uart_library.htm#uart1_data_ready

1/9

22/09/2016

UARTLibrary

Parameters:
baud_rate:requestedbaudrate

RefertothedevicedatasheetforbaudratesallowedforspecificFosc.
Note:CalculationoftheUARTbaudratevalueiscarriedoutbythecompiler,asitwould
producearelativelylargecodeifperformedonthelibrarylevel.
Therefore,compilerneedstoknowthevalueoftheparameterinthecompiletime.Thatiswhy
thisparameterneedstobeaconstant,andnotavariable.
Example

//InitializehardwareUART1andestablishcommunicationat9600bps
UART1_Init(9600)

UARTx_Data_Ready
Prototype

charUARTx_Data_Ready()

Returns
1ifdataisreadyforreading
0ifthereisnodatainthereceiveregister

Description

Usethefunctiontotestifdatainreceivebufferisreadyforreading.

Requires

UARTHWmodulemustbeinitializedandcommunicationestablishedbeforeusingthisfunction.See
UARTx_Init.

Example

//Ifdataisready,readit:
if(UART1_Data_Ready()==1){
receive=UART1_Read()
}

UARTx_Tx_Idle
Prototype

Returns

charUARTx_Tx_Idle()

1ifthedatahasbeentransmitted
0otherwise

Description

Usethefunctiontotestifthetransmitshiftregisterisemptyornot.

Requires

UARTHWmodulemustbeinitializedandcommunicationestablishedbeforeusingthisfunction.See
UARTx_Init.

Example

//Ifthepreviousdatahasbeenshiftedout,sendnextdata:
if(UART1_Tx_Idle()==1){
UART1_Write(_data)
}

http://download.mikroe.com/documents/compilers/mikroc/pic/help/uart_library.htm#uart1_data_ready

2/9

22/09/2016

UARTLibrary

UARTx_Read
Prototype

charUARTx_Read()

Returns

Returnsthereceivedbyte.

Description

FunctionreceivesabyteviaUART.UsethefunctionUARTx_Data_Readytotestifdataisreadyfirst.

Requires

UARTHWmodulemustbeinitializedandcommunicationestablishedbeforeusingthisfunction.See
UARTx_Init.

Example

//Ifdataisready,readit:
if(UART1_Data_Ready()==1){
receive=UART1_Read()
}

UARTx_Read_Text
Prototype

voidUARTx_Read_Text(char*Output,char*Delimiter,charAttempts)

Returns

Nothing.

Description

ReadscharactersreceivedviaUARTuntilthedelimitersequenceisdetected.Thereadsequenceis
storedintheparameteroutputdelimitersequenceisstoredintheparameterdelimiter.
Thisisablockingcall:thedelimitersequenceisexpected,otherwisetheprocedureexits(ifthe
delimiterisnotfound).
Parameters:
Output:receivedtext
Delimiter:sequenceofcharactersthatidentifiestheendofareceivedstring
Attempts:definesnumberofreceivedcharactersinwhichDelimitersequenceisexpected.
IfAttemptsissetto255,thisroutinewillcontinuouslytrytodetecttheDelimitersequence.

Requires

UARTHWmodulemustbeinitializedandcommunicationestablishedbeforeusingthisfunction.See
UARTx_Init.

Example

ReadtextuntilthesequenceOKisreceived,andsendbackwhatsbeenreceived:
UART1_Init(4800)//initializeUART1module
Delay_ms(100)
while(1){
if(UART1_Data_Ready()==1){//ifdataisreceived
UART1_Read_Text(output,"OK",10)//readstextuntil'OK'isfound
UART1_Write_Text(output)//sendsbacktext
}
}

UARTx_Write
http://download.mikroe.com/documents/compilers/mikroc/pic/help/uart_library.htm#uart1_data_ready

3/9

22/09/2016

UARTLibrary

Prototype

voidUARTx_Write(chardata_)

Returns

Nothing.

Description

ThefunctiontransmitsabyteviatheUARTmodule.
Parameters:
_data:datatobesent

Requires

UARTHWmodulemustbeinitializedandcommunicationestablishedbeforeusingthisfunction.See
UARTx_Init.

Example

unsignedchar_data=0x1E
...
UART1_Write(_data)

UARTx_Write_Text
Prototype

voidUARTx_Write_Text(char*UART_text)

Returns

Nothing.

Description

SendstextviaUART.Textshouldbezeroterminated.
Parameters:
UART_text:texttobesent

Requires

UARTHWmodulemustbeinitializedandcommunicationestablishedbeforeusingthisfunction.See
UARTx_Init.

Example

ReadtextuntilthesequenceOKisreceived,andsendbackwhatsbeenreceived:
UART1_Init(4800)//initializeUART1module
Delay_ms(100)
while(1){
if(UART1_Data_Ready()==1){//ifdataisreceived
UART1_Read_Text(output,"OK",10)//readstextuntil'OK'isfound
UART1_Write_Text(output)//sendsbacktext
}
}

UART_Set_Active
Prototype

voidUART_Set_Active(char(*read_ptr)(),void(*write_ptr)(unsignedchardata_),char
(*ready_ptr)(),char(*tx_idle_ptr)())

Returns

Nothing.

http://download.mikroe.com/documents/compilers/mikroc/pic/help/uart_library.htm#uart1_data_ready

4/9

22/09/2016

Description

UARTLibrary

SetsactiveUARTmodulewhichwillbeusedbytheUARTlibraryroutines.
Parameters:
read_ptr:UARTx_Readhandler
write_ptr:UARTx_Writehandler
ready_ptr:UARTx_Data_Readyhandler
tx_idle_ptr:UARTx_Tx_Idlehandler

Requires

RoutineisavailableonlyforMCUswithtwoUARTmodules.
UsedUARTmodulemustbeinitializedbeforeusingthisroutine.SeeUARTx_Initroutine

Example

UART1_Init(9600)//initializeUART1module
UART2_Init(9600)//initializeUART2module
RS485Master_Init()//initializeMCUasMaster
UART_Set_Active(&UART1_Read,&UART1_Write,&UART1_Data_Ready,&UART1_Tx_Idle)//setUART1active
RS485Master_Send(dat,1,160)//sendmessagethroughUART1
UART_Set_Active(&UART2_Read,&UART2_Write,&UART2_Data_Ready,&UART2_Tx_Idle)//setUART2active
RS485Master_Send(dat,1,160)//sendthroughUART2

UART_Data_Ready
Prototype

Returns

Description

charUART_Data_Ready()

1ifdataisreadyforreading
0ifthereisnodatainthereceiveregister

Usethefunctiontotestifdatainreceivebufferisreadyforreading.
ThisisagenericroutinewhichusestheactiveUARTmodulepreviouslyactivatedbythe
UART_Set_Activeroutine.

Requires

UARTHWmodulemustbeinitializedandcommunicationestablishedbeforeusingthisfunction.See
UARTx_Init.

Example

//Ifdataisready,readit:
if(UART_Data_Ready()==1){
receive=UART_Read()
}

UART_Tx_Idle
Prototype

charUART_Tx_Idle()

Returns
1ifthedatahasbeentransmitted
0otherwise
http://download.mikroe.com/documents/compilers/mikroc/pic/help/uart_library.htm#uart1_data_ready

5/9

22/09/2016

Description

UARTLibrary

Usethefunctiontotestifthetransmitshiftregisterisemptyornot.
ThisisagenericroutinewhichusestheactiveUARTmodulepreviouslyactivatedbythe
UART_Set_Activeroutine.

Requires

UARTHWmodulemustbeinitializedandcommunicationestablishedbeforeusingthisfunction.See
UARTx_Init.

Example

//Ifthepreviousdatahasbeenshiftedout,sendnextdata:
if(UART_Tx_Idle()==1){
UART_Write(_data)
}

UART_Read
Prototype

charUART_Read()

Returns

Returnsthereceivedbyte.

Description

FunctionreceivesabyteviaUART.UsethefunctionUART_Data_Readytotestifdataisreadyfirst.
ThisisagenericroutinewhichusestheactiveUARTmodulepreviouslyactivatedbythe
UART_Set_Activeroutine.

Requires

UARTHWmodulemustbeinitializedandcommunicationestablishedbeforeusingthisfunction.See
UARTx_Init.

Example

//Ifdataisready,readit:
if(UART_Data_Ready()==1){
receive=UART_Read()
}

UART_Read_Text
Prototype

voidUART_Read_Text(char*Output,char*Delimiter,charAttempts)

Returns

Nothing.

Description

ReadscharactersreceivedviaUARTuntilthedelimitersequenceisdetected.Thereadsequenceis
storedintheparameteroutputdelimitersequenceisstoredintheparameterdelimiter.
Thisisablockingcall:thedelimitersequenceisexpected,otherwisetheprocedureexits(ifthe
delimiterisnotfound).
ThisisagenericroutinewhichusestheactiveUARTmodulepreviouslyactivatedbythe
UART_Set_Activeroutine.
Parameters:
Output:receivedtext
Delimiter:sequenceofcharactersthatidentifiestheendofareceivedstring
Attempts:definesnumberofreceivedcharactersinwhichDelimitersequenceisexpected.
IfAttemptsissetto255,thisroutinewillcontinuouslytrytodetecttheDelimitersequence.

http://download.mikroe.com/documents/compilers/mikroc/pic/help/uart_library.htm#uart1_data_ready

6/9

22/09/2016

UARTLibrary

Requires

UARTHWmodulemustbeinitializedandcommunicationestablishedbeforeusingthisfunction.See
UARTx_Init.

Example

ReadtextuntilthesequenceOKisreceived,andsendbackwhatsbeenreceived:
UART1_Init(4800)//initializeUART1module
Delay_ms(100)
while(1){
if(UART_Data_Ready()==1){//ifdataisreceived
UART_Read_Text(output,"OK",10)//readstextuntil'OK'isfound
UART_Write_Text(output)//sendsbacktext
}
}

UART_Write
Prototype

voidUART_Write(chardata_)

Returns

Nothing.

Description

ThefunctiontransmitsabyteviatheUARTmodule.
ThisisagenericroutinewhichusestheactiveUARTmodulepreviouslyactivatedbythe
UART_Set_Activeroutine.
Parameters:
_data:datatobesent

Requires

UARTHWmodulemustbeinitializedandcommunicationestablishedbeforeusingthisfunction.See
UARTx_Init.

Example

unsignedchar_data=0x1E
...
UART_Write(_data)

UART_Write_Text
Prototype

voidUART_Write_Text(char*UART_text)

Returns

Nothing.

Description

SendstextviaUART.Textshouldbezeroterminated.
ThisisagenericroutinewhichusestheactiveUARTmodulepreviouslyactivatedbythe
UART_Set_Activeroutine.
Parameters:
UART_text:texttobesent

http://download.mikroe.com/documents/compilers/mikroc/pic/help/uart_library.htm#uart1_data_ready

7/9

22/09/2016

UARTLibrary

Requires

UARTHWmodulemustbeinitializedandcommunicationestablishedbeforeusingthisfunction.See
UARTx_Init.

Example

ReadtextuntilthesequenceOKisreceived,andsendbackwhatsbeenreceived:
UART1_Init(4800)//initializeUART1module
Delay_ms(100)
while(1){
if(UART_Data_Ready()==1){//ifdataisreceived
UART_Read_Text(output,"OK",10)//readstextuntil'OK'isfound
UART_Write_Text(output)//sendsbacktext
}
}

LibraryExample
TheexampledemonstratesasimpledataexchangeviaUART.WhenPICMCUreceivesdata,itimmediatelysendsitback.
IfPICisconnectedtothePC(seethefigurebelow),youcantesttheexamplefromthemikroCPROforPICterminalfor
RS232communication,menuchoiceToolsTerminal.
CopyCodeToClipboard

charuart_rd
voidmain(){
ANSEL=0//ConfigureANpinsasdigital
ANSELH=0

UART1_Init(9600)//InitializeUARTmoduleat9600bps
Delay_ms(100)//WaitforUARTmoduletostabilize

UART1_Write_Text("Start")
UART1_Write(10)
UART1_Write(13)

while(1){//Endlessloop
if(UART1_Data_Ready()){//Ifdataisreceived,
uart_rd=UART1_Read()//readthereceiveddata,
UART1_Write(uart_rd)//andsenddataviaUART
}
}
}

HWConnection

http://download.mikroe.com/documents/compilers/mikroc/pic/help/uart_library.htm#uart1_data_ready

8/9

22/09/2016

UARTLibrary

RS232HWconnection

Copyright(c)20022012mikroElektronika.Allrightsreserved.
Whatdoyouthinkaboutthistopic?Sendusfeedback!

http://download.mikroe.com/documents/compilers/mikroc/pic/help/uart_library.htm#uart1_data_ready

Wantmoreexamplesandlibraries?
Findthemon

9/9