docs/feature_split_keyboard.md

   1 # Split Keyboard
   2
   3 Many keyboards in the QMK Firmware repo are "split" keyboards. They use two controllers—one plugging into USB, and the second connected by a serial or an I<sup>2</sup>C connection over a TRRS or similar cable.
   4
   5 Split keyboards can have a lot of benefits, but there is some additional work needed to get them enabled.
   6
   7 QMK Firmware has a generic implementation that is usable by any board, as well as numerous board specific implementations.
   8
   9 For this, we will mostly be talking about the generic implementation used by the Let's Split and other keyboards.
  10
  11 !> ARM is not yet supported for Split Keyboards.  Progress is being made, but we are not quite there, yet.
  12
  13
  14 ## Hardware Configuration
  15
  16 This assumes that you're using two Pro Micro-compatible controllers, and are using TRRS jacks to connect to two halves.
  17
  18 ### Required Hardware
  19
  20 Apart from diodes and key switches for the keyboard matrix in each half, you will need 2x TRRS sockets and 1x TRRS cable.
  21
  22 Alternatively, you can use any sort of cable and socket that has at least 3 wires.
  23
  24 If you want to use I<sup>2</sup>C to communicate between halves, you will need a cable with at least 4 wires and 2x 4.7kΩ pull-up resistors.
  25
  26 #### Considerations
  27
  28 The most commonly used connection is a TRRS cable and jacks.  These provide 4 wires, making them very useful for split keyboards, and are easy to find.
  29
  30 However, since one of the wires carries VCC, this means that the boards are not hot pluggable. You should always disconnect the board from USB before unplugging and plugging in TRRS cables, or you can short the controller, or worse.
  31
  32 Another option is to use phone cables (as in, old school RJ-11/RJ-14 cables). Make sure that you use one that actually supports 4 wires/lanes.
  33
  34 However, USB cables, SATA cables, and even just 4 wires have been known to be used for communication between the controllers.
  35
  36 !> Using USB cables for communication between the controllers works just fine, but the connector could be mistaken for a normal USB connection and potentially short out the keyboard, depending on how it's wired.  For this reason, they are not recommended for connecting split keyboards.
  37
  38 ### Serial Wiring
  39
  40 The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and D0 (aka PDO or pin 3) between the two Pro Micros.
  41
  42 ?> Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below.
  43
  44 ![serial wiring](https://i.imgur.com/C3D1GAQ.png)
  45
  46 ### I<sup>2</sup>C Wiring
  47
  48 The 4 wires of the TRRS cable need to connect GND, VCC, and SCL and SDA (aka PD0/pin 3 and PD1/pin 2, respectively) between the two Pro Micros.
  49
  50 The pull-up resistors may be placed on either half. It is also possible to use 4 resistors and have the pull-ups in both halves, but this is unnecessary in simple use cases.
  51
  52 ![I2C wiring](https://i.imgur.com/Hbzhc6E.png)
  53
  54 ## Firmware Configuration
  55
  56 To enable the split keyboard feature, add the following to your `rules.mk`:
  57
  58 ```make
  59 SPLIT_KEYBOARD = yes
  60 ```
  61
  62 If you're using a custom transport (communication method), then you will also need to add:
  63
  64 ```make
  65 SPLIT_TRANSPORT = custom
  66 ```
  67
  68 ### Setting Handedness
  69
  70 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.
  71
  72 #### Handedness by Pin
  73
  74 You can configure the firmware to read a pin on the controller to determine handedness.  To do this, add the following to your `config.h` file:
  75
  76 ```c
  77 #define SPLIT_HAND_PIN B7
  78 ```
  79
  80 This will read the specified pin. If it's high, then the controller assumes it is the left hand, and if it's low, it's assumed to be the right side.
  81
  82 #### Handedness by EEPROM
  83
  84 This method sets the keyboard's handedness by setting a flag in the persistent storage (`EEPROM`).  This is checked when the controller first starts up, and determines what half the keyboard is, and how to orient the keyboard layout.
  85
  86
  87 To enable this method, add the following to your `config.h` file:
  88
  89 ```c
  90 #define EE_HANDS
  91 ```
  92
  93 However, you'll have to flash the EEPROM files for the correct hand to each controller.  You can do this manually, or there are targets for avrdude and dfu to do this, while flashing the firmware:
  94
  95 * `:avrdude-split-left`
  96 * `:avrdude-split-right`
  97 * `:dfu-split-left`
  98 * `:dfu-split-right`
  99
 100 This setting is not changed when re-initializing the EEPROM using the `EEP_RST` key, or using the `eeconfig_init()` function.  However, if you reset the EEPROM outside of the firmware's built in options (such as flashing a file that overwrites the `EEPROM`, like how the [QMK Toolbox]()'s "Reset EEPROM" button works), you'll need to re-flash the controller with the `EEPROM` files.
 101
 102 You can find the `EEPROM` files in the QMK firmware repo, [here](https://github.com/qmk/qmk_firmware/tree/master/quantum/split_common).
 103
 104 #### Handedness by `#define`
 105
 106 You can set the handedness at compile time.  This is done by adding the following to your `config.h` file:
 107
 108 ```c
 109 #define MASTER_RIGHT
 110 ```
 111
 112 or
 113
 114 ```c
 115 #define MASTER_LEFT
 116 ```
 117
 118 If neither are defined, the handedness defaults to `MASTER_LEFT`.
 119
 120
 121 ### Communication Options
 122
 123 Because not every split keyboard is identical, there are a number of additional options that can be configured in your `config.h` file.
 124
 125 ```c
 126 #define USE_I2C
 127 ```
 128
 129 This enables I<sup>2</sup>C support for split keyboards. This isn't strictly for communication, but can be used for OLED or other I<sup>2</sup>C-based devices.
 130
 131 ```c
 132 #define SOFT_SERIAL_PIN D0
 133 ```
 134
 135 This sets the pin to be used for serial communication. If you're not using serial, you shouldn't need to define this.
 136
 137 However, if you are using serial and I<sup>2</sup>C on the board, you will need to set this, and to something other than D0 and D1 (as these are used for I<sup>2</sup>C communication).
 138
 139 ```c
 140 #define SELECT_SOFT_SERIAL_SPEED {#}`
 141 ```
 142
 143 If you're having issues with serial communication, you can change this value, as it controls the communication speed for serial.  The default is 1, and the possible values are:
 144
 145 * **`0`**: about 189kbps (Experimental only)
 146 * **`1`**: about 137kbps (default)
 147 * **`2`**: about 75kbps
 148 * **`3`**: about 39kbps
 149 * **`4`**: about 26kbps
 150 * **`5`**: about 20kbps
 151
 152 ###  Hardware Configuration Options
 153
 154 There are some settings that you may need to configure, based on how the hardware is set up.
 155
 156 ```c
 157 #define MATRIX_ROW_PINS_RIGHT { <row pins> }
 158 #define MATRIX_COL_PINS_RIGHT { <col pins> }
 159 ```
 160
 161 This allows you to specify a different set of pins for the matrix on the right side.  This is useful if you have a board with differently-shaped halves that requires a different configuration (such as Keebio's Quefrency).
 162
 163
 164 ```c
 165 #define RGBLIGHT_SPLIT
 166 ```
 167
 168 This option enables synchronization of the RGB Light modes between the controllers of the split keyboard.  This is for keyboards that have RGB LEDs that are directly wired to the controller (that is, they are not using the "extra data" option on the TRRS cable).
 169
 170 ```c
 171 #define RGBLED_SPLIT { 6, 6 }
 172 ```
 173
 174 This sets how many LEDs are directly connected to each controller.  The first number is the left side, and the second number is the right side.
 175
 176 ?> This setting implies that `RGBLIGHT_SPLIT` is enabled, and will forcibly enable it, if it's not.
 177
 178
 179 ## Additional Resources
 180
 181 Nicinabox has a [very nice and detailed guide](https://github.com/nicinabox/lets-split-guide) for the Let's Split keyboard, that covers most everything you need to know, including troubleshooting information.
 182
 183 However, the RGB Light section is out of date, as it was written long before the RGB Split code was added to QMK Firmware. Instead, wire each strip up directly to the controller.
 184
 185 <!-- I may port this information later, but for now ... it's very nice, and covers everything -->