feat(mouse): Initial mouse keys support.

* Add HID report/descriptor for a new report with mouse buttons, and x/y/wheel deltas. * New mouse key press behavior for press/release of mouse keys. * Add constants for HID main item values (e.g. data/array/absolute) * Define and use constants for our HID report IDs.
zmkfirmware · Nov 13, 2023 · bd2dd9e · bd2dd9e
1 parent 91aa337
commit bd2dd9e
Show file tree

Hide file tree

Showing 27 changed files with 616 additions and 1 deletion.
diff --git a/app/CMakeLists.txt b/app/CMakeLists.txt
@@ -31,12 +31,14 @@ target_sources_ifdef(CONFIG_ZMK_EXT_POWER app PRIVATE src/ext_power_generic.c)
 target_sources(app PRIVATE src/events/activity_state_changed.c)
 target_sources(app PRIVATE src/events/position_state_changed.c)
 target_sources(app PRIVATE src/events/sensor_event.c)
+target_sources(app PRIVATE src/events/mouse_button_state_changed.c)
 target_sources_ifdef(CONFIG_ZMK_WPM app PRIVATE src/events/wpm_state_changed.c)
 target_sources_ifdef(CONFIG_USB_DEVICE_STACK app PRIVATE src/events/usb_conn_state_changed.c)
 target_sources(app PRIVATE src/behaviors/behavior_reset.c)
 target_sources_ifdef(CONFIG_ZMK_EXT_POWER app PRIVATE src/behaviors/behavior_ext_power.c)
 if ((NOT CONFIG_ZMK_SPLIT) OR CONFIG_ZMK_SPLIT_ROLE_CENTRAL)
  target_sources(app PRIVATE src/hid.c)
+ target_sources_ifdef(CONFIG_ZMK_MOUSE app PRIVATE src/mouse.c)
  target_sources(app PRIVATE src/behaviors/behavior_key_press.c)
  target_sources_ifdef(CONFIG_ZMK_BEHAVIOR_KEY_TOGGLE app PRIVATE src/behaviors/behavior_key_toggle.c)
  target_sources(app PRIVATE src/behaviors/behavior_hold_tap.c)
@@ -54,6 +56,7 @@ if ((NOT CONFIG_ZMK_SPLIT) OR CONFIG_ZMK_SPLIT_ROLE_CENTRAL)
  target_sources_ifdef(CONFIG_ZMK_BEHAVIOR_SENSOR_ROTATE app PRIVATE src/behaviors/behavior_sensor_rotate.c)
  target_sources_ifdef(CONFIG_ZMK_BEHAVIOR_SENSOR_ROTATE_VAR app PRIVATE src/behaviors/behavior_sensor_rotate_var.c)
  target_sources_ifdef(CONFIG_ZMK_BEHAVIOR_SENSOR_ROTATE_COMMON app PRIVATE src/behaviors/behavior_sensor_rotate_common.c)
+ target_sources_ifdef(CONFIG_ZMK_BEHAVIOR_MOUSE_KEY_PRESS app PRIVATE src/behaviors/behavior_mouse_key_press.c)
  target_sources(app PRIVATE src/combo.c)
  target_sources(app PRIVATE src/behaviors/behavior_tap_dance.c)
  target_sources(app PRIVATE src/behavior_queue.c)

diff --git a/app/Kconfig b/app/Kconfig
@@ -154,6 +154,10 @@ config ZMK_BLE_CONSUMER_REPORT_QUEUE_SIZE
  int "Max number of consumer HID reports to queue for sending over BLE"
  default 5
 
+config ZMK_BLE_MOUSE_REPORT_QUEUE_SIZE
+ int "Max number of mouse HID reports to queue for sending over BLE"
+ default 20
+
 config ZMK_BLE_CLEAR_BONDS_ON_START
  bool "Configuration that clears all bond information from the keyboard on startup."
  default n
@@ -313,6 +317,15 @@ endif
 #Display/LED Options
 endmenu
 
+menu "Mouse Options"
+
+config ZMK_MOUSE
+ bool "Enable ZMK mouse emulation"
+ default n
+
+#Mouse Options
+endmenu
+
 menu "Power Management"
 
 config ZMK_BATTERY_REPORTING

