diff options
Diffstat (limited to 'docs')
59 files changed, 424 insertions, 301 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/chibios_upgrade_instructions.md b/docs/chibios_upgrade_instructions.md index 40c2faafcf..b0a71142a3 100644 --- a/docs/chibios_upgrade_instructions.md +++ b/docs/chibios_upgrade_instructions.md @@ -14,10 +14,10 @@ ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a bra * First time around this will take several hours * Subsequent updates will be incremental only * Tagging example (work out which version first!): - * `git tag -a ver20.3.3 -m ver20.3.3 svn/tags/ver20.3.3` - * `git push qmk ver20.3.3` - * `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN svn/tags/ver20.3.3` - * `git push qmk breaking_YYYY_qN` + * `git tag -a ver20.3.4 -m ver20.3.4 svn/tags/ver20.3.4` + * `git push qmk ver20.3.4` + * `git tag -a develop_YYYY_qN -m develop_YYYY_qN svn/tags/ver20.3.4` + * `git push qmk develop_YYYY_qN` ## Getting ChibiOS-Contrib @@ -30,8 +30,8 @@ ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a bra * `git checkout chibios-20.3.x` * `git pull --ff-only` * `git push origin chibios-20.3.x` - * `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN chibios-20.3.x` - * `git push origin breaking_YYYY_qN` + * `git tag -a develop_YYYY_qN -m develop_YYYY_qN chibios-20.3.x` + * `git push origin develop_YYYY_qN` ## Updating submodules @@ -42,15 +42,18 @@ ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a bra * `git checkout -b chibios-version-bump` * `cd lib/chibios` * `git fetch --all --tags --prune` - * `git checkout breaking_YYYY_qN` + * `git checkout develop_YYYY_qN` * `cd ../chibios-contrib` * `git fetch --all --tags --prune` - * `git checkout breaking_YYYY_qN` + * `git checkout develop_YYYY_qN` +* Update ChibiOS configs within QMK + * `cd $QMK_FIRMWARE` + * `./util/chibios_conf_updater.sh` * Build everything * `cd $QMK_FIRMWARE` * `qmk multibuild -j4` * Make sure there are no errors * Push to the repo - * `git commit -am 'Update ChibiOS to XXXXXXXXX'` + * `git commit -am 'Update ChibiOS to 99.9.9'` * `git push --set-upstream origin chibios-version-bump` -* Make a PR to qmk_firmware with the new branch
\ No newline at end of file +* Make a PR to qmk_firmware with the new branch 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/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 2bf3b0ebb7..39e9061c20 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -27,6 +27,7 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s * [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html) * [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html) * [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html) + * [STM32F405](https://www.st.com/en/microcontrollers-microprocessors/stm32f405-415.html) * [STM32F407](https://www.st.com/en/microcontrollers-microprocessors/stm32f407-417.html) * [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html) * [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html) @@ -42,7 +43,14 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s * [MKL26Z64](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/kl-series-cortex-m0-plus/kinetis-kl2x-72-96-mhz-usb-ultra-low-power-microcontrollers-mcus-based-on-arm-cortex-m0-plus-core:KL2x) * [MK20DX128](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-50-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-based-on-arm-cortex-m4-core:K20_50) * [MK20DX256](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72) + * [MK66FX1M0](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k6x-ethernet/kinetis-k66-180-mhz-dual-high-speed-full-speed-usbs-2mb-flash-microcontrollers-mcus-based-on-arm-cortex-m4-core:K66_180) ## Atmel ATSAM There is limited support for one of Atmel's ATSAM microcontrollers, that being the [ATSAMD51J18A](https://www.microchip.com/wwwproducts/en/ATSAMD51J18A) used by the [Massdrop keyboards](https://github.com/qmk/qmk_firmware/tree/master/keyboards/massdrop). + +## RISC-V + +### GigaDevice + +[ChibiOS-Contrib](https://github.com/ChibiOS/ChibiOS-Contrib) has support for the GigaDevice [GD32VF103 series](https://www.gigadevice.com/products/microcontrollers/gd32/risc-v/mainstream-line/gd32vf103-series/) microcontrollers and provides configurations for the [SiPeed Longan Nano](https://longan.sipeed.com/en/) development board that uses this microcontroller. It is largely pin and feature compatible with STM32F103 and STM32F303 microcontrollers.
\ No newline at end of file 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/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 463366ff76..798c346e67 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -149,7 +149,7 @@ This is useful for setting up stuff that you may need elsewhere, but isn't hardw * GPIO pin initialisation: `void matrix_init_pins(void)` * This needs to perform the low-level initialisation of all row and column pins. By default this will initialise the input/output state of each of the GPIO pins listed in `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no initialisation of pin state will occur within QMK itself, instead deferring to the keyboard's override. * `COL2ROW`-based row reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)` -* `ROW2COL`-based column reads: `void matrix_read_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col)` +* `ROW2COL`-based column reads: `void matrix_read_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col, matrix_row_t row_shifter)` * `DIRECT_PINS`-based reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)` * These three functions need to perform the low-level retrieval of matrix state of relevant input pins, based on the matrix type. Only one of the functions should be implemented, if needed. By default this will iterate through `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, configuring the inputs and outputs based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no manipulation of matrix GPIO pin state will occur within QMK itself, instead deferring to the keyboard's override. 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/driver_installation_zadig.md b/docs/driver_installation_zadig.md index 9155e56e37..003629ba9a 100644 --- a/docs/driver_installation_zadig.md +++ b/docs/driver_installation_zadig.md @@ -93,6 +93,7 @@ The device name here is the name that appears in Zadig, and may not be what the |`usbasploader`|USBasp |`16C0:05DC` |libusbK| |`apm32-dfu` |APM32 DFU ISP Mode |`314B:0106` |WinUSB | |`stm32-dfu` |STM32 BOOTLOADER |`0483:DF11` |WinUSB | +|`gd32v-dfu` |GD32V BOOTLOADER |`28E9:0189` |WinUSB | |`kiibohd` |Kiibohd DFU Bootloader |`1C11:B007` |WinUSB | |`stm32duino` |Maple 003 |`1EAF:0003` |WinUSB | |`qmk-hid` |(keyboard name) Bootloader |`03EB:2067` |HidUsb | diff --git a/docs/es/hardware_drivers.md b/docs/es/hardware_drivers.md index e0a9736068..788de2c5ef 100644 --- a/docs/es/hardware_drivers.md +++ b/docs/es/hardware_drivers.md @@ -18,10 +18,6 @@ Soporte para direccionar pines en el ProMicro por su nombre Arduino en lugar de Soporte para pantallas OLED basadas en SSD1306. Para obtener más información consulta la página de [Característica de Controlador OLED](feature_oled_driver.md). -## uGFX - -Puedes hacer uso de uGFX dentro de QMK para manejar LCDs de caracteres y gráficos, matrices de LED, OLED, TFT, y otras tecnologías de visualización. Esto necesita ser mejor documentado. Si estás tratando de hacer esto y leer el código no ayuda por favor [abre una issue](https://github.com/qmk/qmk_firmware/issues/new) y podemos ayudarte por el proceso. - ## WS2812 (Solo AVR) Soporte para LEDs WS2811/WS2812{a,b,c}. Para obtener más información consulta la página de [Luz RGB](feature_rgblight.md). diff --git a/docs/es/hardware_keyboard_guidelines.md b/docs/es/hardware_keyboard_guidelines.md index a505cc5ce1..298a3b7ce7 100644 --- a/docs/es/hardware_keyboard_guidelines.md +++ b/docs/es/hardware_keyboard_guidelines.md @@ -142,8 +142,6 @@ El año debe ser el primer año en que se crea el archivo. Si el trabajo se hizo El núcleo de QMC está licenciado bajo la [GNU General Public License](https://www.gnu.org/licenses/licenses.en.html). Si estás enviando binarios para los procesadores AVR puedes elegir cualquiera [GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) o [GPLv3](https://www.gnu.org/licenses/gpl.html). Si estás enviando binarios para ARM procesadores debes elegir [GPL Versión 3](https://www.gnu.org/licenses/gpl.html) para cumplir con los [ChibiOS](https://www.chibios.org) licencia GPLv3. -Si tu teclado hace uso de la [uGFX](https://gfx.io) características dentro de QMK debes cumplir con la [Licencia de uGFX](https://ugfx.io/license.html), que requiere una licencia comercial separada antes de vender un dispositivo que contiene uGFX. - ## Detalles técnicos Si estás buscando más información sobre cómo hacer que su teclado funcione con QMK, [echa un vistazo a la sección hardware](hardware.md)! 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/faq_misc.md b/docs/faq_misc.md index 9ab2b69a80..41d17906bf 100644 --- a/docs/faq_misc.md +++ b/docs/faq_misc.md @@ -36,7 +36,7 @@ Size after: can retry, loading that one - Some of the options you might specify in your keyboard's Makefile consume extra memory; watch out for BOOTMAGIC_ENABLE, |