diff --git a/docs/_static/itwt_10s_current.png b/docs/_static/itwt_10s_current.png new file mode 100644 index 0000000000..bfd315c042 Binary files /dev/null and b/docs/_static/itwt_10s_current.png differ diff --git a/docs/_static/itwt_30s_current.png b/docs/_static/itwt_30s_current.png new file mode 100644 index 0000000000..7b8890149f Binary files /dev/null and b/docs/_static/itwt_30s_current.png differ diff --git a/docs/_static/itwt_setup.png b/docs/_static/itwt_setup.png new file mode 100644 index 0000000000..0aa68878e1 Binary files /dev/null and b/docs/_static/itwt_setup.png differ diff --git a/docs/_static/itwt_suspend.png b/docs/_static/itwt_suspend.png new file mode 100644 index 0000000000..c49403313e Binary files /dev/null and b/docs/_static/itwt_suspend.png differ diff --git a/docs/_static/itwt_teardown.png b/docs/_static/itwt_teardown.png new file mode 100644 index 0000000000..c3c6805e32 Binary files /dev/null and b/docs/_static/itwt_teardown.png differ diff --git a/docs/zh_CN/api-guides/low-power-mode.rst b/docs/zh_CN/api-guides/low-power-mode.rst index c18605473a..a1fd881f0f 100644 --- a/docs/zh_CN/api-guides/low-power-mode.rst +++ b/docs/zh_CN/api-guides/low-power-mode.rst @@ -743,3 +743,293 @@ Deep-sleep 有如下可配置选项: .. only:: esp32c2 平均电流约 4.9 μA + +.. only:: esp32c6 + + 目标唤醒时间 (TWT) + ---------------------------------- + + 目标唤醒时间 (Target Wake Time, TWT) 是 Wi-Fi 6 中引入的一项特性,旨在降低设备功耗和提高网络效率。 + + 在以往的 Wi-Fi 节能机制中,设备可能需要在每个 DTIM 周期醒来与 AP 交换数据,而在 TWT 机制中支持 AP 和设备协商得到特定的唤醒时间,设备会在这些时间点醒来与 AP 进行数据交换,而其余时间则处于休眠状态。TWT 协商的唤醒和休眠时间取决于设备具体的应用需求。例如,有些传感器设备需要定时上传数据,在该场景下设备可以与 AP 建立 TWT 协商,相隔多个小时交换一次数据。实际应用中可根据具体需求定制唤醒时间,在不影响设备正常工作的情况下降低功耗。 + + AP 可以与多个设备建立 TWT 协商。利用 Wi-Fi 6 的多用户特性,AP 可以对上行和下行数据传输做出合理协调,从而减少信道竞争,提高传输效率。 + + TWT 类型 + ++++++++++ + + 根据协商类型和工作模式,可以把 TWT 分为: + + - **Individual TWT (iTWT)** + + iTWT 模式下,AP 与终端设备建立的是一对一的 TWT 协商。 + + - **Broadcast TWT (bTWT)** + + 在 bTWT 模式下,AP 通过 Beacon 帧广播 TWT 信息,以组的形式来管理多个终端设备的 TWT 过程。终端设备可以根据 Beacon 中的 TWT 信息选择执行加组操作。 + + .. note:: + 在建立 TWT 协商前,需要确认 AP 是否支持并开启了 TWT 功能。{IDF_TARGET_NAME} 当前只支持 iTWT 模式。 + + TWT 工作流程 + ++++++++++++ + TWT 工作流程一般分为 TWT 协商建立、TWT 协商暂停/恢复、TWT 协商终止。TWT 协商建立后,Station 就可以按照协商的参数进入休眠状态,直到约定好的下一个 TWT 时间点到来时苏醒。 + 对已经建立的 TWT,用户可以根据需求协商暂停/恢复 TWT 或者终止 TWT。 + + - TWT 协商建立 + + - Individual TWT 协商建立 + + 在 iTWT 协商建立过程中,通常由 Station 充当请求发起方发送 TWT 请求,而后 AP 作为接收方对该请求做出回应。AP 也可以主动向 Station 发起 TWT 协商建立过程。 + 在成功建立起 iTWT 协商后,Station 可以进入休眠状态,直到约定好的下一个 TWT 时间点到来时苏醒,该时间点通过和 AP 间的协商得到。Station 醒来后和 AP 进行数据交换,这段时间被称为 TWT 服务时间 (Service Period, SP)。 + TWT SP 的持续时间被称为 TWT Wake Duration,其最小值为 256 微秒。当一次 TWT SP 结束后,Station 进入休眠状态直到下次 TWT SP 醒来进行数据传输。本次 TWT SP 的起始到下次 TWT SP 的起始的时间间隔被称为 TWT Wake Interval。下图为基本的 iTWT 示例: + + .. figure:: ../../_static/itwt_setup.png + :align: center + + Individual TWT 协商建立过程示例 + + Station 在 iTWT 协商建立时可以发送不同类型的请求,AP 会根据请求类型及参数做出对应的回复。用户需要根据 AP 回复中的类型和具体参数决定后续的操作逻辑。Station 所发送的请求类型有 ``Request``、``Suggest`` 和 ``Demand``。 + AP 的回复类型可分为 ``Accept``、``Alternate`` 和 ``Dictate``。下表描述了发送不同请求时 AP 可能的回复以及不同情况下对应的含义: + + .. list-table:: + :header-rows: 1 + :widths: 20 10 40 + + * - 请求类型 + - AP 回复 + - 含义 + * - Request, Suggest or Demand + - No response + - 在该情况下 AP 不会与 Station 建立 iTWT 协商。 + * - Suggest or Request + - Accept + - AP 同意建立 iTWT 协商,其使用的参数以回复中 TWT 参数为准。回复中的 TWT 参数有可能与请求中不一致。 + * - Demand + - Accept + - AP 同意建立 iTWT 协商,且回复中的 TWT 参数与请求中的一致。 + * - Demand or Suggest + - Alternate + - AP 使用该回复类型代表给 Station提供一组备选 TWT 参数,此时不会建立 iTWT 协商。后续 Station 可以发送新的请求,但 AP 仍有可能使用该组参数。 + * - Demand or Suggest + - Dictate + - AP 使用该回复类型代表给 Station 提供一组备选 TWT 参数,此时不会建立 iTWT 协商,同时也表明 AP 不接受除该组参数以外的其他参数。后续 Station 可以发送新的请求,但只有参数与所提供的备选参数一致才会收到 Accept 回复。 + * - Request, Suggest or Demand + - Reject + - 在该情况下 AP 不会与 station 建立 iTWT 协商。后续 Station 可以更改 TWT 参数发送新的请求。 + + 在 TWT SP 中依照数据交互时的操作可以将 TWT 进一步地细分为多种类型,下表描述了这些类型间的差异: + + .. list-table:: + :header-rows: 1 + :widths: 10 20 + + * - Types + - 含义 + * - Trigger-enabled + - AP 会在 SP 中使用 Trigger 帧来协调 Station 的数据传输。 + * - Non trigger-enabled + - 在 SP 中不需要使用 Trigger 帧。 + * - Announced + - Station 会发送 QoS Null 帧告知 AP 其唤醒状态。 + * - Unannounced + - 不需要发送 QoS Null 帧。 + + - Broadcast TWT 协商建立 + + 与 iTWT 不同的是,在 bTWT 模式下 AP 将 TWT 信息放在 Beacon 帧中进行广播宣告。Station 接收到 Beacon 后,可以向 AP 发送请求申请选择加入某个 TWT。 + 当建立起 bTWT 协商后, Station 和 AP 会在协商好的 TWT SP 中进行数据传输。 + + 与 iTWT 类似,可以把 bTWT 进一步分成 Trigger-enabled 和 Non trigger-enabled 类型,以及 Announced 和 Unannounced 类型,具体的行为差异可以参考 iTWT 中的描述。 + + - TWT 协商暂停/恢复 + + 建立起 TWT 协商后, Station 可以通过向 AP 发送 TWT Information 帧暂停或者恢复指定的 TWT 协商。由 flow_id 来标识需要暂停或者恢复的 TWT 协商,具体可以参考 TWT 参数配置。 + + .. figure:: ../../_static/itwt_suspend.png + :align: center + + Individual TWT 协商暂停/恢复过程示例 + + - TWT 协商终止 + + 建立起 TWT 协商后, Station 可以通过向 AP 发送 TWT Teardown 帧终止指定的 TWT 协商。由 flow_id 来标识需要终止的 TWT 协商,具体可以参考 TWT 参数配置。 + + .. figure:: ../../_static/itwt_teardown.png + :align: center + + Individual TWT 协商终止过程示例 + + TWT 参数配置 + ++++++++++++ + + 在使用过程中,需要配置 TWT 和低功耗模式的相关参数,其中低功耗模式相关参数决定了设备在休眠状态下的行为模式。本小节将主要阐述如何配置 TWT,有关低功耗模式下的参数配置,请参考 `如何配置 Wi-Fi 场景下低功耗模式`_。 + + - Individual TWT 参数配置 + + 在建立 Station 和 AP 间的 iTWT 时,使用 :component_file:`esp_wifi/include/esp_wifi_he_types.h` 中定义的结构体 :cpp:type:`wifi_twt_setup_config_t` 来配置 TWT 的相关参数,其定义如下: + + .. code-block:: C + + typedef struct + { + wifi_twt_setup_cmds_t setup_cmd; + uint16_t trigger :1; + uint16_t flow_type :1; + uint16_t flow_id :3; + uint16_t wake_invl_expn :5; + uint16_t wake_duration_unit :1; + uint16_t reserved :5; + uint8_t min_wake_dura; + uint16_t wake_invl_mant; + uint16_t twt_id; + uint16_t timeout_time_ms; + } wifi_twt_setup_config_t; + + :cpp:type:`wifi_twt_setup_config_t` 中各个字段的含义如下: + + .. list-table:: + :header-rows: 1 + :widths: 15 45 + :align: center + + * - 字段 + - 描述 + * - setup_cmd + - 指示了 TWT 建立时请求和回复使用的命令类型,具体类型请参阅 :cpp:type:`wifi_twt_setup_cmds_t` 。 + * - trigger + - 值为 1 时配置 TWT 类型为 Trigger-enabled,值为 0 时配置为 Non trigger-enabled。 + * - flow_type + - 值为 1 时配置 TWT 类型为 Unannounced,值为 0 时配置为 Announced。 + * - flow_id + - 当建立起一个 iTWT 协商后,AP 会为其分配 flow_id。Station 在协商建立请求中可以指定 flow_id,但在 AP 的回复中该字段可能会被改变。 + * - wake_invl_expn + - TWT Wake Interval 指数部分。 + * - wake_duration_unit + - TWT Wake Duration 计数单元。为 0 代表 256 微秒,为 1 代表以 TU (1024 微秒) 为单位。 + * - reserved + - 保留字段。 + * - min_wake_dura + - 该字段代表 Station 期望处于唤醒状态的时间,以 ``wake_duration_unit`` 作为基本单位。 + * - wake_invl_mant + - TWT Wake Interval 尾数部分。 + * - twt_id + - TWT 配置标识。在发起多个 TWT 请求时,该字段用于在 handler 中区分不同的 TWT 参数配置。 + * - timeout_time_ms + - TWT 请求超时时间,单位为毫秒。 + + 需要指出的是,Station 在协商中所期望的 TWT Wake Interval 为 wake_invl_mant * 2\ :sup:`wake_invl_expn`\,单位是微秒。 + 而所期望的 TWT Wake Duration 为 min_wake_dura * wake_duration_unit。 + + .. note:: + 注意, TWT Wake Interval 和 TWT Wake Duration 的差值需要大于 10 毫秒。 + + 配置示例如下: + + .. code-block:: C + + wifi_twt_setup_config_t setup_config = { + .setup_cmd = TWT_REQUEST, + .flow_id = 0, + .twt_id = 0, + .flow_type = 0, + .min_wake_dura = 255, + .wake_duration_unit = 0, + .wake_invl_expn = 10, + .wake_invl_mant = 512, + .trigger = 1, + .timeout_time_ms = 5000, + }; + + 以上配置指定建立 TWT 请求时使用的类型为 Trigger-enabled,Announced,期望的 TWT Wake Interval 为 524288 微秒, TWT Wake Duration 为 65280 微秒。配置好 :cpp:type:`wifi_twt_setup_config_t` 后,调用 API :cpp:func:`esp_wifi_sta_itwt_setup` 向 AP 发起 iTWT 建立请求。 + + .. note:: + {IDF_TARGET_NAME} 支持用户调用 API :cpp:func:`esp_wifi_sta_itwt_set_target_wake_time_offset` 配置相对于目标唤醒时间的偏移时间。 + + TWT 事件 + ++++++++++ + + - WIFI_EVENT_ITWT_SETUP + + 发送请求后,用户可以在 :cpp:enumerator:`WIFI_EVENT_ITWT_SETUP` 事件的对应处理程序中获取请求结果并自定义处理逻辑。事件结果保存在 :cpp:type:`wifi_event_sta_itwt_setup_t` 结构体中,其成员变量 status 指示了此次事件的状态。 + 当 status 为 :c:macro:`ITWT_SETUP_SUCCESS` 时代表请求成功收到了对应回复,为其他值代表请求失败。在得到请求成功的状态后,用户可以从该结构体中的 config 成员变量中得到 AP 回复中的具体参数,并根据具体参数决定后续的处理逻辑。 + 例如,Station 发送了类型为 Demand 的 TWT 请求,收到 AP 的回复类型为 Dictate,用户此时可以考察回复中的 TWT 参数是否可行,若可行便可以发送一个新的 TWT 请求与 AP 继续建立 TWT 协商,并且该请求中的 TWT 参数需要与 AP 回复中一致。 + + 在 Station 未主动发送请求时也有可能触发 :cpp:enumerator:`WIFI_EVENT_ITWT_SETUP` 事件,这种情况下对应的是 AP 主动向 Station 发起 iTWT 协商建立过程,此时 AP 向 Station 发送的帧中会带有 TWT 参数。同样地,用户可以在 :cpp:enumerator:`WIFI_EVENT_ITWT_SETUP` 事件的对应处理程序中获取结果并自定义处理逻辑。 + 用户需要检查 config 成员变量中 AP 发送的 TWT 参数类型,一般有两种情况: + 1. AP 发送的 TWT 参数为 Accept 类型,此时 Station 会与 AP 建立起使用该 TWT 参数的 iTWT 协商。若用户不希望建立此 iTWT 协商,可以向 AP 发送 Teardown 帧。 + 2. AP 发送的 TWT 参数为 Alternate 或 Dictate 类型,此时 Station 不会与 AP 建立起 iTWT 协商,但可以在接下来使用该参数向 AP 发起 iTWT 协商建立请求。 + + - WIFI_EVENT_ITWT_SUSPEND + + 在调用 API :cpp:func:`esp_wifi_sta_itwt_suspend` 请求暂停已经建立的 iTWT 协商时, 用户可以在 :cpp:enumerator:`WIFI_EVENT_ITWT_SUSPEND` 事件的对应处理程序中获取请求结果并自定义处理逻辑。事件结果保存在 :cpp:type:`wifi_event_sta_itwt_suspend_t` 结构体中,其成员变量 status 指示了此次事件的状态。 + 当 status 为 :c:macro:`ESP_OK` 时代表成功暂停了指定的 iTWT 协商,为其他值代表请求暂停失败。 + + .. note:: + 注意,调用 API :cpp:func:`esp_wifi_sta_itwt_suspend` 请求暂停 iTWT 时,用户需要指定对应 iTWT 的 flow_id 以及暂停时间。需要注意的是,当暂停时间大于 0 时,对应 iTWT 会在暂停指定时间后恢复,而当暂停时间为 0 时,对应的 iTWT 会暂停,直到被用户调用 API 手动恢复为止。 + + - WIFI_EVENT_ITWT_TEARDOWN + + 在调用 API :cpp:func:`esp_wifi_sta_itwt_teardown` 请求终止 iTWT 时,用户可以在 :cpp:enumerator:`WIFI_EVENT_ITWT_TEARDOWN` 事件的对应处理程序中获取请求结果并自定义处理逻辑。事件结果保存在 :cpp:type:`wifi_event_sta_itwt_teardown_t` 结构体中,其成员变量 status 指示了此次事件的状态。 + 当 status 为 :cpp:enumerator:`ITWT_TEARDOWN_SUCCESS` 时代表成功终止了指定的 iTWT 协商,为其他值代表终止 iTWT 失败。调用 API 时用户需要指定需要终止的 iTWT 的 flow_id。 + + - WIFI_EVENT_TWT_WAKEUP + + 当 Station 在休眠中醒来时,Wi-Fi 驱动程序将会上报 :cpp:enumerator:`WIFI_EVENT_TWT_WAKEUP` 事件,用户可以在该事件的对应处理程序中自定义处理逻辑。事件结果保存在 :cpp:type:`wifi_event_sta_twt_wakeup_t` 结构体中,成员变量 twt_type 指示了此次事件 TWT 的类型,成员变量 flow_id 指示了此次醒来的具体的 TWT。 + + - WIFI_EVENT_ITWT_PROBE + + 调用 API :cpp:func:`esp_wifi_sta_itwt_send_probe_req` 在 iTWT 期间发送 probe request 时,用户可以在 :cpp:enumerator:`WIFI_EVENT_ITWT_PROBE` 事件的对应处理程序中获取请求结果并自定义处理逻辑。事件结果保存在 :cpp:type:`wifi_event_sta_itwt_probe_t` 结构体中,其成员变量 status 指示了此次事件的状态。 + 当 status 为 :cpp:enumerator:`ITWT_PROBE_SUCCESS` 时代表成功发送 probe request 并且接收到 AP 回复的 probe response,为其他值代表发送或者接收 probe 失败。 + + + 有关 iTWT 使用的更多信息,可以参考示例 :example:`wifi/itwt` 。 + + TWT 功耗分析 + +++++++++++++ + + 为了展现 TWT 在节省设备功耗方面的优势,我们使用功率分析仪追踪了 {IDF_TARGET_NAME} 在不同模式下的电流情况。如下图所示,{IDF_TARGET_NAME} 首先处于 DTIM 模式,接着与 AP 建立起 iTWT 协商,TWT Wake Interval 为 10 s,在 TWT SP 结束后,{IDF_TARGET_NAME} 会进入 Light-sleep 状态直到下个 SP 到来时唤醒。 + 其中 :cpp:type:`wifi_twt_setup_config_t` 配置示例如下: + + .. code-block:: C + + wifi_twt_setup_config_t setup_config = { + .setup_cmd = TWT_REQUEST, + .flow_id = 0, + .twt_id = 0, + .flow_type = 0, + .min_wake_dura = 255, + .wake_duration_unit = 0, + .wake_invl_expn = 10, + .wake_invl_mant = 10000, + .trigger = 1, + .timeout_time_ms = 5000, + }; + + .. figure:: ../../_static/itwt_10s_current.png + :align: center + + DTIM 与 iTWT 模式下的电流图 + + 进一步,将 TWT 协商中的 TWT Wake Interval 参数更改为 30 s,下图展现了参数变化对于电流的影响。 + 其中 :cpp:type:`wifi_twt_setup_config_t` 配置示例如下: + + .. code-block:: C + + wifi_twt_setup_config_t setup_config = { + .setup_cmd = TWT_REQUEST, + .flow_id = 0, + .twt_id = 0, + .flow_type = 0, + .min_wake_dura = 255, + .wake_duration_unit = 0, + .wake_invl_expn = 10, + .wake_invl_mant = 30000, + .trigger = 1, + .timeout_time_ms = 5000, + }; + + .. figure:: ../../_static/itwt_30s_current.png + :align: center + + 更改参数后的 DTIM 与 iTWT 模式下的电流图