diff --git a/app/CMakeLists.txt b/app/CMakeLists.txt index 072d5672912..cc0b0b2bc44 100644 --- a/app/CMakeLists.txt +++ b/app/CMakeLists.txt @@ -55,6 +55,7 @@ if ((NOT CONFIG_ZMK_SPLIT) OR CONFIG_ZMK_SPLIT_ROLE_CENTRAL) target_sources_ifdef(CONFIG_ZMK_BEHAVIOR_MACRO app PRIVATE src/behaviors/behavior_macro.c) target_sources(app PRIVATE src/behaviors/behavior_momentary_layer.c) target_sources(app PRIVATE src/behaviors/behavior_mod_morph.c) + target_sources(app PRIVATE src/behaviors/behavior_antecedent_morph.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) diff --git a/app/dts/bindings/behaviors/zmk,behavior-antecedent-morph.yaml b/app/dts/bindings/behaviors/zmk,behavior-antecedent-morph.yaml new file mode 100644 index 00000000000..2e61b1af8bd --- /dev/null +++ b/app/dts/bindings/behaviors/zmk,behavior-antecedent-morph.yaml @@ -0,0 +1,23 @@ +# Copyright (c) 2023 The ZMK Contributors +# SPDX-License-Identifier: MIT + +description: Antecedent Morph Behavior + +compatible: "zmk,behavior-antecedent-morph" + +include: zero_param.yaml + +properties: + defaults: + type: phandle-array + required: true + specifier-space: binding + bindings: + type: phandle-array + required: true + antecedents: + type: array + required: true + max-delay-ms: + type: int + default: -1 diff --git a/app/src/behaviors/behavior_antecedent_morph.c b/app/src/behaviors/behavior_antecedent_morph.c new file mode 100644 index 00000000000..67e480a5ac7 --- /dev/null +++ b/app/src/behaviors/behavior_antecedent_morph.c @@ -0,0 +1,228 @@ +/* + * Copyright (c) 2023 The ZMK Contributors + * + * SPDX-License-Identifier: MIT + */ + +#define DT_DRV_COMPAT zmk_behavior_antecedent_morph + +#include +#include +#include +#include + +#include +#include +#include +#include + +LOG_MODULE_DECLARE(zmk, CONFIG_ZMK_LOG_LEVEL); + +#if DT_HAS_COMPAT_STATUS_OKAY(DT_DRV_COMPAT) + +// configuration struct per instance +struct behavior_antecedent_morph_config { + int serial; // serial number of the instance of this behavior + uint32_t max_delay_ms; // maximum delay between key release and successive key press for the adaptive behavior + size_t defaults_len; // length of the array of default behaviors (must be 1) + struct zmk_behavior_binding *defaults; // array of default behaviors + size_t bindings_len; // length of the array of morphed behaviors + struct zmk_behavior_binding *bindings; // array of morphed behaviors + int32_t antecedents_len; // length of the array of antecedents (key codes) + int32_t antecedents[]; // array of antecedents (key codes) +}; + +// data struct per instance +struct behavior_antecedent_morph_data { + struct zmk_behavior_binding *pressed_binding; // the actual behavior that was pressed by the adaptive behavior +}; + +// data shared by all instances +static int32_t code_pressed; // most recently pressed key code (with implicit mods, usage page and keycode) +static int64_t time_pressed; // time stamp in milli-seconds of that key press + +static int antecedent_morph_keycode_state_changed_listener(const zmk_event_t *eh); + +ZMK_LISTENER(behavior_antecedent_morph, antecedent_morph_keycode_state_changed_listener); +ZMK_SUBSCRIPTION(behavior_antecedent_morph,zmk_keycode_state_changed); + +// Capture all key press and release events in order to record the most recently released key code. +// +// Note that the event structure gives us the keycode (16 bit), the usage page (8 bit) and the implicit modifiers (8 +// bit), but not the explicit modifiers. If the keymap contains the binding "&kp RA(Y)", for example, then right-alt is +// an implicit modifier so that instead of the Y, the special character Ü is sent (US International layout). +// +// Whether the user is holding down a shift key at that moment, however, i.e. the explicit modifiers, is not known. We +// could reconstruct this information by tracking the press and release events of the modifier keys (keycodes higher +// than 0xe0) though, but in the present version, the potential antecedents are recorded without modifiers. +// +// We here record all key release events of non-modifier keys (keycodes less than 0xe0). +// +// If someone somewhere triggers a key down event with an illegal key code (beyond 0xff), this key code is recorded as a +// potential antecedent, but is then discarded. This way, it is possible to trigger 'silent antecedents', e.g. in order +// to create new dead keys. + +static int antecedent_morph_keycode_state_changed_listener(const zmk_event_t *eh) { + + struct zmk_keycode_state_changed *ev = as_zmk_keycode_state_changed(eh); + + int32_t code = ((ev->implicit_modifiers & 0xff) << 24) | ((ev->usage_page & 0xff) << 16) | (ev->keycode & 0xffff); + + LOG_DBG("%s keycode %d; page %d; implicit mods %d; explicit mods %d; key code 0x%08x",ev->state ? "down" : "up",ev->keycode,ev->usage_page,ev->implicit_modifiers,ev->explicit_modifiers,code); + if ((ev->state) && ((ev->keycode < 0xe0) || (ev->keycode > 0xff))) { + LOG_DBG("global variable changes from 0x%08x to 0x%08x",code_pressed,code); + code_pressed = code; + time_pressed = ev->timestamp; + } + + if (ev->keycode > 0xff) { + LOG_DBG("event dropped"); + return(ZMK_EV_EVENT_HANDLED); + } else { + return(ZMK_EV_EVENT_BUBBLE); + } +} + +// When an antecedent morph binding is pressed, we test whether the most recently released key code is among the +// configured antecedents and whether the corresponding key release event was no more than the configured delay time +// ago. + +static int on_antecedent_morph_binding_pressed(struct zmk_behavior_binding *binding, + struct zmk_behavior_binding_event event) { + const struct device *dev = zmk_behavior_get_binding(binding->behavior_dev); + const struct behavior_antecedent_morph_config *cfg = dev->config; + struct behavior_antecedent_morph_data *data = dev->data; + int morph = -1; + + LOG_DBG("press zmk,behavior-antecedent-morph serial no. %d when is 0x%08x; delay %dms; and explicit_mods 0x%02x", + cfg->serial,code_pressed,(int32_t)(event.timestamp-time_pressed),zmk_hid_get_explicit_mods()); + + if (data->pressed_binding != NULL) { + LOG_ERR("Can't press the same antecedent-morph twice"); + return -ENOTSUP; + } + + for (int i=0;iantecedents_len;i++) { + if (code_pressed == cfg->antecedents[i]) { + morph = i; + } + } + + if ((morph >= 0) && ((int32_t)(event.timestamp-time_pressed)) < cfg->max_delay_ms) { + + // If the the delay between the most recent key release and the pressing of the current behavior is less than the + // configured maximum delay and if the most recently released key is among the recorded antecedents, issue the + // behavior among the 'bindings' that is at the corresponding position to the antecedent among the 'antecedents'. + // + // Note that should one of the arrays 'bindings' or 'defaults' are too short, an error is triggered and the behavior + // never pressed. + + LOG_DBG("morph condition satisfied"); + + if (morph < cfg->bindings_len) { + data->pressed_binding = (struct zmk_behavior_binding *)&cfg->bindings[morph]; + } else { + LOG_ERR("Property 'bindings' must be an array at least of length %d.",morph+1); + return -ENOTSUP; + } + + } else { + + // Otherwise, issue the first behavior of the 'defaults' array. + + if (0 < cfg->defaults_len) { + data->pressed_binding = (struct zmk_behavior_binding *)&cfg->defaults[0]; + } else { + LOG_ERR("Property 'defaults' must be an array at least of length 1."); + return -ENOTSUP; + } + } + + return zmk_behavior_invoke_binding(data->pressed_binding,event,true); +} + +// The release of the antecedent morph behavior considers the behavior that was recorded in the instance data and +// releases it. + +static int on_antecedent_morph_binding_released(struct zmk_behavior_binding *binding, + struct zmk_behavior_binding_event event) { + const struct device *dev = zmk_behavior_get_binding(binding->behavior_dev); + const struct behavior_antecedent_morph_config *cfg = dev->config; + struct behavior_antecedent_morph_data *data = dev->data; + + if (data->pressed_binding == NULL) { + LOG_ERR("Antecedent-morph already released"); + return -ENOTSUP; + } + + LOG_DBG("release zmk,behavior-antecedent-morph serial no. %d",cfg->serial); + + struct zmk_behavior_binding *pressed_binding = data->pressed_binding; + data->pressed_binding = NULL; + return zmk_behavior_invoke_binding(pressed_binding,event,false); +} + +static const struct behavior_driver_api behavior_antecedent_morph_driver_api = { + .binding_pressed = on_antecedent_morph_binding_pressed, + .binding_released = on_antecedent_morph_binding_released, +}; + +static int behavior_antecedent_morph_init(const struct device *dev) { + + const struct behavior_antecedent_morph_config *cfg = dev->config; + struct behavior_antecedent_morph_data *data = dev->data; + + LOG_DBG("zmk,behavior-antecedent-morph serial no. %d defined with %d defaults, %d bindings and %d antecedents.",cfg->serial,cfg->defaults_len,cfg->bindings_len,cfg->antecedents_len); + for (int i=0; iantecedents_len;i++) { + LOG_DBG("antedecent no. %d is 0x%08x.",i,cfg->antecedents[i]); + } + + data->pressed_binding = NULL; + code_pressed = 0; + return 0; +} + +#define ZMK_KEYMAP_EXTRACT_DEFAULT(idx, drv_inst) \ + { \ + .behavior_dev = DEVICE_DT_NAME(DT_PHANDLE_BY_IDX(drv_inst, defaults, idx)), \ + .param1 = COND_CODE_0(DT_PHA_HAS_CELL_AT_IDX(drv_inst, defaults, idx, param1), (0), \ + (DT_PHA_BY_IDX(drv_inst, defaults, idx, param1))), \ + .param2 = COND_CODE_0(DT_PHA_HAS_CELL_AT_IDX(drv_inst, defaults, idx, param2), (0), \ + (DT_PHA_BY_IDX(drv_inst, defaults, idx, param2))), \ + } + +#define _TRANSFORM_ENTRY_DEFAULT(idx, node) ZMK_KEYMAP_EXTRACT_DEFAULT(idx, node) + +#define TRANSFORMED_DEFAULTS(node) \ + { LISTIFY(DT_INST_PROP_LEN(node, defaults), _TRANSFORM_ENTRY_DEFAULT, (, ), DT_DRV_INST(node)) } + +#define _TRANSFORM_ENTRY_BINDING(idx, node) ZMK_KEYMAP_EXTRACT_BINDING(idx, node) + +#define TRANSFORMED_BINDINGS(node) \ + { LISTIFY(DT_INST_PROP_LEN(node, bindings), _TRANSFORM_ENTRY_BINDING, (, ), DT_DRV_INST(node)) } + +#define KP_INST(n) \ + static struct zmk_behavior_binding behavior_antecedent_morph_config_##n##_defaults[DT_INST_PROP_LEN(n, defaults)] = \ + TRANSFORMED_DEFAULTS(n); \ + static struct zmk_behavior_binding behavior_antecedent_morph_config_##n##_bindings[DT_INST_PROP_LEN(n, bindings)] = \ + TRANSFORMED_BINDINGS(n); \ + static struct behavior_antecedent_morph_config behavior_antecedent_morph_config_##n = { \ + .serial = n, \ + .max_delay_ms = DT_INST_PROP(n, max_delay_ms), \ + .defaults = behavior_antecedent_morph_config_##n##_defaults, \ + .defaults_len = DT_INST_PROP_LEN(n, defaults), \ + .bindings = behavior_antecedent_morph_config_##n##_bindings, \ + .bindings_len = DT_INST_PROP_LEN(n, bindings), \ + .antecedents = DT_INST_PROP(n, antecedents), \ + .antecedents_len = DT_INST_PROP_LEN(n, antecedents) \ + }; \ + static struct behavior_antecedent_morph_data behavior_antecedent_morph_data_##n = { \ + }; \ + BEHAVIOR_DT_INST_DEFINE(n,behavior_antecedent_morph_init,NULL,&behavior_antecedent_morph_data_##n, \ + &behavior_antecedent_morph_config_##n, \ + POST_KERNEL, CONFIG_KERNEL_INIT_PRIORITY_DEFAULT, \ + &behavior_antecedent_morph_driver_api); + +DT_INST_FOREACH_STATUS_OKAY(KP_INST) + +#endif diff --git a/docs/docs/keymaps/behaviors/antecedent-morph.md b/docs/docs/keymaps/behaviors/antecedent-morph.md new file mode 100644 index 00000000000..8b8f7af6456 --- /dev/null +++ b/docs/docs/keymaps/behaviors/antecedent-morph.md @@ -0,0 +1,115 @@ +--- +title: Antecedent-Morph Behavior +sidebar_label: Antecedent-Morph +--- + +## Summary + +The Antecedent-Morph behavior (adaptive keys) sends different behaviors, depending on which key was most recently +released before the antecedent-morph behavior was pressed, if this occurs within a configurable time period. + +## Antecedent-Morph + +The configuration of the behavior consists of an array of `antecedents`, key codes with implicit modifiers, as well as +of a delay `max-delay-ms` in milli-seconds. If none of the `antecedents` was released during the `max-delay-ms` before +the antecedent-morph behavior is pressed, the behavior invokes the `defaults` binding. If, however, the `n`-th of the +key codes (with implicit modifiers) listed in the array `antecedents` was released within `max-delay-ms`, the behavior +invokes the `n`-th of the bindings of the `bindings` property. + +### Configuration + +If the key A is assigned the behavior `&ad_a` defined as follows, for example, + +```dts +/ { + behaviors { + ad_a: adaptive_a { + compatible = "zmk,behavior-antecedent-morph"; + label = "ADAPTIVE_A"; + #binding-cells = <0>; + defaults = <&kp A>; + bindings = <&kp U>, <&kp O>; + antecedents = ; + max-delay-ms = <250>; + }; + }; +}; +``` + +then by default, pressing this key issues the key press `&kp A`. But if it is preceded within 250 milli-seconds by Q or +Z, then `&kp U` or `&kp O`, respectively, are issued instead. + +### Behavior Binding + +- Reference: `&ad_a` +- Parameter: None + +Example: + +```dts +&ad_a +``` + +### Behaviors + +The antecedent-morph behavior can issue not only key press events, but rather arbitrary behaviors. + +### Implicit Modifiers + +Some special key codes can be obtained only with the help of modifiers. For example, on the U.S. International Keyboard, +the symbol Ü is obtained by holding right Alt and tapping Y. In order to issue this symbol, one can therefore use `&kp +RA(Y)`. Here, right Alt is called an *implicit modifier*. Antecedents are always considered with implicit modifiers. For +example, + +```dts +/ { + behaviors { + ad_a: adaptive_a { + compatible = "zmk,behavior-antecedent-morph"; + label = "ADAPTIVE_A"; + #binding-cells = <0>; + defaults = <&kp A>; + bindings = <&kp U>, <&kp O>; + antecedents = ; + max-delay-ms = <250>; + }; + }; +}; +``` + +replaces the A by a U if preceded by Ü, but not if preceded by Y. + +### Explicit Modifiers + +The entire function of the antecedent-morph behavior is independent of the *explicit modifiers*. These are the modifiers +that the user is holding down while tapping the antecedent or while pressing the antecedent-morph behavior. In the above +example, A is replaced by O if preceded by Z, regardless of which modifier keys were held down while tapping the Z, +i.e. in particular after a lower case z or after an upper case Z. + +Finally, if the user is still holding down a Shift key when pressing the A that triggers the above antecedent-morph +behavior, then this results in an upper case O rather than a lower case o. + +### Dead Antecedents + +If some binding somewhere issues an illegal key code in the range beyond 0x00ff, this illegal key code is recognized and +tested as an antecedent, but then immediately discarded from the event queue. It therefore functions similarly to a dead +key. Note that these illegal key codes are specified with the *usage page* 0x07 as in the following example. If some key +is bound to `&kp DEAD_ANTE`, then it does not print anything, but still turns a subsequent A into a U. + +```dts +#define DEAD_ANTE 0x070100 + +/ { + behaviors { + ad_a: adaptive_a { + compatible = "zmk,behavior-antecedent-morph"; + label = "ADAPTIVE_A"; + #binding-cells = <0>; + defaults = <&kp A>; + bindings = <&kp U>, <&kp O>; + antecedents = ; + max-delay-ms = <250>; + }; + }; +}; +```