zmk/docs/docs/keymaps/behaviors/mouse-emulation.md

title, sidebar_label

title	sidebar_label
Mouse Emulation Behaviors	Mouse Emulation

Summary

Mouse emulation behaviors send mouse events, including mouse button presses, cursor movement and scrolling.

:::warning[Refreshing the HID descriptor]

Enabling or disabling the mouse emulation feature modifies the HID report descriptor and requires it to be refreshed. The mouse functionality will not work over BLE until that is done.

:::

Configuration Option

To use any of the behaviors documented here, the ZMK mouse feature must be enabled explicitly via a config option:

CONFIG_ZMK_POINTING=y

Mouse Emulation Defines

To make it easier to encode the HID mouse button and move/scroll speed numeric values, include the dt-bindings/zmk/pointing.h header provided by ZMK near the top:

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

Should you wish to override the default movement or scrolling max velocities, you can define the defaults before including the header, e.g.:

#define ZMK_POINTING_DEFAULT_MOVE_VAL 1500  // default: 600
#define ZMK_POINTING_DEFAULT_SCRL_VAL 20    // default: 10

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

Mouse Button Press

This behavior can press/release up to 5 mouse buttons.

Behavior Binding

• Reference: &mkp
• Parameter: A uint8 with bits 0 through 4 each referring to a button.

The following defines can be passed for the parameter:

Define	Action
MB1, LCLK	Left click
MB2, RCLK	Right click
MB3, MCLK	Middle click
MB4	Mouse button 4
MB5	Mouse button 5

Mouse buttons 4 and 5 typically map to "back" and "forward" actions in most applications.

Examples

The following will send a left click press when the binding is triggered:

&mkp LCLK

This example will send press of the fourth mouse button when the binding is triggered:

&mkp MB4

Input Processors

If you want to apply any input processors to &mkp you can do so by referencing &mkp_input_listener, e.g.:

&mkp_input_listener {
    input-processors = <&zip_temp_layer 2 2000>;
}

Mouse Move

This behavior sends mouse X/Y movement events to the connected host.

Behavior Binding

• Reference: &mmv
• Parameter: A uint32 with 16-bits each used for vertical and horizontal max velocity.

The following predefined values can be passed for the parameter:

Define	Action
MOVE_UP	Move up
MOVE_DOWN	Move down
MOVE_LEFT	Move left
MOVE_RIGHT	Move right

Additionally, if you want to pass a different max speed than the default for the MOVE_* defines, custom X and Y velocity values can be passed with MOVE_X and MOVE_Y, e.g. MOVE_X(100) or MOVE_Y(-100). Positive values indicate movement directions right or down. Note that the default value of the max speed depends on the value of ZMK_POINTING_DEFAULT_MOVE_VAL.

Examples

The following will send a down mouse movement event to the host when pressed/held:

&mmv MOVE_DOWN

The following will send a left mouse movement event to the host when pressed/held:

&mmv MOVE_LEFT

Input Processors

If you want to apply any input processors to &mmv you can do so by referencing &mmv_input_listener, e.g.:

&mmv_input_listener {
    input-processors = <&zip_temp_layer 2 2000>;
}

Mouse Scroll

This behavior sends vertical and horizontal scroll events to the connected host.

Behavior Binding

• Reference: &msc
• Parameter: A uint32 with 16-bits each used for vertical and horizontal velocity.

The following defines can be passed for the parameter:

Define	Action
SCRL_UP	Scroll up
SCRL_DOWN	Scroll down
SCRL_LEFT	Scroll left
SCRL_RIGHT	Scroll right

Additionally, if you want to pass a different max speed than the default for the SCRL_* defines, custom X and Y velocity values can be passed with MOVE_X and MOVE_Y, e.g. MOVE_X(5) or MOVE_Y(-5). Positive values indicate scroll directions right or up. Note that the default value of the max speed depends on the value of ZMK_POINTING_DEFAULT_SCRL_VAL.

Examples

The following will send a scroll down event to the host when pressed/held:

&msc SCRL_DOWN

The following will send a scroll left event to the host when pressed/held:

&msc SCRL_LEFT

:::note

If you enabled smooth scrolling then you will want to use the same MOVE_UP, MOVE_DOWN, etc values instead of the smaller SCRL_* parameters for more sensible scroll speeds.

:::

Input Processors

If you want to apply any input processors to &msc you can do so by referencing &msc_input_listener, e.g.:

&msc_input_listener {
    input-processors = <&zip_temp_layer 2 2000>;
}

Advanced Configuration

Both &mmv and &msc are instances of the "zmk,behavior-input-two-axis" behavior and can be modified using the two axis input behavior configuration properties. The default settings are as follows:

Mouse Move

&mmv {
    x-input-code = <INPUT_REL_X>;
    y-input-code = <INPUT_REL_Y>;
    time-to-max-speed-ms = <300>;
    acceleration-exponent = <1>;
};

Mouse Scroll

&msc {
    x-input-code = <INPUT_REL_HWHEEL>;
    y-input-code = <INPUT_REL_WHEEL>;
    time-to-max-speed-ms = <300>;
    acceleration-exponent = <1>;
};