什么是 Openterface KeyMod
Openterface KeyMod 是 TechXArtisan Studio 推出的 100% 开源 USB + 蓝牙 HID 模拟器。它的核心功能是将你的手机变成一台便携式键盘和触控板——只需将 KeyMod 插入目标设备的 USB 口，通过手机 App（KeyCmd）即可控制目标电脑、广告机、智能电视或自助终端。
与市面上依赖专有固件的商业 KVM 切换器不同，KeyMod 从硬件原理图、PCB 设计、固件源码到手机 App 全部开源。项目遵循 AGPL-3.0 软件许可证和 CERN-OHL-S-2.0 硬件开源许可证，并获得了 OSHWA 开源硬件认证（UID CN000015）。
KeyMod 隶属于 Openterface 产品线，该产品线还包括：
| 产品 | 定位 | 开源仓库 Stars |
|---|---|---|
| Mini-KVM | 便携式 BIOS 级 KVM 控制 | 299（硬件）+ 162（桌面端） |
| KVM-GO | 增强版便携 KVM | 21（硬件） |
| KeyMod Series | USB + BLE HID 键盘/触控板 | 本文主题 |
| uConsole KVM 扩展 | uConsole 便携 KVM 扩展板 | 5（硬件） |
产品形态：Mini 与 Plus 两个版本
KeyMod 提供两个硬件版本，共享相同的核心功能：
| 特性 | KeyMod Mini | KeyMod Plus |
|---|---|---|
| USB 接口 | USB-C 公头 | USB-A 公头 + USB-C 母口 |
| 适用场景 | 现代设备（USB-C） | 传统设备 + 透传充电 |
| 蓝牙 | BLE HID | BLE HID |
| 手机连接 | USB / BLE | USB / BLE |
| 尺寸 | 超紧凑 EDC | 略大，带透传口 |
连接流程为：手机（KeyCmd App）→ KeyMod（USB 或蓝牙）→ 目标设备。目标设备无需安装任何软件——KeyMod 是真正的硬件级 HID 模拟。
核心硬件方案：CH32V208
KeyMod 的核心主控芯片是 WCH CH32V208，这是一款基于 RISC-V 架构的国产微控制器。CH32V208 内置 CH9329 兼容协议，可直接实现 USB HID 键盘/鼠标模拟，无需在目标设备上安装驱动。
硬件设计亮点
┌─────────────────────────────────────────────┐
│ KeyMod PCB │
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ CH32V208 │ │ BLE 模块 │ │
│ │ RISC-V │◄──►│ 蓝牙 5.x │ │
│ │ MCU │ │ │ │
│ └────┬─────┘ └──────────┘ │
│ │ │
│ ┌────┴─────┐ │
│ │ USB 接口 │ → 连接目标设备（HID 键盘/鼠标）│
│ └──────────┘ │
│ │
│ ┌──────────┐ │
│ │ 可编程 │ 可编程按钮（自定义宏/切换） │
│ │ 按钮 │ │
│ └──────────┘ │
└─────────────────────────────────────────────┘
关键硬件选型：
- 主控芯片：CH32V208（RISC-V，CH9329 兼容协议）
- 无线连接：BLE 蓝牙（HID 键盘/鼠标）
- USB 接口：Mini 版 USB-C 公头 / Plus 版 USB-A 公头 + USB-C 母口
- 可编程按钮：支持自定义宏命令和配置切换
- 认证：CE、UKCA、RoHS、WEEE
为什么选择 CH32V208？
CH32V208 相比常见的 RP2040 或 ESP32 方案，有几个独特优势：
- 原生 CH9329 协议兼容：无需从零实现 USB HID 描述符，开箱即用
- RISC-V 架构：开源指令集，与项目的开源理念一致
- 低成本：国产芯片，BOM 成本可控
- 低功耗：适合便携 EDC 设备
- 小封装：有助于实现超紧凑的硬件设计
KeyCmd App：功能全面的手机控制端
KeyMod 的配套 App 名为 KeyCmd，支持 Android 和 iPadOS（包括 iOS）。KeyCmd 不仅是简单的键盘/触控板，而是一个功能丰富的 HID 控制平台。
功能矩阵
| 功能模块 | 说明 |
|---|---|
| 键盘 & 鼠标（基础） | 全屏键盘 + 长按重复 + 按键预览 + 数字键盘 |
| 键盘 & 鼠标 Pro | 复合布局 + Shortcut Hub 快捷键条 + 分体键盘 + IME 输入 |
| 演示模式 | 幻灯片遥控 + 计时器（支持 Google Slides 等） |
| 游戏手柄 | 虚拟手柄 + 可自定义预设布局 + 多点触控 |
| Shortcut Hub | 基于配置文件的快捷键（Blender、KiCAD、Photoshop、VS Code） |
| 宏命令 | 可编程按键序列 + 延迟控制 |
| 语音输入 | 基于 Whisper API 的语音转键盘 |
| 终端 | 蓝牙 SSH 远程命令访问 |
| Agent | AI 驱动的 HID/SSH 命令直接控制 |
Shortcut Hub 详解
Shortcut Hub 是 KeyCmd 最具特色的功能之一。它允许用户为不同的专业软件创建、导入和导出快捷键配置文件：
Shortcut Hub 配置文件示例
├── Blender.json # 3D 建模快捷键
├── KiCAD.json # PCB 设计快捷键
├── Photoshop.json # 图像编辑快捷键
├── VS Code.json # 代码编辑快捷键
└── Custom.json # 用户自定义配置
开发者可以为自己常用的工具创建专属配置，并通过社区分享。
Agent 模式：AI 驱动的 HID 控制
KeyCmd 的 Agent 模式是一个前瞻性功能——通过 AI 直接生成 HID 或 SSH 命令来控制目标计算机。这意味着你可以用自然语言描述操作，AI 会将其转化为具体的键盘/鼠标输入序列。
GitHub 仓库结构
Openterface 项目在 GitHub 上采用多仓库组织方式，由 TechxArtisanStudio 维护：
核心仓库一览
| 仓库 | Stars | 内容 | 许可证 |
|---|---|---|---|
| Openterface | 124 | 官方网站（GitHub Pages） | — |
| Openterface_Mini-KVM_Hardware | 299 | 硬件设计、原理图、BOM | CERN-OHL-S-2.0 |
| Openterface_QT | 162 | Windows/Linux 桌面端 | AGPL-3.0 |
| Openterface_MacOS | 62 | macOS 桌面端 | AGPL-3.0 |
| Openterface_Android | 39 | Android 端 App | AGPL-3.0 |
| Openterface_WebExtension | 6 | Chrome/Firefox 浏览器扩展 | AGPL-3.0 |
| Openterface_KVM-GO_Hardware | 21 | KVM-GO 硬件设计 | CERN-OHL-S-2.0 |
| Openterface_KVM_Ext_Hardware | 5 | uConsole KVM 扩展板硬件 | CERN-OHL-S-2.0 |
仓库目录结构（以 Mini-KVM Hardware 为例）
Openterface_Mini-KVM_Hardware/
├── docs/ # 硬件文档
├── hardware/ # KiCad PCB 设计文件
│ ├── schematics/ # 原理图
│ ├── pcb/ # PCB 布局
│ └── gerber/ # 生产文件
├── models/ # 3D 模型（外壳）
├── part/ # 元器件资料
├── LICENSE # CERN-OHL-S-2.0
└── README.md
桌面端代码结构（Openterface_QT）
Openterface_QT/
├── CMakeLists.txt # CMake 构建配置
├── src/
│ ├── main.cpp # 入口
│ ├──mainwindow.cpp # 主窗口
│ ├── video/ # HDMI 视频捕获
│ ├── hid/ # USB HID 通信
│ └── ui/ # Qt UI 组件
├── packaging/ # 桌面集成文件
└── docs/
└── BUILD.md # 编译指南
开源许可证解读
Openterface 采用双重许可策略：
软件：AGPL-3.0
所有软件代码（桌面端、Android 端、固件）使用 GNU Affero General Public License v3.0：
- 可以自由使用：个人和商业使用均可
- 修改必须开源：衍生作品必须以相同许可证发布
- 网络使用触发条款：即使通过网络提供服务（SaaS），也必须公开源码
- 适合场景：确保社区改进回馈项目
硬件：CERN-OHL-S-2.0
硬件设计文件使用 CERN Open Hardware License — Strongly Reciprocal：
- 可自由制造：你可以基于设计文件自行生产 PCB
- 可修改分发：修改后的设计必须以相同许可证发布
- 可商业使用：允许基于开源设计销售产品
- 文档齐全：必须附带原始设计文件和修改说明
实战：从源码构建桌面端
以 Openterface_QT（Windows/Linux 桌面端）为例，展示如何从源码构建：
环境准备（Ubuntu/Debian）
# 安装依赖
sudo apt install cmake build-essential qt6-base-dev \
qt6-multimedia-dev libusb-1.0-0-dev libfftw3-dev
# 克隆仓库
git clone https://github.com/TechxArtisanStudio/Openterface_QT.git
cd Openterface_QT
编译步骤
mkdir build && cd build
cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DUSE_SHARED_FFMPEG=ON
make -j$(nproc)
Fedora 注意事项
在 Fedora 上编译时，需要注意 FFmpeg 共享库路径问题。参考 BUILD.md 中的 workaround：
cmake .. -DFFMPEG_PREFIX=/usr/local/ffmpeg
常见问题
| 问题 | 解决方案 |
|---|---|
undefined symbol: vaMapBuffer2 |
不要混用系统 FFmpeg 和捆绑的 VA 库 |
| CMake 成功但没有二进制文件 | 需要额外运行 make |
| 桌面分类错误 | 使用 Categories=Utility; |
使用场景实战
场景 1：户外广告机维护
户外 LED 广告机通常需要现场配置，但携带键盘不方便：
1. 将 KeyMod Mini 插入广告机的 USB-C 口
2. 手机打开 KeyCmd，通过 BLE 连接 KeyMod
3. 使用手机屏幕键盘输入配置命令
4. 完成维护后拔出 KeyMod
场景 2：自助终端调试
1. KeyMod Plus 插入终端的 USB-A 口
2. 手机通过 USB 连接 KeyMod（更稳定）
3. 使用 Shortcut Hub 加载终端专用配置
4. 快速输入调试命令
场景 3：开发者工作流加速
1. KeyMod 插入开发机
2. KeyCmd 加载 VS Code Shortcut Hub 配置
3. 使用宏命令快速执行重复性操作
4. Agent 模式用自然语言执行复杂任务
如何参与贡献
Openterface 是一个活跃的开源社区，欢迎各种形式的贡献：
提交 Issue
- Bug 报告：描述问题、复现步骤、固件版本
- 功能建议：描述使用场景和期望行为
- 硬件问题：使用对应仓库的 Issue 标签
提交 Pull Request
# 1. Fork 仓库
# 2. 创建功能分支
git checkout -b feature/your-feature
# 3. 开发并测试
# 4. 提交 PR 到 main 分支
文档改进
文档仓库 Openterface/Openterface 使用 MkDocs 构建，支持多语言（中、英、日、韩、法、德、意、葡、罗）。翻译 PR 非常受欢迎。
社区渠道
- Discord：openterface.com/discord — 实时交流
- GitHub Discussions：功能讨论和技术问答
- 论坛：openterface.com/forum — 长期讨论
- YouTube：TechxArtisan — 产品演示和教程
与其他开源 HID 方案对比
| 特性 | Openterface KeyMod | TinyUSB HID | Arduino HID | BluePill HID |
|---|---|---|---|---|
| 主控 | CH32V208 (RISC-V) | 多平台 | AVR/ARM | STM32F103 |
| 蓝牙 | ✅ BLE | ❌ 需外挂 | ❌ 需外挂 | ❌ 需外挂 |
| 手机 App | ✅ KeyCmd | ❌ 自行开发 | ❌ 自行开发 | ❌ 自行开发 |
| 开源硬件 | ✅ CERN-OHL | ❌ 仅固件 | ❌ 仅固件 | ✅ 部分 |
| 即插即用 | ✅ 免驱 | ✅ 免驱 | ✅ 免驱 | ✅ 免驱 |
| 产品化程度 | 量产产品 | 开发框架 | 开发框架 | DIY 方案 |
| AI 集成 | ✅ Agent 模式 | ❌ | ❌ | ❌ |
常见问题
KeyMod 和传统 KVM 切换器有什么区别？
传统 KVM 切换器用于在多台电脑间切换一套键盘/鼠标/显示器。KeyMod 的定位不同——它是将手机变成键盘和触控板，用于控制单台没有输入设备的目标机器。适合户外广告机、自助终端、智能电视等场景。
KeyMod 需要目标设备安装软件吗？
不需要。KeyMod 是真正的硬件级 HID 模拟，目标设备会将其识别为标准 USB 键盘和鼠标，无需任何驱动或软件。
可以自行制造 KeyMod 吗？
可以。硬件设计文件以 CERN-OHL-S-2.0 许可证开源，你可以下载 Gerber 文件自行生产 PCB，并根据 BOM 采购元器件组装。
KeyCmd App 支持哪些平台？
目前支持 Android 和 iPadOS（iOS）。桌面版（Windows/macOS）在 Openterface 生态中已有 QT 和 macOS 原生应用。
开源许可证对商业使用有什么限制？
软件使用 AGPL-3.0，商业使用可以，但修改后的代码必须开源。硬件使用 CERN-OHL-S-2.0，允许基于开源设计生产和销售产品，但修改后的设计也必须开源。
总结
Openterface KeyMod 代表了开源硬件和软件协同开发的最佳实践：
- 100% 开源：硬件设计、固件、App 全部公开，获得 OSHWA 认证
- 实用工具：解决户外设备维护、终端调试、工作流加速等真实场景
- 技术先进：CH32V208 RISC-V 主控 + BLE + AI Agent 模式
- 社区活跃：多仓库协作，多语言文档，Discord 实时交流
无论你是想学习 RISC-V 嵌入式开发、了解 USB HID 协议、还是需要一个实用的便携输入工具，Openterface KeyMod 都值得深入关注。
相关链接： - GitHub 组织：github.com/TechxArtisanStudio - 官方文档：docs.openterface.com/products/keymod - 官方网站：openterface.com - Discord 社区：openterface.com/discord - 相关教程：Openterface Mini-KVM 深度解析