forked from kofal.net/zmk
feat(mouse): Add mouse move and scroll support (#2477)
* feat(mouse): Add mouse move and scroll support
* Use Zephyr input subsystem for all pointers.
* Input processors for modifying events, e.g. scaling, swapping
codes, temporary (mouse) layers, etc.
* Mouse move/scroll behaviors.
* Infrastructure in place for physical pointer input devices.
* feat: Add input split support.
* docs: Add initial pointer docs.
---------
Co-authored-by: Cem Aksoylar <caksoylar@users.noreply.github.com>
Co-authored-by: Alexander Krikun <krikun98@gmail.com>
Co-authored-by: Robert U <urob@users.noreply.github.com>
Co-authored-by: Shawn Meier <ftc@users.noreply.github.com>
Co-authored-by: Chris Andreae <chris@andreae.gen.nz>
Co-authored-by: Anant Thazhemadam <47104651+thazhemadam@users.noreply.github.com>
Co-authored-by: Erik Tollerud <erik.tollerud@gmail.com>
Co-authored-by: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com>
This commit is contained in:
Pete Johanson
GitHub
@@ -5,8 +5,7 @@ sidebar_label: Mouse Emulation
|
||||
|
||||
## Summary
|
||||
|
||||
Mouse emulation behaviors send mouse events. Currently, only mouse button presses are supported, but movement
|
||||
and scroll action support is planned for the future.
|
||||
Mouse emulation behaviors send mouse events, including mouse button presses, cursor movement and scrolling.
|
||||
|
||||
:::warning[Refreshing the HID descriptor]
|
||||
|
||||
@@ -17,17 +16,15 @@ The mouse functionality will not work over BLE until that is done.
|
||||
|
||||
## Configuration Option
|
||||
|
||||
This feature can be enabled or disabled explicitly via a config option:
|
||||
To use any of the behaviors documented here, the ZMK mouse feature must be enabled explicitly via a config option:
|
||||
|
||||
```
|
||||
CONFIG_ZMK_MOUSE=y
|
||||
CONFIG_ZMK_POINTING=y
|
||||
```
|
||||
|
||||
If you use the mouse key press behavior in your keymap, the feature will automatically be enabled for you.
|
||||
## Mouse Emulation Defines
|
||||
|
||||
## Mouse Button Defines
|
||||
|
||||
To make it easier to encode the HID mouse button numeric values, include
|
||||
To make it easier to encode the HID mouse button and move/scroll speed numeric values, include
|
||||
the [`dt-bindings/zmk/mouse.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/mouse.h) header
|
||||
provided by ZMK near the top:
|
||||
|
||||
@@ -35,6 +32,15 @@ provided by ZMK near the top:
|
||||
#include <dt-bindings/zmk/mouse.h>
|
||||
```
|
||||
|
||||
Should you wish to override the default movement or scrolling max velocities, you can define the defaults before including the header, e.g.:
|
||||
|
||||
```c
|
||||
#define ZMK_POINTING_DEFAULT_MOVE_VAL 1500 // default: 600
|
||||
#define ZMK_POINTING_DEFAULT_SCRL_VAL 20 // default: 10
|
||||
|
||||
#include <dt-bindings/zmk/mouse.h>
|
||||
```
|
||||
|
||||
## Mouse Button Press
|
||||
|
||||
This behavior can press/release up to 5 mouse buttons.
|
||||
@@ -69,3 +75,133 @@ This example will send press of the fourth mouse button when the binding is trig
|
||||
```
|
||||
&mkp MB4
|
||||
```
|
||||
|
||||
### Input Processors
|
||||
|
||||
If you want to apply any [input processors](../input-processors/index.md#input-processors-overview) to `&mkp` you can do so by referencing `&mkp_input_listener`, e.g.:
|
||||
|
||||
```dts
|
||||
&mkp_input_listener {
|
||||
input-processors = <&zip_temp_layer 2 2000>;
|
||||
}
|
||||
```
|
||||
|
||||
## Mouse Move
|
||||
|
||||
This behavior sends mouse X/Y movement events to the connected host.
|
||||
|
||||
### Behavior Binding
|
||||
|
||||
- Reference: `&mmv`
|
||||
- Parameter: A `uint32` with 16-bits each used for vertical and horizontal max velocity.
|
||||
|
||||
The following predefined values can be passed for the parameter:
|
||||
|
||||
| Define | Action |
|
||||
| :----------- | :--------- |
|
||||
| `MOVE_UP` | Move up |
|
||||
| `MOVE_DOWN` | Move down |
|
||||
| `MOVE_LEFT` | Move left |
|
||||
| `MOVE_RIGHT` | Move right |
|
||||
|
||||
Additionally, if you want to pass a different max speed than the default for the `MOVE_*` defines, custom X and Y velocity values can be passed with `MOVE_X` and `MOVE_Y`, e.g. `MOVE_X(100)` or `MOVE_Y(-100)`. Positive values indicate movement directions right or down. Note that the default value of the max speed depends on [the value of `ZMK_POINTING_DEFAULT_MOVE_VAL`](#mouse-emulation-defines).
|
||||
|
||||
### Examples
|
||||
|
||||
The following will send a down mouse movement event to the host when pressed/held:
|
||||
|
||||
```
|
||||
&mmv MOVE_DOWN
|
||||
```
|
||||
|
||||
The following will send a left mouse movement event to the host when pressed/held:
|
||||
|
||||
```
|
||||
&mmv MOVE_LEFT
|
||||
```
|
||||
|
||||
### Input Processors
|
||||
|
||||
If you want to apply any [input processors](../input-processors/index.md#input-processors-overview) to `&mmv` you can do so by referencing `&mmv_input_listener`, e.g.:
|
||||
|
||||
```dts
|
||||
&mmv_input_listener {
|
||||
input-processors = <&zip_temp_layer 2 2000>;
|
||||
}
|
||||
```
|
||||
|
||||
## Mouse Scroll
|
||||
|
||||
This behavior sends vertical and horizontal scroll events to the connected host.
|
||||
|
||||
### Behavior Binding
|
||||
|
||||
- Reference: `&msc`
|
||||
- Parameter: A `uint32` with 16-bits each used for vertical and horizontal velocity.
|
||||
|
||||
The following defines can be passed for the parameter:
|
||||
|
||||
| Define | Action |
|
||||
| :----------- | :----------- |
|
||||
| `SCRL_UP` | Scroll up |
|
||||
| `SCRL_DOWN` | Scroll down |
|
||||
| `SCRL_LEFT` | Scroll left |
|
||||
| `SCRL_RIGHT` | Scroll right |
|
||||
|
||||
Additionally, if you want to pass a different max speed than the default for the `SCRL_*` defines, custom X and Y velocity values can be passed with `MOVE_X` and `MOVE_Y`, e.g. `MOVE_X(5)` or `MOVE_Y(-5)`. Positive values indicate scroll directions right or up. Note that the default value of the max speed depends on [the value of `ZMK_POINTING_DEFAULT_SCRL_VAL`](#mouse-emulation-defines).
|
||||
|
||||
### Examples
|
||||
|
||||
The following will send a scroll down event to the host when pressed/held:
|
||||
|
||||
```
|
||||
&msc SCRL_DOWN
|
||||
```
|
||||
|
||||
The following will send a scroll left event to the host when pressed/held:
|
||||
|
||||
```
|
||||
&msc SCRL_LEFT
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
If you enabled [smooth scrolling](../../config/pointing.md#kconfig) then you will want to use the same `MOVE_UP`, `MOVE_DOWN`, etc values instead of the smaller `SCRL_*` parameters for more sensible scroll speeds.
|
||||
|
||||
:::
|
||||
|
||||
### Input Processors
|
||||
|
||||
If you want to apply any [input processors](../input-processors/index.md#input-processors-overview) to `&msc` you can do so by referencing `&msc_input_listener`, e.g.:
|
||||
|
||||
```dts
|
||||
&msc_input_listener {
|
||||
input-processors = <&zip_temp_layer 2 2000>;
|
||||
}
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
Both `&mmv` and `&msc` are instances of the `"zmk,behavior-input-two-axis"` behavior and can be modified using the [two axis input behavior](../../config/behaviors.md#two-axis-input) configuration properties. The default settings are as follows:
|
||||
|
||||
### Mouse Move
|
||||
|
||||
```dts
|
||||
&mmv {
|
||||
x-input-code = <INPUT_REL_X>;
|
||||
y-input-code = <INPUT_REL_Y>;
|
||||
time-to-max-speed-ms = <300>;
|
||||
acceleration-exponent = <1>;
|
||||
};
|
||||
```
|
||||
|
||||
### Mouse Scroll
|
||||
|
||||
```dts
|
||||
&msc {
|
||||
x-input-code = <INPUT_REL_HWHEEL>;
|
||||
y-input-code = <INPUT_REL_WHEEL>;
|
||||
time-to-max-speed-ms = <300>;
|
||||
acceleration-exponent = <1>;
|
||||
};
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user