From 70cbf08b673c2cc59e603503e834ac460040ecc1 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Tue, 27 Aug 2024 10:52:23 +1000 Subject: Add new connection keycodes for Bluetooth, 2.4GHz. (#24251) --- tests/test_common/keycode_table.cpp | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'tests/test_common/keycode_table.cpp') diff --git a/tests/test_common/keycode_table.cpp b/tests/test_common/keycode_table.cpp index 4c28ab4d20..e4d445de82 100644 --- a/tests/test_common/keycode_table.cpp +++ b/tests/test_common/keycode_table.cpp @@ -562,6 +562,20 @@ std::map KEYCODE_ID_TABLE = { {QK_MACRO_29, "QK_MACRO_29"}, {QK_MACRO_30, "QK_MACRO_30"}, {QK_MACRO_31, "QK_MACRO_31"}, + {QK_OUTPUT_NEXT, "QK_OUTPUT_NEXT"}, + {QK_OUTPUT_PREV, "QK_OUTPUT_PREV"}, + {QK_OUTPUT_NONE, "QK_OUTPUT_NONE"}, + {QK_OUTPUT_USB, "QK_OUTPUT_USB"}, + {QK_OUTPUT_2P4GHZ, "QK_OUTPUT_2P4GHZ"}, + {QK_OUTPUT_BLUETOOTH, "QK_OUTPUT_BLUETOOTH"}, + {QK_BLUETOOTH_PROFILE_NEXT, "QK_BLUETOOTH_PROFILE_NEXT"}, + {QK_BLUETOOTH_PROFILE_PREV, "QK_BLUETOOTH_PROFILE_PREV"}, + {QK_BLUETOOTH_UNPAIR, "QK_BLUETOOTH_UNPAIR"}, + {QK_BLUETOOTH_PROFILE1, "QK_BLUETOOTH_PROFILE1"}, + {QK_BLUETOOTH_PROFILE2, "QK_BLUETOOTH_PROFILE2"}, + {QK_BLUETOOTH_PROFILE3, "QK_BLUETOOTH_PROFILE3"}, + {QK_BLUETOOTH_PROFILE4, "QK_BLUETOOTH_PROFILE4"}, + {QK_BLUETOOTH_PROFILE5, "QK_BLUETOOTH_PROFILE5"}, {QK_BACKLIGHT_ON, "QK_BACKLIGHT_ON"}, {QK_BACKLIGHT_OFF, "QK_BACKLIGHT_OFF"}, {QK_BACKLIGHT_TOGGLE, "QK_BACKLIGHT_TOGGLE"}, @@ -632,9 +646,6 @@ std::map KEYCODE_ID_TABLE = { {QK_SPACE_CADET_LEFT_ALT_PARENTHESIS_OPEN, "QK_SPACE_CADET_LEFT_ALT_PARENTHESIS_OPEN"}, {QK_SPACE_CADET_RIGHT_ALT_PARENTHESIS_CLOSE, "QK_SPACE_CADET_RIGHT_ALT_PARENTHESIS_CLOSE"}, {QK_SPACE_CADET_RIGHT_SHIFT_ENTER, "QK_SPACE_CADET_RIGHT_SHIFT_ENTER"}, - {QK_OUTPUT_AUTO, "QK_OUTPUT_AUTO"}, - {QK_OUTPUT_USB, "QK_OUTPUT_USB"}, - {QK_OUTPUT_BLUETOOTH, "QK_OUTPUT_BLUETOOTH"}, {QK_UNICODE_MODE_NEXT, "QK_UNICODE_MODE_NEXT"}, {QK_UNICODE_MODE_PREVIOUS, "QK_UNICODE_MODE_PREVIOUS"}, {QK_UNICODE_MODE_MACOS, "QK_UNICODE_MODE_MACOS"}, -- cgit v1.2.3 From 0bda0f47754d01aa904f9831ff58ef760807ab16 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Thu, 14 Nov 2024 21:16:52 +1100 Subject: Revert removal of `QK_OUTPUT_AUTO`, fixup docs to reflect. (#24593) --- .../keycodes/keycodes_0.0.6_connection.hjson | 18 ++++--- docs/_aliases.json | 4 +- docs/_sidebar.json | 4 +- docs/features/bluetooth.md | 46 ----------------- docs/features/wireless.md | 58 ++++++++++++++++++++++ docs/keycodes.md | 30 +++++++---- docs/reference_info_json.md | 4 +- quantum/keycodes.h | 19 +++---- tests/test_common/keycode_table.cpp | 1 + 9 files changed, 109 insertions(+), 75 deletions(-) delete mode 100644 docs/features/bluetooth.md create mode 100644 docs/features/wireless.md (limited to 'tests/test_common/keycode_table.cpp') diff --git a/data/constants/keycodes/keycodes_0.0.6_connection.hjson b/data/constants/keycodes/keycodes_0.0.6_connection.hjson index 9a1a750f1a..9be1106825 100644 --- a/data/constants/keycodes/keycodes_0.0.6_connection.hjson +++ b/data/constants/keycodes/keycodes_0.0.6_connection.hjson @@ -7,41 +7,47 @@ "keycodes": { "0x7780": { "group": "connection", - "key": "QK_OUTPUT_NEXT", + "key": "QK_OUTPUT_AUTO", "aliases": [ - "OU_NEXT", "OU_AUTO" ] }, "0x7781": { + "group": "connection", + "key": "QK_OUTPUT_NEXT", + "aliases": [ + "OU_NEXT" + ] + }, + "0x7782": { "group": "connection", "key": "QK_OUTPUT_PREV", "aliases": [ "OU_PREV" ] }, - "0x7782": { + "0x7783": { "group": "connection", "key": "QK_OUTPUT_NONE", "aliases": [ "OU_NONE" ] }, - "0x7783": { + "0x7784": { "group": "connection", "key": "QK_OUTPUT_USB", "aliases": [ "OU_USB" ] }, - "0x7784": { + "0x7785": { "group": "connection", "key": "QK_OUTPUT_2P4GHZ", "aliases": [ "OU_2P4G" ] }, - "0x7785": { + "0x7786": { "group": "connection", "key": "QK_OUTPUT_BLUETOOTH", "aliases": [ diff --git a/docs/_aliases.json b/docs/_aliases.json index f06e032215..0dfcdea1e2 100644 --- a/docs/_aliases.json +++ b/docs/_aliases.json @@ -16,6 +16,8 @@ "/tutorial": "/newbs", "/unicode": "/feature_unicode", + "/features/bluetooth": "/features/wireless", + "/adc_driver": "/drivers/adc", "/apa102_driver": "/drivers/apa102", "/audio_driver": "/drivers/audio", @@ -24,7 +26,7 @@ "/feature_auto_shift": "/features/auto_shift", "/feature_autocorrect": "/features/autocorrect", "/feature_backlight": "/features/backlight", - "/feature_bluetooth": "/features/bluetooth", + "/feature_bluetooth": "/features/wireless", "/feature_bootmagic": "/features/bootmagic", "/feature_caps_word": "/features/caps_word", "/feature_combo": "/features/combo", diff --git a/docs/_sidebar.json b/docs/_sidebar.json index d691011d64..7f353ad351 100644 --- a/docs/_sidebar.json +++ b/docs/_sidebar.json @@ -166,7 +166,6 @@ ] }, { "text": "Audio", "link": "/features/audio" }, - { "text": "Bluetooth", "link": "/features/bluetooth" }, { "text": "Bootmagic", "link": "/features/bootmagic" }, { "text": "Converters", "link": "/feature_converters" }, { "text": "Custom Matrix", "link": "/custom_matrix" }, @@ -179,7 +178,8 @@ { "text": "Pointing Device", "link": "/features/pointing_device" }, { "text": "PS/2 Mouse", "link": "/features/ps2_mouse" }, { "text": "Split Keyboard", "link": "/features/split_keyboard" }, - { "text": "Stenography", "link": "/features/stenography" } + { "text": "Stenography", "link": "/features/stenography" }, + { "text": "Wireless", "link": "/features/wireless" } ] }, { diff --git a/docs/features/bluetooth.md b/docs/features/bluetooth.md deleted file mode 100644 index d3634498be..0000000000 --- a/docs/features/bluetooth.md +++ /dev/null @@ -1,46 +0,0 @@ -# Bluetooth - -## Bluetooth Known Supported Hardware - -Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QMK has support for RN-42 modules. For more recent BLE protocols, currently only the Adafruit Bluefruit SPI Friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support mouse input. - -|Board |Bluetooth Protocol |Connection Type|rules.mk |Bluetooth Chip| -|----------------------------------------------------------------|--------------------|---------------|---------------------------------|--------------| -|Roving Networks RN-42 (Sparkfun Bluesmirf) |Bluetooth Classic |UART |`BLUETOOTH_DRIVER = rn42` |RN-42 | -|[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy|SPI |`BLUETOOTH_DRIVER = bluefruit_le`|nRF51822 | - -Not Supported Yet but possible: -* [Bluefruit LE UART Friend](https://www.adafruit.com/product/2479). [Possible tmk implementation found in](https://github.com/tmk/tmk_keyboard/issues/514) -* HC-05 boards flashed with RN-42 firmware. They apparently both use the CSR BC417 Chip. Flashing it with RN-42 firmware gives it HID capability. -* Sparkfun Bluetooth Mate -* HM-13 based boards - -### Adafruit BLE SPI Friend -Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit SPI Friend. It's a Nordic nRF51822 based chip running Adafruit's custom firmware. Data is transmitted via Adafruit's SDEP over Hardware SPI. The [Feather 32u4 Bluefruit LE](https://www.adafruit.com/product/2829) is supported as it's an AVR mcu connected via SPI to the Nordic BLE chip with Adafruit firmware. If Building a custom board with the SPI friend it would be easiest to just use the pin selection that the 32u4 feather uses but you can change the pins in the config.h options with the following defines: -* `#define BLUEFRUIT_LE_RST_PIN D4` -* `#define BLUEFRUIT_LE_CS_PIN B4` -* `#define BLUEFRUIT_LE_IRQ_PIN E6` - -A Bluefruit UART friend can be converted to an SPI friend, however this [requires](https://github.com/qmk/qmk_firmware/issues/2274) some reflashing and soldering directly to the MDBT40 chip. - - -## Bluetooth Rules.mk Options - -The currently supported Bluetooth chipsets do not support [N-Key Rollover (NKRO)](../reference_glossary#n-key-rollover-nkro), so `rules.mk` must contain `NKRO_ENABLE = no`. - -Add the following to your `rules.mk`: - -```make -BLUETOOTH_ENABLE = yes -BLUETOOTH_DRIVER = bluefruit_le # or rn42 -``` - -## Bluetooth Keycodes - -This is used when multiple keyboard outputs can be selected. Currently this only allows for switching between USB and Bluetooth on keyboards that support both. - -| Key | Aliases | Description | -|-----------------------|----------------------|------------------------------------------------| -| `QK_OUTPUT_NEXT` | `OU_NEXT`, `OU_AUTO` | Automatically switch between USB and Bluetooth | -| `QK_OUTPUT_USB` | `OU_USB` | USB only | -| `QK_OUTPUT_BLUETOOTH` | `OU_BT` | Bluetooth only | diff --git a/docs/features/wireless.md b/docs/features/wireless.md new file mode 100644 index 0000000000..0d73ad3583 --- /dev/null +++ b/docs/features/wireless.md @@ -0,0 +1,58 @@ +# Wireless / Bluetooth + +## Bluetooth Known Supported Hardware + +Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QMK has support for RN-42 modules. For more recent BLE protocols, currently only the Adafruit Bluefruit SPI Friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support mouse input. + +|Board |Bluetooth Protocol |Connection Type|rules.mk |Bluetooth Chip| +|----------------------------------------------------------------|--------------------|---------------|---------------------------------|--------------| +|Roving Networks RN-42 (Sparkfun Bluesmirf) |Bluetooth Classic |UART |`BLUETOOTH_DRIVER = rn42` |RN-42 | +|[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy|SPI |`BLUETOOTH_DRIVER = bluefruit_le`|nRF51822 | + +Not Supported Yet but possible: +* [Bluefruit LE UART Friend](https://www.adafruit.com/product/2479). [Possible tmk implementation found in](https://github.com/tmk/tmk_keyboard/issues/514) +* HC-05 boards flashed with RN-42 firmware. They apparently both use the CSR BC417 Chip. Flashing it with RN-42 firmware gives it HID capability. +* Sparkfun Bluetooth Mate +* HM-13 based boards + +### Adafruit BLE SPI Friend +Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit SPI Friend. It's a Nordic nRF51822 based chip running Adafruit's custom firmware. Data is transmitted via Adafruit's SDEP over Hardware SPI. The [Feather 32u4 Bluefruit LE](https://www.adafruit.com/product/2829) is supported as it's an AVR mcu connected via SPI to the Nordic BLE chip with Adafruit firmware. If Building a custom board with the SPI friend it would be easiest to just use the pin selection that the 32u4 feather uses but you can change the pins in the config.h options with the following defines: +* `#define BLUEFRUIT_LE_RST_PIN D4` +* `#define BLUEFRUIT_LE_CS_PIN B4` +* `#define BLUEFRUIT_LE_IRQ_PIN E6` + +A Bluefruit UART friend can be converted to an SPI friend, however this [requires](https://github.com/qmk/qmk_firmware/issues/2274) some reflashing and soldering directly to the MDBT40 chip. + + +## Bluetooth Rules.mk Options + +The currently supported Bluetooth chipsets do not support [N-Key Rollover (NKRO)](../reference_glossary#n-key-rollover-nkro), so `rules.mk` must contain `NKRO_ENABLE = no`. + +Add the following to your `rules.mk`: + +```make +BLUETOOTH_ENABLE = yes +BLUETOOTH_DRIVER = bluefruit_le # or rn42 +``` + +## Bluetooth Keycodes + +This is used when multiple keyboard outputs can be selected. Currently this only allows for switching between USB and Bluetooth on keyboards that support both. + +| Key | Aliases | Description | +|-----------------------------|-----------|-----------------------------------------------------------------------------------------------| +| `QK_OUTPUT_AUTO` | `OU_AUTO` | Automatically switch to USB when plugged in, otherwise use wireless | +| `QK_OUTPUT_NEXT` | `OU_NEXT` | Cycle forwards through USB, Bluetooth, and 2.4GHz (when available) **(not yet implemented)** | +| `QK_OUTPUT_PREV` | `OU_PREV` | Cycle backwards through USB, Bluetooth, and 2.4GHz (when available) **(not yet implemented)** | +| `QK_OUTPUT_NONE` | `OU_NONE` | Disable all output **(not yet implemented)** | +| `QK_OUTPUT_USB` | `OU_USB` | Output to USB only | +| `QK_OUTPUT_2P4GHZ` | `OU_2P4G` | Output to 2.4GHz only **(not yet implemented)** | +| `QK_OUTPUT_BLUETOOTH` | `OU_BT` | Output to Bluetooth only | +| `QK_BLUETOOTH_PROFILE_NEXT` | `BT_NEXT` | Move to the next Bluetooth profile **(not yet implemented)** | +| `QK_BLUETOOTH_PROFILE_PREV` | `BT_PREV` | Move to the previous Bluetooth profile **(not yet implemented)** | +| `QK_BLUETOOTH_UNPAIR` | `BT_UNPR` | Un-pair the current Bluetooth profile **(not yet implemented)** | +| `QK_BLUETOOTH_PROFILE1` | `BT_PRF1` | Swap to Bluetooth profile #1 **(not yet implemented)** | +| `QK_BLUETOOTH_PROFILE2` | `BT_PRF2` | Swap to Bluetooth profile #2 **(not yet implemented)** | +| `QK_BLUETOOTH_PROFILE3` | `BT_PRF3` | Swap to Bluetooth profile #3 **(not yet implemented)** | +| `QK_BLUETOOTH_PROFILE4` | `BT_PRF4` | Swap to Bluetooth profile #4 **(not yet implemented)** | +| `QK_BLUETOOTH_PROFILE5` | `BT_PRF5` | Swap to Bluetooth profile #5 **(not yet implemented)** | diff --git a/docs/keycodes.md b/docs/keycodes.md index 1210390f54..3665747a0b 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -290,15 +290,27 @@ See also: [Backlighting](features/backlight) | `QK_BACKLIGHT_DOWN` | `BL_DOWN` | Decrease the backlight level | | `QK_BACKLIGHT_TOGGLE_BREATHING` | `BL_BRTG` | Toggle backlight breathing | -## Bluetooth {#bluetooth} - -See also: [Bluetooth](features/bluetooth) - -| Key | Aliases | Description | -|-----------------------|----------------------|------------------------------------------------| -| `QK_OUTPUT_NEXT` | `OU_NEXT`, `OU_AUTO` | Automatically switch between USB and Bluetooth | -| `QK_OUTPUT_USB` | `OU_USB` | USB only | -| `QK_OUTPUT_BLUETOOTH` | `OU_BT` | Bluetooth only | +## Wireless/Bluetooth {#bluetooth} + +See also: [Wireless](features/wireless) + +| Key | Aliases | Description | +|-----------------------------|-----------|-----------------------------------------------------------------------------------------------| +| `QK_OUTPUT_AUTO` | `OU_AUTO` | Automatically switch to USB when plugged in, otherwise use wireless | +| `QK_OUTPUT_NEXT` | `OU_NEXT` | Cycle forwards through USB, Bluetooth, and 2.4GHz (when available) **(not yet implemented)** | +| `QK_OUTPUT_PREV` | `OU_PREV` | Cycle backwards through USB, Bluetooth, and 2.4GHz (when available) **(not yet implemented)** | +| `QK_OUTPUT_NONE` | `OU_NONE` | Disable all output **(not yet implemented)** | +| `QK_OUTPUT_USB` | `OU_USB` | Output to USB only | +| `QK_OUTPUT_2P4GHZ` | `OU_2P4G` | Output to 2.4GHz only **(not yet implemented)** | +| `QK_OUTPUT_BLUETOOTH` | `OU_BT` | Output to Bluetooth only | +| `QK_BLUETOOTH_PROFILE_NEXT` | `BT_NEXT` | Move to the next Bluetooth profile **(not yet implemented)** | +| `QK_BLUETOOTH_PROFILE_PREV` | `BT_PREV` | Move to the previous Bluetooth profile **(not yet implemented)** | +| `QK_BLUETOOTH_UNPAIR` | `BT_UNPR` | Un-pair the current Bluetooth profile **(not yet implemented)** | +| `QK_BLUETOOTH_PROFILE1` | `BT_PRF1` | Swap to Bluetooth profile #1 **(not yet implemented)** | +| `QK_BLUETOOTH_PROFILE2` | `BT_PRF2` | Swap to Bluetooth profile #2 **(not yet implemented)** | +| `QK_BLUETOOTH_PROFILE3` | `BT_PRF3` | Swap to Bluetooth profile #3 **(not yet implemented)** | +| `QK_BLUETOOTH_PROFILE4` | `BT_PRF4` | Swap to Bluetooth profile #4 **(not yet implemented)** | +| `QK_BLUETOOTH_PROFILE5` | `BT_PRF5` | Swap to Bluetooth profile #5 **(not yet implemented)** | ## Caps Word {#caps-word} diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index c1061cdf82..99ff7b1f7a 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -177,9 +177,9 @@ Configures the [Backlight](features/backlight) feature. * `pins` Array: Pin * A list of GPIO pins connected to the backlight LEDs (`software` and `timer` drivers only). -## Bluetooth {#bluetooth} +## Wireless/Bluetooth {#bluetooth} -Configures the [Bluetooth](features/bluetooth) feature. +Configures the [Wireless](features/wireless) feature. * `bluetooth` * `driver` String diff --git a/quantum/keycodes.h b/quantum/keycodes.h index 38127bb6da..51b7eb6c9a 100644 --- a/quantum/keycodes.h +++ b/quantum/keycodes.h @@ -622,12 +622,13 @@ enum qk_keycode_defines { QK_MACRO_29 = 0x771D, QK_MACRO_30 = 0x771E, QK_MACRO_31 = 0x771F, - QK_OUTPUT_NEXT = 0x7780, - QK_OUTPUT_PREV = 0x7781, - QK_OUTPUT_NONE = 0x7782, - QK_OUTPUT_USB = 0x7783, - QK_OUTPUT_2P4GHZ = 0x7784, - QK_OUTPUT_BLUETOOTH = 0x7785, + QK_OUTPUT_AUTO = 0x7780, + QK_OUTPUT_NEXT = 0x7781, + QK_OUTPUT_PREV = 0x7782, + QK_OUTPUT_NONE = 0x7783, + QK_OUTPUT_USB = 0x7784, + QK_OUTPUT_2P4GHZ = 0x7785, + QK_OUTPUT_BLUETOOTH = 0x7786, QK_BLUETOOTH_PROFILE_NEXT = 0x7790, QK_BLUETOOTH_PROFILE_PREV = 0x7791, QK_BLUETOOTH_UNPAIR = 0x7792, @@ -1309,8 +1310,8 @@ enum qk_keycode_defines { MC_29 = QK_MACRO_29, MC_30 = QK_MACRO_30, MC_31 = QK_MACRO_31, + OU_AUTO = QK_OUTPUT_AUTO, OU_NEXT = QK_OUTPUT_NEXT, - OU_AUTO = QK_OUTPUT_NEXT, OU_PREV = QK_OUTPUT_PREV, OU_NONE = QK_OUTPUT_NONE, OU_USB = QK_OUTPUT_USB, @@ -1494,7 +1495,7 @@ enum qk_keycode_defines { #define IS_AUDIO_KEYCODE(code) ((code) >= QK_AUDIO_ON && (code) <= QK_AUDIO_VOICE_PREVIOUS) #define IS_STENO_KEYCODE(code) ((code) >= QK_STENO_BOLT && (code) <= QK_STENO_COMB_MAX) #define IS_MACRO_KEYCODE(code) ((code) >= QK_MACRO_0 && (code) <= QK_MACRO_31) -#define IS_CONNECTION_KEYCODE(code) ((code) >= QK_OUTPUT_NEXT && (code) <= QK_BLUETOOTH_PROFILE5) +#define IS_CONNECTION_KEYCODE(code) ((code) >= QK_OUTPUT_AUTO && (code) <= QK_BLUETOOTH_PROFILE5) #define IS_BACKLIGHT_KEYCODE(code) ((code) >= QK_BACKLIGHT_ON && (code) <= QK_BACKLIGHT_TOGGLE_BREATHING) #define IS_LED_MATRIX_KEYCODE(code) ((code) >= QK_LED_MATRIX_ON && (code) <= QK_LED_MATRIX_SPEED_DOWN) #define IS_UNDERGLOW_KEYCODE(code) ((code) >= QK_UNDERGLOW_TOGGLE && (code) <= QK_UNDERGLOW_SPEED_DOWN) @@ -1520,7 +1521,7 @@ enum qk_keycode_defines { #define AUDIO_KEYCODE_RANGE QK_AUDIO_ON ... QK_AUDIO_VOICE_PREVIOUS #define STENO_KEYCODE_RANGE QK_STENO_BOLT ... QK_STENO_COMB_MAX #define MACRO_KEYCODE_RANGE QK_MACRO_0 ... QK_MACRO_31 -#define CONNECTION_KEYCODE_RANGE QK_OUTPUT_NEXT ... QK_BLUETOOTH_PROFILE5 +#define CONNECTION_KEYCODE_RANGE QK_OUTPUT_AUTO ... QK_BLUETOOTH_PROFILE5 #define BACKLIGHT_KEYCODE_RANGE QK_BACKLIGHT_ON ... QK_BACKLIGHT_TOGGLE_BREATHING #define LED_MATRIX_KEYCODE_RANGE QK_LED_MATRIX_ON ... QK_LED_MATRIX_SPEED_DOWN #define UNDERGLOW_KEYCODE_RANGE QK_UNDERGLOW_TOGGLE ... QK_UNDERGLOW_SPEED_DOWN diff --git a/tests/test_common/keycode_table.cpp b/tests/test_common/keycode_table.cpp index e4d445de82..a520dd3f2b 100644 --- a/tests/test_common/keycode_table.cpp +++ b/tests/test_common/keycode_table.cpp @@ -562,6 +562,7 @@ std::map KEYCODE_ID_TABLE = { {QK_MACRO_29, "QK_MACRO_29"}, {QK_MACRO_30, "QK_MACRO_30"}, {QK_MACRO_31, "QK_MACRO_31"}, + {QK_OUTPUT_AUTO, "QK_OUTPUT_AUTO"}, {QK_OUTPUT_NEXT, "QK_OUTPUT_NEXT"}, {QK_OUTPUT_PREV, "QK_OUTPUT_PREV"}, {QK_OUTPUT_NONE, "QK_OUTPUT_NONE"}, -- cgit v1.2.3 From 36b5559b997cedd14a352aa70891558936b8b3a3 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Wed, 20 Nov 2024 22:31:54 -0800 Subject: [Core] Add Layer Lock feature (#23430) Co-authored-by: Daniel <1767914+iamdanielv@users.noreply.github.com> Co-authored-by: Pascal Getreuer Co-authored-by: Pascal Getreuer <50221757+getreuer@users.noreply.github.com> --- builddefs/generic_features.mk | 1 + .../keycodes/keycodes_0.0.6_quantum.hjson | 7 + data/mappings/info_config.hjson | 3 + data/schemas/keyboard.jsonschema | 6 + docs/_sidebar.json | 1 + docs/feature_layers.md | 3 + docs/features/layer_lock.md | 139 ++++++++++ docs/keycodes.md | 8 + quantum/keyboard.c | 7 + quantum/keycodes.h | 6 +- quantum/layer_lock.c | 81 ++++++ quantum/layer_lock.h | 135 ++++++++++ quantum/process_keycode/process_layer_lock.c | 95 +++++++ quantum/process_keycode/process_layer_lock.h | 69 +++++ quantum/quantum.c | 7 + quantum/quantum.h | 4 + tests/layer_lock/config.h | 8 + tests/layer_lock/test.mk | 8 + tests/layer_lock/test_layer_lock.cpp | 284 +++++++++++++++++++++ tests/test_common/keycode_table.cpp | 1 + 20 files changed, 871 insertions(+), 2 deletions(-) create mode 100644 docs/features/layer_lock.md create mode 100644 quantum/layer_lock.c create mode 100644 quantum/layer_lock.h create mode 100644 quantum/process_keycode/process_layer_lock.c create mode 100644 quantum/process_keycode/process_layer_lock.h create mode 100644 tests/layer_lock/config.h create mode 100644 tests/layer_lock/test.mk create mode 100644 tests/layer_lock/test_layer_lock.cpp (limited to 'tests/test_common/keycode_table.cpp') diff --git a/builddefs/generic_features.mk b/builddefs/generic_features.mk index dc34a64230..f14f440877 100644 --- a/builddefs/generic_features.mk +++ b/builddefs/generic_features.mk @@ -36,6 +36,7 @@ GENERIC_FEATURES = \ HAPTIC \ KEY_LOCK \ KEY_OVERRIDE \ + LAYER_LOCK \ LEADER \ MAGIC \ MOUSEKEY \ diff --git a/data/constants/keycodes/keycodes_0.0.6_quantum.hjson b/data/constants/keycodes/keycodes_0.0.6_quantum.hjson index 814cd66a5b..be3285f9e4 100644 --- a/data/constants/keycodes/keycodes_0.0.6_quantum.hjson +++ b/data/constants/keycodes/keycodes_0.0.6_quantum.hjson @@ -3,5 +3,12 @@ "0x7C20": "!delete!", // old QK_OUTPUT_AUTO "0x7C21": "!delete!", // old QK_OUTPUT_USB "0x7C22": "!delete!", // old QK_OUTPUT_BLUETOOTH + "0x7C7B": { + "group": "quantum", + "key": "QK_LAYER_LOCK", + "aliases": [ + "QK_LLCK" + ] + } } } diff --git a/data/mappings/info_config.hjson b/data/mappings/info_config.hjson index 4c895cf5d5..8d3e3c7f0e 100644 --- a/data/mappings/info_config.hjson +++ b/data/mappings/info_config.hjson @@ -64,6 +64,9 @@ "WEAR_LEVELING_BACKING_SIZE": {"info_key": "eeprom.wear_leveling.backing_size", "value_type": "int", "to_json": false}, "WEAR_LEVELING_LOGICAL_SIZE": {"info_key": "eeprom.wear_leveling.logical_size", "value_type": "int", "to_json": false}, + // Layer locking + "LAYER_LOCK_IDLE_TIMEOUT": {"info_key": "layer_lock.timeout", "value_type": "int"}, + // Indicators "LED_CAPS_LOCK_PIN": {"info_key": "indicators.caps_lock"}, "LED_NUM_LOCK_PIN": {"info_key": "indicators.num_lock"}, diff --git a/data/schemas/keyboard.jsonschema b/data/schemas/keyboard.jsonschema index 9f1f6dd74a..ec87680fa0 100644 --- a/data/schemas/keyboard.jsonschema +++ b/data/schemas/keyboard.jsonschema @@ -375,6 +375,12 @@ } }, "keycodes": {"$ref": "qmk.definitions.v1#/keycode_decl_array"}, + "layer_lock": { + "type": "object", + "properties": { + "timeout": {"$ref": "qmk.definitions.v1#/unsigned_int"} + } + }, "layout_aliases": { "type": "object", "additionalProperties": {"$ref": "qmk.definitions.v1#/layout_macro"} diff --git a/docs/_sidebar.json b/docs/_sidebar.json index 7f353ad351..15c3cbec31 100644 --- a/docs/_sidebar.json +++ b/docs/_sidebar.json @@ -123,6 +123,7 @@ { "text": "Key Lock", "link": "/features/key_lock" }, { "text": "Key Overrides", "link": "/features/key_overrides" }, { "text": "Layers", "link": "/feature_layers" }, + { "text": "Layer Lock", "link": "/features/layer_lock" }, { "text": "One Shot Keys", "link": "/one_shot_keys" }, { "text": "OS Detection", "link": "/features/os_detection" }, { "text": "Raw HID", "link": "/features/rawhid" }, diff --git a/docs/feature_layers.md b/docs/feature_layers.md index 30ab713222..45f02fe536 100644 --- a/docs/feature_layers.md +++ b/docs/feature_layers.md @@ -17,6 +17,9 @@ These functions allow you to activate layers in various ways. Note that layers a * `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed). * `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps. +See also the [Layer Lock key](features/layer_lock), which locks the highest +active layer until pressed again. + ### Caveats {#caveats} Currently, the `layer` argument of `LT()` is limited to layers 0-15, and the `kc` argument to the [Basic Keycode set](keycodes_basic), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. This is because QMK uses 16-bit keycodes, of which 4 bits are used for the function identifier and 4 bits for the layer, leaving only 8 bits for the keycode. diff --git a/docs/features/layer_lock.md b/docs/features/layer_lock.md new file mode 100644 index 0000000000..aaf323accc --- /dev/null +++ b/docs/features/layer_lock.md @@ -0,0 +1,139 @@ +# Layer Lock + +Some [layer switches](../feature_layers#switching-and-toggling-layers) access +the layer by holding the key, including momentary layer `MO(layer)` and layer +tap `LT(layer, key)` keys. You may sometimes need to stay on the layer for a +long period of time. Layer Lock "locks" the current layer to stay on, supposing +it was accessed by one of: + + * `MO(layer)` momentary layer switch + * `LT(layer, key)` layer tap + * `OSL(layer)` one-shot layer + * `TT(layer)` layer tap toggle + * `LM(layer, mod)` layer-mod key (the layer is locked, but not the mods) + +Press the Layer Lock key again to unlock the layer. Additionally, when a layer +is locked, layer switch keys that turn off the layer such as `TO(other_layer)` +will unlock it. + + +## How do I enable Layer Lock + +In your rules.mk, add: + +```make +LAYER_LOCK_ENABLE = yes +``` + +Pick a key in your keymap on a layer you intend to lock, and assign it the +keycode `QK_LAYER_LOCK` (short alias `QK_LLCK`). Note that locking the base +layer has no effect, so typically, this key is used on layers above the base +layer. + + +## Example use + +Consider a keymap with the following base layer. + +![Base layer with a MO(NAV) key.](https://i.imgur.com/DkEhj9x.png) + +The highlighted key is a momentary layer switch `MO(NAV)`. Holding it accesses a +navigation layer. + +![Nav layer with a Layer Lock key.](https://i.imgur.com/2wUZNWk.png) + + +Holding the NAV key is fine for brief use, but awkward to continue holding when +using navigation functions continuously. The Layer Lock key comes to the rescue: + +1. Hold the NAV key, activating the navigation layer. +2. Tap Layer Lock. +3. Release NAV. The navigation layer stays on. +4. Make use of the arrow keys, etc. +5. Tap Layer Lock or NAV again to turn the navigation layer back off. + +A variation that would also work is to put the Layer Lock key on the base layer +and make other layers transparent (`KC_TRNS`) in that position. Pressing the +Layer Lock key locks (or unlocks) the highest active layer, regardless of which +layer the Layer Lock key is on. + + +## Idle timeout + +Optionally, Layer Lock may be configured to unlock if the keyboard is idle +for some time. In config.h, define `LAYER_LOCK_IDLE_TIMEOUT` in units of +milliseconds: + +```c +#define LAYER_LOCK_IDLE_TIMEOUT 60000 // Turn off after 60 seconds. +``` + + +## Functions + +Use the following functions to query and manipulate the layer lock state. + +| Function | Description | +|----------------------------|------------------------------------| +| `is_layer_locked(layer)` | Checks whether `layer` is locked. | +| `layer_lock_on(layer)` | Locks and turns on `layer`. | +| `layer_lock_off(layer)` | Unlocks and turns off `layer`. | +| `layer_lock_invert(layer)` | Toggles whether `layer` is locked. | + + +## Representing the current Layer Lock state + +There is an optional callback `layer_lock_set_user()` that gets called when a +layer is locked or unlocked. This is useful to represent the current lock state +for instance by setting an LED. In keymap.c, define + +```c +bool layer_lock_set_user(layer_state_t locked_layers) { + // Do something like `set_led(is_layer_locked(NAV));` + return true; +} +``` + +The argument `locked_layers` is a bitfield in which the kth bit is on if the kth +layer is locked. Alternatively, you can use `is_layer_locked(layer)` to check if +a given layer is locked. + + +## Combine Layer Lock with a mod-tap + +It is possible to create a [mod-tap MT key](../mod_tap) that acts as a modifier +on hold and Layer Lock on tap. Since Layer Lock is not a [basic +keycode](../keycodes_basic), attempting `MT(mod, QK_LLCK)` is invalid does not +work directly, yet this effect can be achieved through [changing the tap +function](../mod_tap#changing-tap-function). For example, the following +implements a `SFTLLCK` key that acts as Shift on hold and Layer Lock on tap: + +```c +#define SFTLLCK LSFT_T(KC_0) + +// Use SFTLLCK in your keymap... + +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case SFTLLCK: + if (record->tap.count) { + if (record->event.pressed) { + // Toggle the lock on the highest layer. + layer_lock_invert(get_highest_layer(layer_state)); + } + return false; + } + break; + + // Other macros... + } + return true; +} +``` + +In the above, `KC_0` is an arbitrary placeholder for the tapping keycode. This +keycode will never be sent, so any basic keycode will do. In +`process_record_user()`, the tap press event is changed to toggle the lock on +the highest layer. Layer Lock can be combined with a [layer-tap LT +key](../feature_layers#switching-and-toggling-layers) similarly. + diff --git a/docs/keycodes.md b/docs/keycodes.md index 3665747a0b..cae6418266 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -387,6 +387,14 @@ See also: [Key Lock](features/key_lock) |---------|--------------------------------------------------------------| |`QK_LOCK`|Hold down the next key pressed, until the key is pressed again| +## Layer Lock {#layer-lock} + +See also: [Layer Lock](features/layer_lock) + +|Key |Aliases |Description | +|---------------|---------|----------------------------------| +|`QK_LAYER_LOCK`|`QK_LLCK`|Locks or unlocks the highest layer| + ## Layer Switching {#layer-switching} See also: [Layer Switching](feature_layers#switching-and-toggling-layers) diff --git a/quantum/keyboard.c b/quantum/keyboard.c index df1dc1c3ee..8db81a4b39 100644 --- a/quantum/keyboard.c +++ b/quantum/keyboard.c @@ -140,6 +140,9 @@ along with this program. If not, see . #ifdef OS_DETECTION_ENABLE # include "os_detection.h" #endif +#if defined(LAYER_LOCK_ENABLE) && LAYER_LOCK_IDLE_TIMEOUT > 0 +# include "layer_lock.h" +#endif // LAYER_LOCK_ENABLE static uint32_t last_input_modification_time = 0; uint32_t last_input_activity_time(void) { @@ -655,6 +658,10 @@ void quantum_task(void) { #ifdef SECURE_ENABLE secure_task(); #endif + +#if defined(LAYER_LOCK_ENABLE) && LAYER_LOCK_IDLE_TIMEOUT > 0 + layer_lock_task(); +#endif } /** \brief Main task that is repeatedly called as fast as possible. */ diff --git a/quantum/keycodes.h b/quantum/keycodes.h index 51b7eb6c9a..e9da5105ce 100644 --- a/quantum/keycodes.h +++ b/quantum/keycodes.h @@ -759,6 +759,7 @@ enum qk_keycode_defines { QK_TRI_LAYER_UPPER = 0x7C78, QK_REPEAT_KEY = 0x7C79, QK_ALT_REPEAT_KEY = 0x7C7A, + QK_LAYER_LOCK = 0x7C7B, QK_KB_0 = 0x7E00, QK_KB_1 = 0x7E01, QK_KB_2 = 0x7E02, @@ -1445,6 +1446,7 @@ enum qk_keycode_defines { TL_UPPR = QK_TRI_LAYER_UPPER, QK_REP = QK_REPEAT_KEY, QK_AREP = QK_ALT_REPEAT_KEY, + QK_LLCK = QK_LAYER_LOCK, }; // Range Helpers @@ -1501,7 +1503,7 @@ enum qk_keycode_defines { #define IS_UNDERGLOW_KEYCODE(code) ((code) >= QK_UNDERGLOW_TOGGLE && (code) <= QK_UNDERGLOW_SPEED_DOWN) #define IS_RGB_KEYCODE(code) ((code) >= RGB_MODE_PLAIN && (code) <= RGB_MODE_TWINKLE) #define IS_RGB_MATRIX_KEYCODE(code) ((code) >= QK_RGB_MATRIX_ON && (code) <= QK_RGB_MATRIX_SPEED_DOWN) -#define IS_QUANTUM_KEYCODE(code) ((code) >= QK_BOOTLOADER && (code) <= QK_ALT_REPEAT_KEY) +#define IS_QUANTUM_KEYCODE(code) ((code) >= QK_BOOTLOADER && (code) <= QK_LAYER_LOCK) #define IS_KB_KEYCODE(code) ((code) >= QK_KB_0 && (code) <= QK_KB_31) #define IS_USER_KEYCODE(code) ((code) >= QK_USER_0 && (code) <= QK_USER_31) @@ -1527,6 +1529,6 @@ enum qk_keycode_defines { #define UNDERGLOW_KEYCODE_RANGE QK_UNDERGLOW_TOGGLE ... QK_UNDERGLOW_SPEED_DOWN #define RGB_KEYCODE_RANGE RGB_MODE_PLAIN ... RGB_MODE_TWINKLE #define RGB_MATRIX_KEYCODE_RANGE QK_RGB_MATRIX_ON ... QK_RGB_MATRIX_SPEED_DOWN -#define QUANTUM_KEYCODE_RANGE QK_BOOTLOADER ... QK_ALT_REPEAT_KEY +#define QUANTUM_KEYCODE_RANGE QK_BOOTLOADER ... QK_LAYER_LOCK #define KB_KEYCODE_RANGE QK_KB_0 ... QK_KB_31 #define USER_KEYCODE_RANGE QK_USER_0 ... QK_USER_31 diff --git a/quantum/layer_lock.c b/quantum/layer_lock.c new file mode 100644 index 0000000000..9ee3c307dc --- /dev/null +++ b/quantum/layer_lock.c @@ -0,0 +1,81 @@ +// Copyright 2022-2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +#include "layer_lock.h" +#include "quantum_keycodes.h" + +#ifndef NO_ACTION_LAYER +// The current lock state. The kth bit is on if layer k is locked. +layer_state_t locked_layers = 0; + +// Layer Lock timer to disable layer lock after X seconds inactivity +# if defined(LAYER_LOCK_IDLE_TIMEOUT) && LAYER_LOCK_IDLE_TIMEOUT > 0 +uint32_t layer_lock_timer = 0; + +void layer_lock_task(void) { + if (locked_layers && timer_elapsed32(layer_lock_timer) > LAYER_LOCK_IDLE_TIMEOUT) { + layer_lock_all_off(); + layer_lock_timer = timer_read32(); + } +} +# endif // LAYER_LOCK_IDLE_TIMEOUT > 0 + +bool is_layer_locked(uint8_t layer) { + return locked_layers & ((layer_state_t)1 << layer); +} + +void layer_lock_invert(uint8_t layer) { + const layer_state_t mask = (layer_state_t)1 << layer; + if ((locked_layers & mask) == 0) { // Layer is being locked. +# ifndef NO_ACTION_ONESHOT + if (layer == get_oneshot_layer()) { + reset_oneshot_layer(); // Reset so that OSL doesn't turn layer off. + } +# endif // NO_ACTION_ONESHOT + layer_on(layer); +# if defined(LAYER_LOCK_IDLE_TIMEOUT) && LAYER_LOCK_IDLE_TIMEOUT > 0 + layer_lock_timer = timer_read32(); +# endif // LAYER_LOCK_IDLE_TIMEOUT > 0 + } else { // Layer is being unlocked. + layer_off(layer); + } + layer_lock_set_kb(locked_layers ^= mask); +} + +// Implement layer_lock_on/off by deferring to layer_lock_invert. +void layer_lock_on(uint8_t layer) { + if (!is_layer_locked(layer)) { + layer_lock_invert(layer); + } +} + +void layer_lock_off(uint8_t layer) { + if (is_layer_locked(layer)) { + layer_lock_invert(layer); + } +} + +void layer_lock_all_off(void) { + layer_and(~locked_layers); + locked_layers = 0; + layer_lock_set_kb(locked_layers); +} + +__attribute__((weak)) bool layer_lock_set_kb(layer_state_t locked_layers) { + return layer_lock_set_user(locked_layers); +} +__attribute__((weak)) bool layer_lock_set_user(layer_state_t locked_layers) { + return true; +} +#endif // NO_ACTION_LAYER diff --git a/quantum/layer_lock.h b/quantum/layer_lock.h new file mode 100644 index 0000000000..6d7285da2a --- /dev/null +++ b/quantum/layer_lock.h @@ -0,0 +1,135 @@ +// Copyright 2022-2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +/** + * @file layer_lock.h + * @brief Layer Lock, a key to stay in the current layer. + * + * Overview + * -------- + * + * Layers are often accessed by holding a button, e.g. with a momentary layer + * switch `MO(layer)` or layer tap `LT(layer, key)` key. But you may sometimes + * want to "lock" or "toggle" the layer so that it stays on without having to + * hold down a button. One way to do that is with a tap-toggle `TT` layer key, + * but here is an alternative. + * + * This library implements a "Layer Lock key". When tapped, it "locks" the + * highest layer to stay active, assuming the layer was activated by one of the + * following keys: + * + * * `MO(layer)` momentary layer switch + * * `LT(layer, key)` layer tap + * * `OSL(layer)` one-shot layer + * * `TT(layer)` layer tap toggle + * * `LM(layer, mod)` layer-mod key (the layer is locked, but not the mods) + * + * Tapping the Layer Lock key again unlocks and turns off the layer. + * + * @note When a layer is "locked", other layer keys such as `TO(layer)` or + * manually calling `layer_off(layer)` will override and unlock the layer. + * + * Configuration + * ------------- + * + * Optionally, a timeout may be defined so that Layer Lock disables + * automatically if not keys are pressed for `LAYER_LOCK_IDLE_TIMEOUT` + * milliseconds. Define `LAYER_LOCK_IDLE_TIMEOUT` in your config.h, for instance + * + * #define LAYER_LOCK_IDLE_TIMEOUT 60000 // Turn off after 60 seconds. + * + * and call `layer_lock_task()` from your `matrix_scan_user()` in keymap.c: + * + * void matrix_scan_user(void) { + * layer_lock_task(); + * // Other tasks... + * } + * + * For full documentation, see + * + */ + +#pragma once + +#include +#include +#include "action_layer.h" +#include "action_util.h" + +/** + * Handler function for Layer Lock. + * + * In your keymap, define a custom keycode to use for Layer Lock. Then handle + * Layer Lock from your `process_record_user` function by calling + * `process_layer_lock`, passing your custom keycode for the `lock_keycode` arg: + * + * #include "features/layer_lock.h" + * + * bool process_record_user(uint16_t keycode, keyrecord_t* record) { + * if (!process_layer_lock(keycode, record, LLOCK)) { return false; } + * // Your macros ... + * + * return true; + * } + */ + +#ifndef NO_ACTION_LAYER +/** Returns true if `layer` is currently locked. */ +bool is_layer_locked(uint8_t layer); + +/** Locks and turns on `layer`. */ +void layer_lock_on(uint8_t layer); + +/** Unlocks and turns off `layer`. */ +void layer_lock_off(uint8_t layer); + +/** Unlocks and turns off all locked layers. */ +void layer_lock_all_off(void); + +/** Toggles whether `layer` is locked. */ +void layer_lock_invert(uint8_t layer); + +/** + * Optional callback that gets called when a layer is locked or unlocked. + * + * This is useful to represent the current lock state, e.g. by setting an LED or + * playing a sound. In your keymap, define + * + * void layer_lock_set_user(layer_state_t locked_layers) { + * // Do something like `set_led(is_layer_locked(NAV));` + * } + * + * @param locked_layers Bitfield in which the kth bit represents whether the + * kth layer is on. + */ +bool layer_lock_set_kb(layer_state_t locked_layers); +bool layer_lock_set_user(layer_state_t locked_layers); + +void layer_lock_task(void); +#else // NO_ACTION_LAYER +static inline bool is_layer_locked(uint8_t layer) { + return false; +} +static inline void layer_lock_on(uint8_t layer) {} +static inline void layer_lock_off(uint8_t layer) {} +static inline void layer_lock_all_off(void) {} +static inline void layer_lock_invert(uint8_t layer) {} +static inline bool layer_lock_set_kb(layer_state_t locked_layers) { + return true; +} +static inline bool layer_lock_set_user(layer_state_t locked_layers) { + return true; +} +static inline void layer_lock_task(void) {} +#endif // NO_ACTION_LAYER diff --git a/quantum/process_keycode/process_layer_lock.c b/quantum/process_keycode/process_layer_lock.c new file mode 100644 index 0000000000..1e36d8844e --- /dev/null +++ b/quantum/process_keycode/process_layer_lock.c @@ -0,0 +1,95 @@ +// Copyright 2022-2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +/** + * @file layer_lock.c + * @brief Layer Lock implementation + * + * For full documentation, see + * + */ + +#include "layer_lock.h" +#include "process_layer_lock.h" +#include "quantum_keycodes.h" +#include "action_util.h" + +// The current lock state. The kth bit is on if layer k is locked. +extern layer_state_t locked_layers; +#if defined(LAYER_LOCK_IDLE_TIMEOUT) && LAYER_LOCK_IDLE_TIMEOUT > 0 +extern uint32_t layer_lock_timer; +#endif + +// Handles an event on an `MO` or `TT` layer switch key. +static bool handle_mo_or_tt(uint8_t layer, keyrecord_t* record) { + if (is_layer_locked(layer)) { + if (record->event.pressed) { // On press, unlock the layer. + layer_lock_invert(layer); + } + return false; // Skip default handling. + } + return true; +} + +bool process_layer_lock(uint16_t keycode, keyrecord_t* record) { +#ifndef NO_ACTION_LAYER +# if defined(LAYER_LOCK_IDLE_TIMEOUT) && LAYER_LOCK_IDLE_TIMEOUT > 0 + layer_lock_timer = timer_read32(); +# endif // LAYER_LOCK_IDLE_TIMEOUT > 0 + + // The intention is that locked layers remain on. If something outside of + // this feature turned any locked layers off, unlock them. + if ((locked_layers & ~layer_state) != 0) { + layer_lock_set_kb(locked_layers &= layer_state); + } + + if (keycode == QK_LAYER_LOCK) { + if (record->event.pressed) { // The layer lock key was pressed. + layer_lock_invert(get_highest_layer(layer_state)); + } + return false; + } + + switch (keycode) { + case QK_MOMENTARY ... QK_MOMENTARY_MAX: // `MO(layer)` keys. + return handle_mo_or_tt(QK_MOMENTARY_GET_LAYER(keycode), record); + + case QK_LAYER_TAP_TOGGLE ... QK_LAYER_TAP_TOGGLE_MAX: // `TT(layer)`. + return handle_mo_or_tt(QK_LAYER_TAP_TOGGLE_GET_LAYER(keycode), record); + + case QK_LAYER_MOD ... QK_LAYER_MOD_MAX: { // `LM(layer, mod)`. + uint8_t layer = QK_LAYER_MOD_GET_LAYER(keycode); + if (is_layer_locked(layer)) { + if (record->event.pressed) { // On press, unlock the layer. + layer_lock_invert(layer); + } else { // On release, clear the mods. + clear_mods(); + send_keyboard_report(); + } + return false; // Skip default handling. + } + } break; + +# ifndef NO_ACTION_TAPPING + case QK_LAYER_TAP ... QK_LAYER_TAP_MAX: // `LT(layer, key)` keys. + if (record->tap.count == 0 && !record->event.pressed && is_layer_locked(QK_LAYER_TAP_GET_LAYER(keycode))) { + // Release event on a held layer-tap key where the layer is locked. + return false; // Skip default handling so that layer stays on. + } + break; +# endif // NO_ACTION_TAPPING + } +#endif // NO_ACTION_LAYER + return true; +} diff --git a/quantum/process_keycode/process_layer_lock.h b/quantum/process_keycode/process_layer_lock.h new file mode 100644 index 0000000000..b54c0f6f10 --- /dev/null +++ b/quantum/process_keycode/process_layer_lock.h @@ -0,0 +1,69 @@ +// Copyright 2022-2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +/** + * @file layer_lock.h + * @brief Layer Lock, a key to stay in the current layer. + * + * Overview + * -------- + * + * Layers are often accessed by holding a button, e.g. with a momentary layer + * switch `MO(layer)` or layer tap `LT(layer, key)` key. But you may sometimes + * want to "lock" or "toggle" the layer so that it stays on without having to + * hold down a button. One way to do that is with a tap-toggle `TT` layer key, + * but here is an alternative. + * + * This library implements a "Layer Lock key". When tapped, it "locks" the + * highest layer to stay active, assuming the layer was activated by one of the + * following keys: + * + * * `MO(layer)` momentary layer switch + * * `LT(layer, key)` layer tap + * * `OSL(layer)` one-shot layer + * * `TT(layer)` layer tap toggle + * * `LM(layer, mod)` layer-mod key (the layer is locked, but not the mods) + * + * Tapping the Layer Lock key again unlocks and turns off the layer. + * + * @note When a layer is "locked", other layer keys such as `TO(layer)` or + * manually calling `layer_off(layer)` will override and unlock the layer. + * + * Configuration + * ------------- + * + * Optionally, a timeout may be defined so that Layer Lock disables + * automatically if not keys are pressed for `LAYER_LOCK_IDLE_TIMEOUT` + * milliseconds. Define `LAYER_LOCK_IDLE_TIMEOUT` in your config.h, for instance + * + * #define LAYER_LOCK_IDLE_TIMEOUT 60000 // Turn off after 60 seconds. + * + * and call `layer_lock_task()` from your `matrix_scan_user()` in keymap.c: + * + * void matrix_scan_user(void) { + * layer_lock_task(); + * // Other tasks... + * } + * + * For full documentation, see + * + */ + +#pragma once + +#include +#include +#include "action.h" + +bool process_layer_lock(uint16_t keycode, keyrecord_t* record); diff --git a/quantum/quantum.c b/quantum/quantum.c index 874df1593a..811ad2e715 100644 --- a/quantum/quantum.c +++ b/quantum/quantum.c @@ -76,6 +76,10 @@ # include "process_unicode_common.h" #endif +#ifdef LAYER_LOCK_ENABLE +# include "process_layer_lock.h" +#endif // LAYER_LOCK_ENABLE + #ifdef AUDIO_ENABLE # ifndef GOODBYE_SONG # define GOODBYE_SONG SONG(GOODBYE_SOUND) @@ -400,6 +404,9 @@ bool process_record_quantum(keyrecord_t *record) { #ifdef TRI_LAYER_ENABLE process_tri_layer(keycode, record) && #endif +#ifdef LAYER_LOCK_ENABLE + process_layer_lock(keycode, record) && +#endif #ifdef BLUETOOTH_ENABLE process_connection(keycode, record) && #endif diff --git a/quantum/quantum.h b/quantum/quantum.h index b60d8a86bf..71cf900f2d 100644 --- a/quantum/quantum.h +++ b/quantum/quantum.h @@ -240,6 +240,10 @@ extern layer_state_t layer_state; # include "os_detection.h" #endif +#ifdef LAYER_LOCK_ENABLE +# include "layer_lock.h" +#endif // LAYER_LOCK_ENABLE + void set_single_default_layer(uint8_t default_layer); void set_single_persistent_default_layer(uint8_t default_layer); diff --git a/tests/layer_lock/config.h b/tests/layer_lock/config.h new file mode 100644 index 0000000000..25d0b20c0e --- /dev/null +++ b/tests/layer_lock/config.h @@ -0,0 +1,8 @@ +// Copyright 2021 Christopher Courtney, aka Drashna Jael're (@drashna) +// SPDX-License-Identifier: GPL-2.0-or-later + +#pragma once + +#include "test_common.h" + +#define LAYER_LOCK_IDLE_TIMEOUT 1000 diff --git a/tests/layer_lock/test.mk b/tests/layer_lock/test.mk new file mode 100644 index 0000000000..05771e4dbf --- /dev/null +++ b/tests/layer_lock/test.mk @@ -0,0 +1,8 @@ +# Copyright 2021 Christopher Courtney, aka Drashna Jael're (@drashna) +# SPDX-License-Identifier: GPL-2.0-or-later + +# -------------------------------------------------------------------------------- +# Keep this file, even if it is empty, as a marker that this folder contains tests +# -------------------------------------------------------------------------------- + +LAYER_LOCK_ENABLE = yes diff --git a/tests/layer_lock/test_layer_lock.cpp b/tests/layer_lock/test_layer_lock.cpp new file mode 100644 index 0000000000..00742c3b43 --- /dev/null +++ b/tests/layer_lock/test_layer_lock.cpp @@ -0,0 +1,284 @@ +// Copyright 2021 Christopher Courtney, aka Drashna Jael're (@drashna) +// SPDX-License-Identifier: GPL-2.0-or-later + +#include "keycodes.h" +#include "test_common.hpp" + +using testing::_; + +class LayerLock : public TestFixture {}; + +TEST_F(LayerLock, LayerLockState) { + TestDriver driver; + KeymapKey key_a = KeymapKey(0, 0, 0, KC_A); + KeymapKey key_b = KeymapKey(1, 0, 0, KC_B); + KeymapKey key_c = KeymapKey(2, 0, 0, KC_C); + KeymapKey key_d = KeymapKey(3, 0, 0, KC_C); + + set_keymap({key_a, key_b, key_c, key_d}); + + EXPECT_FALSE(is_layer_locked(1)); + EXPECT_FALSE(is_layer_locked(2)); + EXPECT_FALSE(is_layer_locked(3)); + + layer_lock_invert(1); // Layer 1: unlocked -> locked + layer_lock_on(2); // Layer 2: unlocked -> locked + layer_lock_off(3); // Layer 3: stays unlocked + + // Layers 1 and 2 are now on. + EXPECT_TRUE(layer_state_is(1)); + EXPECT_TRUE(layer_state_is(2)); + // Layers 1 and 2 are now locked. + EXPECT_TRUE(is_layer_locked(1)); + EXPECT_TRUE(is_layer_locked(2)); + EXPECT_FALSE(is_layer_locked(3)); + + layer_lock_invert(1); // Layer 1: locked -> unlocked + layer_lock_on(2); // Layer 2: stays locked + layer_lock_on(3); // Layer 3: unlocked -> locked + + EXPECT_FALSE(layer_state_is(1)); + EXPECT_TRUE(layer_state_is(2)); + EXPECT_TRUE(layer_state_is(3)); + EXPECT_FALSE(is_layer_locked(1)); + EXPECT_TRUE(is_layer_locked(2)); + EXPECT_TRUE(is_layer_locked(3)); + + layer_lock_invert(1); // Layer 1: unlocked -> locked + layer_lock_off(2); // Layer 2: locked -> unlocked + + EXPECT_TRUE(layer_state_is(1)); + EXPECT_FALSE(layer_state_is(2)); + EXPECT_TRUE(layer_state_is(3)); + EXPECT_TRUE(is_layer_locked(1)); + EXPECT_FALSE(is_layer_locked(2)); + EXPECT_TRUE(is_layer_locked(3)); + + layer_lock_all_off(); // Layers 1 and 3: locked -> unlocked + + EXPECT_FALSE(layer_state_is(1)); + EXPECT_FALSE(layer_state_is(2)); + EXPECT_FALSE(layer_state_is(3)); + EXPECT_FALSE(is_layer_locked(1)); + EXPECT_FALSE(is_layer_locked(2)); + EXPECT_FALSE(is_layer_locked(3)); +} + +TEST_F(LayerLock, LayerLockMomentaryTest) { + TestDriver driver; + KeymapKey key_layer = KeymapKey(0, 0, 0, MO(1)); + KeymapKey key_a = KeymapKey(0, 1, 0, KC_A); + KeymapKey key_trns = KeymapKey(1, 0, 0, KC_TRNS); + KeymapKey key_ll = KeymapKey(1, 1, 0, QK_LAYER_LOCK); + + set_keymap({key_layer, key_a, key_trns, key_ll}); + + EXPECT_NO_REPORT(driver); + key_layer.press(); + run_one_scan_loop(); + EXPECT_TRUE(layer_state_is(1)); + EXPECT_FALSE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); + + EXPECT_NO_REPORT(driver); + tap_key(key_ll); + EXPECT_TRUE(layer_state_is(1)); + EXPECT_TRUE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); + + EXPECT_NO_REPORT(driver); + key_layer.release(); + run_one_scan_loop(); + EXPECT_TRUE(layer_state_is(1)); + EXPECT_TRUE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); + + // Pressing Layer Lock again unlocks the lock. + EXPECT_NO_REPORT(driver); + key_ll.press(); + run_one_scan_loop(); + EXPECT_FALSE(layer_state_is(1)); + EXPECT_FALSE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); +} + +TEST_F(LayerLock, LayerLockLayerTapTest) { + TestDriver driver; + KeymapKey key_layer = KeymapKey(0, 0, 0, LT(1, KC_B)); + KeymapKey key_a = KeymapKey(0, 1, 0, KC_A); + KeymapKey key_trns = KeymapKey(1, 0, 0, KC_TRNS); + KeymapKey key_ll = KeymapKey(1, 1, 0, QK_LAYER_LOCK); + + set_keymap({key_layer, key_a, key_trns, key_ll}); + + EXPECT_NO_REPORT(driver); + key_layer.press(); + idle_for(TAPPING_TERM); + run_one_scan_loop(); + EXPECT_TRUE(layer_state_is(1)); + VERIFY_AND_CLEAR(driver); + + EXPECT_NO_REPORT(driver); + tap_key(key_ll); + EXPECT_TRUE(layer_state_is(1)); + EXPECT_TRUE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); + + // Pressing Layer Lock again unlocks the lock. + EXPECT_NO_REPORT(driver); + key_ll.press(); + run_one_scan_loop(); + EXPECT_FALSE(layer_state_is(1)); + EXPECT_FALSE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); +} + +TEST_F(LayerLock, LayerLockOneshotTapTest) { + TestDriver driver; + KeymapKey key_layer = KeymapKey(0, 0, 0, OSL(1)); + KeymapKey key_a = KeymapKey(0, 1, 0, KC_A); + KeymapKey key_trns = KeymapKey(1, 0, 0, KC_TRNS); + KeymapKey key_ll = KeymapKey(1, 1, 0, QK_LAYER_LOCK); + + set_keymap({key_layer, key_a, key_trns, key_ll}); + + EXPECT_NO_REPORT(driver); + tap_key(key_layer); + run_one_scan_loop(); + EXPECT_TRUE(layer_state_is(1)); + VERIFY_AND_CLEAR(driver); + + EXPECT_NO_REPORT(driver); + tap_key(key_ll); + run_one_scan_loop(); + EXPECT_TRUE(layer_state_is(1)); + EXPECT_TRUE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); + + // Pressing Layer Lock again unlocks the lock. + EXPECT_NO_REPORT(driver); + key_ll.press(); + run_one_scan_loop(); + EXPECT_FALSE(layer_state_is(1)); + EXPECT_FALSE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); +} + +TEST_F(LayerLock, LayerLockOneshotHoldTest) { + TestDriver driver; + KeymapKey key_layer = KeymapKey(0, 0, 0, OSL(1)); + KeymapKey key_a = KeymapKey(0, 1, 0, KC_A); + KeymapKey key_trns = KeymapKey(1, 0, 0, KC_TRNS); + KeymapKey key_ll = KeymapKey(1, 1, 0, QK_LAYER_LOCK); + + set_keymap({key_layer, key_a, key_trns, key_ll}); + + EXPECT_NO_REPORT(driver); + key_layer.press(); + idle_for(TAPPING_TERM); + run_one_scan_loop(); + EXPECT_TRUE(layer_state_is(1)); + VERIFY_AND_CLEAR(driver); + + EXPECT_NO_REPORT(driver); + tap_key(key_ll); + run_one_scan_loop(); + EXPECT_TRUE(layer_state_is(1)); + VERIFY_AND_CLEAR(driver); + + EXPECT_NO_REPORT(driver); + key_layer.release(); + run_one_scan_loop(); + EXPECT_TRUE(layer_state_is(1)); + EXPECT_TRUE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); + + // Pressing Layer Lock again unlocks the lock. + EXPECT_NO_REPORT(driver); + key_ll.press(); + run_one_scan_loop(); + EXPECT_FALSE(layer_state_is(1)); + EXPECT_FALSE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); +} + +TEST_F(LayerLock, LayerLockTimeoutTest) { + TestDriver driver; + KeymapKey key_layer = KeymapKey(0, 0, 0, MO(1)); + KeymapKey key_a = KeymapKey(0, 1, 0, KC_A); + KeymapKey key_trns = KeymapKey(1, 0, 0, KC_TRNS); + KeymapKey key_ll = KeymapKey(1, 1, 0, QK_LAYER_LOCK); + + set_keymap({key_layer, key_a, key_trns, key_ll}); + + EXPECT_NO_REPORT(driver); + key_layer.press(); + run_one_scan_loop(); + EXPECT_TRUE(layer_state_is(1)); + VERIFY_AND_CLEAR(driver); + + EXPECT_NO_REPORT(driver); + tap_key(key_ll); + EXPECT_TRUE(layer_state_is(1)); + VERIFY_AND_CLEAR(driver); + + EXPECT_NO_REPORT(driver); + key_layer.release(); + run_one_scan_loop(); + EXPECT_TRUE(layer_state_is(1)); + EXPECT_TRUE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); + + EXPECT_NO_REPORT(driver); + idle_for(LAYER_LOCK_IDLE_TIMEOUT); + run_one_scan_loop(); + EXPECT_FALSE(layer_state_is(1)); + EXPECT_FALSE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); +} + +TEST_F(LayerLock, ToKeyOverridesLayerLock) { + TestDriver driver; + KeymapKey key_layer = KeymapKey(0, 0, 0, MO(1)); + KeymapKey key_to0 = KeymapKey(1, 0, 0, TO(0)); + KeymapKey key_ll = KeymapKey(1, 1, 0, QK_LAYER_LOCK); + + set_keymap({key_layer, key_to0, key_ll}); + + EXPECT_NO_REPORT(driver); + layer_lock_on(1); + run_one_scan_loop(); + EXPECT_TRUE(layer_state_is(1)); + EXPECT_TRUE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); + + EXPECT_NO_REPORT(driver); + tap_key(key_to0); // TO(0) overrides Layer Lock and unlocks layer 1. + EXPECT_FALSE(layer_state_is(1)); + EXPECT_FALSE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); +} + +TEST_F(LayerLock, LayerClearOverridesLayerLock) { + TestDriver driver; + KeymapKey key_layer = KeymapKey(0, 0, 0, MO(1)); + KeymapKey key_a = KeymapKey(0, 1, 0, KC_A); + KeymapKey key_ll = KeymapKey(1, 1, 0, QK_LAYER_LOCK); + + set_keymap({key_layer, key_a, key_ll}); + + EXPECT_NO_REPORT(driver); + layer_lock_on(1); + run_one_scan_loop(); + EXPECT_TRUE(layer_state_is(1)); + EXPECT_TRUE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); + + EXPECT_REPORT(driver, (KC_A)); + layer_clear(); // layer_clear() overrides Layer Lock and unlocks layer 1. + key_a.press(); + run_one_scan_loop(); + EXPECT_FALSE(layer_state_is(1)); + EXPECT_FALSE(is_layer_locked(1)); + VERIFY_AND_CLEAR(driver); +} diff --git a/tests/test_common/keycode_table.cpp b/tests/test_common/keycode_table.cpp index a520dd3f2b..ae1a9edcd0 100644 --- a/tests/test_common/keycode_table.cpp +++ b/tests/test_common/keycode_table.cpp @@ -699,6 +699,7 @@ std::map KEYCODE_ID_TABLE = { {QK_TRI_LAYER_UPPER, "QK_TRI_LAYER_UPPER"}, {QK_REPEAT_KEY, "QK_REPEAT_KEY"}, {QK_ALT_REPEAT_KEY, "QK_ALT_REPEAT_KEY"}, + {QK_LAYER_LOCK, "QK_LAYER_LOCK"}, {QK_KB_0, "QK_KB_0"}, {QK_KB_1, "QK_KB_1"}, {QK_KB_2, "QK_KB_2"}, -- cgit v1.2.3