From c3a7c1f79fec5217b317a838a052d3baf4d4fdd4 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Mon, 9 Dec 2024 23:33:06 -0800 Subject: [PATCH 1/3] docs: Add missing code fence languages in pointing --- docs/docs/keymaps/behaviors/mouse-emulation.md | 16 ++++++++-------- docs/docs/keymaps/input-processors/index.md | 2 +- .../docs/keymaps/input-processors/transformer.md | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/docs/keymaps/behaviors/mouse-emulation.md b/docs/docs/keymaps/behaviors/mouse-emulation.md index 6726bad28b6..13cad5c0ec8 100644 --- a/docs/docs/keymaps/behaviors/mouse-emulation.md +++ b/docs/docs/keymaps/behaviors/mouse-emulation.md @@ -18,7 +18,7 @@ The mouse functionality will not work over BLE until that is done. To use any of the behaviors documented here, the ZMK mouse feature must be enabled explicitly via a config option: -``` +```ini CONFIG_ZMK_POINTING=y ``` @@ -28,7 +28,7 @@ To make it easier to encode the HID mouse button and move/scroll speed numeric v the [`dt-bindings/zmk/pointing.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/pointing.h) header provided by ZMK near the top: -``` +```dts #include ``` @@ -66,13 +66,13 @@ Mouse buttons 4 and 5 typically map to "back" and "forward" actions in most appl The following will send a left click press when the binding is triggered: -``` +```dts &mkp LCLK ``` This example will send press of the fourth mouse button when the binding is triggered: -``` +```dts &mkp MB4 ``` @@ -110,13 +110,13 @@ Additionally, if you want to pass a different max speed than the default for the The following will send a down mouse movement event to the host when pressed/held: -``` +```dts &mmv MOVE_DOWN ``` The following will send a left mouse movement event to the host when pressed/held: -``` +```dts &mmv MOVE_LEFT ``` @@ -154,13 +154,13 @@ Additionally, if you want to pass a different max speed than the default for the The following will send a scroll down event to the host when pressed/held: -``` +```dts &msc SCRL_DOWN ``` The following will send a scroll left event to the host when pressed/held: -``` +```dts &msc SCRL_LEFT ``` diff --git a/docs/docs/keymaps/input-processors/index.md b/docs/docs/keymaps/input-processors/index.md index 489003b8303..26b95e19bdc 100644 --- a/docs/docs/keymaps/input-processors/index.md +++ b/docs/docs/keymaps/input-processors/index.md @@ -19,7 +19,7 @@ Below is a summary of pre-defined input processors and user-definable input proc A set of predefined input processors is available by adding the following at the top of your keymap/overlay file: -``` +```dts #include ``` diff --git a/docs/docs/keymaps/input-processors/transformer.md b/docs/docs/keymaps/input-processors/transformer.md index 155e63707dd..1c4a531ec10 100644 --- a/docs/docs/keymaps/input-processors/transformer.md +++ b/docs/docs/keymaps/input-processors/transformer.md @@ -13,7 +13,7 @@ The following transforms are available, by including the [`dt-bindings/zmk/input_transform.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/input_transform.h) header provided by ZMK near the top of your keymap/overlay: -``` +```dts #include ``` From 03c075197de0e17bda06afdcc32ad05da465a161 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Mon, 9 Dec 2024 23:44:26 -0800 Subject: [PATCH 2/3] docs: Fix default msc exponent in example --- docs/docs/keymaps/behaviors/mouse-emulation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/keymaps/behaviors/mouse-emulation.md b/docs/docs/keymaps/behaviors/mouse-emulation.md index 13cad5c0ec8..dcd1fb70f09 100644 --- a/docs/docs/keymaps/behaviors/mouse-emulation.md +++ b/docs/docs/keymaps/behaviors/mouse-emulation.md @@ -202,6 +202,6 @@ Both `&mmv` and `&msc` are instances of the `"zmk,behavior-input-two-axis"` beha x-input-code = ; y-input-code = ; time-to-max-speed-ms = <300>; - acceleration-exponent = <1>; + acceleration-exponent = <0>; }; ``` From cfbab6e57180c746f3496a4966ee6834e511e9b7 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Tue, 10 Dec 2024 17:20:06 -0800 Subject: [PATCH 3/3] docs: Make pointing hardware integration follow semantic structure --- .../hardware-integration/pointing.mdx | 145 ++++++++++++------ 1 file changed, 99 insertions(+), 46 deletions(-) diff --git a/docs/docs/development/hardware-integration/pointing.mdx b/docs/docs/development/hardware-integration/pointing.mdx index df7dfaefb8c..031c6897ff9 100644 --- a/docs/docs/development/hardware-integration/pointing.mdx +++ b/docs/docs/development/hardware-integration/pointing.mdx @@ -1,30 +1,48 @@ --- title: Pointing Devices +toc_max_heading_level: 2 --- 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. +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: +Pointing devices are also supported on split peripherals, with some additional configuration using the [input split device](../../config/pointing.md#input-split). +The configuration 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. - - +export const SplitTabs = (props) => ( + + + {/* eslint-disable-next-line */} + {props.children} + + + +); ## 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. +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: +This node should always be set up in the `.overlay`/`.dts` file for the keyboard side that has the device attached to it. -```dts + + + +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), a node like following would be added to the `.overlay`/`.dts` file for the unibody or central part: + +```dts title=".overlay" &pro_micro_spi { status = "okay"; cs-gpios = <&pro_micro 19 GPIO_ACTIVE_LOW>; @@ -43,33 +61,50 @@ For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr }; ``` -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 +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), a node like following would be added to the `.overlay`/`.dts` file for the peripheral part: -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 title=".overlay" +&pro_micro_spi { + status = "okay"; + cs-gpios = <&pro_micro 19 GPIO_ACTIVE_LOW>; -```dts -/ { - glidepoint_listener { - compatible = "zmk,input-listener"; - device = <&glidepoint>; + 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; }; }; ``` -## 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: +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. -```dts -#include +## 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, add to your `.overlay`/`.dts` file for the unibody or central part a node like the following: +```dts title=".overlay" / { 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)>; }; }; ``` @@ -77,21 +112,21 @@ Some physical pointing devices may be generating input events that need adjustme -## 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 Configuration -### Shared +When a pointing device is on a peripheral, 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. -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. +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. +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 +```dts title="-pointing.dtsi" / { split_inputs { #address-cells = <1>; @@ -111,17 +146,18 @@ Input splits need to be nested under a parent node that properly sets `#address- }; ``` -### Peripheral +### Peripheral Configuration 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" +```dts title=".overlay" +// Pull in the shared configuration +#include "-pointing.dtsi" +// Node added in Input Device section above &pro_micro_spi { status = "okay"; cs-gpios = <&pro_micro 19 GPIO_ACTIVE_LOW>; @@ -139,6 +175,7 @@ In the peripheral .overlay/.dts file, we do the following: }; }; +// Overrides for the input-split child node &glidepoint_split { device = <&glidepoint>; @@ -146,18 +183,15 @@ In the peripheral .overlay/.dts file, we do the following: }; ``` -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 [`input-processors` property](#input-processors) 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. +### Central Configuration -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. +Here we first include the shared file, and then enable the [input listener](#listener) that is created, but disabled, in our shared file: -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" +```dts title=".overlay" +#include "-pointing.dtsi" &glidepoint_listener { status = "okay"; @@ -165,4 +199,23 @@ On the central, the input split acts as an input device, receiving events from t ``` - + + +## 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 listener defined in the previous section with an input processor that inverts and swaps the X/Y axes: + +```dts +#include + +/ { + 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)>; + }; +}; +```