ESP32蓝牙键盘DIY全攻略：从零实现HID设备（附完整代码解析）

ESP32蓝牙键盘DIY全攻略：从零实现HID设备（附完整代码解析）

你是否曾想过，手边那块小小的ESP32开发板，除了连接Wi-Fi、驱动传感器，还能摇身一变，成为一把完全由你定义的蓝牙键盘？无论是想为智能家居打造一个专属的物理控制面板，还是为你的游戏设备制作一个宏命令快捷键键盘，亦或是单纯想深入理解蓝牙HID（人机接口设备）协议栈的运作机理，基于ESP32的蓝牙键盘DIY都是一个绝佳的切入点。这不仅仅是复制粘贴一段代码，而是从协议层到应用层，亲手搭建一个能与电脑、手机无缝对话的智能外设。本文将带你穿越理论迷雾，直抵实战核心，用清晰的步骤和可运行的代码，构建属于你自己的蓝牙输入设备。

1. 理解蓝牙HID与HOGP：协议基石

在开始焊接电路或编写代码之前，我们需要先弄清楚蓝牙键盘是如何被操作系统“无感”识别的。关键在于一套名为HOGP的规范。

HOGP，全称HID Over GATT Profile，是蓝牙低功耗（BLE）中用于实现键盘、鼠标等HID设备的标准化协议。它构建在GATT（通用属性协议）之上。你可以把GATT理解为BLE设备间数据交换的“语言”和“规则”，而HOGP则是用这种“语言”专门描述“键盘动作”的“方言”。

为什么你的自制键盘能被Windows、macOS或Android直接识别，而无需安装额外驱动？因为主流操作系统内部都内置了HOGP客户端。当你的ESP32设备广播自己是一个HID设备时，系统会主动与之建立连接，并按照预定义的“对话格式”来解读ESP32发送的数据包。这个“对话格式”的核心，就是属性表和报告映射。

提示：GATT通信的核心是“属性”（Attribute），每个属性都有一个唯一的“句柄”（Handle）、一个“类型”（UUID）和一个“值”（Value）。HID服务就是一系列特定UUID的属性集合。

一个完整的蓝牙HID键盘，其GATT服务器通常包含两个主要服务：

1. 电池服务：用于向主机报告设备的剩余电量。
2. HID服务：这是核心，定义了设备类型、功能以及数据报告格式。

HID服务内部包含几个关键特征值，其关系与作用如下表所示：

其中，报告映射是一段按照HID规范编写的描述符，它像一份“产品说明书”，精确描述了数据报告中每一个字节、甚至每一个比特位的含义。例如，它规定了报告的第一个字节的8个比特分别对应Ctrl、Shift、Alt、GUI（Win键）等修饰键，而后续的6个字节则对应最多6个同时按下的普通按键值。

2. 搭建ESP32开发环境与项目框架

工欲善其事，必先利其器。我们将使用乐鑫官方的ESP-IDF开发框架，它提供了完整的蓝牙协议栈实现，极大简化了我们的开发工作。

2.1 环境准备与工程创建

首先，确保你的计算机上已安装好ESP-IDF开发环境。这里以ESP-IDF v5.0及以上版本为例。

# 1. 获取ESP-IDF
mkdir -p ~/esp
cd ~/esp
git clone -b v5.1 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh all

# 2. 激活环境（每次打开新终端都需要执行）
. ./export.sh

# 3