别再死磕USB HID了！用ESP32的Arduino框架手把手教你实现蓝牙鼠标键盘（附完整代码）

ESP32蓝牙HID实战：零基础打造自定义键盘鼠标

手里那块吃灰的ESP32开发板终于能派上用场了！上周我用它做了个无线演示控制器，在会议室里走着就能翻PPT，同事们都问是怎么实现的。其实秘诀就在于ESP32的蓝牙HID功能——不需要任何USB线缆，也不用理解复杂的HID协议栈，用Arduino框架几个现成的库就能搞定。

1. 开发环境准备

1.1 硬件选择建议

ESP32系列开发板中，这些型号特别适合HID项目：

我用的是一块淘来的ESP32-WROOM-32D，价格不到30元。别被开发板上那些密密麻麻的引脚吓到，我们实际只需要用到：

• USB接口（供电和烧录）
• Boot按钮（下载模式切换）
• EN按钮（复位）

1.2 软件环境配置

首先确保Arduino IDE已安装ESP32支持包。如果还没安装，在首选项的"附加开发板管理器网址"中添加：

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

然后安装这两个关键库：

#include <BleCompositeHID.h> #include <BleMouse.h> #include <BleKeyboard.h>

库安装完成后，在开发板管理器中选择"ESP32 Dev Module"。有个小技巧：把编译优化等级调到"Faster"可以显著减少编译时间。

2. 蓝牙鼠标快速实现

2.1 基础鼠标功能

让我们从最简单的鼠标移动开始。新建一个Arduino项目，输入以下代码：

BleMouse mouse("ESP32-Mouse", "MakerSpace", 100); void setup() { Serial.begin(115200); mouse.begin(); } void loop() { if(mouse.isConnected()) { mouse.move(10, 0); // 向右移动10像素 delay(500); mouse.click(MOUSE_LEFT); // 左键单击 delay(500); } }

上传代码后，在电脑蓝牙设置里会发现名为"ESP32-Mouse"的设备。连接成功后，你会看到光标每秒钟向右移动一次并自动点击。

2.2 高级鼠标控制

实际项目中我们可能需要更精细的控制。比如做一个演示翻页器：

#define BUTTON_PIN 0 // 使用GPIO0作为按钮 BleMouse mouse; void setup() { pinMode(BUTTON_PIN, INPUT_PULLUP); mouse.begin(); } void loop() { static bool lastState = HIGH; bool currentState = digitalRead(BUTTON_PIN); if(currentState == LOW && lastState == HIGH) { mouse.move(0, 0, 1); // 滚轮向下滚动 } lastState = currentState; delay(50); }

这个代码实现了：

• 使用开发板上的Boot按钮(GPIO0)控制
• 按下时触发滚轮滚动
• 内置防抖处理

常见问题排查：

• 如果设备不可见，检查蓝牙是否启用
• 连接不稳定时尝试降低BLE广播间隔
• 按键无响应时检查GPIO模式设置

3. 蓝牙键盘实战

3.1 基础键盘功能

键盘的实现同样简单。以下代码实现了一个发送组合键的宏键盘：

BleKeyboard keyboard("ESP32-Keyboard", "MakerSpace", 100); void setup() { keyboard.begin(); } void loop() { if(keyboard.isConnected()) { keyboard.press(KEY_LEFT_CTRL); keyboard.press('s'); delay(100); keyboard.releaseAll(); delay(5000); } }

这段代码每5秒发送一次Ctrl+S保存组合键。实际测试时建议先打开记事本观察效果。

3.2 多媒体键盘扩展

ESP32还能模拟多媒体键盘。比如做个音乐控制器：

#include <BleKeyboard.h> BleKeyboard keyboard; void setup() { keyboard.begin(); } void sendMediaKey(uint8_t key) { keyboard.write(key); delay(200); } void loop() { if(keyboard.isConnected()) { sendMediaKey(KEY_MEDIA_PLAY_PAUSE); delay(3000); sendMediaKey(KEY_MEDIA_VOLUME_UP); delay(1000); } }

支持的多媒体键包括：

• KEY_MEDIA_PLAY_PAUSE
• KEY_MEDIA_VOLUME_UP/DOWN
• KEY_MEDIA_MUTE
• KEY_MEDIA_NEXT_TRACK
• KEY_MEDIA_PREVIOUS_TRACK

4. 复合设备与高级应用

4.1 键盘鼠标二合一

真正的生产力工具应该同时具备键盘和鼠标功能。使用BleCompositeHID库可以轻松实现：

#include <BleCompositeHID.h> BleCompositeHID compositeHID("ESP32-Combo"); BleKeyboard keyboard; BleMouse mouse; void setup() { keyboard.setBatteryLevel(80); mouse.setBatteryLevel(80); compositeHID.addHID(keyboard); compositeHID.addHID(mouse); compositeHID.begin(); } void loop() { if(compositeHID.isConnected()) { mouse.move(random(-5,5), random(-5,5)); delay(100); if(millis() % 5000 == 0) { keyboard.print("Hello from ESP32!\n"); } } }

这个例子展示了：

• 同时模拟键盘和鼠标
• 设置虚拟电量显示
• 随机移动鼠标光标
• 定时发送字符串

4.2 游戏控制器实现

通过修改HID描述符，ESP32还能变身游戏手柄。需要先定义特殊的报告映射：

static const uint8_t gamepadReportMap[] = { 0x05, 0x01, 0x09, 0x05, 0xA1, 0x01, 0x15, 0x00, 0x25, 0x01, 0x35, 0x00, 0x45, 0x01, 0x75, 0x01, // 省略具体描述符... }; BleGamepad gamepad("ESP32-Gamepad"); void setup() { gamepad.setReportMap(gamepadReportMap, sizeof(gamepadReportMap)); gamepad.begin(); } void loop() { if(gamepad.isConnected()) { gamepad.setAxes(127, 0, 0, 0, 0, 0, 0, 0); delay(100); } }

完整实现需要约50字节的报告描述符，可以在GitHub上找到现成的模板。实际测试时，这个方案在Android和Windows上都能被识别为标准的游戏控制器。

5. 功耗优化与稳定性

5.1 低功耗配置

默认设置下ESP32蓝牙功耗约20mA，通过以下调整可降至5mA以下：

#include <BLEDevice.h> void setup() { BLEDevice::setPower(ESP_PWR_LVL_N12); // 最低功率 bleKeyboard.begin(); esp_ble_conn_update_params_t params; params.latency = 6; // 增加连接间隔 esp_ble_gap_update_conn_params(&params); }

关键优化点：

• 设置发射功率为-12dBm
• 增加连接间隔到100ms
• 禁用不必要的蓝牙服务

5.2 连接稳定性技巧

在办公室这种无线环境复杂的地方，这些设置能显著改善连接质量：

void improveConnection() { esp_wifi_set_ps(WIFI_PS_NONE); // 禁用Wi-Fi省电 esp_ble_tx_power_set(ESP_BLE_PWR_TYPE_DEFAULT, ESP_PWR_LVL_P9); esp_ble_gap_set_prefer_conn_params(6, 12, 0, 400); }

实测发现，将发射功率提升到+9dBm后，连接距离从5米延长到了15米。不过要注意这会增加功耗，建议根据实际需求调整。