如何用ESP32实现蓝牙HID设备：面向开发者的创新无线控制解决方案

2026-04-18 08:17:33作者：何将鹤

ESP32 implementation for HID over GATT Keyboard and Mouse (Bluetooth Low Energy). Including serial API for external modules (similar to Adafruit EZKey HID)

项目地址：https://gitcode.com/gh_mirrors/es/esp32_mouse_keyboard

ESP32蓝牙HID设备项目是一个基于ESP32芯片实现的蓝牙低能耗（BLE）人机交互设备（HID）解决方案，支持键盘和鼠标功能。该项目提供完整的硬件设计文件和软件代码，允许开发者通过简单配置即可构建自定义无线输入设备。无论是电子爱好者、嵌入式开发者还是DIY创客，都能利用此项目快速实现从概念到产品的转化，为智能设备开发提供灵活的无线控制方案。

10分钟了解蓝牙HID技术：从概念到应用

什么是蓝牙HID设备？

蓝牙HID（Human Interface Device）是一种通过蓝牙协议实现的人机交互设备标准，允许设备像传统USB鼠标、键盘一样与主机系统通信。与传统蓝牙相比，BLE（蓝牙低能耗）技术具有功耗低、连接快速的特点，非常适合电池供电的嵌入式设备。

💡 小贴士：HID协议最初是为USB设备设计的，后来被扩展到蓝牙技术中，形成了HID over GATT（Generic Attribute Profile）规范，这也是本项目采用的核心技术标准。

ESP32为何成为理想选择？

ESP32芯片集成了蓝牙和Wi-Fi功能，提供强大的处理能力和丰富的I/O接口，同时保持较低的功耗和成本。其内置的BLE控制器完全支持HID over GATT规范，使开发者能够专注于应用逻辑而非底层协议实现。

项目核心组件概览

项目主要由三部分组成：硬件设计文件、固件源代码和开发工具链。硬件部分包含PCB设计图和元件清单，软件部分基于ESP-IDF框架开发，提供HID设备实现和串口控制API，开发工具链支持一键编译和烧录。

30分钟完成硬件搭建：从元件到组装

核心材料清单

元件名称	规格参数	采购建议
ESP32-WROOM-32	双核32位处理器，集成BLE	选择带天线的模块版本
3.3V LDO稳压器	输出电流≥500mA	推荐RT9193或类似型号
电容	100uF(1206封装)，10uF(0603)，100nF(0603)	选用X7R材质，50V耐压
电阻	100kΩ(0603)，330Ω(0603)	精度±1%
黄色LED	1206封装	正向电压2.0-2.2V
MEMS麦克风	I2S接口	可选CMM-4030D-261

硬件组装步骤

PCB准备：根据项目提供的KiCad设计文件制作PCB，或使用洞洞板手工搭建
元件焊接：按照组装图放置并焊接元件，注意ESP32模块方向
电源测试：先不焊接ESP32，测试3.3V输出是否稳定
模块安装：焊接ESP32模块和排针接口
功能检查：连接USB-TTL转换器，检查串口通信是否正常

💡 小贴士：焊接ESP32模块时建议使用热风枪，避免烙铁温度过高损坏芯片。初学者可先在洞洞板上搭建测试电路，验证功能后再制作PCB。

从编译到烧录：ESP32固件开发全流程

开发环境配置检查清单

[ ] 安装ESP-IDF v4.4或更高版本
[ ] 配置交叉编译工具链
[ ] 安装Python依赖库
[ ] 配置USB转串口驱动
[ ] 验证Git工具是否安装

快速上手命令序列

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/es/esp32_mouse_keyboard
cd esp32_mouse_keyboard

# 配置项目
idf.py menuconfig

# 编译固件
idf.py build

# 烧录到设备（替换PORT为实际串口）
idf.py -p /dev/ttyUSB0 flash

# 启动监控终端
idf.py -p /dev/ttyUSB0 monitor

💡 小贴士：首次编译会下载依赖组件，可能需要较长时间。如果遇到编译错误，可尝试执行idf.py fullclean后重新编译。

基础功能测试

连接设备后，在监控终端中可使用以下命令测试基本功能：

w/a/s/d：控制鼠标上/左/下/右移动
l/r：鼠标左键/右键点击
q：发送测试字符"y"
$HELP：查看所有支持的命令

实用场景案例：解锁ESP32 HID设备潜力

案例一：无障碍辅助设备

场景描述：为行动不便人士设计的语音控制输入设备

实施方法：

连接语音识别模块到ESP32的UART接口
在main/ble_hidd_demo_main.c中添加语音命令解析逻辑
将语音指令映射为鼠标移动和键盘输入事件
调整config.h中的参数优化响应速度

效果对比：传统辅助设备价格通常超过2000元，而此方案总成本可控制在100元以内，且支持完全自定义功能。

案例二：智能家居控制中心

场景描述：通过手势控制实现家庭影院系统的一体化操作

实施方法：

连接PIR运动传感器到ESP32的GPIO引脚
在hid_dev.c中扩展自定义HID报告，添加手势识别数据
开发手机APP接收手势数据并转换为红外控制信号
编写自动化脚本实现场景模式切换

效果对比：相比传统遥控器，手势控制减少了物理按键数量，支持更自然的交互方式，响应延迟降低约30%。

进阶开发指南：自定义HID功能

修改键盘布局

编辑main/hid_dev.c文件中的HID报告描述符，可自定义键盘布局：

// 自定义键盘报告描述符示例
const uint8_t keyboard_report_map[] = {
  0x05, 0x01,        // 用法页(通用桌面)
  0x09, 0x06,        // 用法(键盘)
  0xA1, 0x01,        // 集合(应用)
  0x05, 0x07,        //   用法页(键盘)
  0x19, 0xE0,        //   用法最小值(左控制)
  0x29, 0xE7,        //   用法最大值(右GUI)
  0x15, 0x00,        //   逻辑最小值(0)
  0x25, 0x01,        //   逻辑最大值(1)
  // ... 其他描述符定义
};

💡 小贴士：HID报告描述符采用特定格式定义设备功能，修改时需遵循USB HID规范。可使用HID描述符工具辅助生成。

添加新设备类型

通过修改hid_dev.h和hid_dev.c文件，可扩展支持游戏手柄等其他HID设备类型：

// 在hid_dev.h中添加操纵杆报告ID
#define HID_RPT_ID_JOYSTICK_IN  0x03

// 定义操纵杆报告结构
typedef struct {
  int8_t x_axis;      // X轴值(-128~127)
  int8_t y_axis;      // Y轴值(-128~127)
  uint8_t buttons;    // 按钮状态(8个按钮)
} joy_stick_report_t;