UART Library

UART hardware module is available with a number of PIC MCUs. mikroBasic 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 :

Library Routines

Generic Routines

UARTx_Init

Prototype

sub procedure UARTx_Init(const baud_rate as longint)

Returns

Nothing.

Description

Configures and initializes the UART module.

The internal UART module module is set to:

  • receiver enabled
  • transmitter enabled
  • frame size 8 bits
  • 1 STOP bit
  • parity mode disabled
  • asynchronous operation

Parameters :

  • baud_rate: requested baud rate

Refer to the device data sheet for baud rates allowed for specific Fosc.

Requires

You'll need PIC MCU with hardware UART.

UARTx_Init needs to be called before using other functions from UART Library.

  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 libary 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

This will initialize hardware UART1 module and establish the communication at 2400 bps:

 'This will initialize hardware UART1 module and establish the communication at 2400 bps
  UART1_Init(2400)

UARTx_Data_Ready

Prototype

sub function UARTx_Data_Ready() as byte

Returns

    Function returns 1 if data is ready or 0 if there is no data.

Description

The function tests if data in receive buffer is ready for reading.

Requires

MCU with the UART module.

The UART module must be initialized before using this routine. See the UARTx_Init routine.

Example
dim receive as byte
...
' read data if ready
if (UART1_Data_Ready() = 1) then
  receive = UART1_Read()
end if

UARTx_Tx_Idle

Prototype

sub function UARTx_Tx_Idle() as byte

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_Idle = 1) then 
  UART1_Write(_data)
end if

UARTx_Read

Prototype

sub function UARTx_Read() as byte

Returns

Received byte.

Description

The function receives a byte via UART. Use the UARTx_Data_Ready function to test if data is ready first.

Requires

MCU with the UART module.

The UART module must be initialized before using this routine. See UARTx_Init routine.

Example
dim receive as byte
...
' read data if ready
if (UART1_Data_Ready() = 1) then
  receive = UART1_Read()

UARTx_Read_Text

Prototype

sub procedure UARTx_Read_Text(dim byref Output as string[255], dim byref Delimiter as string[10], dim Attempts as byte)

Returns

Nothing.

Description

Reads characters received via UART until the delimiter sequence is detected. The read sequence is stored in the parameter output; delimiter sequence is stored in the parameter delimiter.

This is a blocking call: the delimiter sequence is expected, otherwise the procedure exits( if the delimiter is not found). Parameter Attempts defines number of received characters in which Delimiter sequence is expected. If Attempts is set to 255, this routine will continuously try to detect the Delimiter 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 what’s been received:

UART1_Init(4800)                           ' initialize UART module
Delay_ms(100)

 while TRUE
   if (UART1_Data_Ready() = 1)             ' if data is received   
     UART1_Read_Text(output, 'OK', 10)  ' reads text until 'OK' is found
     UART1_Write_Text(output)              ' sends back text 
   end if
 wend.

UARTx_Write

Prototype

sub procedure UARTx_Write(dim TxData as byte)

Returns

Nothing.

Description

The function transmits a byte via the UART module.

Parameters :

  • TxData: data to be sent

Requires

MCU with the UART module.

The UART module must be initialized before using this routine. See UARTx_Init routine.

Example
dim data_ as byte
...
data_ = 0x1E
UART1_Write(data_)

UARTx_Write_Text

Prototype

sub procedure UARTx_Write_Text(dim byref uart_text as string[255])

Returns

Nothing.

Description

Sends text (parameter uart_text) via UART. Text should be zero terminated.

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 what’s been received:

UART1_Init(4800)                           ' initialize UART module
Delay_ms(100)

 while TRUE
   if (UART1_Data_Ready() = 1)             ' if data is received   
     UART1_Read_Text(output, 'OK', 10)  ' reads text until 'OK' is found
     UART1_Write_Text(output)              ' sends back text 
   end if
 wend.

UART_Set_Active

Prototype

sub procedure UART_Set_Active (dim read_ptr as ^Tread_ptr, dim write_ptr as ^Twrite_ptr, dim ready_ptr as ^Tready_ptr, dim tx_idle_ptr as ^Ttx_idle_ptr)

Returns

Nothing.

Description

Sets active UART module which will be used by the UART library routines.

