https://github.com/ssbb/zmk-listeners
ZMK module to invoke behaviors on certain events.
https://github.com/ssbb/zmk-listeners
zmk zmk-module
Last synced: 3 months ago
JSON representation
ZMK module to invoke behaviors on certain events.
- Host: GitHub
- URL: https://github.com/ssbb/zmk-listeners
- Owner: ssbb
- License: mit
- Created: 2025-01-03T19:29:27.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-10T08:21:27.000Z (over 1 year ago)
- Last Synced: 2025-10-13T01:41:35.994Z (7 months ago)
- Topics: zmk, zmk-module
- Language: C
- Homepage:
- Size: 13.7 KB
- Stars: 13
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-zmk - ssbb/zmk-listeners - ZMK module to invoke behaviors on certain events. (Community firmware Modules and Behaviors / Custom Behaviors)
README
# zmk-listeners
ZMK module to invoke behaviors on certain events.
## Usage
Add the following entries to `remotes` and `projects` in `config/west.yml`.
```yaml
manifest:
remotes:
- name: zmkfirmware
url-base: https://github.com/zmkfirmware
- name: ssbb
url-base: https://github.com/ssbb
projects:
- name: zmk
remote: zmkfirmware
import: app/west.yml
- name: zmk-listeners
remote: ssbb
revision: v1
self:
path: config
```
## Layer Listeners
Layer listeners are specified like this:
```c
/ {
layer_listeners {
compatible = "zmk,layer-listeners";
// Call &haptic_feedback_in on layer enter, and &haptic_feedback_out on layer leave
nav_num_feedback {
layers = ;
bindings = <&haptic_feedback_in &haptic_feedback_out>;
};
// Call &reset_nav on NAV layer leave
nav_reset {
layers = ;
bindings = <&none &reset_nav>;
};
};
}
```
### Root properties
- `tap-ms`: The time to wait (in milliseconds) between the press and release events of a triggered behavior. Defaults to 5 ms.
- `wait-ms`: The time to wait (in milliseconds) before triggering the next listener. Defaults to 5 ms.
### Listener Properties
Each listener is defined as a child node.
- `layers` (required): A list of layers to which this listener should apply.
- `bindings` (required): The first behavior is triggered on layer entry, and the second on layer exit. Use `&none` for the other if you need only one. Second binding (layer leave) can be omitted if not needed.
## Keycode Listeners
```c
/ {
keycode_listeners {
compatible = "zmk,keycode-listeners";
// Call &haptic_feedback_key_press on key press, and &haptic_feedback_key_release on key release
a_b_feedback {
layers = ;
keycodes = ;
bindings = <&haptic_feedback_key_press &haptic_feedback_key_release>;
};
};
}
```
### Root properties
- `tap-ms`: The time to wait (in milliseconds) between the press and release events of a triggered behavior. Defaults to 5 ms.
- `wait-ms`: The time to wait (in milliseconds) before triggering the next listener. Defaults to 5 ms.
### Listener Properties
Each listener is defined as a child node.
- `keycodes` (required): A list of keycodes to which this listener should apply. Implicit modifiers (eg `LG(C)`) are supported.
- `layers` (optional): A list of layers to which this listener should apply.
- `bindings` (required): The first behavior is triggered on key press, and the second on key release. Use `&none` for the other if you need only one. Second binding (key release) can be omitted if not needed.
## USB HID LED Listeners
```c
#include
/ {
hid_listeners {
compatible = "zmk,hid-listeners";
// Call &haptic_feedback_led_on when caps lock led enables, and &haptic_feedback_led_off when caps lock disables
caps_feedback {
indicator = ;
bindings = <&haptic_feedback_led_on &haptic_feedback_led_off>;
};
};
}
```
### Root properties
- `tap-ms`: The time to wait (in milliseconds) between the press and release events of a triggered behavior. Defaults to 5 ms.
- `wait-ms`: The time to wait (in milliseconds) before triggering the next listener. Defaults to 5 ms.
### Listener Properties
Each listener is defined as a child node.
- `indicator` (required): A constant from `dt-binding/zmk/hid_usage.h` representing either the NUM LOCK, CAPS LOCK, SCROLL LOCK, KANA, or COMPOSE LED state. These are the only USB HID LED states emitted by the underlying ZMK event.
- `bindings` (required): The first behavior is triggered on key press, and the second on key release. Use `&none` for the other if you need only one. Second binding (key release) can be omitted if not needed.
## References
- [elpekenin/zmk-userspace](https://github.com/elpekenin/zmk-userspace) - Same thing with a different implementation and API.
- [badjeff/zmk-output-behavior-listener](https://github.com/badjeff/zmk-output-behavior-listener) - A more generic and complex listener that supports layers, keycodes, mouse events, etc.