Skip to content

About

基于 CH552E + 霍尔传感器的磁轴单键键盘,配套通过 Web Serial 连接设备的网页控制台。https://onekeyhall.dogolab.org/

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

oneKeyHall

基于 CH552E + 霍尔传感器的磁轴单键键盘,配套通过 Web Serial 连接设备的网页控制台。

支持可调触发点、快速触发 RT、按键映射、设备内线性控制和行程灯效。配置完成后,键盘可独立运行,无需常驻网页或额外安装伴随程序。

项目仓库 · 固件文件 · 当前发布信息 · 串口协议

功能

功能 说明
磁轴校准 松开、压到底两点校准,支持两种磁极方向,显示有效 ADC 跨度
触发手感 可调触发点、释放点、顶部死区、滤波强度和确认采样数
快速触发 RT 根据行程极值动态释放和重新触发,网页显示实时阈值线
按键映射 KEY1 / KEY2、单键、组合键、最多 30 字节 ASCII 文本
双击 可配置 50–1000 ms 间隔,默认 200 ms;键盘双击模式与 RT 互斥
线性控制 行程控制音量、滚轮速度、固定位置触控面积和压力
双击反向 在线性模式中切换音量方向、滚轮方向或触控大小方向
RGB 灯效 固定、呼吸、HUE 渐变、行程亮度、反向亮度、行程颜色、颜色亮度联动
设备信息 读取应用固件版本、BootLoader 版本、芯片序列号和累计释放次数
设备名称 自定义设备名称与 USB 名称;未保存自定义名称时使用芯片序列号生成默认名称
网页工具 中英文切换、浅色/深色/系统主题、键盘测试、触控测试、串口指令表
恢复出厂 清除全部设备配置和累计次数,立即保存;重新校准后使用
固件更新 下载网站发布的 HEX 文件,支持手动请求设备进入 ISP

当前应用版本、配置格式与镜像哈希见自动生成的发布信息。只发布一个默认支持 ISP 的版本,文件为 firmware/build/onekeyhall-ch552-24mhz.hex。

硬件

项目 当前配置
主控 CH552E,24 MHz 内部时钟
供电 USB 5V
霍尔传感器 DRV5055A2QDBZR(当前实测组合)
传感器输出 OUT → R1(1 kΩ)→ P1.5 / AIN2
ADC 8 位,0–255;P1.5 配置为高阻输入
RGB P1.4,WS2812
USB CDC 配置串口 + HID 输入

原理图和 PCB 资料位于 hardware,结构设计和打印文件位于 3D。固件按上述接线实现,替换传感器或引脚时需同时检查硬件与源码。

已验证的磁轴组合

根据维护者提供的实测反馈,DRV5055A2QDBZR + XVX 潘多拉 46gf 版磁轴,使用 CH552E 的 8 位 ADC,在当前装配条件下测得的最大有效校准跨度为 93 个 ADC 计数。这里的跨度是松开与压到底两个校准端点的 ADC 差值绝对值,不是 ADC 的最大读数,也不是所有轴体或装配条件下的固定上限。

以下为维护者提供的商品标称参数,未逐项进行独立测量:

项目 商品标称值
品牌 / 商品名称 XVX(eXplore creativity)/ 潘多拉 46gf 版
轴体类型 线性磁轴
总行程 3.5 ± 0.1 mm
初始压力 46 ± 5 gf
触底力 60 ± 10 gf
弹簧长度 22 mm
初始磁通量(商品标注) 120 ± 8 GS
触底磁通量(商品标注) 700 ± 30 GS
商品特点 双灯位结构、声音手感特调、HiFi 音质

商品所述“运动行程可自由设定”在本项目中对应可配置的触发位置,轴体的物理总行程仍按上述标称值描述。商品磁场参数不等于 PCB 上传感器位置的实测磁场。

