diff options
Diffstat (limited to 'docs')
55 files changed, 339 insertions, 271 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/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/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, - MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE + MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE - DFU tools do /not/ allow you to write into the bootloader (unless you throw in an extra fruit salad of options), so there is little risk there. 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..fdf19c1077 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) @@ -17,22 +17,23 @@ Not Supported Yet but possible: ### Adafruit BLE SPI Friend Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit SPI Friend. It's a Nordic nRF5182 based chip running Adafruit's custom firmware. Data is transmitted via Adafruit's SDEP over Hardware SPI. The [Feather 32u4 Bluefruit LE](https://www.adafruit.com/product/2829) is supported as it's an AVR mcu connected via SPI to the Nordic BLE chip with Adafruit firmware. If Building a custom board with the SPI friend it would be easiest to just use the pin selection that the 32u4 feather uses but you can change the pins in the config.h options with the following defines: -* #define AdafruitBleResetPin D4 -* #define AdafruitBleCSPin B4 -* #define AdafruitBleIRQPin E6 +* `#define ADAFRUIT_BLE_RST_PIN D4` +* `#define ADAFRUIT_BLE_CS_PIN B4` +* `#define ADAFRUIT_BLE_IRQ_PIN E6` 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/< |