diff options
Diffstat (limited to 'docs/feature_split_keyboard.md')
-rw-r--r-- | docs/feature_split_keyboard.md | 52 |
1 files changed, 37 insertions, 15 deletions
diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index 99c252d03e..c39d0a7e08 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -8,20 +8,24 @@ QMK Firmware has a generic implementation that is usable by any board, as well a For this, we will mostly be talking about the generic implementation used by the Let's Split and other keyboards. -!> ARM split supports most QMK subsystems when using the 'serial' and 'serial_usart' drivers. I2C slave is currently unsupported. +::: warning +ARM split supports most QMK subsystems when using the 'serial' and 'serial_usart' drivers. I2C slave is currently unsupported. +::: -!> Both sides must use the same MCU family, for eg two Pro Micro-compatible controllers or two Blackpills. Currently, mixing AVR and ARM is not possible as ARM vs AVR uses different method for serial communication, and are not compatible. Moreover Blackpill's uses 3.3v logic, and atmega32u4 uses 5v logic. +::: warning +Both sides must use the same MCU family, for eg two Pro Micro-compatible controllers or two Blackpills. Currently, mixing AVR and ARM is not possible as ARM vs AVR uses different method for serial communication, and are not compatible. Moreover Blackpill's uses 3.3v logic, and atmega32u4 uses 5v logic. +::: ## Compatibility Overview | Transport | AVR | ARM | |------------------------------|--------------------|--------------------| -| ['serial'](serial_driver.md) | :heavy_check_mark: | :white_check_mark: <sup>1</sup> | +| ['serial'](serial_driver) | :heavy_check_mark: | :white_check_mark: <sup>1</sup> | | I2C | :heavy_check_mark: | | Notes: -1. Both hardware and software limitations are detailed within the [driver documentation](serial_driver.md). +1. Both hardware and software limitations are detailed within the [driver documentation](serial_driver). ## Hardware Configuration @@ -45,13 +49,17 @@ Another option is to use phone cables (as in, old school RJ-11/RJ-14 cables). Ma However, USB cables, SATA cables, and even just 4 wires have been known to be used for communication between the controllers. -!> 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. +::: warning +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. +::: ### Serial Wiring The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and D0/D1/D2/D3 (aka PD0/PD1/PD2/PD3) between the two Pro Micros. -?> Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below. +::: tip +Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below. +::: <img alt="sk-pd0-connection-mono" src="https://user-images.githubusercontent.com/2170248/92296488-28e9ad80-ef70-11ea-98be-c40cb48a0319.JPG" width="48%"/> <img alt="sk-pd2-connection-mono" src="https://user-images.githubusercontent.com/2170248/92296490-2d15cb00-ef70-11ea-801f-5ace313013e6.JPG" width="48%"/> @@ -160,9 +168,13 @@ Reset the right controller and run: qmk flash -kb crkbd/rev1 -km default -bl avrdude-split-right ``` -?> 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. +::: tip +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 +::: tip +[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 +::: This setting is not changed when re-initializing the EEPROM using the `EE_CLR` 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. @@ -183,7 +195,9 @@ If the USB cable is always connected to the left side, add the following to your #define MASTER_LEFT ``` -?> If neither options are defined, the handedness defaults to `MASTER_LEFT`. +::: tip +If neither options are defined, the handedness defaults to `MASTER_LEFT`. +::: ### Communication Options @@ -292,7 +306,9 @@ This enables transmitting the current ST7565 on/off status to the slave side of This enables transmitting the pointing device status to the master side of the split keyboard. The purpose of this feature is to enable use pointing devices on the slave side. -!> There is additional required configuration for `SPLIT_POINTING_ENABLE` outlined in the [pointing device documentation](feature_pointing_device.md?id=split-keyboard-configuration). +::: warning +There is additional required configuration for `SPLIT_POINTING_ENABLE` outlined in the [pointing device documentation](feature_pointing_device#split-keyboard-configuration). +::: ```c #define SPLIT_HAPTIC_ENABLE @@ -306,7 +322,7 @@ This enables the triggering of haptic feedback on the slave side of the split ke This synchronizes the activity timestamps between sides of the split keyboard, allowing for activity timeouts to occur. -### Custom data sync between sides :id=custom-data-sync +### Custom data sync between sides {#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. @@ -362,7 +378,9 @@ void housekeeping_task_user(void) { } ``` -!> It is recommended that any data sync between halves happens during the master side's _housekeeping task_. This ensures timely retries should failures occur. +::: warning +It is recommended that any data sync between halves happens during the master side's _housekeeping task_. This ensures timely retries should failures occur. +::: If only one-way data transfer is needed, helper methods are provided: @@ -381,7 +399,7 @@ By default, the inbound and outbound data is limited to a maximum of 32 bytes ea #define RPC_S2M_BUFFER_SIZE 48 ``` -### Hardware Configuration Options +### Hardware Configuration Options There are some settings that you may need to configure, based on how the hardware is set up. @@ -417,7 +435,9 @@ This option enables synchronization of the RGB Light modes between the controlle 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. -?> This setting implies that `RGBLIGHT_SPLIT` is enabled, and will forcibly enable it, if it's not. +::: tip +This setting implies that `RGBLIGHT_SPLIT` is enabled, and will forcibly enable it, if it's not. +::: ```c @@ -430,7 +450,9 @@ Without this option, the master is the half that can detect voltage on the physi Enabled by default on ChibiOS/ARM. -?> This setting will stop the ability to demo using battery packs. +::: tip +This setting will stop the ability to demo using battery packs. +::: ```c #define SPLIT_USB_TIMEOUT 2000 |