UART Library

UART hardware module is available with a number of AVR MCUs. mikroBasic PRO for AVR 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 AVR MCU with hardware integrated UART, for example ATmega16. Then, simply use the functions listed below.

Important :

AVR MCUs require you to specify the module you want to use. To select the desired UART, simply change the letter x in the prototype for a number from 1 to 4. Number of UART modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.
For the XMEGA family of MCUs change the X in the routine prototype with C0, C1, D0, D1, E0, E1, F0 or F1 (MCU dependent).
Some of the AVR MCUs do not support UARTx_Init_Advanced routine. Please, refer to the appropriate datasheet.
Some AVR MCUs have multiple UART modules. Switching between the UART modules in the UART library is done by the UART_Set_Active function (UART module has to be previously initialized).

Generic Routines

UART_Data_Ready
UART_Tx_Idle
UART_Read
UART_Read_Text
UART_Write
UART_Write_Text

UARTx_Init

Prototype	sub procedure UARTx_Init(dim 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. 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. Also, UART baud rate it is calculated under assumption that peripheral clock is equal to the system clock.
Requires	You'll need AVR MCU with hardware UART. `UARTx_Init` needs to be called before using other functions from UART Library.
Example	' Initialize hardware UART1 and establish communication at 9600 bps UART1_Init(9600)

UARTx_Init_Advanced

Prototype

sub procedure UARTx_Init_Advanced(dim baud_rate as longword, dim parity as byte, dim stop_bits as byte)

Returns

Nothing.

Description

Configures and initializes UART module.

Parameter baud_rate configures UART module to work on a requested baud rate.
Parameters parity and stop_bits determine the work mode for UART, and can have the following values:

Description	Predefined library const
Parity constants:
`Parity mode disabled`	`_UART_NOPARITY`
`Even parity`	`_UART_EVENPARITY`
`Odd parity`	`_UART_ODDPARITY`
Stop bit constants:
`1 stop bit`	`_UART_ONE_STOPBIT`
`2 stop bits`	`_UART_TWO_STOPBITS`

Note :

Some MCUs do not support advanced configuration of the UART module. Please consult appropriate daatsheet.
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.
Also, UART baud rate it is calculated under assumption that peripheral clock is equal to the system clock.

Requires

MCU must have UART module.

Example

' Initialize hardware UART1 module and establish communication at 9600 bps, 8-bit data, even parity and 2 STOP bits 
UART1_Init_Advanced(9600, _UART_EVENPARITY, _UART_TWO_STOPBITS)

UARTx_Data_Ready

Prototype	sub function UARTx_Data_Ready() as byte
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.
Requires	UART HW module must be initialized and communication established before using this function. See UARTx_Init.
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 UART1_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	Returns the received byte.
Description	The function receives a byte via UART. Use the UARTx_Data_Ready function to test if data is ready first.
Requires	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). Parameters : `Output:` received text `Delimiter:` sequence of characters that identifies the end of a received string `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 data_ as byte)
Returns	Nothing.
Description	The function transmits a byte via the UART module. Parameters : `data_:` 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 via UART. Text should be zero terminated. Parameters : `UART_text:` 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 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 : `read_ptr:` UARTx_Read handler `write_ptr:` UARTx_Write handler `ready_ptr:` UARTx_Data_Ready handler `tx_idle_ptr:` UARTx_Tx_Idle handler
Requires	Routine is available only for MCUs with multiple 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	`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	dim receive as byte ... ' read data if ready if (UART_Data_Ready() = 1) then receive = UART_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 (UART_Tx_Idle() <> 0) begin ... end;

UART_Read

Prototype	sub function UART_Read() as byte
Returns	Returns the received byte. This is a generic routine which uses the active UART module previously activated by the UART_Set_Active routine.
Description	Function receives a byte via UART. Use the UART_Data_Ready function to test if data is ready first.
Requires	The UART module must be initialized before using this routine. See UARTx_Init routine.
Example	dim receive as byte ... ' read data if ready if (UART_Data_Ready() = 1) then receive = UART_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). Parameters : `Output:` received text `Delimiter:` sequence of characters that identifies the end of a received string `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 (UART_Data_Ready() = 1) ' if data is received UART_Read_Text(output, 'OK', 10) ' reads text until 'OK' is found UART_Write_Text(output) ' sends back text end if wend.

UART_Write

Prototype	sub procedure UART_Write(dim data_ as byte)
Returns	Nothing.
Description	The function transmits a byte via the UART module. Parameters : `data_:` data to be sent 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 data_ as byte ... data_ = 0x1E UART_Write(data_)

UART_Write_Text

Prototype	sub procedure UART_Write_Text(dim byref uart_text as string[255])
Returns	Nothing.
Description	Sends text via UART. Text should be zero terminated. Parameters : `UART_text:` text to be sent 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 (UART_Data_Ready() = 1) ' if data is received UART_Read_Text(output, 'OK', 10) ' reads text until 'OK' is found UART_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 AVR USART Terminal.

Copy Code To Clipboard

program UART
dim uart_rd as byte

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

  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

Want more examples and libraries?
Find them on