ESP32 BLE HID 蓝牙鼠标键盘终极指南：从入门到实践 [特殊字符]

**ESP32 BLE HID 鼠标键盘**是一个基于ESP32微控制器的开源项目，通过蓝牙低能耗（BLE）技术实现无线鼠标和键盘功能，支持与电脑、平板和智能手机等设备连接，同时提供灵活的串行控制接口。## 一、什么是ESP32 BLE HID设备？### 1.1 核心功能解析 ⚙️ESP32 BLE HID设备本质是将ESP32开发板转变为蓝牙人机交互设备（HID），主要实现两大功能

gitblog_00051

1186人浏览 · 2025-11-10 05:53:03

gitblog_00051 · 2025-11-10 05:53:03 发布

ESP32 BLE HID 蓝牙鼠标键盘终极指南：从入门到实践 🚀

【免费下载链接】esp32_mouse_keyboard 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 BLE HID 鼠标键盘是一个基于ESP32微控制器的开源项目，通过蓝牙低能耗（BLE）技术实现无线鼠标和键盘功能，支持与电脑、平板和智能手机等设备连接，同时提供灵活的串行控制接口。

一、什么是ESP32 BLE HID设备？

1.1 核心功能解析 ⚙️

ESP32 BLE HID设备本质是将ESP32开发板转变为蓝牙人机交互设备（HID），主要实现两大功能：

无线鼠标：支持光标移动、左右键点击和滚轮操作
无线键盘：模拟标准键盘输入，兼容US键盘布局

该设备通过BLE协议与主机通信，无需复杂驱动，即连即用。项目还提供了设备切换、固件更新和配置存储等进阶功能，满足多场景使用需求。

1.2 适用场景推荐 🌟

智能家居控制：搭配传感器实现手势或环境触发的自动化输入
辅助设备开发：为行动不便人群定制专用输入方案
DIY创意项目：构建自定义游戏控制器、远程演示器等
物联网原型：快速验证需要人机交互的IoT设备功能

二、设备兼容性测试指南

2.1 已验证设备列表 📱💻

项目团队和社区已测试多种设备，兼容性情况如下：

设备类型	支持情况	备注
Windows 10/11 PC	✅ 完全支持	需CSR 4.0以上蓝牙适配器
macOS设备	✅ 完全支持	测试型号：MacBook Pro (Mid 2012)
iPad (iOS 13+)	✅ 部分支持	需开启辅助触控，可能显示WiFi干扰提示（可忽略）
Android设备	✅ 完全支持	测试型号：小米Mi A1 (LineageOS 16.0)
虚拟机环境	❌ 不支持	VirtualBox中Windows系统无法连接

2.2 连接问题排查 🔍

若遇到连接问题，建议：

确保ESP32已正确烧录固件并处于配对模式
尝试删除现有配对记录后重新连接
通过串口监控工具检查设备日志输出
确认目标设备蓝牙版本≥4.0（支持BLE）

三、硬件准备与组装教程

3.1 所需材料清单 🛠️

ESP32开发板（推荐esp32miniBT或Arduino Nano RP2040 Connect）
Micro-USB数据线（用于供电和烧录）
可选：面包板、杜邦线、外壳配件

3.2 硬件组装步骤 📦

对于esp32miniBT模块，可参考组装示意图：

图：ESP32 BLE HID设备硬件组装示意图

组装要点：

确保ESP32模块与外部控制器（如TeensyLC或ProMicro）正确连接
检查UART接口引脚定义，避免接错导致损坏
如需使用外部电源，确保电压稳定在3.3V

四、固件烧录完整步骤

4.1 开发环境搭建 🔧

安装ESP-IDF框架
按照Espressif官方指南搭建开发环境：

# 克隆ESP-IDF仓库（指定支持版本）
git clone -b release/v5.0 https://gitcode.com/gh_mirrors/es/esp32_mouse_keyboard.git
cd esp32_mouse_keyboard
./install.sh
. ./export.sh

配置目标设备
通过菜单配置选择正确的硬件型号：
```
idf.py menuconfig
```
在配置菜单中选择"Board Support" → "Target Board Type"

4.2 固件编译与烧录 🚀

# 编译项目
idf.py build

# 烧录到ESP32（替换COM3为实际端口）
idf.py -p COM3 flash

# 启动串口监控
idf.py -p COM3 monitor

烧录成功后，ESP32将自动重启并进入蓝牙配对模式，LED指示灯会快速闪烁。

五、基础使用方法

5.1 设备配对流程 📱

确保ESP32已上电，处于待配对状态
在目标设备上打开蓝牙设置，搜索新设备
选择名称类似"ESP32-HID"的设备进行配对
配对成功后，设备将自动连接（部分设备可能需要输入PIN码"0000"）

5.2 基本功能测试 ⌨️🖱️

通过串口监控工具发送以下命令测试基本功能：

按键	功能	说明
w	鼠标上移	每次移动30像素
s	鼠标下移	每次移动30像素
a	鼠标左移	每次移动30像素
d	鼠标右移	每次移动30像素
l	左键点击	模拟鼠标左键单击
r	右键点击	模拟鼠标右键单击
q	测试输入	发送字符"y"

六、高级功能配置

6.1 多设备切换指南 🔄

支持在多个已配对设备间快速切换：

查看已配对设备
通过串口发送命令：$GP
设备将返回所有配对设备的MAC地址列表
切换目标设备
使用命令：$SW 001122334455
其中"001122334455"是目标设备的MAC地址

6.2 配置参数存储方法 💾

通过NVS（非易失性存储）功能保存自定义配置：

# 设置键值对
$SV device_name MyESP32HID

# 获取键值
$GV device_name

# 清除所有配置
$CV

常用可配置参数包括设备名称、默认连接设备和串口波特率等。

七、常见问题解决

7.1 连接频繁断开怎么办？

可能原因及解决方法：

距离过远：确保设备间距离不超过10米
电源不稳定：使用独立电源或高质量USB线
蓝牙干扰：远离WiFi路由器、微波炉等干扰源
固件版本问题：确保使用ESP-IDF v5.0版本编译固件

7.2 如何更新设备固件？

通过串行接口更新固件：

发送固件更新命令：$UG
设备将重启并进入固件接收模式
使用专用工具通过UART发送新固件.bin文件

八、项目贡献与社区支持

8.1 提交设备测试报告 📝

如果您测试了新设备，欢迎通过以下方式贡献测试结果：

在项目仓库创建新issue，添加"device-testreport"标签
包含设备型号、系统版本和测试结果
描述测试的功能和遇到的问题（如有）

8.2 获取帮助与资源 🤝

项目文档：查看仓库中的README.md和硬件设计文件
社区支持：通过项目issue系统提问
源码贡献：Fork项目后提交Pull Request

九、进阶开发建议

9.1 自定义HID报告 📊

如需扩展功能，可修改HID报告描述符：

// 在hid_dev.c中修改报告定义
static const uint8_t mouse_report_desc[] = {
    // 自定义鼠标报告格式
    0x05, 0x01,        // Usage Page (Generic Desktop)
    0x09, 0x02,        // Usage (Mouse)
    // ... 报告描述符内容 ...
};

9.2 串行API应用开发 🖥️

外部控制器可通过UART发送HID指令，例如模拟键盘输入：

// 发送"Hello"的示例代码（Arduino平台）
uint8_t keyboard_report[] = {0xFD, 0x00, 0x00, 
                             0x08, 0x05, 0x0C, 0x0C, 0x0F, 0x00};
Serial.write(keyboard_report, sizeof(keyboard_report));