UART Library
  mikroBasic PRO for ARM Libraries > Hardware Libraries > 
  

UART Library

The UART hardware module is available with a number of ARM MCUs. The mikroBasic PRO for ARM UART Library provides comfortable work with the Asynchronous (full duplex) mode.

  Important :

Library Routines

Generic Routines

UARTx_Init

Prototype

sub procedure UARTx_Init(dim baud_rate as longword)
Description

Configures and initializes the UART module.

The internal UART module module is set to :

  • default Tx and Rx pins.
  • 8-bit data, no parity.
  • 1 STOP bit.
Parameters
  • baud_rate: requested baud rate.
Returns

Nothing.
Requires

Routine requires the UART module.
Example 
' Initialize hardware UART1 module and establish communication at 2400 bps
UART1_Init(2400)
Notes
  • Refer to the device data sheet for baud rates allowed for specific peripheral clock values.
  • 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 0 to 7.
  • 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.

Stellaris

  • For MCUs with alternative PORT functions on GPIO pins, UART modules can be set on the following pins. :
    • UART0 - PA0/PA1,
    • UART1 - PB0/PB1, PB4/PB5, PC6/PC7, PD2/PD3,
    • UART2 - PB4/E4, PD0/PD1, PG0/PG1,
  • The compiler will choose for which speed the calculation is to be performed (high or low). This does not mean that it is the best choice for desired baud rate.
    If the baud rate error generated in this way is too big then UARTx_Init_Advanced routine, which allows speed select, should be used.

STM32

  • UART modules can be set on the following pins :
    • UART1 - PA9/PA10,
    • UART2 - PA2/PA3,
    • UART3 - PB10/PB11,
    • UART4 - PC10/PC11,
    • UART5 - PC12/PD2,
    • UART6 - PC6/PC7.

UARTx_Init_Advanced

Prototype ' for Stellaris MCUs :

sub procedure UARTx_Init_Advanced(dim baud_rate as longword, dim freq_Khz as longword, dim data_bits as word, dim parity as word, dim stop_bits as word, dim high_low as word)

' for MCUs with alternative PORT functions on GPIO pins :

sub procedure UARTx_Init_Advanced(dim baud_rate as longword, dim freq_Khz as longword, dim data_bits as word, dim parity as word, dim stop_bits as word, dim high_low as word, dim module as ^const Module_Struct);

' for ST MCUs :

sub procedure UARTx_Init_Advanced(dim baud_rate as longword, dim data_bits as word, dim parity as word, dim stop_bits as word, dim high_low as word dim module as ^const Module_Struct)
Description

Configures and initializes the UART module with user defined settings.
Parameters

Stellaris

  • baud_rate: Requested baud rate.
  • freq_Khz: Peripheral Bus Clock frequency in kHz.
  • data_bits: Data bits selection parameter. Valid values :

    Data Bits
    Description Predefined library const
    5 data bits _UART_5_BIT_DATA
    6 data bits _UART_6_BIT_DATA
    7 data bits _UART_7_BIT_DATA
    8 data bits _UART_8_BIT_DATA

  • parity: Parity selection parameter. Valid values :

    Parity Mode
    Description Predefined library const
    No parity _UART_NOPARITY
    Even parity _UART_EVENPARITY
    Odd parity _UART_ODDPARITY
    Parity bit is one _UART_PARITY_ONE
    Parity bit is zero _UART_PARITY_ZERO

  • stop_bits: Stop bit selection parameter. Valid values :

    Stop bits
    Description Predefined library const
    One stop bit _UART_ONE_STOPBIT
    Two stop bit _UART_TWO_STOPBITS

  • high_low: High/low speed selection parameter. Valid values :

    High/Low Speed
    Description Predefined library const
    Low Speed UART _UART_LOW_SPEED
    Hi Speed UART _UART_HI_SPEED

  • module: appropriate module pinout, see the following table :

    UART Module Pinouts for Stellaris Cortex M3
    UART0 _GPIO_MODULE_UART0_A01
    UART1 _GPIO_MODULE_UART1_A01 _GPIO_MODULE_UART1_B01 _GPIO_MODULE_UART1_B45 _GPIO_MODULE_UART1_C67 _GPIO_MODULE_UART1_D01 _GPIO_MODULE_UART1_D23
    UART2 _GPIO_MODULE_UART2_D01 _GPIO_MODULE_UART2_D56 _GPIO_MODULE_UART2_G01

    UART Module Pinouts for Stellaris Cortex M4
    UART0 _GPIO_MODULE_UART0_A01_AHB
    UART1 _GPIO_MODULE_UART1_B01_AHB _GPIO_MODULE_UART1_C45_AHB
    UART2 _GPIO_MODULE_UART2_D67_AHB _GPIO_MODULE_UART2_G45_AHB
    UART3 _GPIO_MODULE_UART3_C67_AHB
    UART4 _GPIO_MODULE_UART4_C45_AHB _GPIO_MODULE_UART4_J01_AHB
    UART5 _GPIO_MODULE_UART5_E45_AHB _GPIO_MODULE_UART5_J23_AHB
    UART6 _GPIO_MODULE_UART6_D45_AHB _GPIO_MODULE_UART6_J45_AHB
    UART7 _GPIO_MODULE_UART7_E01_AHB _GPIO_MODULE_UART7_K45_AHB

STM32

  • baud_rate: Requested baud rate.
  • data_bits: Data bits selection parameter. Valid values :

    Data Bits
    Description Predefined library const
    5 data bits _UART_5_BIT_DATA
    6 data bits _UART_6_BIT_DATA
    7 data bits _UART_7_BIT_DATA
    8 data bits _UART_8_BIT_DATA
    9 data bits _UART_9_BIT_DATA

  • parity: Parity selection parameter. Valid values :

    Parity Mode
    Description Predefined library const
    No parity _UART_NOPARITY
    Even parity _UART_EVENPARITY
    Odd parity _UART_ODDPARITY
    Parity bit is one _UART_PARITY_ONE
    Parity bit is zero _UART_PARITY_ZERO

  • stop_bits: Stop bit selection parameter. Valid values :

    Stop bits
    Description Predefined library const
    Half stop bit _UART_HALF_STOPBIT
    One stop bit _UART_ONE_STOPBIT
    One and a half stop bits _UART_ONE_AND_A_HALF_STOPBITS
    Two stop bit _UART_TWO_STOPBITS

  • module: appropriate module pinout, see the following table :

    UART Module Pinouts for ST M3
    UART1 _GPIO_MODULE_USART1_PA9_10 _GPIO_MODULE_USART1_PB67
    UART2 _GPIO_MODULE_USART2_PA23 _GPIO_MODULE_USART2_PD56
    UART3 _GPIO_MODULE_USART3_PB10_11 _GPIO_MODULE_USART3_PC10_11 _GPIO_MODULE_USART3_PD89
    UART4 _GPIO_MODULE_UART4_PC10_11 _GPIO_MODULE_UART4_PA01
    UART5 _GPIO_MODULE_UART5_PC12_PD2
    UART6 _GPIO_MODULE_USART6_PC67 _GPIO_MODULE_USART6_PG9_14

    UART Module Pinouts for ST M4
    UART1 _GPIO_MODULE_USART1_PA9_10 _GPIO_MODULE_USART1_PB67
    UART2 _GPIO_MODULE_USART2_PA23 _GPIO_MODULE_USART2_PD56
    UART3 _GPIO_MODULE_USART3_PB10_11 _GPIO_MODULE_USART3_PC10_11 _GPIO_MODULE_USART3_PD89
    UART4 _GPIO_MODULE_UART4_PA01 _GPIO_MODULE_UART4_PC10_11
    UART5 _GPIO_MODULE_UART5_PC12_PD2
    UART6 _GPIO_MODULE_USART6_PC67 _GPIO_MODULE_USART6_PG9_14
Returns

Nothing.
Requires

Routine requires the UART module.
Example

Stellaris

