【0x0037】HCI_Write_Link_Supervision

一、命令概述

二、命令格式及参数说明

2.1. HCI_Write_Link_Supervision_Timeout 命令格式

2.2. Handle

2.3. Link_Supervision_Timeout

三、生成事件及参数

3.1. HCI_Command_Complete 事件

3.2. Status

3.3. Handle

四、命令执行流程

4.1. 命令准备阶段

4.2. 命令传输阶段

4.3. 命令处理阶段（控制器端）

4.4. 返回结果阶段

4.5. 事件通知阶段（如果未屏蔽）

4.6. 示例代码

五、应用场景

六、注意事项

6.1. 角色限制

6.2. 参数设置

6.3. 事件处理

6.4. 兼容性考虑

6.5. 连接稳定性与节能的平衡

6.6. 安全性考虑

HCI_Write_Link_Supervision_Timeout 命令是用于设置蓝牙基本速率/增强数据速率（BR/EDR）控制器中的链路监督超时（Link Supervision Timeout, LSTO）值的命令。链路监督超时是指在一定时间内如果没有接收到来自对端设备的数据包，则认为链路已经丢失，设备将断开连接。这个命令对于管理蓝牙连接的稳定性和资源非常关键。

一、命令概述

HCI_Write_Link_Supervision_Timeout 命令是蓝牙HCI（Host Controller Interface）协议中用于设置特定ACL（Asynchronous Connection-Less）连接的链路监督超时的命令。它允许主机（Host）为特定的蓝牙连接设置一个链路监督超时值。在蓝牙设备的管理和连接维护中起着重要作用。

当主机（Host）向控制器（Controller）发送此命令时，它指定了一个连接句柄和期望的链路监督超时值。
如果控制器作为外设（Peripheral）角色，并且主机尝试修改这个值，控制器将返回错误代码“命令不允许”（Command Disallowed，错误码0x0C）。
使用的连接句柄应该是指向目标设备的ACL连接。执行此命令后，该设备的其他同步连接句柄（Synchronous Handles）的链路监督超时值也将被设置为相同的值。

二、命令格式及参数说明

2.1. `HCI_Write_Link_Supervision_Timeout` 命令格式

HCI_Write_Link_Supervision_Timeout 命令的格式遵循蓝牙核心规范中定义的HCI命令结构。

该命令的详细格式:

Opcode（操作码）:
- OGF（Operation Group Field）: 0x03表示该命令属于链路控制命令组。
- OCF（Operation Code Field）: 0x0037表示该命令是设置链路监督超时命令。
- 完整的Opcode: 0x03 0x0037 或组合为 0x0C37
Parameter Total Length（参数总长度）:
- 长度为1个字节，表示后续参数的总长度。
- 对于HCI_Write_Link_Supervision_Timeout命令，参数总长度固定为4个字节（2个字节用于连接句柄，2个字节用于链路监督超时值）。
Parameters（参数）:
- Connection Handle（连接句柄）：
  - 长度：2个字节。
  - 用于唯一标识一个ACL连接。
- Link Supervision Timeout（链路监督超时值）：
  - 长度：2个字节。
  - 表示链路监督超时的值，单位为0.625毫秒的倍数。例如，如果设置为0x0200，则超时时间为0x0200 * 0.625毫秒 = 512毫秒。

2.2. Handle

Handle 是指一个用于标识特定BR/EDR控制器连接的连接句柄（Connection_Handle）。在 HCI_Write_Link_Supervision_Timeout 命令中用于指定哪个连接的链路监督超时值将被写入。

范围：从 0x0000 到 0x0EFF。这个范围限制了可以标识的连接数量，因为连接句柄只有 12 位有效。

2.3. Link_Supervision_Timeout

Link_Supervision_Timeout用于定义蓝牙BR/EDR连接在没有收到来自对等设备的任何数据包时可以保持活动状态的最长时间。这个参数在 HCI_Write_Link_Supervision_Timeout 命令中用于设置特定连接的链路监督超时值。

0x0000：表示没有设置链路监督超时，但在实际应用中，通常不是有效的设置，因为蓝牙核心规范为控制器定义了一个强制范围。
N = 0xXXXX：N 是一个十六进制值，表示以BR/EDR基带时隙为单位的数量。链路监督超时值是通过将 N 乘以 0.625 毫秒来计算的，其中 0.625 毫秒是一个基带时隙的持续时间。
- 时间范围：从 0.625 毫秒到 40.96 秒。
- 默认值：0x7D00，表示 20 秒的超时时间。
- 控制器的强制范围：0x0190 到 0xFFFF；意味着超时值可以从 1 个基带时隙（即 0.625 毫秒）到 65535 个基带时隙（即约 40.96 秒）不等。另外，0x0000 可以表示无限超时（尽管在实际应用中，可能需要特定的实现或配置）。

