aboutsummaryrefslogtreecommitdiff
path: root/docs/drivers/serial.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/drivers/serial.md')
-rw-r--r--docs/drivers/serial.md114
1 files changed, 65 insertions, 49 deletions
diff --git a/docs/drivers/serial.md b/docs/drivers/serial.md
index 75d11bc93b..dda75f629a 100644
--- a/docs/drivers/serial.md
+++ b/docs/drivers/serial.md
@@ -12,8 +12,6 @@ The Serial driver powers the [Split Keyboard](../features/split_keyboard) featur
Serial in this context should be read as **sending information one bit at a time**, rather than implementing UART/USART/RS485/RS232 standards.
:::
-<hr>
-
## Bitbang
This is the Default driver, absence of configuration assumes this driver. It works by [bit banging](https://en.wikipedia.org/wiki/Bit_banging) a GPIO pin using the CPU. It is therefore not as efficient as a dedicated hardware peripheral, which the Half-duplex and Full-duplex drivers use.
@@ -53,11 +51,15 @@ SERIAL_DRIVER = bitbang
#define SOFT_SERIAL_PIN D0 // or D1, D2, D3, E6
```
-3. On ARM platforms you must turn on ChibiOS `PAL_USE_CALLBACKS` feature:
+3. On ARM platforms you must turn on ChibiOS PAL callbacks:
-* In `halconf.h` add the line `#define PAL_USE_CALLBACKS TRUE`.
+```c
+#pragma once
-<hr>
+#define PAL_USE_CALLBACKS TRUE // [!code focus]
+
+#include_next <halconf.h>
+```
## USART Half-duplex
@@ -117,8 +119,6 @@ For STM32 MCUs several GPIO configuration options can be changed as well. See th
4. Decide either for `SERIAL`, `SIO`, or `PIO` subsystem. See section ["Choosing a driver subsystem"](#choosing-a-driver-subsystem).
-<hr>
-
## USART Full-duplex
Targeting ARM boards based on ChibiOS where communication is offloaded to an USART hardware device. The advantages over bitbanging are fast, accurate timings and reduced CPU usage; therefore it is advised to choose this driver over all others where possible. Due to its internal design Full-duplex is slightly more efficient than the Half-duplex driver, but Full-duplex should be primarily chosen if Half-duplex operation is not supported by the controller's USART peripheral.
@@ -179,38 +179,46 @@ For STM32 MCUs several GPIO configuration options, including the ability for `TX
4. Decide either for `SERIAL`, `SIO`, or `PIO` subsystem. See section ["Choosing a driver subsystem"](#choosing-a-driver-subsystem).
-<hr>
-
## Choosing a driver subsystem
### The `SERIAL` driver
The `SERIAL` Subsystem is supported for the majority of ChibiOS MCUs and should be used whenever supported. Follow these steps in order to activate it:
-1. In your keyboards `halconf.h` add:
+1. Enable the SERIAL subsystem in the ChibiOS HAL.
-```c
-#define HAL_USE_SERIAL TRUE
-```
+ Add the following to your keyboard's `halconf.h`, creating it if necessary:
-2. In your keyboards `mcuconf.h`: activate the USART peripheral that is used on your MCU. The shown example is for an STM32 MCU, so this will not work on MCUs by other manufacturers. You can find the correct names in the `mcuconf.h` files of your MCU that ship with ChibiOS.
-
-Just below `#include_next <mcuconf.h>` add:
+ ```c
+ #pragma once
-```c
-#include_next <mcuconf.h>
+ #define HAL_USE_SERIAL TRUE // [!code focus]
-#undef STM32_SERIAL_USE_USARTn
-#define STM32_SERIAL_USE_USARTn TRUE
-```
+ #include_next <halconf.h>
+ ```
-Where 'n' matches the peripheral number of your selected USART on the MCU.
+2. Activate the USART peripheral that is used on your MCU. The shown example is for an STM32 MCU, so this will not work on MCUs by other manufacturers. You can find the correct names in the `mcuconf.h` files of your MCU that ship with ChibiOS.
-3. In you keyboards `config.h`: override the default USART `SERIAL` driver if you use a USART peripheral that does not belong to the default selected `SD1` driver. For instance, if you selected `STM32_SERIAL_USE_USART3` the matching driver would be `SD3`.
+ Add the following to your keyboard's `mcuconf.h`, creating it if necessary:
-```c
- #define SERIAL_USART_DRIVER SD3
- ```
+ ```c
+ #pragma once
+
+ #include_next <mcuconf.h>
+
+ #undef STM32_SERIAL_USE_USARTn // [!code focus]
+ #define STM32_SERIAL_USE_USARTn TRUE // [!code focus]
+ ```
+
+ Where *n* matches the peripheral number of your selected USART on the MCU.
+
+3. Override the default USART `SERIAL` driver if you use a USART peripheral that does not belong to the default selected `SD1` driver. For instance, if you selected `STM32_SERIAL_USE_USART3` the matching driver would be `SD3`.
+
+ Add the following to your keyboard's `config.h`:
+
+ ```c
+ #define SERIAL_USART_DRIVER SD3
+ ```
### The `SIO` driver
@@ -218,31 +226,41 @@ The `SIO` Subsystem was added to ChibiOS with the 21.11 release and is only supp
Follow these steps in order to activate it:
-1. In your keyboards `halconf.h` add:
+1. Enable the SIO subsystem in the ChibiOS HAL.
-```c
-#define HAL_USE_SIO TRUE
-```
+ Add the following to your keyboard's `halconf.h`, creating it if necessary:
-2. In your keyboards `mcuconf.h:` activate the USART peripheral that is used on your MCU. The shown example is for an STM32 MCU, so this will not work on MCUs by other manufacturers. You can find the correct names in the `mcuconf.h` files of your MCU that ship with ChibiOS.
-
-Just below `#include_next <mcuconf.h>` add:
+ ```c
+ #pragma once
-```c
-#include_next <mcuconf.h>
+ #define HAL_USE_SIO TRUE // [!code focus]
-#undef STM32_SIO_USE_USARTn
-#define STM32_SIO_USE_USARTn TRUE
-```
+ #include_next <halconf.h>
+ ```
-Where 'n' matches the peripheral number of your selected USART on the MCU.
+2. Activate the USART peripheral that is used on your MCU. The shown example is for an STM32 MCU, so this will not work on MCUs by other manufacturers. You can find the correct names in the `mcuconf.h` files of your MCU that ship with ChibiOS.
-3. In the keyboard's `config.h` file: override the default USART `SIO` driver if you use a USART peripheral that does not belong to the default selected `SIOD1` driver. For instance, if you selected `STM32_SERIAL_USE_USART3` the matching driver would be `SIOD3`.
+ Add the following to your keyboard's `mcuconf.h`, creating it if necessary:
+
+ ```c
+ #pragma once
+
+ #include_next <mcuconf.h>
+
+ #undef STM32_SIO_USE_USARTn // [!code focus]
+ #define STM32_SIO_USE_USARTn TRUE // [!code focus]
+ ```
+
+ Where *n* matches the peripheral number of your selected USART on the MCU.
+
+3. Override the default USART `SIO` driver if you use a USART peripheral that does not belong to the default selected `SIOD1` driver. For instance, if you selected `STM32_SERIAL_USE_USART3` the matching driver would be `SIOD3`.
+
+ Add the following to your keyboard's `config.h`:
+
+ ```c
+ #define SERIAL_USART_DRIVER SIOD3
+ ```
-```c
- #define SERIAL_USART_DRIVER SIOD3
- ```
-
### The `PIO` driver
The `PIO` subsystem is a Raspberry Pi RP2040 specific implementation, using an integrated PIO peripheral and is therefore only available on this MCU. Because of the flexible nature of PIO peripherals, **any** GPIO pin can be used as a `TX` or `RX` pin. Half-duplex and Full-duplex operation modes are fully supported with this driver. Half-duplex uses the built-in pull-ups and GPIO manipulation of the RP2040 to drive the line high by default, thus an external pull-up resistor **is not required**.
@@ -254,8 +272,6 @@ Optionally, the PIO peripheral utilized for split communication can be changed w
The Serial PIO program uses 2 state machines, 13 instructions and the complete interrupt handler of the PIO peripheral it is running on.
-<hr>
-
## Advanced Configuration
There are several advanced configuration options that can be defined in your keyboards `config.h` file:
@@ -265,9 +281,11 @@ There are several advanced configuration options that can be defined in your key
If you're having issues or need a higher baudrate with serial communication, you can change the baudrate which in turn controls the communication speed for serial. You want to lower the baudrate if you experience failed transactions.
```c
-#define SELECT_SOFT_SERIAL_SPEED {#}
+#define SELECT_SOFT_SERIAL_SPEED n
```
+Where *n* is one of:
+
| Speed | Bitbang | Half-duplex and Full-duplex |
| ----- | -------------------------- | --------------------------- |
| `0` | 189000 baud (experimental) | 460800 baud |
@@ -287,8 +305,6 @@ This is the default time window in milliseconds in which a successful communicat
#define SERIAL_USART_TIMEOUT 20 // USART driver timeout. default 20
```
-<hr>
-
## Troubleshooting
If you're having issues withe serial communication, you can enable debug messages that will give you insights which part of the communication failed. The enable these messages add to your keyboards `config.h` file: