englmaxi / zmk-hid-trackball-interface

ZMK trackball interface using HID indicators

This ZMK module allows interfacing with a trackball that can't run ZMK. The state of the HID indicator LEDs is shared between input devices so they can be used for communication. This module provides macros to send commands to the trackball and implements a listener to enable a mouse layer when movement is detected.

Usage

To use, first add this module to your config/west.yml by adding a new entry to remotes and projects:

manifest:
  remotes:
    - name: zmkfirmware
      url-base: https://github.com/zmkfirmware
    - name: englmaxi
      url-base: https://github.com/englmaxi
  projects:
    - name: zmk
      remote: zmkfirmware
      revision: main
      import: app/west.yml
    - name: zmk-hid-trackball-interface
      remote: englmaxi
      revision: main
  self:
    path: config

Then add the following to your keymap:

#include <interfaces/hid-trackball.dtsi>

This gives you access to the following predefined behaviors:

• &tb_cyc_dpi: Cycles between the different DPI options of the trackball.
• &tb_bootloader: Reboots the trackball into the bootloader.
• &tb_tg_scroll: Toggles the trackball between move- and scroll-mode.
• &tb_mo_scroll: Toggles the trackball between move- and scroll-mode while the key is held down.
• &tbs_mt 0 0: &tb_tg_scroll on tap, &tb_mo_scroll on hold.

If you want to automatically change to a layer or enable scrolling and change DPI on specific layers, add this (with the desired layer inside <>) to your keymap:

&hid_trackball_interface {
    automouse-layer = <1>;
    automouse-layer-timeout-ms = <600>;
    scroll-layers = <2>;
    snipe-layers = <3>;
};

• If a layer is defined in automouse-layer, it will be enabled while the mouse is moving.
• automouse-layer-timeout-ms defines how many miliseconds of mouse inactivity are required before the automouse-layer is disabled, the default value is 400 ms.
• If any layers are defined in scroll-layers, &tb_tg_scroll is executed by default when one of those layers is enabled or disabled.
• If any layers are defined in snipe-layers, &tb_cyc_dpi is executed by default when one of those layers is enabled or disabled. (this is only usefull if it cycles between two DPI settings only).

If you use a Ploopy Nano, you can use the modified firmware in trackball_firmware. Otherwise, you need to modify your firmware to listen to specific HID indicator changes.

How does this work?

The idea is based on the lkbm keymap for the Ploopy Nano, created by @aidalgol. It allows sending 2-bit commands by turning NLCK (0b01) and CLCK (0b10) on and off within a specified short time (<25 ms):

• 0b01 ... toggle scroll-mode
• 0b10 ... cycle DPI
• 0b11 ... bootloader

To enable the automouse-layer, the trackball keymap was extended to turn on SLCK while the mouse is moving, which gets detected by this module.

---

Acknowledgements

Inorichi's PMW3610 driver and the original lkbm firmware were major inspirations for implementing this module.