简介BLUE源码XE10是一套面向Embarcadero Delphi XE10开发环境的源代码集合面向希望深入理解Object Pascal语言、RAD快速开发理念及跨平台应用构建方法的Delphi开发者。压缩包整体约358.54MB已有547人浏览学习。源码围绕软件工程实践展开包含模块划分、类与接口设计、数据结构与算法应用等典型实现通过逐行阅读能够看清大型项目的组织脉络与核心业务逻辑。其中关于FireMonkey框架的部分值得重点关注可对比同一套代码在Windows、iOS、Android上的界面渲染与交互差异学习真正的跨平台开发思路同时也可借助Delphi内置调试器练习断点、单步执行、变量监视和调用栈分析等排错技巧。此外代码中体现的异常处理、组件封装、注释规范与命名习惯展示了企业级开发常用的最佳实践对新手建立良好编码习惯和资深开发者优化架构设计均具有参考价值。1. BLUE源码XE10是什么一套拿来就能跑的BLE协议栈还是一堆看不懂的C文件拿到一块带蓝牙的SoC开发板SDK里躺着一个叫BLUE的源码目录版本号写着XE10。很多人的第一反应是打开它然后被几百个C文件劝退。BLUE源码XE10不是某个厂商的闭门造车而是这套芯片官方SDK里的BLE协议栈实现覆盖从链路层、主机协议到GAP、GATT的全套逻辑。它的价值在于给你一个能直接编译进固件的蓝牙协议栈让你不用从零实现广播、连接、配对和OTA真正要你做的是在它上面搭自己的应用。这篇笔记适合刚接触BLE协议栈源码、想在XE10平台上把第一个广播跑起来并计划做自定义服务和OTA的开发者。我会按源码结构、最小工程、调参、踩坑、进阶的顺序讲全部是能复现的步骤。2. 先拆源码结构BLUE的目录布局与从上电到广播的执行链路2.1 源码分层BLUE把BLE协议栈拆成了哪几层每层该看什么BLUE源码XE10的内部结构和大部分商业BLE协议栈一样按照蓝牙标准的分层模型组织。不要一上来就按字母序读文件先认清这几层的职责后面查问题才有方向。目录/模块对应协议层你在这个目录里要找的东西ll/链路层 Link Layer广播、扫描、连接的底层状态机RF前端控制、白名单、信道选择hci/主机控制器接口命令、事件、数据的封装与解析通常只在调试和透传模式用l2cap/逻辑链路控制与适配协议分片重组、MTU协商、基于信道的数据分发gap/通用访问规范广播参数、连接参数、绑定管理、角色切换gatt/通用属性规范服务、特征的注册属性读写回调分发smp/安全管理配对、密钥分配、加密、签名port/平台移植层时钟、中断、GPIO、Flash读写、随机数、功耗管理的对接app/应用示例透传、心率计、OTA等参考实现这里有个常见误解以为gatt/目录就是整个BLE协议栈的全部。实际上GATT只是最上层的属性交互规则广播能不能被手机搜到取决于ll/和gap/连接能不能稳定保持取决于ll/里的连接事件调度和l2cap/的参数协商。所以排查问题时先定位问题出现在哪一层再打开对应目录而不是在app/里反复加日志。我在读BLUE源码XE10时习惯先把port/目录通读一遍因为平台移植层的代码决定了这套协议栈能不能在你手里这块芯片上跑起来。其他地方看不懂可以先跳过但port/里的时钟配置、中断向量、内存分配函数必须逐行确认它们和硬件绑定最紧也是最容易因芯片型号差异而出错的地方。2.2 关键结构体与配置表广播、连接、功耗的默认参数藏在哪BLUE源码XE10的配置不是散落在各个C文件里的魔法数字而是集中在几个头文件的配置结构体里。我以最常见的广播和连接配置为例说明这些参数的位置和含义。不同版本的BLUE源码字段名可能略有差异但语义是一致的。/* 文件app_config.h精简后的广播与连接参数配置 */ adv_param_t adv_config { .adv_int_min_ms 100, /* 广播间隔最小值单位毫秒 */ .adv_int_max_ms 150, /* 广播间隔最大值实际间隔在此区间内随机 */ .adv_type ADV_TYPE_IND, /* 可连接非定向广播手机能发起连接 */ .channel_map CH_ALL, /* 37/38/39三个信道全开 */ .filter_policy FILTER_ALLOW_ALL, /* 不启用白名单过滤 */ .local_addr_type ADDR_TYPE_PUBLIC, /* 使用公共地址需烧录有效MAC */ }; conn_param_t conn_config { .interval_min_ms 15, /* 从机希望使用的连接间隔下限 */ .interval_max_ms 30, /* 从机希望使用的连接间隔上限 */ .slave_latency 0, /* 从机跳过连接事件的最大次数 */ .supervision_timeout_ms 4000, /* 链路监控超时超过则判定连接断开 */ };广播间隔的单位在协议栈内部会被换算成时间片的倍数。BLE标准规定时间片是0.625毫秒所以100毫秒的配置在寄存器里是160。修改时你要么确保上层配置结构体做了换算要么直接按协议栈提供的毫秒接口赋值否则广播间隔会和你预期差很多手机端扫描到的间隔浮动也会异常。连接参数里最容易被忽略的是supervision_timeout_ms。BLE规范要求它必须大于连接间隔的最大值乘以(slave_latency 1)再乘以2否则连接建立后会被对端直接判定为无效参数而断开。我见过不少开发者把超时设成2000毫秒连接间隔又允许到100毫秒以上结果就是连接一建立就断后台日志里反复出现连接超时事件。2.3 从reset到能搜到设备BLUE源码里的一条主调用链先弄清BLUE源码XE10从上电到发出第一个广播包中间发生了什么。按执行顺序看这段调用链会帮你建立整体认知之后改任何功能都知道往哪个函数里加代码。/* 主流程简化示意按实际源码整理 */ int main(void) { system_clock_init(); /* 配置系统主时钟和外设时钟BLE协议栈需要精准的32.768kHz */ gpio_init(); /* 配置天线开关、调试UART、LED等引脚 */ flash_init(); /* 初始化Flash控制器协议栈参数区和用户数据区分离 */ /* BLUE协议栈初始化内部会完成LL层状态机和定时器的注册 */ blue_stack_init(); /* 注册GAP回调连接建立、断开、广播状态变化都会回到这里 */ gap_event_callback_register(app_gap_callback); /* 注册GATT服务先添加默认的GAP服务和GATT服务再添加应用服务 */ gatt_services_init(); /* 启动广播参数来自adv_config结构体 */ gap_adv_start(adv_config); /* 进入主循环协议栈事件通过中断和标志位驱动 */ while (1) { uint32_t evt blue_sched_poll(); if (evt SCHED_EVT_GAP) { app_gap_callback(); /* 处理连接、断开、广播超时等事件 */ } if (evt SCHED_EVT_GATT) { gatt_event_dispatch(); /* 处理属性读写、通知、指示事件 */ } power_save_poll(); /* 进入低功耗前检查是否还有待处理事件 */ } }这条链路里有两个关键点。第一system_clock_init()必须在blue_stack_init()之前完成而且32.768kHz辅助时钟必须起振因为BLE的射频定时器依赖它。有些开发板把辅助时钟引脚接错了或者没焊晶振代码跑到协议栈初始化时直接卡死在时钟等待循环里表现就是程序不进主循环。第二gap_event_callback_register注册的回调是整个应用的事件入口连接断开、加密完成、配对请求都会通过它上报。调试初期建议在这个回调里把所有事件都打印出来排查问题就靠它了。3. 在XE10上跑通最小工程编译、烧录与第一次广播3.1 拿到源码后要先做的三件事确认芯片头文件、对齐时钟、检查链接脚本在改任何代码之前先把环境对齐。BLUE源码XE10的工程通常自带编译器支持和链接脚本但芯片型号、Flash起始地址、SRAM分配这些硬参数必须和你的实际板子一致。第一件确认芯片头文件。打开工程根目录下的Makefile或CMakeLists.txt找到芯片型号定义比如CHIP_TYPEXE10之类的宏。如果默认型号和你的板子不符编译出来的协议栈寄存器地址可能是错的烧进去大概率直接跑飞。确认方式是看port/目录下的芯片抽象层文件里面是否引用了对应型号的头文件。第二件对齐时钟配置。进入port/clock.c确认主时钟频率和外接晶振频率。XE10平台的典型配置是SYSTEM_CLOCK_HZ为64MHz或48MHz。如果这里写错了UART波特率会偏差BLE射频的定时精度也会受影响手机扫描时会发现你的广播包间隔抖动特别大连接稳定性差。第三件检查链接脚本里的内存分配。协议栈通常需要一块对齐的SRAM区域存放连接上下文、加密密钥和链路层状态。链接脚本里会预留类似BLE_STACK_HEAP_SIZE的区域不要随意减小。我会先把ld文件中Flash起始地址和大小、RAM起始地址和大小记下来和芯片手册对上再开始改代码。3.2 最小工程配置一个只播不发的最低可运行代码在XE10上跑通广播不需要完整透传工程也不需要移植厂商示例里那一大堆业务代码。把工程裁剪到只保留协议栈、广播配置和必要的GPIO初始化这是验证源码可用性和硬件环境的最快路径。/* 最小广播工程只实现启动广播和状态打印 */ #include blue.h #include port.h static uint8_t adv_data[] { 0x02, 0x01, 0x05, /* 广播标志LE通用可连接广播 */ 0x05, 0x09, B, L, U, E, /* 完整本地名字BLUE */ }; /* GAP事件回调只打印不做业务处理 */ static void app_gap_handler(gap_evt_t evt, void *param) { switch (evt) { case GAP_EVT_ADV_STARTED: log_info(adv started); break; case GAP_EVT_CONNECTED: log_info(connected, handle%04x, ((conn_evt_t *)param)-handle); break; case GAP_EVT_DISCONNECTED: log_info(disconnected, reason%02x, ((disc_evt_t *)param)-reason); break; default: break; } } int main(void) { system_clock_init(); gpio_init(); uart_init(115200); blue_stack_init(); gap_event_callback_register(app_gap_handler); /* 填充广播包和扫描响应包此时不会真正发送 */ gap_adv_set_data(adv_data, sizeof(adv_data), NULL, 0); /* 使用默认参数启动广播 */ adv_param_t adv { .adv_int_min_ms 100, .adv_int_max_ms 150, .adv_type ADV_TYPE_IND, }; gap_adv_start(adv); while (1) { blue_sched_poll(); } }这段代码的关键逻辑是先初始化基础设施再启动协议栈然后注册回调、设置广播数据、启动广播。gap_adv_set_data只负责把广播内容拷贝进协议栈缓冲区真正的发射动作由gap_adv_start触发。如果把顺序倒过来先启动广播再设置数据可能出现两种结果要么广播包内容为空手机能看到设备但名字显示不出来要么广播没有启动成功。adv_type选择ADV_TYPE_IND是最稳妥的因为它是可连接非定向广播既能被手机扫描到也能发起连接。如果你只想测试扫描不考虑连接可以用ADV_TYPE_NONCONN_IND功耗更低且手机更容易扫描。这个最小工程跑通了再往里面加服务和业务逻辑出问题时也更容易定位是协议栈的问题还是自己代码的问题。3.3 编译烧录与日志验证用什么命令、看什么输出XE10平台常见的编译方式是GNU Arm嵌入式工具链。进入工程目录执行编译成功之后烧录固件然后用串口看日志。# 交叉编译Debug版本带优化等级和调试信息 make CHIPXE10 DEBUG1 -j4 # 编译产物通常在 build/ 目录下烧录前确认 .hex 或 .bin 文件存在 ls -l build/*.hex build/*.bin # 用板载调试器烧录以pyocd为例烧录后自动复位运行 pyocd flash -t xE10 build/bluetooth_xe10.hex pyocd reset -t xE10烧录之后打开串口工具波特率设为115200观察输出。正常的启动日志应当包含协议栈版本号、MAC地址、广播启动成功标志。如果看到类似adv start fail或错误码不是0的日志按上一节配置表的字段逐一排查。日志里还要重点看MAC地址是否为全零全零地址虽然能广播但部分手机系统会直接忽略这类设备。串口日志是黑匣子里唯一的窗口调参数的时候别省这一步。我会把GAP事件、GATT读写事件、发生错误时的错误码都以十六进制完整打印出来每一条日志都带上时间戳。这样后面检查广播失败、连接秒断、OTA翻车时能对着日志找出第一次触发问题的位置。3.4 把广播间隔和发射功率调到实测值默认配置跑通之后下一步就是把广播间隔和发射功率从能跑调到能用。这里说的实测值是指用手机实测并观察到的结果而不是手册里写的标称值。广播间隔直接影响设备被发现的速度和广播功耗。间隔越短手机扫描到你的速度越快但功耗越高。我用一个折中方案需要快速发现的场景设100毫秒稳定工作场景设200到300毫秒。注意广播间隔要配合另一个参数广播持续时长。如果你的产品只在特定时间允许被发现可以用gap_adv_start之后的超时机制到达设定时间后自动停止广播这比长期广播省电得多。发射功率的设置在XE10上有几档可选典型值是TX_POWER_0DBM、TX_POWER_4DBM、TX_POWER_NEG_4DBM。功率越大穿墙能力越强但功耗也越高。调试时我会固定在0dBm起步用手机在不同距离和墙体遮挡下测试扫描成功率。别一上来就开最大功率否则功耗和射频杂散可能超标。设置发射功率通常在blue_stack_init之后调用rf_set_tx_power也可以在广播的配置结构体里直接指定具体看BLUE源码XE10对外暴露的接口风格。4. BLUE源码落地避坑广播失败、连接秒断与功耗异常的6个排查4.1 现象广播发不出去用手机搜不到设备现象是程序跑起来了串口打印了广播启动成功但手机扫描列表里始终没有这个设备。这是蓝牙类项目里最常见的玄学问题一半以上不是射频问题而是初始化顺序的问题。原因是广播启动前协议栈依赖的基础时钟或射频前端控制引脚没有就绪。我遇到过两种典型情况一种是32.768kHz辅助时钟没起振协议栈用内部RC振荡器凑合频率偏了导致射频发射频率落在BLE信道之外另一种是射频开关引脚被复用成普通GPIO而且默认输出了低电平把天线通路切断了。解决方法是先确认辅助时钟标志位强制等待时钟稳定后再启动协议栈。然后把射频开关相关引脚的GPIO复用功能改回外设功能并确认引脚初始电平。如果还是搜不到用频谱仪或另一个蓝牙设备查看是否真的在发射如果连频谱都看不到信号问题就还在射频前端能看到信号但手机搜不到才去查广播类型和MAC地址配置。4.2 现象能搜到但连接就断重连也要靠运气现象是手机能搜到设备一点连接就显示连接失败或者连接成功后两三秒内自动断开。串口日志里能看到设备侧收到连接请求然后很快出现disconnect reason0x08之类的错误码。原因是连接参数协商失败。BLE连接建立后从机会向主机发起连接参数更新请求。如果从机在广播或扫描响应里声明了连接参数而手机端默认的连接参数和它冲突手机可能直接拒绝更新甚至主动断开。另一个常见原因是监控超时和连接间隔之间的关系不符合BLE规范要求导致链路层认为连接无效。解决方法是把连接参数的supervision_timeout_ms设置足够大并按规范保持它大于(interval_max_ms 单位换算) * (slave_latency 1) * 2。我一般把超时固定在4000到6000毫秒slave_latency保持0或1不去挑战这个公式。如果手机端强制要求更快或更慢的连接间隔从机应当响应所以在连接事件回调里要保留对L2CAP_CONN_PARAM_UPDATE_REQ的处理。4.3 现象待机电流比手册值高一个数量级现象是设备进入睡眠模式后用万用表或功耗分析仪测到待机电流是几十微安甚至几百微安而不是手册宣称的几微安。这个坑几乎每个做过低功耗产品的人都会踩一遍。原因是GPIO悬空或引脚配置不当导致漏电其次是低功耗模式没有真正进入或者是外设没关干净。BLUE源码XE10通常会在进入睡眠前把所有GPIO配置成确定电平但如果你在自己的初始化代码里加了上拉或下拉又没有在睡眠前恢复漏电路径就存在了。解决方法是逐项排查先把所有GPIO都设成高阻输入测一个基准电流然后逐个引脚恢复为功能状态看哪个引脚引入漏电最后检查power_save_poll()是否真的执行到了有些版本的协议栈在调试模式下会禁止睡眠需要把调试宏关掉才能测真实功耗。我用一个简单的二分法把外设初始化代码注释掉一半看电流变化定位到具体外设再精调。4.4 现象配对弹窗不出来或配对后通信失败现象是手机连上设备后不弹配对框或者配对完成后读写特征值返回错误码设备端收不到正确的读写请求。原因是安全相关的属性权限配置和SM层初始化不一致。BLUE源码XE10的GATT服务在注册特征时会指定该属性的访问权限例如READ_ENCRYPTED | WRITE_AUTHENTICATED。如果属性的权限要求加密或认证而设备侧SM没有启动配对流程手机端的读写就会失败。反过来如果你希望所有操作都无需配对特征权限就不能带加密标志否则Android和iOS都会强制发起配对。解决方法是先确认需求需要配对保护的业务在初始化时调用配对管理接口并在GATT属性定义中开启相应权限不需要保护的保持属性权限为开放。调试时用日志确认配对流程各阶段事件是否到达再对照表排查是权限配置的问题还是密钥交换流程的问题。4.5 现象OTA升级到一半失败设备变砖现象是OTA升级进度条走到30%左右手机端提示失败设备重启后进入异常状态甚至无法再被连接。这是BLE开发里代价最高的一次翻车。原因是Flash操作和蓝牙协议栈的事件处理冲突。BLE连接事件期间射频收发是高频且时间敏感的如果在连接事件处理过程中执行了大块的Flash擦写操作擦写耗时会让协议栈错过接收窗口导致链路层重传超时连接直接断开。而OTA过程又恰好是持续的大块Flash写入所以冲突概率极高。解决方法是把Flash写入放到协议栈空闲时隙执行或者使用协议栈专门提供的原子操作接口在写Flash前挂起蓝牙调度写完后恢复。另外要在升级程序里加看门狗喂狗逻辑防止擦写过程中看门狗复位。我通常把OTA升级分成两个阶段先把升级包完整接收并放在临时分区校验整包CRC无误后再一次性写入应用区尽量避免边收边写带来的半包风险。4.6 现象GATT读写返回错误码回调没触发现象是手机端读写一个自定义特征值设备串口没有任何打印或者返回了0x02未找到错误。这个现象在自定义服务时非常常见。原因是GATT服务注册后句柄分配出现偏移或者特征的属性权限配置不允许当前连接状态下的访问。BLUE源码XE10的GATT服务通常用一个静态句柄表来管理服务、特征、描述符如果你添加了多个服务或者在已有服务中间插入了新特征句柄表顺序和注册顺序不一致读写请求就会落到错误的服务上。解决方法是注册完成后将句柄表完整打印出来和手机端实际读到的服务列表逐项对照。另外确认特征的回调函数是否被正确注册有些版本的协议栈要求每个特征单独绑定回调而不是只在服务层面注册一个分发函数。我习惯先跑一个最简的只读特征确认读写链路通再扩展多特征和写操作这样定位问题快得多。5. 进阶把BLUE源码改成自己的透传服务与OTA通道5.1 自定义GATT服务从模板到可用的最小透传跑通广播和连接之后最常做的就是透传服务。BLUE源码XE10通常会带一个参考的UART服务在里面加一个写特征用于收数据再加一个通知特征用于发数据。/* 自定义透传服务包含一个可写特征和一个通知特征 */ static uint16_t s_handle_attr; static uint16_t s_handle_write; static uint16_t s_handle_notify; static void on_write_attr(uint16_t handle, uint8_t *data, uint16_t len) { /* 透传收到数据原样转发给业务逻辑 */ log_info(recv(%d): %s, len, data); } gatt_service_t service { .uuid 0xFFE0, /* 128位UUID的自定义16位别名实际工程用128位UUID */ .characteristics { { .uuid 0xFFE1, .properties GATT_PROP_WRITE, .permission GATT_PERM_WRITE, .write_cb on_write_attr, }, { .uuid 0xFFE2, .properties GATT_PROP_NOTIFY, .permission GATT_PERM_READ, }, }, }; void user_service_init(void) { gatt_service_register(service); }注册完服务后要主动给通知特征分配一个CCCD客户端特征配置描述符否则手机上没法开启通知功能。有些SDK会自动添加CCCD有些需要你手动添加一个只读描述符并设置GATT_PERM_READ和GATT_PERM_WRITE权限。这个细节能省下很多调试时间。5.2 验证方法用手机App确认三个指标改完代码不能只看手机能连上就收工。我会用手机上的通用BLE调试工具做三个确认这三个指标基本决定了这个源码移植是否可用。第一是广播间隔实测值。用调试工具扫描设备看广播包的接收间隔和配置的100毫秒或150毫秒对比误差在20%以内可接受。如果偏差过大先查时钟配置。第二是连接参数协商后的结果。连接建立后在调试工具的链接信息里查看实际连接间隔。手机可能会提一个它偏好的间隔设备侧要确保自己的回退逻辑不冲突。如果实际连接间隔和期望值差太多检查从机是否正确处理了连接参数更新请求。第三是通知吞吐量。通过透传服务持续发送数据记录手机端每秒接收的字节数。在默认MTU23字节下有效吞吐量通常只有10到15KB/s。如果换成MTU协商到247字节配合DLE数据长度扩展吞吐量能到60KB/s以上。这个指标直接决定了OTA升级和批量数据传输的用户体验。最后说一个我自己的教训以前做OTA时迷信官方示例直接拿过来用结果升级成功率只有六成。后来把升级流程改成先接收整包、写入临时分区、校验CRC、再原子性切换分区地址成功率才稳定在99%以上。BLUE源码XE10给你的是一个可靠的协议栈底座但应用层的可靠性设计比如断点续传、版本回退、升级失败后的恢复引导还是要自己做。希望这些踩坑记录能让你的蓝牙项目少走几个弯。本文还有配套的精品资源点击获取