diff --git a/drivers/include/periph/uart.h b/drivers/include/periph/uart.h index c29f3b4b261efec80a5b3a6ec758fd1c96e6e284..52af846c650875b3e1fbcb33dc3cf7491608c9fb 100644 --- a/drivers/include/periph/uart.h +++ b/drivers/include/periph/uart.h @@ -12,6 +12,29 @@ * @brief Low-level UART peripheral driver * @{ * + * This is a basic UART (Universal Asynchronous Receiver Transmitter) interface + * to allow platform independent access to the MCU's serial communication abilities. + * This interface is intentionally designed to be as simple as possible, to allow + * for easy implementation and maximum portability. In RIOT we only use the + * common 8-N-1 format of the serial port (8 data bist, no parity bit, one stop bit). + * + * The simple interface provides capabilities to initialize the serial communication + * module, which automatically enables for receiving data, as well as writing data + * to the UART port, which means transmitting data. The UART device and the + * corresponding pins need to be mapped in `RIOT/boards/ * /include/periph_conf.h`. + * Furthermore you need to select the baudrate for initialization which is typically + * {9600, 19200, 38400, 57600, 115200} baud. Additionally you should register a + * callback function that is executed in interrupt context when data is being received. + * The driver will then read the received data byte, call the registered callback + * function and pass the received data to it via its argument. The interface enforces + * the receiving to be impemented in an interrupt driven mode. Thus, you never now how + * many bytes are going to be received and might want to handle that in your specific + * callback function. The transmit function can be implemented in any way + * + * By default the @p UART_DEV(0) device of each board is initialized and mapped to STDIO + * in RIOT which is used for standard input/output functions like `printf()` or + * `puts()`. + * * @file * @brief Low-level UART peripheral driver interface definition *