feat(behaviors): Add behavior metadata information.

* For upcoming ZMK studio work, make a set of rich metadata available to provide a friendly name for a behavior, and allow super flexible descriptions of the parameters the behaviors take. * Add ability to validate a zmk_behavior_binding against the behavior metadata available.
zmkfirmware · Jun 12, 2024 · e5b4818 · e5b4818
1 parent 308d6bc
commit e5b4818
Show file tree

Hide file tree

Showing 42 changed files with 982 additions and 14 deletions.
diff --git a/app/Kconfig.behaviors b/app/Kconfig.behaviors
@@ -1,6 +1,12 @@
 # Copyright (c) 2023 The ZMK Contributors
 # SPDX-License-Identifier: MIT
 
+config ZMK_BEHAVIOR_METADATA
+    bool "Metadata"
+    help
+      Enabling this option adds APIs for documenting and fetching
+      metadata describing a behaviors name, and supported parameters.
+
 config ZMK_BEHAVIOR_KEY_TOGGLE
     bool
     default y
@@ -35,4 +41,4 @@ config ZMK_BEHAVIOR_SENSOR_ROTATE_VAR
 config ZMK_BEHAVIOR_MACRO
     bool
     default y
-    depends on DT_HAS_ZMK_BEHAVIOR_MACRO_ENABLED || DT_HAS_ZMK_BEHAVIOR_MACRO_ONE_PARAM_ENABLED || DT_HAS_ZMK_BEHAVIOR_MACRO_TWO_PARAM_ENABLED
+    depends on DT_HAS_ZMK_BEHAVIOR_MACRO_ENABLED || DT_HAS_ZMK_BEHAVIOR_MACRO_ONE_PARAM_ENABLED || DT_HAS_ZMK_BEHAVIOR_MACRO_TWO_PARAM_ENABLED
diff --git a/app/dts/behaviors/backlight.dtsi b/app/dts/behaviors/backlight.dtsi
@@ -10,6 +10,7 @@
         /omit-if-no-ref/ bl: bcklight {
             compatible = "zmk,behavior-backlight";
             #binding-cells = <2>;
+            friendly-name = "Backlight";
         };
     };
 };
diff --git a/app/dts/behaviors/bluetooth.dtsi b/app/dts/behaviors/bluetooth.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ bt: bluetooth {
             compatible = "zmk,behavior-bluetooth";
             #binding-cells = <2>;
+            friendly-name = "Bluetooth";
         };
     };
 };
diff --git a/app/dts/behaviors/caps_word.dtsi b/app/dts/behaviors/caps_word.dtsi
@@ -12,6 +12,7 @@
             compatible = "zmk,behavior-caps-word";
             #binding-cells = <0>;
             continue-list = <UNDERSCORE BACKSPACE DELETE>;
+            friendly-name = "Caps Word";
         };
     };
 };

diff --git a/app/dts/behaviors/ext_power.dtsi b/app/dts/behaviors/ext_power.dtsi
@@ -10,6 +10,7 @@
         ext_power: extpower {
             compatible = "zmk,behavior-ext-power";
             #binding-cells = <1>;
+            friendly-name = "External Power";
         };
     };
 };
diff --git a/app/dts/behaviors/gresc.dtsi b/app/dts/behaviors/gresc.dtsi
@@ -13,6 +13,7 @@
             #binding-cells = <0>;
             bindings = <&kp ESC>, <&kp GRAVE>;
             mods = <(MOD_LGUI|MOD_LSFT|MOD_RGUI|MOD_RSFT)>;
+            friendly-name = "Grave/Escape";
         };
     };
 };
diff --git a/app/dts/behaviors/key_press.dtsi b/app/dts/behaviors/key_press.dtsi
@@ -10,6 +10,7 @@
         /omit-if-no-ref/ cp: kp: key_press {
             compatible = "zmk,behavior-key-press";
             #binding-cells = <1>;
+            friendly-name = "Key Press";
         };
     };
 };
diff --git a/app/dts/behaviors/key_repeat.dtsi b/app/dts/behaviors/key_repeat.dtsi
@@ -12,6 +12,7 @@
             compatible = "zmk,behavior-key-repeat";
             #binding-cells = <0>;
             usage-pages = <HID_USAGE_KEY>;
+            friendly-name = "Key Repeat";
         };
     };
 };

diff --git a/app/dts/behaviors/key_toggle.dtsi b/app/dts/behaviors/key_toggle.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ kt: key_toggle {
             compatible = "zmk,behavior-key-toggle";
             #binding-cells = <1>;
+            friendly-name = "Key Toggle";
         };
     };
 };
diff --git a/app/dts/behaviors/layer_tap.dtsi b/app/dts/behaviors/layer_tap.dtsi
@@ -12,6 +12,7 @@
             flavor = "tap-preferred";
             tapping-term-ms = <200>;
             bindings = <&mo>, <&kp>;
+            friendly-name = "Layer-Tap";
         };
     };
 };
