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 */
};

I've tried rebasing ftc's fork, but unfortunately, I must have gone wrong with some merge conflicts, so it wasn't working 😅 @baggiiiie You're talking about this repository from @urob ? I still have issues.

To answer some questions. ftc's fork is very outdated by now. As of today, my mouse repo is otherwise up to date with upstream ZMK. If you want additional experimental features like smart layers or swapper, the main branch of that repo adds mouse emulation support alongside various common features (see the readme in that branch for a list). I try to keep both branches up to date with the latest ZMK updates (but this may change in the future).

Note that if you are coming from ftc's branch, there have been some breaking changes to ZMK in the meantime, which require some edits to the keymap. The most common change needed is to replace &reset with &sys_reset in the keymap. If you are using custom board definitions, you may need additional changes. See this blog post for details.

For troubleshooting, updates on the mouse support and ZMK, or any other help in general, I highly recommend checking out the ZMK discord. The community has been most friendly and helpful.

I've tried rebasing ftc's fork, but unfortunately, I must have gone wrong with some merge conflicts, so it wasn't working 😅 @baggiiiie You're talking about this repository from @urob ? I still have issues.

yes and urob has given some insights on this issue. hope you have resolved it and it's up and running. discord is a good place to seek help too, do consider asking on that platform

Hi all,

Looks like mouse emulation is poised to be merged into zmk master. There’s a testing branch available. Follow this GitHub issue for more information and updates.

Hi all,

Looks like mouse emulation is poised to be merged into zmk master. There’s a testing branch available. Follow this GitHub issue for more information and updates.

That's lit! Can't wait!

Hey everyone! I was successful in using @urob's clone to compile the mouse compatible keymap.
I can't wait to see native support in the main repo!

I also had success with @urob's fork. It's worth noting that changing the max speed setting from 10 to 100 (as documented above) was necessary for me to get scroll wheel movements working with rotary encoders. You can see that in action here.

A part of mouse emulation is in the main repo, Look at the latest doc

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

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

Additionally to all the comments above, &mwh SCROLL_UP become &msc SCRL_UP and so on.

And if adjusting scroll speeds use #define SCRL_UP MOVE_Y(ZMK_MOUSE_DEFAULT_SCRL_VAL) and such.

This work wireless?

This work wireless?

Yes