蓝牙 Bluetooth APCF实现休眠唤醒功能

零.声明

本专栏文章我们会以连载的方式持续更新，本专栏计划更新内容如下：

第一篇:蓝牙综合介绍 ，主要介绍蓝牙的一些概念，产生背景，发展轨迹，市面蓝牙介绍，以及蓝牙开发板介绍。

第二篇:Transport层介绍,主要介绍蓝牙协议栈跟蓝牙芯片之前的硬件传输协议,比如基于UART的H4,H5,BCSP，基于USB的H2等

第三篇:传统蓝牙controller介绍，主要介绍传统蓝牙芯片的介绍，包括射频层（RF），基带层（baseband），链路管理层（LMP）等

第四篇:传统蓝牙host介绍，主要介绍传统蓝牙的协议栈，比如HCI,L2CAP,SDP,RFCOMM,HFP,SPP,HID,AVDTP,AVCTP,A2DP,AVRCP,OBEX,PBAP,MAP等等一系列的协议吧。

第五篇：低功耗蓝牙controller介绍，主要介绍低功耗蓝牙芯片，包括物理层（PHY），链路层（LL）

第六篇：低功耗蓝牙host介绍，低功耗蓝牙协议栈的介绍，包括HCI,L2CAP,ATT,GATT,SM等

第七篇：蓝牙芯片介绍，主要介绍一些蓝牙芯片的初始化流程，基于HCI vendor command的扩展

第八篇：附录，主要介绍以上常用名词的介绍以及一些特殊流程的介绍等。

另外，开发板如下所示，对于想学习蓝牙协议栈的最好人手一套。以便更好的学习蓝牙协议栈，相信我，学完这一套视频你将拥有修改任何协议栈的能力（比如Linux下的bluez，Android下的bluedroid）。

-------------------------------------------------------------------------------------------------------------------------

蓝牙视频教程(跟韦东山老师合作)：https://item.taobao.com/item.htm?spm=a1z10.5-c-s.w4002-22329603914.10.77201fc98qgCWh&id=679276693032

蓝牙交流扣扣群：970324688

Github代码：GitHub - sj15712795029/bluetooth_stack: 这是一个开源的双模蓝牙协议栈(bluetooth.stack)(btstack),可以运行在STM32,Linux.，包含HCI,L2CAP,SDP,RFCOMM,HFP,SPP,A2DP,AVRCP,AVDTP,AVCTP,OBEX,PBAP等协议，后续会继续维护，以达到商用的目的

入手开发板：https://shop220811498.taobao.com/category-1542116976.htm?spm=a1z10.5-c-s.w4010-22329603913.7.39ca7dbe2EA0K3&search=y&catName=%C0%B6%D1%C0%BF%AA%B7%A2%B0%E5#bd

蓝牙学习目录：一篇文章足够你学习蓝牙技术，提供史上最全的蓝牙技术（传统蓝牙/低功耗蓝牙）文章总结，文档下载总结（2020/12/11更新）_Wireless_Link的博客-CSDN博客_蓝牙eir

--------------------------------------------------------------------------------------------------------------------------

 

一.概念

ACPF(Advertising Packet Content Filter)是广播内容过滤功能，主要使能后运行controller中，所以广泛应用于广播唤醒功能，但是有个局限，不过滤周期广播。

这个命令属于HCI Vendor Specific Command/Event,所以需要固件额外支持才行！

另外，如果要做广播唤醒，需要从特定的引脚输出特定的波形，所以这个需要额外的vendor specific command才行

二.封包格式

以下是APCF Command的格式

