From a1f72ffd5babd0cc8b0c607543ec816f5806be73 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Fri, 6 Dec 2024 02:21:37 -0500 Subject: [PATCH] Docs code review fixes. Co-authored-by: Cem Aksoylar --- docs/docs/config/pointing.md | 16 ++++++++-------- .../hardware-integration/pointing.mdx | 8 ++++---- docs/docs/features/pointing.md | 4 ++-- docs/docs/keymaps/behaviors/index.mdx | 4 ++-- docs/docs/keymaps/behaviors/mouse-emulation.md | 8 ++++---- .../docs/keymaps/input-processors/code-mapper.md | 12 ++++++++---- docs/docs/keymaps/input-processors/index.md | 8 ++++---- docs/docs/keymaps/input-processors/scaler.md | 6 +++--- docs/docs/keymaps/input-processors/temp-layer.md | 14 +++++++------- .../docs/keymaps/input-processors/transformer.md | 4 ++-- docs/docs/keymaps/input-processors/usage.md | 6 +++--- 11 files changed, 47 insertions(+), 43 deletions(-) diff --git a/docs/docs/config/pointing.md b/docs/docs/config/pointing.md index e5eb6f4aeae..3971fb735e5 100644 --- a/docs/docs/config/pointing.md +++ b/docs/docs/config/pointing.md @@ -15,12 +15,12 @@ Definition file: [zmk/app/mouse/Kconfig](https://github.com/zmkfirmware/zmk/blob | Config | Type | Description | Default | | ----------------------------------- | ---- | -------------------------------------------------------------------------- | ------- | -| `CONFIG_ZMK_MOUSE` | bool | Enable the general pointer/mouse functionality | n | +| `CONFIG_ZMK_MOUSE` | bool | Enable the general pointing/mouse functionality | n | | `CONFIG_ZMK_MOUSE_SMOOTH_SCROLLING` | bool | Enable smooth scrolling HID functionality (via HID Resolution Multipliers) | n | ### Zephyr Settings -The following settings are from Zephyr, and should be defaulted to sane values, but can be adjusted if you encounter problems +The following settings are from Zephyr and should be defaulted to sane values, but can be adjusted if you encounter problems. | Config | Type | Description | Default | | -------------------------------- | ---- | ---------------------------------------------------------- | ------------------------------- | @@ -28,7 +28,7 @@ The following settings are from Zephyr, and should be defaulted to sane values, ## Input Listener -The following documents [input listeners](../features/pointing.md#input-listeners). +The following documents settings related to [input listeners](../features/pointing.md#input-listeners). ### Devicetree @@ -38,8 +38,8 @@ Definition file: [zmk/app/dts/bindings/zmk,input-listener.yaml](https://github.c | Property | Type | Description | | ------------------ | ------ | ------------------------------------------------------------------- | --- | -| `device` | handle | Input device handle | -| `input-processors` | array | List of input processors (with parameters) to apply to input events | | +| `device` | phandle | Input device handle | +| `input-processors` | phandle-array | List of input processors (with parameters) to apply to input events | | #### Child Properties @@ -48,8 +48,8 @@ Additional properties can be set on child nodes, which allows changing the setti | 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-processors` | phandle-array | List of input processors (with parameters) to apply to input events | +| `inherit` | bool | Whether to first apply the base input processors before the processors specific to this override | ## Input Split @@ -64,4 +64,4 @@ Definition file: [zmk/app/dts/bindings/zmk,input-split.yaml](https://github.com/ | Property | Type | Description | | ------------------ | ------ | ------------------------------------------------------------------- | | `device` | handle | Input device handle | -| `input-processors` | array | List of input processors (with parameters) to apply to input events | +| `input-processors` | phandle-array | List of input processors (with parameters) to apply to input events | diff --git a/docs/docs/development/hardware-integration/pointing.mdx b/docs/docs/development/hardware-integration/pointing.mdx index 327e1e3487d..77a19104d54 100644 --- a/docs/docs/development/hardware-integration/pointing.mdx +++ b/docs/docs/development/hardware-integration/pointing.mdx @@ -7,12 +7,12 @@ import TabItem from "@theme/TabItem"; 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. -The details will depend on if you are adding a pointing device to a [split peripheral](../../features/split-keyboards.md#central-and-peripheral-roles) or to a non-split or split central: +The details will depend on if you are adding a pointing device to a [split peripheral](../../features/split-keyboards.md#central-and-peripheral-roles) or to a unibody keyboard or split central part: @@ -60,7 +60,7 @@ Every input device needs an associated listener added that listens for events fr ## Input Processors -Some physical pointing devices may be generating input events that need some adjustment before being sent to hosts. For example a trackpad might be integrated into a keyboard rotated 90° and need the X/Y data adjusted appropriately. This can be accomplished with [input processors](../../keymaps/input-processors/index.md). You could enhande the above listener with: +Some physical pointing devices may be generating input events that need adjustment before being sent to hosts. For example a trackpad might be integrated into a keyboard rotated 90° and need the X/Y data adjusted appropriately. This can be accomplished with [input processors](../../keymaps/input-processors/index.md). As an example, you could enhance the above listener with the following input processor that inverts and swaps the X/Y axes: ```dts #include @@ -79,7 +79,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/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. +Pointing devices are supported on split peripherals, with some additional configuration using the [input split device](../../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 diff --git a/docs/docs/features/pointing.md b/docs/docs/features/pointing.md index 4eb2715dcf0..0aeedc58567 100644 --- a/docs/docs/features/pointing.md +++ b/docs/docs/features/pointing.md @@ -10,7 +10,7 @@ To enable the pointer functionality, you must set `CONFIG_ZMK_MOUSE=y` in your c :::warning -When enabling the feature, changes are made to the HID report descriptor which some hosts may not pick up automatically over BLE. Be sure to remove and re-pair to your hosts once you enable the feature. +When enabling the feature, changes are made to the HID report descriptor which some hosts may not pick up automatically over BLE. Be sure to [remove and re-pair to your hosts](bluetooth.md#refreshing-the-hid-descriptor) once you enable the feature. ::: @@ -22,7 +22,7 @@ See the [mouse emulation behaviors](../keymaps/behaviors/mouse-emulation.md) for ## 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](#input-processors) linked to the physical pointing device. +There are a few drivers available for supporting physical pointing devices integrated into a 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](#input-processors) linked to the physical pointing device. For more information, refer to the [pointer hardware integration](../development/hardware-integration/pointing.mdx) documentation. diff --git a/docs/docs/keymaps/behaviors/index.mdx b/docs/docs/keymaps/behaviors/index.mdx index c876beb111e..53ed4200c54 100644 --- a/docs/docs/keymaps/behaviors/index.mdx +++ b/docs/docs/keymaps/behaviors/index.mdx @@ -43,8 +43,8 @@ Below is a summary of pre-defined behavior bindings and user-definable behaviors | Binding | Behavior | Description | | ------- | ----------------------------------------------------------- | ------------------------------- | | `&mkp` | [Mouse Button Press](mouse-emulation.md#mouse-button-press) | Emulates pressing mouse buttons | -| `&mmv` | [Mouse Button Press](mouse-emulation.md#mouse-move) | Emulates mouse movement | -| `&msc` | [Mouse Button Press](mouse-emulation.md#mouse-scroll) | Emulates mouse scrolling | +| `&mmv` | [Mouse Move](mouse-emulation.md#mouse-move) | Emulates mouse movement | +| `&msc` | [Mouse Scroll](mouse-emulation.md#mouse-scroll) | Emulates mouse scrolling | ## Reset Behaviors diff --git a/docs/docs/keymaps/behaviors/mouse-emulation.md b/docs/docs/keymaps/behaviors/mouse-emulation.md index 310ad2018b2..98954fdefc0 100644 --- a/docs/docs/keymaps/behaviors/mouse-emulation.md +++ b/docs/docs/keymaps/behaviors/mouse-emulation.md @@ -22,9 +22,9 @@ To use any of the behaviors documented here, the ZMK mouse feature must be enabl CONFIG_ZMK_MOUSE=y ``` -## Mouse Button Defines +## Mouse Emulation 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,8 +35,8 @@ provided by ZMK near the top: 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_MOUSE_DEFAULT_MOVE_VAL 1500 -#define ZMK_MOUSE_DEFAULT_SCRL_VAL 20 +#define ZMK_MOUSE_DEFAULT_MOVE_VAL 1500 // default: 600 +#define ZMK_MOUSE_DEFAULT_SCRL_VAL 20 // default: 10 #include ``` diff --git a/docs/docs/keymaps/input-processors/code-mapper.md b/docs/docs/keymaps/input-processors/code-mapper.md index 48c4c2e6751..76689f12bfd 100644 --- a/docs/docs/keymaps/input-processors/code-mapper.md +++ b/docs/docs/keymaps/input-processors/code-mapper.md @@ -5,7 +5,7 @@ sidebar_label: Code Mapper ## Overview -The scaler input processor is used to map the code of an event to a new one, e.g. changing a vertical Y movement event into a scroll event. +The code mapper input processor is used to map the code of an event to a new one, e.g. changing a vertical Y movement event into a scroll event. ## Usage @@ -22,14 +22,18 @@ Three pre-defined instance of the code mapper input processor are available: | Reference | Description | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `&zip_xy_to_scroll_mapper` | Map X/Y movement events to horizontal wheel/wheel events, respectively. | -| `&zip_xy_swap_mapper` | Map X to Y, and Y to X for movements. This can also be accomplished with the [transformer](transformer.md#pre-defined-instances) processors. | +| `&zip_xy_swap_mapper` | Map X to Y, and Y to X for movements. | -## User Defined Instances +Note that swapping X and Y movements can also be accomplished with the [transformer](transformer.md#pre-defined-instances) processors. + +## User-Defined Instances Users can define new instances of the code mapper input processor if they want to target different codes. ### Example +Below example maps the left mouse button code to the middle mouse button. + ```dts #include @@ -56,4 +60,4 @@ The code mapper input processor uses a `compatible` property of `"zmk,input-proc ### User Properties - `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_REL` for relative events and `INPUT_EV_KEY` for key/button events. -- `map` - The specific codes of the given type to map, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245). This list must be an even number of entries, which is process as a list of pairs of codes, with the first is the source code, and the second is the code to map it to. +- `map` - The specific codes of the given type to map, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245). This list must be an even number of entries which is processed as a list of pairs of codes. The first code in the pair is the source code, and the second is the code to map it to. diff --git a/docs/docs/keymaps/input-processors/index.md b/docs/docs/keymaps/input-processors/index.md index 4d415c48c47..5e37e47bd03 100644 --- a/docs/docs/keymaps/input-processors/index.md +++ b/docs/docs/keymaps/input-processors/index.md @@ -11,11 +11,11 @@ sidebar_label: Overview For information on using input processors with a given pointing device, see [input processor usage](usage.md). -# Available Processors +## Available Processors Below is a summary of pre-defined input processors and user-definable input processors available in ZMK, with references to documentation pages describing them. -## Pre-Defined Processors +### Pre-Defined Processors A set of predefined input processors is available by adding the following at the top of your keymap/overlay file: @@ -36,14 +36,14 @@ Once included, you can use the following: | `&zip_xy_swap_mapper` | [XY Swap Mapper](code-mapper.md#pre-defined-instances) | Swap X/Y values | | `&zip_temp_layer` | [Temporary Layer](temp-layer.md#pre-defined-instances) | Temporarily enable a layer during pointer use | -## Used-Defined Processors +### User-Defined Processors Several of the input processors that have predefined instances, e.g. `&zip_xy_scaler` or `&zip_xy_to_scroll_mapper` can also have new instances created with custom properties around which input codes to scale, or which codes to map, etc. | Compatible | Processor | Description | | --------------------------------- | ---------------------------------------------------- | ------------------------------------------------ | | `zmk,input-processor-transform` | [Transform](transformer.md#user-defined-instances) | Perform various transforms like inverting values | -| `zmk,input-processor-code-mapper` | [Code Mapper](code-mapper.md#user-defined-instances) | Perform various transforms like inverting values | +| `zmk,input-processor-code-mapper` | [Code Mapper](code-mapper.md#user-defined-instances) | Map one event code to another type | ## External Processors diff --git a/docs/docs/keymaps/input-processors/scaler.md b/docs/docs/keymaps/input-processors/scaler.md index af6fc94323c..c6bb01489aa 100644 --- a/docs/docs/keymaps/input-processors/scaler.md +++ b/docs/docs/keymaps/input-processors/scaler.md @@ -9,7 +9,7 @@ The scaler input processor is used to scale the value of an input event that has ## Usage -When used, a scaler takes two parameters, a multiplier and a divisor, e.g.: +When used, a scaler takes two parameters that are positive integers, a multiplier and a divisor, e.g.: ```dts &zip_xy_scaler 2 1 @@ -21,7 +21,7 @@ which will double all the X/Y movement, or: &zip_xy_scaler 1 3 ``` -which will make movements more granular. +which will make movements more granular by reducing the speed to one third. ## Pre-Defined Instances @@ -33,7 +33,7 @@ Three pre-defined instance of the scaler input processor are available: | `&zip_x_scaler` | Scale X-axis values | | `&zip_y_scaler` | Scale Y-axis values | -## User Defined Instances +## User-Defined Instances Users can define new instances of the scaler input processor if they want to target different codes. diff --git a/docs/docs/keymaps/input-processors/temp-layer.md b/docs/docs/keymaps/input-processors/temp-layer.md index 56495693021..47f2fe6d672 100644 --- a/docs/docs/keymaps/input-processors/temp-layer.md +++ b/docs/docs/keymaps/input-processors/temp-layer.md @@ -5,27 +5,27 @@ sidebar_label: Temporary Layer ## Overview -The temporary layer input processor is used to enable a layer when input events are received, and automatically disabling the layer when no further events are received in the given timeout duration. This most frequently is used to temporarily enable a layer with a set of [mouse button emulation behaviors](../behaviors/mouse-emulation.md#mouse-button-press) on it, so you can press various mouse buttons with the normal keyboard keys while using a physical pointer device for X/Y movement. +The temporary layer input processor is used to enable a layer when input events are received, and automatically disable it when no further events are received in the given timeout duration. This most frequently is used to temporarily enable a layer with a set of [mouse button emulation behaviors](../behaviors/mouse-emulation.md#mouse-button-press) on it, so you can press various mouse buttons with the normal keyboard keys while using a physical pointer device for X/Y movement. ## Usage -When used, the temporary layer input processor takes two parameters, the layer index to enabled and a timeout value in milliseconds: +When used, the temporary layer input processor takes two parameters, the layer index to enable and a timeout value in milliseconds: ```dts &zip_temp_layer 2 2000 ``` -which will enable the third layer and automatically disable it again after 2 seconds with no events from this pointing device. +Above example enables the third layer and automatically disables it again after 2 seconds with no events from this pointing device. ## Pre-Defined Instances -Three pre-defined instance of the scaler input processor are available: +One pre-defined instance of the temporary layer input processor is available: | Reference | Description | | ----------------- | --------------------------------------------------------------- | | `&zip_temp_layer` | Enable a certain layer temporarily until no events are received | -## User Defined Instances +## User-Defined Instances Users can define new instances of the temporary layer input processor to use different settings. @@ -54,5 +54,5 @@ The temp layer input processor uses a `compatible` property of `"zmk,input-proce ### User Properties -- `require-prior-idle-ms` - Only activate the layer if there have not been any key presses for at least the set number of milliseconds -- `excluded-positions` - Exclude certain positions from deactivating the layer once it is active. +- `require-prior-idle-ms` - Only activate the layer if there have not been any key presses for at least the set number of milliseconds before the pointing device event +- `excluded-positions` - List of (zero-based) key positions to exclude from deactivating the layer once it is active. diff --git a/docs/docs/keymaps/input-processors/transformer.md b/docs/docs/keymaps/input-processors/transformer.md index b1756806bd3..155e63707dd 100644 --- a/docs/docs/keymaps/input-processors/transformer.md +++ b/docs/docs/keymaps/input-processors/transformer.md @@ -5,7 +5,7 @@ sidebar_label: Transformer ## Overview -The transform input processor is used to perform various transforms on the value of an input event that has a code matching the codes set on the transformer. Events with other codes will be ignored. +The transformer input processor is used to perform various transforms on the value of an input event that has a code matching the codes set on the transformer. Events with other codes will be ignored. ## Available Transforms @@ -53,8 +53,8 @@ Users can define new instances of the transform input processor if they want to compatible = "zmk,input-processor-transform"; #input-processor-cells = <1>; type = ; - y-codes = ; x-codes = ; + y-codes = ; }; }; } diff --git a/docs/docs/keymaps/input-processors/usage.md b/docs/docs/keymaps/input-processors/usage.md index 5b2b0346e0c..e245173ed34 100644 --- a/docs/docs/keymaps/input-processors/usage.md +++ b/docs/docs/keymaps/input-processors/usage.md @@ -3,11 +3,11 @@ title: Input Processor Usage sidebar_label: Usage --- -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`: +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 examples in the following assume you are adding processors to the `&trackpad` device which is set up with a `&trackpad_listener`. ### Base Processors -Base processors are assigned in the `input-processors` property, and when events are generated, the events are process in the sequence in the order the processors are listed. For example, if you wanted your trackpad to always scale the values to increase the movements, you would assign the [scaler](scaler.md#pre-defined-instances) to the property: +Base processors are assigned in the `input-processors` property, and when events are generated, the events are process in the sequence in the order the processors are listed. For example, if you wanted your trackpad to always scale the values to increase the movements, you would assign the [scaler](scaler.md#pre-defined-instances) input processor to the property: ```dts #include @@ -29,7 +29,7 @@ Additional overrides can be added that only apply when the associated layer is a scroller { layers = <1>; - input-processors = <&zip_xy_to_scoll_mapper>; + input-processors = <&zip_xy_to_scroll_mapper>; }; } ```