企业官网建设流程全解析

简介：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协议栈一样，按照蓝牙标准的分层模型组织。不要一上来就按字母序读文件，先认清这几层的职责，后面查问题才有方向。

这里有个常见误解：以为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_TYPE=XE10之类的宏。如果默认型号和你的板子不符，编译出来的协议栈寄存器地址可能是错的，烧进去大概率直接跑飞。确认方式是看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 CHIP=XE10 DEBUG=1 -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 reason=0x08之类的错误码。

原因是连接参数协商失败。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%以内可接受。如果偏差过大，先查时钟配置。

第二是连接参数协商后的结果。连接建立后，在调试工具的链接信息里查看实际连接间隔。手机可能会提一个它偏好的间隔，设备侧要确保自己的回退逻辑不冲突。如果实际连接间隔和期望值差太多，检查从机是否正确处理了连接参数更新请求。

第三是通知吞吐量。通过透传服务持续发送数据，记录手机端每秒接收的字节数。在默认MTU（23字节）下，有效吞吐量通常只有10到15KB/s。如果换成MTU协商到247字节，配合DLE（数据长度扩展），吞吐量能到60KB/s以上。这个指标直接决定了OTA升级和批量数据传输的用户体验。

最后说一个我自己的教训：以前做OTA时迷信官方示例，直接拿过来用，结果升级成功率只有六成。后来把升级流程改成先接收整包、写入临时分区、校验CRC、再原子性切换分区地址，成功率才稳定在99%以上。BLUE源码XE10给你的是一个可靠的协议栈底座，但应用层的可靠性设计，比如断点续传、版本回退、升级失败后的恢复引导，还是要自己做。希望这些踩坑记录能让你的蓝牙项目少走几个弯。

本文还有配套的精品资源，点击获取