Wi-Fi 低功耗

概述

基本概念

Wi-Fi 模组低功耗根据实现原理与功耗级别，可以分为下面几种类型：

• 普通低功耗
• 断电快连
• 深度休眠（Deep Sleep）
• 热点模式（Access Point，AP）长保活（Keep-alive）

各种模式的主要特点如下：

低功耗模式	主要特点
普通低功耗	Wi-Fi 连接保持；数据上报速度快；功耗 < 15 mA
断电快连	Wi-Fi 连接断开；模组掉电，需要时重新上电启动，一般和 MCU 配合；数据上报速度慢
深度休眠	Wi-Fi 连接断开；主动上报时，可通过 GPIO、定时器等方式唤醒，唤醒后系统重启；数据上报速度慢；功耗 uA 级别
AP 长保活	Wi-Fi 连接保持；主动上报时，可通过 GPIO 中断等方式唤醒，无需系统重启；数据上报速度较快；功耗百 uA 级别

实现原理

• Wi-Fi 设备进入低功耗，就是让 CPU 进入睡眠模式，同时 RF 进入睡眠模式；按需唤醒，从而降低功耗。
• RF 进入睡眠模式时，设备与路由器协商定时唤醒处理数据，路由器在设备睡眠时会缓存数据，设备处理完数据后进入睡眠（如需了解更多，请自行参考 DTIM 模式）。
• CPU 进入睡眠模式时，需要使用到 CPU 时，立即唤醒（如需了解更多，请自行参考 Tickless 模式）。

API 说明

TuyaOS 提供了丰富的 API 以实现不同的低功耗模式，具体使用方法请参考示例。

设置 CPU 低功耗模式

用于设置 CPU 是否支持低功耗模式，只有设置后才能在后续控制 CPU 进出低功耗模式。

/**
 * @brief set cpu lowpower mode
 *
 * @param[in] lp_enable
 *
 * @return none
 */
VOID_T tal_cpu_set_lp_mode(BOOL_T lp_enable);

使能 CPU 低功耗

用于控制 CPU 进入低功耗模式（Tickless），需要先设置 CPU 低功耗模式 tal_cpu_set_lp_mode(TRUE)。

/**
 * @brief cpu lowpower enable
 *
 * @param[in] param: none
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_cpu_lp_enable(VOID_T);

关闭 CPU 低功耗

用于控制 CPU 退出低功耗模式，需要与 tal_cpu_lp_enable 配对使用，否则可能导致功耗控制紊乱。

/**
 * @brief cpu lowpower disable
 *
 * @param[in] param: none
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_cpu_lp_disable(VOID_T);

使能 Wi-Fi 低功耗

用于控制 Wi-Fi 进入低功耗模式（默认 DTIM-1），默认会同步设置 CPU 低功耗。

/**
 * @brief enable wifi lowpower (together with cpu).
 *
 * @param[in] none
 * @return  OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_wifi_lp_enable(VOID_T);

关闭 Wi-Fi 低功耗

用于控制 Wi-Fi 退出低功耗模式。

• 默认会同步退出 CPU 低功耗。
• 需要与 tal_wifi_lp_enable 配对使用，否则可能导致功耗控制紊乱。

/**
 * @brief disable wifi lowpower (together with cpu).
 *
 * @param[in] none
 * @return  OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_wifi_lp_disable(VOID_T);

仅使能 Wi-Fi 低功耗

用于仅控制 Wi-Fi 进入低功耗模式（默认 DTIM-1）。

/**
 * @brief enable wifi lowpower only
 *
 * @param[in]       none
 * @return  OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_wifi_lp_enable_v2(VOID_T);

仅关闭 Wi-Fi 低功耗

用于仅控制 Wi-Fi 退出低功耗模式，需要与 tal_wifi_lp_enable_v2 配对使用，否则可能导致功耗控制紊乱。

/**
 * @brief disable wifi lowpower only
 *
 * @param[in]       none
 * @return  OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_wifi_lp_disable_v2(VOID_T);

使能 Wi-Fi 超低功耗（AP 长保活低功耗）

用于控制 Wi-Fi 进入自适应超低功耗模式（默认 DTIM-10）。该模式下 CPU 也会同步进入超低功耗模式（Tickless），最大休眠时间 5s（无中断唤醒，以及数据交互唤醒）。

/**
 * @brief Enable ultra lowpower.
 *
 * @param[in] none
 *
 * @return  OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_wifi_ulp_init(VOID);

/**
 * @brief register CPU or wifi power mode for feature(HTTP_CONN, OTA, MQTT_CONN, UART, U2C, SPI, PWM, KEY)
 *
 * @param[in] type    function module
 * @retval 0          success
 * @retval Other      fail
 */
