diff --git a/docs/docs/development/hardware-integration/pointing.md b/docs/docs/development/hardware-integration/pointing.mdx similarity index 63% rename from docs/docs/development/hardware-integration/pointing.md rename to docs/docs/development/hardware-integration/pointing.mdx index 0e00c776c22..327e1e3487d 100644 --- a/docs/docs/development/hardware-integration/pointing.md +++ b/docs/docs/development/hardware-integration/pointing.mdx @@ -2,13 +2,27 @@ title: Pointing Devices --- +import Tabs from "@theme/Tabs"; +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: + + + + ## Input Device -The starting point to any integration of a physical pointing device is the device node 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 a device that uses SPI, you may have a node like: +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 { @@ -60,6 +74,9 @@ 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. @@ -96,11 +113,32 @@ Input splits need to be nested under a parent node that properly sets the `#addr ### Peripheral -On the peripheral, first include the shared file, and then update the input split to reference the pointer device that should be proxied: +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>; @@ -108,7 +146,11 @@ On the peripheral, first include the shared file, and then update the input spli }; ``` -The `input-processors` property is optional, and only necessary if the input needs to be fixed up before it is sent to the central. +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 @@ -121,3 +163,6 @@ On the central, the input split acts as an input device, receiving events from t status = "okay"; }; ``` + + +