diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_summary.md | 5 | ||||
| -rw-r--r-- | docs/config_options.md | 17 | ||||
| -rw-r--r-- | docs/custom_quantum_functions.md | 94 | ||||
| -rw-r--r-- | docs/faq_build.md | 15 | ||||
| -rw-r--r-- | docs/feature_audio.md | 31 | ||||
| -rw-r--r-- | docs/feature_debounce_type.md | 5 | ||||
| -rw-r--r-- | docs/feature_grave_esc.md | 2 | ||||
| -rw-r--r-- | docs/feature_macros.md | 97 | ||||
| -rw-r--r-- | docs/feature_mouse_keys.md | 107 | ||||
| -rw-r--r-- | docs/feature_rgb_matrix.md | 276 | ||||
| -rw-r--r-- | docs/feature_rgblight.md | 58 | ||||
| -rw-r--r-- | docs/flashing.md | 21 | ||||
| -rw-r--r-- | docs/getting_started_build_tools.md | 2 | ||||
| -rw-r--r-- | docs/how_keyboards_work.md | 2 | ||||
| -rw-r--r-- | docs/i2c_driver.md | 2 | ||||
| -rw-r--r-- | docs/isp_flashing_guide.md | 5 | ||||
| -rw-r--r-- | docs/keymap.md | 56 | ||||
| -rw-r--r-- | docs/newbs_flashing.md | 69 | ||||
| -rw-r--r-- | docs/newbs_getting_started.md | 6 | ||||
| -rw-r--r-- | docs/other_eclipse.md (renamed from docs/eclipse.md) | 0 | ||||
| -rw-r--r-- | docs/other_vscode.md | 117 | ||||
| -rw-r--r-- | docs/understanding_qmk.md | 2 |
22 files changed, 672 insertions, 317 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 35936df00d..c9d6c2bb14 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -3,7 +3,7 @@ * [Building Your First Firmware](newbs_building_firmware.md) * [Flashing Firmware](newbs_flashing.md) * [Testing and Debugging](newbs_testing_debugging.md) - * [Best Practices](newbs_best_practices.md) + * [Git Best Practices](newbs_best_practices.md) * [Learning Resources](newbs_learn_more_resources.md) * [QMK Basics](README.md) @@ -92,7 +92,8 @@ * [Understanding QMK](understanding_qmk.md) * Other Topics - * [Using Eclipse with QMK](eclipse.md) + * [Using Eclipse with QMK](other_eclipse.md) + * [Using VSCode with QMK](other_vscode.md) * [Support](support.md) * QMK Internals (In Progress) diff --git a/docs/config_options.md b/docs/config_options.md index 336feee8fd..c5131a8414 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -126,6 +126,8 @@ If you define these options you will enable the associated feature, which may in * `#define TAPPING_TERM 200` * how long before a tap becomes a hold, if set above 500, a key tapped during the tapping term will turn it into a hold too +* `#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 * See [Retro Tapping](feature_advanced_keycodes.md#retro-tapping) for details @@ -171,11 +173,15 @@ If you define these options you will enable the associated feature, which may in ## RGB Light Configuration * `#define RGB_DI_PIN D7` - * pin the DI on the ws2812 is hooked-up to + * pin the DI on the WS2812 is hooked-up to * `#define RGBLIGHT_ANIMATIONS` * run RGB animations -* `#define RGBLED_NUM 15` +* `#define RGBLED_NUM 12` * number of LEDs +* `#define RGBLED_SPLIT { 6, 6 }` + * number of LEDs connected that are directly wired to `RGB_DI_PIN` on each half of a split keyboard + * First value indicates number of LEDs for left half, second value is for the right half + * Needed if both halves of the board have RGB LEDs wired directly to the RGB output pin on the controllers instead of passing the output of the left half to the input of the right half * `#define RGBLIGHT_HUE_STEP 12` * units to step when in/decreasing hue * `#define RGBLIGHT_SAT_STEP 25` @@ -208,9 +214,13 @@ There are a few different ways to set handedness for split keyboards (listed in 1. Set `SPLIT_HAND_PIN`: Reads a pin to determine handedness. If pin is high, it's the left side, if low, the half is determined to be the right side 2. Set `EE_HANDS` and flash `eeprom-lefthand.eep`/`eeprom-righthand.eep` to each half + * For boards with DFU bootloader you can use `:dfu-split-left`/`:dfu-split-right` to flash these EEPROM files + * For boards with Caterina bootloader (like stock Pro Micros), use `:avrdude-split-left`/`:avrdude-split-right` 3. Set `MASTER_RIGHT`: Half that is plugged into the USB port is determined to be the master and right half (inverse of the default) 4. Default: The side that is plugged into the USB port is the master half and is assumed to be the left half. The slave side is the right half +#### Defines for handedness + * `#define SPLIT_HAND_PIN B7` * For using high/low pin to determine handedness, low = right hand, high = left hand. Replace `B7` with the pin you are using. This is optional, and if you leave `SPLIT_HAND_PIN` undefined, then you can still use the EE_HANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses. @@ -232,6 +242,9 @@ There are a few different ways to set handedness for split keyboards (listed in * `#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. +* `#define RGBLED_SPLIT { 6, 6 }` + * See [RGB Light Configuration](#rgb-light-configuration) + * `#define SELECT_SOFT_SERIAL_SPEED <speed>` (default speed is 1) * Sets the protocol speed when using serial communication * Speeds: diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index f291fc2d21..6287b95309 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -116,29 +116,29 @@ Use the `IS_LED_ON(usb_led, led_name)` and `IS_LED_OFF(usb_led, led_name)` macro ```c void led_set_user(uint8_t usb_led) { if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) { - PORTB |= (1<<0); + writePinLow(B0); } else { - PORTB &= ~(1<<0); + writePinHigh(B0); } if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) { - PORTB |= (1<<1); + writePinLow(B1); } else { - PORTB &= ~(1<<1); + writePinHigh(B1); } if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) { - PORTB |= (1<<2); + writePinLow(B2); } else { - PORTB &= ~(1<<2); + writePinHigh(B2); } if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) { - PORTB |= (1<<3); + writePinLow(B3); } else { - PORTB &= ~(1<<3); + writePinHigh(B3); } if (IS_LED_ON(usb_led, USB_LED_KANA)) { - PORTB |= (1<<4); + writePinLow(B4); } else { - PORTB &= ~(1<<4); + writePinHigh(B4); } } ``` @@ -189,16 +189,18 @@ However, if you have hardware stuff that you need initialized, this is the best ### Example `keyboard_pre_init_user()` Implementation -This example, at the keyboard level, sets up B1, B2, and B3 as LED pins. +This example, at the keyboard level, sets up B0, B1, B2, B3, and B4 as LED pins. ```c void keyboard_pre_init_user(void) { // Call the keyboard pre init code. // Set our LED pins as output - DDRB |= (1<<1); - DDRB |= (1<<2); - DDRB |= (1<<3); + setPinOutput(B0); + setPinOutput(B1); + setPinOutput(B2); + setPinOutput(B3); + setPinOutput(B4); } ``` @@ -233,7 +235,7 @@ This example, running after everything else has initialized, sets up the rgb und void keyboard_post_init_user(void) { // Call the post init code. rgblight_enable_noeeprom(); // enables Rgb, without saving settings - rgblight_sethsv_noeeprom(180, 255, 255): // sets the color to teal/cyan without saving + rgblight_sethsv_noeeprom(180, 255, 255); // sets the color to teal/cyan without saving rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // sets mode to Fast breathing without saving } ``` @@ -270,16 +272,13 @@ This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_ ### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation -This example, at the keyboard level, sets up B1, B2, and B3 as LED pins. ```c -void suspend_power_down_user(void) -{ +void suspend_power_down_user(void) { rgb_matrix_set_suspend_state(true); } -void suspend_wakeup_init_user(void) -{ +void suspend_wakeup_init_user(void) { rgb_matrix_set_suspend_state(false); } ``` @@ -324,6 +323,7 @@ uint32_t layer_state_set_user(uint32_t state) { * Keyboard/Revision: `uint32_t layer_state_set_kb(uint32_t state)` * Keymap: `uint32_t layer_state_set_user(uint32_t state)` + The `state` is the bitmask of the active layers, as explained in the [Keymap Overview](keymap.md#keymap-layer-status) @@ -343,7 +343,7 @@ This is an example of how to add settings, and read and write it. We're using th In your keymap.c file, add this to the top: -``` +```c typedef union { uint32_t raw; struct { @@ -356,11 +356,11 @@ user_config_t user_config; This sets up a 32 bit structure that we can store settings with in memory, and write to the EEPROM. Using this removes the need to define variables, since they're defined in this structure. Remember that `bool` (boolean) values use 1 bit, `uint8_t` uses 8 bits, `uint16_t` uses up 16 bits. You can mix and match, but changing the order can cause issues, as it will change the values that are read and written. -We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `matrix_init_user` and `process_record_user` to configure everything. +We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `keyboard_post_init_user` and `process_record_user` to configure everything. -Now, using the `matrix_init_user` code above, you want to add `eeconfig_read_user()` to it, to populate the structure you've just created. And you can then immediately use this structure to control functionality in your keymap. And It should look like: -``` -void matrix_init_user(void) { +Now, using the `keyboard_post_init_user` code above, you want to add `eeconfig_read_user()` to it, to populate the structure you've just created. And you can then immediately use this structure to control functionality in your keymap. And It should look like: +```c +void keyboard_post_init_user(void) { // Call the keymap level matrix init. // Read the user config from EEPROM @@ -376,7 +376,7 @@ void matrix_init_user(void) { ``` The above function will use the EEPROM config immediately after reading it, to set the default layer's RGB color. The "raw" value of it is converted in a usable structure based on the "union" that you created above. -``` +```c uint32_t layer_state_set_user(uint32_t state) { switch (biton32(state)) { case _RAISE: @@ -398,8 +398,8 @@ uint32_t layer_state_set_user(uint32_t state) { return state; } ``` -This will cause the RGB underglow to be changed ONLY if the value was enabled. Now to configure this value, create a new keycode for `process_record_user` called `RGB_LYR` and `EPRM`. Additionally, we want to make sure that if you use the normal RGB codes, that it turns off Using the example above, make it look this: -``` +This will cause the RGB underglow to be changed ONLY if the value was enabled. Now to configure this value, create a new keycode for `process_record_user` called `RGB_LYR`. Additionally, we want to make sure that if you use the normal RGB codes, that it turns off Using the example above, make it look this: +```c bool process_record_user(uint16_t keycode, keyrecord_t *record) { switch (keycode) { @@ -416,11 +416,6 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { PLAY_NOTE_ARRAY(tone_qwerty); } return true; // Let QMK send the enter press/release events - case EPRM: - if (record->event.pressed) { - eeconfig_init(); // resets the EEPROM to default - } - return false; case RGB_LYR: // This allows me to use underglow as layer indication, or as normal if (record->event.pressed) { user_config.rgb_layer_change ^= 1; // Toggles the status @@ -443,10 +438,11 @@ 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. 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 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. -``` +```c void eeconfig_init_user(void) { // EEPROM is getting reset! + user_config.raw = 0; user_config.rgb_layer_change = true; // We want this enabled by default eeconfig_update_user(user_config.raw); // Write default value to EEPROM now @@ -465,3 +461,31 @@ And you're done. The RGB layer indication will only work if you want it to. And * Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)` The `val` is the value of the data that you want to write to EEPROM. And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM. + +# Custom Tapping Term + +By default, the tapping term is defined globally, and is not configurable by key. For most users, this is perfectly fine. But in come cases, dual function keys would be greatly improved by different timeouts than `LT` keys, or because some keys may be easier to hold than others. Instead of using custom key codes for each, this allows for per key configurable `TAPPING_TERM`. + +To enable this functionality, you need to add `#define TAPPING_TERM_PER_KEY` to your `config.h`, first. + + +## Example `get_tapping_term` Implementation + +To change the `TAPPING TERM` based on the keycode, you'd want to add something like the following to your `keymap.c` file: + +```c +uint16_t get_tapping_term(uint16_t keycode) { + switch (keycode) { + case SFT_T(KC_SPC): + return TAPPING_TERM + 1250; + case LT(1, KC_GRV): + return 130; + default: + return TAPPING_TERM; + } +} +``` + +### `get_tapping_term` Function Documentation + +Unlike many of the other functions here, there isn't a need (or even reason) to have a quantum or keyboard level function. Only a user level function is useful here, so no need to mark it as such. diff --git a/docs/faq_build.md b/docs/faq_build.md index be26a7c581..0c1bedd715 100644 --- a/docs/faq_build.md +++ b/docs/faq_build.md @@ -15,7 +15,7 @@ or just: $ sudo make <keyboard>:<keymap>:dfu -Note that running `make` with `sudo` is generally *not* a good idea, and you should use one of the former methods, if possible. +Note that running `make` with `sudo` is generally ***not*** a good idea, and you should use one of the former methods, if possible. ### Linux `udev` Rules On Linux, you'll need proper privileges to access the MCU. You can either use @@ -36,6 +36,12 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="066 # tmk keyboard products https://github.com/tmk/tmk_keyboard SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" ``` +**/etc/udev/rules.d/54-input-club-keyboard.rules:** + +``` +# Input Club keyboard bootloader +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666" +``` ### Serial device is not detected in bootloader mode on Linux Make sure your kernel has appropriate support for your device. If your device uses USB ACM, such as @@ -47,7 +53,12 @@ If you're using Windows to flash your keyboard, and you are running into issues, Re-running the installation script for MSYS2 may help (eg run `./util/qmk_install.sh` from MSYS2/WSL) or reinstalling the QMK Toolbox may fix the issue. -If that doesn't work, then you may need to grab the [Zadig Utility](https://zadig.akeo.ie/). Download this, find the device in question, and select the `WinUS(libusb-1.0)` option, and hit "Reinstall driver". Once you've done that, try flashing your board, again. +If that doesn't work, then you may need to grab the [Zadig Utility](https://zadig.akeo.ie/). Download this, find the device in question, and select the `WinUSB` option, and hit "Reinstall driver". Once you've done that, try flashing your board, again. If that doesn't work, try all of the options, until one works. + +?> There isn't a best option for which driver should be used here. Some options work better on some systems than others. libUSB and WinUSB seem to be the best options here. + +If the bootloader doesn't show up in the list for devices, you may need to enable the "List all devices" option in the `Options` menu, and then find the bootloader in question. + ## WINAVR is Obsolete It is no longer recommended and may cause some problem. diff --git a/docs/feature_audio.md b/docs/feature_audio.md index 38861e8c14..e1dd4c5a85 100644 --- a/docs/feature_audio.md +++ b/docs/feature_audio.md @@ -100,6 +100,16 @@ In music mode, the following keycodes work differently, and don't pass through: * `KC_UP` - speed-up playback * `KC_DOWN` - slow-down playback +The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`: + + #define PITCH_STANDARD_A 432.0f + +You can completely disable Music Mode as well. This is useful, if you're pressed for space on your controller. To disable it, add this to your `config.h`: + + #define NO_MUSIC_MODE + +### Music Mask + By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less than `0xFF` are turned into notes, and don't output anything. You can change this by defining this in your `config.h` like this: #define MUSIC_MASK keycode != KC_NO @@ -120,13 +130,26 @@ For a more advanced way to control which keycodes should still be processed, you Things that return false are not part of the mask, and are always processed. -The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`: +### Music Map - #define PITCH_STANDARD_A 432.0f +By default, the Music Mode uses the columns and row to determine the scale for the keys. For a board that uses a rectangular matrix that matches the keyboard layout, this is just fine. However, for boards that use a more complicated matrix (such as the Planck Rev6, or many split keyboards) this would result in a very skewed experience. -You can completely disable Music Mode as well. This is useful, if you're pressed for space on your controller. To disable it, add this to your `config.h`: +However, the Music Map option allows you to remap the scaling for the music mode, so it fits the layout, and is more natural. - #define NO_MUSIC_MODE +To enable this feature, add `#define MUSIC_MAP` to your `config.h` file, and then you will want to add a `uint8_t music_map` to your keyboard's `c` file, or your `keymap.c`. + +```c +const uint8_t music_map[MATRIX_ROWS][MATRIX_COLS] = LAYOUT_ortho_4x12( + 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, + 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, + 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 +); +``` + +You will want to use whichever `LAYOUT` macro that your keyboard uses here. This maps it to the correct key location. Start in the bottom left of the keyboard layout, and move to the right, and then upwards. Fill in all the entries until you have a complete matrix. + +You can look at the [Planck Keyboard](https://github.com/qmk/qmk_firmware/blob/e9ace1487887c1f8b4a7e8e6d87c322988bec9ce/keyboards/planck/planck.c#L24-L29) as an example of how to implement this. ## Audio Click diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md index 5d4343f08b..38eca3f37c 100644 --- a/docs/feature_debounce_type.md +++ b/docs/feature_debounce_type.md @@ -33,7 +33,10 @@ The debounce code is compatible with split keyboards. # Changing between included debouncing methods You can either use your own code, by including your own debounce.c, or switch to another included one. Included debounce methods are: -* eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE_DELAY``` millseconds of no further input for that key +* eager_pr - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE_DELAY``` milliseconds of no further input for that row. +For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be +appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use. +* eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE_DELAY``` milliseconds of no further input for that key * sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE_DELAY``` milliseconds of no changes has occured, all input changes are pushed. diff --git a/docs/feature_grave_esc.md b/docs/feature_grave_esc.md index a7261d2dc8..f57c6042ca 100644 --- a/docs/feature_grave_esc.md +++ b/docs/feature_grave_esc.md @@ -18,7 +18,7 @@ If Mary presses GESC on her keyboard, the OS will see an KC_ESC character. Now i ### Caveats - * On macOS CMD/GUI + KC_GRV is actually mapped to a hot key so it will not output a backtick. +On macOS, Command+<code>`</code> is by default mapped to "Move focus to next window" so it will not output a backtick. Additionally, Terminal always recognises this shortcut to cycle between windows, even if the shortcut is changed in the Keyboard preferences. ## Configuration diff --git a/docs/feature_macros.md b/docs/feature_macros.md index 79419abd20..743fc3ad55 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -146,9 +146,59 @@ send_string(my_str); SEND_STRING(".."SS_TAP(X_END)); ``` -## The Old Way: `MACRO()` & `action_get_macro` -?> This is inherited from TMK, and hasn't been updated - it's recommend that you use `SEND_STRING` and `process_record_user` instead. +## Advanced Macro Functions + +There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro, if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple. + +### `record->event.pressed` + +This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is + +```c + if (record->event.pressed) { + // on keydown + } else { + // on keyup + } +``` + +### `register_code(<kc>);` + +This sends the `<kc>` keydown event to the computer. Some examples would be `KC_ESC`, `KC_C`, `KC_4`, and even modifiers such as `KC_LSFT` and `KC_LGUI`. + +### `unregister_code(<kc>);` + +Parallel to `register_code` function, this sends the `<kc>` keyup event to the computer. If you don't use this, the key will be held down until it's sent. + +### `tap_code(<kc>);` + +This will send `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it). + +If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds. + +### `register_code16(<kc>);`, `unregister_code16(<kc>);` and `tap_code16(<kc>);` + +These functions work similar to their regular counterparts, but allow you to use modded keycodes (with Shift, Alt, Control, and/or GUI applied to them). + +Eg, you could use `register_code16(S(KC_5));` instead of registering the mod, then registering the keycode. + +### `clear_keyboard();` + +This will clear all mods and keys currently pressed. + +### `clear_mods();` + +This will clear all mods currently pressed. + +### `clear_keyboard_but_mods();` + +This will clear all keys besides the mods currently pressed. + + +## **(DEPRECATED)** The Old Way: `MACRO()` & `action_get_macro` + +!> This is inherited from TMK, and hasn't been updated - it's recommended that you use `SEND_STRING` and `process_record_user` instead. By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example: @@ -222,49 +272,8 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { }; ``` -## Advanced Macro Functions - -There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple. - -### `record->event.pressed` - -This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is - -```c - if (record->event.pressed) { - // on keydown - } else { - // on keyup - } -``` - -### `register_code(<kc>);` - -This sends the `<kc>` keydown event to the computer. Some examples would be `KC_ESC`, `KC_C`, `KC_4`, and even modifiers such as `KC_LSFT` and `KC_LGUI`. - -### `unregister_code(<kc>);` - -Parallel to `register_code` function, this sends the `<kc>` keyup event to the computer. If you don't use this, the key will be held down until it's sent. - -### `tap_code(<kc>);` - -This will send `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it). - -If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds. - -### `clear_keyboard();` - -This will clear all mods and keys currently pressed. - -### `clear_mods();` - -This will clear all mods currently pressed. - -### `clear_keyboard_but_mods();` - -This will clear all keys besides the mods currently pressed. -## Advanced Example: Single-Key Copy/Paste +### Advanced Example: Single-Key Copy/Paste This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released. diff --git a/docs/feature_mouse_keys.md b/docs/feature_mouse_keys.md index 673eafaef5..e64ddf3d06 100644 --- a/docs/feature_mouse_keys.md +++ b/docs/feature_mouse_keys.md @@ -1,48 +1,48 @@ # Mousekeys -Mousekeys is a feature that allows you to emulate a mouse using your keyboard. You can move the pointer around, click up to 5 buttons, and even scroll in all 4 directions. QMK uses the same algorithm as the X Window System MouseKeysAccel feature. You can read more about it [on Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys). +Mousekeys is a feature that allows you to emulate a mouse using your keyboard. You can move the pointer around, click up to 5 buttons, and even scroll in all 4 directions. -## Adding Mousekeys to a Keymap +There are 2 ways to define how the mousekeys behave, using "[auto-accelerating](#configuring-the-behavior-of-mousekeys-with-auto-accelerated-movement)" or "[3-speed constant](#configuring-the-behavior-of-mousekeys-with-3-speed-constant-movement)" behavior. -There are two steps to adding Mousekeys support to your keyboard. You must enable support in the `rules.mk` file and you must map mouse actions to keys on your keyboard. +In either case, you will need to enable mousekeys in your makefile, +and add the relevant [keycodes](#mapping-mouse-actions-to-keyboard-keys) to your keymap. -### Adding Mousekeys Support in the `rules.mk` +#### Enable Mousekeys -To add support for Mousekeys you simply need to add a single line to your keymap's `rules.mk`: +To enable the mousekey functionality, add the following line to your keymap's `rules.mk`: ``` MOUSEKEY_ENABLE = yes ``` -You can see an example here: https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/66/keymaps/mouse_keys/rules.mk - -### Mapping Mouse Actions to Keyboard Keys +#### Mapping Mouse Actions to Keyboard Keys You can use these keycodes within your keymap to map button presses to mouse actions: -|Key |Aliases |Description | -|----------------|---------|---------------------------| -|`KC_MS_UP` |`KC_MS_U`|Mouse Cursor Up | -|`KC_MS_DOWN` |`KC_MS_D`|Mouse Cursor Down | -|`KC_MS_LEFT` |`KC_MS_L`|Mouse Cursor Left | -|`KC_MS_RIGHT` |`KC_MS_R`|Mouse Cursor Right | -|`KC_MS_BTN1` |`KC_BTN1`|Mouse Button 1 | -|`KC_MS_BTN2` |`KC_BTN2`|Mouse Button 2 | -|`KC_MS_BTN3` |`KC_BTN3`|Mouse Button 3 | -|`KC_MS_BTN4` |`KC_BTN4`|Mouse Button 4 | -|`KC_MS_BTN5` |`KC_BTN5`|Mouse Button 5 | -|`KC_MS_WH_UP` |`KC_WH_U`|Mouse Wheel Up | -|`KC_MS_WH_DOWN` |`KC_WH_D`|Mouse Wheel Down | -|`KC_MS_WH_LEFT` |`KC_WH_L`|Mouse Wheel Left | -|`KC_MS_WH_RIGHT`|`KC_WH_R`|Mouse Wheel Right | -|`KC_MS_ACCEL0` |`KC_ACL0`|Set mouse acceleration to 0| -|`KC_MS_ACCEL1` |`KC_ACL1`|Set mouse acceleration to 1| -|`KC_MS_ACCEL2` |`KC_ACL2`|Set mouse acceleration to 2| - -You can see an example in the `_ML` here: https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/66/keymaps/mouse_keys/keymap.c#L46 - -## Configuring the Behavior of Mousekeys +|Key |Aliases |Description | +|----------------|---------|-----------------------------------| +|`KC_MS_UP` |`KC_MS_U`|Mouse Cursor Up | +|`KC_MS_DOWN` |`KC_MS_D`|Mouse Cursor Down | +|`KC_MS_LEFT` |`KC_MS_L`|Mouse Cursor Left | +|`KC_MS_RIGHT` |`KC_MS_R`|Mouse Cursor Right | +|`KC_MS_BTN1` |`KC_BTN1`|Mouse Button 1 | +|`KC_MS_BTN2` |`KC_BTN2`|Mouse Button 2 | +|`KC_MS_BTN3` |`KC_BTN3`|Mouse Button 3 | +|`KC_MS_BTN4` |`KC_BTN4`|Mouse Button 4 | +|`KC_MS_BTN5` |`KC_BTN5`|Mouse Button 5 | +|`KC_MS_WH_UP` |`KC_WH_U`|Mouse Wheel Up | +|`KC_MS_WH_DOWN` |`KC_WH_D`|Mouse Wheel Down | +|`KC_MS_WH_LEFT` |`KC_WH_L`|Mouse Wheel Left | +|`KC_MS_WH_RIGHT`|`KC_WH_R`|Mouse Wheel Right | +|`KC_MS_ACCEL0` |`KC_ACL0`|Set mouse acceleration to 0(slow) | +|`KC_MS_ACCEL1` |`KC_ACL1`|Set mouse acceleration to 1(medium)| +|`KC_MS_ACCEL2` |`KC_ACL2`|Set mouse acceleration to 2(fast) | + + +## Configuring the Behavior of Mousekeys with auto-accelerated movement + +This behavior is intended to emulate the X Window System MouseKeysAccel feature. You can read more about it [on Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys). The default speed for controlling the mouse with the keyboard is intentionally slow. You can adjust these parameters by adding these settings to your keymap's `config.h` file. All times are specified in milliseconds (ms). @@ -55,27 +55,60 @@ The default speed for controlling the mouse with the keyboard is intentionally s #define MOUSEKEY_WHEEL_TIME_TO_MAX 40 ``` - -### `MOUSEKEY_DELAY` +#### `MOUSEKEY_DELAY` When one of the mouse movement buttons is pressed this setting is used to define the delay between that button press and the mouse cursor moving. Some people find that small movements are impossible if this setting is too low, while settings that are too high feel sluggish. -### `MOUSEKEY_INTERVAL` +#### `MOUSEKEY_INTERVAL` When a movement key is held down this specifies how long to wait between each movement report. Lower settings will translate into an effectively higher mouse speed. -### `MOUSEKEY_MAX_SPEED` +#### `MOUSEKEY_MAX_SPEED` As a movement key is held down the speed of the mouse cursor will increase until it reaches `MOUSEKEY_MAX_SPEED`. -### `MOUSEKEY_TIME_TO_MAX` +#### `MOUSEKEY_TIME_TO_MAX` How long you want to hold down a movement key for until `MOUSEKEY_MAX_SPEED` is reached. This controls how quickly your cursor will accelerate. -### `MOUSEKEY_WHEEL_MAX_SPEED` +#### `MOUSEKEY_WHEEL_MAX_SPEED` The top speed for scrolling movements. -### `MOUSEKEY_WHEEL_TIME_TO_MAX` +#### `MOUSEKEY_WHEEL_TIME_TO_MAX` How long you want to hold down a scroll key for until `MOUSEKEY_WHEEL_MAX_SPEED` is reached. This controls how quickly your scrolling will accelerate. + + +## Configuring the Behavior of Mousekeys with 3-speed constant movement + +In your keymap's `config.h`, you must add the line: +``` +#define MK_3_SPEED +``` +Then you can precisely define 3 different speeds for both the cursor and the mouse wheel, and also whether speed selection is momentary or tap-to-select. +For each speed, you can specify how many milliseconds you want between reports(interval), and how far you want to it to move per report(offset). + +For example: + +``` +#define MK_3_SPEED +#define MK_MOMENTARY_ACCEL // comment this out for tap-to-select acceleration +// cursor speeds: +#define MK_C_OFFSET_SLOW 1 // pixels +#define MK_C_INTERVAL_SLOW 100 // milliseconds +#define MK_C_OFFSET_MED 4 +#define MK_C_INTERVAL_MED 16 +#define MK_C_OFFSET_FAST 12 +#define MK_C_INTERVAL_FAST 16 +// scroll wheel speeds: +#define MK_W_OFFSET_SLOW 1 // wheel clicks +#define MK_W_INTERVAL_SLOW 400 // milliseconds +#define MK_W_OFFSET_MED 1 +#define MK_W_INTERVAL_MED 200 +#define MK_W_OFFSET_FAST 1 +#define MK_W_INTERVAL_FAST 100 +``` + +Medium values will be used as the default or unmodified speed. +The speed at which both the cursor and scrolling move can be selected with KC_ACL0, KC_ACL1, KC_ACL2 for slow, medium, and fast. However, if you leave MK_MOMENTARY_ACCEL defined then there is no need to ever send KC_ACL1, since that will be the unmodified speed. diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 910a704691..ec12189545 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -10,39 +10,45 @@ If you want to use single color LED's you should use the [LED Matrix Subsystem]( There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`: - RGB_MATRIX_ENABLE = IS31FL3731 +```C +RGB_MATRIX_ENABLE = IS31FL3731 +``` Configure the hardware via your `config.h`: |