(feature) Add &to keycode/behavior (#489)

feat(behaviors): Add `&to` behavior to switch to a layer.

app/CMakeLists.txt

@@ -47,6 +47,7 @@ if ((NOT CONFIG_ZMK_SPLIT) OR CONFIG_ZMK_SPLIT_BLE_ROLE_CENTRAL)
   target_sources(app PRIVATE src/behaviors/behavior_momentary_layer.c)
   target_sources(app PRIVATE src/behaviors/behavior_outputs.c)
   target_sources(app PRIVATE src/behaviors/behavior_toggle_layer.c)
+  target_sources(app PRIVATE src/behaviors/behavior_to_layer.c)
   target_sources(app PRIVATE src/behaviors/behavior_transparent.c)
   target_sources(app PRIVATE src/behaviors/behavior_none.c)
   target_sources(app PRIVATE src/behaviors/behavior_sensor_rotate_key_press.c)

app/dts/behaviors.dtsi

@@ -6,6 +6,7 @@
 #include <behaviors/sticky_key.dtsi>
 #include <behaviors/momentary_layer.dtsi>
 #include <behaviors/toggle_layer.dtsi>
+#include <behaviors/to_layer.dtsi>
 #include <behaviors/reset.dtsi>
 #include <behaviors/sensor_rotate_key_press.dtsi>
 #include <behaviors/rgb_underglow.dtsi>

app/dts/behaviors/to_layer.dtsi

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) 2020 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+/ {
+	behaviors {
+		to: behavior_to_layer {
+			compatible = "zmk,behavior-to-layer";
+			label = "TO_LAYER";
+			#binding-cells = <1>;
+		};
+	};
+};

app/dts/bindings/behaviors/zmk,behavior-to-layer.yaml

@@ -0,0 +1,8 @@
+# Copyright (c) 2020 The ZMK Contributors
+# SPDX-License-Identifier: MIT
+
+description: To Layer
+
+compatible: "zmk,behavior-to-layer"
+
+include: one_param.yaml

app/include/zmk/keymap.h

@@ -15,5 +15,6 @@ uint8_t zmk_keymap_highest_layer_active();
 int zmk_keymap_layer_activate(uint8_t layer);
 int zmk_keymap_layer_deactivate(uint8_t layer);
 int zmk_keymap_layer_toggle(uint8_t layer);
+int zmk_keymap_layer_to(uint8_t layer);
 
 int zmk_keymap_position_state_changed(uint32_t position, bool pressed, int64_t timestamp);

app/src/behaviors/behavior_to_layer.c

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2020 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#define DT_DRV_COMPAT zmk_behavior_to_layer
+
+#include <device.h>
+#include <drivers/behavior.h>
+#include <logging/log.h>
+
+#include <zmk/keymap.h>
+#include <zmk/behavior.h>
+
+LOG_MODULE_DECLARE(zmk, CONFIG_ZMK_LOG_LEVEL);
+
+static int behavior_to_init(const struct device *dev) { return 0; };
+
+static int to_keymap_binding_pressed(struct zmk_behavior_binding *binding,
+                                     struct zmk_behavior_binding_event event) {
+    LOG_DBG("position %d layer %d", event.position, binding->param1);
+    return zmk_keymap_layer_to(binding->param1);
+}
+
+static int to_keymap_binding_released(struct zmk_behavior_binding *binding,
+                                      struct zmk_behavior_binding_event event) {
+    LOG_DBG("position %d layer %d", event.position, binding->param1);
+    return 0;
+}
+
+static const struct behavior_driver_api behavior_to_driver_api = {
+    .binding_pressed = to_keymap_binding_pressed,
+    .binding_released = to_keymap_binding_released,
+};
+
+DEVICE_AND_API_INIT(behavior_to, DT_INST_LABEL(0), behavior_to_init, NULL, NULL, APPLICATION,
+                    CONFIG_KERNEL_INIT_PRIORITY_DEFAULT, &behavior_to_driver_api);

app/src/keymap.c