三、生成事件及参数

3.1. `HCI_Command_Complete` 事件

当 HCI_Write_Link_Supervision_Timeout 命令完成时，将生成一个 HCI_Command_Complete 事件。这个事件是HCI层用来通知主机命令已经执行完毕的标准机制。

事件内容：
- 命令操作码（Opcode）：标识触发此事件的HCI命令。
- 返回参数：包括的Status和Handle（如果适用）。Status字段将指示命令是否成功执行（0x00表示成功，其他值表示失败及相应的错误代码）。如果命令成功，Handle字段将包含被更新链路监督超时值的连接句柄。
事件处理：主机接收到HCI_Command_Complete事件后，将检查Status字段以确定命令是否成功执行。如果命令失败，主机可能会采取适当的错误处理措施，如重试命令、记录错误日志或通知用户。

3.2. Status

Status 参数用于表明 HCI_Write_Link_Supervision_Timeout 命令的执行情况。

当 Status 的值为 0x00 时，代表 HCI_Write_Link_Supervision_Timeout 命令已成功执行。表示系统已成功更新了指定连接的链路监督超时值。
如果 Status 的值介于 0x01 到 0xFF 之间，意味着命令执行失败。此时，具体的错误代码将提供有关失败原因的详细信息。蓝牙Controller错误代码全面概览_蓝牙错误代码-CSDN博客

3.3. Handle

Handle 参数用于指定哪个连接的链路监督超时值被 HCI_Write_Link_Supervision_Timeout 命令所更新。

与HCI_Write_Link_Supervision_Timeout 命令参数中的 Handle 格式相同，用于确认操作对应的连接。如果命令执行成功，返回的 Handle 应该与发送命令时使用的 Handle 一致；如果出现错误，返回的 Handle 可能用于帮助定位问题连接。

四、命令执行流程

4.1. 命令准备阶段

确定目标连接句柄：主机确定要设置链路监督超时（LSTO）值的蓝牙连接的唯一标识符（Connection_Handle），该句柄必须在0x0000到0x0EFF的范围内。
设置超时值：主机设置所需的LSTO值，该值以0.625毫秒为单位，范围是0x0001到0xFFFF。
构建命令包：主机按照HCI命令格式，使用操作码0x0037，并附加Handle和Link_Supervision_Timeout参数，构建完整的命令数据包。

4.2. 命令传输阶段

发送命令：主机通过HCI接口（如UART、USB等）将构建好的命令数据包发送给蓝牙控制器。

4.3. 命令处理阶段（控制器端）

接收并解析命令：控制器接收命令包，并检查其格式是否正确。
权限和范围检查：
- 控制器验证Handle对应的连接角色，确保不是从设备发出的命令（从设备不允许设置LSTO）。
- 控制器检查Handle和LSTO参数是否在有效范围内。
更新链路监督超时值：如果所有检查都通过，控制器将更新指定连接的LSTO值，包括可能的同步连接。

4.4. 返回结果阶段

构建返回包：控制器根据命令执行结果构建返回包，包括Status和Handle参数。
发送返回包：控制器通过HCI接口将返回包发送回主机。
接收并处理返回结果：
- 主机接收返回包，检查Status参数以确定命令是否成功。
- 根据Status值，主机执行相应的后续操作，如记录日志、更新状态或报告错误。

4.5. 事件通知阶段（如果未屏蔽）

生成并发送事件：控制器生成HCI_Command_Complete事件（除非被屏蔽），并通过HCI接口发送给主机。
接收并处理事件：主机接收事件，进一步确认命令已完成，并根据需要进行其他处理。

4.6. 示例代码

以下是一个简化的示例代码框架，用于说明如何在C语言中构建和发送该命令，以及如何处理响应。请注意，这只是一个示例，并不包含实际的硬件接口代码或错误处理细节。