Command parameter	Size	Purpose
APCF_opcode (OGF = 0x3F) (OCG = 0x0157)	1 octet	0x00 - APCF Enable 0x01 - APCF Set Filtering parameters 0x02 - APCF Broadcaster Address 0x03 - APCF Service UUID 0x04 - APCF Service Solicitation UUID 0x05 - APCF Local Name 0x06 - APCF Manufacturer Data 0x07 - APCF Service Data 0x08 - APCF Transport Discovery Service 0x09 - APCF AD Type Filter 0x10 ~ 0xAF - Reserved for future use 0xB0 ~ 0xDF - Reserved for vendor 0xE0 ~ 0xFE - Reserved for future use 0xFF - APCF Read extended Features

A Command Complete event will be generated for this command.

Return parameter	Size	Purpose
Status	1 octet	Return status
APCF_opcode	1 octet	0x00 - APCF Enable 0x01 - APCF Set Filtering parameters 0x02 - APCF Broadcaster Address 0x03 - APCF Service UUID 0x04 - APCF Service Solicitation UUID 0x05 - APCF Local Name 0x06 - APCF Manufacturer Data 0x07 - APCF Service Data 0x08 - APCF Transport Discovery Service 0x09 - APCF AD Type Filter 0x10 ~ 0xAF - Reserved for future use 0xB0 ~ 0xDF - Reserved for vendor 0xE0 ~ 0xFE - Reserved for future use 0xFF - APCF Read extended Features

1.LE_APCF_Command: Enable_sub_cmd

Sub OCF: 0x00

Sub-command parameter	Size	Purpose
APCF_enable	1 octet	0x01 - Enable APCF feature 0x00 - Disable APCF feature

A Command Complete event will be generated for this command.

Return parameter	Size	Purpose
Status	1 octet	Command Complete status
APCF_opcode	1 octet	0x0 - APCF Enable
APCF_Enable	1 octet	Enable/disable is set via APCF_enable

2.LE_APCF_Command: set_filtering_parameters_sub_cmd

This subcommand is used to add or delete a filter specification or clear a filter list for on-chip filtering.

Sub OCF: 0x01

Sub-command parameter	Size	Purpose
APCF_Action	1 octet	0x00 - Add 0x01 - Delete 0x02 - Clear Delete will clear the specific filter along with associated feature entries in other tables. Clear will clear all the filters and associated entries in other tables.
APCF_Filter_Index	1 octet	Filter index (0, max_filter-1)
APCF_Feature_Selection	2 octets	Bit masks for the selected features: Bit 0: Set to enable Broadcast Address filter Bit 1: Set to enable Service Data Change filter Bit 2: Set to enable Service UUID check Bit 3: Set to enable Service Solicitation UUID check Bit 4: Set to enable Local Name check Bit 5: Set to enable Manufacturer Data Check Bit 6: Set to enable Service Data Check Bit 7: Set to enable Transport Discovery Service Check Bit 8: Set to enable AD Type Check
APCF_List_Logic_Type	2 octets	Logic operation for each feature selection (per-bit position) specified in APCF_Feature_Selection. Valid only when a feature is enabled. Bit position value: 0: OR 1: AND If "AND" logic is selected, an ADV packet will pass the filter only if it contains ALL of the entries in the list. If "OR" logic is selected, an ADV packet will pass the filter if it contains any of the entries in the list.
APCF_Filter_Logic_Type	1 octet	0x00: OR 0x01: AND Note: The logic type is N/A for the first three fields of APCF_Feature_Selection, which is always "AND" logic. They are only applicable for (Bit 3 - ­Bit 6) four fields of APCF_Feature_Selection.
rssi_high_thresh	1 octet	[in dBm] The advertiser is considered seen only if the signal is higher than the RSSI high threshold. Otherwise, the firmware must behave as if it never saw it.
delivery_mode	1 octet	0x00 - immediate 0x01 - on_found 0x02 - batched
onfound_timeout	2 octets	Valid only if delivery_mode is on_found. [in milliseconds] Time for firmware to linger and collect additional advertisements before reporting.
onfound_timeout_cnt	1 octet	Valid only if delivery_mode is on_found. [count] If an advertisement in onFound lingers in firmware for the onfound_timeout duration, it will collect a few advertisements and the count is checked. If the count exceeds onfound_timeout_cnt, it's reported OnFound immediately thereafter.
rssi_low_thresh	1 octet	Valid only if delivery_mode is on_found. [in dBm] The advertiser packet is considered as not seen if the RSSI of the received packet is not above the RSSI low threshold.
onlost_timeout	2 octets	Valid only if delivery_mode is on_found. [in milliseconds] If an advertisement, after being found, is not seen contiguously for the lost_timeout period, it will immediately be reported lost.
num_of_tracking_entries	2 octets	Valid only if delivery_mode is on_found. [count] Total number of advertisers to track per filter.

