Skip to main content

Pointing Devices

ZMK's pointing device support builds upon the Zephyr input API 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 for a variety of hardware.

Pointing devices are also supported on split peripherals, with some additional configuration using the input split device. The configuration details will thus vary depending on if you are adding a pointing device to a split peripheral as opposed to a unibody keyboard or split central part.

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 if you need to configure the pins for an I2C or SPI bus.

This node should always be set up in the .overlay/.dts file for the keyboard side that has the device attached to it.

For example, if setting up an SPI device, a node like following would be added to the .overlay/.dts file for the keyboard, like <keyboard>.overlay:

&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 and Input Split 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 for the full details.

If your pointing device is on a split peripheral part, you also need to define and use an input split device on all keyboard parts.

To add a listener for the above device, add to your .overlay/.dts file for the keyboard a node like the following:

<keyboard>.overlay
/ {
    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. 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:

#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)>;
    };
};

Configuration Setting​

If your keyboard hardware includes a pointing device by default, you can enable the ZMK_POINTING config in your keyboard definition. You can do that in your Kconfig.defconfig file, where you can also enable the config for the communication protocol (e.g. SPI, I2C) used by the pointing device:

Kconfig.defconfig
if SHIELD_MY_KEYBOARD

# Other keyboard settings

config ZMK_POINTING
    default y

# Assuming pointing device uses SPI
config SPI
    default y

endif

If the hardware is optional, users should set CONFIG_ZMK_POINTING=y manually in their user configuration file, along with the config for the protocol.