Device Initialization

After a device is powered on and started, it calls a range of APIs to initialize the hardware environment, TuyaOS software, and applications.

Overview

Concepts

Module with independent OTA feature: The mobile app displays the version information about such modules as the MCU and external voice module. It will prompt users if a firmware update is available.

Description

Typically, when the software is started, the main function is run. For TuyaOS, the entry points vary depending on the systems. For example, in a Linux environment, the main function should be implemented by you. In an RTOS, you should implement the tuya_app_main function and initialize TuyaOS software and applications in this function.

How it works

• Device startup process

  

• TuyaOS system service initialization

  

• Device initialization

  

Development guide

Reference the header

• tuya_iot_com_api.h
• tuya_iot_wifi_api.h
• tuya_iot_base_api.h

How to

Before using other TuyaOS functions, you need to initialize the TuyaOS system service and set the startup parameters for your scenario. Then, select the initialization interface as per device capability and register the network status callback.

Data structure

System service initial parameters

• init_db: Specifies whether to initialize the key-value (KV) store service during TuyaOS system service initialization. If you do not initialize this service at that time, you need to explicitly call tuya_iot_kv_flash_init_param to enable it when needed. For more information, see FAQs.

• sys_env: System environment variables (for Linux).

• log_seq_path: The log file path (for Linux).

  /**
  * @brief Definition of TuyaOS init param
  */
  typedef struct {
      /** kv init or not */
      BOOL_T init_db;
      /** sys env settings */
      CHAR_T sys_env[SYS_ENV_LEN];
      /** log seq path */
      CHAR_T log_seq_path[LOG_SEQ_PATH_LEN];
  } TY_INIT_PARAMS_S;
  

IoT device functionality callbacks

• For devices

  • gw_status_cb: Notifies you of changes in device activation status.
  • gw_reset_cb: Notifies you of device reset.
  • dev_obj_dp_cb: Notifies you of reception of object data point (DP) commands.
  • dev_raw_dp_cb: Notifies you of reception of raw DP commands.
  • dev_dp_query_cb: Notifies you of queries for the current status of the specified DP.

• For a module with an independent OTA feature

  • pre_gw_ug_cb: Notifies you of a firmware update available for the module with an independent OTA feature. You should tell the development framework whether to install the update in the return value.

  • gw_ug_cb: Notifies you of the update process and the information required to download the update package.

    For networked products, sub-device-related callbacks are not needed, and you can just input NULL.

• For the connected sub-devices

  • pre_dev_ug_cb: Notifies you of a firmware update available for the connected sub-device. You should tell the development framework whether to install the update in the return value.

  • dev_ug_cb: Notifies you of the update process and the information required to download the update package.

  • dev_reset_cb: Notifies you of sub-device reset. This callback is not needed for networked products.

    For Wi-Fi or Wi-Fi and Bluetooth combo products, pairing with QR code related callbacks are not needed, and you can just input NULL.

• For pairing with QR code

  • active_shorturl: The development framework returns a URL during the pairing progress. You can generate a QR code from the received URL. The mobile app can scan the QR code to activate the device that supports pairing with QR code.

    /**
    * @brief Definition of gateway callback functions
    */
    typedef struct {
       /** status update */
       GW_STATUS_CHANGED_CB gw_status_cb;
       /** gateway upgrade */
       GW_UG_INFORM_CB gw_ug_cb;
       /** gateway reset */
       GW_RESET_IFM_CB gw_reset_cb;
       /** structured DP info */
       DEV_OBJ_DP_CMD_CB dev_obj_dp_cb;
       /** raw DP info */
       DEV_RAW_DP_CMD_CB dev_raw_dp_cb;
       /** DP query */
       DEV_DP_QUERY_CB dev_dp_query_cb;
       /** sub-device upgrade */
       DEV_UG_INFORM_CB dev_ug_cb;
       /** sub-device reset */
       DEV_RESET_IFM_CB dev_reset_cb;
       /** active short url */
       ACTIVE_SHORTURL_CB active_shorturl;
       /** gateway upgrade pre-condition */
       GW_UG_INFORM_CB pre_gw_ug_cb;
       /** sub-device upgrade pre-condition */
       DEV_UG_INFORM_CB pre_dev_ug_cb;
    } TY_IOT_CBS_S;
    