跨度 93 对应每个 ADC 计数约 1.08% 相对行程;这不是毫米精度或有效位数的测量。磁铁与传感器的间距、位置和样品差异均可能改变跨度,每台设备仍需完成两点校准。该结果验证了这组硬件的校准跨度,不代表所有固件功能均已完成实机验收。早期文档中的 A3 型号记录已按本次反馈更新为 A2。

快速开始

1. 烧录固件

使用适配 CH552 的烧录工具,将 onekeyhall-ch552-24mhz.hex 写入设备。首次烧录需要通过硬件方式进入芯片的 ISP 模式;网页下载模式按钮需要设备已经运行支持该命令的固件。

升级时保留 DataFlash 可迁移已有名称、校准和参数;擦除 DataFlash 后需要重新校准和配置。HEX 只包含应用程序,不包含 BootLoader 或芯片配置字。

WCHISPTool_CH54x/55x 烧录配置

以下按维护者提供的工具截图记录。芯片配置由烧录工具设置,不能仅凭选择 HEX 文件代替这些选项。

位置 / 选项 设置
芯片系列 CH55x
芯片型号 CH552
下载接口 USB
设备连接后自动下载 不勾选,手动执行下载
目标程序文件 1 选择 firmware/build/onekeyhall-ch552-24mhz.hex,勾选该行
DataFlash 文件 不选择文件、不勾选
目标程序文件 2 / 3 / 4 不选择文件、不勾选
启用代码和数据保护模式 截图中为灰色勾选状态,保持工具当前状态
使能 RST Pin 作为手工复位输入引脚 勾选
使能上电复位后长延时 不勾选
下载完成后运行目标程序 勾选
清空 DataFlash 首次烧录或需要重置时勾选;升级并保留配置时取消勾选
清空 CodeFlash 勾选
串口免按键下载功能 按截图勾选
下载配置脚 P1.5

截图勾选了“清空 DataFlash”,按此设置下载会清除保存的校准、设备名称、按键映射、灯光、输出开关和累计次数。日常升级需要保留这些内容时,取消此项;“DataFlash 文件”保持不勾选。

操作步骤:

  1. 按上表选择芯片、接口和目标 HEX,确认 DataFlash 是否需要清空。
  2. 让设备进入 ISP。已有支持软件 ISP 的固件时,可在网页点击“进入下载模式”;首次烧录使用板子的硬件 ISP 进入方式。
  3. 点击“搜索”,确认设备列表识别到目标芯片,再执行下载。
  4. 等待工具显示编程、校验成功;必要时重新插拔 USB,再连接网页确认应用版本。
  5. 如果清空过 DataFlash,重新完成两点校准和参数设置,并点击“保存配置”。

表中的“串口免按键下载功能”是烧录工具中的选项名称,不代表网页的串口波特率设置。网页和 Python demo 仍使用 57600,固件仍禁用 CDC 1200 波特率自动进入 ISP。

2. 打开网页控制台

本地运行需要 Node.js 18 或更新版本。Windows 下双击 host/start.cmd,或在项目根目录运行:

node host/server.mjs

用桌面 Chrome / Edge 打开 **http://127.0.0.1:5173**,点击“连接设备”,选择键盘对应的串口。

网页无需安装 npm 依赖或打包。通过本地 HTTP 或 HTTPS 访问,不要直接双击 index.html 使用 file:// 打开。网页只连接用户主动选择的设备。

3. 校准磁轴

  1. 点击“开始校准 / 暂停输出”。
  2. 完全松开轴体,保持静止,点击“① 松开轴体,采集顶部”。
  3. 压住轴体到底,保持静止,点击“② 压住到底,采集底部”。
  4. 底部采集成功后,校准自动应用。松开轴体,等待显示“已就绪”。
  5. 设置按键与触发手感,点击“保存配置”,使校准和参数在断电后保留。

