docs: Add initial pointer docs.

Co-authored-by: Anant Thazhemadam <[email protected]> Co-authored-by: Erik Tollerud <[email protected]> Co-authored-by: Cem Aksoylar <[email protected]> Co-authored-by: Nicolas Munnich <[email protected]>
petejohanson · Dec 10, 2024 · 0ddce94 · 0ddce94
1 parent 72d17c1
commit 0ddce94
Show file tree

Hide file tree

Showing 13 changed files with 784 additions and 15 deletions.
diff --git a/docs/docs/config/behaviors.md b/docs/docs/config/behaviors.md
@@ -282,3 +282,23 @@ Applies to: `compatible = "zmk,behavior-tap-dance"`
 | `#binding-cells`  | int           | Must be `<0>`                                                                                |         |
 | `bindings`        | phandle array | A list of behaviors from which to select                                                     |         |
 | `tapping-term-ms` | int           | The maximum time (in milliseconds) between taps before an item from `bindings` is triggered. | 200     |
+
+## Two Axis Input
+
+This behavior is part of the core [pointing devices](../features/pointing.md) feature, and is used to generate X/Y and scroll input events. It is the underlying behavior used for the mouse [move](../keymaps/behaviors/mouse-emulation.md#mouse-move) and [scroll](../keymaps/behaviors/mouse-emulation.md#mouse-scroll) behaviors.
+
+### Devicetree
+
+Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-input-two-axis.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-input-two-axis.yaml)
+
+Applies to: `compatible = "zmk,behavior-input-two-axis"`
+
+| Property                | Type | Description                                                                                                                                                                                   | Default |
+| ----------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `#binding-cells`        | int  | Must be `<1>`                                                                                                                                                                                 |         |
+| `x-input-code`          | int  | The [relative event code](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245) for generated input events for the X-axis. |         |
+| `y-input-code`          | int  | The [relative event code](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245) for generated input events for the Y-axis. |         |
+| `trigger-period-ms`     | int  | How many milliseconds between generated input events based on the current speed/direction.                                                                                                    | 16      |
+| `delay-ms`              | int  | How many milliseconds to delay any processing or event generation when first pressed.                                                                                                         | 0       |
+| `time-to-max-speed-ms`  | int  | How many milliseconds it takes to accelerate to the curren max speed.                                                                                                                         | 0       |
+| `acceleration-exponent` | int  | The acceleration exponent to apply: `0` - uniform speed, `1` - uniform acceleration, `2` - exponential acceleration                                                                           | 1       |
diff --git a/docs/docs/config/pointing.md b/docs/docs/config/pointing.md
@@ -0,0 +1,67 @@
+---
+title: Pointing Device Configuration
+sidebar_label: Pointing
+---
+
+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.
+
+## Kconfig
+
+Definition file: [zmk/app/pointing/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/pointing/Kconfig)
+
+### General
+
+| Config                                 | Type | Description                                                                | Default |
+| -------------------------------------- | ---- | -------------------------------------------------------------------------- | ------- |
+| `CONFIG_ZMK_POINTING`                  | bool | Enable the general pointing/mouse functionality                            | n       |
+| `CONFIG_ZMK_POINTING_SMOOTH_SCROLLING` | bool | Enable smooth scrolling HID functionality (via HID Resolution Multipliers) | n       |
+
+### Advanced Settings
+
+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                         |
+| -------------------------------- | ---- | ---------------------------------------------------------- | ------------------------------- |
+| `CONFIG_INPUT_THREAD_STACK_SIZE` | int  | Stack size for the dedicated input event processing thread | 512 (1024 on split peripherals) |
+
+## Input Listener
+
+The following documents settings related to [input listeners](../features/pointing.md#input-listeners).
+
+### Devicetree
+
+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                                                         |
+| ------------------ | ------------- | ------------------------------------------------------------------- |
+| `device`           | phandle       | Input device handle                                                 |
+| `input-processors` | phandle-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                                                                                |
+| ------------------ | ------------- | ------------------------------------------------------------------------------------------ |
+| `layers`           | array         | List of layer indexes. This config will apply if any layer in the list is active.          |
+| `input-processors` | phandle-array | List of input processors (with parameters) to apply to input events                        |
+| `process-next`     | bool          | Whether to continue applying other input processors after this override if it takes effect |
+
+## Input Split
+
+Input splits are used for [pointing devices on split peripherals](../development/hardware-integration/pointing.mdx#split).
+
+### Devicetree
+
+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                                                         |
+| ------------------ | ------------- | ------------------------------------------------------------------- |
+| `device`           | handle        | Input device handle                                                 |
+| `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
@@ -0,0 +1,168 @@
+---
+title: Pointing Devices
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+ZMK's pointing device support builds upon the Zephyr [input API](https://docs.zephyrproject.org/3.5.0/services/input/index.html) to offer pointing/mouse functionality with various hardware. A limited number of input drivers are available in the Zephyr 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) as opposed to a unibody keyboard or split central part:
+
+<Tabs
+  defaultValue="central"
+  values={[
+    { label: "Unibody or Split Central", value: "central" },
+    { label: "Split Peripheral", value: "peripheral" },
+  ]}
+>
+  <TabItem value="central">
+
+## Input Device
+
+First, we must define the pointing device itself. The specifics of where this node goes will depend on the specific hardware. _Most_ pointing hardware uses either SPI or I2C for communication, and will be nested under a properly configured bus node, e.g. `&pro_micro_i2c` or for a complete onboard setup, `&i2c3`. See the documentation on [pin control](./pinctrl.mdx) if you need to configure the pins for an I2C or SPI bus.
+
+For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml), you may have a node like:
+
+```dts
+&pro_micro_spi {
+    status = "okay";
+    cs-gpios = <&pro_micro 19 GPIO_ACTIVE_LOW>;
+
+    glidepoint: glidepoint@0 {
+        compatible = "cirque,pinnacle";
+        reg = <0>;
+        spi-max-frequency = <1000000>;
+        status = "okay";
+        dr-gpios = <&pro_micro 5 (GPIO_ACTIVE_HIGH)>;
+
+        sensitivity = "4x";
+        sleep;
+        no-taps;
+    };
+};
+```
+
+The specifics of the properties required to set for a given driver will vary; always consult the devicetree bindings file for the specific driver to see what properties can be set.
+
+## 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/pointing.md#input-listener) for the full details. For example, to add a listener for the above device:
+
+```dts
+/ {
+    glidepoint_listener {
+        compatible = "zmk,input-listener";
+        device = <&glidepoint>;
+    };
+};
+```
+
+## Input Processors
+
+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 <dt-bindings/zmk/input_transform.h>
+
+/ {
+    glidepoint_listener {
+        compatible = "zmk,input-listener";
+        device = <&glidepoint>;
+        input-processors = <&zip_xy_transform (INPUT_TRANSFORM_XY_SWAP | INPUT_TRANSFORM_X_INVERT | INPUT_TRANSFORM_Y_INVERT)>;
+    };
+};
+```
+
+  </TabItem>
+  <TabItem value="peripheral">
+
+## Split
+
+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
+
+Both peripheral and central make use of a `zmk,input-split` device, which functions differently depending on where it is used. To avoid duplicating work, this node can be defined in a common `.dtsi` file that is included into both central and peripheral `.overlay`/`.dts` files. Second, the input listener for the central side is added here, but disabled, so that keymaps (which are included for central and peripheral builds) can reference the listener to add input processors without issue.
+
+:::note
+
+Input splits need to be nested under a parent node that properly sets `#address-cells = <1>` and `#size-cells = <0>`. These settings are what allow us to use a single integer number for the `reg` value.
+
+:::
+
+```dts
+/ {
+    split_inputs {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        glidepoint_split: glidepoint_split@0 {
+            compatible = "zmk,input-split";
+            reg = <0>;
+        };
+    };
+
+    glidepoint_listener: glidepoint_listener {
+        compatible = "zmk,input-listener";
+        status = "disabled";
+        device = <&glidepoint_split>;
+    };
+};
+```
+
+### Peripheral
+
+In the peripheral .overlay/.dts file, we do the following:
+
+- Include the shared .dtsi file.
+- Add the device node for the physical pointer.
+- Update the input split with a reference to the new device node that should be proxied.
+
+```dts
+#include "common.dtsi"
+
+&pro_micro_spi {
+    status = "okay";
+    cs-gpios = <&pro_micro 19 GPIO_ACTIVE_LOW>;
+
+    glidepoint: glidepoint@0 {
+        compatible = "cirque,pinnacle";
+        reg = <0>;
+        spi-max-frequency = <1000000>;
+        status = "okay";
+        dr-gpios = <&pro_micro 5 (GPIO_ACTIVE_HIGH)>;
+
+        sensitivity = "4x";
+        sleep;
+        no-taps;
+    };
+};
+
+&glidepoint_split {
+    device = <&glidepoint>;
+
+    input-processors = <&zip_xy_transform (INPUT_TRANSFORM_XY_SWAP | INPUT_TRANSFORM_X_INVERT | INPUT_TRANSFORM_Y_INVERT)>;
+};
+```
+
+The `input-processors` property on the input split is optional, and only necessary if the input needs to be fixed up before it is sent to the central.
+
+The specifics of where the pointing device node goes will depend on the specific hardware. _Most_ pointing hardware uses either SPI or I2C for communication, and will be nested under a properly configured bus node, e.g. `&pro_micro_i2c` or for a complete onboard setup, `&i2c3`. See the documentation on [pin control](./pinctrl.mdx) if you need to configure the pins for an I2C or SPI bus.
+
+The specifics of the properties required to set for a given driver will vary; always consult the devicetree bindings file for the specific driver to see what properties can be set.
+
+### 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:
+
+```dts
+#include "common.dtsi"
+
+&glidepoint_listener {
+    status = "okay";
+};
+```
+
+  </TabItem>
+</Tabs>
diff --git a/docs/docs/features/pointing.md b/docs/docs/features/pointing.md
@@ -0,0 +1,39 @@
+---
+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_POINTING=y` in your config. See the [pointer configuration](../config/pointing.md) for the full details.
+
+:::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](bluetooth.md#refreshing-the-hid-descriptor) once you enable the feature.
+
+:::
+
+## Mouse Emulation
+
+Mouse emulation allows you to use your keyboard as a pointing device without using dedicated pointer hardware, like an integrated trackpad, trackball, etc. By adding new bindings in your keymap like `&mmv MOVE_UP` you can make key presses send mouse HID events to your connected hosts.
+
+See the [mouse emulation behaviors](../keymaps/behaviors/mouse-emulation.md) for details.
+
+## Physical Pointing Devices
+
+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.
+
+## Input Processors
+
+Input processors are small pieces of functionality that process and optionally modify events generated from emulated and physical pointing devices. Processors can do things like scaling movement values to make them larger or smaller for detailed work, swapping the event types to turn movements into scroll events, or temporarily enabling an extra layer while the pointer is in use.
+
+For more details, see the [input processors](../keymaps/input-processors/index.md) section of the keymap documentation.
+
+## Input Listeners
+
+Listeners are the key piece that integrate the low level input devices to the rest of the ZMK system. In particular, listeners subscribe to input events from the linked device, and when a given event occurs (e.g. X/Y movement), apply any input processors before sending those events to the HID system for notification to the host. The main way to modify the way a pointer behaves is by configuring the input processors for a given listener.
+
+For more details on assigning processors to your listeners, see the [input processor usage](../keymaps/input-processors/usage.md) documentation.
diff --git 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