diff --git a/app/Kconfig.behaviors b/app/Kconfig.behaviors
@@ -6,6 +6,11 @@ config ZMK_BEHAVIOR_KEY_TOGGLE
  default y
  depends on DT_HAS_ZMK_BEHAVIOR_KEY_TOGGLE_ENABLED
 
+config ZMK_BEHAVIOR_MOUSE_KEY_PRESS
+ bool
+ default y
+ depends on DT_HAS_ZMK_BEHAVIOR_MOUSE_KEY_PRESS_ENABLED
+ imply ZMK_MOUSE
 
 config ZMK_BEHAVIOR_SENSOR_ROTATE_COMMON
  bool

diff --git a/app/dts/behaviors.dtsi b/app/dts/behaviors.dtsi
@@ -18,4 +18,5 @@
 #include <behaviors/caps_word.dtsi>
 #include <behaviors/key_repeat.dtsi>
 #include <behaviors/backlight.dtsi>
-#include <behaviors/macros.dtsi>
+#include <behaviors/macros.dtsi>
+#include <behaviors/mouse_key_press.dtsi>
diff --git a/app/dts/behaviors/mouse_key_press.dtsi b/app/dts/behaviors/mouse_key_press.dtsi
@@ -0,0 +1,9 @@
+/ {
+ behaviors {
+ /omit-if-no-ref/ mkp: behavior_mouse_key_press {
+ compatible = "zmk,behavior-mouse-key-press";
+ label = "MOUSE_KEY_PRESS";
+ #binding-cells = <1>;
+ };
+ };
+};
diff --git a/app/dts/bindings/behaviors/zmk,behavior-mouse-key-press.yaml b/app/dts/bindings/behaviors/zmk,behavior-mouse-key-press.yaml
@@ -0,0 +1,5 @@
+description: Mouse key press/release behavior
+
+compatible: "zmk,behavior-mouse-key-press"
+
+include: one_param.yaml
diff --git a/app/include/dt-bindings/zmk/hid_usage_pages.h b/app/include/dt-bindings/zmk/hid_usage_pages.h
@@ -26,6 +26,7 @@
 #define HID_USAGE_GDV (0x06) // Generic Device Controls
 #define HID_USAGE_KEY (0x07) // Keyboard/Keypad
 #define HID_USAGE_LED (0x08) // LED
+#define HID_USAGE_BUTTON (0x09) // Button
 #define HID_USAGE_TELEPHONY (0x0B) // Telephony Device
 #define HID_USAGE_CONSUMER (0x0C) // Consumer
 #define HID_USAGE_DIGITIZERS (0x0D) // Digitizers

diff --git a/app/include/dt-bindings/zmk/mouse.h b/app/include/dt-bindings/zmk/mouse.h
@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2020 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+#pragma once
+
+/* Mouse press behavior */
+/* Left click */
+#define MB1 (0x01)
+#define LCLK (MB1)
+
+/* Right click */
+#define MB2 (0x02)
+#define RCLK (MB2)
+
+/* Middle click */
+#define MB3 (0x04)
+#define MCLK (MB3)
+
+#define MB4 (0x08)
+
+#define MB5 (0x10)
diff --git a/app/include/zmk/endpoints.h b/app/include/zmk/endpoints.h
@@ -69,3 +69,7 @@ int zmk_endpoints_toggle_transport(void);
 struct zmk_endpoint_instance zmk_endpoints_selected(void);
 
 int zmk_endpoints_send_report(uint16_t usage_page);