@@ -78,11 +78,23 @@ static struct zmk_behavior_binding zmk_sensor_keymap[ZMK_KEYMAP_LAYERS_LEN]
 #endif /* ZMK_KEYMAP_HAS_SENSORS */
 
 static inline int set_layer_state(uint8_t layer, bool state) {
-    if (layer >= 32) {
+    if (layer >= ZMK_KEYMAP_LAYERS_LEN) {
         return -EINVAL;
     }
+
+    // Default layer should *always* remain active
+    if (layer == _zmk_keymap_layer_default && !state) {
+        return 0;
+    }
+
+    zmk_keymap_layers_state_t old_state = _zmk_keymap_layer_state;
     WRITE_BIT(_zmk_keymap_layer_state, layer, state);
-    ZMK_EVENT_RAISE(create_layer_state_changed(layer, state));
+    // Don't send state changes unless there was an actual change
+    if (old_state != _zmk_keymap_layer_state) {
+        LOG_DBG("layer_changed: layer %d state %d", layer, state);
+        ZMK_EVENT_RAISE(create_layer_state_changed(layer, state));
+    }
+
     return 0;
 }
 
@@ -90,12 +102,18 @@ uint8_t zmk_keymap_layer_default() { return _zmk_keymap_layer_default; }
 
 zmk_keymap_layers_state_t zmk_keymap_layer_state() { return _zmk_keymap_layer_state; }
 
+bool zmk_keymap_layer_active_with_state(uint8_t layer, zmk_keymap_layers_state_t state_to_test) {
+    // The default layer is assumed to be ALWAYS ACTIVE so we include an || here to ensure nobody
+    // breaks up that assumption by accident
+    return (state_to_test & (BIT(layer))) == (BIT(layer)) || layer == _zmk_keymap_layer_default;
+};
+
 bool zmk_keymap_layer_active(uint8_t layer) {
-    return (_zmk_keymap_layer_state & (BIT(layer))) == (BIT(layer));
+    return zmk_keymap_layer_active_with_state(layer, _zmk_keymap_layer_state);
 };
 
 uint8_t zmk_keymap_highest_layer_active() {
-    for (uint8_t layer = 31; layer > 0; layer--) {
+    for (uint8_t layer = ZMK_KEYMAP_LAYERS_LEN - 1; layer > 0; layer--) {
         if (zmk_keymap_layer_active(layer)) {
             return layer;
         }
@@ -115,8 +133,14 @@ int zmk_keymap_layer_toggle(uint8_t layer) {
     return zmk_keymap_layer_activate(layer);
 };
 
-bool is_active_layer(uint8_t layer, zmk_keymap_layers_state_t layer_state) {
-    return (layer_state & BIT(layer)) == BIT(layer) || layer == _zmk_keymap_layer_default;
+int zmk_keymap_layer_to(uint8_t layer) {
+    for (int i = ZMK_KEYMAP_LAYERS_LEN - 1; i >= 0; i--) {
+        zmk_keymap_layer_deactivate(i);
+    }
+
+    zmk_keymap_layer_activate(layer);
+
+    return 0;
 }
 
 int zmk_keymap_apply_position_state(int layer, uint32_t position, bool pressed, int64_t timestamp) {
@@ -150,7 +174,7 @@ int zmk_keymap_position_state_changed(uint32_t position, bool pressed, int64_t t
         zmk_keymap_active_behavior_layer[position] = _zmk_keymap_layer_state;
     }
     for (int layer = ZMK_KEYMAP_LAYERS_LEN - 1; layer >= _zmk_keymap_layer_default; layer--) {
-        if (is_active_layer(layer, zmk_keymap_active_behavior_layer[position])) {
+        if (zmk_keymap_layer_active_with_state(layer, zmk_keymap_active_behavior_layer[position])) {
             int ret = zmk_keymap_apply_position_state(layer, position, pressed, timestamp);
             if (ret > 0) {
                 LOG_DBG("behavior processing to continue to next layer");
@@ -171,9 +195,7 @@ int zmk_keymap_position_state_changed(uint32_t position, bool pressed, int64_t t
 int zmk_keymap_sensor_triggered(uint8_t sensor_number, const struct device *sensor,
                                 int64_t timestamp) {
     for (int layer = ZMK_KEYMAP_LAYERS_LEN - 1; layer >= _zmk_keymap_layer_default; layer--) {
-        if (((_zmk_keymap_layer_state & BIT(layer)) == BIT(layer) ||
-             layer == _zmk_keymap_layer_default) &&
-            zmk_sensor_keymap[layer] != NULL) {
+        if (zmk_keymap_layer_active(layer) && zmk_sensor_keymap[layer] != NULL) {
             struct zmk_behavior_binding *binding = &zmk_sensor_keymap[layer][sensor_number];
             const struct device *behavior;
             int ret;

app/tests/to-layer/behavior_keymap.dtsi

@@ -0,0 +1,22 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan-mock.h>
+
+/ {
+	keymap {
+		compatible = "zmk,keymap";
+		label ="Default keymap";
+
+		default_layer {
+			bindings = <
+				&to 0  &to 1
+				&kp A &kp S>;
+		};
+
+		second_layer {
+			bindings = <
+				&to 0 &to 1
+				&kp J  &kp K>;
+		};
+	};
+};

app/tests/to-layer/normal/events.patterns

@@ -0,0 +1,3 @@
+s/.*hid_listener_keycode/kp/p
+s/.*to_keymap_binding/to/p
+s/.*layer_changed/layer_changed/p

app/tests/to-layer/normal/keycode_events.snapshot

@@ -0,0 +1,18 @@
+kp_pressed: usage_page 0x07 keycode 0x16 mods 0x00
+kp_released: usage_page 0x07 keycode 0x16 mods 0x00
+to_pressed: position 1 layer 1
+layer_changed: layer 1 state 1
+to_released: position 1 layer 1
+kp_pressed: usage_page 0x07 keycode 0x0e mods 0x00
+kp_released: usage_page 0x07 keycode 0x0e mods 0x00
+to_pressed: position 0 layer 0
+layer_changed: layer 1 state 0
+layer_changed: layer 0 state 1
+to_released: position 0 layer 0
+kp_pressed: usage_page 0x07 keycode 0x16 mods 0x00
+kp_released: usage_page 0x07 keycode 0x16 mods 0x00
+to_pressed: position 0 layer 0
+to_released: position 0 layer 0
+to_pressed: position 1 layer 1
+layer_changed: layer 1 state 1
+to_released: position 1 layer 1

app/tests/to-layer/normal/native_posix.keymap

@@ -0,0 +1,29 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan-mock.h>
+#include "../behavior_keymap.dtsi"
+
+// Press key A
+// To layer 1
+// Press key J
+// To layer 0
+// Press key S
+// To layer 0 -- does nothing
+
+&kscan {
+	events = <ZMK_MOCK_PRESS(1,1,10)
+			  ZMK_MOCK_RELEASE(1,1,10)
+			  ZMK_MOCK_PRESS(0,1,10)
+			  ZMK_MOCK_RELEASE(0,1,10)
+			  ZMK_MOCK_PRESS(1,1,10)
+			  ZMK_MOCK_RELEASE(1,1,10)
+			  ZMK_MOCK_PRESS(0,0,10)
+			  ZMK_MOCK_RELEASE(0,0,10)
+			  ZMK_MOCK_PRESS(1,1,10)
+			  ZMK_MOCK_RELEASE(1,1,10)
+			  ZMK_MOCK_PRESS(0,0,10)
+			  ZMK_MOCK_RELEASE(0,0,10)
+			  ZMK_MOCK_PRESS(0,1,10)
+			  ZMK_MOCK_RELEASE(0,1,10)
+			>;
+};

docs/docs/behaviors/layers.md

@@ -57,6 +57,21 @@ Example:
 &lt LOWER SPACE
 ```
 
+## To Layer
+
+The "to layer" behavior enables a layer and disables _all_ other layers _except_ the default layer.
+
+### Behavior Binding
+
+- Reference: `&to`
+- Parameter: The layer number to enable, e.g. `1`
+
+Example:
+
+```
+&to 3
+```
+
 ## Toggle Layer
 
 The "toggle layer" behavior enables a layer until the layer is manually disabled.