终极指南：如何快速打造你的ESP32蓝牙鼠标键盘（零基础也能上手）
项目地址: https://gitcode.com/gh_mirrors/es/esp32_mouse_keyboard ESP32 Mouse/Keyboard for BLE HID 是一个基于ESP32芯片的开源项目，通过蓝牙低功耗（BLE）技术实现无线鼠标和键盘功能，还支持类似Adafruit EZKey HID的串行API，让你轻松打造自定义无线输入设备。本文将带你从环境搭建到成功烧录，一步步解锁ESP32的无线HID潜力！
📋 项目核心功能与兼容性
支持设备一览
该项目已通过AsTeRICS团队测试，兼容多种设备系统：
| 设备类型 | 鼠标功能 | 键盘功能 |
|---|---|---|
| Debian Bullseye PC | ✅ 支持 | ✅ 支持 |
| MacBook Pro (macOS) | ✅ 支持 | ✅ 支持 |
| Windows 10 PC | ✅ 支持 | ✅ 支持 |
| 安卓设备（LineageOS） | ✅ 支持 | ✅ 支持 |
| iPad（iOS 13+） | ✅ 支持 | ✅ 支持 |
⚠️ 注意：部分iPad可能会提示"设备可能影响WiFi性能"，可忽略此提示（与ESP32的WiFi共存有关）。欢迎提交你的设备测试报告，帮助完善社区兼容性列表！
硬件参考设计
项目提供完整的硬件设计文件，包括PCB布局和3D打印模型：
图：esp32miniBT模块的硬件装配示意图，适合作为辅助设备的蓝牙扩展模块
🔧 超简单环境搭建步骤
1. 安装ESP-IDF开发框架
这是ESP32官方开发工具链，支持Windows/macOS/Linux系统：
- 访问ESP-IDF工具链安装指南
- 按文档完成环境变量配置（新手建议使用安装脚本自动配置）
2. 获取项目源码
git clone https://gitcode.com/gh_mirrors/es/esp32_mouse_keyboard.git
cd esp32_mouse_keyboard
3. 配置项目参数
idf.py menuconfig
在配置菜单中需注意：
- Board Selection：选择
esp32miniBT或Arduino Nano RP2040 Connect - UART Settings：自定义串口参数（默认配置适用于官方参考板）
🚀 编译与烧录完整教程
编译固件
idf.py build # 或使用 make 命令
✨ 提示：首次编译会下载依赖组件，耐心等待完成（约5-10分钟，取决于网络速度）
烧录到ESP32
- 用USB线连接ESP32开发板到电脑
- 执行烧录命令（替换
<PORT>为实际端口，如COM3或/dev/ttyUSB0）：
idf.py -p <PORT> flash
验证与测试
烧录完成后，通过串口监控查看设备状态：
idf.py -p <PORT> monitor
在监控界面可直接测试基础功能：
- 按
W/A/S/D键控制鼠标移动 - 按
L/R键测试鼠标左右键 - 按
Q键发送键盘Y字符
💻 进阶使用指南
通过串口API控制设备
项目支持通过UART接口连接外部控制器，使用简单命令即可实现自定义输入：
| 命令格式 | 功能描述 | 示例 |
|---|---|---|
$PM 1 | 开启蓝牙配对模式 | 让设备可被手机/电脑发现 |
$NAME MyESP | 设置蓝牙设备名称 | 重启后生效 |
$DP 0 | 删除第1个配对设备 | 需先通过$GP查看配对列表 |
HID数据包格式（开发者参考）
- 鼠标报告：以
0xFD开头，包含按键掩码和XY轴偏移 - 键盘报告：支持 modifier 键和6个同时按键（兼容标准HID协议）
- 摇杆报告：支持多轴控制和32个按键（适合游戏设备开发）
🙏 项目致谢
特别感谢以下贡献者：
- Paul Stoffregen（Teensyduino键盘布局实现）
- Neil Kolban（ESP32蓝牙开发支持）
- Espressif官方HID协议实现团队
通过本教程，你已掌握ESP32蓝牙鼠标键盘的完整搭建流程。无论是DIY无线控制器还是开发辅助设备，这个项目都能为你提供强大的基础。如有问题，欢迎查阅项目文档或提交issue获取社区支持！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
