4键8K回报率磁轴小键盘

视频链接：

附件中有简单的实际使用演示视频。具体介绍视频暂未发布

项目简介

本项目是一款专为 OSU! 等4K音游打造的磁轴小键盘。采用 STM32F205RET6 为主控，通过 DRV5055A1 线性霍尔传感器采集磁轴按键行程，配合外部 ULPI PHY（USB3300 方案）实现 USB 2.0 HS 连接，回报率最高可达8kHZ
键盘配备 4 颗磁轴（默认 Z/X/C/V，键位可自由映射）、EC11 旋转编码器与 ENC_KEY，并预留 0.91 寸 OLED 接口，规划实现离线设置菜单与快捷翻页。灯效采用 WS2812B实现。
设备通过 Boot HID 键盘完成游戏输入，并通过 Vendor HID 协议配合 Python 上位机进行触发阈值、RT 灵敏度、键位映射、磁轴校准等配置；参数写入片内 Flash，断电不丢失。

项目功能

1. 基础 HID 输入

固件以 复合 USB 设备 枚举：接口 0 为 Boot Keyboard，接口 1 为 Vendor HID（64 字节自定义报告）。

6 槽物理按键映射（hid_keyboard_api.c）：

槽位	默认功能	说明
0–3	Z / X / C / V	磁轴通道，边沿触发上报
4	↑ / ↓	EC11 编码器旋转（短脉冲，约 15 ms）
5	Esc	ENC_KEY 按键

磁轴槽 0–3 的 HID 键码可通过 Vendor OUT 命令 0x30–0x33 单独修改。
触发判定基于滤波后的行程值，边沿变化即上报，保证按键响应及时。

2. 磁轴行程采集

采样：双 ADC + DMA 循环缓冲，TIM2 TRGO 触发扫描，约 7.9 kHz。
滤波：3 点中值 + EMA 基线跟踪（main.c）。

3. 磁轴校准

支持消除霍尔/装配差异导致的通道满量程不一致（mag_calib.c）：

方式	操作	说明
手动两点	静止 → 触底	分步采集 rest/bottom EMA
自动校准	静止 → 按到底 → 松开	固件自动识别端点，单键一次行程
清除	单通道 / 全部	清除校准数据并标记 Flash 脏

校准成功后自动应用建议触发/释放阈值（约 2.0 mm / 1.5 mm），并可通过上位机保存到 Flash。校准过程中对应通道暂停 HID 触发，避免误报。

4. Rapid Trigger（RT）

参考 Wooting 磁轴键盘的峰值追踪逻辑（hid_adc_keys.c）：

RT 关闭：经典滞回——超过触发阈值按下，低于释放阈值松开。
RT 开启：在按压过程中追踪峰值与谷值，按 灵敏度（mm） 判定释放与再触发。
每通道可独立设置灵敏度；参数持久化于片内flash

5. 参数配置与 Flash 持久化

Vendor OUT 命令（与 vendor_hid_protocol.py / vendor_out_cmd.c 一致）：

类别	命令	功能
阈值	`0x00`–`0x07`	各通道触发/释放阈值（travel 量纲）
RT	`0x10`	RT 开关
RT	`0x11`–`0x14`	各通道统一灵敏度（mm）
RT	`0x15`–`0x18`	各通道再触发灵敏度（Split 模式）
键位	`0x30`–`0x33`	各磁轴槽 HID 键码
存储	`0x20`	提交当前 RAM 参数到 Flash
回读	`0x21`	请求参数镜像（经 Vendor IN 上报）
校准	`0x40` / `0x41`	单通道校准 / 清除全部

Flash 布局：扇区 7 @ 0x08060000（128 KB），含 magic、版本号、CRC32、阈值、RT、键码、校准端点等。上电 UserParam_LoadAndApply() 自动加载；改参后防抖写入（约 400 ms）或上位机显式提交。

6. USB 高速与 Vendor 遥测

┌─────────────┐    Boot Keyboard     ┌──────────┐
│  hid_adc_keys│ ──────────────────► │ 操作系统  │
│             │    Vendor IN (64B)   │          │
│             │ ──────────────────► │ 上位机 GUI│
│             │ ◄── Vendor OUT ────── │          │
└─────────────┘                       └──────────┘

Vendor IN v5（最高 8 kHz）：序列号、按键掩码、四通道 travel_pos、触发/释放阈值、RT 参数、校准状态等。
回报率切换：开机时若 ENC_KEY 按下，Vendor 遥测设为 8 kHz；否则 1 kHz（main.c）。
说明：Boot 键盘报告为边沿触发，受 Windows kbdhid 驱动限制，实际按键回报率通常低于 8 kHz；高频优势主要体现在 Vendor 遥测、调参监控与低延迟触发逻辑。

7. 上位机软件

osu_keyboard_gui.py（依赖 hidapi、vendor_hid_protocol.py）：

无感连接：启动后后台枚举设备，发现即自动连接，断线/拔插后自动重连。
主界面：四通道实时行程（mm）、2×2 参数网格、键盘布局状态指示。
工具菜单：
- 按键映射：四通道 HID 键码配置；
- 磁轴校准：手动三步 / 单键自动 / 四键依次自动；
- RT 设置：开关与各通道灵敏度（mm）。
持久化：参数下发后可「写入并保存到芯片」。

8. 灯效（WS2812B）

已实现 PWM + DMA 驱动，4 颗 LED 链挂于 PC6（TIM3）。
当前固件为主循环彩虹演示效果。
规划中：按键状态联动、上位机可配置灯效模式。

9.EC11模拟输入

模拟“↑，↓输入”：编码器正转反转映射为↑↓输入，实现翻页功能
ENC_KEY:编码器按下默认映射为“ESC”

项目参数

主控： STM32F205RET6
霍尔传感器： DRV5055A1 ×4
旋转编码器：EC11（TIM4 正交解码）
显示屏： 0.91 OLED（SPI，引脚已引出，后续可能会更新）
灯效： WS2812B ×4
USB： OTG HS + 外部 ULPI PHY（USB3300）

原理解析（硬件说明）

1.系统供电

系统总电源：由TYPEC接口提供5V电源（VCC），使用ESD5Z6.0实现简单的ESD防护。

LDO降压：使用两颗SPX3819M5-3.3芯片实现5V-3.3V降压，分别给数字（3V3）与模拟部分（A3V3）供电
数字部分供电负责主控与usb3300的供电，模拟部分负责霍尔传感器的供电。数字地与模拟地未分割，主控的VDDA使用一颗磁轴连接A3V3.

WS2812B电源：由USB5V经1N5819WS二极管输出供电（VRGB）

2.外部PHY实现USB2.0HS

因STM32F405RET6芯片没有内置usb2.0hs phy，所以需要通过ULPI接口配合外部PHY实现USB2.0HS。外部PHY选用USB3300芯片。具体参数请查看数据手册：chrome-extension://efaidnbmnnnibpcajpcglclefindmkaj/https://ww1.microchip.com/downloads/en/DeviceDoc/00001783C.pdf

ULPI接口介绍

ULPI协议，全称为UTMI+ Low Pin Interface，是一种用于USB控制器和USB PHY之间通信的协议。它是基于UTMI（USB 2.0 Transceiver Macrocell Interface）的低引脚版本，旨在减少所需的引脚数量，同时保持与UTMI的兼容性。ULPI通过提供一个8位的双向数据总线，以及其他几个控制信号，实现了与外部PHY的有效连接。
详细介绍请参考：https://blog.csdn.net/huangkangying/article/details/104280372