kb01/zmk
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge 790e9ff9d7 into 0f972f1cc3

Browse source
This commit is contained in:
Void Your Warranty 2024-09-02 08:15:24 +02:00 • committed by GitHub
commit 1dc0f4a8fc
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 367 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
app/CMakeLists.txt
View file

@ -54,6 +54,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_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_momentary_layer.c)
target_sources(app PRIVATE src/behaviors/behavior_mod_morph.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_outputs.c)
target_sources(app PRIVATE src/behaviors/behavior_toggle_layer.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_to_layer.c)

23
app/dts/bindings/behaviors/zmk,behavior-antecedent-morph.yaml Normal file
View file

@ -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

228
app/src/behaviors/behavior_antecedent_morph.c Normal file
View file

@ -0,0 +1,228 @@
/*
* Copyright (c) 2023 The ZMK Contributors
*
* SPDX-License-Identifier: MIT
*/
#define DT_DRV_COMPAT zmk_behavior_antecedent_morph
#include <zephyr/device.h>
#include <drivers/behavior.h>
#include <zephyr/logging/log.h>
#include <zmk/behavior.h>
#include <zmk/keymap.h>
#include <zmk/event_manager.h>
#include <zmk/events/keycode_state_changed.h>
#include <zmk/hid.h>
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 <code_pressed> 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 = device_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 <code_pressed> 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;i<cfg->antecedents_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 behavior_keymap_binding_pressed(data->pressed_binding, event);
}
// 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 = device_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 behavior_keymap_binding_released(pressed_binding, event);
}
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; i<cfg->antecedents_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 = DT_PROP(DT_PHANDLE_BY_IDX(drv_inst, defaults, idx), label), \
.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 = { \
}; \
DEVICE_DT_INST_DEFINE(n,behavior_antecedent_morph_init,NULL,&behavior_antecedent_morph_data_##n, \
&behavior_antecedent_morph_config_##n, \
APPLICATION, CONFIG_KERNEL_INIT_PRIORITY_DEFAULT, \
&behavior_antecedent_morph_driver_api);
DT_INST_FOREACH_STATUS_OKAY(KP_INST)
#endif

115
docs/docs/behaviors/antecedent-morph.md Normal file
View file

@ -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 = <Q Z>;
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 = <RA(Y) Z>;
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 = <DEAD_ANTE Z>;
max-delay-ms = <250>;
};
};
};
```