diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/CNAME | 1 | ||||
| -rw-r--r-- | docs/README.md | 4 | ||||
| -rw-r--r-- | docs/_sidebar.md | 1 | ||||
| -rw-r--r-- | docs/contributing.md | 6 | ||||
| -rw-r--r-- | docs/custom_quantum_functions.md | 35 | ||||
| -rw-r--r-- | docs/feature_leader_key.md | 18 | ||||
| -rw-r--r-- | docs/feature_rgblight.md | 36 | ||||
| -rw-r--r-- | docs/feature_tap_dance.md | 10 | ||||
| -rw-r--r-- | docs/features.md | 2 | ||||
| -rw-r--r-- | docs/getting_started_build_tools.md | 2 | ||||
| -rw-r--r-- | docs/hardware_keyboard_guidelines.md | 10 | ||||
| -rw-r--r-- | docs/keycodes.md | 17 | ||||
| -rw-r--r-- | docs/newbs_getting_started.md | 14 |
13 files changed, 119 insertions, 37 deletions
diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 000000000..e089843e0 --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +docs.qmk.fm
\ No newline at end of file diff --git a/docs/README.md b/docs/README.md index a4db81eb6..22ab243cd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,7 +19,7 @@ Otherwise, you can either download it directly ([zip](https://github.com/qmk/qmk ## How to Compile -Before you are able to compile, you'll need to [install an environment](01_Getting_Started/01_Install_Build_Tools.md) for AVR or/and ARM development. Once that is complete, you'll use the `make` command to build a keyboard and keymap with the following notation: +Before you are able to compile, you'll need to [install an environment](getting_started_build_tools.md) for AVR or/and ARM development. Once that is complete, you'll use the `make` command to build a keyboard and keymap with the following notation: make planck/rev4:default @@ -29,4 +29,4 @@ This would build the `rev4` revision of the `planck` with the `default` keymap. ## How to Customize -QMK has lots of [features](05_Features/index.md) to explore, and a good deal of [reference documentation](http://docs.qmk.fm) to dig through. Most features are taken advantage of by modifying your [keymap](07_Reference/Keymap_Overview.md), and changing the [keycodes](06_Keycodes/index.md). +QMK has lots of [features](features.md) to explore, and a good deal of [reference documentation](http://docs.qmk.fm) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md). diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 00aeb8057..31a22315d 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -43,6 +43,7 @@ * [Pointing Device](feature_pointing_device.md) * [PS/2 Mouse](feature_ps2_mouse.md) * [RGB Lighting](feature_rgblight.md) + * [RGB Matrix](feature_rgb_matrix.md) * [Space Cadet Shift](feature_space_cadet.md) * [Space Cadet Shift Enter](feature_space_shift_cadet.md) * [Stenography](feature_stenography.md) diff --git a/docs/contributing.md b/docs/contributing.md index 0e8066f00..17a9aa985 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -101,7 +101,7 @@ You'll find all our documentation in the `qmk_firmware/docs` directory, or if yo Most first-time QMK contributors start with their personal keymaps. We try to keep keymap standards pretty casual (keymaps, after all, reflect the personality of their creators) but we do ask that you follow these guidelines to make it easier for others to discover and learn from your keymap. -* Write a `readme.md` using [the template](https://docs.qmk.fm/documentation_templates.html#). +* Write a `readme.md` using [the template](documentation_templates.md). * All Keymap PR's are squashed, so if you care about how your commits are squashed you should do it yourself * Do not lump features in with keymap PR's. Submit the feature first and then a second PR for the keymap. * Do not include `Makefile`s in your keymap folder (they're no longer used) @@ -113,7 +113,7 @@ Keyboards are the raison d'être for QMK. Some keyboards are community maintaine We also ask that you follow these guidelines: -* Write a `readme.md` using [the template](https://docs.qmk.fm/documentation_templates.html#). +* Write a `readme.md` using [the template](documentation_templates.md). * Keep the number of commits reasonable or we will squash your PR * Do not lump core features in with new keyboards. Submit the feature first and then submit a separate PR for the keyboard. * Name `.c`/`.h` file after the immediate parent folder, eg `/keyboards/<kb1>/<kb2>/<kb2>.[ch]` @@ -140,7 +140,7 @@ We also ask that you follow these guidelines: * Keep the number of commits reasonable or we will squash your PR * Do not lump keyboards or keymaps in with core changes. Submit your core changes first. -* Write [Unit Tests](http://docs.qmk.fm/unit_testing.html) for your feature +* Write [Unit Tests](unit_testing.md) for your feature * Follow the style of the file you are editing. If the style is unclear or there are mixed styles you should conform to the [coding conventions](#coding-conventions) above. ## Refactoring diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 6d741b6cb..9a1c486df 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -135,9 +135,11 @@ void led_set_user(uint8_t usb_led) { * Keyboard/Revision: `void led_set_kb(uint8_t usb_led)` * Keymap: `void led_set_user(uint8_t usb_led)` + # Matrix Initialization Code -Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i²c controllers you will need to set up that hardware before it can be used. +Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i²c controllers you will need to set up that hardware before it can be used. + ### Example `matrix_init_user()` Implementation @@ -177,9 +179,38 @@ This function gets called at every matrix scan, which is basically as often as t You should use this function if you need custom matrix scanning code. It can also be used for custom status output (such as LED's or a display) or other functionality that you want to trigger regularly even when the user isn't typing. +# Keyboard Idling/Wake Code + +If the board supports it, it can be "idled", by stopping a number of functions. A good example of this is RGB lights or backlights. This can save on power consumption, or may be better behavior for your keyboard. + +This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_init_*`, which are called when the system is board is idled and when it wakes up, respectively. + + +### 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. + +``` +void suspend_power_down_user(void) +{ + rgb_matrix_set_suspend_state(true); +} + +void suspend_wakeup_init_user(void) +{ + rgb_matrix_set_suspend_state(false); +} + +``` + +### `keyboard_init_*` Function Documentation + +* Keyboard/Revision: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)` +* Keymap: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)` + # Layer Change Code -Thir runs code every time that the layers get changed. This can be useful for layer indication, or custom layer handling. +This runs code every time that the layers get changed. This can be useful for layer indication, or custom layer handling. ### Example `layer_state_set_*` Implementation diff --git a/docs/feature_leader_key.md b/docs/feature_leader_key.md index fb74bf7c8..46633b287 100644 --- a/docs/feature_leader_key.md +++ b/docs/feature_leader_key.md @@ -17,14 +17,16 @@ void matrix_scan_user(void) { leader_end(); SEQ_ONE_KEY(KC_F) { - register_code(KC_S); - unregister_code(KC_S); + // Anything you can do in a macro. + SEND_STRING("QMK is awesome."); } - SEQ_TWO_KEYS(KC_A, KC_S) { - register_code(KC_H); - unregister_code(KC_H); + SEQ_TWO_KEYS(KC_D, KC_D) { + SEND_STRING(SS_LCTRL("a")SS_LCTRL("c")); } - SEQ_THREE_KEYS(KC_A, KC_S, KC_D) { + SEQ_THREE_KEYS(KC_D, KC_D, KC_S) { + SEND_STRING("https://start.duckduckgo.com"SS_TAP(X_ENTER)); + } + SEQ_TWO_KEYS(KC_A, KC_S) { register_code(KC_LGUI); register_code(KC_S); unregister_code(KC_S); @@ -34,4 +36,6 @@ void matrix_scan_user(void) { } ``` -As you can see, you have three function. you can use - `SEQ_ONE_KEY` for single-key sequences (Leader followed by just one key), and `SEQ_TWO_KEYS` and `SEQ_THREE_KEYS` for longer sequences. Each of these accepts one or more keycodes as arguments. This is an important point: You can use keycodes from **any layer on your keyboard**. That layer would need to be active for the leader macro to fire, obviously. +As you can see, you have a few function. You can use `SEQ_ONE_KEY` for single-key sequences (Leader followed by just one key), and `SEQ_TWO_KEYS`, `SEQ_THREE_KEYS` up to `SEQ_FIVE_KEYS` for longer sequences. + +Each of these accepts one or more keycodes as arguments. This is an important point: You can use keycodes from **any layer on your keyboard**. That layer would need to be active for the leader macro to fire, obviously. diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 0f1e649ef..e0918d11b 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -88,11 +88,36 @@ const uint16_t RGBLED_GRADIENT_RANGES[] PROGMEM = {360, 240, 180, 120, 90}; Look in `rgblights.h` for all available functions, but if you want to control all or some LEDs your goto functions are: ```c -rgblight_disable(); // turn all lights off -rgblight_enable(); // turn lights on, based on their previous state (stored in EEPROM) +// turn all lights off (stored in EEPROM) +rgblight_disable(); +// turn lights on, based on their previous state (stored in EEPROM) +rgblight_enable(); + +// turn all lights off (not stored in EEPROM) +rgblight_disable_noeeprom(); +// turn lights on, based on their previous state (not stored in EEPROM) +rgblight_enable_noeeprom(); + +// where r/g/b is a number from 0..255. Turns all the LEDs to this color (ignores mode, not stored in EEPROM). +rgblight_setrgb(r, g, b); +// HSV color control - h is a value from 0..360 and s/v is a value from 0..255 (stored in EEPROM) +rgblight_sethsv(h, s, v); +// HSV color control - h is a value from 0..360 and s/v is a value from 0..255 (not stored in EEPROM) +rgblight_sethsv_noeeprom(h, s, v); + +// Sets the mode, if rgb animations are enabled (stored in eeprom) +rgblight_mode(x); +// Sets the mode, if rgb animations are enabled (not stored in eeprom) +rgblight_mode_noeeprom(x); +// MODE 1, solid color +// MODE 2-5, breathing +// MODE 6-8, rainbow mood +// MODE 9-14, rainbow swirl +// MODE 15-20, snake +// MODE 21-23, knight +// MODE 24, xmas +// MODE 25-34, static rainbow -rgblight_setrgb(r, g, b); // where r/g/b is a number from 0..255. Turns all the LEDs to this color -rgblight_sethsv(h, s, v); // HSV color control - h is a value from 0..360 and s/v is a value from 0..255 rgblight_setrgb_at(r,g,b, LED); // control a single LED. 0 <= LED < RGBLED_NUM rgblight_sethsv_at(h,s,v, LED); // control a single LED. 0 <= LED < RGBLED_NUM ``` @@ -121,12 +146,13 @@ These control the RGB Lighting functionality. |`RGB_MODE_KNIGHT` |`RGB_M_K` |"Knight Rider" animation mode | |`RGB_MODE_XMAS` |`RGB_M_X` |Christmas animation mode | |`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode | +|`RGB_MODE_RGBTEST `|`RGB_M_T` |Red,Green,Blue test animation mode | note: for backwards compatibility, `RGB_SMOD` is an alias for `RGB_MOD`. ## Hardware Modification - + Here is a quick demo on Youtube (with NPKC KC60) (https://www.youtube.com/watch?v=VKrpPAHlisY). diff --git a/docs/feature_tap_dance.md b/docs/feature_tap_dance.md index 4b05bd51b..99298fbda 100644 --- a/docs/feature_tap_dance.md +++ b/docs/feature_tap_dance.md @@ -6,9 +6,9 @@ Hit the semicolon key once, send a semicolon. Hit it twice, rapidly -- send a co With this feature one can specify keys that behave differently, based on the amount of times they have been tapped, and when interrupted, they get handled before the interrupter. -To make it clear how this is different from `ACTION_FUNCTION_TAP`, lets explore a certain setup! We want one key to send `Space` on single tap, but `Enter` on double-tap. +To make it clear how this is different from `ACTION_FUNCTION_TAP`, let's explore a certain setup! We want one key to send `Space` on single tap, but `Enter` on double-tap. -With `ACTION_FUNCTION_TAP`, it is quite a rain-dance to set this up, and has the problem that when the sequence is interrupted, the interrupting key will be send first. Thus, `SPC a` will result in `a SPC` being sent, if they are typed within `TAPPING_TERM`. With the tap dance feature, that'll come out as `SPC a`, correctly. +With `ACTION_FUNCTION_TAP`, it is quite a rain-dance to set this up, and has the problem that when the sequence is interrupted, the interrupting key will be sent first. Thus, `SPC a` will result in `a SPC` being sent, if they are typed within `TAPPING_TERM`. With the tap dance feature, that'll come out as `SPC a`, correctly. The implementation hooks into two parts of the system, to achieve this: into `process_record_quantum()`, and the matrix scan. We need the latter to be able to time out a tap sequence even when a key is not being pressed, so `SPC` alone will time out and register after `TAPPING_TERM` time. @@ -16,13 +16,13 @@ But lets start with how to use it, first! First, you will need `TAP_DANCE_ENABLE=yes` in your `rules.mk`, because the feature is disabled by default. This adds a little less than 1k to the firmware size. Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro, that - similar to `F()`, takes a number, which will later be used as an index into the `tap_dance_actions` array. -This array specifies what actions shall be taken when a tap-dance key is in action. Currently, there are three possible options: +This array specifies what actions shall be taken when a tap-dance key is in action. Currently, there are five possible options: * `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: Sends the `kc1` keycode when tapped once, `kc2` otherwise. When the key is held, the appropriate keycode is registered: `kc1` when pressed and held, `kc2` when tapped once, then pressed and held. * `ACTION_TAP_DANCE_DUAL_ROLE(kc, layer)`: Sends the `kc` keycode when tapped once, or moves to `layer`. (this functions like the `TO` layer keycode). * `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action. -* `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function on when the dance action finishes (like the previous option), and the last function when the tap dance action resets. -** `ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`: This functions identically to the `ACTION_TAP_DANCE_FN_ADVANCED` function, but uses a custom tapping term for it, instead of the predefined `TAPPING_TERM`. +* `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function when the dance action finishes (like the previous option), and the last function when the tap dance action resets. +* `ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`: This functions identically to the `ACTION_TAP_DANCE_FN_ADVANCED` function, but uses a custom tapping term for it, instead of the predefined `TAPPING_TERM`. The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise. diff --git a/docs/features.md b/docs/features.md index 5abede2c2..4dee486ef 100644 --- a/docs/features.md +++ b/docs/features.md @@ -17,8 +17,10 @@ QMK has a staggering number of features for building your keyboard. It can take * [Pointing Device](feature_pointing_device.md) - Framework for connecting your custom pointing device to your keyboard. * [PS2 Mouse](feature_ps2_mouse.md) - Driver for connecting a PS/2 mouse directly to your keyboard. * [RGB Light](feature_rgblight.md) - RGB lighting for your keyboard. +* [RGB Matrix](feature_rgb_matrix.md) - RGB Matrix lights for per key lighting. * [Space Cadet](feature_space_cadet.md) - Use your left/right shift keys to type parenthesis and brackets. * [Stenography](feature_stenography.md) - Put your keyboard into Plover mode for stenography use. +* [Swap Hands](feature_swap_hands.md) - Mirror your keyboard for one handed usage. * [Tap Dance](feature_tap_dance.md) - Make a single key do as many things as you want. * [Terminal](feature_terminal.md) - CLI interface to the internals of your keyboard. * [Thermal Printer](feature_thermal_printer.md) - Connect a thermal printer to your keyboard to be able to toggle on a printed log of everything you type. diff --git a/docs/getting_started_build_tools.md b/docs/getting_started_build_tools.md index 636b54672..45b51b2cc 100644 --- a/docs/getting_started_build_tools.md +++ b/docs/getting_started_build_tools.md @@ -4,6 +4,8 @@ This page describes setting up the build environment for QMK. These instructions <!-- FIXME: We should have ARM instructions somewhere. --> +Note: If it is your first time here, Check out the "Complete Newbs guide" instead + ## Linux To ensure you are always up to date, you can just run `sudo util/install_dependencies.sh`. That should always install all the dependencies needed. **This will run `apt-get upgrade`.** diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md index 27d29f5c7..67af78838 100644 --- a/docs/hardware_keyboard_guidelines.md +++ b/docs/hardware_keyboard_guidelines.md @@ -47,16 +47,6 @@ The `info.json` file is a JSON formatted dictionary with the following keys avai * Example: `Clueboard 66%` * `url` * A URL to the keyboard's product page, [QMK.fm/keyboards](https://qmk.fm/keyboards) page, or other page describing information about the keyboard. -* `bootloader` - * What bootloader this keyboard uses. Available options: - * `atmel-dfu` - * `kiibohd-dfu-util` - * `lufa-dfu` - * `qmk-dfu` - * `stm32-dfu-util` - * `caterina` - * `halfkay` - * `bootloadHID` * `maintainer` * GitHub username of the maintainer, or `qmk` for community maintained boards * `width` diff --git a/docs/keycodes.md b/docs/keycodes.md index dad645cf0..ca81d02b6 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -283,6 +283,23 @@ This is a reference only. Each group of keys links to the page documenting their |`RGB_MODE_KNIGHT` |`RGB_M_K` |"Knight Rider" animation mode | |`RGB_MODE_XMAS` |`RGB_M_X` |Christmas animation mode | |`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode | +|`RGB_MODE_RGBTEST` |`RGB_M_T` |Red,Green,Blue test animation mode | + +## [RGB Matrix Lighting](feature_rgb_matrix.md) + +|Key |Aliases |Description | +|-------------------|----------|--------------------------------------------------------------------| +|`RGB_TOG` | |Toggle RGB lighting on or off | +|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held | +|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held| +|`RGB_HUI` | |Increase hue | +|`RGB_HUD` | |Decrease hue | +|`RGB_SAI` | |Increase saturation | +|`RGB_SAD` | |Decrease saturation | +|`RGB_VAI` | |Increase value (brightness) | +|`RGB_VAD` | |Decrease value (brightness) | +|`RGB_SPI` | |Increase effect speed (does no support eeprom yet) | +|`RGB_SPD` | |Decrease effect speed (does no support eeprom yet) | ## [Thermal Printer](feature_thermal_printer.md) diff --git a/docs/newbs_getting_started.md b/docs/newbs_getting_started.md index 162d7066b..218154285 100644 --- a/docs/newbs_getting_started.md +++ b/docs/newbs_getting_started.md @@ -2,7 +2,7 @@ Your computer keyboard has a processor inside of it, not unlike the one inside your computer. This processor runs software that is responsible for detecting button presses and sending reports about the state of the keyboard when they are pressed or released. QMK fills the role of that software, detecting button presses and passing that information on to the host computer. When you build your custom layout you are creating the equivalent of an .exe for your keyboard. -QMK tries to put a lot of power into your hands by making easy things easy, and hard things possible. You don't have to know how to program to create powerful layouts, you only have to follow a few simple syntax rules. +QMK tries to put a lot of power into your hands by making easy things easy, and hard things possible. You don't have to know how to program to create powerful layouts, you only have to follow a few simple syntax rules. # Getting Started @@ -12,13 +12,19 @@ Before you can build keymaps you need to install some software and setup your bu ### Text Editor -You'll need a program that can edit and save **plain text** files. If you are on Windows you can make due with Notepad, and on Linux you can use Gedit, both of which are simple but functional text editors. On macOS you can not use TextEdit.app, it will not save plain text files. You will need to install another program such as Sublime Text. +You'll need a program that can edit and save **plain text** files. If you are on Windows you can make due with Notepad, and on Linux you can use Gedit, both of which are simple but functional text editors. On macOS be careful with TextEdit.app, it will not save plain text files unless you make sure to select "Make Plain text" from the "Format" menu, or you can use another program such as Sublime Text. ?> Not sure which text editor to use? Laurence Bradford wrote [a great introduction](https://learntocodewith.me/programming/basics/text-editors/) to the subject. ### QMK Toolbox -QMK Toolbox is a Windows and macOS program that allows you to both program and debug your custom keyboard. You will want to install it so that you can easily flash your keyboard and receive the debugging messages that your keyboard will print. +QMK Toolbox is an optional graphical Windows and macOS program that allows you to both program and debug your custom keyboard. You will likely prefer it to easily flash your keyboard and receive the debugging messages that your keyboard will print. + +Download the files from the links below: + +For Windows: "qmk_toolbox.exe" or "qmk_toolbox_install.exe" (with installer) + +For Mac: "QMK.Toolbox.app.zip" or "QMK.Toolbox.pkg" (with installer) * [Newest Release](https://github.com/qmk/qmk_toolbox/releases/latest) * [Source Code](https://github.com/qmk/qmk_toolbox/) @@ -43,6 +49,8 @@ You will need to install msys2 and git. You will need to install homebrew. Follow the instructions on the homebrew homepage: https://brew.sh +After homebrew is installed continue with "Download QMK", following step "Setup QMK" runs a script that will install other packages. + ### Linux You will need to install git. It's extremely likely you already have it, but if not one of the following commands should install it: |