有效跨度至少需要 16 个 ADC 计数。采样不稳定或信号接近电源轨时会拒绝校准;请检查磁铁位置、传感器方向和接线。全新配置的 KEY1 默认为空格,两组文本内容默认为 oneKeyHall。

4. 应用与保存

  • 自动应用:停止修改参数约 400 ms 后,有效参数自动写入运行内存,不写 DataFlash。
  • 保存配置:将当前配置和累计释放次数写入 DataFlash,断电后保留。
  • 校准期间:暂停参数自动应用与键盘输出,完成底部采集后自动应用校准。
  • 放弃待应用修改:清除尚未应用的输入或取消未完成的校准,不撤销已经自动应用的参数。

自动应用后,关闭网页或断开配置串口不会停止设备运行;设备断电后恢复最后保存的配置。设备名称最多支持 12 个 BMP 字符(可含中文),留空使用 oneKeyHall 加 10 位十六进制芯片序列号;修改 USB 名称需保存后拔插 USB 生效。

关闭输出与灯光模式

V2.6.2 起,在“按键映射 → 工作模式”中选择“完全关闭模拟键鼠输出”(与 KEY1、KEY2、单/双击、线性模式并列),可停止所有键盘、鼠标、音量和触控输出,同时保留 ADC 采样、实时状态和串口配置;关闭期间仍按触发点、释放点或 RT 判定累计有效释放次数,未触发的浅按、设置暂停和 ADC 故障不计数。重新启用后需先完全松开轴体。

在“RGB 灯效”的模式列表中选择“完全关闭灯光”,可关闭全部灯效,与固定、呼吸、HUE 渐变及行程灯效并列;选择其他灯效即可重新点亮。颜色、亮度等参数保留。工作模式和灯效模式互不影响,修改后自动应用,点击“保存配置”后断电保留。旧固件上的新增关闭模式会禁用并提示升级。

恢复出厂设置

连接 V2.6.1 或更新固件后,点击页面下方的“恢复出厂设置”,阅读提示并确认。此操作清除设备名称、校准、按键与文本、双击、RT、灯光、线性参数和累计次数,立即保存且无法撤销。完成后需要重新校准;拔插 USB 后默认设备名称生效。固件、BootLoader、芯片序列号及浏览器语言/主题不变。

线性模式

在“工作模式”选择“线性模式”,再选择预设。所有输出均在固件内通过 USB HID 完成。

预设 行程行为
音量 / 音量反向 在设定的最低、最高音量之间随行程变化,可交换方向
滚轮向上 / 向下 松开停止,按得越深滚动越快
当前光标 在鼠标当前位置按住左键,释放磁轴后松开,可用于拖动
固定位置触控面积 在指定 X/Y 产生触点,接触面积随行程变化
固定位置触控压力 在指定 X/Y 产生触点,压力随行程变化
面积与压力联动 同时改变固定触点的接触面积和压力

勾选“双击切换反向”后,一对双击切换方向,下一对切回;使用同一个可配置双击间隔。当前光标左键预设不提供反向。开关可以保存,临时方向不保存,重新上电或应用配置后回到所选预设方向。

音量通过媒体音量键近似映射,不能读取系统实际百分比。固定位置触控需要系统和应用支持对应 HID 报告;当前光标预设仅提供普通鼠标左键,不提供跟随鼠标的触控面积或压力。

详细参数与限制见 线性模式说明。

固件更新

网页提供两个独立入口:

  • 下载最新固件(HEX):下载网站发布的文件,无需连接设备,不执行烧录。
  • 进入下载模式:向已连接设备发送 ISP 请求,固件先关闭 LED,再交接给 BootLoader;随后使用烧录工具更新固件。

当前固件能力值为 0xFF,默认支持手动 ISP,1200 波特率自动进入 ISP 保持关闭。网页收到成功应答后关闭应用串口,但这不等于已确认 ISP 枚举,也不会自动启动烧录软件。下载请求记录仅保留在当前页面,刷新后清空。

