本项目为基于 STM32H7 打造的开源 MPE 表情 MIDI 控制器。采用柔性悬臂机械结构搭配 TMAG5273 霍尔传感器，实现琴键 X/Y 轴多维位置检测，让每个音符拥有独立音高滑音、持续压力控制等复音表情能力。全套开放 3D 模型、PCB 工程与 STM32 固件，提供一套低成本 DIY 高端表情演奏键盘的完整方案。

一、项目核心简介

• 主控：STM32H7

• 通信：USB-C 直连电脑

• 输入：霍尔传感器（TMAG5273）柔性悬臂琴键（flexure）

• 输出：USB MPE MIDI 信号，可直接接入 Ableton Live 等数字音频工作站

• 按键：2 个八度 + 额外 1 枚琴键（共 25 键）

• 指示：每个琴键配套 PWM 可调 LED 指示灯

• 定位：低成本 DIY MPE 表情键盘；商用 MPE 控制器普遍售价 500–2000 美元，本项目物料总成本约418 美元

二、硬件设计方案

1. 机械结构

作者创新采用单部件柔性悬臂（flexure）琴键结构，常规键盘琴键零件数量普遍 100+，本方案将单键零件压缩至最少 2 件；

每个琴键内置磁铁，依靠TMAG5273 I²C 霍尔传感器检测磁铁距离、旋转角度，从而捕捉按键下压深度、横向位移，实现 MPE 所需的触后、X/Y 轴表情控制。

2. BOM 物料清单要点

全部物料账面合计 $333.27，加上作者自掏腰包增补零件，真实总成本 $418.45

三、固件（Firmware）信息

• 编程语言：C，基于 STM32CubeIDE 开发

• 开源依赖：

  • tinymusb MIT 协议 USB 栈

  • lib-mux-stm32 BSD-2 协议 I2C 多路复用驱动

  • 改写版stm32_tmag5273库，解决传感器地址限制问题

• 可调参数：代码内置大量参数宏

  • 八度切换、MIDI 通道偏移

  • 触后阈值、Pitch 弯音范围

  • LED 闪烁时长、按键长按判定时间

  • 可关闭串口调试输出提升运行速度

四、作者记录的已知问题 ⚠️

文档详细记录了样机实测缺陷，复刻前建议重点留意：

1. 生产制造问题

1. TMAG5273 传感器 I²C 地址固化，只能通过采购不同型号区分，无法软件修改

2. 螺丝锁紧塑料壳体时容易压裂结构件

3. PCB 与 3D 打印件公差控制难度高，极易出现琴键卡滞

4. 排线长度紧张，焊接难度大

2. 长期使用与固件缺陷

1. PLA 柔性悬臂高温下会产生永久形变，夏季车内放置容易失效

2. 霍尔传感器需要单独校准；按键靠近传感器时角度读数会漂移

3. 琴键存在轻微打滑，手感需要磨合

4. 供电电压波动会导致 LED 亮度不稳定

五、项目文件结构（仓库目录）

plaintext

idea/        前期构思文档
cad/         3D打印模型（机械结构）
firmware/    STM32固件源码
pcb/         KiCad PCB工程文件
production/  生产辅助图文
gligpore/
JOURNAL.md    开发日志
LICENSE      GPLv3开源协议

六、项目价值

1. 低成本 MPE 开源方案：市面成品 MPE 键盘价格高昂，本项目提供完整硬件 + 软件开源参考

2. 霍尔传感琴键方案参考：柔性悬臂 + TMAG5273 无触点琴键设计思路，适合自制表情 MIDI 设备

3. STM32 USB MPE 协议实现范例：可直接参考多路 I2C 传感器采集、MPE 数据包封装代码

七、License

GPL-3.0 license

八、项目地址

https://github.com/udu3324/stm32pe-midi