ZMK固件中的指向设备集成指南

ZMK固件中的指向设备集成指南

zmk ZMK Firmware Repository 项目地址: https://gitcode.com/gh_mirrors/zm/zmk

前言

在键盘定制领域，ZMK固件为开发者提供了强大的指向设备（如触控板、轨迹球等）集成能力。本文将深入解析如何在ZMK项目中配置和使用各类指向设备，涵盖单体和分体式键盘的不同场景。

指向设备基础概念

ZMK的指向设备支持基于Zephyr输入API构建，能够处理多种硬件设备的输入信号。目前支持以下主要功能：

1. 鼠标移动控制
2. 滚轮操作
3. 鼠标按键功能
4. 分体键盘间的输入同步

硬件设备配置

1. 设备节点定义

首先需要在设备树中定义指向设备节点。大多数指向设备使用SPI或I2C通信协议，需要正确配置总线节点。

典型配置示例：

&pro_micro_spi {
    status = "okay";
    cs-gpios = <&pro_micro 19 GPIO_ACTIVE_LOW>;

    glidepoint: glidepoint@0 {
        compatible = "cirque,pinnacle";
        reg = <0>;
        spi-max-frequency = <1000000>;
        status = "okay";
        dr-gpios = <&pro_micro 5 (GPIO_ACTIVE_HIGH)>;

        sensitivity = "4x";
        sleep;
        no-taps;
    };
};

关键参数说明：

• compatible: 指定设备驱动类型
• reg: 设备地址
• spi-max-frequency: SPI通信最大频率
• dr-gpios: 数据就绪GPIO引脚

2. 设备树放置位置

根据键盘类型不同，设备树配置位置也有所区别：

| 键盘类型 | 配置文件位置 | |----------------|-----------------------| | 单体键盘 | <键盘名>.overlay | | 分体中央部分 | <中央部分>.overlay | | 分体外设部分 | <外设部分>.overlay |

输入监听器配置

每个指向设备都需要配置对应的输入监听器，用于处理原始输入事件并转换为HID鼠标报告。

单体键盘配置

/ {
    glidepoint_listener {
        compatible = "zmk,input-listener";
        device = <&glidepoint>;
    };
};

分体键盘特殊配置

分体键盘需要额外配置输入分流设备，确保输入事件能在中央和外设间正确传递。

共享配置(.dtsi文件):

/ {
    split_inputs {
        #address-cells = <1>;
        #size-cells = <0>;

        glidepoint_split: glidepoint_split@0 {
            compatible = "zmk,input-split";
            reg = <0>;
        };
    };

    glidepoint_listener: glidepoint_listener {
        compatible = "zmk,input-listener";
        status = "disabled";
        device = <&glidepoint_split>;
    };
};

外设部分配置:

#include "<键盘名>.dtsi"

&glidepoint_split {
    device = <&glidepoint>;
};

中央部分配置:

#include "<键盘名>.dtsi"

&glidepoint_listener {
    status = "okay";
};

输入处理器应用

某些物理指向设备可能需要调整输入数据，例如旋转90°安装的触控板需要交换X/Y轴数据。

示例配置:

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

/ {
    glidepoint_listener {
        compatible = "zmk,input-listener";
        device = <&glidepoint>;
        input-processors = <&zip_xy_transform 
            (INPUT_TRANSFORM_XY_SWAP | 
             INPUT_TRANSFORM_X_INVERT | 
             INPUT_TRANSFORM_Y_INVERT)>;
    };
};

常用变换标志：

• INPUT_TRANSFORM_XY_SWAP: 交换X/Y轴
• INPUT_TRANSFORM_X_INVERT: 反转X轴
• INPUT_TRANSFORM_Y_INVERT: 反转Y轴

Kconfig配置

对于默认包含指向设备的键盘，需要在Kconfig中启用相关选项。

单体键盘配置:

if SHIELD_我的键盘

config ZMK_POINTING
    default y

config SPI  # 或I2C
    default y

endif

分体键盘配置:

中央和外设部分需要分别配置，确保通信协议只在有实际设备的部分启用。

调试技巧

1. 使用zmk-input-test工具验证输入事件
2. 检查SPI/I2C通信是否正常
3. 确认GPIO引脚配置正确
4. 逐步测试输入处理器效果

常见问题解决

1. 设备无响应:

   • 检查电源供应
   • 验证总线配置
   • 确认CS/DR引脚配置

2. 输入方向错误:

   • 调整输入处理器参数
   • 检查物理安装方向

3. 延迟或卡顿:

   • 优化SPI/I2C频率
   • 减少输入处理复杂度

通过本文的详细指导，开发者应该能够在ZMK项目中成功集成各类指向设备，为键盘增加强大的鼠标控制功能。

zmk ZMK Firmware Repository 项目地址: https://gitcode.com/gh_mirrors/zm/zmk