项目曾出现请求 ISP 后电脑异常关闭的反馈;后续 TMOD 交接修正曾获实机成功反馈,原异常原因仍未确定。相关记录保留在 ISP 排查记录 和 取证说明。

发布新的下载文件

运行 scripts/build_firmware.ps1 成功后,会自动更新 host/firmware/latest.hex、网页发布信息 host/assets/release.mjs 和 docs/CURRENT_RELEASE.md。网页页头、版本查询示例、能力值和下载版本从这份生成信息读取,无需手改。设备连接区域的固件版本仍由设备实际应答获取。

发布前运行:

node scripts/sync-release.mjs --check

检查源码版本、构建 HEX、网页 HEX 和发布信息是否一致;不一致时拒绝部署。使用 Arduino IDE 编译时,先将结果放到 firmware/build/onekeyhall-ch552-24mhz.hex,再运行 node scripts/sync-release.mjs --write 同步本地发布文件。直接替换 latest.hex 会触发一致性检查失败。

下载路径保持 firmware/latest.hex,下载文件名自动包含发布版本。构建和同步只更新本地文件,不会自动提交、推送或部署。详见固件发布目录说明。

部署网页

网页为原生 HTML / CSS / JavaScript,无服务端业务依赖,可部署到 HTTPS 静态站点。浏览器直接通过 Web Serial 与本机设备通信,云端不运行串口服务。

GitHub Pages:源码和网页共用仓库

固件、硬件资料、文档和 host 可以保存在同一个仓库。已提供 Pages 部署工作流,仅将 host/index.html、host/assets/ 和 host/firmware/latest.hex 发布为网站,其他内容仍作为仓库源码管理。

  1. 将项目(包括 .github/workflows/pages.yml)提交并推送到仓库的 main 分支。
  2. 在 GitHub 仓库 Settings → Pages → Build and deployment → Source 选择 GitHub Actions。
  3. 在 Actions → Deploy webhost to GitHub Pages → Run workflow 手动触发首次部署,选择 main。后续向 main 推送网页、测试或工作流修改会自动部署。
  4. 工作流成功后打开 Pages 显示的 HTTPS 地址。本仓库使用默认项目地址时为 https://0ingchun.github.io/oneKeyHall/;此处是部署后的预期地址,不表示已上线。

工作流先检查发布信息与固件一致,再运行网页测试并发布静态文件,不编译或烧录固件。发布新固件时先完成本地构建与自动同步,再提交。主页面、指令表、触控测试和下载链接均使用相对路径,兼容项目子路径、本地服务及自定义域名。

访问在线网页时无需安装或运行 Node.js。使用支持 Web Serial 的桌面 Chrome / Edge,点击“连接设备”并选择本机串口;更换站点后需要重新选择设备。网页仍可校准、修改和保存配置,进入 ISP 后的实际烧录仍使用烧录工具。

依据:GitHub Pages 自定义工作流、Web Serial 使用说明。

Cloudflare Pages

使用 Cloudflare Pages 连接本仓库时,可按以下配置部署:

设置 值
Framework preset None
项目根目录 仓库根目录
Build command node scripts/sync-release.mjs --check && npm --prefix host test
Build output directory host

部署后访问站点根路径;server.mjs 仅用于本地启动,无需在 Pages 上运行。也可只上传 host/index.html、host/assets/ 和 host/firmware/latest.hex,保持目录结构。

上述设置对应 Cloudflare Pages 静态 HTML 部署文档。本地服务器的下载响应头不会自动带到静态托管环境,更新固件时需同时检查托管平台缓存。此仓库提供部署说明,不代表已经部署了在线站点。

编译固件

构建脚本需要 Node.js 18 或更新版本,用于生成网页发布信息。已验证的工具链为 Arduino CLI 1.2.0、CH55xDuino 0.0.16、SDCC build.13407。先安装 CH55xDuino 开发板支持,在项目根目录执行:

powershell -ExecutionPolicy Bypass -File scripts/build_firmware.ps1

脚本优先查找 PATH 中的 arduino-cli,随后尝试 Arduino IDE 默认安装位置。自定义位置可通过 -ArduinoCli 指定。输出为 firmware/build/onekeyhall-ch552-24mhz.hex,编译中间文件位于 tmp/;脚本不连接或烧录设备。

Arduino IDE 也默认启用 ISP,配置如下:

项目 值
Sketch firmware/firmware.ino
开发板 CH552 Board
Clock Source 24 MHz (internal), 5V
USB Settings USER CODE w/ 266B USB ram
Upload method USB

V2.6.2 内存占用

区域 当前占用
应用 Flash 14316 / 14336 字节,剩余 20 字节
应用 XRAM 454 / 758 字节,剩余 304 字节
USB XRAM 预留 266 字节;加上应用共 720 / 1024 字节
内部 RAM 栈区域 从 0x47 开始,可用区域 186 字节,非运行时峰值测量
配置持久化 128 字节 DataFlash,含 CRC

数据来自当前构建的 内存报告,校验信息见 verification.json。

测试与限制

完整主机测试需要 Python 3、GCC 和 Node.js:

python scripts/run_tests.py

脚本可自动查找 PATH 或本机 CLion 中的 GCC,也可用环境变量 CC 指定。只运行网页测试时:

npm --prefix host test

当前验证包括 CH552 目标编译、43 组固件逻辑测试、USB / ROM / 文本输入测试及 64 项 Node 测试。测试不连接真实设备。完整 V2.6.2 的实机验证状态见版本说明,主机测试不等于实际 ADC、USB 枚举或触控应用验证。

  • 行程是两点 ADC 校准得到的相对百分比,不是毫米测量;磁铁位移与磁场不一定线性。
  • 采样采用主循环时间检查,不应将网页刷新率或 1 ms 采样间隔理解为实测输入延迟。
  • 累计释放次数为 16 位,65535 后回到 0;在线性模式下同样统计有效释放,保存配置后才断电保留。
  • 网页键盘测试无法区分不同物理键盘,也无法保证接收被系统拦截的快捷键。

项目结构

oneKeyHall/
├── .github/workflows/      GitHub Pages 自动部署
├── firmware/
│   ├── firmware.ino       固件入口(与 Arduino sketch 目录同名)
│   ├── src/               固件模块与 USB 驱动
│   └── build/              默认 ISP 固件、内存和验证报告
├── host/
│   ├── index.html          网页控制台入口
│   ├── assets/             界面、串口协议、测试页与指令表
│   ├── firmware/latest.hex 网页提供下载的固件
│   └── server.mjs          本地静态服务器
├── hardware/               原理图与芯片资料
├── 3D/                     结构设计与打印文件
├── scripts/                编译、测试与故障取证工具
├── tests/                  固件和网页回归测试
└── docs/                   协议、版本与排查文档

许可证

oneKeyHall 的自有项目代码采用 GNU GPL 第 3 版(SPDX:GPL-3.0-only),完整条款见 LICENSE。适用范围包括本项目原创的固件、Web 控制台、脚本和测试代码,以及维护者有权许可的修改部分。

第三方代码保留其原有版权和许可声明;硬件/结构设计文件、芯片资料及 BootLoader 测试样本不因本声明而改用 GPL。来源、许可文本及尚待确认的材料见 第三方声明。

相关资料

本项目由 onekeyboard 单键键盘改造为霍尔磁轴方案,网页样式参考 原版控制台,固件使用 CH55xDuino 相关实现。源码中的原有版权与许可声明予以保留。

About

基于 CH552E + 霍尔传感器的磁轴单键键盘,配套通过 Web Serial 连接设备的网页控制台。https://onekeyhall.dogolab.org/

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages