2024零基础玩转ESP32蓝牙鼠标键盘：从硬件到固件的完整DIY指南

ESP32 Mouse/Keyboard for BLE HID是一个基于ESP32的蓝牙低能耗人机交互设备实现，支持键盘和鼠标功能。该项目提供串行API与Adafruit EZKey HID兼容，允许外部模块控制，为智能设备提供灵活便捷的无线输入解决方案。

🛠️ 为什么选择ESP32打造蓝牙输入设备？

✅ 跨平台兼容优势

经过实测验证，该方案可在多系统稳定运行：

• Windows 10/11：完美支持鼠标键盘功能
• macOS Mojave+：全功能兼容
• Linux (Debian/Ubuntu)：即插即用
• Android 6.0+：完整支持输入操作
• iOS/iPadOS 13.3+：需辅助触控实现鼠标功能

💰 超高性价比方案

相比商业无线键鼠套装，ESP32模块（￥20-50）成本更低且支持完全自定义。项目提供完整开源硬件设计文件，包括PCB布局、BOM清单和3D打印模型，极大降低入门门槛。

📝 零基础入门：3大核心步骤

1️⃣ 开发环境搭建

# 克隆项目仓库
git clone --recursive https://gitcode.com/gh_mirrors/es/esp32_mouse_keyboard
cd esp32_mouse_keyboard
# 安装ESP-IDF工具链（参考官方文档）

2️⃣ 固件编译指南

# ESP-IDF编译方式
idf.py build

# 或使用Makefile编译
make

3️⃣ 设备烧录与测试

# 替换(PORT)为实际串口
idf.py -p (PORT) flash
# 启动监控终端
idf.py -p (PORT) monitor

🔧 硬件组装完全图解

上图展示了ESP32蓝牙附加模块的详细组装指南，包含元件布局和焊接指示。主要组件包括：

• ESP32-WROOM-32主控模块
• 3.3V LDO稳压器
• MEMS麦克风（可选）
• 电容电阻等外围元件

完整硬件设计文件位于hardware/目录，包含KiCad原理图、PCB布局和BOM清单。

🎮 功能测试与控制方法

⌨️ 基础串口控制

连接设备后，通过监控终端输入以下指令：

• w/a/s/d：控制鼠标上下左右移动（30像素/次）
• l/r：鼠标左键/右键点击
• q：发送测试字符"y"（US键盘布局）

📡 UART外部控制协议

支持与外部微控制器通信，协议示例：

# 设置设备名称
$NAME MyESP32HID

# 获取已配对设备
$GP

# 鼠标移动指令（X+100, Y-50）
$MOVE 100 -50

💡 进阶功能开发指南

自定义键盘布局

修改main/hid_dev.c文件中的HID报告描述符：

// 标准US布局定义示例
const uint8_t keyboard_report_map[] = {
  0x05, 0x01,        // Usage Page (Generic Desktop)
  0x09, 0x06,        // Usage (Keyboard)
  // ...其他HID报告描述符定义
};

扩展设备类型

通过修改main/hid_dev.h添加新HID设备类型：

// 添加操纵杆报告ID
#define HID_RPT_ID_JOYSTICK_IN  0x03

// 定义操纵杆报告结构
typedef struct {
  int8_t x_axis;
  int8_t y_axis;
  // ...其他轴和按键定义
} joy_stick_report_t;

🚀 创新应用场景

1️⃣ 无障碍辅助设备

• 眼动追踪转鼠标控制
• 语音命令转键盘输入
• 呼吸传感器控制光标

2️⃣ 智能家居控制

• 一键场景切换
• 影音设备遥控器
• 环境参数调节

3️⃣ 嵌入式调试工具

• 无头系统配置
• 工业设备调试
• IoT设备远程控制

📄 开源许可信息

硬件设计遵循CERN OHL v1.2开源协议，软件部分采用MIT许可证。完整许可文本可在项目根目录的LICENSE文件中查看。

通过本指南，即使是零基础用户也能快速上手ESP32蓝牙鼠标键盘开发。项目开源特性允许无限扩展，无论是个人DIY还是商业应用，都能提供灵活可靠的无线输入解决方案。现在就动手打造你的专属ESP32输入设备吧！