#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>// 假设有一个HCI接口库提供以下函数
// hci_send_command(uint8_t *packet, uint16_t length);
// hci_receive_event(uint8_t *event, uint16_t *length);// 示例：HCI命令包结构
typedef struct {uint16_t opcode;       // 操作码uint8_t  param_len;    // 参数长度uint16_t handle;       // 连接句柄uint16_t lsto;         // 链路监督超时值
} hci_write_lsto_cmd_t;// 示例：HCI事件包结构（简化）
typedef struct {uint8_t  evt_code;     // 事件代码uint8_t  plen;         // 参数长度uint8_t  status;       // 状态码uint16_t handle;       // 连接句柄（可能包含在返回包中）// ... 其他可能的参数
} hci_command_complete_evt_t;// 函数：构建并发送HCI_Write_Link_Supervision_Timeout命令
void send_write_lsto_command(uint16_t handle, uint16_t lsto) {hci_write_lsto_cmd_t cmd;cmd.opcode = 0x0037; // HCI_Write_Link_Supervision_Timeout 操作码cmd.param_len = 4;   // 参数长度（2字节handle + 2字节lsto）cmd.handle = handle;cmd.lsto = lsto;uint8_t packet[HCI_COMMAND_PACKET_MAX_SIZE]; // 假设定义了最大包大小memset(packet, 0, sizeof(packet));// 将命令结构复制到包中（这里需要适当的字节序转换，如果必要）memcpy(packet, &cmd, sizeof(cmd));// 发送命令hci_send_command(packet, sizeof(cmd));
}// 函数：处理HCI_Command_Complete事件
void handle_command_complete_event(uint8_t *event, uint16_t length) {if (length < sizeof(hci_command_complete_evt_t)) {// 事件包太短，无法处理return;}hci_command_complete_evt_t *evt = (hci_command_complete_evt_t *)event;if (evt->evt_code == HCI_EVENT_COMMAND_COMPLETE) {if (evt->status == 0x00) {// 命令成功执行printf("HCI_Write_Link_Supervision_Timeout command succeeded for handle 0x%04X\n", evt->handle);} else {// 命令执行失败printf("HCI_Write_Link_Supervision_Timeout command failed with status 0x%02X for handle 0x%04X\n", evt->status, evt->handle);}} else {// 不是命令完成事件printf("Unexpected event code 0x%02X\n", evt->evt_code);}
}// 主函数：示例使用
int main() {uint16_t handle = 0x0001; // 示例连接句柄uint16_t lsto = 0x0200;   // 示例链路监督超时值（512 * 0.625ms = 320ms）// 发送HCI_Write_Link_Supervision_Timeout命令send_write_lsto_command(handle, lsto);// 等待并处理HCI事件（这里需要实现一个循环来不断检查新事件）// 示例中省略了这部分，因为它通常涉及到异步I/O和事件循环机制// ...// 假设在某个时刻，我们收到了一个HCI_Command_Complete事件// uint8_t event_data[] = { ... }; // 假设这是接收到的事件数据// uint16_t event_length = ...;    // 假设这是接收到的事件长度// handle_command_complete_event(event_data, event_length);return 0;
}

在将命令结构复制到包中时，可能需要进行字节序转换（大端或小端）。这取决于HCI接口和蓝牙控制器的要求。

五、应用场景

HCI_Write_Link_Supervision_Timeout命令允许用户根据具体的应用场景和设备需求，灵活地设置链路监督超时（LSTO）的值。这一特性使得该命令在多个方面都有广泛的应用。

蓝牙连接稳定性维护：在不同环境下，通过调整LSTO的值，可以优化蓝牙连接的稳定性。例如，在干扰较大的环境中缩短超时时间，以便更快地检测到连接问题；在对连接稳定性要求极高的场景中延长超时时间，以减少因短暂数据传输间隔而误判连接中断的情况。
节能管理：对于电池供电的蓝牙设备，合理设置LSTO值可以在一定程度上实现节能。当设备在一段时间内没有数据交互且超时时间到达后，蓝牙控制器可以将设备置于低功耗模式或断开连接，从而减少能耗。
多设备连接协调：在多设备连接到一个主设备的场景中，通过为不同设备设置不同的LSTO值，可以优化资源分配，提高连接效率和用户体验。例如，为正在使用的设备设置较长的超时时间，而为不常使用的设备设置较短的超时时间。
蓝牙协议栈开发与测试：在蓝牙协议栈的开发和测试阶段，使用HCI_Write_Link_Supervision_Timeout命令可以模拟各种连接场景和故障情况，从而发现协议栈实现中的潜在问题，并优化其性能和稳定性。

HCI_Write_Link_Supervision_Timeout命令在蓝牙通信中具有广泛的应用场景和重要的实用价值。通过合理设置LSTO的值，可以优化连接稳定性、实现节能管理、协调多设备连接以及支持蓝牙协议栈的开发与测试。在实际应用中，开发人员和工程师应根据具体需求和场景来合理设置LSTO的值，以实现最佳的蓝牙通信性能和用户体验。