' Initialize hardware UART1 module at 115200 bps with 10 MHz peripheral clock, 8 data, no parity and 1 stop bit in high speed mode :
UART1_Init_Advanced(115200, 10000, _UART_8_BIT_DATA, _UART_NOPARITY, _UART_ONE_STOPBIT, _UART_HI_SPEED)

' Initialize hardware UART1 module on GPIO_PORTA at 115200 bps with 10 MHz peripheral clock, 8 data, no parity and 1 stop bit in high speed mode :
UART1_Init_Advanced(115200, 10000, _UART_8_BIT_DATA, _UART_NOPARITY, _UART_ONE_STOPBIT, _UART_HI_SPEED, @_GPIO_MODULE_UART1_A01)

STM32

' Initialize hardware UART1 module on PORTA at 115200 bps, 8 data, no parity and 1 stop bit :
UART1_Init_Advanced(115200, _UART_8_BIT_DATA, _UART_NOPARITY, _UART_ONE_STOPBIT, @_GPIO_MODULE_USART1_PA9_10)
Notes
  • Refer to the device data sheet for baud rates allowed for specific peripheral clock values.
  • 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 0 to 7.
  • 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.
  • For available working modes for a specific MCU please read the appropriate datasheet.

UARTx_Data_Ready

Prototype

sub function UARTx_Data_Ready() as word
Description

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

None.
Returns
  • 1 if data is ready for reading.
  • 0 if there is no data in the receive register.
Requires

Routine requires at least one UART module.

Used UART module must be initialized before using this routine. See UARTx_Init and UARTx_Init_Advanced routines.
Example 
dim receive as word
...
' read data if ready
if (UART1_Data_Ready() = 1) then
  receive = UART1_Read()
end if
Notes
  • 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 0 to 7.
  • Number of UART modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

UARTx_Tx_Idle

Prototype

sub function UARTx_Tx_Idle() as word
Description

Use the function to test if the transmit shift register is empty or not.
Parameters

None.
Returns
  • 1 if the data has been transmitted.
  • 0 otherwise.
Requires

Routine requires at least one UART module.

Used UART module must be initialized before using this routine. See UARTx_Init and UARTx_Init_Advanced routines.
Example 
' If the previous data has been shifted out, send next data:
if (UART1_Tx_Idle() = 1) then
  UART1_Write(_data)
end if
Notes
  • 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 0 to 7.
  • Number of UART modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

UARTx_Read

Prototype

sub function UARTx_Read() as word
Description

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

None.
Returns

Received byte.
Requires

Routine requires at least one UART module.

Used UART module must be initialized before using this routine. See UARTx_Init and UARTx_Init_Advanced routines.
Example 
dim receive as word
...
' read data if ready
if (UART1_Data_Ready() = 1) then 
  receive = UART1_Read()
end if
Notes
  • 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 0 to 7.
  • Number of UART modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

UARTx_Read_Text

Prototype

sub procedure UARTx_Read_Text(dim byref output, delimiter as string; dim Attempts as byte)
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.
Returns

Nothing.
Requires

Routine requires at least one UART module.

Used UART module must be initialized before using this routine. See UARTx_Init and UARTx_Init_Advanced routines.
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.
Notes
  • 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 0 to 7.
  • Number of UART modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

UARTx_Write

Prototype

sub procedure UARTx_Write(dim data_ as word)
Description

The function transmits a byte via the UART module.
Parameters
  • _data: data to be sent.
Returns

Nothing.
Requires

Routine requires at least one UART module.

Used UART module must be initialized before using this routine. See UARTx_Init and UARTx_Init_Advanced routines.
Example 
dim data_ as byte
...
data_ = 0x1E
UART1_Write(data_)
Notes
  • 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 0 to 7.
  • Number of UART modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

UARTx_Write_Text

Prototype

sub procedure UARTx_Write_Text(dim byref uart_text as string)
Description

Sends text via UART. Text should be zero terminated.
Parameters
  • UART_text: text to be sent.
Returns

Nothing.
Requires

Routine requires at least one UART module.

