+ ## 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. @@ -33,7 +35,7 @@ On ARM platforms the bitbang driver causes connection issues when using it toget +-------+ +-------+ ``` -One GPIO pin is needed for the bitbang driver, as only one wire is used for receiving and transmitting data. This pin is referred to as the `SOFT_SERIAL_PIN` (SSP) in the configuration. A TRS or USB cable provides enough conductors for this driver to function. +One GPIO pin is needed for the bitbang driver, as only one wire is used for receiving and transmitting data. This pin is referred to as the `SOFT_SERIAL_PIN` (SSP) in the configuration. A TRS or USB cable provides enough conductors for this driver to function. ### Setup @@ -51,24 +53,20 @@ SERIAL_DRIVER = bitbang #define SOFT_SERIAL_PIN D0 // or D1, D2, D3, E6 ``` -3. On ARM platforms you must turn on ChibiOS PAL callbacks: +3. On ARM platforms you must turn on ChibiOS `PAL_USE_CALLBACKS` feature: -```c -#pragma once +* In `halconf.h` add the line `#define PAL_USE_CALLBACKS TRUE`. -#define PAL_USE_CALLBACKS TRUE // [!code focus] - -#include_next
## USART Half-duplex -Targeting ARM boards based on ChibiOS, where communication is offloaded to a USART hardware device that supports Half-duplex operation. The advantages over bitbanging are fast, accurate timings and reduced CPU usage. Therefore it is advised to choose Half-duplex over Bitbang if MCU is capable of utilising Half-duplex, and Full-duplex can't be used instead (e.g. lack of available GPIO pins, or incompatible PCB design). +Targeting ARM boards based on ChibiOS, where communication is offloaded to a USART hardware device that supports Half-duplex operation. The advantages over bitbanging are fast, accurate timings and reduced CPU usage. Therefore it is advised to choose Half-duplex over Bitbang if MCU is capable of utilising Half-duplex, and Full-duplex can't be used instead (e.g. lack of available GPIO pins, or imcompatible PCB design). ### Pin configuration ``` - LEFT RIGHT + LEFT RIGHT +-------+ | | +-------+ | | R R | | | | | SERIAL | | | @@ -80,7 +78,7 @@ Targeting ARM boards based on ChibiOS, where communication is offloaded to a USA +-------+ +-------+ ``` -Only one GPIO pin is needed for the Half-duplex driver, as only one wire is used for receiving and transmitting data. This pin is referred to as the `SERIAL_USART_TX_PIN` in the configuration. Ensure that the pin chosen for split communication can operate as the TX pin of the contoller's USART peripheral. A TRS or USB cable provides enough conductors for this driver to function. As the split connection is configured to operate in open-drain mode, an **external pull-up resistor is needed to keep the line high**. Resistor values of 1.5kΩ to 8.2kΩ are known to work. +Only one GPIO pin is needed for the Half-duplex driver, as only one wire is used for receiving and transmitting data. This pin is referred to as the `SERIAL_USART_TX_PIN` in the configuration. Ensure that the pin chosen for split communication can operate as the TX pin of the contoller's USART peripheral. A TRS or USB cable provides enough conductors for this driver to function. As the split connection is configured to operate in open-drain mode, an **external pull-up resistor is needed to keep the line high**. Resistor values of 1.5kΩ to 8.2kΩ are known to work. ::: warning ***Note:*** A pull-up resistor isn't required for RP2040 controllers configured with PIO subsystem. @@ -119,6 +117,8 @@ 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). +
+ ## 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,46 +179,38 @@ 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). +
+ ## 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. Enable the SERIAL subsystem in the ChibiOS HAL. +1. In your keyboards `halconf.h` add: - Add the following to your keyboard's `halconf.h`, creating it if necessary: +```c +#define HAL_USE_SERIAL TRUE +``` - ```c - #pragma once +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
+ ## Advanced Configuration There are several advanced configuration options that can be defined in your keyboards `config.h` file: ### Baudrate -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. +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 n +#define SELECT_SOFT_SERIAL_SPEED {#} ``` -Where *n* is one of: - | Speed | Bitbang | Half-duplex and Full-duplex | | ----- | -------------------------- | --------------------------- | | `0` | 189000 baud (experimental) | 460800 baud | @@ -305,21 +287,23 @@ This is the default time window in milliseconds in which a successful communicat #define SERIAL_USART_TIMEOUT 20 // USART driver timeout. default 20 ``` +
+ ## Troubleshooting -If you're having issues with 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: +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: ```c #define SERIAL_DEBUG ``` - + ::: tip The messages will be printed out to the `CONSOLE` output. For additional information, refer to [Debugging/Troubleshooting QMK](../faq_debug). ::: ## Alternate Functions for selected STM32 MCUs -Pins for USART Peripherals with +Pins for USART Peripherals with ### STM32F303 / Proton-C [Datasheet](https://www.st.com/resource/en/datasheet/stm32f303cc.pdf) diff --git a/docs/drivers/snled27351.md b/docs/drivers/snled27351.md index c0785711d9..1d91182f7c 100644 --- a/docs/drivers/snled27351.md +++ b/docs/drivers/snled27351.md @@ -52,7 +52,7 @@ Depending on the ChibiOS board configuration, you may need to [enable and config ## LED Mapping {#led-mapping} -In order to use this driver, each output must be mapped to an LED index, by adding the following to your `
Changing the **Saturation** moves between the inner and outer sections of the wheel, affecting the intensity of the color.
Changing the **Value** sets the overall brightness.
- + ## Keycodes -::: warning -These keycodes also simultaneously control [RGB Matrix](rgb_matrix), if enabled. This behaviour is in the process of being deprecated, so during this time it is recommended to additionally include the dedicated RGB Matrix keycodes to your keymap, and add `#define RGB_MATRIX_DISABLE_SHARED_KEYCODES` to `config.h`. -::: - |Key |Aliases |Description | |------------------------------|----------|---------------------------------------------------------------------| |`QK_UNDERGLOW_TOGGLE` |`UG_TOGG` |Toggle RGB lighting on or off | @@ -91,18 +87,24 @@ These keycodes also simultaneously control [RGB Matrix](rgb_matrix), if enabled. These keycodes cannot be used with functions like `tap_code16()` as they are not USB HID keycodes. If you wish to replicate similar behaviour in custom code within your firmware (e.g. inside `encoder_update_user()` or `process_record_user()`), the equivalent [RGB functions](#functions) should be used instead. ::: + +::: warning +By default, if you have both the RGB Light and the [RGB Matrix](rgb_matrix) feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature. +::: + ## Configuration Your RGB lighting can be configured by placing these `#define`s in your `config.h`: |Define |Default |Description | |---------------------------|----------------------------|---------------------------------------------------------------------------------------------------------------------------| -|`RGBLIGHT_HUE_STEP` |`8` |The value by which to increment the hue per adjustment action | -|`RGBLIGHT_SAT_STEP` |`17` |The value by which to increment the saturation per adjustment action | -|`RGBLIGHT_VAL_STEP` |`17` |The value by which to increment the brightness per adjustment action | +|`RGBLIGHT_HUE_STEP` |`8` |The number of steps to cycle through the hue by | +|`RGBLIGHT_SAT_STEP` |`17` |The number of steps to increment the saturation by | +|`RGBLIGHT_VAL_STEP` |`17` |The number of steps to increment the brightness by | |`RGBLIGHT_LIMIT_VAL` |`255` |The maximum brightness level | |`RGBLIGHT_SLEEP` |*Not defined* |If defined, the RGB lighting will be switched off when the host goes to sleep | |`RGBLIGHT_SPLIT` |*Not defined* |If defined, synchronization functionality for split keyboards is added | +|`RGBLIGHT_DISABLE_KEYCODES`|*Not defined* |If defined, disables the ability to control RGB Light from the keycodes. You must use code functions to control the feature| |`RGBLIGHT_DEFAULT_MODE` |`RGBLIGHT_MODE_STATIC_LIGHT`|The default mode to use upon clearing the EEPROM | |`RGBLIGHT_DEFAULT_HUE` |`0` (red) |The default hue to use upon clearing the EEPROM | |`RGBLIGHT_DEFAULT_SAT` |`UINT8_MAX` (255) |The default saturation to use upon clearing the EEPROM | diff --git a/docs/features/space_cadet.md b/docs/features/space_cadet.md index 66761f5a46..0abdaebf33 100644 --- a/docs/features/space_cadet.md +++ b/docs/features/space_cadet.md @@ -32,7 +32,7 @@ COMMAND_ENABLE = no ## Configuration -By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`. In addition, you can redefine the modifier to send on tap, or even send no modifier at all. The new configuration defines bundle all options up into a single define of 3 key codes in this order: the `Modifier` when held or when used with other keys, the `Tap Modifier` sent when tapped (no modifier if `KC_TRNS`), finally the `Keycode` sent when tapped. Now keep in mind, mods from other keys will still apply to the `Keycode` if say `KC_RSFT` is held while tapping `SC_LSPO` key with `KC_TRNS` as the `Tap Modifier`. +By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`. In addition, you can redefine the modifier to send on tap, or even send no modifier at all. The new configuration defines bundle all options up into a single define of 3 key codes in this order: the `Modifier` when held or when used with other keys, the `Tap Modifer` sent when tapped (no modifier if `KC_TRNS`), finally the `Keycode` sent when tapped. Now keep in mind, mods from other keys will still apply to the `Keycode` if say `KC_RSFT` is held while tapping `SC_LSPO` key with `KC_TRNS` as the `Tap Modifer`. |Define |Default |Description | |----------------|-------------------------------|---------------------------------------------------------------------------------| diff --git a/docs/features/split_keyboard.md b/docs/features/split_keyboard.md index a6fbad1c8f..49582c3946 100644 --- a/docs/features/split_keyboard.md +++ b/docs/features/split_keyboard.md @@ -1,12 +1,12 @@ -# Split Keyboard +# Split Keyboard -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 I2C connection over a TRRS or similar cable. +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 I2C connection over a TRRS or similar cable. -Split keyboards can have a lot of benefits, but there is some additional work needed to get them enabled. +Split keyboards can have a lot of benefits, but there is some additional work needed to get them enabled. -QMK Firmware has a generic implementation that is usable by any board, as well as numerous board specific implementations. +QMK Firmware has a generic implementation that is usable by any board, as well as numerous board specific implementations. -For this, we will mostly be talking about the generic implementation used by the Let's Split and other keyboards. +For this, we will mostly be talking about the generic implementation used by the Let's Split and other keyboards. ::: warning ARM split supports most QMK subsystems when using the 'serial' and 'serial_usart' drivers. I2C slave is currently unsupported. @@ -29,33 +29,33 @@ Notes: ## Hardware Configuration -This assumes that you're using two Pro Micro-compatible controllers, and are using TRRS jacks to connect to two halves. +This assumes that you're using two Pro Micro-compatible controllers, and are using TRRS jacks to connect to two halves. ### Required Hardware Apart from diodes and key switches for the keyboard matrix in each half, you will need 2x TRRS sockets and 1x TRRS cable. -Alternatively, you can use any sort of cable and socket that has at least 3 wires. +Alternatively, you can use any sort of cable and socket that has at least 3 wires. If you want to use I2C to communicate between halves, you will need a cable with at least 4 wires and 2x 4.7kΩ pull-up resistors. -#### Considerations +#### Considerations -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. +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. -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. +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. -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. +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. -However, USB cables, SATA cables, and even just 4 wires have been known to be used for communication between the controllers. +However, USB cables, SATA cables, and even just 4 wires have been known to be used for communication between the controllers. ::: 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. +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. +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. ::: tip Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below. @@ -66,7 +66,7 @@ Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below. ### I2C Wiring -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. +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. The pull-up resistors may be placed on either half. If you wish to use the halves independently, it is also possible to use 4 resistors and have the pull-ups in both halves. Note that the total resistance for the connected system should be within spec at 2.2k-10kOhm, with an 'ideal' at 4.7kOhm, regardless of the placement and number. @@ -75,13 +75,13 @@ Note that the total resistance for the connected system should be within spec at ## Firmware Configuration -To enable the split keyboard feature, add the following to your `rules.mk`: +To enable the split keyboard feature, add the following to your `rules.mk`: ```make SPLIT_KEYBOARD = yes ``` -If you're using a custom transport (communication method), then you will also need to add: +If you're using a custom transport (communication method), then you will also need to add: ```make SPLIT_TRANSPORT = custom @@ -91,11 +91,11 @@ SPLIT_TRANSPORT = custom 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: - + 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: - + ### Setting Handedness @@ -109,7 +109,7 @@ You can configure the firmware to read a pin on the controller to determine hand #define SPLIT_HAND_PIN B7 ``` -This will read the specified pin. By default, 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. +This will read the specified pin. By default, 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. This behaviour can be flipped by adding this to you `config.h` file: @@ -141,10 +141,10 @@ While `MATRIX_MASKED` isn't necessary to use `SPLIT_HAND_MATRIX_GRID` successful #### Handedness by EEPROM -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. +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. -To enable this method, add the following to your `config.h` file: +To enable this method, add the following to your `config.h` file: ```c #define EE_HANDS @@ -176,7 +176,7 @@ Some controllers (e.g. Blackpill with DFU compatible bootloader) will need to be [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases/) 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](https://github.com/qmk/qmk_toolbox/releases/)'s "Reset EEPROM" button works), you'll need to re-flash the controller with the `EEPROM` files. +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](https://github.com/qmk/qmk_toolbox/releases/)'s "Reset EEPROM" button works), you'll need to re-flash the controller with the `EEPROM` files. You can find the `EEPROM` files in the QMK firmware repo, [here](https://github.com/qmk/qmk_firmware/tree/master/quantum/split_common). @@ -208,13 +208,13 @@ Because not every split keyboard is identical, there are a number of additional #define USE_I2C ``` -This configures the use of I2C support for split keyboard transport (AVR only). +This configures the use of I2C support for split keyboard transport (AVR only). ```c #define SOFT_SERIAL_PIN D0 ``` -This sets the pin to be used for serial communication. If you're not using serial, you shouldn't need to define this. +This sets the pin to be used for serial communication. If you're not using serial, you shouldn't need to define this. However, if you are using serial and I2C on the board, you will need to set this, and to something other than D0 and D1 (as these are used for I2C communication). @@ -235,7 +235,7 @@ If you're having issues with serial communication, you can change this value, as #define FORCED_SYNC_THROTTLE_MS 100 ``` -This sets the maximum number of milliseconds before forcing a synchronization of data from master to slave. Under normal circumstances this sync occurs whenever the data _changes_, for safety a data transfer occurs after this number of milliseconds if no change has been detected since the last sync. +This sets the maximum number of milliseconds before forcing a synchronization of data from master to slave. Under normal circumstances this sync occurs whenever the data _changes_, for safety a data transfer occurs after this number of milliseconds if no change has been detected since the last sync. ```c #define SPLIT_MAX_CONNECTION_ERRORS 10 @@ -249,7 +249,7 @@ Set to 0 to disable the disconnection check altogether. ``` How long (in milliseconds) the master part should block all connection attempts to the slave after the communication has been flagged as disconnected (see `SPLIT_MAX_CONNECTION_ERRORS` above). -One communication attempt will be allowed every time this amount of time has passed since the last attempt. If that attempt succeeds, the communication is seen as working again. +One communication attempt will be allowed everytime this amount of time has passed since the last attempt. If that attempt succeeds, the communication is seen as working again. Set to 0 to disable this throttling of communications while disconnected. This can save you a couple of bytes of firmware size. @@ -280,7 +280,7 @@ This enables syncing of the Host LED status (caps lock, num lock, etc) between b #define SPLIT_MODS_ENABLE ``` -This enables transmitting modifier state (normal, weak, oneshot and oneshot locked) to the non primary side of the split keyboard. The purpose of this feature is to support cosmetic use of modifier state (e.g. displaying status on an OLED screen). +This enables transmitting modifier state (normal, weak, oneshot and oneshot locked) to the non primary side of the split keyboard. The purpose of this feature is to support cosmetic use of modifer state (e.g. displaying status on an OLED screen). ```c #define SPLIT_WPM_ENABLE @@ -304,7 +304,7 @@ This enables transmitting the current ST7565 on/off status to the slave side of #define SPLIT_POINTING_ENABLE ``` -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. +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. ::: warning There is additional required configuration for `SPLIT_POINTING_ENABLE` outlined in the [pointing device documentation](pointing_device#split-keyboard-configuration). @@ -401,7 +401,7 @@ By default, the inbound and outbound data is limited to a maximum of 32 bytes ea ### Hardware Configuration Options -There are some settings that you may need to configure, based on how the hardware is set up. +There are some settings that you may need to configure, based on how the hardware is set up. ```c #define MATRIX_ROW_PINS_RIGHT {
+
| Board | Controller | # I/O |
| :------------ |:-------------:| ------:|
@@ -74,13 +74,13 @@ Established materials and techniques include:
| Technique | Examples | Pros | Cons | Image
| :-----------| :------- | :------ | :--- | :---
-| Lengths of wire with stripped segments | [Sasha Solomon's Dactyl](https://medium.com/@sachee/building-my-first-keyboard-and-you-can-too-512c0f8a4c5f) and [Cribbit's modern hand wire](https://geekhack.org/index.php?topic=87689.0) | Neat and tidy | Some effort in stripping the wire | 
-| Short lengths of wire | [u/xicolinguada's ortho build](https://www.reddit.com/r/MechanicalKeyboards/comments/c39k4f/my_first_hand_wired_keyboard_its_not_perfect_but/) | Easier to strip the wire | More difficult to place | 
-| Magnet/Enamelled wire | [fknraiden's custom board](https://geekhack.org/index.php?topic=74223.0) | Can be directly soldered onto (insulation burns off with heat) | Appearance? | 
-| Bending the legs of the diodes for the rows | [Matt3o's Brownfox](https://deskthority.net/viewtopic.php?f=7&t=6050) | Fewer solder joints required | Uninsulated | 
-| Using rigid wiring (e.g. brass tube) | [u/d_stilgar's invisible hardline](https://www.reddit.com/r/MechanicalKeyboards/comments/8aw5j2/invisible_hardline_keyboard_progress_update_april/) and [u/jonasfasler's first attempt](https://www.reddit.com/r/MechanicalKeyboards/comments/de1jyv/my_first_attempt_at_handwiring_a_keyboard/) | Very pretty | More difficult. No physical insulation | 
-| Bare wire with insulation added after (e.g. kapton tape) | [Matt3o's 65% on his website](https://matt3o.com/hand-wiring-a-custom-keyboard/) | Easier (no wire stripping required) | Not as attractive | 
-| Copper tape | [ManuForm Dactyl](https://github.com/tshort/dactyl-keyboard) | Very easy | Only really works when your plate/case aligns with the bottom of your switches | 
+| Lengths of wire with stripped segments | [Sasha Solomon's Dactyl](https://medium.com/@sachee/building-my-first-keyboard-and-you-can-too-512c0f8a4c5f) and [Cribbit's modern hand wire](https://geekhack.org/index.php?topic=87689.0) | Neat and tidy | Some effort in stripping the wire | 
+| Short lengths of wire | [u/xicolinguada's ortho build](https://www.reddit.com/r/MechanicalKeyboards/comments/c39k4f/my_first_hand_wired_keyboard_its_not_perfect_but/) | Easier to strip the wire | More difficult to place | 
+| Magnet/Enamelled wire | [fknraiden's custom board](https://geekhack.org/index.php?topic=74223.0) | Can be directly soldered onto (insulation burns off with heat) | Appearance? | 
+| Bending the legs of the diodes for the rows | [Matt3o's Brownfox](https://deskthority.net/viewtopic.php?f=7&t=6050) | Fewer solder joints required | Uninsulated | 
+| Using rigid wiring (e.g. brass tube) | [u/d_stilgar's invisible hardline](https://www.reddit.com/r/MechanicalKeyboards/comments/8aw5j2/invisible_hardline_keyboard_progress_update_april/) and [u/jonasfasler's first attempt](https://www.reddit.com/r/MechanicalKeyboards/comments/de1jyv/my_first_attempt_at_handwiring_a_keyboard/) | Very pretty | More difficult. No physical insulation | 
+| Bare wire with insulation added after (e.g. kapton tape) | [Matt3o's 65% on his website](https://matt3o.com/hand-wiring-a-custom-keyboard/) | Easier (no wire stripping required) | Not as attractive | 
+| Copper tape | [ManuForm Dactyl](https://github.com/tshort/dactyl-keyboard) | Very easy | Only really works when your plate/case aligns with the bottom of your switches | 
Note that these methods can be combined. Prepare your lengths of wire before moving on to soldering.
@@ -97,11 +97,11 @@ There are a lot of soldering guides and tips available elsewhere but here are so
To ensure a strong solder joint you want a good amount of contact between the solder and the two pieces of metal you are connecting. A good way of doing this (though not required) is looping around pins or twisting wires together before applying solder.
-
+
If your diodes are on a packaging strip and need a bend in them (either the start of a loop or for connecting to its neighbour) this can easily done by bending it over something straight like the edge of a box, table, or ruler. This also helps keep track of the direction of the diode as all the bends will be on the same side.
-
+
If your iron has temperature control, set it to 315ºC (600ºF).
@@ -162,9 +162,9 @@ The pins you'll absolutely have to avoid, as with any controller, are: GND, VCC,
Cut wires to the length of the distance from the a point on each column/row to the controller. You can solder anywhere along the row, as long as it's after the diode - soldering before the diode (on the keyswitch side) will cause that row not to work.
-Ribbon cable can be used to keep this extra tidy. You may also want to consider routing the wires beneath the existing columns/rows.
+Ribbon cable can be used to keep this extra tidy. You may also want to consider routing the wires beneath the exisiting columns/rows.
-
+
As you solder the wires to the controller make a note of which row/column is going to which pin on the controller as we'll use this data to setup the matrix when we create the firmware.
@@ -188,7 +188,7 @@ qmk import-kbfirmware /path/to/export.json
For example:
```
-$ qmk import-kbfirmware ~/Downloads/gh62.json
+$ qmk import-kbfirmware ~/Downloads/gh62.json
Ψ Importing gh62.json.
⚠ Support here is basic - Consider using 'qmk new-keyboard' instead
@@ -227,16 +227,16 @@ If you've done all of these things, keep in mind that sometimes you might have h
## Finishing up
-Once you have confirmed that the keyboard is working, if you have used a separate (non handwire specific) controller you will want to secure it in place. This can be done in many different ways e.g. hot glue, double sided sticky tape, 3D printed caddy, electrical tape.
+Once you have confirmed that the keyboard is working, if you have used a seperate (non handwire specific) controller you will want to secure it in place. This can be done in many different ways e.g. hot glue, double sided sticky tape, 3D printed caddy, electrical tape.
-If you found this fulfilling you could experiment by adding additional features such as [in switch LEDs](https://geekhack.org/index.php?topic=94258.0), [in switch RGB](https://www.reddit.com/r/MechanicalKeyboards/comments/5s1l5u/photoskeyboard_science_i_made_a_handwired_rgb/), [RGB underglow](https://medium.com/@DavidNZ/hand-wired-custom-keyboard-cdd14429c7b3#.7a1ovebsk) or even an [OLED display!](https://www.reddit.com/r/olkb/comments/5zy7og/adding_ssd1306_oled_display_to_your_build/)
+If you found this fullfilling you could experiment by adding additional features such as [in switch LEDs](https://geekhack.org/index.php?topic=94258.0), [in switch RGB](https://www.reddit.com/r/MechanicalKeyboards/comments/5s1l5u/photoskeyboard_science_i_made_a_handwired_rgb/), [RGB underglow](https://medium.com/@DavidNZ/hand-wired-custom-keyboard-cdd14429c7b3#.7a1ovebsk) or even an [OLED display!](https://www.reddit.com/r/olkb/comments/5zy7og/adding_ssd1306_oled_display_to_your_build/)
-There are a lot of possibilities inside the firmware - explore [the documentation](/) for a full feature list, and dive into the different keyboards to see how people use all of them. You can always stop by [the OLKB subreddit](https://reddit.com/r/olkb) or [QMK Discord](https://discord.gg/qmk) for help!
+There are a lot of possibilities inside the firmware - explore [docs.qmk.fm](https://docs.qmk.fm) for a full feature list, and dive into the different keyboards to see how people use all of them. You can always stop by [the OLKB subreddit](https://reddit.com/r/olkb) or [QMK Discord](https://discord.gg/Uq7gcHh) for help!
## Links to Other Guides
- [matt3o's step by step guide (BrownFox build)](https://deskthority.net/viewtopic.php?f=7&t=6050) also his [website](https://matt3o.com/hand-wiring-a-custom-keyboard/) and [video guide](https://www.youtube.com/watch?v=LVzpsjFWPP4)
-- [Cribbit's "Modern hand wiring guide - stronger, cleaner, easier"](https://geekhack.org/index.php?topic=87689.0)
+- [Cribbit's "Modern hand wiring guide - stronger, cleaner, easier"](https://geekhack.org/index.php?topic=87689.0)
- [Sasha Solomon's "Building my first Keyboard"](https://medium.com/@sachee/building-my-first-keyboard-and-you-can-too-512c0f8a4c5f)
- [RoastPotatoes' "How to hand wire a Planck"](https://blog.roastpotatoes.co/guide/2015/11/04/how-to-handwire-a-planck/)
- [Masterzen's "Handwired keyboard build log"](https://www.masterzen.fr/2018/12/16/handwired-keyboard-build-log-part-1/)
diff --git a/docs/hardware_drivers.md b/docs/hardware_drivers.md
index 40a25d9fa7..694d46971a 100644
--- a/docs/hardware_drivers.md
+++ b/docs/hardware_drivers.md
@@ -24,7 +24,7 @@ Support for WS2811/WS2812{a,b,c} LED's. For more information see the [RGB Light]
## IS31FL3731
-Support for up to 2 drivers. Each driver implements 2 charlieplex matrices to individually address LEDs using I2C. This allows up to 144 same color LEDs or 32 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](features/rgb_matrix) page.
+Support for up to 2 drivers. Each driver impliments 2 charlieplex matrices to individually address LEDs using I2C. This allows up to 144 same color LEDs or 32 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](features/rgb_matrix) page.
## IS31FL3733
diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md
index 0b8f35a373..de67fa3bc3 100644
--- a/docs/hardware_keyboard_guidelines.md
+++ b/docs/hardware_keyboard_guidelines.md
@@ -44,11 +44,7 @@ QMK uses sub-folders both for organization and to share code between revisions o
qmk_firmware/keyboards/top_folder/sub_1/sub_2/sub_3/sub_4
```
-If a sub-folder has a `keyboard.json` file it will be considered a compilable keyboard. It will be available in QMK Configurator and tested with `make all`. If you are using a folder to organize several keyboards from the same maker you should not have a `keyboard.json` file.
-
-::: tip
-When configuring a keyboard with multiple revisions (like the `clueboard/66` example below), an `info.json` file at the top keyboard level (eg. `clueboard/66`) should be used for configuration shared between revisions. Then `keyboard.json` in each revision directory containing revision-specific configuration, and indicating a buildable keyboard.
-:::
+If a sub-folder has a `rules.mk` file it will be considered a compilable keyboard. It will be available in QMK Configurator and tested with `make all`. If you are using a folder to organize several keyboards from the same maker you should not have a `rules.mk` file.
Example:
@@ -56,49 +52,35 @@ Clueboard uses sub-folders for both purposes, organization and keyboard revision
* [`qmk_firmware`](https://github.com/qmk/qmk_firmware/tree/master)
* [`keyboards`](https://github.com/qmk/qmk_firmware/tree/master/keyboards)
- * [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard) ← This is the organization folder, there's no `keyboard.json` file
- * [`60`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/60) ← This is a compilable keyboard - it has a `keyboard.json` file
- * [`66`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66) ← This is not a compilable keyboard - a revision must be specified
+ * [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard) ← This is the organization folder, there's no `rules.mk` file
+ * [`60`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/60) ← This is a compilable keyboard, it has a `rules.mk` file
+ * [`66`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66) ← This is also compilable- it uses `DEFAULT_FOLDER` to specify `rev3` as the default revision
* [`rev1`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev1) ← compilable: `make clueboard/66/rev1`
* [`rev2`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev2) ← compilable: `make clueboard/66/rev2`
- * [`rev3`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev3) ← compilable: `make clueboard/66/rev3`
+ * [`rev3`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev3) ← compilable: `make clueboard/66/rev3` or `make clueboard/66`
## Keyboard Folder Structure
-Your keyboard should be located in `qmk_firmware/keyboards/` and the folder name should be your keyboard's name as described in the previous section. Inside this folder should be several files, some of which are optional:
+Your keyboard should be located in `qmk_firmware/keyboards/` and the folder name should be your keyboard's name as described in the previous section. Inside this folder should be several files:
* `readme.md`
-* `keyboard.json` (or `info.json`)
+* `info.json`
* `config.h`
* `rules.mk`
-* `
+
#### Features
diff --git a/docs/platformdev_rp2040.md b/docs/platformdev_rp2040.md
index 346cae58dc..1269ffeeb5 100644
--- a/docs/platformdev_rp2040.md
+++ b/docs/platformdev_rp2040.md
@@ -17,8 +17,8 @@ The following table shows the current driver status for peripherals on RP2040 MC
## GPIO
-
-
+
+
::: warning
The GPIO pins of the RP2040 are not 5V tolerant!
diff --git a/docs/porting_your_keyboard_to_qmk.md b/docs/porting_your_keyboard_to_qmk.md
index 108576cb58..eb45790128 100644
--- a/docs/porting_your_keyboard_to_qmk.md
+++ b/docs/porting_your_keyboard_to_qmk.md
@@ -4,51 +4,52 @@ This page describes the support for [Compatible Microcontrollers](compatible_mic
If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_guidelines) to get a sense of how keyboards fit into QMK.
+
QMK has a number of features to simplify working with keyboards. For most, you don't have to write a single line of code. To get started, run `qmk new-keyboard`:
```
$ qmk new-keyboard
Ψ Generating a new QMK keyboard directory
-Ψ Name Your Keyboard Project
-Ψ For more information, see:
-https://docs.qmk.fm/hardware_keyboard_guidelines#naming-your-keyboard-project
-Keyboard Name? mycoolkeeb
-Ψ Attribution
-Ψ Used for maintainer, copyright, etc.
-Your GitHub Username? [jsmith]
-Ψ More Attribution
-Ψ Used for maintainer, copyright, etc.
-Your Real Name? [John Smith]
-Ψ Pick Base Layout
-Ψ As a starting point, one of the common layouts can be used to
-bootstrap the process
-Default Layout?
- 1. 60_abnt2
- ...
- 65. none of the above
-Please enter your choice: [65]
-Ψ What Powers Your Project
-Ψ Is your board using a separate development board, such as a Pro Micro,
-or is the microcontroller integrated onto the PCB?
+Name Your Keyboard Project
+For more infomation, see:
+https://docs.qmk.fm/hardware_keyboard_guidelines#naming-your-keyboardproject
-For more information, see:
-https://docs.qmk.fm/compatible_microcontrollers
-Using a Development Board? [y/n] y
-Ψ Select Development Board
-Ψ For more information, see:
-https://docs.qmk.fm/compatible_microcontrollers
-Development Board?
- 1. bit_c_pro
- ...
- 14. promicro
- ...
- 18. svlinky
-Please enter your choice: [14]
+keyboard Name? mycoolkeeb
+
+Attribution
+Used for maintainer, copyright, etc
+
+Your GitHub Username? [jsmith]
+
+More Attribution
+Used for maintainer, copyright, etc
+
+Your Real Name? [John Smith]
+
+Pick Base Layout
+As a starting point, one of the common layouts can be used to bootstrap the process
+
+Default Layout?
+ 1. 60_ansi
+...
+ 50. tkl_iso
+ 51. none of the above
+Please enter your choice: [51]
+
+What Powers Your Project
+For more infomation, see:
+https://docs.qmk.fm/#/compatible_microcontrollers
+
+MCU?
+ 1. atmega32u4
+...
+ 22. STM32F303
+Please enter your choice: [12]
Ψ Created a new keyboard called mycoolkeeb.
-Ψ Build Command: qmk compile -kb mycoolkeeb -km default.
-Ψ Project Location: /Users/jsmith/qmk_firmware/keyboards/mycoolkeeb.
-Ψ Now update the config files to match the hardware!
+Ψ To start working on things, `cd` into keyboards/mycoolkeeb,
+Ψ or open the directory in your preferred text editor.
+Ψ And build with qmk compile -kb mycoolkeeb -km default.
```
This will create all the files needed to support your new keyboard, and populate the settings with default values. Now you just need to customize it for your keyboard.
@@ -57,13 +58,13 @@ This will create all the files needed to support your new keyboard, and populate
This is where you'll describe your keyboard. Please follow the [Keyboard Readme Template](documentation_templates#keyboard-readmemd-template) when writing your `readme.md`. You're encouraged to place an image at the top of your `readme.md`, please use an external service such as [Imgur](https://imgur.com) to host the images.
-## `keyboard.json`
+## `info.json`
-The `keyboard.json` file is where you configure the hardware and feature set for your keyboard. There are a lot of options that can be placed in that file, too many to list here. For a complete overview of available options see the [Data Driven Configuration Options](reference_info_json) page.
+The `info.json` file is where you configure the hardware and feature set for your keyboard. There are a lot of options that can be placed in that file, too many to list here. For a complete overview of available options see the [Data Driven Configuration Options](reference_info_json) page.
### Hardware Configuration
-At the top of the `keyboard.json` you'll find USB related settings. These control how your keyboard appears to the Operating System. If you don't have a good reason to change you should leave the `usb.vid` as `0xFEED`. For the `usb.pid` you should pick a number that is not yet in use.
+At the top of the `info.json` you'll find USB related settings. These control how your keyboard appears to the Operating System. If you don't have a good reason to change you should leave the `usb.vid` as `0xFEED`. For the `usb.pid` you should pick a number that is not yet in use.
Do change the `manufacturer` and `keyboard_name` lines to accurately reflect your keyboard.
@@ -81,11 +82,10 @@ Do change the `manufacturer` and `keyboard_name` lines to accurately reflect you
Windows and macOS will display the `manufacturer` and `keyboard_name` in the list of USB devices. `lsusb` on Linux instead prefers the values in the list maintained by the [USB ID Repository](http://www.linux-usb.org/usb-ids.html). By default, it will only use `manufacturer` and `keyboard_name` if the list does not contain that `usb.vid` / `usb.pid`. `sudo lsusb -v` will show the values reported by the device, and they are also present in kernel logs after plugging it in.
:::
+
### Matrix Configuration
-The next section of the `keyboard.json` deals with your keyboard's matrix. The first thing you should define is which pins on your MCU are connected to rows and columns. To do so simply specify the names of those pins:
-
-#### Diode Matrix
+The next section of the `info` file deals with your keyboard's matrix. The first thing you should define is which pins on your MCU are connected to rows and columns. To do so simply specify the names of those pins:
```json
"matrix_pins": {
@@ -94,7 +94,7 @@ The next section of the `keyboard.json` deals with your keyboard's matrix. The f
},
```
-The matrix dimensions are inferred from the length of the `matrix_pins.cols` and `matrix_pins.rows` arrays (previously specified explicitly in `config.h` with `MATRIX_ROWS` and `MATRIX_COLS`).
+The size of the `matrix_pins.cols` and `matrix_pins.rows` arrays infer the size of the matrix (previously `MATRIX_ROWS` and `MATRIX_COLS`).
Finally, you can specify the direction your diodes point. This can be `COL2ROW` or `ROW2COL`.
@@ -103,56 +103,54 @@ Finally, you can specify the direction your diodes point. This can be `COL2ROW`
```
#### Direct Pin Matrix
-
-To configure a keyboard where each switch is connected to a separate pin and ground instead of sharing row and column pins, use `matrix_pins.direct`. This overrides the behaviour of `diode_direction`, `matrix_pins.cols` and `matrix_pins.rows`, and they should not be specified together.
+To configure a keyboard where each switch is connected to a separate pin and ground instead of sharing row and column pins, use `matrix_pins.direct`. The mapping defines the pins of each switch in rows and columns, from left to right. The size of the `matrix_pins.direct` array infers the size of the matrix. Use `NO_PIN` to fill in blank spaces. Overrides the behaviour of `diode_direction`, `matrix_pins.cols` and `matrix_pins.rows`.
```json
"matrix_pins": {
"direct": [
- ["F1", "E6", "B0", "B2", "B3"],
- ["F5", "F0", "B1", "B7", "D2"],
- ["F6", "F7", "C7", "D5", "D3"],
- ["B5", "C6", "B6", null, null]
+ ["F1", "E6", "B0", "B2", "B3" ],
+ ["F5", "F0", "B1", "B7", "D2" ],
+ ["F6", "F7", "C7", "D5", "D3" ],
+ ["B5", "C6", "B6", "NO_PIN", "NO_PIN"]
]
},
```
-Here, the matrix dimensions are inferred directly from the dimensions of the `matrix_pins.direct` array. Since there are no row or column pins to prescribe the matrix dimensions, you can arrange it however you like. Each "row" must contain the same number of "column"s; use `null` to fill in blank spaces, but try to minimize them.
+### Layout macros
-### Layout Macros
-
-Next is configuring layout macro(s). These define the physical arrangement of keys, and their position within the matrix that switches are connected to. This allows you to have a physical arrangement of keys that differs from the wiring matrix.
+Next is configuring Layout Macro(s). These define the physical arrangement of keys, and its position within the matrix that a switch are connected to. This allows you to have a physical arrangement of keys that differs from the wiring matrix.
```json
"layouts": {
"LAYOUT_ortho_4x4": {
"layout": [
- {"matrix": [0, 0], "x": 0, "y": 0},
- {"matrix": [0, 1], "x": 1, "y": 0},
- {"matrix": [0, 2], "x": 2, "y": 0},
- {"matrix": [0, 3], "x": 3, "y": 0},
- {"matrix": [1, 0], "x": 0, "y": 1},
- {"matrix": [1, 1], "x": 1, "y": 1},
- {"matrix": [1, 2], "x": 2, "y": 1},
- {"matrix": [1, 3], "x": 3, "y": 1},
- {"matrix": [2, 0], "x": 0, "y": 2},
- {"matrix": [2, 1], "x": 1, "y": 2},
- {"matrix": [2, 2], "x": 2, "y": 2},
- {"matrix": [2, 3], "x": 3, "y": 2},
- {"matrix": [3, 0], "x": 0, "y": 3},
- {"matrix": [3, 1], "x": 1, "y": 3},
- {"matrix": [3, 2], "x": 2, "y": 3},
- {"matrix": [3, 3], "x": 3, "y": 3}
+ { "matrix": [0, 0], "x": 0, "y": 0 },
+ { "matrix": [0, 1], "x": 1, "y": 0 },
+ { "matrix": [0, 2], "x": 2, "y": 0 },
+ { "matrix": [0, 3], "x": 3, "y": 0 },
+ { "matrix": [1, 0], "x": 0, "y": 1 },
+ { "matrix": [1, 1], "x": 1, "y": 1 },
+ { "matrix": [1, 2], "x": 2, "y": 1 },
+ { "matrix": [1, 3], "x": 3, "y": 1 },
+ { "matrix": [2, 0], "x": 0, "y": 2 },
+ { "matrix": [2, 1], "x": 1, "y": 2 },
+ { "matrix": [2, 2], "x": 2, "y": 2 },
+ { "matrix": [2, 3], "x": 3, "y": 2 },
+ { "matrix": [3, 0], "x": 0, "y": 3 },
+ { "matrix": [3, 1], "x": 1, "y": 3 },
+ { "matrix": [3, 2], "x": 2, "y": 3 },
+ { "matrix": [3, 3], "x": 3, "y": 3 }
]
}
}
+
```
-In the above example,
+In the above example,
* `LAYOUT_ortho_4x4` defines the name of the layout macro
- * It must conform to the [layout guidelines](hardware_keyboard_guidelines#keyboard-name-h)
-* `"matrix": [0, 0]` defines the matrix row and column that the key is associated with
+ * It must conform to the [layout guidelines](hardware_keyboard_guidelines#ltkeyboard_namehgt)
+* `"matrix": [0, 0]` defines the electrical position
::: tip
See also: [Split Keyboard Layout Macro](features/split_keyboard#layout-macro) and [Matrix to Physical Layout](understanding_qmk#matrix-to-physical-layout-map).
@@ -160,11 +158,10 @@ See also: [Split Keyboard Layout Macro](features/split_keyboard#layout-macro) an
## Additional Configuration
-There are a lot of features that can be turned on or off, configured or tuned. Some of these have yet to be migrated over to [Data Driven Configuration](data_driven_config). The following sections cover the process for when a data-driven option is unavailable.
+There are a lot of features that can be turned on or off, configured or tuned. Some of these have yet to be migrated over to [Data Driven Configuration](data_driven_config). The following sections cover the process for when an `info.json` option is unavailable.
### Configuration Options
-
-For available options for `config.h`, you should see the [Config Options](config_options#the-config-h-file) page for more details.
+For available options for `config.h`, you should see the [Config Options](config_options#the-configh-file) page for more details.
### Build Options
diff --git a/docs/pr_checklist.md b/docs/pr_checklist.md
index 61119178bb..e0b0810aef 100644
--- a/docs/pr_checklist.md
+++ b/docs/pr_checklist.md
@@ -2,7 +2,7 @@
This is a non-exhaustive checklist of what the QMK Collaborators will be checking when reviewing submitted PRs.
-If there are any inconsistencies with these recommendations, you're best off [creating an issue](https://github.com/qmk/qmk_firmware/issues/new) against this document, or getting in touch with a QMK Collaborator on [Discord](https://discord.gg/qmk).
+If there are any inconsistencies with these recommendations, you're best off [creating an issue](https://github.com/qmk/qmk_firmware/issues/new) against this document, or getting in touch with a QMK Collaborator on [Discord](https://discord.gg/Uq7gcHh).
## Requirements for all PRs
@@ -44,14 +44,12 @@ If there are any inconsistencies with these recommendations, you're best off [cr
Note that personal keymap submissions will no longer be accepted. This section applies to manufacturer-supported keymaps. Please see this [issue](https://github.com/qmk/qmk_firmware/issues/22724) for more information.
:::
-- PRs for vendor specific keymaps will be permitted. The naming convention for these should be `default_${vendor}` i.e. `default_clueboard`.
- - vendor specific keymaps do not necessarily need to be "vanilla" and can be more richly featured than `default` stock keymaps.
+- PRs for vendor specific keymaps will be permitted. The naming convention for these should be `default_${vendor}`, `via_${vendor}` i.e. `via_clueboard`.
+ - vendor specific keymaps do not necessarily need to be "vanilla" and can be more richly featured than `default` or `via` stock keymaps.
- `#include QMK_KEYBOARD_H` preferred to including specific board files
- prefer layer enums to #defines
- custom keycode enums must have first entry = `QK_USER`
- some care with spacing (e.g., alignment on commas or first char of keycodes) makes for a much nicer-looking keymap. Spaces are preferred to tabs
-- keymaps should not enable VIA
- - keymaps targeting VIA support should be submitted to the [VIA QMK Userspace](https://github.com/the-via/qmk_userspace_via) repository
## Keyboard PRs
@@ -127,8 +125,7 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
- empty `xxxx_xxxx_kb()`, `xxxx_xxxx_user()`, or other weak-defined default implemented functions removed
- commented-out functions removed too
- `matrix_init_board()` etc. migrated to `keyboard_pre_init_kb()`, see: [keyboard_pre_init*](custom_quantum_functions#keyboard_pre_init_-function-documentation)
- - when configuring custom matrix, the 'lite' variant (`CUSTOM_MATRIX = lite`) must be used where possible, as this allows for standard debounce. See [custom matrix 'lite'](custom_matrix#lite)
- - justification for full custom matrix (`CUSTOM_MATRIX = yes`) must be provided when used
+ - prefer `CUSTOM_MATRIX = lite` if custom matrix used, allows for standard debounce, see [custom matrix 'lite'](custom_matrix#lite)
- prefer LED indicator [Configuration Options](features/led_indicators#configuration-options) to custom `led_update_*()` implementations where possible
- hardware that's enabled at the keyboard level and requires configuration such as OLED displays or encoders should have basic functionality implemented here
- `