RSSI values must use 2's complement to represent negative values.

Host shall be able to configure multiple filters with APCF_Application_Address_type set to 0x02 (for all broadcaster addresses) to manage various filter combinations.

Filtering, batching and reporting are inter-related concepts. Every advertisement and related scan response will have to go through all the filters, one after the other. Thus, resulting actions (delivery_mode) are closely tied to filtering. The delivery modes are the following: report_immediately, batch, and onFound. The OnLost value is related to OnFound in the sense that it will come after OnFound when lost.

This processing flow depicts the conceptual model:

When an advertisement (or scan response) frame is received, it is applied to all the filters in serial order. It's possible that an advertisement can cause immediate reporting based on one filter and batching of the same due to a different filter action.

RSSI level thresholds (high and low) give the ability to control when the frame is visible for filter processing, even when a valid packet is received by the controller. In case of delivery mode being set to immediate or batched, the RSSI of a frame is considered for further controller processing. Different apps need different reporting and batching behavior. This allows multiple apps to have direct reporting and/or batching of results in firmware, concurrently. An example is a case when a batch scan is active from one app and later a regular LE scan is issued by another app. Before a batch scan is issued, the framework/app sets appropriate filters. Later, when the second app issues a regular scan, previous batching continues. However, due to the regular scan, it is akin to conceptually adding a null filter (along with all the existing filters) along with the LE scan command. The LE scan command parameters take precedence when active. When the regular LE scan is disabled, the controller will revert back to a previous batch scan, if it existed.

The OnFound delivery mode is based on configured filters. A combination that triggers a filter's action to succeed is considered the entity to track for onLost. The corresponding event is the LE Advt tracking subevent.

The OnFound/OnLost transition for a filter (if enabled) will look like the following:

A Command Complete event will be generated for this command.

Return parameter	Size	Purpose
Status	1 octet	Command Complete status
APCF_opcode	1 octet	0x02 - APCF Set Filtering Parameters
APCF_Action	1 octet	Echo back command's APCF_Action
APCF_AvailableSpaces	1 octet	Number of available entries in the filters table

3.LE_APCF_Command: broadcast_address_sub_cmd

This subcommand is used to add or delete an advertiser address or to clear the advertiser address list for on-chip filtering.

Sub OCF: 0x02

Sub-command parameter	Size	Purpose
APCF_Action	1 octet	0x00 - Add 0x01 - Delete 0x02 - Clear Delete will delete the specified broadcaster address in the specified filter. Clear will clear all the broadcaster addresses in the specified filter.
APCF_Filter_Index	1 octet	Filter index (0, max_filter-1)
APCF_Broadcaster_Address	6 octet	6-byte device address to add to or delete from the broadcaster address list
APCF_Application_Address_type	1 octet	0x00: Public 0x01: Random 0x02: NA (addresses type not applicable)

A Command Complete event will be generated for this command.

Return parameter	Size	Purpose
Status	1 octet	Command Complete status
APCF_opcode	1 octet	0x02 - APCF Broadcaster Address
APCF_Action	1 octet	Echo back command's APCF_Action
APCF_AvailableSpaces	1 octet	Number of free entries still available in the Broadcast Address table

4. LE_APCF_Command: service_uuid_sub_cmd