API description

System service initialization

This API is the entry point to TuyaOS system service initialization, which applies to device types including Ethernet, Wi-Fi, Wi-Fi and Bluetooth combo, and cellular. It allocates resources for TuyaOS basic services and performs initialization.

/**
 * @brief TuyaOS system service init
 *
 * @param[in] fs_storge_path: Storage path of KV database(Linux only)
 * @param[in] p_param: Extra init params, @see TY_INIT_PARAMS_S
 *
 * @return OPRT_OK on success. For others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_iot_init_params(IN CONST CHAR_T *fs_storge_path,
                                 IN CONST TY_INIT_PARAMS_S *p_param);

Initialize a networked device

This API is used to initialize a device that has multiple modules with an independent OTA feature, such as an external voice module.

Wireless device

/**
 * @brief General Wi-Fi device init(with attached functional facilities)
 *
 * @param[in] cfg: wifi device work mode, @see GW_WF_CFG_MTHD_SEL
 * @param[in] start_mode: wifi netcfg mode, @see GW_WF_START_MODE
 * @param[in] cbs: tuya sdk user callbacks, @see TY_IOT_CBS_S
 * @param[in] firmware_key: the firmware key
 * @param[in] product_key: product key/product ID
 * @param[in] wf_sw_ver: wifi module software version format: xx.xx.xx (0<=x<=9)
 * @param[in] tp: device type, DEV_NM_ATH_SNGL
 * @param[in] attr: attached firmware of this device, @see GW_ATTACH_ATTR_T
 * @param[in] attr_num: number of attached firmwares
 *
 * @return OPRT_OK on success. For others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_iot_wf_dev_init(IN CONST GW_WF_CFG_MTHD_SEL cfg,
                                 IN CONST GW_WF_START_MODE start_mode,
                                 IN CONST TY_IOT_CBS_S *cbs,
                                 IN CHAR_T *firmware_key,
                                 IN CHAR_T *product_key,
                                 IN CHAR_T *wf_sw_ver,
                                 IN CONST DEV_TYPE_T tp,
                                 IN GW_ATTACH_ATTR_T *attr,
                                 IN CONST UINT_T attr_num);

Wired device

/**
 * @brief General wired device init(with attached functional facilities)
 *
 * @param[in] cbs: tuya sdk user callbacks, @see TY_IOT_CBS_S
 * @param[in] firmware_key: the firmware key
 * @param[in] product_key: product key/product ID
 * @param[in] sw_ver: wired module software version format: xx.xx.xx (0<=x<=9)
 * @param[in] tp: device type, DEV_NM_ATH_SNGL
 * @param[in] attr: attached firmware of this device, @see GW_ATTACH_ATTR_T
 * @param[in] attr_num: number of attached firmwares
 *
 * @return OPRT_OK on success. For others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_iot_dev_init(IN CONST TY_IOT_CBS_S *cbs,
                              IN CONST CHAR_T *firmware_key,
                              IN CONST CHAR_T *product_key,
                              IN CONST CHAR_T *sw_ver,
                              IN CONST DEV_TYPE_T tp,
                              IN CONST GW_ATTACH_ATTR_T *attr,
                              IN CONST UINT_T attr_num);

Initialize an MCU-based device (having a module with an independent OTA feature)

With networked device initialization encapsulated, this API is dedicated to initializing a device that has a module with an independent OTA feature.

Wireless device

/**
 * @brief Wi-Fi device init (with MCU)
 *
 * @param[in] cfg: wifi device work mode, @see GW_WF_CFG_MTHD_SEL
 * @param[in] start_mode: wifi netcfg mode, @see GW_WF_START_MODE
 * @param[in] cbs: tuya sdk user callbacks, @see TY_IOT_CBS_S
 * @param[in] p_firmware_key: the firmware key
 * @param[in] product_key: product key/product ID
 * @param[in] wf_sw_ver: wifi module software version format:xx.xx.xx (0<=x<=9)
 * @param[in] mcu_sw_ver: MCU software version format:xx.xx.xx (0<=x<=9)
 *
 * @return OPRT_OK on success. For others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_iot_wf_mcu_dev_init(IN CONST GW_WF_CFG_MTHD_SEL cfg,
                                     IN CONST GW_WF_START_MODE start_mode,
                                     IN CONST TY_IOT_CBS_S *cbs,
                                     IN CHAR_T *p_firmware_key,
                                     IN CHAR_T *product_key,
                                     IN CHAR_T *wf_sw_ver,
                                     IN CONST CHAR_T *mcu_sw_ver);

Wired device

/**
 * @brief wired device init (with MCU)
 *
 * @param[in] cbs: tuya sdk user callbacks, @see TY_IOT_CBS_S
 * @param[in] p_firmware_key: the firmware key
 * @param[in] product_key: product key/product ID
 * @param[in] sw_ver: module software version format:xx.xx.xx (0<=x<=9)
 * @param[in] mcu_sw_ver: MCU software version format:xx.xx.xx (0<=x<=9)
 *
 * @return OPRT_OK on success. For others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_iot_mcu_dev_init(IN CONST TY_IOT_CBS_S *cbs,
                                  IN CHAR_T *p_firmware_key,
                                  IN CHAR_T *product_key,
                                  IN CHAR_T *sw_ver,
                                  IN CONST CHAR_T *mcu_sw_ver);

Initialize an SoC-based device (not having a module with an independent OTA feature)

With networked device initialization encapsulated, this API is dedicated to initializing a device that does not have a module with an independent OTA feature.

Wireless device

/**
 * @brief Wi-Fi device init(without MCU)
 *
 * @param[in] cfg: wifi device work mode, @see GW_WF_CFG_MTHD_SEL
 * @param[in] start_mode: wifi netcfg mode, @see GW_WF_START_MODE
 * @param[in] cbs: tuya sdk user callbacks, @see TY_IOT_CBS_S
 * @param[in] firmware_key: the firmware key
 * @param[in] product_key: product key/product ID
 * @param[in] wf_sw_ver: wifi module software version format:xx.xx.xx (0<=x<=9)
 *
 * @return OPRT_OK on success. For others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_iot_wf_soc_dev_init_param(IN CONST GW_WF_CFG_MTHD_SEL cfg,
                                           IN CONST GW_WF_START_MODE start_mode,
                                           IN CONST TY_IOT_CBS_S *cbs,
                                           IN CHAR_T *firmware_key,
                                           IN CHAR_T *product_key,
                                           IN CHAR_T *wf_sw_ver);

Wired device

/**
 * @brief wired device init(without MCU)
 *
 * @param[in] cbs: tuya sdk user callbacks, @see TY_IOT_CBS_S
 * @param[in] firmware_key: the firmware key
 * @param[in] product_key: product key/product ID
 * @param[in] sw_ver: module software version format:xx.xx.xx (0<=x<=9)
 *
 * @return OPRT_OK on success. For others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_iot_soc_init_param(IN CONST TY_IOT_CBS_S *cbs,
                                    IN CHAR_T *firmware_key,
                                    IN CHAR_T *product_key,
                                    IN CHAR_T *sw_ver);

Register network status callbacks

When a device’s network status changes, the TuyaOS development framework invokes the functions registered with this API to notify the application to respond.

Wireless device

/**
 * @brief Set callback when network state changed(@see GW_WIFI_NW_STAT_E)
 *
 * @param wf_nw_stat_cb: network status monitor callback
 * @param min_interval_s: @deprecated (callback is called on state changed)
 *
 * @return OPRT_OK on success. For others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_iot_reg_get_wf_nw_stat_cb_params(IN CONST GET_WF_NW_STAT_CB wf_nw_stat_cb,
                                                  IN CONST INT_T min_interval_s);

Wired device

/**
 * @brief Set callback when network state changed(@see GW_BASE_NW_STAT_T)
 *
 * @param nw_stat_cb: network status monitor callback
 * @param min_interval_s: @deprecated (callback is called on state changed)
 *
 * @return OPRT_OK on success. For others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_iot_reg_get_nw_stat_cb_params(IN CONST GET_NW_STAT_CB nw_stat_cb,
                                               IN CONST INT_T min_interval_s);

Example

STATIC VOID_T user_main(VOID_T)
{
  // 1. TuyaOS system service initialization
  TY_INIT_PARAMS_S init_param = {0};
  init_param.init_db = FALSE; //  Key-value (KV) store initialization takes a while, which can cause the system to start slowly. You can delay KV store initialization.
  strcpy(init_param.sys_env, TARGET_PLATFORM);
  TUYA_CALL_ERR_LOG(tuya_iot_init_params(NULL, &init_param));

  // 2. KV store initialization
  tuya_iot_kv_flash_init(NULL);

  // 3.  Set device authorization or production test
  // xxx

  // 4. Device initialization
  TY_IOT_CBS_S iot_cbs = {0};
  iot_cbs.gw_status_cb = __soc_dev_status_changed_cb;
  iot_cbs.gw_ug_cb = __soc_dev_rev_upgrade_info_cb;
  iot_cbs.gw_reset_cb = __soc_dev_restart_req_cb;
  iot_cbs.dev_obj_dp_cb = __soc_dev_obj_dp_cmd_cb;
  iot_cbs.dev_raw_dp_cb = __soc_dev_raw_dp_cmd_cb;
  iot_cbs.dev_dp_query_cb = __soc_dev_dp_query_cb;
  tuya_iot_wf_soc_dev_init(GWCM_OLD, WF_START_AP_ONLY, &wf_cbs);

  // 5. Register network status callbacks.
  tuya_iot_reg_get_wf_nw_stat_cb(__soc_dev_net_status_cb);
}

THREAD_HANDLE ty_app_thread = NULL;
STATIC VOID_T tuya_app_thread(VOID_T *arg)
{
  user_main();

  tal_thread_delete(ty_app_thread);
  ty_app_thread = NULL;
}

// Application entry point.
VOID_T tuya_app_main(VOID_T)
{
    THREAD_CFG_T thrd_param = {4096, 4, "tuya_app_main"};
     tal_thread_create_and_start(&ty_app_thread, NULL, NULL, tuya_app_thread, NULL, &thrd_param);
}

FAQs

What is init_db used for?

During TuyaOS system service initialization, the KV store service is initialized by default, unless you explicitly set init_db to FALSE.

If your product needs to quickly read stored data after power on to perform specified actions, it is recommended to store these data in UF and set init_db to FALSE on TuyaOS system service initialization. After the TuyaOS system service is initialized, call tuya_iot_kv_flash_init to explicitly initialize the KV store service.

Which API should I use to initialize a device that has multiple external modules like voice module, MCU, and Bluetooth module?

Wireless devices call tuya_iot_wf_dev_init, and wired devices call tuya_iot_dev_init. Make sure attr and attr_num are correctly configured. Example:

UINT_T attr_num = 3;
GW_ATTACH_ATTR_T attr[3] = {
  {
    .tp = DEV_NM_NOT_ATH_SNGL, // MCU module
    .ver = "1.0.0"
  },
  {
    .tp = DEV_BLE_SNGL, // Bluetooth module
    .ver = "2.0.0"
  },
  {
    .tp = DEV_ATTACH_MOD_1, // Voice module (customizing tp is required and must be consistent with the configuration on the Tuya IoT Development Platform.)
    .ver = "3.0.0"
  }
};

Support and help

If you have any problems with TuyaOS development, you can post your questions in the Tuya Developer Forum.