+
+#if IS_ENABLED(CONFIG_ZMK_MOUSE)
+int zmk_endpoints_send_mouse_report();
+#endif // IS_ENABLE(CONFIG_ZMK_MOUSE)
diff --git a/app/include/zmk/events/mouse_button_state_changed.h b/app/include/zmk/events/mouse_button_state_changed.h
@@ -0,0 +1,26 @@
+
+/*
+ * Copyright (c) 2020 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+#include <zmk/hid.h>
+#include <zmk/event_manager.h>
+#include <zmk/mouse.h>
+
+struct zmk_mouse_button_state_changed {
+ zmk_mouse_button_t buttons;
+ bool state;
+ int64_t timestamp;
+};
+
+ZMK_EVENT_DECLARE(zmk_mouse_button_state_changed);
+
+static inline struct zmk_mouse_button_state_changed_event *
+zmk_mouse_button_state_changed_from_encoded(uint32_t encoded, bool pressed, int64_t timestamp) {
+ return new_zmk_mouse_button_state_changed((struct zmk_mouse_button_state_changed){
+ .buttons = ZMK_HID_USAGE_ID(encoded), .state = pressed, .timestamp = timestamp});
+}
diff --git a/app/include/zmk/hid.h b/app/include/zmk/hid.h
@@ -10,10 +10,15 @@
 #include <zephyr/usb/class/usb_hid.h>
 
 #include <zmk/keys.h>
+#if IS_ENABLED(CONFIG_ZMK_MOUSE)
+#include <zmk/mouse.h>
+#endif // IS_ENABLED(CONFIG_ZMK_MOUSE)
+
 #include <dt-bindings/zmk/hid_usage.h>
 #include <dt-bindings/zmk/hid_usage_pages.h>
 
 #define ZMK_HID_KEYBOARD_NKRO_MAX_USAGE HID_USAGE_KEY_KEYPAD_EQUAL
+#define ZMK_HID_MOUSE_NUM_BUTTONS 0x05
 
 // See https://www.usb.org/sites/default/files/hid1_11.pdf section 6.2.2.4 Main Items
 
@@ -46,6 +51,7 @@
 
 #define ZMK_HID_REPORT_ID_KEYBOARD 0x01
 #define ZMK_HID_REPORT_ID_CONSUMER 0x02
+#define ZMK_HID_REPORT_ID_MOUSE 0x03
 
 static const uint8_t zmk_hid_report_desc[] = {
  HID_USAGE_PAGE(HID_USAGE_GEN_DESKTOP),
@@ -114,6 +120,39 @@ static const uint8_t zmk_hid_report_desc[] = {
  HID_REPORT_COUNT(CONFIG_ZMK_HID_CONSUMER_REPORT_SIZE),
  HID_INPUT(ZMK_HID_MAIN_VAL_DATA | ZMK_HID_MAIN_VAL_ARRAY | ZMK_HID_MAIN_VAL_ABS),
  HID_END_COLLECTION,
+
+#if IS_ENABLED(CONFIG_ZMK_MOUSE)
+ HID_USAGE_PAGE(HID_USAGE_GD),
+ HID_USAGE(HID_USAGE_GD_MOUSE),
+ HID_COLLECTION(HID_COLLECTION_APPLICATION),
+ HID_REPORT_ID(ZMK_HID_REPORT_ID_MOUSE),
+ HID_USAGE(HID_USAGE_GD_POINTER),
+ HID_COLLECTION(HID_COLLECTION_PHYSICAL),
+ HID_USAGE_PAGE(HID_USAGE_BUTTON),
+ HID_USAGE_MIN8(0x1),
+ HID_USAGE_MAX8(ZMK_HID_MOUSE_NUM_BUTTONS),
+ HID_LOGICAL_MIN8(0x00),
+ HID_LOGICAL_MAX8(0x01),
+ HID_REPORT_SIZE(0x01),
+ HID_REPORT_COUNT(0x5),
+ HID_INPUT(ZMK_HID_MAIN_VAL_DATA | ZMK_HID_MAIN_VAL_VAR | ZMK_HID_MAIN_VAL_ABS),
+ // Constant padding for the last 3 bits.
+ HID_REPORT_SIZE(0x03),
+ HID_REPORT_COUNT(0x01),
+ HID_INPUT(ZMK_HID_MAIN_VAL_CONST | ZMK_HID_MAIN_VAL_VAR | ZMK_HID_MAIN_VAL_ABS),
+ // Some OSes ignore pointer devices without X/Y data.
+ HID_USAGE_PAGE(HID_USAGE_GEN_DESKTOP),
+ HID_USAGE(HID_USAGE_GD_X),
+ HID_USAGE(HID_USAGE_GD_Y),
+ HID_USAGE(HID_USAGE_GD_WHEEL),
+ HID_LOGICAL_MIN8(-0x7F),
+ HID_LOGICAL_MAX8(0x7F),
+ HID_REPORT_SIZE(0x08),
+ HID_REPORT_COUNT(0x03),
+ HID_INPUT(ZMK_HID_MAIN_VAL_DATA | ZMK_HID_MAIN_VAL_VAR | ZMK_HID_MAIN_VAL_REL),
+ HID_END_COLLECTION,
+ HID_END_COLLECTION,
+#endif // IS_ENABLED(CONFIG_ZMK_MOUSE)
 };
 
 #if IS_ENABLED(CONFIG_ZMK_USB_BOOT)
@@ -163,6 +202,21 @@ struct zmk_hid_consumer_report {
  struct zmk_hid_consumer_report_body body;
 } __packed;
 
+#if IS_ENABLED(CONFIG_ZMK_MOUSE)
+struct zmk_hid_mouse_report_body {
+ zmk_mouse_button_flags_t buttons;
+ int8_t d_x;
+ int8_t d_y;
+ int8_t d_wheel;
+} __packed;
+
+struct zmk_hid_mouse_report {
+ uint8_t report_id;
+ struct zmk_hid_mouse_report_body body;
+} __packed;
+
+#endif // IS_ENABLED(CONFIG_ZMK_MOUSE)
+
 zmk_mod_flags_t zmk_hid_get_explicit_mods();
 int zmk_hid_register_mod(zmk_mod_t modifier);
 int zmk_hid_unregister_mod(zmk_mod_t modifier);
@@ -189,9 +243,22 @@ int zmk_hid_press(uint32_t usage);
 int zmk_hid_release(uint32_t usage);
 bool zmk_hid_is_pressed(uint32_t usage);
 
+#if IS_ENABLED(CONFIG_ZMK_MOUSE)
+int zmk_hid_mouse_button_press(zmk_mouse_button_t button);
+int zmk_hid_mouse_button_release(zmk_mouse_button_t button);
+int zmk_hid_mouse_buttons_press(zmk_mouse_button_flags_t buttons);
+int zmk_hid_mouse_buttons_release(zmk_mouse_button_flags_t buttons);
+void zmk_hid_mouse_clear();
+#endif // IS_ENABLED(CONFIG_ZMK_MOUSE)
+
 struct zmk_hid_keyboard_report *zmk_hid_get_keyboard_report();
 struct zmk_hid_consumer_report *zmk_hid_get_consumer_report();
 
 #if IS_ENABLED(CONFIG_ZMK_USB_BOOT)
 zmk_hid_boot_report_t *zmk_hid_get_boot_report();
 #endif
+
+#if IS_ENABLED(CONFIG_ZMK_MOUSE)
+struct zmk_hid_mouse_report *zmk_hid_get_mouse_report();
+#endif // IS_ENABLED(CONFIG_ZMK_MOUSE)
+
diff --git a/app/include/zmk/hog.h b/app/include/zmk/hog.h
@@ -13,3 +13,7 @@ int zmk_hog_init();
 
 int zmk_hog_send_keyboard_report(struct zmk_hid_keyboard_report_body *body);
 int zmk_hog_send_consumer_report(struct zmk_hid_consumer_report_body *body);
+
+#if IS_ENABLED(CONFIG_ZMK_MOUSE)
+int zmk_hog_send_mouse_report(struct zmk_hid_mouse_report_body *body);
+#endif // IS_ENABLED(CONFIG_ZMK_MOUSE)
diff --git a/app/include/zmk/mouse.h b/app/include/zmk/mouse.h
@@ -0,0 +1,12 @@
+/*
+ * Copyright (c) 2021 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+#include <dt-bindings/zmk/mouse.h>
+
+typedef uint8_t zmk_mouse_button_flags_t;
+typedef uint16_t zmk_mouse_button_t;
diff --git a/app/include/zmk/usb_hid.h b/app/include/zmk/usb_hid.h
@@ -10,4 +10,7 @@
 
 int zmk_usb_hid_send_keyboard_report();
 int zmk_usb_hid_send_consumer_report();
+#if IS_ENABLED(CONFIG_ZMK_MOUSE)
+int zmk_usb_hid_send_mouse_report();
+#endif // IS_ENABLED(CONFIG_ZMK_MOUSE)
 void zmk_usb_hid_set_protocol(uint8_t protocol);
diff --git a/app/src/behaviors/behavior_mouse_key_press.c b/app/src/behaviors/behavior_mouse_key_press.c
@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2021 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#define DT_DRV_COMPAT zmk_behavior_mouse_key_press
+
+#include <zephyr/device.h>
+#include <drivers/behavior.h>
+#include <zephyr/logging/log.h>
+
+#include <zmk/behavior.h>
+#include <zmk/event_manager.h>
+#include <zmk/events/mouse_button_state_changed.h>
+
+LOG_MODULE_DECLARE(zmk, CONFIG_ZMK_LOG_LEVEL);
+
+#if DT_HAS_COMPAT_STATUS_OKAY(DT_DRV_COMPAT)
+
+static int behavior_mouse_key_press_init(const struct device *dev) { return 0; };
+
+static int on_keymap_binding_pressed(struct zmk_behavior_binding *binding,
+ struct zmk_behavior_binding_event event) {
+ LOG_DBG("position %d keycode 0x%02X", event.position, binding->param1);
+
+ return ZMK_EVENT_RAISE(
+ zmk_mouse_button_state_changed_from_encoded(binding->param1, true, event.timestamp));
+}
+
+static int on_keymap_binding_released(struct zmk_behavior_binding *binding,
+ struct zmk_behavior_binding_event event) {
+ LOG_DBG("position %d keycode 0x%02X", event.position, binding->param1);
+ return ZMK_EVENT_RAISE(
+ zmk_mouse_button_state_changed_from_encoded(binding->param1, false, event.timestamp));
+}
+
+static const struct behavior_driver_api behavior_mouse_key_press_driver_api = {
+ .binding_pressed = on_keymap_binding_pressed, .binding_released = on_keymap_binding_released};
+
+#define KP_INST(n) \
+ DEVICE_DT_INST_DEFINE(n, behavior_mouse_key_press_init, device_pm_control_nop, NULL, NULL, \
+ APPLICATION, CONFIG_KERNEL_INIT_PRIORITY_DEFAULT, \
+ &behavior_mouse_key_press_driver_api);
+
+DT_INST_FOREACH_STATUS_OKAY(KP_INST)
+
+#endif /* DT_HAS_COMPAT_STATUS_OKAY(DT_DRV_COMPAT) */
diff --git a/app/src/endpoints.c b/app/src/endpoints.c
@@ -191,6 +191,36 @@ int zmk_endpoints_send_report(uint16_t usage_page) {
  return -ENOTSUP;
 }
 
