这部分是HCI_LE_Add_Device_To_Filter_Accept_List command也就是LE 添加设备到过滤接受列表命令它属于 BLE Controller 相关的 HCI Command章节号是7.8.16. LE Add Device To Filter Accept List command一、表格内容翻译原文表格Command: HCI_LE_Add_Device_To_Filter_Accept_List OCF: 0x0011 Command Parameters: Address_Type, Address Return Parameters: Status翻译命令名称 HCI_LE_Add_Device_To_Filter_Accept_List OCF 0x0011 命令参数 Address_Type Address 返回参数 Status也就是说这条 HCI Command 需要 Host 传给 Controller 两个参数Address_Type地址类型 Address设备地址Controller 执行完成后会返回Status执行结果二、Description 翻译原文This command is used to add a single device to the Filter Accept List stored in the Controller.翻译该命令用于向 Controller 中保存的 Filter Accept List 添加一个设备。说明Filter Accept List 是保存在 Controller 里的过滤接受列表。 Host 通过 HCI Command 把某个设备地址添加进去。 后续 Controller 在广播、扫描、发起连接等过程中可以基于这个列表做过滤。原文This command shall not be used when:翻译在以下情况下不应使用该命令原文第一条any advertising filter policy uses the Filter Accept List and advertising is enabled, or翻译如果当前存在某个 advertising filter policy 正在使用 Filter Accept List并且广播已经启用则不应使用该命令。说明如果 Controller 正在广播并且广播过滤策略正在使用 Filter Accept List 这时候不应该再去修改 Filter Accept List。因为 Filter Accept List 正在被广播过程使用运行中修改名单可能导致行为不确定所以规范要求不要这样做。原文第二条the scanning filter policy uses the Filter Accept List and scanning is enabled, or翻译如果 scanning filter policy 正在使用 Filter Accept List并且扫描已经启用则不应使用该命令。说明如果 Controller 正在扫描并且扫描过滤策略正在使用 Filter Accept List 这时候也不应该修改 Filter Accept List。例如扫描时只接受 Filter Accept List 中设备的广播包这时候列表已经参与扫描过滤逻辑不能边扫描边修改。原文第三条the initiator filter policy uses the Filter Accept List and an HCI_LE_Create_Connection or HCI_LE_Extended_Create_Connection command is pending.翻译如果 initiator filter policy 正在使用 Filter Accept List并且当前有一个 HCI_LE_Create_Connection 或 HCI_LE_Extended_Create_Connection 命令处于 pending 状态则不应使用该命令。说明initiator 可以理解为正在发起连接的一方。 如果当前 Controller 正在根据 Filter Accept List 发起连接 并且 LE Create Connection 或 LE Extended Create Connection 命令还没有完成 这时候也不应该修改 Filter Accept List。这里的 pending 表示Host 已经发送了连接命令 Controller 正在尝试建立连接 但连接结果还没有通过 event 返回。原文If the device is already in the Filter Accept List, the Controller should not add the device to the Filter Accept List again and should return success.翻译如果该设备已经在 Filter Accept List 中Controller 不应重复添加该设备并且应返回成功。说明重复添加同一个设备时不应该报错。 Controller 应该认为这个操作已经满足目标因此返回 success。也就是说这个命令具备一定的“幂等性”第一次添加添加成功 第二次添加同一个设备不重复添加但仍然返回成功。原文Address shall be ignored when Address_Type is set to 0xFF.翻译当 Address_Type 设置为 0xFF 时Address 字段应被忽略。说明Address_Type 0xFF 表示发送 anonymous advertisements 的设备。 这种情况下没有具体设备地址可匹配所以 Address 参数不再有实际意义。三、Errors 翻译原文See Section 4.5.2 for a list of error types and descriptions.翻译错误类型和说明请参考 4.5.2 节。错误表格Type: MC Condition: The Controller cannot add a device to the Filter Accept List because there is no space available. Error code: Memory Capacity Exceeded (0x07)翻译错误类型 MC 错误条件 Controller 无法向 Filter Accept List 添加设备因为列表中没有可用空间。 错误码 Memory Capacity Exceeded也就是内存容量超出错误码为 0x07。说明Filter Accept List 不是无限大的。 Controller 能保存多少个设备取决于具体蓝牙芯片能力。如果列表满了再添加设备就可能返回0x07 Memory Capacity Exceeded四、Command parameters 翻译1. Address_Type原文Address_Type Size: 1 octet翻译Address_Type 大小1 字节参数取值表0x00Public Device Address 0x01Random Device Address 0xFFDevices sending anonymous advertisements All other valuesReserved for future use.翻译0x00Public Device Address公共设备地址 0x01Random Device Address随机设备地址 0xFF发送匿名广播的设备 其他值保留给未来使用重点是如果要添加的设备使用 Public Address就填 0x00。 如果要添加的设备使用 Random Address就填 0x01。 如果目标是 anonymous advertising 设备就填 0xFF。结合前面的 HCI 日志Address Type: Random Address: xx:xx:xx:00:xx:6C对应的原始参数就是Address_Type 0x01 Address xx:xx:xx:00:xx:6C2. Address原文Address Size: 6 octets翻译Address 大小6 字节参数说明Public Device Address or Random Device Address of the device to be added to the Filter Accept List.翻译要添加到 Filter Accept List 中的设备的 Public Device Address 或 Random Device Address。说明Address 字段就是具体设备地址占 6 字节也就是通常看到的 XX:XX:XX:XX:XX:XX 形式。不过在 HCI 原始数据中地址字段通常按小端顺序出现。例如显示地址是xx:xx:xx:00:xx:6CHCI 原始字节里通常是6C xx 00 xx xx xx所以解析 HCI 日志时要注意显示出来的地址顺序和原始字节中的地址顺序是反过来的。五、Return parameters 翻译Status原文Status Size: 1 octet翻译Status 大小1 字节返回值说明0x00 HCI_LE_Add_Device_To_Filter_Accept_List command succeeded. 0x01 to 0xFF HCI_LE_Add_Device_To_Filter_Accept_List command failed.翻译0x00 HCI_LE_Add_Device_To_Filter_Accept_List 命令执行成功。 0x01 到 0xFF HCI_LE_Add_Device_To_Filter_Accept_List 命令执行失败。说明Status 0x00 表示添加成功。 Status 非 0x00 表示失败具体失败原因要根据 Controller Error Codes 查看。常见失败原因之一就是0x07 Memory Capacity Exceeded也就是 Filter Accept List 已经满了。六、Event generated 翻译原文When the HCI_LE_Add_Device_To_Filter_Accept_List command has completed, an HCI_Command_Complete event shall be generated.翻译当 HCI_LE_Add_Device_To_Filter_Accept_List 命令完成后应生成一个 HCI_Command_Complete event。说明这条命令执行完成后不是返回 LE Meta Event 而是返回普通的 HCI_Command_Complete event。所以在 HCI 日志中通常会看到类似流程Host - Controller: HCI_LE_Add_Device_To_Filter_Accept_List Controller - Host: HCI_Command_CompleteCommand Complete event 里面会带上Command_Opcode 0x2011 Status 0x00 或错误码七、必要 Tip 说明Tip 1这条命令不是“发起连接”而是“连接前配置过滤名单”这条命令的核心作用是把某个设备加入 Controller 的 Filter Accept List。它不会直接发起连接也不会直接在空口发送连接请求包。真正发起 LE 连接的命令通常是HCI_LE_Create_Connection或者HCI_LE_Extended_Create_Connection所以它和连接流程的关系是先配置名单 再发起连接 连接命令可以选择是否使用这个名单。Tip 2Filter Accept List 是 Controller 里的名单不是 Host App 自己维护的数组Filter Accept List 存在于Controller不是存在于App 层 Host 普通内存 GATT 层 GAP 文本描述层Host 只能通过 HCI Command 去操作它例如LE Clear Filter Accept List LE Add Device To Filter Accept List LE Remove Device From Filter Accept List LE Read Filter Accept List Size所以这类命令本质上都是Host 配置 Controller 行为Tip 3添加设备之前通常会先 Clear实际日志中经常会看到类似顺序LE Clear Filter Accept List LE Add Device To Filter Accept List LE Create Connection原因是先清空旧名单 再添加当前目标设备 然后基于这个名单发起连接。这样可以避免 Controller 里还残留之前的设备地址导致过滤行为不符合预期。Tip 4Address_Type 一定要和目标设备地址类型匹配这个命令不仅要填地址值还要填地址类型Address_Type Address不能只看地址字符串。例如同样是xx:xx:xx:00:xx:6C还要知道它是Public Device Address还是Random Device Address如果地址类型填错Controller 后续过滤时可能匹配不到目标设备。Tip 5Address_Type 0x01 只表示 Random Address不等于一定是 RPA0x01 Random Device AddressRandom Device Address 下面还可以继续分Static Random Address Resolvable Private Address Non-resolvable Private Address所以看到Address_Type 0x01只能说明它是 Random Device Address不能直接断定它一定是 RPA。如果要进一步判断 Random Address 的子类型需要结合地址最高两位规则继续分析。Tip 6命令不能在 Filter Accept List 正在被使用时随便修改规范明确说了三种不应使用的情况广播正在使用 Filter Accept List 扫描正在使用 Filter Accept List 发起连接正在使用 Filter Accept List并且连接命令 pending核心原因是Filter Accept List 正在被 Controller 的实时链路行为使用。因此正确做法通常是先停止相关行为 再修改 Filter Accept List 再重新启动广播、扫描或连接。例如扫描场景LE Set Scan Enable: Disable LE Clear Filter Accept List LE Add Device To Filter Accept List LE Set Scan Enable: Enable连接场景LE Clear Filter Accept List LE Add Device To Filter Accept List LE Create ConnectionTip 7重复添加同一个设备规范要求返回成功如果设备已经在 Filter Accept List 中再次添加时Controller 不应该重复添加 但应该返回 success。所以如果日志里多次看到添加同一个设备不一定代表异常。这说明规范希望该命令具备类似幂等行为目标是让该设备出现在名单中 只要最终它已经在名单里就可以返回成功。Tip 8Filter Accept List 容量有限Filter Accept List 能保存多少个设备不是规范固定死的而是取决于 Controller 实现。可以通过下面命令读取容量LE Read Filter Accept List Size如果添加失败并返回0x07 Memory Capacity Exceeded说明Controller 的 Filter Accept List 已经没有空间了。Tip 9它和 Advertising_Filter_Policy、Scanning_Filter_Policy、Initiator_Filter_Policy 有直接关系Filter Accept List 本身只是一个名单。真正决定是否使用这个名单的是各种 filter policy例如Advertising_Filter_Policy Scanning_Filter_Policy Initiator_Filter_Policy所以要把它理解成两部分第一步通过 LE Add Device To Filter Accept List 配置名单。 第二步在广播、扫描、发起连接参数中通过 filter policy 决定是否使用这个名单。如果 filter policy 没有选择使用 Filter Accept List那么即使名单里有设备也不一定会参与过滤。Tip 10结合前面的日志这条命令可以这样理解前面日志中的原始数据是11 20 07 01 6C 04 00 30 0D DD解析如下11 20Opcode小端序实际是0x2011对应命令LE Add Device To Filter Accept List07参数总长度7 字节01Address_Type0x01 Random Device Address6C xx 00 xx xx xxAddress反过来显示为xx:xx:xx:00:xx:6C所以整条命令的含义是把 Random Address 为 xx:xx:xx:00:xx:6C 的设备 添加到 Controller 的 Filter Accept List 中。八、这条命令在 BLE Legacy 连接流程中的位置它通常属于连接前准备步骤1. 清空 Filter Accept List 2. 添加目标设备到 Filter Accept List 3. 配置本地地址、扫描参数、连接参数等 4. 发送 LE Create Connection 5. Controller 在空口扫描目标设备广播 6. 扫描到可连接广播后发送 CONNECT_IND 7. 连接建立后返回 LE Connection Complete event所以它不是连接建立本身而是为了让后续连接过程只针对特定设备提前配置 Controller 的过滤名单。真实 HCI 日志截图如下也就是说如果计划要 connect 设备 A那么需要先将设备 A 的 Device Address 先设置好。