Bulk Commissioning

Set up and commission smart home devices in bulk without internet access, making project delivery easier for real estate. This topic describes how to implement the bulk commissioning feature with TuyaOS Gateway Development Kit.

Scenarios

With a construction SaaS, you can configure setup templates specific to each house plan in light of devices, scenes, and automation, and issue tasks to field engineers.

The engineer uses the dedicated mobile app to add devices and test scenes and automation, and hands over privileges to end users after they move in.

End users can directly try out the pre-configured scenes without going through the setup process.

How it works

1. The mobile app requests room information, device models, and scene configurations from the construction SaaS. The gateway exchanges data with the mobile app over a secure LAN.
2. After commissioning is done, the engineer uploads the deployment data from the mobile app to the construction SaaS that will synchronize the received data with the Tuya Developer Platform.
3. The gateway switches to the normal mode and becomes inactive.
4. After the gateway is activated by the end user, it requests the deployment data for restoration.
5. Tuya Developer Platform sends the deployment data to the gateway.
6. The sub-devices and scenes set up in the commissioning stage are displayed on the mobile app and are available to use.

Development guide

The gateway should support switching between commissioning mode and normal mode. You can use command line parameters to run a gateway in the desired mode. It is recommended to enable the gateway to restart into normal mode by default and switch to commissioning mode with button press.

Perform the following steps to add the commissioning mode to your gateway product.

1. Determine whether to enter commissioning mode. If so, call tuya_set_engineer_mode.

2. Call tuya_get_engineer_mode to get the current operation mode.

   • If the gateway is in commissioning mode, the parameter to tuya_iot_init is the directory for commissioning mode (defaulting to directory for normal mode + /engineer/).
   • If the gateway is in normal mode, the parameter to tuya_iot_init is the directory for normal mode.

3. In both the commissioning mode and normal mode, you need to call tuya_engineer_sdk_init to initialize the commissioning SDK. Set the value of product_key to the PID for normal mode. There are two scenarios for using this API.

   • If you use Tuya’s Zigbee module, before you call this API, tuya_engineer_set_tuya_zigbee_enable must be called to enable the commissioning service for Zigbee.
   • If you do not use Tuya’s Zigbee module, you need to implement callbacks for TY_ENGR_GW_ZIG_CBS_S to act as parameters to this API.

4. Initialize the SDK.

   • If the gateway runs in commissioning mode, call tuya_engineer_gw_init to initialize the commissioning gateway service, with the product_key set to the PID for commissioning mode.
   • If the gateway runs in normal mode, call tuya_iot_wr_wf_sdk_init to initialize the normal gateway service, with the product_key set to the PID for normal mode.

5. Specify the network interface for LAN. You need to adapt to tkl_wifi_get_ip to return the IP address of the network interface for LAN.

API description

Enter commissioning mode

/**
 * @brief Set the gateway to run in commissioning mode.
 * @note Call this API first when the program starts to make the gateway enter commissioning mode.
 */
VOID tuya_set_engineer_mode(VOID);

Determine operation mode

/**
 * @brief Determine if the gateway is in commissioning mode.
 * @note Call this API to check the operation mode.
 *
 * @return TRUE: Commissioning mode. FALSE: Normal mode.
 */
BOOL_T tuya_get_engineer_mode(VOID);

Initialize the SDK

/**
 * @brief Initialize SDK.
 * @note Call this API to initialize the SDK regardless of the operation mode. In commissioning mode, the commissioning logic is processed. In normal mode, the deployment data is synchronized.
 *
 * @param[in] product_key The PID for normal mode.
 * @param[in] eng_infra_cbs Commissioning application callback.
 * @param[in] eng_zig_cbs Callback for Zigbee commissioning service.
 */
OPERATE_RET tuya_engineer_sdk_init(IN CONST CHAR_T *product_key,
                                   IN TY_ENGR_GW_INFRA_CBS_S *eng_infra_cbs,
                                   IN TY_ENGR_GW_ZIG_CBS_S* eng_zig_cbs);

Initialize the gateway

/**
 * @brief Initialize the gateway commissioning service.
 * @note This API applies to commissioning mode. For normal mode, call `tuya_iot_sdk_init` / `tuya_iot_wf_sdk_init` / `tuya_iot_wr_wf_sdk_init` to initialize the gateway service.
 *
 * @param[in] net_mode Specify the network mode.
 * @param[in] product_key The PID for commissioning mode.
 * @param[in] sw_ver Firmware version.
 * @param[in] attr An array of module information.
 * @param[in] attr_num  The length of the array of module information.
 */
OPERATE_RET tuya_engineer_gw_init(IN CONST IOT_GW_NET_TYPE_T net_mode,
                                  IN CONST CHAR_T *product_key,
                                  IN CONST CHAR_T *sw_ver,
                                  IN CONST GW_ATTACH_ATTR_T *attr,
                                  IN CONST UINT_T attr_num);

Enable Tuya’s Zigbee service

/**
 * @brief Enable Zigbee commissioning service.
 * @note If the gateway uses Tuya's Zigbee module, call this API to enable the Zigbee commissioning service. The SDK processes the corresponding logic. This API must be called before `tuya_engineer_sdk_init`.
 */
OPERATE_RET tuya_engineer_set_tuya_zigbee_enable(VOID);

Example

For more information, see the example apps/tuyaos_demo_engr.