afiqzudinhadi/zmk
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
zmk/app/include/zmk/hid.h
Pete Johanson 6b44d33db2
feat(split): Runtime selection of split transport (#2886) 
feat(split): Runtime selection of split transport

Allow building multiple split transports, and select an active
one based on the transport availability. Wired split availability
depends on additional `detect-gpios` which must be a GPIO pin
that goes active when a wired connection is present.

feat(split): Suspend/resume wired UART devices.

To better support runtime split support, suspend/resume the UART
as necessary to save power when not using the UART.

docs(split): Document adjusting nRF52 UART interrupt priorities

For wired split on nRF52, you may need to adjust the priority for UART
interrupts lower, to ensure the interrupts used for timing sensitive
BT operations can run when needed, so document this in our pinctrl docs.

refactor(split): Restore use of aync UART on nRF52.

With fixes for Zephyr UART driver, re-enable using async API on nRF52.

fix(split): Minor wired split fixes.

Various minor fixes for wired split to avoid spurious TX in half duplex,
etc.

fix: Unconditionally define HID payloads to avoid error.

Don't conditionally define HID indicator payload, to avoid compilation
errors.

docs(split): Expand on details of split transports.

Expand the split keyboard documentation with a more fleshed out section
on the available split trasnports, and what is and isn't supported by
each, including the runtime selection functionality.

---------

Co-authored-by: Nicolas Munnich <98408764+nmunnich@users.noreply.github.com>
2025-06-16 03:45:25 -04:00

392 lines
13 KiB
C
Raw Blame History

/*
* Copyright (c) 2020 The ZMK Contributors
*
* SPDX-License-Identifier: MIT
*/
#pragma once
#include <zephyr/sys/util.h>
#include <zephyr/usb/usb_device.h>
#include <zephyr/usb/class/usb_hid.h>
#include <zmk/keys.h>
#if IS_ENABLED(CONFIG_ZMK_POINTING)
#include <zmk/pointing.h>
#endif // IS_ENABLED(CONFIG_ZMK_POINTING)
#include <dt-bindings/zmk/hid_usage.h>
#include <dt-bindings/zmk/hid_usage_pages.h>
#if IS_ENABLED(CONFIG_ZMK_HID_KEYBOARD_NKRO_EXTENDED_REPORT)
#define ZMK_HID_KEYBOARD_NKRO_MAX_USAGE HID_USAGE_KEY_KEYBOARD_LANG8
#else
#define ZMK_HID_KEYBOARD_NKRO_MAX_USAGE HID_USAGE_KEY_KEYPAD_EQUAL
#endif
#if IS_ENABLED(CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_BASIC)
#define ZMK_HID_CONSUMER_MAX_USAGE 0xFF
#elif IS_ENABLED(CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_FULL)
#define ZMK_HID_CONSUMER_MAX_USAGE 0xFFF
#else
#error "Unknown consumer report usages configuration"
#endif
#if IS_ENABLED(CONFIG_ZMK_HID_REPORT_TYPE_NKRO)
#define ZMK_HID_KEYBOARD_MAX_USAGE ZMK_HID_KEYBOARD_NKRO_MAX_USAGE
#elif IS_ENABLED(CONFIG_ZMK_HID_REPORT_TYPE_HKRO)
#define ZMK_HID_KEYBOARD_MAX_USAGE 0xFF
#else
#error "Unknown keyboard report usages configuration"
#endif
#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
#define ZMK_HID_MAIN_VAL_DATA (0x00 << 0)
#define ZMK_HID_MAIN_VAL_CONST (0x01 << 0)
#define ZMK_HID_MAIN_VAL_ARRAY (0x00 << 1)
#define ZMK_HID_MAIN_VAL_VAR (0x01 << 1)
#define ZMK_HID_MAIN_VAL_ABS (0x00 << 2)
#define ZMK_HID_MAIN_VAL_REL (0x01 << 2)
#define ZMK_HID_MAIN_VAL_NO_WRAP (0x00 << 3)
#define ZMK_HID_MAIN_VAL_WRAP (0x01 << 3)
#define ZMK_HID_MAIN_VAL_LIN (0x00 << 4)
#define ZMK_HID_MAIN_VAL_NON_LIN (0x01 << 4)
#define ZMK_HID_MAIN_VAL_PREFERRED (0x00 << 5)
#define ZMK_HID_MAIN_VAL_NO_PREFERRED (0x01 << 5)
#define ZMK_HID_MAIN_VAL_NO_NULL (0x00 << 6)
#define ZMK_HID_MAIN_VAL_NULL (0x01 << 6)
#define ZMK_HID_MAIN_VAL_NON_VOL (0x00 << 7)
#define ZMK_HID_MAIN_VAL_VOL (0x01 << 7)
#define ZMK_HID_MAIN_VAL_BIT_FIELD (0x00 << 8)
#define ZMK_HID_MAIN_VAL_BUFFERED_BYTES (0x01 << 8)
#define ZMK_HID_REPORT_ID_KEYBOARD 0x01
#define ZMK_HID_REPORT_ID_LEDS 0x01
#define ZMK_HID_REPORT_ID_CONSUMER 0x02
#define ZMK_HID_REPORT_ID_MOUSE 0x03
#ifndef HID_ITEM_TAG_PUSH
#define HID_ITEM_TAG_PUSH 0xA
#endif
#ifndef HID_ITEM_TAG_POP
#define HID_ITEM_TAG_POP 0xB
#endif
#define HID_PUSH HID_ITEM(HID_ITEM_TAG_PUSH, HID_ITEM_TYPE_GLOBAL, 0)
#define HID_POP HID_ITEM(HID_ITEM_TAG_POP, HID_ITEM_TYPE_GLOBAL, 0)
#ifndef HID_PHYSICAL_MIN8
#define HID_PHYSICAL_MIN8(a) HID_ITEM(HID_ITEM_TAG_PHYSICAL_MIN, HID_ITEM_TYPE_GLOBAL, 1), a
#endif
#ifndef HID_PHYSICAL_MAX8
#define HID_PHYSICAL_MAX8(a) HID_ITEM(HID_ITEM_TAG_PHYSICAL_MAX, HID_ITEM_TYPE_GLOBAL, 1), a
#endif
#define HID_USAGE16(a, b) HID_ITEM(HID_ITEM_TAG_USAGE, HID_ITEM_TYPE_LOCAL, 2), a, b
#define HID_USAGE16_SINGLE(a) HID_USAGE16((a & 0xFF), ((a >> 8) & 0xFF))
static const uint8_t zmk_hid_report_desc[] = {
HID_USAGE_PAGE(HID_USAGE_GEN_DESKTOP),
HID_USAGE(HID_USAGE_GD_KEYBOARD),
HID_COLLECTION(HID_COLLECTION_APPLICATION),
HID_REPORT_ID(ZMK_HID_REPORT_ID_KEYBOARD),
HID_USAGE_PAGE(HID_USAGE_KEY),
HID_USAGE_MIN8(HID_USAGE_KEY_KEYBOARD_LEFTCONTROL),
HID_USAGE_MAX8(HID_USAGE_KEY_KEYBOARD_RIGHT_GUI),
HID_LOGICAL_MIN8(0x00),
HID_LOGICAL_MAX8(0x01),
HID_REPORT_SIZE(0x01),
HID_REPORT_COUNT(0x08),
HID_INPUT(ZMK_HID_MAIN_VAL_DATA | ZMK_HID_MAIN_VAL_VAR | ZMK_HID_MAIN_VAL_ABS),
HID_USAGE_PAGE(HID_USAGE_KEY),
HID_REPORT_SIZE(0x08),
HID_REPORT_COUNT(0x01),
HID_INPUT(ZMK_HID_MAIN_VAL_CONST | ZMK_HID_MAIN_VAL_VAR | ZMK_HID_MAIN_VAL_ABS),
#if IS_ENABLED(CONFIG_ZMK_HID_INDICATORS)
HID_USAGE_PAGE(HID_USAGE_LED),
HID_USAGE_MIN8(HID_USAGE_LED_NUM_LOCK),
HID_USAGE_MAX8(HID_USAGE_LED_KANA),
HID_REPORT_SIZE(0x01),
HID_REPORT_COUNT(0x05),
HID_OUTPUT(ZMK_HID_MAIN_VAL_DATA | ZMK_HID_MAIN_VAL_VAR | ZMK_HID_MAIN_VAL_ABS),
HID_USAGE_PAGE(HID_USAGE_LED),
HID_REPORT_SIZE(0x03),
HID_REPORT_COUNT(0x01),
HID_OUTPUT(ZMK_HID_MAIN_VAL_CONST | ZMK_HID_MAIN_VAL_VAR | ZMK_HID_MAIN_VAL_ABS),
#endif // IS_ENABLED(CONFIG_ZMK_HID_INDICATORS)
HID_USAGE_PAGE(HID_USAGE_KEY),
#if IS_ENABLED(CONFIG_ZMK_HID_REPORT_TYPE_NKRO)
HID_LOGICAL_MIN8(0x00),
HID_LOGICAL_MAX8(0x01),
HID_USAGE_MIN8(0x00),
HID_USAGE_MAX8(ZMK_HID_KEYBOARD_NKRO_MAX_USAGE),
HID_REPORT_SIZE(0x01),
HID_REPORT_COUNT(ZMK_HID_KEYBOARD_NKRO_MAX_USAGE + 1),
HID_INPUT(ZMK_HID_MAIN_VAL_DATA | ZMK_HID_MAIN_VAL_VAR | ZMK_HID_MAIN_VAL_ABS),
#elif IS_ENABLED(CONFIG_ZMK_HID_REPORT_TYPE_HKRO)
HID_LOGICAL_MIN8(0x00),
HID_LOGICAL_MAX16(0xFF, 0x00),
HID_USAGE_MIN8(0x00),
HID_USAGE_MAX8(0xFF),
HID_REPORT_SIZE(0x08),
HID_REPORT_COUNT(CONFIG_ZMK_HID_KEYBOARD_REPORT_SIZE),
HID_INPUT(ZMK_HID_MAIN_VAL_DATA | ZMK_HID_MAIN_VAL_ARRAY | ZMK_HID_MAIN_VAL_ABS),
#else
#error "A proper HID report type must be selected"
#endif
HID_END_COLLECTION,
HID_USAGE_PAGE(HID_USAGE_CONSUMER),
HID_USAGE(HID_USAGE_CONSUMER_CONSUMER_CONTROL),
HID_COLLECTION(HID_COLLECTION_APPLICATION),
HID_REPORT_ID(ZMK_HID_REPORT_ID_CONSUMER),
HID_USAGE_PAGE(HID_USAGE_CONSUMER),
#if IS_ENABLED(CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_BASIC)
HID_LOGICAL_MIN8(0x00),
HID_LOGICAL_MAX16(0xFF, 0x00),
HID_USAGE_MIN8(0x00),
HID_USAGE_MAX8(0xFF),
HID_REPORT_SIZE(0x08),
#elif IS_ENABLED(CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_FULL)
HID_LOGICAL_MIN8(0x00),
HID_LOGICAL_MAX16(0xFF, 0x0F),
HID_USAGE_MIN8(0x00),
HID_USAGE_MAX16(0xFF, 0x0F),
HID_REPORT_SIZE(0x10),
#else
#error "A proper consumer HID report usage range must be selected"
#endif
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_POINTING)
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_LOGICAL_MIN16(0xFF, -0x7F),
HID_LOGICAL_MAX16(0xFF, 0x7F),
HID_REPORT_SIZE(0x10),
HID_REPORT_COUNT(0x02),
HID_INPUT(ZMK_HID_MAIN_VAL_DATA | ZMK_HID_MAIN_VAL_VAR | ZMK_HID_MAIN_VAL_REL),
HID_COLLECTION(HID_COLLECTION_LOGICAL),
#if IS_ENABLED(CONFIG_ZMK_POINTING_SMOOTH_SCROLLING)
HID_USAGE(HID_USAGE_GD_RESOLUTION_MULTIPLIER),
HID_LOGICAL_MIN8(0x00),
HID_LOGICAL_MAX8(0x0F),
HID_PHYSICAL_MIN8(0x01),
HID_PHYSICAL_MAX8(0x10),
HID_REPORT_SIZE(0x04),
HID_REPORT_COUNT(0x01),
HID_PUSH,
HID_FEATURE(ZMK_HID_MAIN_VAL_DATA | ZMK_HID_MAIN_VAL_VAR | ZMK_HID_MAIN_VAL_ABS),
#endif // IS_ENABLED(CONFIG_ZMK_POINTING_SMOOTH_SCROLLING)
HID_USAGE(HID_USAGE_GD_WHEEL),
HID_LOGICAL_MIN16(0xFF, -0x7F),
HID_LOGICAL_MAX16(0xFF, 0x7F),
HID_PHYSICAL_MIN8(0x00),
HID_PHYSICAL_MAX8(0x00),
HID_REPORT_SIZE(0x10),
HID_REPORT_COUNT(0x01),
HID_INPUT(ZMK_HID_MAIN_VAL_DATA | ZMK_HID_MAIN_VAL_VAR | ZMK_HID_MAIN_VAL_REL),
HID_END_COLLECTION,
HID_COLLECTION(HID_COLLECTION_LOGICAL),
#if IS_ENABLED(CONFIG_ZMK_POINTING_SMOOTH_SCROLLING)
HID_USAGE(HID_USAGE_GD_RESOLUTION_MULTIPLIER),
HID_POP,
HID_FEATURE(ZMK_HID_MAIN_VAL_DATA | ZMK_HID_MAIN_VAL_VAR | ZMK_HID_MAIN_VAL_ABS),
#endif // IS_ENABLED(CONFIG_ZMK_POINTING_SMOOTH_SCROLLING)
HID_USAGE_PAGE(HID_USAGE_CONSUMER),
HID_USAGE16_SINGLE(HID_USAGE_CONSUMER_AC_PAN),
HID_LOGICAL_MIN16(0xFF, -0x7F),
HID_LOGICAL_MAX16(0xFF, 0x7F),
HID_PHYSICAL_MIN8(0x00),
HID_PHYSICAL_MAX8(0x00),
HID_REPORT_SIZE(0x10),
HID_REPORT_COUNT(0x01),
HID_INPUT(ZMK_HID_MAIN_VAL_DATA | ZMK_HID_MAIN_VAL_VAR | ZMK_HID_MAIN_VAL_REL),
HID_END_COLLECTION,
HID_END_COLLECTION,
HID_END_COLLECTION,
#endif // IS_ENABLED(CONFIG_ZMK_POINTING)
};
#if IS_ENABLED(CONFIG_ZMK_USB_BOOT)
#define HID_ERROR_ROLLOVER 0x1
#define HID_BOOT_KEY_LEN 6
#if IS_ENABLED(CONFIG_ZMK_HID_REPORT_TYPE_HKRO) && \
CONFIG_ZMK_HID_KEYBOARD_REPORT_SIZE == HID_BOOT_KEY_LEN
typedef struct zmk_hid_keyboard_report_body zmk_hid_boot_report_t;
#else
struct zmk_hid_boot_report {
zmk_mod_flags_t modifiers;
uint8_t _reserved;
uint8_t keys[HID_BOOT_KEY_LEN];
} __packed;
typedef struct zmk_hid_boot_report zmk_hid_boot_report_t;
#endif
#endif
struct zmk_hid_keyboard_report_body {
zmk_mod_flags_t modifiers;
uint8_t _reserved;
#if IS_ENABLED(CONFIG_ZMK_HID_REPORT_TYPE_NKRO)
uint8_t keys[DIV_ROUND_UP(ZMK_HID_KEYBOARD_NKRO_MAX_USAGE + 1, 8)];
#elif IS_ENABLED(CONFIG_ZMK_HID_REPORT_TYPE_HKRO)
uint8_t keys[CONFIG_ZMK_HID_KEYBOARD_REPORT_SIZE];
#endif
} __packed;
struct zmk_hid_keyboard_report {
uint8_t report_id;
struct zmk_hid_keyboard_report_body body;
} __packed;
struct zmk_hid_led_report_body {
uint8_t leds;
} __packed;
struct zmk_hid_led_report {
uint8_t report_id;
struct zmk_hid_led_report_body body;
} __packed;
struct zmk_hid_consumer_report_body {
#if IS_ENABLED(CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_BASIC)
uint8_t keys[CONFIG_ZMK_HID_CONSUMER_REPORT_SIZE];
#elif IS_ENABLED(CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_FULL)
uint16_t keys[CONFIG_ZMK_HID_CONSUMER_REPORT_SIZE];
#endif
} __packed;
struct zmk_hid_consumer_report {
uint8_t report_id;
struct zmk_hid_consumer_report_body body;
} __packed;
#if IS_ENABLED(CONFIG_ZMK_POINTING)
struct zmk_hid_mouse_report_body {
zmk_mouse_button_flags_t buttons;
int16_t d_x;
int16_t d_y;
int16_t d_scroll_y;
int16_t d_scroll_x;
} __packed;
struct zmk_hid_mouse_report {
uint8_t report_id;
struct zmk_hid_mouse_report_body body;
} __packed;
#if IS_ENABLED(CONFIG_ZMK_POINTING_SMOOTH_SCROLLING)
struct zmk_hid_mouse_resolution_feature_report_body {
uint8_t wheel_res : 4;
uint8_t hwheel_res : 4;
} __packed;
struct zmk_hid_mouse_resolution_feature_report {
uint8_t report_id;
struct zmk_hid_mouse_resolution_feature_report_body body;
} __packed;
#endif // IS_ENABLED(CONFIG_ZMK_POINTING_SMOOTH_SCROLLING)
#endif // IS_ENABLED(CONFIG_ZMK_POINTING)
zmk_mod_flags_t zmk_hid_get_explicit_mods(void);
int zmk_hid_register_mod(zmk_mod_t modifier);
int zmk_hid_unregister_mod(zmk_mod_t modifier);
bool zmk_hid_mod_is_pressed(zmk_mod_t modifier);
int zmk_hid_register_mods(zmk_mod_flags_t explicit_modifiers);
int zmk_hid_unregister_mods(zmk_mod_flags_t explicit_modifiers);
int zmk_hid_implicit_modifiers_press(zmk_mod_flags_t implicit_modifiers);
int zmk_hid_implicit_modifiers_release(void);
int zmk_hid_masked_modifiers_set(zmk_mod_flags_t masked_modifiers);
int zmk_hid_masked_modifiers_clear(void);
int zmk_hid_keyboard_press(zmk_key_t key);
int zmk_hid_keyboard_release(zmk_key_t key);
void zmk_hid_keyboard_clear(void);
bool zmk_hid_keyboard_is_pressed(zmk_key_t key);
int zmk_hid_consumer_press(zmk_key_t key);
int zmk_hid_consumer_release(zmk_key_t key);
void zmk_hid_consumer_clear(void);
bool zmk_hid_consumer_is_pressed(zmk_key_t key);
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_POINTING)
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_movement_set(int16_t x, int16_t y);
void zmk_hid_mouse_scroll_set(int16_t x, int16_t y);
void zmk_hid_mouse_movement_update(int16_t x, int16_t y);
void zmk_hid_mouse_scroll_update(int16_t x, int16_t y);
void zmk_hid_mouse_clear(void);
#endif // IS_ENABLED(CONFIG_ZMK_POINTING)
struct zmk_hid_keyboard_report *zmk_hid_get_keyboard_report(void);
struct zmk_hid_consumer_report *zmk_hid_get_consumer_report(void);
#if IS_ENABLED(CONFIG_ZMK_USB_BOOT)
zmk_hid_boot_report_t *zmk_hid_get_boot_report();
#endif
#if IS_ENABLED(CONFIG_ZMK_POINTING)
struct zmk_hid_mouse_report *zmk_hid_get_mouse_report();
#endif // IS_ENABLED(CONFIG_ZMK_POINTING)
Reference in a new issue View git blame Copy permalink