diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_summary.md | 1 | ||||
| -rw-r--r-- | docs/config_options.md | 5 | ||||
| -rw-r--r-- | docs/feature_caps_word.md | 20 | ||||
| -rw-r--r-- | docs/feature_converters.md | 8 | ||||
| -rw-r--r-- | docs/feature_dynamic_macros.md | 2 | ||||
| -rw-r--r-- | docs/feature_encoders.md | 14 | ||||
| -rw-r--r-- | docs/feature_pointing_device.md | 22 | ||||
| -rw-r--r-- | docs/feature_rgb_matrix.md | 4 | ||||
| -rw-r--r-- | docs/feature_rgblight.md | 5 | ||||
| -rw-r--r-- | docs/feature_split_keyboard.md | 6 | ||||
| -rw-r--r-- | docs/feature_stenography.md | 2 | ||||
| -rw-r--r-- | docs/getting_started_vagrant.md | 56 | ||||
| -rw-r--r-- | docs/ja/_summary.md | 1 | ||||
| -rw-r--r-- | docs/ja/config_options.md | 3 | ||||
| -rw-r--r-- | docs/ja/feature_dynamic_macros.md | 2 | ||||
| -rw-r--r-- | docs/ja/feature_stenography.md | 2 | ||||
| -rw-r--r-- | docs/ja/getting_started_vagrant.md | 61 | ||||
| -rw-r--r-- | docs/ja/tap_hold.md | 28 | ||||
| -rw-r--r-- | docs/mod_tap.md | 2 | ||||
| -rw-r--r-- | docs/newbs_building_firmware_workflow.md | 2 | ||||
| -rw-r--r-- | docs/quantum_painter.md | 22 | ||||
| -rw-r--r-- | docs/squeezing_avr.md | 1 | ||||
| -rw-r--r-- | docs/tap_hold.md | 89 | ||||
| -rw-r--r-- | docs/ws2812_driver.md | 4 | ||||
| -rw-r--r-- | docs/zh-cn/_summary.md | 3 | ||||
| -rw-r--r-- | docs/zh-cn/getting_started_vagrant.md | 61 |
26 files changed, 96 insertions, 330 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 01808bd675..ce579cb071 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -41,7 +41,6 @@ * [Keymap Overview](keymap.md) * Development Environments * [Docker Guide](getting_started_docker.md) - * [Vagrant Guide](getting_started_vagrant.md) * Flashing * [Flashing](flashing.md) * [Flashing ATmega32A (ps2avrgb)](flashing_bootloadhid.md) diff --git a/docs/config_options.md b/docs/config_options.md index 5bfb7c5d58..8ea059a352 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -150,7 +150,7 @@ If you define these options you will enable the associated feature, which may in * `#define TAPPING_TERM_PER_KEY` * enables handling for per key `TAPPING_TERM` settings * `#define RETRO_TAPPING` - * tap anyway, even after TAPPING_TERM, if there was no other key interruption between press and release + * tap anyway, even after `TAPPING_TERM`, if there was no other key interruption between press and release * See [Retro Tapping](tap_hold.md#retro-tapping) for details * `#define RETRO_TAPPING_PER_KEY` * enables handling for per key `RETRO_TAPPING` settings @@ -161,9 +161,6 @@ If you define these options you will enable the associated feature, which may in * See [Permissive Hold](tap_hold.md#permissive-hold) for details * `#define PERMISSIVE_HOLD_PER_KEY` * enabled handling for per key `PERMISSIVE_HOLD` settings -* `#define IGNORE_MOD_TAP_INTERRUPT` - * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold, by enforcing the `TAPPING_TERM` for both keys. - * See [Ignore Mod Tap Interrupt](tap_hold.md#ignore-mod-tap-interrupt) for details * `#define QUICK_TAP_TERM 100` * tap-then-hold timing to use a dual role key to repeat keycode * See [Quick Tap Term](tap_hold.md#quick-tap-term) diff --git a/docs/feature_caps_word.md b/docs/feature_caps_word.md index c58d1a56e2..7f726b059d 100644 --- a/docs/feature_caps_word.md +++ b/docs/feature_caps_word.md @@ -90,6 +90,26 @@ by defining `IS_COMMAND()` in config.h: ## Customizing Caps Word :id=customizing-caps-word +### Invert on shift :id=invert-on-shift + +By default, Caps Word turns off when Shift keys are pressed, considering them as +word-breaking. Alternatively with the `CAPS_WORD_INVERT_ON_SHIFT` option, +pressing the Shift key continues Caps Word and inverts the shift state. This +is convenient for uncapitalizing one or a few letters within a word, for +example with Caps Word on, typing "D, B, Shift+A, Shift+A, S" produces "DBaaS", +or typing "P, D, F, Shift+S" produces "PDFs". + +Enable it by adding in config.h + +```c +#define CAPS_WORD_INVERT_ON_SHIFT +``` + +This option works with regular Shift keys `KC_LSFT` and `KC_RSFT`, mod-tap Shift +keys, and one-shot Shift keys. Note that while Caps Word is on, one-shot Shift +keys behave like regular Shift keys, and have effect only while they are held. + + ### Idle timeout :id=idle-timeout Caps Word turns off automatically if no keys are pressed for diff --git a/docs/feature_converters.md b/docs/feature_converters.md index 9baac14e97..3871f77ee0 100644 --- a/docs/feature_converters.md +++ b/docs/feature_converters.md @@ -21,11 +21,13 @@ Currently the following converters are available: | `promicro` | `rp2040_ce` | | `promicro` | `elite_pi` | | `promicro` | `helios` | +| `promicro` | `liatris` | | `promicro` | `michi` | | `elite_c` | `stemcell` | | `elite_c` | `rp2040_ce` | | `elite_c` | `elite_pi` | | `elite_c` | `helios` | +| `elite_c` | `liatris` | See below for more in depth information on each converter. @@ -88,6 +90,7 @@ If a board currently supported in QMK uses a [Pro Micro](https://www.sparkfun.co | [customMK Bonsai C4](https://shop.custommk.com/products/bonsai-c4-microcontroller-board) | `bonsai_c4` | | [Elite-Pi](https://keeb.io/products/elite-pi-usb-c-pro-micro-replacement-rp2040) | `elite_pi` | | [0xCB Helios](https://keeb.supply/products/0xcb-helios) | `helios` | +| [Liatris](https://splitkb.com/products/liatris) | `liatris` | | [Michi](https://github.com/ci-bus/michi-promicro-rp2040) | `michi` | Converter summary: @@ -104,6 +107,7 @@ Converter summary: | `rp2040_ce` | `-e CONVERT_TO=rp2040_ce` | `CONVERT_TO=rp2040_ce` | `#ifdef CONVERT_TO_RP2040_CE` | | `elite_pi` | `-e CONVERT_TO=elite_pi` | `CONVERT_TO=elite_pi` | `#ifdef CONVERT_TO_ELITE_PI` | | `helios` | `-e CONVERT_TO=helios` | `CONVERT_TO=helios` | `#ifdef CONVERT_TO_HELIOS` | +| `liatris` | `-e CONVERT_TO=liatris` | `CONVERT_TO=liatris` | `#ifdef CONVERT_TO_LIATRIS` | | `michi` | `-e CONVERT_TO=michi` | `CONVERT_TO=michi` | `#ifdef CONVERT_TO_MICHI` | ### Proton C :id=proton_c @@ -168,7 +172,7 @@ The Bonsai C4 only has one on-board LED (B2), and by default, both the Pro Micro #define B0 PAL_LINE(GPIOA, 9) ``` -### RP2040 Community Edition - Elite-Pi and Helios :id=rp2040_ce +### RP2040 Community Edition - Elite-Pi, Helios, and Liatris :id=rp2040_ce Feature set currently identical to [Adafruit KB2040](#kb2040). @@ -185,6 +189,7 @@ If a board currently supported in QMK uses an [Elite-C](https://keeb.io/products | [STeMCell](https://github.com/megamind4089/STeMCell) | `stemcell` | | [Elite-Pi](https://keeb.io/products/elite-pi-usb-c-pro-micro-replacement-rp2040) | `elite_pi` | | [0xCB Helios](https://keeb.supply/products/0xcb-helios) | `helios` | +| [Liatris](https://splitkb.com/products/liatris) | `liatris` | Converter summary: @@ -194,6 +199,7 @@ Converter summary: | `rp2040_ce` | `-e CONVERT_TO=rp2040_ce` | `CONVERT_TO=rp2040_ce` | `#ifdef CONVERT_TO_RP2040_CE` | | `elite_pi` | `-e CONVERT_TO=elite_pi` | `CONVERT_TO=elite_pi` | `#ifdef CONVERT_TO_ELITE_PI` | | `helios` | `-e CONVERT_TO=helios` | `CONVERT_TO=helios` | `#ifdef CONVERT_TO_HELIOS` | +| `liatris` | `-e CONVERT_TO=liatris` | `CONVERT_TO=liatris` | `#ifdef CONVERT_TO_LIATRIS` | ### STeMCell :id=stemcell_elite diff --git a/docs/feature_dynamic_macros.md b/docs/feature_dynamic_macros.md index f5a6952b6b..8ab1bad61c 100644 --- a/docs/feature_dynamic_macros.md +++ b/docs/feature_dynamic_macros.md @@ -59,7 +59,7 @@ There are a number of hooks that you can use to add custom functionality and fee Note, that direction indicates which macro it is, with `1` being Macro 1, `-1` being Macro 2, and 0 being no macro. -* `dynamic_macro_record_start_user(void)` - Triggered when you start recording a macro. +* `dynamic_macro_record_start_user(int8_t direction)` - Triggered when you start recording a macro. * `dynamic_macro_play_user(int8_t direction)` - Triggered when you play back a macro. * `dynamic_macro_record_key_user(int8_t direction, keyrecord_t *record)` - Triggered on each keypress while recording a macro. * `dynamic_macro_record_end_user(int8_t direction)` - Triggered when the macro recording is stopped. diff --git a/docs/feature_encoders.md b/docs/feature_encoders.md index 1c521a4eff..74857c265d 100644 --- a/docs/feature_encoders.md +++ b/docs/feature_encoders.md @@ -102,9 +102,9 @@ Using encoder mapping pumps events through the normal QMK keycode processing pip ## Callbacks -When not using `ENCODER_MAP_ENABLE = yes`, the callback functions can be inserted into your `<keyboard>.c`: +?> [**Default Behaviour**](https://github.com/qmk/qmk_firmware/blob/master/quantum/encoder.c#L79-#L98): all encoders installed will function as volume up (`KC_VOLU`) on clockwise rotation and volume down (`KC_VOLD`) on counter-clockwise rotation. If you do not wish to override this, no further configuration is necessary. -?> Those who are adding new keyboard support where encoders are enabled at the keyboard level should include basic encoder functionality at the keyboard level (`<keyboard>.c`) using the `encoder_update_kb()` function, that way it works for QMK Configuator users and exists in general. +If you would like the alter the default behaviour, and are not using `ENCODER_MAP_ENABLE = yes`, the callback functions can be inserted into your `<keyboard>.c`: ```c bool encoder_update_kb(uint8_t index, bool clockwise) { @@ -113,9 +113,9 @@ bool encoder_update_kb(uint8_t index, bool clockwise) { } if (index == 0) { /* First encoder */ if (clockwise) { - tap_code_delay(KC_VOLU, 10); + tap_code(KC_PGDN); } else { - tap_code_delay(KC_VOLD, 10); + tap_code(KC_PGUP); } } else if (index == 1) { /* Second encoder */ if (clockwise) { @@ -134,9 +134,9 @@ or `keymap.c`: bool encoder_update_user(uint8_t index, bool clockwise) { if (index == 0) { /* First encoder */ if (clockwise) { - tap_code_delay(KC_VOLU, 10); + tap_code(KC_PGDN); } else { - tap_code_delay(KC_VOLD, 10); + tap_code(KC_PGUP); } } else if (index == 1) { /* Second encoder */ if (clockwise) { @@ -149,7 +149,7 @@ bool encoder_update_user(uint8_t index, bool clockwise) { } ``` -!> If you return `true` in the keymap level `_user` function, it will allow the keyboard level encoder code to run on top of your own. Returning `false` will override the keyboard level function, if setup correctly. This is generally the safest option to avoid confusion. +!> If you return `true` in the keymap level `_user` function, it will allow the keyboard/core level encoder code to run on top of your own. Returning `false` will override the keyboard level function, if setup correctly. This is generally the safest option to avoid confusion. ## Hardware diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md index 0089dc7024..c459ba4e9d 100644 --- a/docs/feature_pointing_device.md +++ b/docs/feature_pointing_device.md @@ -197,6 +197,24 @@ The Pimoroni Trackball module is a I2C based breakout board with an RGB enable t | `PIMORONI_TRACKBALL_DEBOUNCE_CYCLES` | (Optional) The number of scan cycles used for debouncing on the ball press. | `20` | | `PIMORONI_TRACKBALL_ERROR_COUNT` | (Optional) Specifies the number of read/write errors until the sensor is disabled. | `10` | +### PMW3320 Sensor + +To use the PMW3320 sensor, add this to your `rules.mk` + +```make +POINTING_DEVICE_DRIVER = pmw3320 +``` + +The PMW3320 sensor uses a serial type protocol for communication, and requires an additional light source (it could work without one, but expect it to be out of service early). + +| Setting | Description | Default | +| ------------------- | ------------------------------------------------------------------- | -------------------------- | +| `PMW3320_SCLK_PIN` | (Required) The pin connected to the clock pin of the sensor. | `POINTING_DEVICE_SCLK_PIN` | +| `PMW3320_SDIO_PIN` | (Required) The pin connected to the data pin of the sensor. | `POINTING_DEVICE_SDIO_PIN` | +| `PMW3320_CS_PIN` | (Required) The pin connected to the cable select pin of the sensor. | `POINTING_DEVICE_CS_PIN` | + +The CPI range is 500-3500, in increments of 250. Defaults to 1000 CPI. + ### PMW 3360 and PMW 3389 Sensor This drivers supports both the PMW 3360 and PMW 3389 sensor as well as multiple sensors of the same type _per_ controller, so 2 can be attached at the same side for split keyboards (or unsplit keyboards). @@ -713,7 +731,7 @@ _Note: The Cirque pinnacle track pad already implements a custom activation func When using a custom pointing device (overwriting `pointing_device_task`) the following code should be somewhere in the `pointing_device_task_*` stack: ```c -void pointing_device_task(void) { +bool pointing_device_task(void) { //...Custom pointing device task code // handle automatic mouse layer (needs report_mouse_t as input) @@ -721,7 +739,7 @@ void pointing_device_task(void) { //...More custom pointing device task code - pointing_device_send(); + return pointing_device_send(); } ``` diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 20ad4c7faf..8b831f010b 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -383,9 +383,9 @@ Configure the hardware via your `config.h`: ```c // The pin connected to the data pin of the LEDs -#define RGB_DI_PIN D7 +#define APA102_DI_PIN D7 // The pin connected to the clock pin of the LEDs -#define RGB_CI_PIN D6 +#define APA102_CI_PIN D6 // The number of LEDs connected #define RGB_MATRIX_LED_COUNT 70 ``` diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 060efaf1b3..7a1866d44f 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -35,8 +35,9 @@ At minimum you must define the data pin your LED strip is connected to, and the |Define |Description | |---------------|---------------------------------------------------------------------------------------------------------| -|`RGB_DI_PIN` |The pin connected to the data pin of the LEDs | -|`RGB_CI_PIN` |The pin connected to the clock pin of the LEDs (APA102 only) | +|`RGB_DI_PIN` |The pin connected to the data pin of the LEDs (WS2812) | +|`APA102_DI_PIN`|The pin connected to the data pin of the LEDs (APA102) | +|`APA102_CI_PIN`|The pin connected to the clock pin of the LEDs (APA102) | |`RGBLED_NUM` |The number of LEDs connected | |`RGBLED_SPLIT` |(Optional) For split keyboards, the number of LEDs connected on each half directly wired to `RGB_DI_PIN` | diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index c095c8712f..1705ea9222 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -300,6 +300,12 @@ This enables transmitting the pointing device status to the master side of the s This enables triggering of haptic feedback on the slave side of the split keyboard. For DRV2605L this will send the mode, but for solenoids it is expected that the desired mode is already set up on the slave. +```c +#define SPLIT_ACTIVITY_ENABLE +``` + +This synchronizes the activity timestamps between sides of the split keyboard, allowing for activity timeouts to occur. + ### Custom data sync between sides :id=custom-data-sync QMK's split transport allows for arbitrary data transactions at both the keyboard and user levels. This is modelled on a remote procedure call, with the master invoking a function on the slave side, with the ability to send data from master to slave, process it slave side, and send data back from slave to master. diff --git a/docs/feature_stenography.md b/docs/feature_stenography.md index 62d4dabf81..df4c9c6ad3 100644 --- a/docs/feature_stenography.md +++ b/docs/feature_stenography.md @@ -138,7 +138,7 @@ bool post_process_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t This function is called after a key has been processed, but before any decision about whether or not to send a chord. This is where to put hooks for things like, say, live displays of steno chords or keys. -If `IS_PRESSED(record->event)` is false, and `n_pressed_keys` is 0 or 1, the chord will be sent shortly, but has not yet been sent. This relieves you of the need of keeping track of where a packet ends and another begins. +If `record->event.pressed` is false, and `n_pressed_keys` is 0 or 1, the chord will be sent shortly, but has not yet been sent. This relieves you of the need of keeping track of where a packet ends and another begins. The `chord` argument contains the packet of the current chord as specified by the protocol in use. This is *NOT* simply a list of chorded steno keys of the form `[STN_E, STN_U, STN_BR, STN_GR]`. Refer to the appropriate protocol section of this document to learn more about the format of the packets in your steno protocol/mode of choice. diff --git a/docs/getting_started_vagrant.md b/docs/getting_started_vagrant.md deleted file mode 100644 index b5b5ce1539..0000000000 --- a/docs/getting_started_vagrant.md +++ /dev/null @@ -1,56 +0,0 @@ -# Vagrant Quick Start - -This project includes a `Vagrantfile` that will allow you to build a new firmware for your keyboard very easily without major changes to your primary operating system. This also ensures that when you clone the project and perform a build, you have the exact same environment as anyone else using the Vagrantfile to build. This makes it much easier for people to help you troubleshoot any issues you encounter. - -## Requirements - -Using the `Vagrantfile` in this repository requires you have [Vagrant](https://www.vagrantup.com/) as well as a supported provider installed: - -* [VirtualBox](https://www.virtualbox.org/) (Version at least 5.0.12) - * Sold as 'the most accessible platform to use Vagrant' -* [VMware Workstation](https://www.vmware.com/products/workstation) and [Vagrant VMware plugin](https://www.vagrantup.com/vmware) - * The (paid) VMware plugin requires a licensed copy of VMware Workstation/Fusion -* [Docker](https://www.docker.com/) - -Other than having Vagrant, a suitable provider installed and possibly a restart of your computer afterwards, you can simple run a 'vagrant up' anywhere inside the folder where you checked out this project and it will start an environment (either a virtual machine or container) that contains all the tools required to build this project. There is a post Vagrant startup hint that will get you off on the right foot, otherwise you can also reference the build documentation below. - -## Flashing the Firmware - -The "easy" way to flash the firmware is using a tool from your host OS: - -* [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (recommended) -* [Teensy Loader](https://www.pjrc.com/teensy/loader.html) - -If you want to program via the command line you can uncomment the ['modifyvm'] lines in the Vagrantfile to enable the USB passthrough into Linux and then program using the command line tools like dfu-util/dfu-programmer or you can install the Teensy CLI version. - -## Vagrantfile Overview -The development environment is configured to run the QMK Docker image, `qmkfm/qmk_cli`. This not only ensures predictability between systems, it also mirrors the CI environment. - -## FAQ - -### 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:** - -``` -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: - -``` -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: -``` -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: - -``` -vagrant ssh -c 'sudo -i' -``` diff --git a/docs/ja/_summary.md b/docs/ja/_summary.md index 8516a5eaaa..e49853bfd4 100644 --- a/docs/ja/_summary.md +++ b/docs/ja/_summary.md @@ -38,7 +38,6 @@ * [キーマップの概要](ja/keymap.md) * 開発環境 * [Docker のガイド](ja/getting_started_docker.md) - * [Vagrant のガイド](ja/getting_started_vagrant.md) * 書き込み * [書き込み](ja/flashing.md) * [ATmega32A の書き込み (ps2avrgb)](ja/flashing_bootloadhid.md) diff --git a/docs/ja/config_options.md b/docs/ja/config_options.md index 6135721a42..4f9f1f2770 100644 --- a/docs/ja/config_options.md +++ b/docs/ja/config_options.md @@ -159,9 +159,6 @@ QMK での全ての利用可能な設定にはデフォルトがあります。 * 詳細は [Permissive Hold](ja/tap_hold.md#permissive-hold) を見てください * `#define PERMISSIVE_HOLD_PER_KEY` * キーごとの `PERMISSIVE_HOLD` 設定の処理を有効にします -* `#define IGNORE_MOD_TAP_INTERRUPT` - * 両方のキーに `TAPPING_TERM` を適用することで、ホールド時に他のキーに変換するキーを使ってローリングコンボ (zx) をすることができるようにします - * 詳細は [Ignore Mod Tap Interrupt](ja/tap_hold.md#ignore-mod-tap-interrupt) を見てください * `#define TAPPING_FORCE_HOLD` * タップされた直後に、デュアルロールキーを修飾子として使用できるようにします * [Tapping Force Hold](ja/tap_hold.md#tapping-force-hold)を見てください diff --git a/docs/ja/feature_dynamic_macros.md b/docs/ja/feature_dynamic_macros.md index 3cff788007..fa1a1df931 100644 --- a/docs/ja/feature_dynamic_macros.md +++ b/docs/ja/feature_dynamic_macros.md @@ -64,7 +64,7 @@ QMK はその場で作られた一時的なマクロをサポートします。 direction がどのマクロであるかを示すことに注意してください。`1` がマクロ 1、`-1` がマクロ 2、0 がマクロ無しです。 -* `dynamic_macro_record_start_user(void)` - マクロの記録を開始する時に起動されます。 +* `dynamic_macro_record_start_user(int8_t direction)` - マクロの記録を開始する時に起動されます。 * `dynamic_macro_play_user(int8_t direction)` - マクロを再生する時に起動されます。 * `dynamic_macro_record_key_user(int8_t direction, keyrecord_t *record)` - マクロの記録中に各キー押下で起動されます。 * `dynamic_macro_record_end_user(int8_t direction)` - マクロの記録を停止した時に起動されます。 diff --git a/docs/ja/feature_stenography.md b/docs/ja/feature_stenography.md index b280084ae3..9551221696 100644 --- a/docs/ja/feature_stenography.md +++ b/docs/ja/feature_stenography.md @@ -80,7 +80,7 @@ bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; } bool post_process_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed); ``` -この関数はキーが処理された後、ただしコードを送信するかどうかを決める前に呼び出されます。`IS_PRESSED(record->event)` が false で、`pressed` が 0 または 1 の場合は、コードはまもなく送信されますが、まだ送信されてはいません。ここが速記コードあるいはキーのライブ表示などのフックを配置する場所です。 +この関数はキーが処理された後、ただしコードを送信するかどうかを決める前に呼び出されます。`record->event.pressed` が false で、`pressed` が 0 または 1 の場合は、コードはまもなく送信されますが、まだ送信されてはいません。ここが速記コードあるいはキーのライブ表示などのフックを配置する場所です。 ## キーコードリファレンス :id=keycode-reference diff --git a/docs/ja/getting_started_vagrant.md b/docs/ja/getting_started_vagrant.md deleted file mode 100644 index 0888b7f311..0000000000 --- a/docs/ja/getting_started_vagrant.md +++ /dev/null @@ -1,61 +0,0 @@ -# Vagrant クイックスタート - -<!--- - original document: 0.12.43:docs/getting_started_vagrant.md - git diff 0.12.43 HEAD -- docs/getting_started_vagrant.md | cat ---> - -このプロジェクトは、プライマリオペレーティングシステムに大きな変更を加えることなくキーボードの新しいファームウェアを非常に簡単に構築することができる `Vagrantfile` を含みます。これは、あなたがプロジェクトをクローンしビルドを実行した時に、ビルドのために Vagrantfile を使っている他のユーザと全く同じ環境を持つことも保証します。これにより、人々はあなたが遭遇した問題の解決をより簡単に行えるようになります。 - -## 必要事項 - -このリポジトリ内の `Vagrantfile` を使うには、[Vagrant](https://www.vagrantup.com/) およびサポートされるプロバイダがインストールされている必要があります: - -* [VirtualBox](https://www.virtualbox.org/) (バージョン 5.0.12 以降) - * 「Vagrant を使うために最もアクセスしやすいプラットフォーム」とうたわれています。 -* [VMware Workstation](https://www.vmware.com/products/workstation) および [Vagrant VMware プラグイン](https://www.vagrantup.com/vmware) - * (有料) VMware プラグインには、ライセンスされた VMware Workstation/Fusion のコピーが必要です。 -* [Docker](https://www.docker.com/) - -Vagrant 以外に、適切なプロバイダがインストールされ、その後におそらくコンピュータを再起動すると、このプロジェクトをチェックアウトしたフォルダ内の任意の場所で 'vagrant up' を単純に実行することができ、このプロジェクトをビルドするのに必要な全てのツールが含まれる環境(仮想マシンあるいはコンテナ)が開始されます。Vagrant 起動時にうまく始めるためのヒントが表示されますが、それ以外に、以下のビルドドキュメントを参照することもできます。 - -## ファームウェアの書き込み - -ファームウェアを書き込む「簡単な」方法は、ホスト OS からツールを使うことです: - -* [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (推奨) -* [Teensy ローダー](https://www.pjrc.com/teensy/loader.html) - -コマンドラインでプログラムしたい場合は、Vagranfile の ['modifyvm'] 行のコメントを解除して Linux への USB パススルーを有効にし、dfu-util/dfu-programmer のようなコマンドラインツールを使ってプログラムすることができます。あるいは Teensy CLI バージョンをインストールすることができます。 - -## Vagrantfile の概要 -開発環境は QMK Docker イメージ、`qmkfm/qmk_cli` を実行するように設定されています。これはシステム間の予測可能性が保証されるだけでなく、CI 環境もミラーされます。 - -## FAQ - -### Virtualbox で問題が発生するのはなぜですか？ -Virtualbox 5 の特定のバージョンはこの Vagrantfile のボックスにインストールされている Virtualbox の拡張機能と互換性が無いようです。/vagrant のマウントで問題が発生した場合は、Virtualbox のバージョンを少なくとも 5.0.12 にアップグレードしてください。**または、以下のコマンドを実行してみることができます:** - -```console -vagrant plugin install vagrant-vbguest -``` - -### 既存の環境を削除するにはどうすればいいですか？ -あなたの環境での作業が完了しましたか？このプロジェクトをチェックアウトしたフォルダの中のどこからでも、以下を実行してください: - -```console -vagrant destroy -``` - -### Docker を直接使いたい場合はどうしますか？ -仮想マシン無しで Vagrant のワークフローを活用したいですか？Vagrantfile は仮想マシンの実行をバイパスし、コンテナを直接実行するように設定されています。Docker を強制的に使うように環境を立ち上げる場合は、以下を実行してください: -```console -vagrant up --provider=docker -``` - -### Docker コンテナではなく仮想マシンにアクセスするにはどうすればいいですか？ -以下を実行して、公式の QMK ビルダーイメージから直接起動する `vagrant` ユーザをバイパスするようにします: - -```console -vagrant ssh -c 'sudo -i' -``` diff --git a/docs/ja/tap_hold.md b/docs/ja/tap_hold.md index ac64fe6ce3..00b80c8b22 100644 --- a/docs/ja/tap_hold.md +++ b/docs/ja/tap_hold.md @@ -63,8 +63,6 @@ uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) { 通常、これら全てを `TAPPING_TERM` (デフォルト: 200ms) 内で行うと、ファームウェアとホストシステムによって `ax` として登録されます。許容ホールドを有効にすると、別のキーがタップされた場合にモッドタップキーを修飾キーと見なすように処理を変更し、 `X` (`SHIFT`+`x`) と登録されます。 -?> `モッドタップ割り込みの無視`を有効にしている場合、これにより両方の動きが変更されます。通常のキーには、最初のキーが最初に放された場合、あるいは両方のキーが `TAPPING_TERM` より長くホールドされた場合に、修飾キーが追加されます。 - この機能をより細かく制御するために、以下を `config.h` に追加することができます: ```c @@ -84,32 +82,6 @@ bool get_permissive_hold(uint16_t keycode, keyrecord_t *record) { } ``` -## モッドタップ割り込みの無視 - -この設定を有効にするには、これを `config.h` に追加してください: - -```c -#define IGNORE_MOD_TAP_INTERRUPT -``` - -許容ホールドと同様に、これは高速なタイピストのためのファームウェアの処理方法を変更します。モッドタップキーを押し、他のキーを押し、モッドタップキーを放し、通常のキーを放すと、`TAPPING_TERM` 内で押された場合でも、通常はモッドと通常のキーが出力されます。これは、ローリングコンボキーや、頻繁に使用するキー(例えば、`RCTL_T(KC_QUOT)`)にモッドタップを使う高速なタイピストには望ましくない場合があります。 - -`モッドタップ割り込みの無視`を設定するには、両方のキーを `TAPPING_TERM` の間ホールドすると、(その修飾キーの)ホールド機能を実行する必要があります。 - -例えば: - -- `SFT_T(KC_A)` を押す -- `KC_X` を押す -- `SFT_T(KC_A)` を放す -- `KC_X` を放す - -通常、これは大文字の `X` (`SHIFT`+`x`)、またはモッド + キーを送信します。`モッドタップ割り込みの無視` を有効にすると、ホールドアクションを登録するには、両方のキーを `TAPPING_TERM` の間ホールドする必要があります。この場合、素早いタップは `ax` を送信しますが、両方をホールドすると、大文字の `X` (`SHIFT`+`x`) を出力します。 - - -?> __注意__: これはモディファイアにのみ関係し、レイヤー切り替えキーには関係しません。 - -?> `許容ホールド`を有効にすると、これは両方がどのように動作するかを変更します。通常のキーには、最初のキーが最初に放された場合、あるいは両方のキーが `TAPPING_TERM` より長くホールドされた場合に、修飾キーが追加されます。 - ## タッピング強制ホールド `タッピング強制ホールド` を有効にするには、以下を `config.h` に追加します: diff --git a/docs/mod_tap.md b/docs/mod_tap.md index ca3a2752c7..8b953d76b4 100644 --- a/docs/mod_tap.md +++ b/docs/mod_tap.md @@ -111,8 +111,6 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { } ``` -Enabling `IGNORE_MOD_TAP_INTERRUPT` is recommended when using Mod-Tap on alphanumeric keys to avoid hold function taking precendence when the next key is pressed quickly. See [Ignore Mod Tap Interrupt](tap_hold.md#ignore-mod-tap-interrupt) for more details. - ### Changing both tap and hold This last example implements custom tap and hold function with `LT(0,KC_NO)` to create a single copy-on-tap, paste-on-hold key: diff --git a/docs/newbs_building_firmware_workflow.md b/docs/newbs_building_firmware_workflow.md index e6895252aa..51ce304901 100644 --- a/docs/newbs_building_firmware_workflow.md +++ b/docs/newbs_building_firmware_workflow.md @@ -95,7 +95,7 @@ on: [push, workflow_dispatch] jobs: build: runs-on: ubuntu-latest - container: qmkfm/qmk_cli + container: ghcr.io/qmk/qmk_cli strategy: fail-fast: false matrix: diff --git a/docs/quantum_painter.md b/docs/quantum_painter.md index ac37053c79..acb9d1d384 100644 --- a/docs/quantum_painter.md +++ b/docs/quantum_painter.md @@ -32,16 +32,18 @@ Supported devices: ## Quantum Painter Configuration :id=quantum-painter-config -| Option | Default | Purpose | -|------------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------| -| `QUANTUM_PAINTER_NUM_IMAGES` | `8` | The maximum number of images/animations that can be loaded at any one time. | -| `QUANTUM_PAINTER_NUM_FONTS` | `4` | The maximum number of fonts that can be loaded at any one time. | -| `QUANTUM_PAINTER_CONCURRENT_ANIMATIONS` | `4` | The maximum number of animations that can be executed at the same time. | -| `QUANTUM_PAINTER_LOAD_FONTS_TO_RAM` | `FALSE` | Whether or not fonts should be loaded to RAM. Relevant for fonts stored in off-chip persistent storage, such as external flash. | -| `QUANTUM_PAINTER_PIXDATA_BUFFER_SIZE` | `32` | The limit of the amount of pixel data that can be transmitted in one transaction to the display. Higher values require more RAM on the MCU. | -| `QUANTUM_PAINTER_SUPPORTS_256_PALETTE` | `FALSE` | If 256-color palettes are supported. Requires significantly more RAM on the MCU. | -| `QUANTUM_PAINTER_SUPPORTS_NATIVE_COLORS` | `FALSE` | If native color range is supported. Requires significantly more RAM on the MCU. | -| `QUANTUM_PAINTER_DEBUG` | _unset_ | Prints out significant amounts of debugging information to CONSOLE output. Significant performance degradation, use only for debugging. | +| Option | Default | Purpose | +|------------------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `QUANTUM_PAINTER_DISPLAY_TIMEOUT` | `30000` | This controls the amount of time (in milliseconds) that all displays will remain on after the last user input. If set to `0`, the display will remain on indefinitely. | +| `QUANTUM_PAINTER_TASK_THROTTLE` | `1` | This controls the amount of time (in milliseconds) that the Quantum Painter internal task will wait between each execution. Affects animations, display timeout, and LVGL timing if enabled. | +| `QUANTUM_PAINTER_NUM_IMAGES` | `8` | The maximum number of images/animations that can be loaded at any one time. | +| `QUANTUM_PAINTER_NUM_FONTS` | `4` | The maximum number of fonts that can be loaded at any one time. | +| `QUANTUM_PAINTER_CONCURRENT_ANIMATIONS` | `4` | The maximum number of animations that can be executed at the same time. | +| `QUANTUM_PAINTER_LOAD_FONTS_TO_RAM` | `FALSE` | Whether or not fonts should be loaded to RAM. Relevant for fonts stored in off-chip persistent storage, such as external flash. | +| `QUANTUM_PAINTER_PIXDATA_BUFFER_SIZE` | `32` | The limit of the amount of pixel data that can be transmitted in one transaction to the display. Higher values require more RAM on the MCU. | +| `QUANTUM_PAINTER_SUPPORTS_256_PALETTE` | `FALSE` | If 256-color palettes are supported. Requires significantly more RAM on the MCU. | +| `QUANTUM_PAINTER_SUPPORTS_NATIVE_COLORS` | `FALSE` | If native color range is supported. Requires significantly more RAM on the MCU. | +| `QUANTUM_PAINTER_DEBUG` | _unset_ | Prints out significant amounts of debugging information to CONSOLE output. Significant performance degradation, use only for debugging. | Drivers have their own set of configurable options, and are described in their respective sections. diff --git a/docs/squeezing_avr.md b/docs/squeezing_avr.md index 62db7f2471..ce9e43cdae 100644 --- a/docs/squeezing_avr.md +++ b/docs/squeezing_avr.md @@ -194,6 +194,7 @@ That said, there are a number of Pro Micro replacements with ARM controllers: * [Blok](https://boardsource.xyz/store/628b95b494dfa308a6581622) * [Elite-Pi](https://keeb.io/products/elite-pi-usb-c-pro-micro-replacement-rp2040) * [0xCB Helios](https://keeb.supply/products/0xcb-helios) ([Open Source](https://github.com/0xCB-dev/0xCB-Helios), DIY/PCBA/Shop) +* [Liatris](https://splitkb.com/products/liatris) * [Michi](https://github.com/ci-bus/michi-promicro-rp2040) There are other, non-Pro Micro compatible boards out there. The most popular being: diff --git a/docs/tap_hold.md b/docs/tap_hold.md index 348e2655eb..cdc1cfeca7 100644 --- a/docs/tap_hold.md +++ b/docs/tap_hold.md @@ -130,20 +130,18 @@ Note that until the tap-or-hold decision completes (which happens when either th To better illustrate the tap-or-hold decision modes, let us compare the expected output of each decision mode in a handful of tapping scenarios involving a mod-tap key (`LSFT_T(KC_A)`) and a regular key (`KC_B`) with the `TAPPING_TERM` set to 200ms. -By default, mod-taps behave like `HOLD_ON_OTHER_KEY_PRESS`, while layer-taps behave like "Ignore Interrupt" out of the box. If you want "Ignore Interrupt"-like behaviour for mod-taps, you must enable `IGNORE_MOD_TAP_INTERRUPT`, or return `false` in the `get_hold_on_other_key_press` function for all mod-taps. - Note: "`kc` held" in the "Physical key event" column means that the key wasn't physically released yet at this point in time. #### Distinct taps (AABB) :id=distinct-taps -| Time | Physical key event |Ignore Interrupt| `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | +| Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | |------|--------------------|----------------|-------------------|----------------------------| | 0 | `LSFT_T(KC_A)` down| | | | | 199 | `LSFT_T(KC_A)` up | a | a | a | | 210 | `KC_B` down | ab | ab | ab | | 220 | `KC_B` up | ab | ab | ab | -| Time | Physical key event |Ignore Interrupt| `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | +| Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | |------|--------------------|----------------|-------------------|----------------------------| | 0 | `LSFT_T(KC_A)` down| | | | | 200 | `LSFT_T(KC_A)` held|<kbd>Shift</kbd>| <kbd>Shift</kbd> | <kbd>Shift</kbd> | @@ -153,14 +151,14 @@ Note: "`kc` held" in the "Physical key event" column means that the key wasn't p #### Nested tap (ABBA) :id=nested-tap -| Time | Physical key event |Ignore Interrupt| `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | +| Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | |------|--------------------|----------------|-------------------|----------------------------| | 0 | `LSFT_T(KC_A)` down| | | | | 110 | `KC_B` down | | | B | | 120 | `KC_B` up | | B | B | | 199 | `LSFT_T(KC_A)` up | ab | B | B | -| Time | Physical key event |Ignore Interrupt| `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | +| Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | |------|--------------------|----------------|-------------------|----------------------------| | 0 | `LSFT_T(KC_A)` down| | | | | 110 | `KC_B` down | | | B | @@ -168,7 +166,7 @@ Note: "`kc` held" in the "Physical key event" column means that the key wasn't p | 200 | `LSFT_T(KC_A)` held| B | B | B | | 210 | `LSFT_T(KC_A)` up | B | B | B | -| Time | Physical key event |Ignore Interrupt| `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | +| Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | |------|--------------------|----------------|-------------------|----------------------------| | 0 | `LSFT_T(KC_A)` down| | | | | 200 | `LSFT_T(KC_A)` held|<kbd>Shift</kbd>| <kbd>Shift</kbd> | <kbd>Shift</kbd> | @@ -178,14 +176,14 @@ Note: "`kc` held" in the "Physical key event" column means that the key wasn't p #### Rolling keys (ABAB) :id=rolling-keys -| Time | Physical key event |Ignore Interrupt| `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | +| Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | |------|--------------------|----------------|-------------------|----------------------------| | 0 | `LSFT_T(KC_A)` down| | | | | 110 | `KC_B` down | | | B | | 130 | `LSFT_T(KC_A)` up | ab | ab | B | | 140 | `KC_B` up | ab | ab | B | -| Time | Physical key event |Ignore Interrupt| `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | +| Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | |------|--------------------|----------------|-------------------|----------------------------| | 0 | `LSFT_T(KC_A)` down| | | | | 110 | `KC_B` down | | | B | @@ -241,10 +239,8 @@ Example sequence 3 (Mod Tap): | +--------------+ | | +---------------------------|--------+ ``` -Based on previous examples, you might have expected the output of the above sequence to be `KC_A` `KC_X` -since `SFT_T(KC_A)` is NOT held longer than the `TAPPING_TERM`. -However, the actual output would be capital `X` (`SHIFT` + `x`) due to reasons -explained under [Ignore Mod Tap Interrupt](#ignore-mod-tap-interrupt). +In the above sequence, `SFT_T(KC_A)` has been released before the end of its `TAPPING_TERM` and as such will be interpreted as `KC_A`, +followed by any key event that happened after the initial press of `SFT_T(KC_A)`. In this instance, the output would be `KC_A` `KC_X`. ### Permissive Hold @@ -379,73 +375,6 @@ bool get_hold_on_other_key_press(uint16_t keycode, keyrecord_t *record) { } ``` - -## Ignore Mod Tap Interrupt - -To enable this setting, add this to your `config.h`: - -```c -#define IGNORE_MOD_TAP_INTERRUPT -``` - -?> This option affects only the Mod Tap keys; it does not affect other dual-role keys such as Layer Tap. - -By default, the tap-or-hold decision for Mod Tap keys strongly prefers the hold action. If you press a Mod Tap key, then press another key while still holding the Mod Tap key down, the Mod Tap press will be handled as a modifier hold even if the Mod Tap key is then released within the tapping term, and irrespective of the order in which those keys are released. Using options such as `PERMISSIVE_HOLD` or `HOLD_ON_OTHER_KEY_PRESS` will not affect the functionality of Mod Tap keys in a major way (these options would still affect the delay until the common code for dual-role keys finishes its tap-or-hold decision, but then the special code for Mod Tap keys will override the result of that decision and choose the hold action if another key was pressed). In fact, by default, the tap-or-hold decision for Mod Tap keys is done in the same way as if the `HOLD_ON_OTHER_KEY_PRESS` option was enabled, but without the decreased delay provided by `HOLD_ON_OTHER_KEY_PRESS`. - -If the `IGNORE_MOD_TAP_INTERRUPT` option is enabled, Mod Tap keys are no longer treated as a special case, and their behavior will match the behavior of other dual-role keys such as Layer Tap. Then the behavior of Mod Tap keys can be further tuned using other options such as `PERMISSIVE_HOLD` or `HOLD_ON_OTHER_KEY_PRESS`. - -An example of a sequence that will be affected by the `IGNORE_MOD_TAP_INTERRUPT` option (assuming that options like `PERMISSIVE_HOLD` or `HOLD_ON_OTHER_KEY_PRESS` are not enabled): - -- `SFT_T(KC_A)` Down -- `KC_X` Down -- `SFT_T(KC_A)` Up -- `KC_X` Up - -``` - TAPPING_TERM - +---------------------------|--------+ - | +-------------+ | | - | | SFT_T(KC_A) | | | - | +-------------+ | | - | +--------------+ | | - | | KC_X | | | - | +--------------+ | | - +---------------------------|--------+ -``` - -Normally, this would send a capital `X` (`SHIFT`+`x`), even if the sequence is performed faster than the `TAPPING_TERM`. However, if the `IGNORE_MOD_TAP_INTERRUPT` option is enabled, the `SFT_T(KC_A)` key must be held longer than the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold will still output a capital `X` (`SHIFT`+`x`). - -However, if the `HOLD_ON_OTHER_KEY_PRESS` option is enabled in addition to `IGNORE_MOD_TAP_INTERRUPT`, the above sequence will again send a capital `X` (`SHIFT`+`x`) even if performed faster than the `TAPPING_TERM`. The difference from the default configuration is that by default the host will receive the key events only after the `SFT_T(KC_A)` key is released, but with the `HOLD_ON_OTHER_KEY_PRESS` option, the host will start receiving key events when the `KC_X` key is pressed. - -For more granular control of this feature, you can add the following to your `config.h`: - -```c -#define HOLD_ON_OTHER_KEY_PRESS_PER_KEY -``` - -?> This option affects *all* dual-role keys. - -You can then add the following function to your keymap: - -```c -bool get_hold_on_other_key_press(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case SFT_T(KC_SPC): - // Do not force the mod-tap key press to be handled as a modifier - // if any other key was pressed while the mod-tap key is held down. - return false; - default: - // Force the dual-role key press to be handled as a modifier if any - // other key was pressed while the mod-tap key is held down. - return true; - } -} -``` - -Note that you must return `false` in `get_hold_on_other_key_press` in order to apply `IGNORE_MOD_TAP_INTERRUPT` for a certain mod-tap key. - -?> `IGNORE_MOD_TAP_INTERRUPT[_PER_KEY]` is being progressively phased out to align the (default) behavior and configuration of mod-taps with the rest of dual-role keys. - ## Quick Tap Term When the user holds a key after tapping it, the tapping function is repeated by default, rather than activating the hold function. This allows keeping the ability to auto-repeat the tapping function of a dual-role key. `QUICK_TAP_TERM` enables fine tuning of that ability. If set to `0`, it will remove the auto-repeat ability and activate the hold function instead. diff --git a/docs/ws2812_driver.md b/docs/ws2812_driver.md index 5942da28d1..23a21de567 100644 --- a/docs/ws2812_driver.md +++ b/docs/ws2812_driver.md @@ -72,8 +72,8 @@ WS2812_DRIVER = i2c Configure the hardware via your config.h: ```c -#define WS2812_ADDRESS 0xb0 // default: 0xb0 -#define WS2812_TIMEOUT 100 // default: 100 +#define WS2812_I2C_ADDRESS 0xB0 // default: 0xB0 +#define WS2812_I2C_TIMEOUT 100 // default: 100 ``` ### SPI diff --git a/docs/zh-cn/_summary.md b/docs/zh-cn/_summary.md index 3baee6dc2e..b8c26ac275 100644 --- a/docs/zh-cn/_summary.md +++ b/docs/zh-cn/_summary.md @@ -42,7 +42,6 @@ * [键映射总览](zh-cn/keymap.md) * 开发环境 * [Docker指南](zh-cn/getting_started_docker.md) - * [Vagrant指南](zh-cn/getting_started_vagrant.md) * 刷写(Flashing) * [刷写](zh-cn/flashing.md) * [刷写ATmega32A (ps2avrgb)](zh-cn/flashing_bootloadhid.md) @@ -188,5 +187,5 @@ * [Midi辅助功能](zh-cn/internals/midi_util.md) * [发送函数](zh-cn/internals/send_functions.md) * [Sysex工具](zh-cn/internals/sysex_tools.md) - + <!--fromen:20211014-12:00(GMT+8) commit 04cf161aa01fd433b5dae69d9fd31569ed5dca59--> diff --git a/docs/zh-cn/getting_started_vagrant.md b/docs/zh-cn/getting_started_vagrant.md deleted file mode 100644 index 5e5de44552..0000000000 --- a/docs/zh-cn/getting_started_vagrant.md +++ /dev/null @@ -1,61 +0,0 @@ -# Vagrant快速上手指引 - -<!--- - original document: 0.15.12:docs/getting_started_vagrant.md - git diff 0.15.12 HEAD -- docs/getting_started_vagrant.md | cat ---> - -本工程包含一份 `Vagrantfile`，可以方便地在不更改你系统环境情况下完成新固件文件的构建工作。这同时也保证了在你拉取该工程代码后的编译环境与也使用Vagrantfile的其它人的一致。当你需要其他人协助你排查遇到的问题时会方便很多。 - -## 需求 - -本工程中的 `Vagrantfile` 需要安装[Vagrant](https://www.vagrantup.com/)以及可用的虚拟机服务： - -* [VirtualBox](https://www.virtualbox.org/) (5.0.12及以后版本) - * 卖点是'最适用于Vagrant的平台' -* [VMware Workstation](https://www.vmware.com/products/workstation) 及 [Vagrant VMware插件](https://www.vagrantup.com/vmware) - * （付费购买的）VMware插件需要在经过正版授权的VMware Workstation/Fusion上运行 -* [Docker](https://www.docker.com/) - -安装了Vagrant之后，在安装合适的虚拟机服务后可能需要重启机器。拉取本工程后在工程目录下执行 'vagrant up' 将启动一个包含了所有本工程所需工具的构建环境（虚拟机或是容器）。最后会有一个vagrant启动提示告知你一切正常就绪，否则你也可以参考一下下面的构建文档。 - -## 刷写固件 - -比较“简单”的方案是在你的宿主系统上借助以下工具刷写固件： - -* [QMK工具箱](https://github.com/qmk/qmk_toolbox) (推荐) -* [Teensy Loader](https://www.pjrc.com/teensy/loader.html) - -如果你希望通过命令行进行编程工作，可以在Vagrantfile中取消掉['modifyvm']的注释以允许USB直通到Linux环境，既可以使用dfu-util/dfu-programmer之类的命令行工具进行编程工作，或是安装Teensy的命令行版本。 - -## Vagrantfile概览 -开发环境被配置为运行QMK Docker镜像 `qmkfm/qmk_cli`，不仅让各系统下的功能预期一致，也是我们CI环境的镜像。 - -## FAQ - -### 为什么我的VirtualBox环境会有问题？ -VirtualBox 5的某些版本与工程中Vagrantfile中指定的VirtualBox扩展存在兼容问题。如果你遇到了/vagrant挂载不成功的问题，请升级VirtualBox至5.0.12或更高版本。**或者，可以尝试执行如下命令：** - -```console -vagrant plugin install vagrant-vbguest -``` - -### 如何移除一个现有环境？ -不再需要这个环境了是吗？在本工程目录下的任何位置，执行： - -```console -vagrant destroy -``` - -### 如果我是想直接用Docker呢？ -想在不使用虚拟机技术的情况下也能使用Vagrant工作流？Vagrangfile已配置为允许绕过运行虚拟机，直接运行容器。通过如下方式执行命令可以强制使用Docker来启动环境： -```console -vagrant up --provider=docker -``` - -### 如何访问虚拟机环境而非Docker容器？ -通过如下方法跳过 `vagrant` 的用户初始化过程以在QMK构建镜像中直接执行： - -```console -vagrant ssh -c 'sudo -i' -``` |