diff options
Diffstat (limited to 'docs')
34 files changed, 250 insertions, 171 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 2f6309e41d..4b528d9967 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -72,6 +72,7 @@ * [Mod-Tap](mod_tap.md) * [Macros](feature_macros.md) * [Mouse Keys](feature_mouse_keys.md) + * [Programmable Button](feature_programmable_button.md) * [Space Cadet Shift](feature_space_cadet.md) * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md) diff --git a/docs/audio_driver.md b/docs/audio_driver.md index 7cd5a98d9f..81c3390074 100644 --- a/docs/audio_driver.md +++ b/docs/audio_driver.md @@ -57,14 +57,14 @@ This driver needs one Timer per enabled/used DAC channel, to trigger conversion; Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timers 6, 7 and 8: -``` c +```c //halconf.h: #define HAL_USE_DAC TRUE #define HAL_USE_GPT TRUE #include_next <halconf.h> ``` -``` c +```c // mcuconf.h: #include_next <mcuconf.h> #undef STM32_DAC_USE_DAC1_CH1 @@ -93,14 +93,14 @@ only needs one timer (GPTD6, Tim6) to trigger the DAC unit to do a conversion; t Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timer 6: -``` c +```c //halconf.h: #define HAL_USE_DAC TRUE #define HAL_USE_GPT TRUE #include_next <halconf.h> ``` -``` c +```c // mcuconf.h: #include_next <mcuconf.h> #undef STM32_DAC_USE_DAC1_CH1 @@ -153,7 +153,7 @@ This driver uses the ChibiOS-PWM system to produce a square-wave on specific out The hardware directly toggles the pin via its alternate function. See your MCU's data-sheet for which pin can be driven by what timer - looking for TIMx_CHy and the corresponding alternate function. A configuration example for the STM32F103C8 would be: -``` c +```c //halconf.h: #define HAL_USE_PWM TRUE #define HAL_USE_PAL TRUE @@ -161,7 +161,7 @@ A configuration example for the STM32F103C8 would be: #include_next <halconf.h> ``` -``` c +```c // mcuconf.h: #include_next <mcuconf.h> #undef STM32_PWM_USE_TIM1 @@ -177,7 +177,7 @@ If we now target pin A8, looking through the data-sheet of the STM32F103C8, for - TIM1_CH4 = PA11 with all this information, the configuration would contain these lines: -``` c +```c //config.h: #define AUDIO_PIN A8 #define AUDIO_PWM_DRIVER PWMD1 diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 8fa7ad41dc..1427b592f5 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -118,54 +118,6 @@ This command lets you configure the behavior of QMK. For the full `qmk config` d qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] ``` -## `qmk console` - -This command lets you connect to keyboard consoles to get debugging messages. It only works if your keyboard firmware has been compiled with `CONSOLE_ENABLE=yes`. - -**Usage**: - -``` -qmk console [-d <pid>:<vid>[:<index>]] [-l] [-n] [-t] [-w <seconds>] -``` - -**Examples**: - -Connect to all available keyboards and show their console messages: - -``` -qmk console -``` - -List all devices: - -``` -qmk console -l -``` - -Show only messages from clueboard/66/rev3 keyboards: - -``` -qmk console -d C1ED:2370 -``` - -Show only messages from the second clueboard/66/rev3: - -``` -qmk console -d C1ED:2370:2 -``` - -Show timestamps and VID:PID instead of names: - -``` -qmk console -n -t -``` - -Disable bootloader messages: - -``` -qmk console --no-bootloaders -``` - ## `qmk doctor` This command examines your environment and alerts you to potential build or flash problems. It can fix many of them if you want it to. @@ -368,6 +320,33 @@ qmk format-c qmk format-c -b branch_name ``` +## `qmk generate-compilation-database` + +**Usage**: + +``` +qmk generate-compilation-database [-kb KEYBOARD] [-km KEYMAP] +``` + +Creates a `compile_commands.json` file. + +Does your IDE/editor use a language server but doesn't _quite_ find all the necessary include files? Do you hate red squigglies? Do you wish your editor could figure out `#include QMK_KEYBOARD_H`? You might need a [compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html)! The qmk tool can build this for you. + +This command needs to know which keyboard and keymap to build. It uses the same configuration options as the `qmk compile` command: arguments, current directory, and config files. + +**Example:** + +``` +$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak +$ qmk generate-compilation-database +Ψ Making clean +Ψ Gathering build instructions from make -n gh60/satan:colemak +Ψ Found 50 compile commands +Ψ Writing build database to /Users/you/src/qmk_firmware/compile_commands.json +``` + +Now open your dev environment and live a squiggly-free life. + ## `qmk docs` This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936. diff --git a/docs/cli_development.md b/docs/cli_development.md index 0f4f401b33..62be3b3d8c 100644 --- a/docs/cli_development.md +++ b/docs/cli_development.md @@ -14,7 +14,7 @@ If you intend to maintain keyboards and/or contribute to QMK, you can enable the This will allow you to see all available subcommands. **Note:** You will have to install additional requirements: -```bash +``` python3 -m pip install -r requirements-dev.txt ``` diff --git a/docs/configurator_default_keymaps.md b/docs/configurator_default_keymaps.md index 30f9fa72f3..c52342cf16 100644 --- a/docs/configurator_default_keymaps.md +++ b/docs/configurator_default_keymaps.md @@ -20,7 +20,7 @@ Keymaps in this directory require four key-value pairs: Additionally, most keymaps contain a `commit` key. This key is not consumed by the API that back-stops QMK Configurator, but is used by Configurator's maintainers to tell which version of a keymap was used to create the JSON keymap in this repository. The value is the SHA of the last commit to modify a board's default `keymap.c` in the `qmk_firmware` repository. The SHA is found by checking out [the `master` branch of the `qmk/qmk_firmware` repository](https://github.com/qmk/qmk_firmware/tree/master/) and running `git log -1 --pretty=oneline -- keyboards/<keyboard>/keymaps/default/keymap.c` (use `keymap.json` if the keyboard in question has this file instead), which should return something similar to: -```shell +``` f14629ed1cd7c7ec9089604d64f29a99981558e8 Remove/migrate action_get_macro()s from default keymaps (#5625) ``` @@ -31,7 +31,7 @@ In this example, `f14629ed1cd7c7ec9089604d64f29a99981558e8` is the value that sh If one wished to add a default keymap for the H87a by Hineybush, one would run the `git log` command above against the H87a's default keymap in `qmk_firmware`: -```shell +``` user ~/qmk_firmware (master) $ git log -1 --pretty=oneline master -- keyboards/hineybush/h87a/keymaps/default/keymap.c ef8878fba5d3786e3f9c66436da63a560cd36ac9 Hineybush h87a lock indicators (#8237) diff --git a/docs/contributing.md b/docs/contributing.md index 1d68d22d9f..eb033d167f 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -105,7 +105,7 @@ enum my_keycodes { Before opening a pull request, you can preview your changes if you have set up the development environment by running this command from the `qmk_firmware/` folder: - ./bin/qmk docs + qmk docs or if you only have Python 3 installed: diff --git a/docs/custom_matrix.md b/docs/custom_matrix.md index cfa900a33d..8f6878f94a 100644 --- a/docs/custom_matrix.md +++ b/docs/custom_matrix.md @@ -15,7 +15,7 @@ The reasons to use this feature include: Implementing custom matrix usually involves compilation of an additional source file. It is recommended that for consistency, this file is called `matrix.c`. Add a new file to your keyboard directory: -```text +``` keyboards/<keyboard>/matrix.c ``` diff --git a/docs/de/cli.md b/docs/de/cli.md index 7dc02d505b..259aeecf75 100644 --- a/docs/de/cli.md +++ b/docs/de/cli.md @@ -51,25 +51,6 @@ Wir suchen nach Freiwilligen, die ein `qmk`-Package für weitere Betriebssysteme * Installiere mit einem [virtualenv](https://virtualenv.pypa.io/en/latest/). * Weise den User an, die Umgebungs-Variable `QMK_HOME` zu setzen, um die Firmware-Quelle anders einzustellen als `~/qmk_firmware`. -# Lokale CLI - -Wenn Du die globale CLI nicht verwenden möchtest, beinhaltet `qmk_firmware` auch eine lokale CLI. Du kannst sie hier finden: `qmk_firmware/bin/qmk`. Du kannst den `qmk`-Befehl aus irgendeinem Datei-Verzeichnis ausführen und es wird immer auf dieser Kopie von `qmk_firmware` arbeiten. - -**Beispiel**: - -``` -$ ~/qmk_firmware/bin/qmk hello -Ψ Hello, World! -``` - -## Einschränkungen der lokalen CLI - -Hier ein Vergleich mit der globalen CLI: - -* Die lokale CLI unterstützt kein `qmk setup` oder `qmk clone`. -* Die lokale CLI arbeitet immer innerhalb der selben `qmk_firmware`-Verzeichnisstruktur, auch wenn Du mehrere Repositories geklont hast. -* Die lokale CLI läuft nicht in einer virtualenv. Daher ist es möglich, dass Abhängigkeiten (dependencies) miteinander in Konflikt kommen/stehen. - # CLI-Befehle ## `qmk compile` diff --git a/docs/faq_debug.md b/docs/faq_debug.md index 1afa38a624..28b8c81759 100644 --- a/docs/faq_debug.md +++ b/docs/faq_debug.md @@ -62,7 +62,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { ``` Example output -```text +``` Waiting for device:....... Listening: KL: kc: 169, col: 0, row: 0, pressed: 1 @@ -82,7 +82,7 @@ When testing performance issues, it can be useful to know the frequency at which ``` Example output -```text +``` > matrix scan frequency: 315 > matrix scan frequency: 313 > matrix scan frequency: 316 diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index d47ecc6824..79782cf564 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -8,7 +8,7 @@ The MCU can only supply so much current to its GPIO pins. Instead of powering th Most keyboards have backlighting enabled by default if they support it, but if it is not working for you, check that your `rules.mk` includes the following: -```makefile +```make BACKLIGHT_ENABLE = yes ``` @@ -54,7 +54,7 @@ If backlight breathing is enabled (see below), the following functions are also To select which driver to use, configure your `rules.mk` with the following: -```makefile +```make BACKLIGHT_DRIVER = software ``` @@ -87,7 +87,7 @@ This functionality is configured at the keyboard level with the `BACKLIGHT_ON_ST The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be: -```makefile +```make BACKLIGHT_DRIVER = pwm ``` @@ -143,7 +143,7 @@ The breathing effect is the same as in the hardware PWM implementation. While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be: -```makefile +```make BACKLIGHT_DRIVER = pwm ``` @@ -167,7 +167,7 @@ Currently only hardware PWM is supported, not timer assisted, and does not provi In this mode, PWM is "emulated" while running other keyboard tasks. It offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your `rules.mk`: -```makefile +```make BACKLIGHT_DRIVER = software ``` @@ -188,7 +188,7 @@ To activate multiple backlight pins, add something like this to your `config.h`, If none of the above drivers apply to your board (for example, you are using a separate IC to control the backlight), you can implement a custom backlight driver using this simple API provided by QMK. To enable, add this to your `rules.mk`: -```makefile +```make BACKLIGHT_DRIVER = custom ``` diff --git a/docs/feature_bluetooth.md b/docs/feature_bluetooth.md index 08e5f24ac5..1b6a825e7a 100644 --- a/docs/feature_bluetooth.md +++ b/docs/feature_bluetooth.md @@ -4,10 +4,10 @@ Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QMK has support for RN-42 modules. For more recent BLE protocols, currently only the Adafruit Bluefruit SPI Friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support mouse input. -|Board |Bluetooth Protocol |Connection Type |rules.mk |Bluetooth Chip| -|----------------------------------------------------------------|----------------------------|----------------|---------------------------|--------------| -|Roving Networks RN-42 (Sparkfun Bluesmirf) |Bluetooth Classic | UART |`BLUETOOTH = RN42` | RN-42 | -|[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy | SPI |`BLUETOOTH = AdafruitBLE` | nRF51822 | +|Board |Bluetooth Protocol |Connection Type|rules.mk |Bluetooth Chip| +|----------------------------------------------------------------|--------------------|---------------|--------------------------------|--------------| +|Roving Networks RN-42 (Sparkfun Bluesmirf) |Bluetooth Classic |UART |`BLUETOOTH_DRIVER = RN42` |RN-42 | +|[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy|SPI |`BLUETOOTH_DRIVER = AdafruitBLE`|nRF51822 | Not Supported Yet but possible: * [Bluefruit LE UART Friend](https://www.adafruit.com/product/2479). [Possible tmk implementation found in](https://github.com/tmk/tmk_keyboard/issues/514) @@ -23,16 +23,17 @@ Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit A Bluefruit UART friend can be converted to an SPI friend, however this [requires](https://github.com/qmk/qmk_firmware/issues/2274) some reflashing and soldering directly to the MDBT40 chip. - <!-- FIXME: Document bluetooth support more completely. --> ## Bluetooth Rules.mk Options The currently supported Bluetooth chipsets do not support [N-Key Rollover (NKRO)](reference_glossary.md#n-key-rollover-nkro), so `rules.mk` must contain `NKRO_ENABLE = no`. -Use only one of these to enable Bluetooth: -* BLUETOOTH_ENABLE = yes (Legacy Option) -* BLUETOOTH = RN42 -* BLUETOOTH = AdafruitBLE +Add the following to your `rules.mk`: + +```make +BLUETOOTH_ENABLE = yes +BLUETOOTH_DRIVER = AdafruitBLE # or RN42 +``` ## Bluetooth Keycodes diff --git a/docs/feature_digitizer.md b/docs/feature_digitizer.md index 9b6aeddbaa..ac2d64f977 100644 --- a/docs/feature_digitizer.md +++ b/docs/feature_digitizer.md @@ -4,7 +4,7 @@ The digitizer HID interface allows setting the mouse cursor position at absolute To enable the digitizer interface, add the following line to your rules.mk: -```makefile +```make DIGITIZER_ENABLE = yes ``` diff --git a/docs/feature_joystick.md b/docs/feature_joystick.md index 95702d6a23..fe33517a16 100644 --- a/docs/feature_joystick.md +++ b/docs/feature_joystick.md @@ -15,7 +15,7 @@ or send gamepad reports based on values computed by the keyboard. To use analog input you must first enable it in `rules.mk`: -```makefile +```make JOYSTICK_ENABLE = yes JOYSTICK_DRIVER = analog # or 'digital' ``` diff --git a/docs/feature_layouts.md b/docs/feature_layouts.md index b34fd442d5..93d040b554 100644 --- a/docs/feature_layouts.md +++ b/docs/feature_layouts.md @@ -25,7 +25,7 @@ The `layouts/default/` and `layouts/community/` are two examples of layout "repo Each layout folder is named (`[a-z0-9_]`) after the physical aspects of the layout, in the most generic way possible, and contains a `readme.md` with the layout to be defined by the keyboard: -```md +```markdown # 60_ansi LAYOUT_60_ansi diff --git a/docs/feature_midi.md b/docs/feature_midi.md index ab29d89db6..3da5c4940a 100644 --- a/docs/feature_midi.md +++ b/docs/feature_midi.md @@ -4,7 +4,7 @@ First, enable MIDI by adding the following to your `rules.mk`: -```makefile +```make MIDI_ENABLE = yes ``` diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md index 905c2a8f95..badeadc12b 100644 --- a/docs/feature_pointing_device.md +++ b/docs/feature_pointing_device.md @@ -4,7 +4,7 @@ Pointing Device is a generic name for a feature intended to be generic: moving t To enable Pointing Device, uncomment the following line in your rules.mk: -```makefile +```make POINTING_DEVICE_ENABLE = yes ``` diff --git a/docs/feature_programmable_button.md b/docs/feature_programmable_button.md new file mode 100644 index 0000000000..b1ef555d16 --- /dev/null +++ b/docs/feature_programmable_button.md @@ -0,0 +1,74 @@ +## Programmable Button + +Programmable button is a feature that can be used to send keys that have no +predefined meaning. +This means they can be processed on the host side by custom software without +colliding without the operating system trying to interpret these keys. + +The keycodes are emitted according to the HID usage +"Telephony Device Page" (0x0B), "Programmable button usage" (0x07). +On Linux (> 5.14) they are handled automatically and translated to `KEY_MACRO#` +keycodes. +(Up to `KEY_MACRO30`) + +### Enabling Programmable Button support + +To enable Programmable Button, add the following line to your keymap’s `rules.mk`: + +```c +PROGRAMMABLE_BUTTON_ENABLE = yes +``` + +### Mapping + +In your keymap you can use the following keycodes to map key presses to Programmable Buttons: + +|Key |Description | +|------------------------|----------------------| +|`PROGRAMMABLE_BUTTON_1` |Programmable button 1 | +|`PROGRAMMABLE_BUTTON_2` |Programmable button 2 | +|`PROGRAMMABLE_BUTTON_3` |Programmable button 3 | +|`PROGRAMMABLE_BUTTON_4` |Programmable button 4 | +|`PROGRAMMABLE_BUTTON_5` |Programmable button 5 | +|`PROGRAMMABLE_BUTTON_6` |Programmable button 6 | +|`PROGRAMMABLE_BUTTON_7` |Programmable button 7 | +|`PROGRAMMABLE_BUTTON_8` |Programmable button 8 | +|`PROGRAMMABLE_BUTTON_9` |Programmable button 9 | +|`PROGRAMMABLE_BUTTON_10`|Programmable button 10| +|`PROGRAMMABLE_BUTTON_11`|Programmable button 11| +|`PROGRAMMABLE_BUTTON_12`|Programmable button 12| +|`PROGRAMMABLE_BUTTON_13`|Programmable button 13| +|`PROGRAMMABLE_BUTTON_14`|Programmable button 14| +|`PROGRAMMABLE_BUTTON_15`|Programmable button 15| +|`PROGRAMMABLE_BUTTON_16`|Programmable button 16| +|`PROGRAMMABLE_BUTTON_17`|Programmable button 17| +|`PROGRAMMABLE_BUTTON_18`|Programmable button 18| +|`PROGRAMMABLE_BUTTON_19`|Programmable button 19| +|`PROGRAMMABLE_BUTTON_20`|Programmable button 20| +|`PROGRAMMABLE_BUTTON_21`|Programmable button 21| +|`PROGRAMMABLE_BUTTON_22`|Programmable button 22| +|`PROGRAMMABLE_BUTTON_23`|Programmable button 23| +|`PROGRAMMABLE_BUTTON_24`|Programmable button 24| +|`PROGRAMMABLE_BUTTON_25`|Programmable button 25| +|`PROGRAMMABLE_BUTTON_26`|Programmable button 26| +|`PROGRAMMABLE_BUTTON_27`|Programmable button 27| +|`PROGRAMMABLE_BUTTON_28`|Programmable button 28| +|`PROGRAMMABLE_BUTTON_29`|Programmable button 29| +|`PROGRAMMABLE_BUTTON_30`|Programmable button 30| +|`PROGRAMMABLE_BUTTON_31`|Programmable button 31| +|`PROGRAMMABLE_BUTTON_32`|Programmable button 32| +|`PB_1` to `PB_32` |Aliases for keymaps | + +### API + +You can also use a dedicated API defined in `programmable_button.h` to interact with this feature: + +``` +void programmable_button_clear(void); +void programmable_button_send(void); +void programmable_button_on(uint8_t code); +void programmable_button_off(uint8_t code); +bool programmable_button_is_on(uint8_t code); +uint32_t programmable_button_get_report(void); +void programmable_button_set_report(uint32_t report); +``` diff --git a/docs/feature_ps2_mouse.md b/docs/feature_ps2_mouse.md index 776a33150e..433a47fa9b 100644 --- a/docs/feature_ps2_mouse.md +++ b/docs/feature_ps2_mouse.md @@ -30,7 +30,7 @@ Note: This is not recommended, you may encounter jerky movement or unsent inputs In rules.mk: -```makefile +```make PS2_MOUSE_ENABLE = yes PS2_USE_BUSYWAIT = yes ``` @@ -56,7 +56,7 @@ The following example uses D2 for clock and D5 for data. You can use any INT or In rules.mk: -```makefile +```make PS2_MOUSE_ENABLE = yes PS2_USE_INT = yes ``` @@ -118,7 +118,7 @@ To use USART on the ATMega32u4, you have to use PD5 for clock and PD2 for data. In rules.mk: -```makefile +```make PS2_MOUSE_ENABLE = yes PS2_USE_USART = yes ``` diff --git a/docs/feature_rawhid.md b/docs/feature_rawhid.md index 4a688fcba7..558a23a80f 100644 --- a/docs/feature_rawhid.md +++ b/docs/feature_rawhid.md @@ -15,7 +15,7 @@ RAW_ENABLE = yes In your `keymap.c` include `"raw_hid.h"` and implement the following: -```C +```c void raw_hid_receive(uint8_t *data, uint8_t length) { // Your code goes here. data is the packet received from host. } @@ -23,7 +23,7 @@ void raw_hid_receive(uint8_t *data, uint8_t length) { The `"raw_hid.h"` header also declares `void raw_hid_send(uint8_t *data, uint8_t length);` which allows sending packets from keyboard to host. As an example, it can also be used for debugging when building your host application by returning all data back to the host. -```C +```c void raw_hid_receive(uint8_t *data, uint8_t length) { raw_hid_send(data, length); } diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 2dbd32fbdb..2660aad09b 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -10,7 +10,7 @@ If you want to use single color LED's you should use the [LED Matrix Subsystem]( There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`: -```makefile +```make RGB_MATRIX_ENABLE = yes RGB_MATRIX_DRIVER = IS31FL3731 ``` @@ -71,7 +71,7 @@ Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet] There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`: -```makefile +```make RGB_MATRIX_ENABLE = yes RGB_MATRIX_DRIVER = IS31FL3733 ``` @@ -141,7 +141,7 @@ Where `X_Y` is the location of the LED in the matrix defined by [the datasheet]( There is basic support for addressable RGB matrix lighting with the I2C IS31FL3737 RGB controller. To enable it, add this to your `rules.mk`: -```makefile +```make RGB_MATRIX_ENABLE = yes RGB_MATRIX_DRIVER = IS31FL3737 ``` @@ -206,7 +206,7 @@ Where `X_Y` is the location of the LED in the matrix defined by [the datasheet]( There is basic support for addressable RGB matrix lighting with a WS2811/WS2812{a,b,c} addressable LED strand. To enable it, add this to your `rules.mk`: -```makefile +```make RGB_MATRIX_ENABLE = yes RGB_MATRIX_DRIVER = WS2812 ``` @@ -226,7 +226,7 @@ Configure the hardware via your `config.h`: There is basic support for APA102 based addressable LED strands. To enable it, add this to your `rules.mk`: -```makefile +```make RGB_MATRIX_ENABLE = yes RGB_MATRIX_DRIVER = APA102 ``` @@ -246,7 +246,7 @@ Configure the hardware via your `config.h`: ### AW20216 :id=aw20216 There is basic support for addressable RGB matrix lighting with the SPI AW20216 RGB controller. To enable it, add this to your `rules.mk`: -```makefile +```make RGB_MATRIX_ENABLE = yes RGB_MATRIX_DRIVER = AW20216 ``` diff --git a/docs/feature_stenography.md b/docs/feature_stenography.md index af4754ed78..92a5c3f848 100644 --- a/docs/feature_stenography.md +++ b/docs/feature_stenography.md @@ -32,7 +32,7 @@ GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything Firstly, enable steno in your keymap's Makefile. You may also need disable mousekeys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them. -```makefile +```make STENO_ENABLE = yes MOUSEKEY_ENABLE = no ``` diff --git a/docs/feature_swap_hands.md b/docs/feature_swap_hands.md index cbc574b6b8..b0239bb802 100644 --- a/docs/feature_swap_hands.md +++ b/docs/feature_swap_hands.md @@ -6,7 +6,7 @@ The swap-hands action allows support for one-handed typing without requiring a s The configuration table is a simple 2-dimensional array to map from column/row to new column/row. Example `hand_swap_config` for Planck: -```C +```c const keypos_t PROGMEM hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = { {{11, 0}, {10, 0}, {9, 0}, {8, 0}, {7, 0}, {6, 0}, {5, 0}, {4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}}, {{11, 1}, {10, 1}, {9, 1}, {8, 1}, {7, 1}, {6, 1}, {5, 1}, {4, 1}, {3, 1}, {2, 1}, {1, 1}, {0, 1}}, diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md index 8b001e3ce2..115ab71753 100644 --- a/docs/feature_userspace.md +++ b/docs/feature_userspace.md @@ -240,7 +240,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { For boards that may not have a shift button (such as on a macro pad), we need a way to always include the bootloader option. To do that, add the following to the `rules.mk` in your userspace folder: -```make +```make ifeq ($(strip $(FLASH_BOOTLOADER)), yes) OPT_DEFS += -DFLASH_BOOTLOADER endif diff --git a/docs/flashing_bootloadhid.md b/docs/flashing_bootloadhid.md index 9879ec999e..213c7c1321 100644 --- a/docs/flashing_bootloadhid.md +++ b/docs/flashing_bootloadhid.md @@ -44,7 +44,7 @@ For native Windows flashing, the `bootloadHID.exe` can be used outside of the MS ### Linux Manual Installation 1. Install libusb development dependency: - ```bash + ``` # This depends on OS - for Debian the following works sudo apt-get install libusb-dev ``` diff --git a/docs/fr-fr/cli.md b/docs/fr-fr/cli.md index bfa060f2ad..917a9315bc 100644 --- a/docs/fr-fr/cli.md +++ b/docs/fr-fr/cli.md @@ -48,25 +48,6 @@ Nous recherchons des gens pour créer et maintenir un paquet `qmk` pour plus de * Installez en utilisant un virtualenv * Expliquez à l'utilisateur de définir la variable d'environnement `QMK_Home` pour "check out" les sources du firmware à un autre endroit que `~/qmk_firmware`. -# CLI locale - -Si vous ne voulez pas utiliser la CLI globale, il y a une CLI locale empaquetée avec `qmk_firmware`. Vous pouvez le trouver dans `qmk_firmware/bin/qmk`. Vous pouvez lancer la commande `qmk` depuis n'importe quel répertoire et elle fonctionnera toujours sur cette copie de `qmk_firmware`. - -**Exemple**: - -``` -$ ~/qmk_firmware/bin/qmk hello -Ψ Hello, World! -``` - -## Limitations de la CLI locale - -Il y a quelques limitations à la CLI locale comparé à la globale: - -* La CLI locale ne supporte pas `qmk setup` ou `qmk clone` -* La CLI locale n'opère pas sur le même arbre `qmk_firmware`, même si vous avez plusieurs dépôts clonés. -* La CLI locale ne s'exécute pas dans un virtualenv, donc il y a des risques que des dépendances seront en conflit - # Les commandes CLI ## `qmk compile` diff --git a/docs/getting_started_docker.md b/docs/getting_started_docker.md index f9c3b366a4..c4da8af968 100644 --- a/docs/getting_started_docker.md +++ b/docs/getting_started_docker.md @@ -12,13 +12,13 @@ The main prerequisite is a working `docker` or `podman` install. Acquire a local copy of the QMK's repository (including submodules): -```bash +``` git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git cd qmk_firmware ``` Run the following command to build a keymap: -```bash +``` util/docker_build.sh <keyboard>:<keymap> # For example: util/docker_build.sh planck/rev6:default ``` @@ -27,14 +27,14 @@ This will compile the desired keyboard/keymap and leave the resulting `.hex` or There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well: -```bash +``` util/docker_build.sh keyboard:keymap:target # For example: util/docker_build.sh planck/rev6:default:flash ``` You can also start the script without any parameters, in which case it will ask you to input the build parameters one by one, which you may find easier to use: -```bash +``` util/docker_build.sh # Reads parameters as input (leave blank for all keyboards/keymaps) ``` @@ -42,7 +42,7 @@ util/docker_build.sh You can manually set which container runtime you want to use by setting the `RUNTIME` environment variable to it's name or path. By default docker or podman are automatically detected and docker is preferred over podman. -```bash +``` RUNTIME="podman" util/docker_build.sh keyboard:keymap:target ``` diff --git a/docs/getting_started_vagrant.md b/docs/getting_started_vagrant.md index 114f875671..b5b5ce1539 100644 --- a/docs/getting_started_vagrant.md +++ b/docs/getting_started_vagrant.md @@ -31,26 +31,26 @@ The development environment is configured to run the QMK Docker image, `qmkfm/qm ### Why am I seeing issues under Virtualbox? Certain versions of Virtualbox 5 appear to have an incompatibility with the Virtualbox extensions installed in the boxes in this Vagrantfile. If you encounter any issues with the /vagrant mount not succeeding, please upgrade your version of Virtualbox to at least 5.0.12. **Alternately, you can try running the following command:** -```console +``` vagrant plugin install vagrant-vbguest ``` ### How do I remove an existing environment? Finished with your environment? From anywhere inside the folder where you checked out this project, Execute: -```console +``` vagrant destroy ``` ### What if I want to use Docker directly? Want to benefit from the Vagrant workflow without a virtual machine? The Vagrantfile is configured to bypass running a virtual machine, and run the container directly. Execute the following when bringing up the environment to force the use of Docker: -```console +``` vagrant up --provider=docker ``` ### How do I access the virtual machine instead of the Docker container? Execute the following to bypass the `vagrant` user booting directly to the official qmk builder image: -```console +``` vagrant ssh -c 'sudo -i' ``` diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md index 7630b44e0c..f975f37f55 100644 --- a/docs/hardware_keyboard_guidelines.md +++ b/docs/hardware_keyboard_guidelines.md @@ -144,10 +144,38 @@ The `rules.mk` file can also be placed in a sub-folder, and its reading order is * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/rules.mk` * `keyboards/top_folder/keymaps/a_keymap/rules.mk` * `users/a_user_folder/rules.mk` + * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/post_rules.mk` + * `keyboards/top_folder/sub_1/sub_2/sub_3/post_rules.mk` + * `keyboards/top_folder/sub_1/sub_2/post_rules.mk` + * `keyboards/top_folder/sub_1/post_rules.mk` +* `keyboards/top_folder/post_rules.mk` * `common_features.mk` Many of the settings written in the `rules.mk` file are interpreted by `common_features.mk`, which sets the necessary source files and compiler options. +The `post_rules.mk` file can interpret `features` of a keyboard-level before `common_features.mk`. For example, when your designed keyboard has the option to implement backlighting or underglow using rgblight.c, writing the following in the `post_rules.mk` makes it easier for the user to configure the `rules.mk`. + +* `keyboards/top_folder/keymaps/a_keymap/rules.mk` + ```make + # Please set the following according to the selection of the hardware implementation option. + RGBLED_OPTION_TYPE = backlight ## none, backlight or underglow + ``` +* `keyboards/top_folder/post_rules.mk` + ```make + ifeq ($(filter $(strip $(RGBLED_OPTION_TYPE))x, nonex backlightx underglowx x),) + $(error unknown RGBLED_OPTION_TYPE value "$(RGBLED_OPTION_TYPE)") + endif + + ifeq ($(strip $(RGBLED_OPTION_TYPE)),backlight) + RGBLIGHT_ENABLE = yes + OPT_DEFS += -DRGBLED_NUM=30 + endif + ifeq ($(strip $(RGBLED_OPTION_TYPE)),underglow) + RGBLIGHT_ENABLE = yes + OPT_DEFS += -DRGBLED_NUM=6 + endif + ``` + ?> See `build_keyboard.mk` and `common_features.mk` for more details. ### `<keyboard_name.c>` diff --git a/docs/how_keyboards_work.md b/docs/how_keyboards_work.md index 3dcbc64522..36cbfb4d9a 100644 --- a/docs/how_keyboards_work.md +++ b/docs/how_keyboards_work.md @@ -9,7 +9,7 @@ firmware directly. Whenever you type on 1 particular key, here is the chain of actions taking place: -``` text +``` +------+ +-----+ +----------+ +----------+ +----+ | User |-------->| Key |------>| Firmware |----->| USB wire |---->| OS | +------+ +-----+ +----------+ +----------+ +----+ diff --git a/docs/i2c_driver.md b/docs/i2c_driver.md index 3ec34a0f87..9017b44ed7 100644 --- a/docs/i2c_driver.md +++ b/docs/i2c_driver.md @@ -62,16 +62,13 @@ Then, modify your board's `mcuconf.h` to enable the peripheral you've chosen, fo Configuration-wise, you'll need to set up the peripheral as per your MCU's datasheet -- the defaults match the pins for a Proton-C, i.e. STM32F303. -|`config.h` Overrride |Description |Default| -|------------------------|-------------------------------------------------------------------------------------------|-------| -|`I2C_DRIVER` |I2C peripheral to use - I2C1 -> `I2CD1`, I2C2 -> `I2CD2` etc. |`I2CD1`| -|`I2C1_BANK` (deprecated)|The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`), superseded by `I2C1_SCL_BANK`/`I2C1_SDA_BANK`|`GPIOB`| -|`I2C1_SCL_BANK` |The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SCL |`GPIOB`| -|`I2C1_SCL` |The pin number for SCL (0-15) |`6` | -|`I2C1_SCL_PAL_MODE` |The alternate function mode for SCL |`4` | -|`I2C1_SDA_BANK` |The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SDA |`GPIOB`| -|`I2C1_SDA` |The pin number for SDA (0-15) |`7` | -|`I2C1_SDA_PAL_MODE` |The alternate function mode for SDA |`4` | +|`config.h` Overrride |Description |Default| +|------------------------|--------------------------------------------------------------|-------| +|`I2C_DRIVER` |I2C peripheral to use - I2C1 -> `I2CD1`, I2C2 -> `I2CD2` etc. |`I2CD1`| +|`I2C1_SCL_PIN` |The pin definition for SCL |`B6` | +|`I2C1_SCL_PAL_MODE` |The alternate function mode for SCL |`4` | +|`I2C1_SDA_PIN` |The pin definition for SDA |`B7` | +|`I2C1_SDA_PAL_MODE` |The alternate function mode for SDA |`4` | The following configuration values depend on the specific MCU in use. diff --git a/docs/ja/i2c_driver.md b/docs/ja/i2c_driver.md index 9d348d5803..1d8f70e163 100644 --- a/docs/ja/i2c_driver.md +++ b/docs/ja/i2c_driver.md @@ -79,13 +79,10 @@ ARM MCU 用の設定はしばしば非常に複雑です。これは、多くの STM32 MCU では、使用するハードウェアドライバにより、さまざまなピンを I2C ピンとして設定できます。標準では `B6`, `B7` ピンが I2C 用のピンです。 I2C 用のピンを設定するために次の定義が使えます： -| 変数 | 説明 | 既定値 | -|-----------------------|--------------------------------------------------------------------------------------------------|---------| -| `I2C1_SCL_BANK` | SCL に使うピンのバンク (`GPIOA`, `GPIOB`, `GPIOC`) | `GPIOB` | -| `I2C1_SDA_BANK` | SDA に使うピンのバンク (`GPIOA`, `GPIOB`, `GPIOC`) | `GPIOB` | -| `I2C1_SCL` | SCL のピン番号 (0-15) | `6` | -| `I2C1_SDA` | SDA のピン番号 (0-15) | `7` | -| `I2C1_BANK`（非推奨） | 使用するピンのバンク (`GPIOA`, `GPIOB`, `GPIOC`)。後継は `I2C1_SCL_BANK`, `I2C1_SDA_BANK` です。 | `GPIOB` | +| 変数 | 説明 | 既定値 | +|-----------------------|-------------------------------------------------------------------------------------------|---------| +| `I2C1_SCL_PIN` | SCL のピン番号 | `B6` | +| `I2C1_SDA_PIN` | SDA のピン番号 | `B7` | ChibiOS I2C ドライバの設定項目は STM32 MCU の種類に依存します。 diff --git a/docs/keycodes.md b/docs/keycodes.md index a134c5a1b2..770a4525a5 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -677,6 +677,46 @@ See also: [One Shot Keys](one_shot_keys.md) |`OS_OFF` |Turns One Shot keys off | |`OS_TOGG` |Toggles One Shot keys status | +## Programmable Button Support :id=programmable-button + +See also: [Programmable Button](feature_programmable_button.md) + +|Key |Description | +|------------------------|----------------------| +|`PROGRAMMABLE_BUTTON_1` |Programmable button 1 | +|`PROGRAMMABLE_BUTTON_2` |Programmable button 2 | +|`PROGRAMMABLE_BUTTON_3` |Programmable button 3 | +|`PROGRAMMABLE_BUTTON_4` |Programmable button 4 | +|`PROGRAMMABLE_BUTTON_5` |Programmable button 5 | +|`PROGRAMMABLE_BUTTON_6` |Programmable button 6 | +|`PROGRAMMABLE_BUTTON_7` |Programmable button 7 | +|`PROGRAMMABLE_BUTTON_8` |Programmable button 8 | +|`PROGRAMMABLE_BUTTON_9` |Programmable button 9 | +|`PROGRAMMABLE_BUTTON_10`|Programmable button 10| +|`PROGRAMMABLE_BUTTON_11`|Programmable button 11| +|`PROGRAMMABLE_BUTTON_12`|Programmable button 12| +|`PROGRAMMABLE_BUTTON_13`|Programmable button 13| +|`PROGRAMMABLE_BUTTON_14`|Programmable button 14| +|`PROGRAMMABLE_BUTTON_15`|Programmable button 15| +|`PROGRAMMABLE_BUTTON_16`|Programmable button 16| +|`PROGRAMMABLE_BUTTON_17`|Programmable button 17| +|`PROGRAMMABLE_BUTTON_18`|Programmable button 18| +|`PROGRAMMABLE_BUTTON_19`|Programmable button 19| +|`PROGRAMMABLE_BUTTON_20`|Programmable button 20| +|`PROGRAMMABLE_BUTTON_21`|Programmable button 21| +|`PROGRAMMABLE_BUTTON_22`|Programmable button 22| +|`PROGRAMMABLE_BUTTON_23`|Programmable button 23| +|`PROGRAMMABLE_BUTTON_24`|Programmable button 24| +|`PROGRAMMABLE_BUTTON_25`|Programmable button 25| +|`PROGRAMMABLE_BUTTON_26`|Programmable button 26| +|`PROGRAMMABLE_BUTTON_27`|Programmable button 27| +|`PROGRAMMABLE_BUTTON_28`|Programmable button 28| +|`PROGRAMMABLE_BUTTON_29`|Programmable button 29| +|`PROGRAMMABLE_BUTTON_30`|Programmable button 30| +|`PROGRAMMABLE_BUTTON_31`|Programmable button 31| +|`PROGRAMMABLE_BUTTON_32`|Programmable button 32| +|`PB_1` to `PB_32` |Aliases for keymaps | + ## Space Cadet :id=space-cadet See also: [Space Cadet](feature_space_cadet.md) diff --git a/docs/newbs_git_resynchronize_a_branch.md b/docs/newbs_git_resynchronize_a_branch.md index 3e7acdba7a..1d0e4dda16 100644 --- a/docs/newbs_git_resynchronize_a_branch.md +++ b/docs/newbs_git_resynchronize_a_branch.md @@ -8,7 +8,7 @@ Suppose you have committed to your `master` branch, and now need to update your No one wants to lose work if it can be helped. If you want to save the changes you've already made to your `master` branch, the simplest way to do so is to simply create a duplicate of your "dirty" `master` branch: -```sh +``` git branch old_master master ``` @@ -18,7 +18,7 @@ Now you have a branch named `old_master` that is a duplicate of your `master` br Now it's time to resynchronize your `master` branch. For this step, you'll want to have QMK's repository configured as a remote in Git. To check your configured remotes, run `git remote -v`, which should return something similar to: -```sh +``` QMKuser ~/qmk_firmware (master) $ git remote -v origin https://github.com/<your_username>/qmk_firmware.git (fetch) @@ -29,7 +29,7 @@ upstream https://github.com/qmk/qmk_firmware.git (push) If you only see one fork referenced: -```sh +``` QMKuser ~/qmk_firmware (master) $ git remote -v origin https://github.com/qmk/qmk_firmware.git (fetch) @@ -38,31 +38,31 @@ origin https://github.com/qmk/qmk_firmware.git (push) add a new remote with: -```sh +``` git remote add upstream https://github.com/qmk/qmk_firmware.git ``` Then, redirect the `origin` remote to your own fork with: -```sh +``` git remote set-url origin https://github.com/<your_username>/qmk_firmware.git ``` Now that you have both remotes configured, you need to update the references for the upstream repository, which is QMK's, by running: -```sh +``` git fetch upstream ``` At this point, resynchronize your branch to QMK's by running: -```sh +``` git reset --hard upstream/master ``` These steps will update the repository on your computer, but your GitHub fork will still be out of sync. To resynchronize your fork on GitHub, you need to push to your fork, instructing Git to override any remote changes that are not reflected in your local repository. To do this, run: -```sh +``` git push --force-with-lease ``` diff --git a/docs/unit_testing.md b/docs/unit_testing.md index a0eef51cb6..7310da8d0b 100644 --- a/docs/unit_testing.md +++ b/docs/unit_testing.md @@ -44,7 +44,7 @@ If there are problems with the tests, you can find the executable in the `./buil To forward any [debug messages](unit_testing.md#debug-api) to `stderr`, the tests can run with `DEBUG=1`. For example -```console +``` make test:all DEBUG=1 ``` |