int lpmgr_register(TY_LP_TYPE type);

/**
 * @brief unregister CPU or wifi power mode for feature(HTTP_CONN, OTA, MQTT_CONN, UART, U2C, SPI, PWM, KEY)
 *
 * @param[in] type    function module
 * @retval 0          success
 * @retval Other      fail
 */
int lpmgr_unregister(TY_LP_TYPE type);

设置退出低功耗的唤醒源

用于设置退出低功耗时的唤醒源。

/**
 * @brief wake up source set
 * 
 * @param[in] param: wake up source set,
 * 
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */

OPERATE_RET tkl_wakeup_source_set(CONST TUYA_WAKEUP_SOURCE_BASE_CFG_T  *param);

使用示例

普通低功耗

void test_lowpower(void)
{
    // 1. 尽可能早地调用该 API，如 tuya_app_main() 函数
    tal_cpu_set_lp_mode(TRUE);

    // 2. 在 Wi-Fi 连上路由时调用
    tal_wifi_lp_enable();

    // 3. 在 Wi-Fi 与路由器断开时调用
    tal_wifi_lp_disable();

    // 4. 其他场景，如需要接收 Wi-Fi 管理帧时，先退出 Wi-Fi 低功耗，接收完毕后再打开
}

深度睡眠（Deep Sleep）

void test_lowpower(void)
{
    // 1. 设置唤醒源（GPIO）
    TUYA_WAKEUP_SOURCE_BASE_CFG_T wakeup_cfg;
    wakeup_cfg.source = TUYA_WAKEUP_SOURCE_GPIO;
    wakeup_cfg.wakeup_para.gpio_param.gpio_num = TUYA_GPIO_NUM_28; // 根据实际产品配置
    wakeup_cfg.wakeup_para.gpio_param.level = TUYA_GPIO_WAKEUP_RISE; // 根据实际产品配置
    tkl_wakeup_source_set(&wakeup_cfg);

    // 2. 关闭非必要的外设，否则可能会影响实际功耗
    // xxx

    // 3. 进入深度睡眠
    tal_cpu_sleep_mode_set(TRUE, TUYA_CPU_DEEP_SLEEP);
}

AP 长保活

void test_lowpower(void)
{
    // 1. 尽可能早地调用该 API，如 tuya_app_main() 函数
    tuya_wifi_ulp_init();

    // 2. 在需要退出超低功耗时调用
    lpmgr_register(TY_LP_UART); // 根据实际产品配置

    // 3. 在需要进入超低功耗时调用
    lpmgr_unregister(TY_LP_UART); // 根据实际产品配置
}

注意事项

低功耗相关 API 需要配对使用，否则可能会导致功耗异常，无法达到预期的低功耗。

FAQ

如何选择 Wi-Fi 低功耗模式？

Wi-Fi 模组在工作时的常态电流在几十毫安（具体模组略有差异，峰值电流会更高一点），低功耗模式的本质是为了降低常态功耗。如果产品对功耗不敏感（如长供电设备），可以不用关注本文档相关内容。

• 对于功耗敏感型设备，请根据实际场景选择相应的低功耗模式。需要注意的是，设备功耗与响应速度一般是负相关的，即功耗越低，响应速度越慢，影响用户体验。

• 一般来说，对于电池供电类设备，选择 断电快连 或者 AP 长保活 可有效延长电池使用时间。

• 对于普通电工、照明类设备，可以选择 普通低功耗 模式（工作电流小于 15 mA）。

设置了低功耗后，功耗没有明显降低

请先检查是否按照示例正确调用了相关 API。需要特别注意，进入/退出低功耗 API 需要配对使用，否则会可能导致功耗紊乱。详细内容请参考本文档相关介绍。

• 对于功耗敏感型设备，请根据实际场景选择相应的低功耗模式。需要注意的是，设备功耗与响应速度一般是负相关的，即功耗越低，响应速度越慢，影响用户体验。

• 一般来说，对于电池供电类设备，选择 断电快连 或者 AP 长保活 可有效延长电池使用时间。

• 对于普通电工、照明类设备，可以选择 普通低功耗 模式（工作电流小于 15 mA）。