设备重置

概述

基本概念

设备重置是把设备恢复到配网、激活之前状态的操作。根据触发源不同，可以分为：

• 本地重置
• 远程重置

根据重置后设备所处的状态，又可细分为：

• 普通重置：指解除绑定
• 恢复出厂重置：指解除绑定清除数据

设备重置的时候，还会和设备配网模式关联起来，具体细节请参考 设备配网模式。

适用场景

设备重置主要适用场景如下：

• 让设备进入配网状态：如支持 记忆模式 的设备，通过设备重置功能进入配网状态。

• 让设备退网/解除绑定：如设备需要更换连接的路由器。

• 让设备恢复出厂/清除用户数据：如电工类产品，清除设备本地存储的电量计量数据。

  对于支持 Wi-Fi 网络备份 或 闪电配网 的设备，无需执行设备重置即可完成路由器变更。

功能描述

• 普通重置（解除绑定）：
  • 清除本地保存的配网数据
  • 清除本地保存的定时数据
  • 通知云端执行解绑操作（云端不会清除设备的历史数据，如定时数据、设备名称等，再次配网绑定后用户可查看到）
  • 通过回调函数通知用户
• 恢复出厂重置（解绑并清除数据）：
  • 全部 普通重置 的数据
  • 通过回调函数通知用户
  • 本地保存的描述设备 DP 列表 (schema) 的数据
  • 通知云端执行解绑并清除数据（云端会清除设备的历史数据，相当于是全新的设备）
  • 通过回调函数通知用户

实现方案

重置操作的伪代码：

GW_RESET_TYPE_E reset_type;
...
//根据重置类型执行重置操作，并赋值 reset_type
...

//执行回调函数
if (gw_cntl->cbs.gw_reset_cb) {
    gw_cntl->cbs.gw_reset_cb(reset_type);
}

//重启设备
tal_system_reset();

开发指导

关联组件

• svc_wifi_api

使用方法

• 本地重置时，需要应用主动调用下述 API

  • 普通重置（解除绑定）：tuya_iot_wf_gw_unactive
  • 恢复出厂重置（解绑并清除数据）：tuya_iot_wf_gw_reset

• 远程重置时，开发者无需主动调用 API，开发框架会监听云端下发的指令，执行重置操作。

• 本地重置和远程重置时，开发框架都会通过回调函数通知开发者。通知回调函数的注册可见设备初始化的 智能设备功能回调函数。

数据结构

类型定义

typedef enum {
    GW_LOCAL_RESET_FACTORY = 0,    // 本地恢复出厂重置
    GW_REMOTE_UNACTIVE,                // App 普通重置（解除绑定）
    GW_LOCAL_UNACTIVE,                   // 本地普通重置（解除绑定）
    GW_REMOTE_RESET_FACTORY,       // App 恢复出厂重置
    GW_RESET_DATA_FACTORY,            // 激活时数据重置（详见 FAQ）
} GW_RESET_TYPE_E;

回调函数

重置通知回调函数，由应用通过设备初始化接口传入。无论何种重置方式，回调函数都会被调用，以执行自定义重置行为（如清除应用数据）。

/**
 * @brief Handler to process gateway reset
 *
 * @param[in] type Reset type, see GW_RESET_TYPE_E
 */
typedef VOID (*GW_RESET_IFM_CB)(GW_RESET_TYPE_E type);

API 说明

本地普通重置（解除绑定）

该 API 会立即返回，具体重置操作将 异步执行，完成重置后将通过回调函数通知开发者。

/**
 * @brief Local unactive
 *
 * @return OPERATE_RET
 */
OPERATE_RET tuya_iot_wf_gw_unactive(VOID);

本地恢复出厂重置（解绑并清除数据）

该 API 会立即返回，具体重置操作将 异步执行，完成重置后将通过回调函数通知开发者。

/**
 * @brief Local reset factory
 *
 * @return OPERATE_RET
 */
OPERATE_RET tuya_iot_wf_gw_reset(VOID);

本地快速重置（解除绑定）

该 API 同步执行 重置操作，在重置之后设备会重新启动，并且按照新的 mthd 和 wifi_start_mode 进入配网状态。

/**
 * @brief Local fast unactive
 *
 * @param[in] mthd: new work mode after reboot
 * @param[in] wifi_start_mode: new netcfg mode after reboot
 *
 * @return OPERATE_RET
 */
OPERATE_RET tuya_iot_wf_gw_fast_unactive(GW_WF_CFG_MTHD_SEL mthd, GW_WF_START_MODE wifi_start_mode);

使用示例

// 执行自定义重置行为
VOID __reset_cb(GW_RESET_TYPE_E type)
{
    if(GW_LOCAL_RESET_FACTORY == type) { // 本地恢复出厂重置

    } else if(GW_REMOTE_UNACTIVE == type) { // App 普通重置（解除绑定）

    } else if(GW_LOCAL_UNACTIVE == type) { // 本地普通重置（解除绑定）

    } else if(GW_REMOTE_RESET_FACTORY == type) { // App 恢复出厂重置

    } else if(GW_RESET_DATA_FACTORY == type) { // 激活时数据重置（详见 FAQ）

    }
}

// 设备初始化
int test_dev_init()
{
    TY_IOT_CBS_S cbs = {
        .gw_reset_cb = __reset_cb，
        //其他回调函数设置
    };


    // 调用设备初始化 API，把 cbs 传入
    // xxx
}

// 本地普通重置
void test_local_unactive()
{
    TUYA_CALL_ERR_LOG(tuya_iot_wf_gw_unactive());
}

// 本地恢复出厂重置
void test_local_reset()
{
    TUYA_CALL_ERR_LOG(tuya_iot_wf_gw_reset());
}

注意事项

开发框架执行完自身的重置任务后会通过回调函数通知开发者设备被重置了，方便开发者在回调中执行自定义的重置行为。最后开发框架会调用 Reset 接口重启设备。设备重启完成后就会进入对应的配网状态。

FAQ

设备离线时可以执行 App 重置么？

可以。

App 重置，将导致设备在云端的状态发生改变。在设备重新上线后，会收到云端的解绑指令，并执行相应重置动作（等同于设备在线时收到云端下发的重置指令）。

设备离线时可以执行本地重置么？

可以。

本地重置，设备将清除自身保存的数据，并重启进入配网状态（此时 App 面板上设备显示为离线）。

为什么激活时也收到了重置回调？

用户通过 App 执行恢复出厂操作后，再将设备重新配网时，使用的 App 账户与原 App 账户不是同一个家庭账号下，则云端在设备激活时会下发 reset factory 指令，开发框架将通过回调函数将 GW_RESET_DATA_FACTORY 状态通知给开发者。