UARTTY is a UART driver for the AVR ATMEGA328P with built-in support for basic TTY features, such as line editing.
With UARTTY you can treat your AVR like a tiny POSIX system!
Anything you send to UARTTY is echoed back to the terminal, just as you might expect.
The most common line-editing characters are supported:
- Backspace erases the last character
- Ctrl-W erases the last word
- Ctrl-U erases the whole line
- Enter sends the line to the application
Note: other editor keys, such as Home/End, Delete, and the arrow keys, are not supported. Signal characters such as Ctrl-C and Ctrl-Z are also not supported; those would require POSIX signal support on the AVR.
Some conversions are made automatically when characters are sent or received:
- Carriage return from the terminal is converted to a linefeed
- Linefeed from the AVR is converted to carriage return plus linefeed
This behavior can be customized at compile time through a set of options (see Compile-time options).
(This code example is taken from the avr-libc manual and modified for UARTTY.)
#include <stdio.h>
#include <avr/interrupt.h>
#include "uartty.h"
#define BAUD 9600
#define UBRR_VALUE (unsigned)((F_CPU) / (16.0 * (BAUD)) + 0.5 - 1)
static FILE uartty_file = FDEV_SETUP_STREAM(uartty_putc, uartty_getc,
_FDEV_SETUP_RW);
int main(void)
{
uartty_init(UBRR_VALUE);
// global interrupts must be enabled for UARTTY
sei();
stdin = &uartty_file;
stdout = &uartty_file;
printf("Hello, world!\n");
for (;;) {
putchar(getchar());
}
}I needed a UART driver with basic line-editing capabilities for an AVR project that I'm working on. I decided to write a new driver after the POSIX TTY model as that is perhaps the most widely-used standard for line-oriented terminal systems, and it provides all of the functionality that I would need (erase characters, erase line, translate carriage returns/linefeeds, etc.).
The TTY processing occurs asynchronously during serial send and receive operations, and it's not too much to ask the UART transmit and receive interrupts to perform a bit of extra processing on top of the more usual task of adding the received byte to a queue or removing a byte from a queue.
Get the latest version of this library with this command:
git clone https://github.com/abbrev/uartty.git
This API is designed to be usable with the AVR-libc stdio module:
void uartty_init(unsigned int ubrr);Initialize the UARTTY library. Pass in the UBRR value.
Global interrupts must be enabled after uartty_init() by calling sei() before any other UARTTY function.
int uartty_getc(FILE *unused);Read a character from the UART.
int uartty_getc_nb(FILE *unused);Read a character from the UART without blocking.
int uartty_putc(char data, FILE *unused);Write a character to the UART.
int uartty_putc_nb(char data, FILE *unused);Write a character to the UART without blocking.
UARTTY can be configured at compile-time to behave differently. The default settings work well in most situations. All of the following options can be modified in the uartty-config.h file.
Set UARTTY_PRESET to one of these symbols to enable/disable a variety of modes:
- UARTTY_PRESET_RAW: no echo or input/output processing; a basic UART
- UARTTY_PRESET_SANE: echo, canonical input processing, etc.
If you know what you're doing, you can disable all presets and instead enable or disable each option individually:
- UARTTY_ICANON: enable canonical processing
- UARTTY_IEXTEN: enable extended input processing
- UARTTY_ECHO: echo received characters
- UARTTY_ECHOE: echo character erases
- UARTTY_ECHOK: kill character erases the current line
- UARTTY_ECHONL: echo newline even when ECHO is not set
- UARTTY_ECHOCTL: echo control characters as ^X
- UARTTY_ERASE: character to erase the previous character
- UARTTY_WERASE: character to erase the previous word
- UARTTY_KILL: character to erase the entire line
- UARTTY_ICRNL: convert carriage return to linefeed on input
- UARTTY_INLCR: convert linefeed to carriage return on input
- UARTTY_IMAXBEL: ring the bell when the input buffer is full
- UARTTY_IGNCR: ignore carriage return on input
- UARTTY_ISTRIP: strip the eighth bit on input
- UARTTY_IXON: enable XON/XOFF flow control
- UARTTY_OPOST: enable output post-processing
- UARTTY_ONLCR: convert linefeed to carriage return linefeed on output
- UARTTY_OCRNL: convert carriage return to linefeed on output
Enabling/disabling these options affects the generated code size:
- 344 with "raw" preset
- 1184 with "sane" preset
(These are only the common configurations. A complete list of sizes for each combination of options would be prohibitively large.)
Buffer size options:
- UARTTY_TX_BUF_SIZE: size of output buffer (default 16)
- UARTTY_RX_BUF_SIZE: size of input buffer (default 256)
Note: POSIX specifies that the input buffer must be at least 255 bytes. An AVR application may not need an input buffer that large, especially if it uses raw mode. UARTTY will function properly with a smaller input buffer but will display a warning at compile time. (A smaller input buffer also adds a few bytes to the code size because UARTTY must mask the buffer indices.)
- Christopher Williams
See LICENSE.
I say it like "you-arty", but you can say it like "you-are-titty" if you prefer.