+#if IS_ENABLED(CONFIG_ZMK_MOUSE)
+int zmk_endpoints_send_mouse_report() {
+ switch (current_instance.transport) {
+#if IS_ENABLED(CONFIG_ZMK_USB)
+ case ZMK_TRANSPORT_USB: {
+ int err = zmk_usb_hid_send_mouse_report();
+ if (err) {
+ LOG_ERR("FAILED TO SEND OVER USB: %d", err);
+ }
+ return err;
+ }
+#endif /* IS_ENABLED(CONFIG_ZMK_USB) */
+
+#if IS_ENABLED(CONFIG_ZMK_BLE)
+ case ZMK_TRANSPORT_BLE: {
+ struct zmk_hid_mouse_report *mouse_report = zmk_hid_get_mouse_report();
+ int err = zmk_hog_send_mouse_report(&mouse_report->body);
+ if (err) {
+ LOG_ERR("FAILED TO SEND OVER HOG: %d", err);
+ }
+ return err;
+ }
+#endif /* IS_ENABLED(CONFIG_ZMK_BLE) */
+ }
+
+ LOG_ERR("Unsupported endpoint transport %d", current_instance.transport);
+ return -ENOTSUP;
+}
+#endif // IS_ENABLED(CONFIG_ZMK_MOUSE)
+
 #if IS_ENABLED(CONFIG_SETTINGS)
 
 static int endpoints_handle_set(const char *name, size_t len, settings_read_cb read_cb,
@@ -295,6 +325,9 @@ static int zmk_endpoints_init(const struct device *_arg) {
 static void disconnect_current_endpoint() {
  zmk_hid_keyboard_clear();
  zmk_hid_consumer_clear();
+#if IS_ENABLED(CONFIG_ZMK_MOUSE)
+ zmk_hid_mouse_clear();
+#endif // IS_ENABLED(CONFIG_ZMK_MOUSE)
 
  zmk_endpoints_send_report(HID_USAGE_KEY);
  zmk_endpoints_send_report(HID_USAGE_CONSUMER);

diff --git a/app/src/events/mouse_button_state_changed.c b/app/src/events/mouse_button_state_changed.c
@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2020 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#include <zmk/events/mouse_button_state_changed.h>
+
+ZMK_EVENT_IMPL(zmk_mouse_button_state_changed);