qmk_firmware

QMK firmware for my keyboards (Corne, Sweep Ferris) and trackball (Ploopy Adept)
Log | Files | Refs | Submodules | LICENSE

uart.md (4447B)

      1 # UART Driver {#uart-driver}
      2 
      3 The UART drivers used in QMK have a set of common functions to allow portability between MCUs.
      4 
      5 Currently, this driver does not support enabling hardware flow control (the `RTS` and `CTS` pins) if available, but may do so in future.
      6 
      7 ## Usage {#usage}
      8 
      9 In most cases, the UART driver code is automatically included if you are using a feature or driver which requires it.
     10 
     11 However, if you need to use the driver standalone, add the following to your `rules.mk`:
     12 
     13 ```make
     14 UART_DRIVER_REQUIRED = yes
     15 ```
     16 
     17 You can then call the UART API by including `uart.h` in your code.
     18 
     19 ## AVR Configuration {#avr-configuration}
     20 
     21 No special setup is required - just connect the `RX` and `TX` pins of your UART device to the opposite pins on the MCU:
     22 
     23 |MCU          |`TX`|`RX`|`CTS`|`RTS`|
     24 |-------------|----|----|-----|-----|
     25 |ATmega16/32U2|`D3`|`D2`|`D7` |`D6` |
     26 |ATmega16/32U4|`D3`|`D2`|`D5` |`B7` |
     27 |AT90USB64/128|`D3`|`D2`|*n/a*|*n/a*|
     28 |ATmega32A    |`D1`|`D0`|*n/a*|*n/a*|
     29 |ATmega328/P  |`D1`|`D0`|*n/a*|*n/a*|
     30 
     31 ## ChibiOS/ARM Configuration {#arm-configuration}
     32 
     33 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.
     34 
     35 To enable UART, modify your board's `mcuconf.h` to enable the peripheral you've chosen, for example:
     36 
     37 ```c
     38 #pragma once
     39 
     40 #include_next <mcuconf.h>
     41 
     42 #undef STM32_SERIAL_USE_USART2 // [!code focus]
     43 #define STM32_SERIAL_USE_USART2 TRUE // [!code focus]
     44 ```
     45 
     46 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.
     47 
     48 |`config.h` Override|Description                                                    |Default|
     49 |-------------------|---------------------------------------------------------------|-------|
     50 |`UART_DRIVER`      |USART peripheral to use - USART1 -> `SD1`, USART2 -> `SD2` etc.|`SD1`  |
     51 |`UART_TX_PIN`      |The pin to use for TX                                          |`A9`   |
     52 |`UART_TX_PAL_MODE` |The alternate function mode for TX                             |`7`    |
     53 |`UART_RX_PIN`      |The pin to use for RX                                          |`A10`  |
     54 |`UART_RX_PAL_MODE` |The alternate function mode for RX                             |`7`    |
     55 |`UART_CTS_PIN`     |The pin to use for CTS                                         |`A11`  |
     56 |`UART_CTS_PAL_MODE`|The alternate function mode for CTS                            |`7`    |
     57 |`UART_RTS_PIN`     |The pin to use for RTS                                         |`A12`  |
     58 |`UART_RTS_PAL_MODE`|The alternate function mode for RTS                            |`7`    |
     59 
     60 ## API {#api}
     61 
     62 ### `void uart_init(uint32_t baud)` {#api-uart-init}
     63 
     64 Initialize the UART driver. This function must be called only once, before any of the below functions can be called.
     65 
     66 #### Arguments {#api-uart-init-arguments}
     67 
     68  - `uint32_t baud`  
     69    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.
     70 
     71 ---
     72 
     73 ### `void uart_write(uint8_t data)` {#api-uart-write}
     74 
     75 Transmit a single byte.
     76 
     77 #### Arguments {#api-uart-write-arguments}
     78 
     79  - `uint8_t data`  
     80    The byte to write.
     81 
     82 ---
     83 
     84 ### `uint8_t uart_read(void)` {#api-uart-read}
     85 
     86 Receive a single byte.
     87 
     88 #### Return Value {#api-uart-read-return}
     89 
     90 The byte read from the receive buffer. This function will block if the buffer is empty (ie. no data to read).
     91 
     92 ---
     93 
     94 ### `void uart_transmit(const uint8_t *data, uint16_t length)` {#api-uart-transmit}
     95 
     96 Transmit multiple bytes.
     97 
     98 #### Arguments {#api-uart-transmit-arguments}
     99 
    100  - `const uint8_t *data`  
    101    A pointer to the data to write from.
    102  - `uint16_t length`  
    103    The number of bytes to write. Take care not to overrun the length of `data`.
    104 
    105 ---
    106 
    107 ### `void uart_receive(char *data, uint16_t length)` {#api-uart-receive}
    108 
    109 Receive multiple bytes.
    110 
    111 #### Arguments {#api-uart-receive-arguments}
    112 
    113  - `uint8_t *data`  
    114    A pointer to a buffer to read into.
    115  - `uint16_t length`  
    116    The number of bytes to read. Take care not to overrun the length of `data`.
    117 
    118 ---
    119 
    120 ### `bool uart_available(void)` {#api-uart-available}
    121 
    122 Return whether the receive buffer contains data. Call this function to determine if `uart_read()` will return data immediately.
    123 
    124 #### Return Value {#api-uart-available-return}
    125 
    126 `true` if there is data available to read.