Parameters :

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_Init(9600);                    // initialize UART1 module
UART2_Init(9600);                    // initialize UART2 module

RS485Master_Init();                  // initialize MCU as Master

UART_Set_Active(@UART1_Read, @UART1_Write, @UART1_Data_Ready, @UART1_Tx_Idle); // set UART1 active
RS485Master_Send(dat,1,160);        // send message through UART1

UART_Set_Active(@UART2_Read, @UART2_Write, @UART2_Data_Ready, @UART2_Tx_Idle); // set UART2 active
RS485Master_Send(dat,1,160);        // send through UART2

UART_Data_Ready

Prototype

sub function UART_Data_Ready() as byte

Returns

    Function returns 1 if data is ready or 0 if there is no data.

Description

The function tests 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

MCU with the UART module.

The UART module must be initialized before using this routine. See the UARTx_Init routine.

Example
dim receive as byte
...
' read data if ready
if (UART1_Data_Ready() = 1) then
  receive = UART1_Read()
end if

UART_Tx_Idle

Prototype

sub function UART_Tx_Idle() as byte

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 (UART1_Tx_Idle = 1) then 
  UART1_Write(_data)
end if

UART_Read

Prototype

sub function UART_Read() as byte

Returns

Received byte.

Description

The function receives a byte via UART. Use the UART_Data_Ready function 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

MCU with the UART module.

The UART module must be initialized before using this routine. See UARTx_Init routine.

Example
dim receive as byte
...
' read data if ready
if (UART1_Data_Ready() = 1) then
  receive = UART1_Read()

UART_Read_Text

Prototype

sub procedure UART_Read_Text(dim byref Output as string[255], dim byref Delimiter as string[10], dim Attempts as byte)

Returns

Nothing.

Description

Reads characters received via UART until the delimiter sequence is detected. The read sequence is stored in the parameter output; delimiter sequence is stored in the parameter delimiter.

This is a blocking call: the delimiter sequence is expected, otherwise the procedure exits( if the delimiter is not found). Parameter Attempts defines number of received characters in which Delimiter sequence is expected. If Attempts is set to 255, this routine will continuously try to detect the Delimiter sequence.

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

Read text until the sequence “OK” is received, and send back what’s been received:

UART1_Init(4800)                           ' initialize UART module
Delay_ms(100)

 while TRUE
   if (UART1_Data_Ready() = 1)             ' if data is received   
     UART1_Read_Text(output, 'OK', 10)  ' reads text until 'OK' is found
     UART1_Write_Text(output)              ' sends back text 
   end if
 wend.

UART_Write

Prototype

sub procedure UART_Write(dim TxData as byte)

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 :

  • TxData: data to be sent

Requires

MCU with the UART module.

The UART module must be initialized before using this routine. See UARTx_Init routine.

Example
dim data_ as byte
...
data_ = 0x1E
UART1_Write(data_)

UART_Write_Text

Prototype

sub procedure UART_Write_Text(dim byref uart_text as string[255])

Returns

Nothing.

Description

Sends text (parameter uart_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.

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 what’s been received:

UART1_Init(4800)                           ' initialize UART module
Delay_ms(100)

 while TRUE
   if (UART1_Data_Ready() = 1)             ' if data is received   
     UART1_Read_Text(output, 'OK', 10)  ' reads text until 'OK' is found
     UART1_Write_Text(output)              ' sends back text 
   end if
 wend.

Library Example

This example demonstrates simple data exchange via UART. If MCU is connected to the PC, you can test the example from the mikroBasic PRO for PIC USART Terminal.

Copy Code To ClipboardCopy Code To Clipboard
program UART
dim uart_rd as byte

main:
  UART1_Init(9600)                     ' Initialize UART module at 9600 bps
  Delay_ms(100)                        ' Wait for UART module to stabilize

  UART1_Write_Text("Ready")
  UART1_Write(10)                      ' Line Feed
  UART1_Write(13)                      ' Carriage Return

  while (TRUE)                         ' Endless loop
    if (UART1_Data_Ready() <> 0) then  ' If data is received,
      uart_rd = UART1_Read()           ' read the received data,
      UART1_Write(uart_rd)             ' and send data via UART
    end if
  wend
end.

HW Connection

UART HW connection

UART 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 LibStock - A place for the code