Used UART module must be initialized before using this routine. See UARTx_Init and UARTx_Init_Advanced routines.
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.
Notes
  • 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 0 to 7.
  • Number of UART modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

UART_Set_Active

Prototype

sub procedure UART_Set_Active (dim read_ptr as ^TUART_Rd_Ptr, dim write_ptr as ^TUART_Wr_Ptr, dim ready_ptr as ^TUART_Rdy_Ptr, dim tx_idle_ptr as ^TUART_TX_Idle_Ptr)
Description

Sets active UART module which will be used by UARTx_Data_Ready, UARTx_Read and UARTx_Write routines.
Parameters

Parameters :
Returns

Nothing.
Requires

Routine is available only for MCUs with multiple UART modules.

Used UART module must be initialized before using this routine. See UARTx_Init and UARTx_Init_Advanced routines.
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
Notes

None.

UART_Data_Ready

Prototype

sub function UART_Data_Ready() as word
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.
Parameters

None.
Returns
  • 1 if data is ready for reading.
  • 0 if there is no data in the receive register.
Requires

Routine requires at least one UART module.

Used UART module must be initialized before using this routine. See UARTx_Init and UARTx_Init_Advanced routines.
Example 
dim receive as word
...
' read data if ready
if (UART_Data_Ready() = 1) then
  receive = UART_Read()
end if
Notes

None.

UART_Tx_Idle

Prototype

sub function UART_Tx_Idle() as word
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.
Parameters

None.
Returns
  • 1 if the data has been transmitted.
  • 0 otherwise.
Requires

Routine requires at least one UART module.

Used UART module must be initialized before using this routine. See UARTx_Init and UARTx_Init_Advanced routines.
Example 
' If the previous data has been shifted out, send next data:
if (UART_Tx_Idle() = 1) then
  UART_Write(_data)
end if
Notes

None.

UART_Read

Prototype

sub function UART_Read() as word
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.
Parameters

None.
Returns

Received byte.
Requires

Routine requires at least one UART module.

Used UART module must be initialized before using this routine. See UARTx_Init and UARTx_Init_Advanced routines.
Example 
dim receive as word
...
' read data if ready
if (UART_Data_Ready() = 1) then 
  receive = UART_Read()
end if
Notes

None.

UART_Read_Text

Prototype

sub procedure UART_Read_Text(dim byref output, delimiter as string; dim Attempts as byte)
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).

This is a generic routine which uses the active UART module previously activated by the UART_Set_Active routine.
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.
Returns

Nothing.
Requires

Routine requires at least one UART module.

Used UART module must be initialized before using this routine. See UARTx_Init and UARTx_Init_Advanced routines.
Example

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

 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.
Notes

None.

UART_Write

Prototype

sub procedure UART_Write(dim data_ as word)
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
  • _data: data to be sent.
Returns

Nothing.
Requires

Routine requires at least one UART module.

Used UART module must be initialized before using this routine. See UARTx_Init and UARTx_Init_Advanced routines.
Example 
dim data_ as byte
...
data_ = 0x1E
UART_Write(data_)
Notes

None.

UART_Write_Text

Prototype

sub procedure UART_Write_Text(dim byref uart_text as string)
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_text: text to be sent.
Returns

Nothing.
Requires

Routine requires at least one UART module.

Used UART module must be initialized before using this routine. See UARTx_Init and UARTx_Init_Advanced routines.
Example

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

 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.
Notes

None.

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 ARM USART communication terminal, launch it from the drop-down menu Tools › USART Terminal or simply click the USART Terminal Icon USART Terminal Icon.

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

main:

  UART0_Init(56000)                       ' Initialize UART module at 56000 bps
  Delay_ms(100)                           ' Wait for UART module to stabilize

  UART0_Write_Text("Start")
  UART0_Write(13)
  UART0_Write(10)

  while TRUE                              ' Endless loop
    if (UART0_Data_Ready() <> 0) then     ' If data is received
      uart_rd = UART0_Read()              ' read the received data
      UART0_Write(uart_rd)                ' and send data via UART
    end if
  wend
end.
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