如何用 ESP32 打造终极蓝牙鼠标键盘：零基础也能上手的完整指南
项目地址: https://gitcode.com/gh_mirrors/es/esp32_mouse_keyboard ESP32 Mouse/Keyboard for BLE HID 是一个基于 ESP32 的蓝牙低能耗（BLE）人机交互设备（HID）实现，支持键盘和鼠标功能。这个开源项目不仅提供了串行API，与Adafruit的EZKey HID兼容，还允许外部模块进行控制。其目标是为各种智能设备提供灵活、便捷的无线输入解决方案。
🚀 项目核心优势：为什么选择 ESP32 BLE HID？
✅ 多平台兼容，无缝连接各种设备
经过严格测试，该项目已验证可在主流操作系统和设备上稳定运行：
| 设备类型 | 鼠标功能 | 键盘功能 |
|---|---|---|
| Windows 10/11 | ✅ 完美支持 | ✅ 完美支持 |
| macOS (Mojave及以上) | ✅ 完美支持 | ✅ 完美支持 |
| Linux (Debian/Ubuntu) | ✅ 完美支持 | ✅ 完美支持 |
| Android (6.0+) | ✅ 完美支持 | ✅ 完美支持 |
| iOS/iPadOS (13.3+) | ✅ 需辅助触控 | ✅ 文本输入支持 |
💡 小贴士：部分iPad设备可能会显示蓝牙性能警告，这是由于ESP32的WiFi模块干扰导致，可忽略此提示正常使用。
🔧 超低成本实现无线控制
相比购买商业无线键鼠套装，使用ESP32模块（约￥20-50）自制方案成本更低，且支持完全自定义功能。硬件设计文件完全开源，包含PCB设计图、BOM清单和3D打印模型。
🛠️ 快速上手：3步完成固件烧录
1️⃣ 搭建开发环境
首先安装ESP-IDF框架：
# 克隆ESP-IDF仓库
git clone --recursive https://gitcode.com/gh_mirrors/es/esp32_mouse_keyboard
cd esp32_mouse_keyboard
# 安装工具链（参考ESP-IDF官方文档）
2️⃣ 编译固件
# 使用IDF工具链编译
idf.py build
# 或使用Makefile编译
make
3️⃣ 烧录到ESP32
# 替换(PORT)为实际串口，如COM3或/dev/ttyUSB0
idf.py -p (PORT) flash
# 查看调试输出
idf.py -p (PORT) monitor
🎮 功能演示：如何控制你的设备
🔌 基础测试：通过串口控制
连接ESP32后，在监控终端输入以下指令测试：
| 按键 | 功能 | 描述 |
|---|---|---|
w/a/s/d | 鼠标移动 | 上/左/下/右移动30像素 |
l/r | 鼠标点击 | 左键/右键点击 |
q | 键盘测试 | 发送"y"字符（US布局） |
🖥️ 外部控制：通过UART接口
项目支持通过UART与外部微控制器通信，使用简单的命令协议：
# 设置设备名称
$NAME MyESP32HID
# 获取已配对设备
$GP
# 发送鼠标移动指令（自定义协议）
$MOVE 100 -50 # X+100, Y-50
📱 实际应用场景：解锁无限可能
1️⃣ 无障碍辅助设备
将传感器或语音识别模块连接到ESP32，为行动不便人士提供定制化输入方案。例如：
- 眼动追踪转鼠标控制
- 语音命令转键盘输入
- 呼吸传感器控制光标
2️⃣ 智能家居控制中心
通过自定义按键实现一键控制：
- 客厅影音系统遥控器
- 智能灯光场景切换
- 家庭影院环境控制
3️⃣ 嵌入式系统调试工具
在无外设场景下：
- 树莓派无头系统配置
- 工业设备参数调试
- IoT设备远程控制
📊 硬件设计与组装
项目提供完整的硬件设计文件，包括KiCad原理图和PCB布局：
图：ESP32 miniBT模块组装示意图，包含蓝牙天线和I2S麦克风接口
主要硬件组件：
- ESP32-WROOM-32模块
- CMM-4030D-261 I2S麦克风（可选）
- 3.3V LDO稳压器
- 迷你USB接口
🛠️ 高级玩法：自定义功能开发
修改键盘布局
编辑main/hid_dev.c文件自定义按键映射：
// 示例：修改按键映射表
const uint8_t keyboard_report_map[] = {
// 标准US布局定义
0x05, 0x01, // Usage Page (Generic Desktop)
0x09, 0x06, // Usage (Keyboard)
// ...其他HID报告描述符定义
};
添加新设备类型
项目支持扩展为游戏手柄等其他HID设备，修改hid_dev.h添加新报告类型：
// 添加操纵杆报告ID
#define HID_RPT_ID_JOYSTICK_IN 0x03
// 定义报告结构
typedef struct {
int8_t x_axis;
int8_t y_axis;
// ...其他轴和按键定义
} joy_stick_report_t;
🤝 社区与支持
贡献代码
- Fork本仓库
- 创建特性分支
git checkout -b feature/amazing-feature - 提交更改
git commit -m 'Add some amazing feature' - 推送到分支
git push origin feature/amazing-feature - 创建Pull Request
问题反馈
- 设备兼容性测试报告
- 功能bug提交
- 新功能建议
📄 许可证信息
硬件设计遵循CERN OHL v1.2开源协议，软件部分采用MIT许可证。详细信息参见项目根目录下的LICENSE文件。
无论你是电子爱好者、开发者还是DIY达人，ESP32 BLE HID项目都能为你提供灵活强大的无线控制解决方案。立即开始你的创作，探索更多可能性！
⭐ 如果你觉得这个项目有用，请给我们点个Star支持！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
