Skip to content

Using The UART HAL

Concept preview: Using The UART HAL

UART byte path between the PC terminal and the Uno’s USART0

The public interface is in avr_hal/uart.h, implemented in uart.c. avr_uart_init(baud) configures USART0 for asynchronous 8N1 and selects the closer normal or double-speed divisor if its error is within the documented limit.

On the Uno, the HAL owns D0/RX and D1/TX. Initialization disables USART interrupts but does not enable global interrupts. Callers must not run a second UART owner at the same time.

avr_uart_put() sends one byte using a readiness polling budget. avr_uart_get() waits for a byte and reports framing, parity or overrun errors. The budget counts unsuccessful polls; it is not a duration in milliseconds. avr_uart_write() accepts a caller-owned buffer and can time out after sending a prefix. avr_uart_u16() prints an unsigned decimal value without heap allocation or printf.

The polling API is intended for one foreground caller. The optional uart_rx interrupt module provides a separate receive queue; do not also install another USART_RX_vect owner.

Use bounded polling when the application can tolerate waiting up to the chosen loop budget. Use the interrupt queue when incoming bytes must be captured while foreground code is occupied. In both cases, define how errors and queue overflow are reported and recovered.

Build the UART echo lab or buffered UART lab and inspect its configuration. The byte-echo path has passed one physical COM4 test; baud-rate extremes and other adapters have not been tested.

For example, build the interrupt-buffer lab with XC8:

Terminal window
python atmega328p-labs/tools/build.py 47-uart-buffer --compiler xc8

UART receive queue status indicator schematic

Does the transmit budget passed to avr_uart_write() limit the entire string to that many polls?

Answer: No. The header defines it as a readiness-poll bound for each byte. The total time can be much longer for a long buffer, and a timeout can occur after a prefix has been transmitted.

Example code on GitHub:

The example’s main() configures its peripherals, runs the algorithm and reports or displays the result. These source operations are listed in execution order:

  • for (;;) - Repeats the foreground task indefinitely; each pass checks inputs, advances the calculation or services the peripheral shown below.
  • if (usart_get(&received)) - Tests the stated condition; the following block handles the matching case and the other path is skipped.

Algorithm: Configures UBRR0, UCSR0A/B/C and UDR0 directly; checks RXC0 and per-byte FE0/DOR0/UPE0 before echoing. Expected behaviour: Each error-free received byte is echoed once; malformed or timed-out receives are ignored HAL source files in this repository: ATmega328P HAL on GitHub

The example’s main() configures its peripherals, runs the algorithm and reports or displays the result. These source operations are listed in execution order:

  • (void)avr_uart_init(9600UL); - Configures USART0 for asynchronous 8N1. It chooses a baud divisor and normal/double-speed mode, programs UBRR0/UCSR0A/UCSR0C, then enables receive and transmit in UCSR0B.
  • for (;;) - Repeats the foreground task indefinitely; each pass checks inputs, advances the calculation or services the peripheral shown below.
  • avr_status_t status = avr_uart_get(&byte, AVR_POLL_BUDGET); - Use the linked public header for this function’s parameters, register ownership, blocking behavior and status values.
  • if (status == AVR_OK) - Only enters the following block when the operation reports success.
  • (void)avr_uart_put(byte, AVR_POLL_BUDGET); - Waits for the USART transmit buffer within its poll budget, then writes the byte to UDR0.

Algorithm: One 8N1 frame contains ten bits. At 9600 baud, a frame takes approximately 1.042 ms; the application must service reception before hardware buffering overflows. Expected behaviour: Each received byte is echoed once HAL source files in this repository: ATmega328P HAL on GitHub

The example’s main() configures its peripherals, runs the algorithm and reports or displays the result. These source operations are listed in execution order:

  • if ((avr_uart_init(9600UL) != AVR_OK) || (avr_uart_rx_start() != AVR_OK)) - This checks for any setup or transfer error before the program continues. Configures USART0 for asynchronous 8N1. It chooses a baud divisor and normal/double-speed mode, programs UBRR0/UCSR0A/UCSR0C, then enables receive and transmit in UCSR0B. Enables the interrupt-driven USART receive queue. Start it after UART setup and enable global interrupts only when shared state is ready.
  • return 1; - Stops this path and returns the indicated status when setup or validation cannot continue.
  • (void)avr_gpio_mode(13U, AVR_GPIO_OUTPUT); - Maps the Uno header pin to its AVR port, sets its DDR direction bit and prepares the PORT latch for the requested initial level or pull-up.
  • (void)avr_gpio_mode(8U, AVR_GPIO_OUTPUT); - Maps the Uno header pin to its AVR port, sets its DDR direction bit and prepares the PORT latch for the requested initial level or pull-up.
  • avr_tick_init(); - Configures the course millisecond tick interrupt source; it does not enable global interrupts itself.
  • uint32_t previous = 0UL; - Clears the state/counter after its threshold is reached so the next interval starts from zero.
  • sei(); - Enables global interrupts after the example has configured its sources and shared state.
  • for (;;) - Repeats the foreground task indefinitely; each pass checks inputs, advances the calculation or services the peripheral shown below.
  • if (avr_uart_rx_get(&value) == AVR_OK) - The operation runs only after this API reports AVR_OK. Removes one byte from the receive queue without blocking; an empty queue returns a busy status.
  • (void)avr_uart_put(value, AVR_POLL_BUDGET); - Waits for the USART transmit buffer within its poll budget, then writes the byte to UDR0.
  • uint32_t now = avr_tick_ms(); - Use the linked public header for this function’s parameters, register ownership, blocking behavior and status values.
  • if (avr_elapsed(now, previous, 500UL)) - Tests this condition to choose which algorithm path runs.
  • previous = now; - Stores this intermediate value for the next step of the algorithm; check the operands and units.
  • (void)avr_gpio_toggle(13U); - Atomically toggles the selected pin output latch.
  • avr_uart_rx_stats_t stats; - Use the linked public header for this function’s parameters, register ownership, blocking behavior and status values.
  • (void)avr_uart_rx_stats(&stats); - Use the linked public header for this function’s parameters, register ownership, blocking behavior and status values.
  • if ((stats.dropped != 0U) || (stats.errors != 0U)) - Tests the stated condition; the following block handles the matching case and the other path is skipped.
  • (void)avr_gpio_write(8U, true); - Changes the pin’s PORT output latch; for an input pin this selects its pull-up state.

Algorithm: A finite single-producer/single-consumer queue separates the ISR from foreground processing; one slot distinguishes full from empty. Expected behaviour: Echo received bytes while LED L toggles; D8 latches high after receive loss HAL source files in this repository: ATmega328P HAL on GitHub