Device Reset

Overview

Concepts

A device is restored to the settings that the device had before it was paired and activated. Device reset can be triggered in two ways:

• Locally reset
• Remotely reset

In terms of device status after a reset, there are two types of reset:

• Normal reset: Unbind a device.
• Factory reset: Unbind a device and clear data.

A device reset is associated with device pairing modes. For more information, Device pairing modes.

Scenarios

When to use device reset:

• Make the device enter pairing mode: For devices with memory mode, a reset can make them enter pairing mode.

• Remove network connection or unbind a device: A reset allows the device to connect to another router.

• Restore factory settings or clear user data: For electrical products, a reset deletes the energy metering data from the local storage.

  For devices supporting Wi-Fi network backup or Pegasus pairing, they can be switched to a new router without a reset.

Description

• Normal reset (Unbind a device):
  • Clear the pairing data saved locally.
  • Clear the schedule data saved locally.
  • Notify the cloud to unbind the device. The device’s historical data such as schedule data and device name is not cleared. It will be restored after the device is paired and bound again.
  • Notify users through a callback.
• Factory reset (Unbind a device and clear data)
  • Clear the pairing data and schedule data saved locally.
  • Notify users through a callback.
  • Clear the description of data points (schema) saved locally.
  • Notify the cloud to unbind the device and clear the device’s historical data.

Implementation

Pseudocode for device reset:

GW_RESET_TYPE_E reset_type;
...
// Perform the reset action according to the reset type, and assign value to reset_type.
...

// Execute the callback function.
if (gw_cntl->cbs.gw_reset_cb) {
    gw_cntl->cbs.gw_reset_cb(reset_type);
}

// Restart the device.
tal_system_reset();

Development guide

Associated components

• svc_wifi_api

How to

• To reset a device locally, the application should proactively call the following APIs.

  • Normal reset (Unbind a device): tuya_iot_wf_gw_unactive
  • Factory reset (Unbind a device and clear data): tuya_iot_wf_gw_reset

• To reset a device remotely, you do not need to proactively call any APIs because the development framework listens for commands from the cloud and performs actions accordingly.

• The development framework notifies you of the reset event through a callback, no matter whether the device is reset locally or remotely. For more information about the notification callbacks, see IoT device functionality callbacks.

Data structure

Type definition

typedef enum {
    GW_LOCAL_RESET_FACTORY = 0,    // Local factory reset
    GW_REMOTE_UNACTIVE,                //  Normal reset via mobile app (unbind device)
    GW_LOCAL_UNACTIVE,                   // Local normal reset (unbind device)
    GW_REMOTE_RESET_FACTORY,       // Factory reset via mobile app
    GW_RESET_DATA_FACTORY,            // Reset data during activation (see FAQs)
} GW_RESET_TYPE_E;

Callbacks

The reset notification callback is passed in through the device initialization interface. No matter how the device is reset, this callback is invoked to perform the specified actions, such as clearing application data.

/**
 * @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);

APIs for local reset

Normal reset (Unbind a device)

The API returns immediately. It performs the reset actions asynchronously and returns the result through a callback.

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

Factory reset (Unbind a device and clear data)

The API returns immediately. It performs the reset actions asynchronously and returns the result through a callback.

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

Quick reset (Unbind a device)

This API performs the reset actions synchronously. After a reset, the device will restart in the pairing mode specified by mthd and 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);

Example

// Execute custom reset action.
VOID __reset_cb(GW_RESET_TYPE_E type)
{
    if(GW_LOCAL_RESET_FACTORY == type) { // Local factory reset

    } else if(GW_REMOTE_UNACTIVE == type) { // Normal reset via mobile app (unbind device)

    } else if(GW_LOCAL_UNACTIVE == type) { // Local normal reset (unbind device)

    } else if(GW_REMOTE_RESET_FACTORY == type) { // Factory reset via mobile app

    } else if(GW_RESET_DATA_FACTORY == type) { // Reset data during activation (see FAQs)

    }
}

// Device initialization
int test_dev_init()
{
    TY_IOT_CBS_S cbs = {
        .gw_reset_cb = __reset_cb,
        // Other callbacks.
    };


    // Call device initialization API to pass in cbs
    // xxx
}

// Local normal reset
void test_local_unactive()
{
    TUYA_CALL_ERR_LOG(tuya_iot_wf_gw_unactive());
}

// Local factory reset
void test_local_reset()
{
    TUYA_CALL_ERR_LOG(tuya_iot_wf_gw_reset());
}

Things to note

After the development framework completes the reset actions, it notifies you of the reset event through a callback. You can execute custom logic in the callback. In the end, the development framework calls the Reset interface to restart the device. The device starts in the specified pairing mode.

FAQs

Can I reset an offline device via the mobile app?

Yes, you can.

Device reset via the mobile app changes the device status stored in the cloud. The device will receive a command to unbind after getting back online. It then performs the reset actions, which works the same way as resetting an online device.

Can I reset an offline device locally?

Yes, you can.

Resetting a device locally clears the data saved locally and restarts the device in pairing mode. After a reset, the device status on the app shows Offline.

Why do I receive a reset callback during device activation?

If users use a different app account to pair devices that have been reset via the mobile app, the cloud sends the reset factory command to the device. The development framework notifies you of the GW_RESET_DATA_FACTORY status through a callback.