diff options
Diffstat (limited to 'docs')
59 files changed, 1801 insertions, 582 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 8347805a2f..2f6309e41d 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -36,6 +36,7 @@ * Guides * [Customizing Functionality](custom_quantum_functions.md) * [Driver Installation with Zadig](driver_installation_zadig.md) + * [Easy Maker for One Offs](easy_maker.md) * [Keymap Overview](keymap.md) * Development Environments * [Docker Guide](getting_started_docker.md) @@ -61,6 +62,7 @@ * [Language-Specific Keycodes](reference_keymap_extras.md) * [Modifier Keys](feature_advanced_keycodes.md) * [Quantum Keycodes](quantum_keycodes.md) + * [Magic Keycodes](keycodes_magic.md) * Advanced Keycodes * [Command](feature_command.md) @@ -78,6 +80,7 @@ * [Combos](feature_combo.md) * [Debounce API](feature_debounce_type.md) * [Key Lock](feature_key_lock.md) + * [Key Overrides](feature_key_overrides.md) * [Layers](feature_layers.md) * [One Shot Keys](one_shot_keys.md) * [Pointing Device](feature_pointing_device.md) @@ -94,6 +97,7 @@ * Hardware Features * Displays * [HD44780 LCD Controller](feature_hd44780.md) + * [ST7565 LCD Driver](feature_st7565.md) * [OLED Driver](feature_oled_driver.md) * Lighting * [Backlight](feature_backlight.md) @@ -102,8 +106,9 @@ * [RGB Matrix](feature_rgb_matrix.md) * [Audio](feature_audio.md) * [Bluetooth](feature_bluetooth.md) - * [Bootmagic](feature_bootmagic.md) + * [Bootmagic Lite](feature_bootmagic.md) * [Custom Matrix](custom_matrix.md) + * [Digitizer](feature_digitizer.md) * [DIP Switch](feature_dip_switch.md) * [Encoders](feature_encoders.md) * [Haptic Feedback](feature_haptic_feedback.md) diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index b0d56a81bd..a1a56bd457 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -100,3 +100,7 @@ This happens immediately after the previous `develop` branch is merged. * [ ] `git pull --ff-only` * [ ] `git merge --no-ff develop` * [ ] `git push upstream master` + +## Post-merge operations + +* (Optional) [update ChibiOS + ChibiOS-Contrib on `develop`](chibios_upgrade_instructions.md) diff --git a/docs/chibios_upgrade_instructions.md b/docs/chibios_upgrade_instructions.md new file mode 100644 index 0000000000..40c2faafcf --- /dev/null +++ b/docs/chibios_upgrade_instructions.md @@ -0,0 +1,56 @@ +# ChibiOS Upgrade Procedure + +ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a branch tied to the ChibiOS version in use and should not be mixed with different versions. + +## Getting ChibiOS + +* `svn` Initialisation: + * Only needed to be done once + * You might need to separately install `git-svn` package in your OS's package manager + * `git svn init --stdlayout --prefix='svn/' http://svn.osdn.net/svnroot/chibios/` + * `git remote add qmk git@github.com:qmk/ChibiOS.git` +* Updating: + * `git svn fetch` + * 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` + +## Getting ChibiOS-Contrib + +* `git` Initialisation: + * `git clone git@github.com:qmk/ChibiOS-Contrib` + * `git remote add upstream https://github.com/ChibiOS/ChibiOS-Contrib` + * `git checkout -b chibios-20.3.x upstream/chibios-20.3.x` +* Updating: + * `git fetch --all --tags --prune` + * `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` + +## Updating submodules + +* Update the submodules + * `cd $QMK_FIRMWARE` + * `git checkout develop` + * `git pull --ff-only` + * `git checkout -b chibios-version-bump` + * `cd lib/chibios` + * `git fetch --all --tags --prune` + * `git checkout breaking_YYYY_qN` + * `cd ../chibios-contrib` + * `git fetch --all --tags --prune` + * `git checkout breaking_YYYY_qN` +* 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 push --set-upstream origin chibios-version-bump` +* Make a PR to qmk_firmware with the new branch
\ No newline at end of file diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 4e27622c74..8fa7ad41dc 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -17,7 +17,7 @@ qmk compile [-c] <configuratorExport.json> **Usage for Keymaps**: ``` -qmk compile [-c] [-e <var>=<value>] -kb <keyboard_name> -km <keymap_name> +qmk compile [-c] [-e <var>=<value>] [-j <num_jobs>] -kb <keyboard_name> -km <keymap_name> ``` **Usage in Keyboard Directory**: @@ -73,6 +73,17 @@ $ qmk compile -kb dz60 ... ``` +**Parallel Compilation**: + +It is possible to speed up compilation by adding the `-j`/`--parallel` flag. +``` +qmk compile -j <num_jobs> -kb <keyboard_name> +``` +The `num_jobs` argument determines the maximum number of jobs that can be used. Setting it to zero will enable parallel compilation without limiting the maximum number of jobs. +``` +qmk compile -j 0 -kb <keyboard_name> +``` + ## `qmk flash` This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default. To specify a different bootloader, use `-bl <bootloader>`. Visit the [Flashing Firmware](flashing.md) guide for more details of the available bootloaders. @@ -82,13 +93,13 @@ This command is directory aware. It will automatically fill in KEYBOARD and/or K **Usage for Configurator Exports**: ``` -qmk flash [-bl <bootloader>] [-c] [-e <var>=<value>] <configuratorExport.json> +qmk flash [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>] <configuratorExport.json> ``` **Usage for Keymaps**: ``` -qmk flash -kb <keyboard_name> -km <keymap_name> [-bl <bootloader>] [-c] [-e <var>=<value>] +qmk flash -kb <keyboard_name> -km <keymap_name> [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>] ``` **Listing the Bootloaders** @@ -109,7 +120,7 @@ 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_ENABLED=yes`. +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**: @@ -280,12 +291,12 @@ qmk list-keymaps -kb planck/ez This command creates a new keyboard based on available templates. -This command will prompt for input to guide you though the generation process. +Any arguments that are not provided will prompt for input. If `-u` is not passed and `user.name` is set in .gitconfig, it will be used as the default username in the prompt. **Usage**: ``` -qmk new-keyboard +qmk new-keyboard [-kb KEYBOARD] [-t {avr,ps2avrgb}] -u USERNAME ``` ## `qmk new-keymap` @@ -314,7 +325,18 @@ qmk clean [-a] # Developer Commands -## `qmk cformat` +## `qmk format-text` + +This command formats text files to have proper line endings. + +Every text file in the repository needs to have Unix (LF) line ending. +If you are working on **Windows**, you must ensure that line endings are corrected in order to get your PRs merged. + +``` +qmk format-text +``` + +## `qmk format-c` This command formats C code using clang-format. @@ -325,25 +347,25 @@ Run it with `-a` to format all core code, or pass filenames on the command line **Usage for specified files**: ``` -qmk cformat [file1] [file2] [...] [fileN] +qmk format-c [file1] [file2] [...] [fileN] ``` **Usage for all core files**: ``` -qmk cformat -a +qmk format-c -a ``` **Usage for only changed files against origin/master**: ``` -qmk cformat +qmk format-c ``` **Usage for only changed files against branch_name**: ``` -qmk cformat -b branch_name +qmk format-c -b branch_name ``` ## `qmk docs` @@ -369,7 +391,7 @@ qmk generate-docs ## `qmk generate-rgb-breathe-table` -This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight.md) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/`. +This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight.md) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/rgblight/`. **Usage**: @@ -399,14 +421,14 @@ $ qmk kle2json -f kle.txt -f Ψ Wrote out to info.json ``` -## `qmk pyformat` +## `qmk format-python` This command formats python code in `qmk_firmware`. **Usage**: ``` -qmk pyformat +qmk format-python ``` ## `qmk pytest` diff --git a/docs/cli_development.md b/docs/cli_development.md index 07c8f281ba..0f4f401b33 100644 --- a/docs/cli_development.md +++ b/docs/cli_development.md @@ -188,7 +188,7 @@ cli.log.info('Reading from %s and writing to %s', cli.args.filename, cli.args.ou # Testing, and Linting, and Formatting (oh my!) -We use nose2, flake8, and yapf to test, lint, and format code. You can use the `pytest` and `pyformat` subcommands to run these tests: +We use nose2, flake8, and yapf to test, lint, and format code. You can use the `pytest` and `format-py` subcommands to run these tests: ### Testing and Linting @@ -196,7 +196,7 @@ We use nose2, flake8, and yapf to test, lint, and format code. You can use the ` ### Formatting - qmk pyformat + qmk format-py ## Formatting Details diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 0f5b140de0..2bf3b0ebb7 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -27,10 +27,13 @@ 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) + * [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) * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) * [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) + * [STM32L412](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html) + * [STM32L422](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html) * [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) * [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) diff --git a/docs/config_options.md b/docs/config_options.md index d0f0b316e0..94f99e74c0 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -51,8 +51,10 @@ This is a C header file that is one of the first things included, and will persi * the number of columns in your keyboard's matrix * `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }` * pins of the rows, from top to bottom + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. * `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }` * pins of the columns, from left to right + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. * `#define MATRIX_IO_DELAY 30` * the delay in microseconds when between changing matrix pin state and reading values * `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }` @@ -186,13 +188,27 @@ If you define these options you will enable the associated feature, which may in few ms of delay from this. But if you're doing chording on something with 3-4ms scan times? You probably want this. * `#define COMBO_COUNT 2` - * Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature. + * Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature. Or leave it undefined and programmatically set the count. * `#define COMBO_TERM 200` * how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined. +* `#define COMBO_MUST_HOLD_MODS` + * Flag for enabling extending timeout on Combos containing modifers +* `#define COMBO_MOD_TERM 200` + * Allows for extending COMBO_TERM for mod keys while mid-combo. +* `#define COMBO_MUST_HOLD_PER_COMBO` + * Flag to enable per-combo COMBO_TERM extension and `get_combo_must_hold()` function +* `#define COMBO_TERM_PER_COMBO` + * Flag to enable per-combo COMBO_TERM extension and `get_combo_term()` function +* `#define COMBO_STRICT_TIMER` + * Only start the combo timer on the first key press instead of on all key presses. +* `#define COMBO_NO_TIMER` + * Disable the combo timer completely for relaxed combos. * `#define TAP_CODE_DELAY 100` * Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds. * `#define TAP_HOLD_CAPS_DELAY 80` * Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPSLOCK` keycode, as this has some special handling on MacOS. The value is in milliseconds, and defaults to 80 ms if not defined. For macOS, you may want to set this to 200 or higher. +* `#define KEY_OVERRIDE_REPEAT_DELAY 500` + * Sets the key repeat interval for [key overrides](feature_key_overrides.md). ## RGB Light Configuration @@ -272,7 +288,7 @@ There are a few different ways to set handedness for split keyboards (listed in ### Other Options * `#define USE_I2C` - * For using I2C instead of Serial (defaults to serial) + * For using I2C instead of Serial (default is serial; serial transport is supported on ARM -- I2C is AVR-only) * `#define SOFT_SERIAL_PIN D0` * When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`. @@ -280,6 +296,7 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define MATRIX_ROW_PINS_RIGHT { <row pins> }` * `#define MATRIX_COL_PINS_RIGHT { <col pins> }` * If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns. + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. * `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }` * If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`. @@ -300,7 +317,7 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define SPLIT_USB_DETECT` * Detect (with timeout) USB connection when delegating master/slave * Default behavior for ARM - * Required for AVR Teensy + * Required for AVR Teensy (without hardware mods) * `#define SPLIT_USB_TIMEOUT 2000` * Maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT` @@ -308,6 +325,34 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define SPLIT_USB_TIMEOUT_POLL 10` * Poll frequency when detecting master/slave when using `SPLIT_USB_DETECT` +* `#define FORCED_SYNC_THROTTLE_MS 100` + * Deadline for synchronizing data from master to slave when using the QMK-provided split transport. + +* `#define SPLIT_TRANSPORT_MIRROR` + * Mirrors the master-side matrix on the slave when using the QMK-provided split transport. + +* `#define SPLIT_LAYER_STATE_ENABLE` + * Ensures the current layer state is available on the slave when using the QMK-provided split transport. + +* `#define SPLIT_LED_STATE_ENABLE` + * Ensures the current host indicator state (caps/num/scroll) is available on the slave when using the QMK-provided split transport. + +* `#define SPLIT_MODS_ENABLE` + * Ensures the current modifier state (normal, weak, and oneshot) is available on the slave when using the QMK-provided split transport. + +* `#define SPLIT_WPM_ENABLE` + * Ensures the current WPM is available on the slave when using the QMK-provided split transport. + +* `#define SPLIT_OLED_ENABLE` + * Syncs the on/off state of the OLED between the halves. + +* `#define SPLIT_ST7565_ENABLE` + * Syncs the on/off state of the ST7565 screen between the halves. + +* `#define SPLIT_TRANSACTION_IDS_KB .....` +* `#define SPLIT_TRANSACTION_IDS_USER .....` + * Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](feature_split_keyboard.md#custom-data-sync) for more information. + # The `rules.mk` File This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features. @@ -375,6 +420,8 @@ Use these to enable or disable building certain features. The more you have enab * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work * `AUDIO_ENABLE` * Enable the audio subsystem. +* `KEY_OVERRIDE_ENABLE` + * Enable the key override feature * `RGBLIGHT_ENABLE` * Enable keyboard underlight functionality * `LEADER_ENABLE` diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 694b421e79..494e76996e 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -144,6 +144,14 @@ This is useful for setting up stuff that you may need elsewhere, but isn't hardw * Keyboard/Revision: `void matrix_init_kb(void)` * Keymap: `void matrix_init_user(void)` +### Low-level Matrix Overrides Function Documentation :id=low-level-matrix-overrides + +* 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_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col)` +* `ROW2COL`-based column reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)` +* `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. ## Keyboard Post Initialization code @@ -374,7 +382,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { } } ``` -And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EEP_RST` keycode or [Bootmagic](feature_bootmagic.md) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued. +And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an |