zmk_mouse_support.md

Edit 2024-02-05:

The instructions below are outdated.

There is an official PR (#2027) for mouse functionality. You should use that rather than what is described below.

See comments [1, 2] below.

ZMK mouse support

When looking to add mouse support, I originally found instructions for how to go about it on Reddit. I was later pointed out to this message on the ZMK Discord (invite).

Repository with mouse support: FTC.

Documentation for for beta testing, including how to make a build off of a different repo such as the one mentioned above. Some documentation about mouse support found here; can be complemented by looking at the source code, here.

EDIT 2022-12-10: Added additional configuration options for scroll wheel speed tweaks.
EDIT 2022-12-09: Added additional configuration options which can be used to tweak mouse movement speed.

How-to

Step one, use the custom repository mentioned above in config/west.yml:

manifest:
  remotes:
    - name: zmkfirmware
      url-base: https://github.com/ftc/     # <--- CHANGE REPO
  projects:
    - name: zmk
      remote: zmkfirmware
      revision: mouse-ftc                   # <--- CHANGE REVISION
      import: app/west.yml
  self:
    path: config

Step 2, add necessary config line in config/YOURBOARD.conf:

CONFIG_ZMK_SLEEP=y
CONFIG_ZMK_MOUSE=y                          /* <--- ADD MOUSE SUPPORT */

Step 3, add support in the keyboard layout, config/YOURBOARD.keymap:

a) Necessary include in the header:

#include <dt-bindings/zmk/mouse.h>

b) Binds, like for instance:

&mkp LCLK       &mkp RCLK
&mmv MOVE_UP    &mmv MOVE_DOWN
&mmv MOVE_LEFT  &mmv MOVE_RIGHT

Step 4, build it; install on the board.

Step 5, unpair and repair the keyboard for it to be recognised as a pointer device as well.

Additional, optional configuration

To adjust mouse movement speed, the following can be used in config/YOURBOARD.keymap, before the keymap {}.

#define U_MOUSE_MOVE_MAX 1400                     /* <--- New max speed setting (default: 600) */
#undef MOVE_UP
#undef MOVE_DOWN
#undef MOVE_LEFT
#undef MOVE_RIGHT
#define MOVE_UP MOVE_VERT(-U_MOUSE_MOVE_MAX)
#define MOVE_DOWN MOVE_VERT(U_MOUSE_MOVE_MAX)
#define MOVE_LEFT MOVE_HOR(-U_MOUSE_MOVE_MAX)
#define MOVE_RIGHT MOVE_HOR(U_MOUSE_MOVE_MAX)

&mmv {
	time-to-max-speed-ms = <400>;             /* <--- How long time until max speed is reached (default: 500) */
};

To adjust scroll wheel, use something like the following:

#define U_MOUSE_SCROLL_MAX 100                    /* <--- New max speed setting (default: 10) */

#undef SCROLL_UP
#undef SCROLL_DOWN
#undef SCROLL_LEFT
#undef SCROLL_RIGHT
#define SCROLL_UP SCROLL_VERT(U_MOUSE_SCROLL_MAX)
#define SCROLL_DOWN SCROLL_VERT(-U_MOUSE_SCROLL_MAX)
#define SCROLL_LEFT SCROLL_HOR(-U_MOUSE_SCROLL_MAX)
#define SCROLL_RIGHT SCROLL_HOR(U_MOUSE_SCROLL_MAX)

&mwh {
  time-to-max-speed-ms = <500>;                 /* <--- How long time until max speed is reached */
};

FYI for anyone using this as a reference: You should now be using the official PR zmkfirmware/zmk#2027 if you want mouse keys functionality with moving and scrolling (see beta testing instructions).

Compared to above instructions, you also need to make these changes:

• Use &msc instead of &mwh
• Use *_X/Y instead of *_HOR/VERT (e.g. SCROLL_X instead of SCROLL_HOR

The branch ftc/mouse-ftc that is documented here is massively outdated and has already caused issues when people try to use it with other ZMK functionality or hardware that is recent.

PS: If you are creating documentation outside the official docs and sharing with others, keeping it up-to-date or at least putting an "this is not updated" notice at the beginning would be good practice.

FYI for anyone using this as a reference: You should now be using the official PR zmkfirmware/zmk#2027 if you want mouse keys functionality with moving and scrolling (see beta testing instructions).

Compared to above instructions, you also need to make these changes:

• Use &msc instead of &mwh
• Use *_X/Y instead of *_HOR/VERT (e.g. SCROLL_X instead of SCROLL_HOR

The branch ftc/mouse-ftc that is documented here is massively outdated and has already caused issues when people try to use it with other ZMK functionality or hardware that is recent.

PS: If you are creating documentation outside the official docs and sharing with others, keeping it up-to-date or at least putting an "this is not updated" notice at the beginning would be good practice.

Thnx! Are there any docs regarding the implementation details that you know of?

PS: If you are creating documentation outside the official docs and sharing with others, keeping it up-to-date or at least putting an "this is not updated" notice at the beginning would be good practice.

Excellent advice! Thank you for taking the time to mention it. Have updated.

@Synow There isn't official docs at the moment, but gist's examples mostly apply (besides the changes I noted above). I am planning to contribute the docs update to the official PR when I get a chance, at which point we can point people to the PR docs preview page.

You also need to add this into your kepmap if using zmkfirmware/zmk#2027

#include <behaviors/mouse_keys.dtsi>

This gives you the use of mmv, msc, and mkp