Add Sub-Devices

This topic describes how to enable a gateway to add a sub-device.

Description

Through the gateway, a sub-device is bound with and connected to the cloud. To add a sub-device to the gateway, the user performs the following steps:

1. Open the Smart Life app. This app can be downloaded from the App Store or app stores for Android.

2. Open the control panel of the gateway. Tap Add Sub-device to make the gateway ready for adding a sub-device.

3. Press and hold the reset button on a sub-device to make it enter the pairing mode. Then, the sub-device will regularly send broadcast packets.

4. After the sub-device joins the same network as the gateway, it will be bound with the cloud through the gateway. At this time, this sub-device will be on the list of bound sub-devices in the app. End-users tap Done to complete the process. Tap Done to complete the process.

The following sequence diagram shows how they interact with each other:

The interaction can be broken down into three parts:

1. The SDK directs the application to permit or disable the joining of a sub-device.
2. The application calls the SDK’s device binding function to bind the sub-device with the cloud.
3. The SDK notifies the application of the operation result.

How to

• Call tuya_subdev_user_sigle_type_reg to register the device management callback and implement the callback for dev_add and dev_bind.
• Implement the communication between the gateway and sub-devices.
• After a sub-device joins the network, the application calls tuya_iot_gw_bind_dev to bind the sub-device with the cloud.

Data structure

/**
 * @brief The sub-device management callback
 */
typedef struct __ty_gw_subdev_mgr_cbs_s {
    GW_PERMIT_ADD_DEV_CB                dev_add;            /**< add device callback function, see GW_PERMIT_ADD_DEV_CB */
    GW_DEV_DEL_CB                       dev_del;            /**< delete device callback function, see GW_DEV_DEL_CB */
    DEV_RESET_IFM_CB                    dev_reset;          /**< device reset callback function, see DEV_RESET_IFM_CB */
    GW_BIND_DEV_INFORM_CB               dev_bind;           /**< device bind result callback function, see GW_BIND_DEV_INFORM_CB */

    DEV_OBJ_DP_CMD_CB                   dp_cmd_obj;         /**< obj dp command, see DEV_OBJ_DP_CMD_CB */
    DEV_RAW_DP_CMD_CB                   dp_cmd_raw;         /**< raw dp command, see DEV_RAW_DP_CMD_CB */
    DEV_DP_QUERY_CB                     dp_query;           /**<query dp, see DEV_DP_QUERY_CB */

    DEV_HEARTBEAT_SEND_CB               dev_hb;             /**< device heartbeat query callback function, see DEV_HEARTBEAT_SEND_CB */
    DEV_UG_INFORM_CB                    dev_upgrade;        /**< device upgrade callback function, see DEV_UG_INFORM_CB */
    GW_DEV_WAKEUP_CB                    dev_wakeup;         /**< waking up low-power device callback function, see GW_DEV_WAKEUP_CB */
    GW_DEV_GRP_INFM_CB                  dev_grp_info;       /**< group action callback function, see GW_DEV_GRP_INFM_CB */
    GW_DEV_SCENE_INFM_CB                dev_sce_info;       /**< scene action callback function, see GW_DEV_SCENE_INFM_CB */

    GW_DEV_SIGMESH_TOPO_UPDAET_CB       bt_topo_update;     /**< adding Bluetooth mesh device to gateway callback function, see GW_DEV_SIGMESH_TOPO_UPDAET_CB */
    GW_DEV_SIGMESH_DEV_CACHE_DEL_CB     bt_cache_del;       /**< removing Bluetooth mesh device from gateway callback function, see GW_DEV_SIGMESH_DEV_CACHE_DEL_CB */
    GW_DEV_SIGMESH_CONN_CB              bt_conn;            /**< Bluetooth mesh device connection function, see GW_DEV_SIGMESH_CONN_CB */

    DEV_ONLINE_STAT_SEND_CB             dev_online;         /**< device online status changed callback function, see DEV_ONLINE_STAT_SEND_CB */
}TY_GW_SUBDEV_MGR_CBS_S;

API description

Bind sub-devices

/**
	* @brief  [Compatible interface] bind a sub-device to gateway
	*
	* @param tp sub-device type
	* @param uddd user-defined type
	* @param id sub-device id
	* @param pk sub-device product key
	* @param ver sub-device version
	*
	* @return OPERATE_RET OPRT_OK is success
*/
#define tuya_iot_gw_bind_dev(tp, uddd, id, pk, ver) \
tuya_iot_gw_bind_dev_attr(tp, uddd, 0, id, pk, ver, NULL, 0, FALSE, NULL)

Call tuya_iot_gw_bind_dev to bind a sub-device with the cloud. OPRT_OK is returned on a successful request.

Example

 /**
  * @brief The callback to invoke when to add devices.
  * @param[in]     tp          : The type of protocol
  * @param[in]     permit      : Whether to join or not
  * @param[in]     timeout     : Timeout
  */
  STATIC BOOL_T __dev_add_cb(CONST GW_PERMIT_DEV_TP_T tp, CONST BOOL_T permit, CONST UINT_T timeout)
  {
    /**
     * TODO:
     * permit == TRUE
     *    allow sub-device to join network and timeout is activated
     *
     * permit == FALSE
     *    stop net-in.
     */

    /**
     * Here we have an example showing how a sub-device join
     * a) Using fix-information sub-device
     * b) if it is not bound, bind it.
     */
      DEV_DESC_IF_S *dev_if = NULL;
      CHAR_T *dev_id = "abcdefabcdef";
      CHAR_T *pid    = "d1xabwgg"; // The PID of a three-way switch created in Tuya Developer Platform.
      if (permit) {
          dev_if = tuya_iot_get_dev_if(dev_id);
          if (dev_if && dev_if->bind) {
              return TRUE;
          }
          tuya_iot_gw_bind_dev(DEV_ATTACH_MOD_1, 0, dev_id, pid, "1.0.0");
      }

      return TRUE;
  }

 /**
  * @brief  The callback to invoke when to bind devices.
  * @param[in]     dev_id      : The device ID.
  * @param[in]     result      : The bind result.
  */
  STATIC VOID __dev_bind_cb(CONST CHAR_T *dev_id, CONST OPERATE_RET result)
  {
     /**
      * TODO:
      * result != OPRT_OK
      *     a) bind failed , do something?
      *     b) remove sub-device
      *
      * result == OPRT_OK
      *     a) maybe you should set heartbeat
      *     b) read sub-device's state & report
      */

     /**
      * Here we have an example showing what we should do after binding is successful
      *     a) set sub-device heartbeat : 2 mins timeout & 3 times
      *     b) report DP information
      */
      if (result == OPRT_OK) {
          tuya_iot_set_dev_hb_cfg(dev_id, 120, 3, FALSE);

          TY_OBJ_DP_S *dps = (TY_OBJ_DP_S *)Malloc(3 * SIZEOF(TY_OBJ_DP_S));
          if (dps == NULL) {
              return;
          }

          // all switch on
          for (int i = 0; i < 3; i++) {
              dps[i].dpid = (i + 1);
              dps[i].type = PROP_BOOL;
              dps[i].value.dp_bool = TRUE;
          }
          dev_report_dp_json_async(dev_id, dps, 3);
      }
  }


  TY_GW_SUBDEV_MGR_CBS_S dev_mgr_cbs = {
      .dev_add       = __dev_add_cb,
      .dev_bind      = __dev_bind_cb,
  };

  tuya_subdev_user_sigle_type_reg( &dev_mgr_cbs , DEV_ATTACH_MOD_1 );