merge upstream 713427c

1 files changed, 35 insertions, 21 deletions

diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md
index 0b475cc63d..c095c8712f 100644
--- a/docs/feature_split_keyboard.md
+++ b/docs/feature_split_keyboard.md
@@ -79,6 +79,16 @@ If you're using a custom transport (communication method), then you will also ne
 SPLIT_TRANSPORT = custom
 ```
 
+### Layout Macro
+
+Configuring your layout in a split keyboard works slightly differently to a non-split keyboard. Take for example the following layout. The top left numbers refer to the matrix row and column, and the bottom right are the order of the keys in the layout:
+
+![Physical layout](https://i.imgur.com/QeY6kMQ.png)
+
+Since the matrix scanning procedure operates on entire rows, it first populates the left half's rows, then the right half's. Thus, the matrix as QMK views it has double the rows instead of double the columns:
+
+![Matrix](https://i.imgur.com/4wjJzBU.png)
+
 ### Setting Handedness
 
 By default, the firmware does not know which side is which; it needs some help to determine that. There are several ways to do this, listed in order of precedence.
@@ -132,28 +142,25 @@ To enable this method, add the following to your `config.h` file:
 #define EE_HANDS
 ```
 
-Next, you will have to flash the EEPROM files once for the correct hand to the controller on each halve. You can do this manually with the following bootloader targets while flashing the firmware:
-
-* AVR controllers with the Caterina bootloader (e.g. Pro Micro):
-  * `:avrdude-split-left`
-  * `:avrdude-split-right`
-* AVR controllers with the stock Amtel DFU or DFU compatible bootloader (e.g. Elite-C):
-  * `:dfu-split-left`
-  * `:dfu-split-right`
-* ARM controllers with a DFU compatible bootloader (e.g. Proton-C):
-  * `:dfu-util-split-left`
-  * `:dfu-util-split-right`
-* ARM controllers with a UF2 compatible bootloader:
-  * `:uf2-split-left`
-  * `:uf2-split-right`
+Next, you will have to flash the correct handedness option to the controller on each halve. You can do this manually with the following bootloader targets using `qmk flash -kb <keyboard> -km <keymap> -bl <bootloader>` command to flash:
 
-Example:
+|Microcontroller Type|Bootloader Parameter|
+|--------------------|--------------------|
+|AVR controllers with Caterina bootloader<br>(e.g. Pro Micro)|`avrdude-split-left`<br>`avrdude-split-right`|
+|AVR controllers with the stock Amtel DFU or DFU compatible bootloader<br>(e.g. Elite-C)|`dfu-split-left`<br>`dfu-split-right`|
+|ARM controllers with a DFU compatible bootloader<br>(e.g. Proton-C)|`dfu-util-split-left`<br>`dfu-util-split-right`|
+|ARM controllers with a UF2 compatible bootloader<br>(e.g. RP2040)|`uf2-split-left`<br>`uf2-split-right`|
 
+Example for `crkbd/rev1` keyboard with normal AVR Pro Micro MCUs, reset the left controller and run:
+```
+qmk flash -kb crkbd/rev1 -km default -bl avrdude-split-left
 ```
-make crkbd:default:avrdude-split-left
+Reset the right controller and run:
+```
+qmk flash -kb crkbd/rev1 -km default -bl avrdude-split-right
 ```
 
-?> ARM controllers using `dfu-util` will require an EEPROM reset after setting handedness. This can be done using the `EE_CLR` keycode or [Bootmagic Lite](feature_bootmagic.md). Controllers using emulated EEPROM will always require handedness parameter when flashing the firmware.
+?> Some controllers (e.g. Blackpill with DFU compatible bootloader) will need to be flashed with handedness bootloader parameter every time because it is not retained between flashes.
 
 ?> [QMK Toolbox]() can also be used to flash EEPROM handedness files. Place the controller in bootloader mode and select menu option Tools -> EEPROM -> Set Left/Right Hand
 
@@ -161,21 +168,22 @@ This setting is not changed when re-initializing the EEPROM using the `EE_CLR` k
 
 You can find the `EEPROM` files in the QMK firmware repo, [here](https://github.com/qmk/qmk_firmware/tree/master/quantum/split_common).
 
+
 #### Handedness by `#define`
 
-You can set the handedness at compile time.  This is done by adding the following to your `config.h` file:
+You can use this option when USB cable is always connected to just one side of the split keyboard.
 
+If the USB cable is always connected to the right side, add the following to your `config.h` file and flash both sides with this option:
 ```c
 #define MASTER_RIGHT
 ```
 
-or 
-
+If the USB cable is always connected to the left side, add the following to your `config.h` file and flash both sides with this option:
 ```c
 #define MASTER_LEFT
 ```
 
-If neither are defined, the handedness defaults to `MASTER_LEFT`.
+?> If neither options are defined, the handedness defaults to `MASTER_LEFT`.
 
 
 ### Communication Options
@@ -286,6 +294,12 @@ This enables transmitting the pointing device status to the master side of the s
 
 !> There is additional required configuration for `SPLIT_POINTING_ENABLE` outlined in the [pointing device documentation](feature_pointing_device.md?id=split-keyboard-configuration).
 
+```c
+#define SPLIT_HAPTIC_ENABLE
+```
+
+This enables triggering of haptic feedback on the slave side of the split keyboard. For DRV2605L this will send the mode, but for solenoids it is expected that the desired mode is already set up on the slave.
+
 ### Custom data sync between sides :id=custom-data-sync
 
 QMK's split transport allows for arbitrary data transactions at both the keyboard and user levels. This is modelled on a remote procedure call, with the master invoking a function on the slave side, with the ability to send data from master to slave, process it slave side, and send data back from slave to master.