summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorRyan <fauxpark@gmail.com>2021-01-27 17:42:49 +1100
committerGitHub <noreply@github.com>2021-01-27 17:42:49 +1100
commit30b46fad5764b54ab4d47e9c4024f8030e1bf1a7 (patch)
tree9a9aa60158edf5adea802e33ee2db2ba4164145a /docs
parentbe897cbc2f9d542dfcc98c8e06aeb04179cc484c (diff)
UART driver refactor (#11637)
Diffstat (limited to 'docs')
-rw-r--r--docs/_summary.md1
-rw-r--r--docs/uart_driver.md90
2 files changed, 91 insertions, 0 deletions
diff --git a/docs/_summary.md b/docs/_summary.md
index 9bc0b193a7..526caf926f 100644
--- a/docs/_summary.md
+++ b/docs/_summary.md
@@ -138,6 +138,7 @@
* [WS2812 Driver](ws2812_driver.md)
* [EEPROM Driver](eeprom_driver.md)
* ['serial' Driver](serial_driver.md)
+ * [UART Driver](uart_driver.md)
* [GPIO Controls](internals_gpio_control.md)
* [Keyboard Guidelines](hardware_keyboard_guidelines.md)
diff --git a/docs/uart_driver.md b/docs/uart_driver.md
new file mode 100644
index 0000000000..4d1716975f
--- /dev/null
+++ b/docs/uart_driver.md
@@ -0,0 +1,90 @@
+# UART Driver
+
+The UART drivers used in QMK have a set of common functions to allow portability between MCUs.
+
+Currently, this driver does not support enabling hardware flow control (the `RTS` and `CTS` pins) if available, but may do so in future.
+
+## AVR Configuration
+
+No special setup is required - just connect the `RX` and `TX` pins of your UART device to the opposite pins on the MCU:
+
+|MCU |`TX`|`RX`|`CTS`|`RTS`|
+|-------------|----|----|-----|-----|
+|ATmega16/32U2|`D3`|`D2`|`D7` |`D6` |
+|ATmega16/32U4|`D3`|`D2`|`D5` |`B7` |
+|AT90USB64/128|`D3`|`D2`|*n/a*|*n/a*|
+|ATmega32A |`D1`|`D0`|*n/a*|*n/a*|
+|ATmega328/P |`D1`|`D0`|*n/a*|*n/a*|
+
+## ChibiOS/ARM Configuration
+
+You'll need to determine which pins can be used for UART -- as an example, STM32 parts generally have multiple UART peripherals, labeled USART1, USART2, USART3 etc.
+
+To enable UART, modify your board's `halconf.h` to enable the serial driver:
+
+```c
+#define HAL_USE_SERIAL TRUE
+```
+
+Then, modify your board's `mcuconf.h` to enable the peripheral you've chosen, for example:
+
+```c
+#undef STM32_SERIAL_USE_USART2
+#define STM32_SERIAL_USE_USART2 TRUE
+```
+
+Configuration-wise, you'll need to set up the peripheral as per your MCU's datasheet -- the defaults match the pins for a Proton-C, i.e. STM32F303.
+
+|`config.h` override |Description |Default Value|
+|--------------------------|---------------------------------------------------------------|-------------|
+|`#define SERIAL_DRIVER` |USART peripheral to use - USART1 -> `SD1`, USART2 -> `SD2` etc.|`SD1` |
+|`#define SD1_TX_PIN` |The pin to use for TX |`A9` |
+|`#define SD1_TX_PAL_MODE` |The alternate function mode for TX |`7` |
+|`#define SD1_RX_PIN` |The pin to use for RX |`A10` |
+|`#define SD1_RX_PAL_MODE` |The alternate function mode for RX |`7` |
+|`#define SD1_CTS_PIN` |The pin to use for CTS |`A11` |
+|`#define SD1_CTS_PAL_MODE`|The alternate function mode for CTS |`7` |
+|`#define SD1_RTS_PIN` |The pin to use for RTS |`A12` |
+|`#define SD1_RTS_PAL_MODE`|The alternate function mode for RTS |`7` |
+
+## Functions
+
+### `void uart_init(uint32_t baud)`
+
+Initialize the UART driver. This function must be called only once, before any of the below functions can be called.
+
+#### Arguments
+
+ - `uint32_t baud`
+ The baud rate to transmit and receive at. This may depend on the device you are communicating with. Common values are 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200.
+
+---
+
+### `void uart_putchar(uint8_t c)`
+
+Transmit a single byte.
+
+#### Arguments
+
+ - `uint8_t c`
+ The byte (character) to send, from 0 to 255.
+
+---
+
+### `uint8_t uart_getchar(void)`
+
+Receive a single byte.
+
+#### Return Value
+
+The byte read from the receive buffer.
+
+---
+
+### `bool uart_available(void)`
+
+Return whether the receive buffer contains data. Call this function to determine if `uart_getchar()` will return meaningful data.
+
+#### Return Value
+
+`true` if the receive buffer length is non-zero.