This subcommand is used to add or delete a service UUID or to clear a service UUID list for on-chip filtering.

Sub OCF: 0x03

Sub-command parameter	Size	Purpose
APCF_Action	1 octet	0x00 - Add 0x01 - Delete 0x02 - Clear Delete will delete the specified service UUID address in the specified filter. Clear will clear all the service UUIDs in the specified filter.
APCF_Filter_Index	1 octet	Filter index (0, max_filter-1)
APCF_UUID	2,4,16 octet	The Service UUID (16-bit, 32-bit, or 128-bit) for adding to, or deleting from, the list.
APCF_UUID_MASK	2,4,16 octet	The Service UUID Mask (16-bit, 32-bit, or 128-bit) to add to the list. It should have the same length as APCF_UUID.

A Command Complete event will be generated for this command.

Return parameter	Size	Purpose
Status	1 octet	Command Complete status
APCF_opcode	1 octet	0x03 - APCF Service UUID
APCF_Action	1 octet	Echo back command's APCF_Action
APCF_AvailableSpaces	1 octet	Number of free entries still available in the Service UUID table

5. LE_APCF_Command: solicitation_uuid_sub_cmd

This subcommand is used to add or delete a solicitation UUID or to clear a solicitation UUID list for on-chip filtering.

Sub OCF: 0x04

Sub-command parameter	Size	Purpose
APCF_Action	1 octet	0x00 - Add 0x01 - Delete 0x02 - Clear Delete will delete the solicitation UUID address in the specified filter. Clear will clear all the solicitation UUIDs in the specified filter.
APCF_Filter_Index	1 octet	Filter index (0, max_filter-1)
APCF_UUID	2,4,16 octet	The Solicitation UUID (16-bit, 32-bit, or 128-bit) to add to or delete from the list.
APCF_UUID_MASK	2,4,16 octet	The Solicitation UUID Mask (16-bit, 32-bit, or 128-bit) to add to the list. It should have the same length as the APCF_UUID.

A Command Complete event will be generated for this command.

Return parameter	Size	Purpose
Status	1 octet	Command Complete status
APCF_opcode	1 octet	0x04 - APCF Solicitation UUID
APCF_Action	1 octet	Echo back command's APCF_Action
APCF_AvailableSpaces	1 octet	Number of free entries still available in the Solicitation UUID table

6. LE_APCF_Command: local_name_sub_cmd

This sub-command is used to add or delete a local name string or to clear the local name string list for on-chip filtering.

Sub OCF: 0x05

Sub-command parameter	Size	Purpose
APCF_Action	1 octet	0x00 - Add 0x01 - Delete 0x02 - Clear Delete will delete the specified local name string in the specified filter. Clear will clear all the local name strings in the specified filter.
APCF_Filter_Index	1 octet	Filter index (0, max_filter-1)
APCF_LocName_Mandata_or_SerData	Variable size	A character string for local name. Notes:   Currently the max number of characters in a local name string is 29 Not applicable when action is "Clear" (0x2)

A Command Complete event will be generated for this command.

Return parameter	Size	Purpose
Status	1 octet	Command Complete status
APCF_opcode	1 octet	0x05 - APCF Local Name
APCF_Action	1 octet	Echo back command's APCF_Action
APCF_AvailableSpaces	1 octet	Number of free entries still available in the Local name table

7. LE_APCF_Command: manf_data_sub_cmd

This subcommand is used to add or delete a manufacturer data string or to clear the manufacturer data string list for on-chip filtering.

Sub OCF: 0x06

Sub-command parameter	Size	Purpose
APCF_Action	1 octet	0x00 - Add 0x01 - Delete 0x02 - Clear Delete will delete the specified manufacturer data string in the specified filter. Clear will clear all the manufacturer data strings in the specified filter.
APCF_Filter_Index	1 octet	Filter Index (0, max_filter-1)
APCF_LocName_Mandata_or_SerData	Variable size	A character string for manufacturer data. Notes:   Currently the max number of characters in a local name string is 29 Not applicable when action is "Clear" (0x2)
APCF_ManData_Mask	Variable size	The manufacture data mask to add to the list. It should have the same length as APCF_LocName_or_ManData_or_SerData.

