From b53844a869f5204284c267d3a980cf63600cef29 Mon Sep 17 00:00:00 2001 From: Peter Johanson Date: Wed, 4 Dec 2024 14:39:14 -0700 Subject: [PATCH] fixup! docs: Add initial pointer docs. --- docs/docs/config/{pointers.md => pointing.md} | 36 +++++++++---------- .../{pointers.md => pointing.md} | 15 +++----- .../features/{pointers.md => pointing.md} | 8 ++--- .../docs/keymaps/behaviors/mouse-emulation.md | 32 ++++++----------- docs/docs/keymaps/input-processors/usage.md | 2 +- docs/sidebars.js | 6 ++-- 6 files changed, 41 insertions(+), 58 deletions(-) rename docs/docs/config/{pointers.md => pointing.md} (82%) rename docs/docs/development/hardware-integration/{pointers.md => pointing.md} (93%) rename docs/docs/features/{pointers.md => pointing.md} (94%) diff --git a/docs/docs/config/pointers.md b/docs/docs/config/pointing.md similarity index 82% rename from docs/docs/config/pointers.md rename to docs/docs/config/pointing.md index 64c03b85159..f164eb2af07 100644 --- a/docs/docs/config/pointers.md +++ b/docs/docs/config/pointing.md @@ -1,9 +1,9 @@ --- -title: Pointer Configuration -sidebar_label: Pointers +title: Pointing Device Configuration +sidebar_label: Pointing --- -These are settings related to the pointer/mouse support in ZMK. +These are settings related to the pointing device/mouse support in ZMK. See [Configuration Overview](index.md) for instructions on how to change these settings. @@ -28,7 +28,7 @@ The following settings are from Zephyr, and should be defaulted to sane values, ## Input Listener -TODO: Complete description +The following documents [input listeners](../features/pointing.md#input-listeners). ### Devicetree @@ -36,24 +36,24 @@ Applies to: `compatible = "zmk,input-listener"` Definition file: [zmk/app/dts/bindings/zmk,input-listener.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/zmk%2Cinput-listener.yaml) -| Property | Type | Description | Default | -| ------------------ | ------ | ------------------------------------------------------------------- | ------- | -| `device` | handle | Input device handle | | -| `input-processors` | array | List of input processors (with parameters) to apply to input events | | +| Property | Type | Description | +| ------------------ | ------ | ------------------------------------------------------------------- | --- | +| `device` | handle | Input device handle | +| `input-processors` | array | List of input processors (with parameters) to apply to input events | | #### Child Properties Additional properties can be set on child nodes, which allows changing the settings when certain layers are enabled: -| Property | Type | Description | Default | -| ------------------ | ----- | ------------------------------------------------------------------------------------------------ | ------- | -| `layers` | array | List of layer indexes. This config will apply if any layer in the list is active. | | -| `input-processors` | array | List of input processors (with parameters) to apply to input events | | -| `inherit` | flag | Whether to first apply the base input processors before the processors specific to this override | | +| Property | Type | Description | +| ------------------ | ----- | ------------------------------------------------------------------------------------------------ | +| `layers` | array | List of layer indexes. This config will apply if any layer in the list is active. | +| `input-processors` | array | List of input processors (with parameters) to apply to input events | +| `inherit` | flag | Whether to first apply the base input processors before the processors specific to this override | ## Input Split -TODO: Complete description +Input splits are used for [pointing devices on split peripherals](../development/hardware-integration/pointing.md#split). ### Devicetree @@ -61,7 +61,7 @@ Applies to: `compatible = "zmk,input-split"` Definition file: [zmk/app/dts/bindings/zmk,input-split.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/zmk%2Cinput-split.yaml) -| Property | Type | Description | Default | -| ------------------ | ------ | ------------------------------------------------------------------- | ------- | -| `device` | handle | Input device handle | | -| `input-processors` | array | List of input processors (with parameters) to apply to input events | | +| Property | Type | Description | +| ------------------ | ------ | ------------------------------------------------------------------- | +| `device` | handle | Input device handle | +| `input-processors` | array | List of input processors (with parameters) to apply to input events | diff --git a/docs/docs/development/hardware-integration/pointers.md b/docs/docs/development/hardware-integration/pointing.md similarity index 93% rename from docs/docs/development/hardware-integration/pointers.md rename to docs/docs/development/hardware-integration/pointing.md index 5161dc01207..0e00c776c22 100644 --- a/docs/docs/development/hardware-integration/pointers.md +++ b/docs/docs/development/hardware-integration/pointing.md @@ -1,6 +1,5 @@ --- title: Pointing Devices -sidebar_label: Pointers --- ZMK's pointer support builds upon the Zephyr [input API](https://docs.zephyrproject.org/3.5.0/services/input/index.html) to offer pointer/mouse functionality with various hardware. A limited number of input drivers are available in the Zephyr 3.5 version currently used by ZMK, but additional drivers can be found in [external modules](../../features/modules.mdx) for a variety of hardware. @@ -34,7 +33,7 @@ The specifics of the properties required to set for a given driver will vary; al ## Listener -Every input device needs an associated listener added that listens for events from the device and processes them before sending the events to the host using a HID mouse report. See [input listener configuration](../../config/pointers.md#input-listener) for the full details. For example, to add a listener for the above device: +Every input device needs an associated listener added that listens for events from the device and processes them before sending the events to the host using a HID mouse report. See [input listener configuration](../../config/pointing.md#input-listener) for the full details. For example, to add a listener for the above device: ```dts / { @@ -63,7 +62,7 @@ Some physical pointing devices may be generating input events that need some adj ## Split -Pointing devices are supported on split peripherals, with some additional configuration using the [input split](../../config/pointers.md#input-split). All split pointers are identified using a unique integer value, which is specified using the `reg` property and in the `@#` suffix for the node. If adding multiple peripheral pointers, be sure that each is given a unique identifier. +Pointing devices are supported on split peripherals, with some additional configuration using the [input split](../../config/pointing.md#input-split). All split pointers are identified using a unique integer value, which is specified using the `reg` property and in the `@#` suffix for the node. If adding multiple peripheral pointers, be sure that each is given a unique identifier. ### Shared @@ -102,14 +101,6 @@ On the peripheral, first include the shared file, and then update the input spli ```dts #include "common.dtsi" -&glidepoint_split { - device = <&glidepoint>; -}; -``` - -If needed, the split can also have basic input processors applied to fix up the input data before it is sent to the central: - -```dts &glidepoint_split { device = <&glidepoint>; @@ -117,6 +108,8 @@ If needed, the split can also have basic input processors applied to fix up the }; ``` +The `input-processors` property is optional, and only necessary if the input needs to be fixed up before it is sent to the central. + ### Central On the central, the input split acts as an input device, receiving events from the peripheral and raising them locally. First, include the shared file, and then enabled the [input listener](#listener) that is created, but disabled, in our shared file: diff --git a/docs/docs/features/pointers.md b/docs/docs/features/pointing.md similarity index 94% rename from docs/docs/features/pointers.md rename to docs/docs/features/pointing.md index 7a7d99fd542..a793ee726c3 100644 --- a/docs/docs/features/pointers.md +++ b/docs/docs/features/pointing.md @@ -1,12 +1,12 @@ --- -title: Pointers +title: Pointing Devices --- ZMK supports physical pointing devices, as well as [mouse emulation behaviors](../keymaps/behaviors/mouse-emulation.md) for sending HID pointing events to hosts. ## Configuration -To enable the pointer functionality, you must set `CONFIG_ZMK_MOUSE=y` in your config. See the [pointer configuration](../config/pointers.md) for the full details. +To enable the pointer functionality, you must set `CONFIG_ZMK_MOUSE=y` in your config. See the [pointer configuration](../config/pointing.md) for the full details. :::warning @@ -20,11 +20,11 @@ Mouse emulation allows you to use your keyboard as a pointing device without usi See the [mouse emulation behaviors](../keymaps/behaviors/mouse-emulation.md) for details. -## Physical Pointers +## Physical Pointing Devices There are a few drivers available for supported physical pointing devices integrated into ZMK powered device. When doing so, you can use your device as both a keyboard and a pointing device with any connected hosts. The functionality can be extended further, e.g. slow mode, scroll mode, temporary mouse layers, etc. by configuring input processors linked to the physical pointing device. -For more information, refer to the [pointer hardware integration](../development/hardware-integration/pointers.md) documentation. +For more information, refer to the [pointer hardware integration](../development/hardware-integration/pointing.md) documentation. ## Input Processors diff --git a/docs/docs/keymaps/behaviors/mouse-emulation.md b/docs/docs/keymaps/behaviors/mouse-emulation.md index 8a3dab57411..65fa480bf64 100644 --- a/docs/docs/keymaps/behaviors/mouse-emulation.md +++ b/docs/docs/keymaps/behaviors/mouse-emulation.md @@ -153,7 +153,7 @@ The following will send a scroll left event to the host when pressed/held: :::note -If you enabled [smooth scrolling](../../config/pointers.md#kconfig) then you will want to use the same `MOVE_UP`, `MOVE_DOWN`, etc values instead of the smaller `SCRL_*` parameters. +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. ::: @@ -173,26 +173,16 @@ Both `&mmv` and `&msc` are instances of the same `"zmk,behavior-input-two-axis"` ```dts &mmv { - trigger-period-ms = <12> + trigger-period-ms = <12>; + delay-ms = <15>; + time-to-max-speed-ms = <600>; + acceleration-exponent = <1>; }; ``` -#### `trigger-period-ms` - -How many milliseconds between generated input events based on the current speed/direction. - -#### `delay-ms` - -How many milliseconds to delay any processing or event generation when first pressed. - -#### `time-to-max-speed-ms` - -How many milliseconds it takes to accelerate to the curren max speed. - -#### `acceleration-exponent` - -The acceleration exponent to apply, with three possible values: - -- `0` - uniform speed -- `1` - uniform acceleration -- `2` - exponential acceleration +| Property | Description | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------- | +| `trigger-period-ms` | How many milliseconds between generated input events based on the current speed/direction. | +| `delay-ms` | How many milliseconds to delay any processing or event generation when first pressed. | +| `time-to-max-speed-ms` | How many milliseconds it takes to accelerate to the curren max speed. | +| `acceleration-exponent` | The acceleration exponent to apply: `0` - uniform speed, `1` - uniform acceleration, `2` - exponential acceleration | diff --git a/docs/docs/keymaps/input-processors/usage.md b/docs/docs/keymaps/input-processors/usage.md index fdbad4c29b8..5b2b0346e0c 100644 --- a/docs/docs/keymaps/input-processors/usage.md +++ b/docs/docs/keymaps/input-processors/usage.md @@ -3,7 +3,7 @@ title: Input Processor Usage sidebar_label: Usage --- -Input processors are used by assigning them to a given [input listener](../../features/pointers.md#input-listeners). A base set of processors is assigned to a listener, and then overrides can be set that are only active when certain [layers](../index.mdx#layers) are active. The following assumes you are adding processors to the `&trackpad` device which is set up with a `&trackpad_listener`: +Input processors are used by assigning them to a given [input listener](../../features/pointing.md#input-listeners). A base set of processors is assigned to a listener, and then overrides can be set that are only active when certain [layers](../index.mdx#layers) are active. The following assumes you are adding processors to the `&trackpad` device which is set up with a `&trackpad_listener`: ### Base Processors diff --git a/docs/sidebars.js b/docs/sidebars.js index 2f28f3fd162..9eba3718a1c 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -39,7 +39,7 @@ module.exports = { "features/battery", "features/low-power-states", "features/encoders", - "features/pointers", + "features/pointing", "features/displays", "features/backlight", "features/underglow", @@ -127,7 +127,7 @@ module.exports = { "config/combos", "config/displays", "config/encoders", - "config/pointers", + "config/pointing", "config/keymap", "config/layout", "config/kscan", @@ -155,7 +155,7 @@ module.exports = { "development/hardware-integration/shift-registers", "development/hardware-integration/encoders", "development/hardware-integration/soft-off-setup", - "development/hardware-integration/pointers", + "development/hardware-integration/pointing", ], }, {