diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ChangeLog/20200229.md | 75 | ||||
| -rw-r--r-- | docs/feature_backlight.md | 20 | ||||
| -rw-r--r-- | docs/feature_encoders.md | 52 |
3 files changed, 125 insertions, 22 deletions
diff --git a/docs/ChangeLog/20200229.md b/docs/ChangeLog/20200229.md new file mode 100644 index 000000000..398fe01c0 --- /dev/null +++ b/docs/ChangeLog/20200229.md @@ -0,0 +1,75 @@ +# QMK Breaking Change - 2020 Feb 29 Changelog + +Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps. + + +## Update ChibiOS/ChibiOS-Contrib/uGFX submodules + +* General Notes + * A `make git-submodule` may be required after pulling the latest QMK firmware code to update affected submodules to the upgraded revisions + * Enabling link-time-optimization (`LINK_TIME_OPTIMIZATION_ENABLE = yes`) should work on a lot more boards +* Upgrade to ChibiOS ver19.1.3 + * This will allow QMK to update to upstream ChibiOS a lot easier -- the old version was ~2 years out of date. Automated update scripts have been made available to simplify future upgrades. + * Includes improved MCU support and bugfixes + * ChibiOS revision is now included in Command output + * Timers should now be more accurate +* Upgrade to newer ChibiOS-Contrib + * Also includes improved MCU support and bugfixes + * ChibiOS-Contrib revision is now included in Command output +* Upgrade to newer uGFX + * Required in order to support updated ChibiOS + + +## Fix ChibiOS timer overflow for 16-bit SysTick devices + +* On 16-bit SysTick devices, the timer subsystem in QMK was incorrectly dealing with overflow. + * When running at a 100000 SysTick frequency (possible on 16-bit devices, but uncommon), this overflow would occur after 0.65 seconds. +* Timers are now correctly handling this overflow case and timing should now be correct on ChibiOS/ARM. + + +## Update LUFA submodule + +* Updates the LUFA submodule to include updates from upstream (abcminiuser/lufa) +* Includes some cleanup for QMK DFU generation + + +## Encoder flip + +* Flips the encoder direction so that `clockwise == true` is for actually turning the knob clockwise +* Adds `ENCODER_DIRECTION_FLIP` define, so that reversing the expected dirction is simple for users. +* Cleans up documentation page for encoders + + +## Adding support for `BACKLIGHT_ON_STATE` for hardware PWM backlight + +* Previously, the define only affected software PWM, and hardware PWM always assumed an N-channel MOSFET. +* The hardware PWM backlight setup has been updated to respect this option. +* The default "on" state has been changed to `1` - **this impacts all keyboards using software PWM backlight that do not define it explicitly**. If your keyboard's backlight is acting strange, it may have a P-channel MOSFET, and will need to have `#define BACKLIGHT_ON_STATE 0` added to the keyboard-level `config.h`. Please see the PR for more detailed information. + + +## Migrating `ACTION_LAYER_TAP_KEY()` entries in `fn_actions` to `LT()` keycodes + +* `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()` +* The end result of removing this obsolete feature should result in a decent reduction in firmware size and code complexity +* All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features + + +## Moving backlight keycode handling to `process_keycode/` + +* This refactors the backlight keycode logic to be clearer and more modular. +* All backlight-related keycodes are now actioned in a single file. +* The `ACTION_BACKLIGHT_*` macros have also been deleted. If you are still using these in a `fn_actions[]` block, please switch to using the backlight keycodes or functions directly. + + +## Refactor Planck keymaps to use Layout Macros + +* Refactor Planck keymaps to use layout macros instead of raw matrix assignments +* Makes keymaps revision-agnostic +* Should reduce noise and errors in Travis CI logs + + +## GON NerD codebase refactor + +* Splits the codebase for GON NerD 60 and NerdD TKL PCBs into two separate directories. +* If your keymap is for a NerD 60 PCB, your `make` command is now `make gon/nerd60:<keymap>`. +* If your keymap is for a NerD TKL PCB, your `make` command is now `make gon/nerdtkl:<keymap>`. diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index e74aab1e3..7c68d74e1 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -119,10 +119,22 @@ When both timers are in use for Audio, the backlight PWM will not use a hardware To change the behavior of the backlighting, `#define` these in your `config.h`: -|Define |Default |Description | -|---------------------|-------------|--------------------------------------------------------------------------------------------------------------| -|`BACKLIGHT_PIN` |`B7` |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this | -|`BACKLIGHT_PINS` |*Not defined*|experimental: see below for more information | +|Define |Default |Description | +|---------------------|-------------|-------------------------------------------------------------------------------------------------------------| +|`BACKLIGHT_PIN` |`B7` |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this| +|`BACKLIGHT_PINS` |*Not defined*|experimental: see below for more information | +|`BACKLIGHT_LEVELS` |`3` |The number of brightness levels (maximum 31 excluding off) | +|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) | +|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported | +|`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds | +|`BACKLIGHT_ON_STATE` |`1` |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low | + +### Backlight On State + +Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*. +Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead. + +This functionality is configured at the keyboard level with the `BACKLIGHT_ON_STATE` define. ### Multiple backlight pins diff --git a/docs/feature_encoders.md b/docs/feature_encoders.md index cbf72914e..4a0ae60c3 100644 --- a/docs/feature_encoders.md +++ b/docs/feature_encoders.md @@ -2,23 +2,35 @@ Basic encoders are supported by adding this to your `rules.mk`: - ENCODER_ENABLE = yes +```make +ENCODER_ENABLE = yes +``` and this to your `config.h`: - #define ENCODERS_PAD_A { B12 } - #define ENCODERS_PAD_B { B13 } +```c +#define ENCODERS_PAD_A { B12 } +#define ENCODERS_PAD_B { B13 } +``` Each PAD_A/B variable defines an array so multiple encoders can be defined, e.g.: - #define ENCODERS_PAD_A { encoder1a, encoder2a } - #define ENCODERS_PAD_B { encoder1b, encoder2b } +```c +#define ENCODERS_PAD_A { encoder1a, encoder2a } +#define ENCODERS_PAD_B { encoder1b, encoder2b } +``` + +If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions. They can also be flipped with a define: -If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions. +```c +#define ENCODER_DIRECTION_FLIP +``` Additionally, the resolution can be specified in the same file (the default & suggested is 4): - #define ENCODER_RESOLUTION 4 +```c +#define ENCODER_RESOLUTION 4 +``` ## Split Keyboards @@ -33,27 +45,31 @@ If you are using different pinouts for the encoders on each half of a split keyb The callback functions can be inserted into your `<keyboard>.c`: - void encoder_update_kb(uint8_t index, bool clockwise) { - encoder_update_user(index, clockwise); - } +```c +void encoder_update_kb(uint8_t index, bool clockwise) { + encoder_update_user(index, clockwise); +} +``` or `keymap.c`: - void encoder_update_user(uint8_t index, bool clockwise) { - if (index == 0) { /* First encoder */ +```c +void encoder_update_user(uint8_t index, bool clockwise) { + if (index == 0) { /* First encoder */ if (clockwise) { - tap_code(KC_PGDN); + tap_code(KC_PGDN); } else { - tap_code(KC_PGUP); + tap_code(KC_PGUP); } - } else if (index == 1) { /* Second encoder */ + } else if (index == 1) { /* Second encoder */ if (clockwise) { - tap_code(KC_UP); + tap_code(KC_DOWN); } else { - tap_code(KC_DOWN); + tap_code(KC_UP); } - } } +} +``` ## Hardware |