分片传输#
使用技术:SLE、SSAP 属性读写、Notification、应用层分片与顺序重组、累加校验和
前置阅读:必须了解 Hello SLE 的扫描与连接流程,建议先完成 Hello Notify 的 Notification 实验。
本案例使用两块 WS53 演示固定长度的大数据传输:Client 通过 SSAP 写请求触发传输;Server 将 1024 字节测试数据拆成 6 个 Notification;Client 按分片序号顺序追加负载,并在最后一片到达后检查总长度和校验和。
学习目标#
理解 SSAP MTU、分片头、单片负载和原始数据长度之间的关系。
掌握 Magic、传输 ID、片序号、总片数、负载长度和校验和的作用。
理解 WS53 当前实现是“严格顺序追加”,不是“携带偏移的乱序重组”。
掌握 Client 收包前的头部、长度、序号和缓冲区边界检查。
区分“触发请求已接受”“Server 已发送完成”和“Client 重组校验通过”三个验收层次。
了解 Notification 不提供应用层逐片确认,以及当前案例在丢片、乱序和并发传输方面的限制。
基本概念#
MTU 与有效负载#
SSAP MTU 限制一次属性数据可承载的最大规模。本案例双方请求 MTU 520,但没有把 520 字节全部作为业务负载,而是把每片业务负载固定为 180 字节,并在前面增加分片头。
在当前 WS53 工具链下,offsetof(sle_fragmentation_packet_t, payload) 为 16,因此:
分片 |
业务负载 |
实际属性数据长度 |
|---|---|---|
第 1~5 片 |
180 字节 |
16 + 180 = 196 字节 |
第 6 片 |
124 字节 |
16 + 124 = 140 字节 |
最大属性数据长度 196 字节,小于请求的 MTU 520。MTU 是链路允许值,180 字节是本案例自行选择的应用层分片负载,两者不能混为同一个参数。
分片与重组#
总片数使用向上取整公式计算:
total = (data_size + payload_size - 1) / payload_size
Server 通过 offset = index × 180 从源缓冲区取出当前片,但这个 offset 只存在于 Server 局部计算中,并没有写进分片头。Client 要求收到的 index 必须等于 g_next_fragment,校验通过后把负载追加到 g_reassembly_buffer[g_reassembly_length]。
因此,当前实现只能重组从 0 开始、严格连续到达的分片,不具备按偏移接收乱序分片的能力。
分片元数据与接收状态#
公共协议结构定义如下:
typedef struct {
uint16_t magic;
uint16_t transfer_id;
uint16_t index;
uint16_t total;
uint16_t payload_len;
uint16_t reserved;
uint32_t checksum;
uint8_t payload[SLE_FRAGMENTATION_PAYLOAD_SIZE];
} sle_fragmentation_packet_t;
当前 16 字节头的字段为:
字段 |
长度 |
WS53 当前值或作用 |
|---|---|---|
|
2 |
固定为 |
|
2 |
固定为 1,识别传输会话 |
|
2 |
从 0 开始的片序号 |
|
2 |
固定为 6 |
|
2 |
当前片有效负载长度,最大 180 |
|
2 |
保留字段;当前发送为 0,Client 不检查 |
|
4 |
完整 1024 字节源数据的累加和 |
需要特别注意:WS53 当前协议头没有 offset 字段。源码 README 中“分片头携带偏移”“按偏移重组”的描述与实际 sle_fragmentation_protocol.h、Client 实现不一致;本文以实际 C 源码为准,按 reserved 字段和严格顺序追加说明。
Client 使用两个全局状态量:
g_reassembly_length:已经追加的有效字节数。g_next_fragment:下一片必须匹配的序号。
收到 index == 0 的分片时,Client 无条件把两者清零,开始或重新开始一次传输。
涉及 API#
API 按实际调用阶段排列。详细参数和返回值请查阅对应 API Reference。
阶段 |
前置状态 |
核心 API |
调用方 |
作用 |
|---|---|---|---|---|
Server 初始化 |
案例任务启动 |
|
Server |
注册读、写和 Notify 属性 |
扫描与连接 |
SLE 已使能 |
|
Client |
查找 |
MTU 与发现 |
配对成功 |
|
Client |
请求 MTU 520 并取得属性 handle |
传输前读取 |
服务发现完成 |
|
Client / Server |
确认属性读流程成功;读取数据本身不参与分片协议 |
触发传输 |
读确认成功 |
|
Client / Server |
写入单字节 |
创建发送任务 |
触发值合法 |
|
Server |
创建 |
发送分片 |
发送任务运行 |
|
Server |
发送单个 Notification 分片 |
片间节流 |
单片发送成功 |
|
Server |
相邻分片之间等待 20 ms |
案例说明#
功能规格#
规格项 |
WS53 源码值 |
|---|---|
Server 广播名称 |
|
服务 UUID |
|
属性 UUID |
|
触发命令 |
单字节 |
原始数据长度 |
1024 字节 |
单片最大负载 |
180 字节 |
当前头长度 |
16 字节 |
最大/最小属性数据长度 |
196 / 140 字节 |
总片数 |
6 |
MTU 请求值 |
520 字节,版本 1 |
Magic |
|
Transfer ID |
1 |
片间等待 |
20 ms |
发送任务 |
优先级 27,栈大小 |
公共分片结构体#
Client 和 Server 共用 src/application/samples/bt/sle/sle_fragmentation/sle_fragmentation_protocol.h。总片数由公共常量计算:
#define SLE_FRAGMENTATION_DATA_SIZE 1024
#define SLE_FRAGMENTATION_PAYLOAD_SIZE 180
#define SLE_FRAGMENTATION_TOTAL_FRAGMENTS \
((SLE_FRAGMENTATION_DATA_SIZE + SLE_FRAGMENTATION_PAYLOAD_SIZE - 1) / \
SLE_FRAGMENTATION_PAYLOAD_SIZE)
Server 不发送整个 sle_fragmentation_packet_t 的固定大小,而是根据当前有效负载计算实际长度:
uint16_t packet_len =
(uint16_t)(offsetof(sle_fragmentation_packet_t, payload) +
packet.payload_len);
这样最后一片只发送 124 字节有效负载,不会发送 payload[180] 中剩余的未使用空间。
案例直接传输 C 结构体头,并在 Client 侧把接收缓冲区转换为结构体指针。跨编译器或跨架构使用时,应显式定义字节序、头长度、字段偏移和对齐方式,不能依赖当前编译器的结构体布局。
端到端交互流程#
sequenceDiagram
participant S as WS53 Server
participant C as WS53 Client
S->>S: 注册服务并广播 fragment_server
C->>S: 扫描、连接、配对、MTU 交换、属性发现
C->>S: Read Request
S-->>C: 8 字节属性初值
C->>C: Read Confirm 成功
C->>S: Write Request:0x01
S-->>C: Write Response:成功
S->>S: 创建 SLEFragmentTx 任务
loop index = 0...5
S->>C: Notification:16 字节头 + 当前负载
S->>S: 等待 20 ms
end
C->>C: 严格检查序号并顺序追加
C->>C: 第 6 片后检查 1024 字节和 checksum
实际流程中,Client 不是在服务发现完成后直接写入 0x01:它先读取属性;只有 read_cfm_cb 收到成功状态才调用 sle_fragmentation_client_send_write_req()。Server 返回的 8 字节属性初值不参与后续分片重组,这个 Read Request 主要充当传输前的属性可读性和流程就绪检查。
三个验收层次#
层次 |
关键日志 |
能证明什么 |
|---|---|---|
触发请求接受 |
|
Server 接受了单字节 |
Server 发送完成 |
|
6 次本地 Notification 发送调用均返回成功 |
Client 重组通过 |
|
Client 按序收到 6 片,总长度为 1024,最终累加和匹配 |
触发请求响应在创建发送任务之前返回,而且 sle_fragmentation_start_transfer() 不向写回调报告任务创建失败。因此 transfer request accepted 不能证明发送任务已经成功运行。最终功能验收必须以 Client 的 test passed 为准。
案例操作指导#
准备开发板#
准备两块 WS53 开发板和两个调试串口,分别作为 Server 和 Client。本案例不需要外接硬件。
配置、构建并烧录 Server#
在 SDK 根目录执行:
fbb config set CONFIG_SAMPLE_SUPPORT_SLE_FRAGMENTATION_SERVER_SAMPLE=y --target ws53_liteos_app
fbb build ws53_liteos_app --clean
fbb flash ws53_liteos_app --port <SERVER_COM> --json-summary
对应的 Kconfig 选择链为:
CONFIG_ENABLE_BT_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_SLE_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_SLE_FRAGMENTATION_SERVER_SAMPLE=y
配置、构建并烧录 Client#
Server 烧录完成后,切换到 Client 角色并重新构建:
fbb config set CONFIG_SAMPLE_SUPPORT_SLE_FRAGMENTATION_CLIENT_SAMPLE=y --target ws53_liteos_app
fbb build ws53_liteos_app --clean
fbb flash ws53_liteos_app --port <CLIENT_COM> --json-summary
对应的 Kconfig 选择链为:
CONFIG_ENABLE_BT_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_SLE_SAMPLE=y
CONFIG_SAMPLE_SUPPORT_SLE_FRAGMENTATION_CLIENT_SAMPLE=y
固件包位于:
output/ws53/fwpkg/pack_all_core/ws53_liteos_app/ws53_liteos_app_all_in_one.fwpkg
运行与验收#
打开两块板的调试串口。
先启动 Server,确认进入等待连接状态。
再启动 Client。两端会自动完成建链和传输,无需人工输入。
先检查 Server 的触发与发送日志,再以 Client 的重组日志做最终判定。
Server 关键日志应包含:
[sle fragmentation server] transfer start: bytes=1024, fragments=6, checksum=130560
[sle fragmentation server] fragment sent: 1/6, payload=180
[sle fragmentation server] fragment sent: 6/6, payload=124
[sle fragmentation server] transfer complete
Client 关键日志应包含:
[sle fragmentation client] transfer request accepted, handle=0x..
[sle fragmentation client] fragment received: 1/6, total_bytes=180
[sle fragmentation client] fragment received: 6/6, total_bytes=1024
[sle fragmentation client] reassembly complete: bytes=1024, checksum=130560
[sle fragmentation client] test passed
若 Server 已输出 transfer complete,但 Client 没有 test passed,仍应判定接收端验证失败。
常见问题#
现象 |
检查项 |
|---|---|
Client 一直扫描 |
确认 Server 已烧录 Server 角色,并广播 |
服务发现后没有触发传输 |
查看 Read Confirm 是否成功;Client 只有读确认成功才发送 |
|
检查写入长度和值是否为单字节 |
|
检查 Magic、Transfer ID、总片数、负载长度和实际接收长度 |
|
检查是否丢片、乱序或出现并发传输;当前实现不会自动恢复 |
|
对比实际总长度、实际累加和与最后一片携带的期望值 |
关键配置#
角色与能力#
顶层 SLE 案例 choice 定义两个互斥角色:
CONFIG_SAMPLE_SUPPORT_SLE_FRAGMENTATION_SERVER_SAMPLE
CONFIG_SAMPLE_SUPPORT_SLE_FRAGMENTATION_CLIENT_SAMPLE
选择 Server 后自动使能 SUPPORT_SLE_PERIPHERAL;选择 Client 后自动使能 SUPPORT_SLE_CENTRAL。
协议与任务参数#
常量 |
值 |
源码位置 |
|---|---|---|
|
|
|
|
1 |
|
|
1024 |
|
|
180 |
|
|
6 |
|
|
520 |
|
|
20 ms |
|
|
27 |
|
|
|
|
修改数据长度或负载长度时,应同时检查:总片数公式、发送任务栈占用、Client 重组缓冲区、最大属性数据长度和实际 MTU。修改协议头时必须同步修改两端,不能只调整 Server 的 packet_len。
代码详解#
1. 代码目录与调用关系#
src/application/samples/bt/sle/sle_fragmentation/
├── sle_fragmentation.c
│ ├── sle_fragmentation_entry()
│ ├── Client 重组缓冲区与 Notification 回调
│ └── Client 最终长度和 checksum 验证
├── sle_fragmentation_protocol.h
│ └── 公共分片结构和长度常量
├── sle_fragmentation_server/src/
│ ├── sle_fragmentation_server.c
│ └── sle_fragmentation_server_adv.c
└── sle_fragmentation_client/src/
└── sle_fragmentation_client.c
sle_fragmentation_entry() 根据 Kconfig 创建 SLEFragmentServer 或 SLEFragmentClient 任务,角色任务优先级为 28、栈大小为 0x1000。Server 收到触发后另建优先级 27 的 SLEFragmentTx 任务执行实际发送。
2. Server 只接受明确的触发值#
Server 写回调只接受长度为 1、首字节为 1 的请求:
bool valid_trigger =
(write_cb_para->length == 1) &&
(write_cb_para->value[0] == 1);
如果请求需要响应,合法触发返回成功,其他内容返回 ERRCODE_SSAP_INCORRECT_DATA_VALUE。响应发送完成后,合法请求才调用 sle_fragmentation_start_transfer()。
由于启动函数返回 void,任务创建失败无法反馈到已经发送的写响应;源码也没有使用忙标志拒绝第二个合法触发。
3. Server 计算边界并逐片发送#
发送任务生成递增测试数据并计算完整校验和:
for (uint16_t index = 0; index < sizeof(source); index++) {
source[index] = (uint8_t)(index & 0xFF);
}
每轮根据片序号计算源数据偏移和剩余长度:
uint16_t offset = index * SLE_FRAGMENTATION_PAYLOAD_SIZE;
uint16_t remaining = (uint16_t)(sizeof(source) - offset);
packet.payload_len =
(remaining > SLE_FRAGMENTATION_PAYLOAD_SIZE) ?
SLE_FRAGMENTATION_PAYLOAD_SIZE : remaining;
复制和 Notification 发送任一失败都会立即结束任务,不再发送后续分片。全部 6 片的发送调用都返回成功后,Server 才输出 transfer complete。
4. Client 先校验再写入缓冲区#
Notification 回调依次执行以下检查:
检查 |
失败日志 |
|---|---|
回调状态成功,数据长度不少于当前头长度 |
|
Magic、Transfer ID 和总片数匹配 |
|
|
|
实际数据长度严格等于头长度加负载长度 |
|
|
|
追加后不超过 1024 字节缓冲区 |
|
|
|
只有全部检查通过,Client 才追加负载、增加累计长度并递增下一片序号。源码不保存乱序分片,也不在序号错误后跳过缺失位置。
5. 0 号片重置接收状态#
回调在进行序号检查之前处理:
if (packet->index == 0) {
g_reassembly_length = 0;
g_next_fragment = 0;
}
这让新一轮传输可以从 0 号片重新开始,但没有同时检查新的 Transfer ID,因为 Transfer ID 始终固定为 1。重复或并发到达的 0 号片也会清空当前进度。
6. 最后一片触发完整性校验#
每接收一片,g_next_fragment 加 1。当它等于头中的 total 时,Client 对当前重组缓冲区重新求和:
if ((g_reassembly_length == SLE_FRAGMENTATION_DATA_SIZE) &&
(checksum == packet->checksum)) {
osal_printk("[sle fragmentation client] test passed\r\n");
}
因此 test passed 的成立条件是:6 片按序通过检查、累计长度恰好 1024,并且计算结果等于最后一片头中的 checksum。它不代表协议具备重传、安全校验或多会话隔离能力。