A Command Complete event will be generated for this command.

Return parameter	Size	Purpose
Status	1 octet	Command Complete status
APCF_opcode	1 octet	0x06 - APCF Manufacturer Data
APCF_Action	1 octet	Echo back command's APCF_Action
APCF_AvailableSpaces	1 octet	Number of free entries still available in the Manufacturer Data table

8. LE_APCF_Command: service_data_sub_cmd

This subcommand is used to add or delete a service data string or to clear the service data string list for on-chip filtering.

Sub OCF: 0x07

Sub-command parameter	Size	Purpose
APCF_Action	1 octet	0x00 - Add 0x01 - Delete 0x02 - Clear Delete will delete the specified service data string in the specified filter. Clear will clear all the service data strings in the specified filter.
APCF_Filter_Index	1 octet	Filter Index (0, max_filter-1)
APCF_LocName_Mandata_or_SerData	Variable size	A character string for service data. Notes:   Currently the max number of characters in a local name string is 29 Not applicable when action is "Clear" (0x2)
APCF_LocName_Mandata_or_SerData_Mask	Variable size	The service data mask to add to the list. It should have the same length as APCF_LocName_or_ManData_or_SerData.

A Command Complete event will be generated for this command.

Return parameter	Size	Purpose
Status	1 octet	Command Complete status
APCF_opcode	1 octet	0x07 - APCF Service Data
APCF_Action	1 octet	Echo back command's APCF_Action
APCF_AvailableSpaces	1 octet	Number of free entries still available for Service Data table

9.LE_APCF_Command: ad_type_sub_cmd

This subcommand is used to add or delete an AD type or to clear an AD type list for on-chip filtering. Use read_extended_features_sub_cmd to check if this command is supported or not.

Sub OCF: 0x09

Sub-command parameter	Size	Purpose
APCF_Action	1 octet	0x00 - Add 0x01 - Delete 0x02 - Clear Delete will delete the specified AD type in the specified filter. Clear will clear all the AD types in the specified filter.
APCF_Filter_Index	1 octet	Filter Index (0, max_filter-1)
APCF_AD_TYPE	1 octet	The AD Type for adding to, or deleting from, the list. Ignore when APCF_Action is 0x02 (Clear)
APCF_AD_DATA_Length	Variable size	0x00 - means do not filter data content Ignore when APCF_Action is 0x02 (Clear)
APCF_AD_DATA	Variable size	Ignore when APCF_Action is 0x02 (Clear)
APCF_AD_DATA_MASK	Variable size	Ignore when APCF_Action is 0x02 (Clear) It should have the same length as APCF_AD_DATA.

A Command Complete event will be generated for this command.

Return parameter	Size	Purpose
Status	1 octet	Command Complete status
APCF_opcode	1 octet	0x09 - APCF AD Type
APCF_Action	1 octet	Echo back command's APCF_Action
APCF_AvailableSpaces	1 octet	Number of free entries still available in the AD Type table

10. LE_APCF_Command: read_extended_features_sub_cmd

This subcommand is used to read extended APCF features.

Sub OCF: 0xFF

Sub-command parameter	Size	Purpose
	Not applicable	Empty command parameter.

A Command Complete event will be generated for this command.

Return parameter	Size	Purpose
Status	1 octet	Command Complete status
APCF_opcode	1 octet	0xFF - APCF_Read_Extended_Features
APCF_extended_features	2 octet	Bit masks for extended features supported: Bit 0: Support Transport Discovery Service filter Bit 1: Support AD Type filter Bit 2 ~15: Reserved for future use Value of bit 0 = Not supported 1 = Supported