- ## 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. @@ -35,7 +33,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 @@ -53,20 +51,24 @@ 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 -
+#define PAL_USE_CALLBACKS TRUE // [!code focus] + +#include_next
- ## 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). -
- ## 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
- ## 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 {#} +#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,23 +305,21 @@ 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 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: +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: ```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 1d91182f7c..c0785711d9 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 `
## 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 | @@ -87,24 +91,18 @@ Changing the **Value** sets the overall brightness.
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 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_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_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 0abdaebf33..66761f5a46 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 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`. +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`. |Define |Default |Description | |----------------|-------------------------------|---------------------------------------------------------------------------------| diff --git a/docs/features/split_keyboard.md b/docs/features/split_keyboard.md index 49582c3946..4b299b14f8 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 @@ -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 everytime 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 every time 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 modifer 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 modifier 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 {
@@ -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 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.
+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.
-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/)
+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/)
-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/qmk) for help!
+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!
## 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 694d46971a..40a25d9fa7 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 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.
+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.
## IS31FL3733
diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md
index de67fa3bc3..0b8f35a373 100644
--- a/docs/hardware_keyboard_guidelines.md
+++ b/docs/hardware_keyboard_guidelines.md
@@ -44,7 +44,11 @@ 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 `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.
+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.
+:::
Example:
@@ -52,35 +56,49 @@ 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 `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
+ * [`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
* [`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` or `make clueboard/66`
+ * [`rev3`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev3) ← compilable: `make clueboard/66/rev3`
## 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:
+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:
* `readme.md`
-* `info.json`
+* `keyboard.json` (or `info.json`)
* `config.h`
* `rules.mk`
-* `