简介一套基于Visual C的蓝牙HCI通信程序源码面向想入门蓝牙协议栈的VC开发者帮助理解主机与控制器之间的核心交互流程。包内共25个文件以C头文件和源文件为主辅以工程配置、资源脚本及文本说明整体约69KB目录清晰便于按模块学习。目前已有591人学习/下载。代码覆盖适配器初始化与参数配置、HCI命令和事件交互、数据包封装与收发、错误处理及中断管理等关键环节同时涉及配对安全机制、SDP服务发现和多设备连接逻辑并演示了Windows蓝牙API的典型调用方式。初学者可借助这份代码掌握蓝牙应用从适配器打开到连接释放的完整流程也能基于现有框架修改扩展用于自定义蓝牙服务或低功耗应用开发。1. 为什么还要在 VC 环境里写 HCI拿到这套 BluetoothHCI 源码时很多人第一反应是“Windows 不是自带蓝牙协议栈吗直接用BluetoothFindFirstDevice不就行了”。但当你真正开始调 CSR、Broadcom 这类经典蓝牙控制器或者想把一个裸的 HCI UART 模块接入自己的板子时系统 API 很快就到边界了——它管不到控制器内部的连接参数、RSSI、调频跳频序列更拿不到底层 HCI Event。BluetoothHCI_蓝牙VC源代码这套工程的价值在于它把 VC MFC 对话框程序直接打在 HCI 层上用BT_HCI.cpp构造命令包、用SerialPort.cpp走串口传输等工作在“主机与控制器之间”这一层。对蓝牙协议栈开发者、嵌入式工程师和准备做经典蓝牙BR/EDR测试工具的人这是能真正动手改协议细节的起点而不是套壳调 API。2. HCI 分层模型与这个工程的项目结构2.1 HCI 在蓝牙协议栈中的位置在经典蓝牙的物理层Radio和 L2CAP 之间HCI 是一道明确的软件分界线。它不像 L2CAP 那样管分段重组也不像 SDP 那样做服务发现它只干一件事把主机侧的 HCI 命令变成控制器能执行的指令再把控制器的状态变化变成主机能读懂的事件。这套BluetoothHCI源码把这条线拉得很干净BT_HCI.h定义命令和事件的构造/解析结构BasePort.cpp抽象了“发送一串字节”和“接收一串字节”SerialPort.cpp实现 Windows 串口收发DevicePort.cpp则把设备句柄与端口绑定。你从Bluetooth HCIDlg.cpp的按钮消息里点一下“打开适配器”实际执行的路径是 UI → DevicePort → SerialPort → HCI Reset Command → 等待 Complete Event。HCI 包永远是四选一没有第五种命令包Host 发往 Controller、事件包Controller 主动回报、ACL 数据包异步面向连接的数据、SCO/eSCO 数据包同步语音数据。源码里BT_HCI.cpp对前两种处理得最完整这也对应了大部分人用 HCI 的第一阶段——先把控制器“叫醒”再让它报告周围环境。包类型方向首字节Packet Indicator典型用途HCI CommandHost → Controller0x01重置、查询、连接、读 RSSIHCI EventController → Host0x04命令完成、查询完成、连接完成HCI ACL Data双向0x02音频、文件、ATT 等逻辑信道数据HCI SCO Data双向0x03同步语音免提场景这四类包在一根 UART 线上分时复用所以SerialPort.cpp里必须有严格的字节流状态机不能用简单的ReadFile一次读一包——常见做法是读到一个包指示字节后再根据Parameter Total Length决定读多少个字节凑齐一包。源码里BasePort.cpp维护的接收缓冲就是这个用途。2.2 源码模块怎么对应 HCI 操作这套工程用的是 VS2008 时代的.vcproj.sln工程结构Bluetooth HCI.vcproj一打开就能看到Bluetooth HCIDlg.cpp是主对话框实现BT_HCI.cpp是协议核心。从文件命名能推断出作者有意分了三层BasePort定义接口和公共收发逻辑SerialPort负责串口细节DevicePort负责把逻辑端口绑定到具体设备。这种分层对后来做蓝牙测试工装的人很有参考价值——换传输介质时只改SerialPort.cpp上层 HCI 构造完全不用动。Bluetooth HCI.rc、Bluetooth HCI.rc2、Bluetooth HCI.ico、Bluetooth HCI.manifest是 MFC 的资源文件stdafx.h是预编译头resource.h定义控件 ID。ReadMe.txt在原始工程里一般只是 VC 生成的模板说明但结合代码看这套工程的启动流程是对话框初始化时枚举串口选定端口后打开接着发 HCI_Reset收到 Command Complete 后更新状态栏。对初学蓝牙编程的人来说这个流程比直接读蓝牙核心规范直观得多因为你能在 VC 调试器的单步执行里看到一字节一字节的包是怎么组出来的。3. 串口传输层实现与初始化参数设置3.1 SerialPort 封装的关键点HCI over UART 的标准做法是空闲线路为高电平波特率由控制器决定常见有 9600、57600、115200、921600 等。BluetoothHCI源码里的SerialPort.cpp走的正是这条路径——CreateFile打开COMxSetCommState设置波特率SetCommTimeouts设置超时再用ReadFile和WriteFile收发字节。// SerialPort.cpp 核心初始化代码示意 BOOL SerialPort::Open(CString portName, DWORD baudRate) { // 1. 打开串口FILE_FLAG_OVERLAPPED 表示异步 HANDLE hComm CreateFile(portName, GENERIC_READ | GENERIC_WRITE, 0, NULL, OPEN_EXISTING, FILE_FLAG_OVERLAPPED, NULL); if (hComm INVALID_HANDLE_VALUE) return FALSE; // 2. 设置 DCB8 数据位 / 无校验 / 1 停止位 DCB dcb { 0 }; dcb.DCBlength sizeof(DCB); GetCommState(hComm, dcb); dcb.BaudRate baudRate; // 例如 115200 或 921600 dcb.ByteSize 8; dcb.Parity NOPARITY; dcb.StopBits ONESTOPBIT; SetCommState(hComm, dcb); // 3. 设置超时避免 ReadFile 永久阻塞 COMMTIMEOUTS timeouts { 0 }; timeouts.ReadIntervalTimeout 50; timeouts.ReadTotalTimeoutConstant 50; timeouts.ReadTotalTimeoutMultiplier 10; SetCommTimeouts(hComm, timeouts); m_hComm hComm; return TRUE; }第一步的FILE_FLAG_OVERLAPPED是异步句柄标志意味着所有串口读写都要配合OVERLAPPED结构不能用同步ReadFile的简单方式去等数据。这里的ReadIntervalTimeout50是关键——HCI 事件包长度不定主机不知道控制器什么时候发完间隔超时保证ReadFile在 50ms 内没有新字节就返回线程就能检查缓冲里有没有完整的一包。dcb.ByteSize8和ONESTOPBIT是绝大多数蓝牙 UART 模块的标准参数如果接的是 HC-05 这类模块对方默认反而经常是 38400 波特率且带 AT 命令层这时候要先用 AT 命令把角色和波特率切到透明串口模式再谈 HCI。第二段要说明SerialPort类里还要维护一个环形接收队列原因是 HCI 命令的响应Command Status 或 Command Complete不一定按你发送的顺序立刻返回控制器可能先上报一个之前触发的事件。一般做法是// 读取线程持续收字节交给解析器 DWORD WINAPI SerialPort::ReceiveThread(LPVOID param) { SerialPort* pThis (SerialPort*)param; BYTE buffer[256]; DWORD bytesRead 0; OVERLAPPED ov { 0 }; ov.hEvent CreateEvent(NULL, TRUE, FALSE, NULL); while (pThis-m_bRunning) { // 异步读最多读 256 字节 BOOL ok ReadFile(pThis-m_hComm, buffer, sizeof(buffer), bytesRead, ov); DWORD err GetLastError(); if (!ok err ERROR_IO_PENDING) { // 等待数据到达或超时 WaitForSingleObject(ov.hEvent, 200); GetOverlappedResult(pThis-m_hComm, ov, bytesRead, FALSE); } if (bytesRead 0) { // 把收到的字节追加到协议解析缓冲 pThis-m_parser.Append(buffer, bytesRead); } ResetEvent(ov.hEvent); } return 0; }这里线程循环用 200ms 等待窗口做超时控制保证程序退出或串口断开时线程能及时响应。m_parser.Append内部会检查字节流中的 0x01/0x04 等包指示字节截出完整的 HCI 包再回调 UI。Bluetooth HCIDlg.cpp里你看到的连接状态、设备列表更新都是由这个回调驱动的而不是对话框主动去轮询。3.2 发送命令与等待事件的线程模型MFC 对话框程序最容易犯的错是在 UI 线程里直接WaitForSingleObject等控制器响应这会导致界面卡死。这套源码的常见改良做法是UI 线程只把“要发的命令”放进队列工作线程从队列取命令、写串口、等事件解析结果再发PostMessage通知对话框刷新。构造一个 HCI 命令包的基本样子如下// 构造 HCI Command 包并发送 BOOL SendHciCommand(BYTE ogf, BYTE ocf[2], BYTE* param, BYTE paramLen) { BYTE packet[260]; packet[0] 0x01; // HCI Command Packet 标志 packet[1] ogf; // OpCode 低字节含 OGF packet[2] ocf[0]; // OpCode 高字节 packet[3] paramLen; // Parameter Total Length memcpy(packet 4, param, paramLen); return SerialPort::Write(packet, 4 paramLen); }参数含义逐条说packet[0]0x01是整个蓝牙 UART 传输层识别命令包的标记任何不是 0x01 开头的字节都不能算是命令包起始packet[1]和packet[2]拼成一个 16 位 OpCode其中高 6 位是 OGFOpCode Group Field用来区分这个命令属于链路控制0x01、链路策略0x02、控制器与基带0x03还是 LE 控制器0x08packet[3]声明参数区长度这样控制器才能知道命令包在哪结束。调用时如果发HCI_ResetOGF0x03OCF0x0003参数区为空paramLen0整包只有四个字节。4. HCI 命令与事件实战设备查询、连接与断开4.1 HCI_Reset 与 Read Local Version 的完整流程拿到控制器后第一个命令永远是 HCI_Reset。它把控制器恢复到上电默认状态清掉所有连接和配对信息。发送01 03 0C 00四个字节后控制器会返回一个 Command Complete 事件04 04 04 03 0C 00 00其中0x04是事件包标志第二个0x04是参数总长第三个0x04是事件码Command Complete最后一个0x00是 Status只有 Status 为 0 才代表复位成功。// 发送 HCI_Reset 并校验 Command Complete BOOL ResetController() { BYTE cmd[4] { 0x01, 0x03, 0x0C, 0x00 }; // HCI_Reset if (!SendHciCommand(cmd, sizeof(cmd))) return FALSE; HciEvent evt; if (!WaitNextEvent(evt, 2000)) return FALSE; // 最多等 2 秒 // 检查: 事件码是 0x0E(Command Complete)且 OpCode 等于 0x0C03 if (evt.eventCode ! 0x0E) return FALSE; if (evt.data[0] ! 1) return FALSE; // Num_HCI_Command_Packets if ((evt.data[1] | (evt.data[2] 8)) ! 0x0C03) return FALSE; return (evt.data[3] 0x00); // Status 必须为 0 }WaitNextEvent内部调ReceiveThread塞进来的缓冲解析超时 2 秒是因为大多数 CSR 控制器复位时间在几百毫秒内超过 2 秒多半是波特率不匹配或者模块没上电。evt.data[0]1表示控制器还能接收的命令槽位evt.data[1..2]是这次完成的是哪个 OpCodeevt.data[3]是命令执行结果。这套校验逻辑对所有 HCI 命令通用所以源码里BT_HCI.cpp通常会封装出SendCommandAndWaitComplete(ogf, ocf, param, paramLen)这样一个统一入口。4.2 Inquiry 扫描与读取 RSSI经典蓝牙的“发现设备”对应 HCI_InquiryOGF0x01OCF0x0001。这个命令是非阻塞的控制器会进入查询扫描状态一段时间然后回调 Inquiry Complete 事件。参数区有三个字段LAPLower Address Part通常用 0x9E8B33 发现所有设备、查询时长以 1.28 秒为单位、最大响应数。示例// 发起 5.12 秒的查询最多返回 10 个设备 BYTE inquiry[5] { 0x33, 0x8B, 0x9E, 0x04, 0x0A }; SendHciCommand(0x01, 0x0001, inquiry, sizeof(inquiry)); // 之后控制器会陆续上报 Inquiry Result 事件(0x02)等待 Inquiry Complete(0x01)参数解释0x33 0x8B 0x9E是 LAP 的 little-endianGIACGeneral Inquiry Access Code所有可发现设备都要响应这个 LAP0x04代表 4 × 1.28 5.12 秒0x0A是最大响应数。事件上报时会给出蓝牙地址BD_ADDR、页扫描重复模式、设备类别和 RSSI——如果你拿来做蓝牙测距实验读到的就是这里面的 RSSI 字段配合发射功率能粗略估算距离。但注意这叫蓝牙测距不叫精确定位反射、遮挡对 RSSI 影响很大5 米内勉强能用再远就只能看趋势。连接某个设备用 HCI_Create_ConnectionOGF0x01OCF0x0005参数区需要 BD_ADDR、包类型、页扫描重复模式等。断开用 HCI_DisconnectOGF0x01OCF0x0006参数区是连接句柄和断开原因。这两步的返回事件分别是 Connection Complete0x03和 Disconnection Complete0x05解析思路与上面一样先确认事件码再取Connection_Handle最后检查 Status。4.3 与 HC-05、CSR 模块的兼容性差异这里必须区分两类硬件否则照着代码接 HC-05 会发现根本收不到 HCI 事件。HC-05 内部已经跑了一个完整的蓝牙协议栈暴露给用户的是串口透明的 SPP 服务和 AT 命令接口它不是一个“裸 HCI 控制器”。所以网上常见问题“hc05蓝牙模块连接不上”往往是指串口收不到 AT 响应跟 HCI 没直接关系。而 CSR BC417、CSR8510 或 Broadcom BCM20702 这类芯片在 UART 引脚上跑的才是真正的 HCI 协议这套 VC 代码才能直接驱动。区分方法很简单看模块有没有引出 PIO、PCM、SPI 这类控制器引脚纯 HCI 模块通常要外接 Flash 和晶振HC-05 是一体化方案。BLE蓝牙 LE的情况也要提一句BluetoothHCI源头代码主要围绕经典蓝牙BR/EDR写如果你要接的是低功耗设备HCI 层的命令群要换成 OGF0x08LE Controller Commands并且传输层的 ACL 数据要支持 ATT 包。常见做法是在BT_HCI.cpp里增加一个SendLeCommand分支把 OGF 固定为 0x08其余流水线通用。5. HCI 抓包与日志验证命令时序的三个技巧HCI 层调试最痛苦的是“不知道命令到底发出去没有”。即使代码里的SendHciCommand返回成功也只代表WriteFile把字节交给了驱动控制器是否真的执行、是否报错必须看事件。我的惯用做法是先给SerialPort.cpp加一个日志开关把收发的每个字节连同时间戳写进文件。// 日志开关记录收发的 HCI 包输出十六进制 void LogHciPacket(BYTE* data, DWORD len, BOOL isTx) { CString line; CString timeStr; SYSTEMTIME st; GetLocalTime(st); timeStr.Format(L%02d:%02d:%02d.%03d, st.wHour, st.wMinute, st.wSecond, st.wMilliseconds); line.AppendFormat(L%s %s , timeStr, isTx ? LTX : LRX); for (DWORD i 0; i len; i) { line.AppendFormat(L%02X , data[i]); } OutputDebugString(line); // 输出到调试器 WriteLogToFile(line); // 同步写入文本 }判断命令是否被正确执行优先看事件里的 Status 字节不要只看有没有收到0x0E。比如 HCI_Create_Connection 可能返回Status0x0CConnection Timeout或Status0x04Hardware Failure含义完全不同。一个可靠的自检流程是Reset → Read Local Version → Read BD_ADDR → Inquiry → Cancel Inquiry → 关闭端口每一步都校验事件码和 Status。这套流程跑通了说明从串口参数到 HCI 状态机全部正确。第二个技巧是比对抓包工具的时序。USB 蓝牙适配器加 Wireshark 的btmon或extcap抓到的 HCI 包和你自己串口日志里的包应该逐字节一致。如果同样的操作厂商工具里的 HCI 命令顺序和你的代码不一样要以厂商工具为准调顺序——典型的坑是忘记先HCI_Write_Scan_Enable打开可连接模式导致后续建链失败。第三个技巧是给对话框加一个“Raw 命令发送”编辑框直接填十六进制字节这样不用重新编译就能跑各种命令组合排查“是不是代码组包组错了”这类问题时特别省时间。BluetoothHCI这套代码虽然年代老、界面朴素但把 HCI 这条主线留得足够清晰拿它当基底改一套自己的蓝牙调试工具比从零搭串口状态机快得多。本文还有配套的精品资源点击获取