diff --git a/app/dts/behaviors/mod_tap.dtsi b/app/dts/behaviors/mod_tap.dtsi
@@ -12,6 +12,7 @@
             flavor = "hold-preferred";
             tapping-term-ms = <200>;
             bindings = <&kp>, <&kp>;
+            friendly-name = "Mod-Tap";
         };
     };
 };
diff --git a/app/dts/behaviors/momentary_layer.dtsi b/app/dts/behaviors/momentary_layer.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ mo: momentary_layer {
             compatible = "zmk,behavior-momentary-layer";
             #binding-cells = <1>;
+            friendly-name = "Momentary Layer";
         };
     };
 };
diff --git a/app/dts/behaviors/none.dtsi b/app/dts/behaviors/none.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ none: none {
             compatible = "zmk,behavior-none";
             #binding-cells = <0>;
+            friendly-name = "None";
         };
     };
 };
diff --git a/app/dts/behaviors/outputs.dtsi b/app/dts/behaviors/outputs.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ out: outputs {
             compatible = "zmk,behavior-outputs";
             #binding-cells = <1>;
+            friendly-name = "Output Selection";
         };
     };
 };
diff --git a/app/dts/behaviors/reset.dtsi b/app/dts/behaviors/reset.dtsi
@@ -12,13 +12,15 @@
         sys_reset: sysreset {
             compatible = "zmk,behavior-reset";
             #binding-cells = <0>;
+            friendly-name = "Reset";
         };
 
         // Behavior can be invoked on peripherals, so name must be <= 8 characters.
         bootloader: bootload {
             compatible = "zmk,behavior-reset";
             type = <RST_UF2>;
             #binding-cells = <0>;
+            friendly-name = "Bootloader";
         };
     };
 };
diff --git a/app/dts/behaviors/rgb_underglow.dtsi b/app/dts/behaviors/rgb_underglow.dtsi
@@ -10,6 +10,7 @@
         rgb_ug: rgb_ug {
             compatible = "zmk,behavior-rgb-underglow";
             #binding-cells = <2>;
+            friendly-name = "Underglow";
         };
     };
 };
diff --git a/app/dts/behaviors/sticky_key.dtsi b/app/dts/behaviors/sticky_key.dtsi
@@ -12,13 +12,15 @@
             release-after-ms = <1000>;
             bindings = <&kp>;
             ignore-modifiers;
+            friendly-name = "Sticky Key";
         };
         /omit-if-no-ref/ sl: sticky_layer {
             compatible = "zmk,behavior-sticky-key";
             #binding-cells = <1>;
             release-after-ms = <1000>;
             bindings = <&mo>;
             quick-release;
+            friendly-name = "Sticky Layer";
         };
     };
 

diff --git a/app/dts/behaviors/to_layer.dtsi b/app/dts/behaviors/to_layer.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ to: to_layer {
             compatible = "zmk,behavior-to-layer";
             #binding-cells = <1>;
+            friendly-name = "To Layer";
         };
     };
 };
diff --git a/app/dts/behaviors/toggle_layer.dtsi b/app/dts/behaviors/toggle_layer.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ tog: toggle_layer {
             compatible = "zmk,behavior-toggle-layer";
             #binding-cells = <1>;
+            friendly-name = "Toggle Layer";
         };
     };
 };
diff --git a/app/dts/behaviors/transparent.dtsi b/app/dts/behaviors/transparent.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ trans: transparent {
             compatible = "zmk,behavior-transparent";
             #binding-cells = <0>;
+            friendly-name = "Transparent";
         };
     };
 };
diff --git a/app/dts/bindings/behaviors/behavior-metadata.yaml b/app/dts/bindings/behaviors/behavior-metadata.yaml
@@ -0,0 +1,6 @@
+# Copyright (c) 2024 The ZMK Contributors
+# SPDX-License-Identifier: MIT
+
+properties:
+  friendly-name:
+    type: string
diff --git a/app/dts/bindings/behaviors/one_param.yaml b/app/dts/bindings/behaviors/one_param.yaml
@@ -1,6 +1,8 @@
 # Copyright (c) 2020 The ZMK Contributors
 # SPDX-License-Identifier: MIT
 
+include: behavior-metadata.yaml
+
 properties:
   label:
     type: string

diff --git a/app/dts/bindings/behaviors/two_param.yaml b/app/dts/bindings/behaviors/two_param.yaml
@@ -1,6 +1,8 @@
 # Copyright (c) 2020 The ZMK Contributors
 # SPDX-License-Identifier: MIT
 
+include: behavior-metadata.yaml
+
 properties:
   label:
     type: string

diff --git a/app/dts/bindings/behaviors/zero_param.yaml b/app/dts/bindings/behaviors/zero_param.yaml
@@ -1,6 +1,8 @@
 # Copyright (c) 2020 The ZMK Contributors
 # SPDX-License-Identifier: MIT
 
+include: behavior-metadata.yaml
+
 properties:
   label:
     type: string