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

2026-04-18 08:58:33作者：伍霜盼Ellen

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 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;