Gateway Networking SDK

Using the networking capabilities of gateways, Tuya gateway networking SDK serves as the software middleware to build communication links with Tuya Developer Platform and Tuya-powered apps and perform Tuya standard data transmission. You can use this SDK to develop gateway products that connect to Tuya Cloud.

• Gateways

  Use the gateway networking SDK and controllers of different protocols to develop a gateway product. The gateway can be connected to products with various communication protocols, such as Zigbee, Bluetooth Low Energy (LE), Z-Wave, and more. For example, control hubs and smart hosts in smart homes. The gateway provides firmware update capabilities for gateway firmware, gateway controllers, and sub-devices.

• Gateways equipped with sub-devices

  The gateway can control its sub-devices. It can also serve as a device with defined data points and be controlled.

Preparation

Before development, you need to register an account on the Tuya Developer Platform to get the required information for device development, including the product ID, license, and more. For specific steps, see Quick Start in 5 Minutes.

Hardware requirements

• Flash: The SDK code occupies about 2 MB. There is a read-write area.
• RAM: Running the SDK consumes 5 MB of memory. You need to increase the memory according to product functionality.

Software requirements

• Support Linux and Android operating systems.
• Support TCP/IP protocol stack.

Get the SDK

The Tuya gateway networking SDK is distributed as a static (.a) or dynamic (.so) library in the C language. Therefore, you need a cross-compilation toolchain of your system to package the SDK.

The Tuya gateway networking SDK will be regularly uploaded to [GitHub]. If the compiled product already contains your cross-compilation toolchain, you can download and use it directly.

Directory structure

.
├── build_app.sh
├── CHANGELOG.md
├── demos
├── platforms
└── sdk
    ├── include
    └── lib
        ├── libtuya_iot.a

For the description of the directory structure and usage, see the README.md file in the package.

Initialize the SDK

Device authentication

• The one-key-per-device authentication mechanism is used. The device is programmed with the unique UUID and authKey. The production line tools of the device shall be modified to support programming a unique UUID and authKey for each device.

• The UUID and authKey are in pairs, and each device must have its unique UUID and authKey. You can apply to the Tuya project manager for several sets for debugging.

• The device authentication information is set through the interface of tuya_iot_set_gw_prod_info.

  Note: The PID, UUID, and authKey in the demo are only used for testing, not for physical products. Otherwise, physical products will be unavailable. You need to apply for a PID in the Developer Platform. Each device must have a unique UUID and authKey.

  

Initialization interface description

tuya_iot_init

OPERATE_RET tuya_iot_init(IN CONST CHAR_T *fs_storge_path)

Functional description

It is used to initialize the Tuya IoT system and must be called first.

Parameter description

Parameter	Description
fs_storge_path	Assign a read-write path for the SDK. The path length cannot be greater than 110 bytes.

Return value

Return value	Description
OPRT_OK	Success.
Error code	Error codes returned on failure.

tuya_iot_get_sdk_info

CHAR_T *tuya_iot_get_sdk_info(VOID);

Functional description

Get the SDK version information.

Parameter description

Void.

Return value

Return value	Description
SDK information string	Include SDK compilation time, platform, version number, and functionalities.

TY_IOT_CBS_S

typedef struct {
    GW_STATUS_CHANGED_CB gw_status_cb;
    GW_UG_INFORM_CB gw_ug_cb;
    GW_RESET_IFM_CB gw_reset_cb;
    DEV_OBJ_DP_CMD_CB dev_obj_dp_cb;
    DEV_RAW_DP_CMD_CB dev_raw_dp_cb;
    DEV_DP_QUERY_CB dev_dp_query_cb;
    DEV_UG_INFORM_CB dev_ug_cb;
    DEV_RESET_IFM_CB dev_reset_cb;
#if defined(TUYA_GW_OPERATOR) && (TUYA_GW_OPERATOR==1)
    OPE_HTTPC_GET_CHCODE_CB ope_get_chcode_cb;
#endif
#if defined(ENABLE_ALARM) && (ENABLE_ALARM==1)
    GW_OFFLINE_DP_SAVE gw_offline_dp_save_cb;
#endif
} TY_IOT_CBS_S;

Summary

SDK user callback interface.

Member description

Member name	Description
gw_status_cb	Gateway status callback.
gw_ug_cb	See gw_ug_cb.
gw_reset_cb	See gw_reset_cb.
dev_obj_dp_cb	See dev_obj_dp_cb.
dev_raw_dp_cb	See dev_raw_dp_cb.
dev_dp_query_cb	DP query callback.
dev_ug_cb	See dev_ug_cb.
dev_reset_cb	See dev_reset_cb.
ope_get_chcode_cb	It is set to NULL. Not supported currently.
gw_offline_dp_save_cb	See gw_offline_dp_save_cb.

tuya_iot_app_cbs_init

VOID tuya_iot_app_cbs_init(IN CONST TY_IOT_APP_CBS_S *app_cbs);

Functional description

Register the callback function of the application layer.

Parameter description

Parameter	Description
app_cbs	The array of application callback. see TY_IOT_APP_CBS_S.

Return value

Void.

TY_IOT_APP_CBS_S

typedef struct {
    GW_APP_LOG_PATH_CB gw_app_log_path_cb;
#if defined(ENABLE_ALARM) && (ENABLE_ALARM==1)
    GW_HOME_SECURITY_IF_CB gw_home_security_if_cb;
    GW_HOME_SECURITY_ALARM_DEV_CB gw_home_security_alarm_dev_cb;
    GW_HOME_SECURITY_ALARM_DEV_CB gw_home_security_alarm_env_dev_cb;
    GW_HOME_SECURITY_ALARM_DELAY_STATUS_CB gw_home_security_alarm_delay_status_cb;
    GW_HOME_SECURITY_EVENT_CB gw_home_security_event_cb;
    GW_HOME_SECURITY_CANCEL_ALARM_CB gw_home_security_cancel_alarm;
#endif
}TY_IOT_APP_CBS_S;

Summary

Application callback interface, including log upload callback and home security callbacks.

Member description

Member name	Description
gw_app_log_path_cb	See gw_app_log_path_cb.
gw_home_security_if_cb	The interface for home security products. For products other than in the field of home security, this parameter is set to NULL. See gw_home_security_if_cb.
gw_home_security_alarm_dev_cb	The interface for home security products. For products other than in the field of home security, this parameter is set to NULL. See gw_home_security_alarm_dev_cb.
gw_home_security_if_cb	The interface for home security products. For products other than in the field of home security, this parameter is set to NULL. See gw_home_security_if_cb.
gw_home_security_alarm_delay_status_cb	The interface for home security products. For products other than in the field of home security, this parameter is set to NULL. See gw_home_security_alarm_delay_status_cb.
gw_home_security_event_cb	The interface for home security products. For products other than in the field of home security, this parameter is set to NULL. See gw_home_security_event_cb.
gw_home_security_cancel_alarm	The interface for home security products. For products other than in the field of home security, this parameter is set to NULL. See gw_home_security_cancel_alarm.

Interface for gateways working with Wi-Fi configuration

For more information, see tuya_iot_wifi_api.h.

---

WF_GW_PROD_INFO_S

typedef struct {
    CHAR_T *uuid; 
    CHAR_T *auth_key;
    CHAR_T *ap_ssid;
    CHAR_T *ap_passwd;
} WF_GW_PROD_INFO_S;

Functional description

Wi-Fi product information.

Member description

Member name	Description
uuid	uuid string. It cannot be NULL. The length must be less than or equal to 16 bytes.
auth_key	auth_key string. It cannot be NULL. The length must be less than or equal to 32 bytes.
ap_ssid	SSID prefix. The length must be less than or equal to 16 bytes. If it is set to NULL, the SSID prefix defaults to “Smartlife-”.
ap_passwd	The length must be less than or equal to 16 bytes. The default is NULL.

tuya_iot_set_wf_gw_prod_info

OPERATE_RET tuya_iot_set_wf_gw_prod_info(IN CONST WF_GW_PROD_INFO_S *wf_prod_info);

Functional description

Set the authorization information of gateways working with Wi-Fi configuration. The authorization information must be got from Tuya. Otherwise, the gateway cannot be used properly.

Parameter description

Parameter	Description
wf_prod_info	The gateway product information. See WF_GW_PROD_INFO_S.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_wf_gw_init

OPERATE_RET tuya_iot_wf_gw_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 CONST TY_IOT_GW_CBS_S *gw_cbs, 
                                IN CONST CHAR_T *product_key, 
                                IN CONST CHAR_T *wf_sw_ver, 
                                IN CONST GW_ATTACH_ATTR_T *attr, 
                                IN CONST UINT_T attr_num);

Functional description

The initialization interface for Wi-Fi gateways.

Parameter description

Parameter	Description
cfg	Wi-Fi configuration method.
start_mode	Wi-Fi pairing mode.
cbs	The registered callback. See TY_IOT_CBS_S.
gw_cbs	The registered gateway callback. See TY_IOT_GW_CBS_S.
product_key	It is generated when a product is created on the Developer Platform.
wf_sw_ver	Firmware version number.
attr	Gateway adapter configuration list.
attr_num	The number of gateway adapter configuration lists.

Return value

Return value	Description
OPRT_OK	Success.
Error code	Error codes returned on failure.

tuya_iot_wf_gw_dev_init

OPERATE_RET tuya_iot_wf_gw_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 CONST TY_IOT_GW_CBS_S *gw_cbs, 
                                    IN CONST CHAR_T *product_key, 
                                    IN CONST CHAR_T *wf_sw_ver, 
                                    IN CONST GW_ATTACH_ATTR_T *attr, 
                                    IN CONST UINT_T attr_num);

Functional description

The initialization interface for Wi-Fi gateways and devices. Compared with tuya_iot_wf_gw_init, this function enables the gateway to serve as a device with defined data points and be controlled.

Parameter description

See tuya_iot_wf_gw_init interface description.

Return value

See tuya_iot_wf_gw_init interface description.

tuya_iot_reg_get_wf_nw_stat_cb

OPERATE_RET tuya_iot_reg_get_wf_nw_stat_cb(IN CONST GET_WF_NW_STAT_CB nw_stat_cb);

Functional description

Get the Wi-Fi status interface.

Parameter description

Parameter	Description
nw_stat_cb	Register the network status callback.

The parameters of the callback function nw_stat_cb are of the GW_WIFI_NW_STAT_E type, which are defined as follows:

#define STAT_LOW_POWER          0   // Idle status, used to external configuration network
#define STAT_UNPROVISION        1   // SmartConfig status
#define STAT_AP_STA_UNCFG       2   //  Wi-Fi AP configuration status
#define STAT_AP_STA_DISC        3   // Wi-Fi AP is already configured. Station is disconnected
#define STAT_AP_STA_CONN        4   // AP station mode. Station is connected
#define STAT_STA_DISC           5   // Only station mode, disconnected
#define STAT_STA_CONN           6   // Station mode is connected
#define STAT_CLOUD_CONN         7   // Cloud is connected
#define STAT_AP_CLOUD_CONN      8   // Cloud is connected and AP starts

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

Interface for gateways working beyond the Wi-Fi protocol

For more information, see tuya_iot_wifi_api.h.

GW_PROD_INFO_S

typedef struct {
   CHAR_T *uuid; 
   CHAR_T *auth_key;
} GW_PROD_INFO_S;

Functional description

The gateway product information.

Member description

Member name	Description
uuid	uuid string. It cannot be NULL.
auth_key	auth_key string. It cannot be NULL.

tuya_iot_set_gw_prod_info

OPERATE_RET tuya_iot_set_gw_prod_info(IN CONST GW_PROD_INFO_S *prod_info);

Functional description

Set the authorization information of network modules working beyond the Wi-Fi protocol. The authorization information must be got from Tuya. Otherwise, the gateway cannot be used properly.

Parameter description

Parameter	Description
prod_info	Product information. See GW_PROD_INFO_S.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_gw_init

OPERATE_RET tuya_iot_gw_init(IN CONST TY_IOT_CBS_S *cbs, 
                            IN CONST TY_IOT_GW_CBS_S *gw_cbs, 
                            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);

Functional description

The initialization interface for the network module.

Parameter description

Parameter	Description
cbs	The array of callback functions that need to be registered. See TY_IOT_CBS_S.
gw_cbs	The array of gateway callback functions that need to be registered. See TY_IOT_GW_CBS_S.
product_key	The PID of a product created on the Developer Platform.
sw_ver	Firmware version number.
attr	Gateway adapter configuration list.
attr_num	The number of gateway adapter configuration lists.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_gw_dev_init

OPERATE_RET tuya_iot_gw_dev_init(IN CONST TY_IOT_CBS_S *cbs, 
                                IN CONST TY_IOT_GW_CBS_S *gw_cbs, 
                                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);

Functional description

The initialization interface for network modules of gateway devices. Compared with tuya_iot_gw_init, this function enables the gateway to serve as a device with defined data points and be controlled.

Parameter description

See the tuya_iot_gw_init interface description.

Return value

See the tuya_iot_gw_init interface description.

tuya_iot_reg_get_nw_stat_cb

OPERATE_RET tuya_iot_reg_get_nw_stat_cb(IN CONST GET_NW_STAT_CB nw_stat_cb);

Functional description

Register the callback function of getting network status. You can get the current network status information.

Parameter description

Parameter	Description
nw_stat_cb	Register the network change callback.

With the registered callback function, you can get the current network status according to the parameters of the callback function. The network status GW_BASE_NW_STAT_T is defined as follows:

/* offline in LAN.  user wired callback <hwl_bnw_station_conn> return <false> */
#define GB_STAT_LAN_UNCONN 0

/* online in LAN, offline in WAN.
   user wired callback <hwl_bnw_station_conn> return <true> but mqtt is offline
*/
#define GB_STAT_LAN_CONN 1

/* online in WAN.
   user wired callback <hwl_bnw_station_conn> return <true> and mqtt is online
*/
#define GB_STAT_CLOUD_CONN 2

For more information, see tuya_cloud_base_defs.h.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

Interface for wired and Wi-Fi gateways

For more information, see tuya_iot_wired_wifi_api.h.

tuya_iot_set_wired_wifi_gw_prod_info

tuya_iot_set_wired_wifi_gw_prod_info(IN CONST WF_GW_PROD_INFO_S *wf_prod_info);

For the parameter description, see the tuya_iot_set_wf_gw_prod_info function.

tuya_iot_wired_wifi_gw_init

OPERATE_RET tuya_iot_wired_wifi_gw_init(IN CONST IOT_GW_NET_TYPE_T net_mode, 
                                       IN CONST GW_WF_CFG_MTHD_SEL cfg, 
                                       IN CONST GW_WF_START_MODE start_mode,
                                       IN CONST TY_IOT_CBS_S *cbs, 
                                       IN CONST TY_IOT_GW_CBS_S *gw_cbs,
                                       IN CONST CHAR_T *product_key, 
                                       IN CONST CHAR_T *wf_sw_ver,
                                       IN CONST GW_ATTACH_ATTR_T *attr, 
                                       IN CONST UINT_T attr_num);

Functional description

The initialization interface for wired and Wi-Fi gateways.

Parameter description

Parameter	Description
net_mode	Network type.
cfg	Wi-Fi configuration method.
start_mode	Wi-Fi pairing mode.
cbs	The array of callback functions that need to be registered. See TY_IOT_CBS_S.
gw_cbs	The array of gateway callback functions that need to be registered. See TY_IOT_GW_CBS_S.
product_key	It is generated when a product is created on the Developer Platform.
wf_sw_ver	Firmware version number.
attr	Gateway adapter configuration list.
attr_num	The number of gateway adapter configuration lists.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_wired_wifi_gw_dev_init

OPERATE_RET tuya_iot_wired_wifi_gw_dev_init(IN CONST IOT_GW_NET_TYPE_T net_mode, 
                                           IN CONST GW_WF_CFG_MTHD_SEL cfg, 
                                           IN CONST GW_WF_START_MODE start_mode, 
                                           IN CONST TY_IOT_CBS_S *cbs, 
                                           IN CONST TY_IOT_GW_CBS_S *gw_cbs, 
                                           IN CONST CHAR_T *product_key, 
                                           IN CONST CHAR_T *wf_sw_ver, 
                                           IN CONST GW_ATTACH_ATTR_T *attr, 
                                           IN CONST UINT_T attr_num);

Functional description

The initialization interface for wired and Wi-Fi gateway devices. The gateway can work as a device.

Parameter description

Parameter	Description
net_mode	Network type.
cfg	Wi-Fi configuration method.
sw_ver	Device’s firmware version string in the format of xx.xx.xx.
cbs	The array of callback functions that need to be registered. See TY_IOT_CBS_S.
gw_cbs	Gateway callback.
product_key	The array of gateway callback functions that need to be registered. See TY_IOT_GW_CBS_S.
wf_sw_ver	Firmware version number.
attr	Gateway adapter configuration list.
attr_num	The number of gateway adapter configuration lists.

IOT_GW_NET_TYPE_T is defined as follows:

#define IOT_GW_NET_WIRED       0   // Support the wired mode only
#define IOT_GW_NET_WIFI        1   // Support Wi-Fi only
#define IOT_GW_NET_WIRED_WIFI  2   // Support both the wired mode and the Wi-Fi mode

GW_WF_CFG_MTHD_SEL is defined as follows:

#define GWCM_OLD                0   // The low power mode is unavailable
#define GWCM_LOW_POWER          1   // The low power mode is available
#define GWCM_SPCL_MODE          2   // Special with low power mode
#define GWCM_OLD_PROD           3   // GWCM_OLD mode with product

For Linux and Android systems, select GWCM_OLD_PROD.

GW_WF_START_MODE is defined as follows:

#define WF_START_AP_ONLY        0   // Only the access point (AP) mode is available.
#define WF_START_SMART_ONLY     1   // Only the SmartConfig mode is available.
#define WF_START_AP_FIRST       2   // Both the AP and SmartConfigare available. AP mode is set by default.
#define WF_START_SMART_FIRST    3   // Both the AP and SmartConfig are available. SmartConfig is set by default.
#define WF_START_SMART_AP_CONCURRENT    4   //  The AP and SmartConfig are concurrent.

The parameter attr shall be set to a supported adapter. For example, if the gateway supports Zigbee, it can be set to:

GW_ATTACH_ATTR_T attr[] = {
   {GP_DEV_ZB,"1.0.0"},
};

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_reg_get_wired_wifi_nw_stat_cb

OPERATE_RET tuya_iot_reg_get_wired_wifi_nw_stat_cb(nw_stat_cb, wf_nw_stat_cb);

Functional description

Register the callback function of managing network status.

Parameter description

Parameter	Description
nw_stat_cb	Register the callback function of network status change.
wf_nw_stat_cb	Register the callback function of the Wi-Fi network status change.

See tuya_iot_reg_get_nw_stat_cb and tuya_iot_reg_get_wf_nw_stat_cb callback function.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_gw_wired_wifi_set_net_name

VOID tuya_iot_gw_wired_wifi_set_net_name(IN CONST CHAR_T *wired_net_name, IN CONST CHAR_T *wifi_net_name);

Functional description

Set the wired and Wi-Fi network interfaces.

Parameter description

Parameter	Description
wired_net_name	Wired network interface name.
wifi_net_name	Wi-Fi interface network name.

Return value

Void.

Device pairing

Note: tuya_SDK will enable multiple threads. The entire process must be rebooted after entering the pairing mode.

Tuya SDK widely applies to many platforms and cannot cover the hardware details of each module. In the SDK, a set of interfaces for networking devices that need to be implemented is abstracted, which are divided into two categories: network interfaces for gateway working with Wi-Fi configuration and network interfaces for gateway working without Wi-Fi configuration. For more information, see the demo code.

Wired device pairing

The device is connected to the internet in a wired way, without the router hotspot name and password. You only need to get the activation token from the app and then apply for activation of the device in Tuya Cloud.

Reset the device (enter the status of waiting for pairing)

tuya_iot_gw_unactive

OPERATE_RET tuya_iot_gw_unactive(VOID);

Functional description

Reset the gateway device and unbind the gateway from the app. Then, the gateway will be waiting for pairing (inactive status).

Parameter description

Void.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_wired_wifi_gw_unactive

OPERATE_RET tuya_iot_wired_wifi_gw_unactive(VOID)

For more information, see tuya_iot_gw_unactive.

Pairing process diagram

• As shown above, after resetting the device locally, the SDK process shall be rebooted before entering the pairing mode.
• For more information, see dev_reset_cb.

Self-implemented interface

tuya_hal_wired_get_ip

OPERATE_RET tuya_hal_wired_get_ip(OUT NW_IP_S *ip)

Functional description

Get the IP address of the wired network card.

Parameter description

Parameter	Description
ip	IP information struct. The IP address, subnet mask, and gateway of the network card.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wired_station_conn

BOOL_T tuya_hal_wired_station_conn(VOID);

Functional description

Get the status of the internet connection.

Parameter description

Void.

Return value

Return value	Description
TRUE	The device is connected.
FALSE	The device is disconnected.

tuya_hal_wired_get_mac

OPERATE_RET tuya_hal_wired_get_mac(OUT NW_MAC_S *mac)

Functional description

Get the MAC address of the wired network interface. Optional implementation.

Parameter description

Parameter	Description
mac	The obtained MAC address of the network interface.

Return value

Return value	Description
OPRT_OK	Got successfully.
Error code	Failed to get.

hwl_bnw_set_mac

OPERATE_RET tuya_hal_wired_set_mac(IN CONST NW_MAC_S *mac);

Functional description

Set the MAC address of the wired network card. There is no need to implement this interface currently.

Parameter description

Parameter	Description
mac	Set the MAC address of the wired network card.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wired_wifi_set_station_connect

OPERATE_RET tuya_hal_wired_wifi_set_station_connect(IN CONST CHAR_T *ssid, 
                                                   IN CONST CHAR_T *passwd)

Functional description

For wired and Wi-Fi combined gateways, you shall implement the Wi-Fi connection function.

Parameter description

Parameter	Description
SSID.	The service set identifier (SSID) of the Wi-Fi router.
password	The password of the Wi-Fi router.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wired_wifi_need_cfg

BOOL_T tuya_hal_wired_wifi_need_cfg(VOID);

Functional description

For wired and Wi-Fi combined gateways, specify whether you need to connect to an external Wi-Fi station.

Parameter description

Void.

Return value

Return value	Description
TRUE	If the hardware has a Wi-Fi interface, you want the hardware to connect to an external Wi-Fi station.
FALSE	If the hardware does not have a Wi-Fi interface, you do not want the hardware to connect to an external Wi-Fi station.

tuya_hal_wired_wifi_station_get_conn_ap_rssi

OPERATE_RET tuya_hal_wired_wifi_station_get_conn_ap_rssi(OUT SCHAR_T *rssi)

Functional description

For wired and Wi-Fi combined gateways, this interface is used to get the RSSI value of Wi-Fi.

Parameter description

Parameter	Description
rssi	Save the obtained RSSI information.

Return value

Return value	Description
OPRT_OK	Got successfully.
Others	Failed to get.

tuya_hal_wired_if_connect_internet

int tuya_hal_wired_if_connect_internet(bool *status);

Functional description

Get the network status.

Parameter description

Parameter	Description
status	Network status. It is true when the network is connected. Otherwise, it is false.

Return value

Return value	Description
OPRT_OK	Got successfully.
Others	Failed to get.

Wi-Fi device pairing

• You need to check the working mode supported by the Wi-Fi network card and then inform the SDK of the supported pairing mode when the tuya_iot_wf_xx_init interface is initialized. For more information, see the cfg parameter description of the tuya_iot_wf_xx_dev_init interface.
• The SDK supports Wi-Fi Easy Connect mode and AP pairing mode. Wi-Fi Easy Connect enables a fast connection. When the device’s Wi-Fi is in the monitor mode and obtains the wireless air interface packets sent by the mobile app. The SDK will parse these packets to get configuration information and switch to the station mode for networking. AP pairing is relatively complicated: The device turns on the AP hotspot, the mobile phone is connected to the AP hotspot, and the configuration information is sent through the local area network. After the device gets the configuration information, the device switches to the station mode for networking.

Reset the device (enter the mode of waiting for pairing)

• As shown above, after resetting the device locally, the SDK process shall be rebooted before entering the pairing mode.
• For more information, see dev_reset_cb.
• During initialization, if both AP and Wi-Fi Easy Connect modes are set to be available, the pairing mode can be switched cyclically by calling this interface.

tuya_iot_wf_gw_unactive

OPERATE_RET tuya_iot_wf_gw_unactive(VOID);

Functional description

Reset the gateway device and unbind the gateway sub-device. Then, the gateway will be waiting for pairing (inactive status).

Parameter description

Void.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_wired_wifi_gw_unactive

OPERATE_RET tuya_iot_wired_wifi_gw_unactive(VOID);

Functional description

Reset wired and Wi-Fi combined gateway. It is the same as tuya_iot_wf_gw_unactive.

tuya_iot_wf_fast_get_nc_type

OPERATE_RET tuya_iot_wf_fast_get_nc_type(GW_WF_NWC_FAST_STAT_T *nc_type)

Functional description

Get the current Wi-Fi configuration type.

Parameter description

Parameter	Description
nc_type	Wi-Fi configuration type.

GW_WF_NWC_FAST_STAT_T is defined as follows:

#define GWNS_FAST_LOWPOWER           0   // Currently in low power mode
#define GWNS_FAST_UNCFG_SMC          1   // Currently in Smart-Config mode
#define GWNS_FAST_UNCFG_AP           2   // Currently in AP mode
#define GWNS_FAST_UNCFG_NORMAL       3   // Currently in normal mode

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_wired_wifi_fast_get_nc_type

OPERATE_RET tuya_iot_wired_wifi_fast_get_nc_type(GW_WF_NWC_FAST_STAT_T *nc_type);

Functional description

Get the current Wi-Fi configuration mode in wired and Wi-Fi combined mode. The parameter description is the same as tuya_iot_wf_fast_get_nc_type.

tuya_iot_set_wf_cfg_err_code_cb

OPERATE_RET tuya_iot_set_wf_cfg_err_code_cb(IN CONST WF_NW_CFG_ERR_CODE_CB wf_nw_cfg_err_code_cb);

Functional description

Register the callback function. It is used to get the error code in the Wi-Fi pairing.

Parameter description

Parameter	Description
wf_nw_cfg_err_code_cb	The callback function of getting the error code in the Wi-Fi pairing.

The callback function parameter is the error code in the Wi-Fi pairing. The definition is as follows:

/*Initial status*/ 
#define NW_CFG_INIT       0
/*Activation failed*/ 
#define NW_CFG_ACTIVE_FAILED    1
/*Cannot find AP*/ 
#define NW_CFG_AP_NOT_FOUND    2
/*Wrong password*/ 
#define NW_CFG_ERR_PASSWD     3
/*Cannot connect to AP*/ 
#define NW_CFG_CANT_CONN_AP    4
/*DHCP error*/ 
#define NW_CFG_DHCP_FAILED     5
/*The router is connected successfully*/ 
#define NW_CFG_SUCC      100

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

AP pairing

1. Implement the required interface.
2. After the device is reset, the SDK is waiting for pairing.

tuya_iot_set_user_def_ap_if

OPERATE_RET tuya_iot_set_user_def_ap_if(IN CONST CHAR_T *ssid,IN CONST CHAR_T *passwd)

Functional description

You can customize the SSID prefix and password. If not set, the SSID prefix is “SmartLife-” by default, the password is empty, and the encryption method is open.

Parameter description

Parameter	Description
SSID.	Custom SSID prefix.
passwd	AP password.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

WF_AP_CFG_IF_S

typedef struct {
   uint8_t ssid[WIFI_SSID_LEN+1];       ///< SSID
   uint8_t s_len;                       ///< SSID length
   uint8_t passwd[WIFI_PASSWD_LEN+1];   ///< Password
   uint8_t p_len;                       ///< Password length
   uint8_t chan;                        ///< Channel. Default to 0
   WF_AP_AUTH_MODE_E md;                ///< Encryption type
   uint8_t ssid_hidden;                 ///< SSID hidden. Default to 0
   uint8_t max_conn;                    ///< The max number of connected stations. Default to 0
   uint16_t ms_interval;                ///< Broadcast interval. Default to 0
} WF_AP_CFG_IF_S;

Summary

AP configuration struct.

Member description

Member name	Description
SSID.	SSID.
s_len	SSID length.
passwd	Password.
p_len	Password length.
chan	Wi-Fi working channel.
md	Wi-Fi encryption type.
ssid_hidden	The hidden SSID.
max_conn	The maximum number of connected station devices.
ms_interval	Broadcast interval.

Self-implemented interface

tuya_hal_wifi_get_ip

OPERATE_RET tuya_hal_wifi_get_ip(IN CONST WF_IF_E wf,OUT NW_IP_S *ip)

Functional description

Get the IP address of the Wi-Fi network card.

Parameter description

Parameter	Description
wf	The working type of the Wi-Fi network card.
ip	Save the obtained IP information structure. The information includes IP address, subnet mask, and gateway.

Type definition of WF_IF_E:

typedef enum
{
   WF_STATION = 0,     // Station type
   WF_AP,              // AP type
} WF_IF_E;

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_get_mac

OPERATE_RET tuya_hal_wifi_get_mac(IN CONST WF_IF_E wf,INOUT NW_MAC_S *mac)

Functional description

Get the MAC address of the Wi-Fi network card.

Parameter description

Parameter	Description
wf	The working type of the Wi-Fi network card.
mac	Save the obtained MAC address.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_set_mac

OPERATE_RET tuya_hal_wifi_set_mac(IN CONST WF_IF_E wf,IN CONST NW_MAC_S *mac)

Functional description

Set the MAC address of the Wi-Fi device. There is no need to implement this interface currently.

Parameter description

Parameter	Description
wf	The working type of the Wi-Fi network card.
mac	The set MAC address.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_set_work_mode

OPERATE_RET tuya_hal_wifi_set_work_mode(IN CONST WF_WK_MD_E mode)

Functional description

Set the Wi-Fi working mode.

Parameter description

Parameter	Description
wf	Set the working mode of the Wi-Fi device.

The working mode of Wi-Fi is defined as follows:

typedef enum
{
   WWM_LOWPOWER = 0,   // Wi-Fi works in the low power mode. The Linux system can skip this working mode. 
   WWM_SNIFFER,        // Wi-Fi works in the sniffer mode
   WWM_STATION,        // Wi-Fi works in the station mode
   WWM_SOFTAP,         // Wi-Fi works in the AP mode
   WWM_STATIONAP,      // Wi-Fi works in the station and AP combined mode
}WF_WK_MD_E;

WWM_SNIFFER and WWM_STATION (or WWM_STATIONAP) shall be processed in Wi-Fi Easy Connect.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_get_work_mode

OPERATE_RET tuya_hal_wifi_get_work_mode(OUT WF_WK_MD_E *mode)

Functional description

Get the Wi-Fi working mode.

Parameter description

Parameter	Description
mode	It has the same meaning as the parameter mode in hwl_wf_wk_mode_set.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_station_connect

OPERATE_RET tuya_hal_wifi_station_connect(IN CONST CHAR_T *ssid,IN CONST CHAR_T *passwd)

Functional description

Wi-Fi devices connect to the router with the SSID and password.

Parameter description

Parameter	Description
SSID.	The SSID of the connected router.
password	The password of the connected router.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_station_disconnect

Function prototype

OPERATE_RET tuya_hal_wifi_station_disconnect(VOID)

Functional description

Disconnect the Wi-Fi device from the router.

Parameter description

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_station_get_conn_ap_rssi

OPERATE_RET tuya_hal_wifi_station_get_conn_ap_rssi(OUT SCHAR_T *rssi)

Functional description

Get the signal strength of the Wi-Fi device.

Parameter description

Parameter	Description
rssi	The obtained RSSI.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_station_get_status

OPERATE_RET tuya_hal_wifi_station_get_status(OUT WF_STATION_STAT_E *stat)

Functional description

Get the network status of the Wi-Fi device.

Parameter description

Parameter	Description
stat	You need to fill in stat. See the description of WF_STATION_STAT_E.

Description of WF_STATION_STAT_E:

typedef enum {
   WSS_IDLE = 0,                       // Not connected
   WSS_CONNECTING,                     // Connecting to Wi-Fi
   WSS_PASSWD_WRONG,                   // Incorrect password
   WSS_NO_AP_FOUND,                    // The AP is not found
   WSS_CONN_FAIL,                      // Failed to connect
   WSS_CONN_SUCCESS,                   // Connect to Wi-Fi successfully
   WSS_GOT_IP,                         // Got the IP address successfully 
} WF_STATION_STAT_E;

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_set_country_code

OPERATE_RET tuya_hal_wifi_set_country_code(IN CONST CHAR_T *p_country_code)

Functional description

Set the country code of the Wi-Fi device.

Parameter description

Parameter	Description
p_country_code	Wi-Fi devices work in different countries with different frequencies and channel signal strengths.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_ap_start

OPERATE_RET tuya_hal_wifi_ap_start(IN CONST WF_AP_CFG_IF_S *cfg)

Functional description

Enable the Wi-Fi AP.

Parameter description

Parameter	Description
cfg	Set the AP according to the function parameter cfg passed in. See WF_AP_CFG_IF_S.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_ap_stop

OPERATE_RET tuya_hal_wifi_ap_stop(VOID)

Functional description

Disable the hotspot in AP mode.

Parameter description

Void.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

Wi-Fi Easy Connect

Self-implemented interface (Wi-Fi Easy Connect)

tuya_hal_wifi_all_ap_scan

OPERATE_RET tuya_hal_wifi_all_ap_scan(OUT AP_IF_S **ap_ary,OUT UINT_T *num)

Functional description

Get the AP list in the current environment.

Parameter description

Parameter	Description
ap_ary	The AP list in the current environment.
num	The length of the AP list in the current environment.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_assign_ap_scan

OPERATE_RET tuya_hal_wifi_assign_ap_scan(IN CONST CHAR_T *ssid,OUT AP_IF_S **ap)

Functional description

Get the AP information of the specified SSID.

Parameter description

Parameter	Description
SSID.	The SSID of the specified AP.
ap	Get the specified AP information.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_release_ap

OPERATE_RET tuya_hal_wifi_release_ap(IN AP_IF_S *ap)

Functional description

Release processing of allocated resources.

Parameter description

Parameter	Description
ap	Release the memory requested in tuya_hal_wifi_all_ap_scan and tuya_hal_wifi_assign_ap_scan.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_set_cur_channel

OPERATE_RET tuya_hal_wifi_set_cur_channel(IN CONST BYTE_T chan)

Functional description

Set the Wi-Fi working channel.

Parameter description

Parameter	Description
chan	Set the working channel of the Wi-Fi device.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_get_cur_channel

OPERATE_RET tuya_hal_wifi_get_cur_channel(OUT BYTE_T *chan)

Functional description

Get the current working channel.

Parameter description

Parameter	Description
chan	Fill in the working channel of the current Wi-Fi device.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_hal_wifi_sniffer_set

OPERATE_RET tuya_hal_wifi_sniffer_set(IN CONST bool en,IN CONST SNIFFER_CALLBACK cb)

Functional description

Set the packet capture status of the Wi-Fi device in the sniffer mode.

Parameter description

Parameter	Description
en	Enable/disable the Wi-Fi sniffer mode.
cb	Notification callback function. The captured over-the-air 802.11 data, including the frame header.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

Other pairing methods

• The user layer gets the router’s SSID, password, and pairing token through other methods, and directly calls the interface to apply for device activation.
• QR code pairing: With the camera, the device scans the QR code on the app to get the SSID, password, and token information.
• Bluetooth pairing: The device gets the SSID, password, and token information on the app via Bluetooth.
• Serial port, sonic pairing, and more.

tuya_iot_gw_wf_user_cfg

OPERATE_RET tuya_iot_gw_wf_user_cfg(IN CONST CHAR_T *ssid, IN CONST CHAR_T *passwd,IN CONST CHAR_T *token);

Functional description

When the device is paired through other modes (rather than AP or Wi-Fi Easy Connect), such as the QR code scanning and the acoustic wave pairing, this interface can be called.

Parameter description

Parameter	Description
SSID.	The SSID used for pairing in the AP mode.
passwd	The password used for pairing in the AP mode.
token	The token used for pairing in the AP mode.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

Gateway reset

Reset the gateway with the app

You can reset the gateway with the app.

gw_reset_cb

VOID gw_reset_cb(GW_RESET_TYPE_E type);

Functional description

Register the callback function gw_reset_cb of TY_IOT_CBS_S.

Parameter description

Void.

GW_RESET_TYPE_E is defined as follows:

typedef enum {
   GW_LOCAL_RESET_FACTORY = 0,
   GW_REMOTE_UNACTIVE,
   GW_LOCAL_UNACTIVE,
   GW_REMOTE_RESET_FACTORY,
   GW_RESET_DATA_FACTORY, //  Local data needs to be cleared when active.
}GW_RESET_TYPE_E;

Currently, the reset types of GW_REMOTE_RESET_FACTORY and GW_RESET_DATA_FACTORY are processed in the callback. After reset, reboot the gateway application.

Return value

Void.

Locally reset the gateway

The SDK is capable of locally resetting the gateway. You can reset the gateway locally with the reset button. See tuya_iot_gw_unactive and tuya_iot_wf_gw_unactive.

Firmware update (OTA)

• The firmware update is used to fix bugs and add new functions. There are two types including device update and MCU update. The firmware updates of Wi-Fi devices here refer to device updates.

• The device update process involves the mobile app, device, and Tuya Cloud.

  • Mobile app: Display the update progress or initiate the update message.
  • Tuya Cloud: Manage the update. Store firmware updates, renew the device update status and push the update notification.
  • Device: Receive the firmware and execute the update.

Configuration description of the firmware package

• After the gateway or sub-device is successfully paired, the virtual ID in the device information from the app can be added to the whitelist for firmware updates.
• Compile the firmware package to be updated. The firmware version must be higher than that running on the device.
• Log in to the Tuya Developer Platform, find the created products, and upload the configuration firmware package. For more information, see Select and Change the Firmware Version.

Start updates

After the device firmware is uploaded to the cloud, the device will not receive the updates message immediately. Currently, Tuya supports the following methods:

• App notification upgrade: When opening the device panel for the first time, users will receive an upgrade prompt and can choose to update or not.
• App silent upgrade: The device is updated silently. After reboot, the device will ask the cloud for a silent upgrade task. If any, the device will be updated directly. If the user opens the device panel, a progress box will be displayed, and the device cannot be operated during an update.
• App forced upgrade: When opening the device panel for the first time, users will receive an upgrade prompt and must choose to upgrade. Otherwise, the device cannot be operated.
• App detects updates: Users can click the top right corner on the device panel to enter the device information interface and check for updates.

Data transmission process

The update progress in the figure below is reported by tuya_SDK, and it can also be reported by the application layer through tuya_iot_upgrade_gw_notify.

Interfaces and callback description

FW_UG_S

typedef struct {
   DEV_TYPE_T tp;
   UPGRADE_TYPE_T type;
   CHAR_T fw_url[FW_URL_LEN+1];
   CHAR_T sw_ver[SW_VER_LEN+1];
   UINT_T file_size;
   CHAR_T fw_hmac[FW_HMAC_LEN+1];
} FW_UG_S;

Summary

Updated firmware information.

Member description

Member name	Description
tp	Firmware type.
type	UPGRADE_TYPE_NORMAL: Normal update. UPGRADE_TYPE_SILENT: Forced update.
fw_url	Firmware download URL address.
sw_ver	Firmware version number.
file_size	Firmware size.
fw_hmac	Firmware HMAC authentication code.

gw_ug_cb

VOID gw_ug_cb(IN CONST FW_UG_S *fw)

Functional description

Register the callback function gw_ug_cb of TY_IOT_CBS_S. The callback of firmware update notification.

Parameter description

Parameter	Description
fw	Firmware information. See FW_UG_S.

Return value

Void.

tuya_iot_upgrade_gw

OPERATE_RET tuya_iot_upgrade_gw_notify(IN CONST FW_UG_S *fw, 
                                      IN CONST GET_FILE_DATA_CB get_file_cb, 
                                      IN CONST UPGRADE_NOTIFY_CB upgrd_nofity_cb, 
                                      IN CONST PVOID_T pri_data, 
                                      BOOL_T notify, 
                                      UINT_T download_buf_size);

Functional description

The interface for processing firmware updates of network modules.

Parameter description

Parameter	Description
fw	Firmware information.
get_file_cb	The callback function of storing downloaded files.
upgrd_nofity_cb	The callback function of notifying the application of the update status.
pri_data	Parameters passed to get_file_cb and upgrd_nofity_cb.
notify	Choose whether to report the update progress by the SDK.
download_buf_size	The maximum download cache in bytes.

Return value

Return value	Description
OPRT_OK	Success.
Error code	Error codes returned on failure.

Report the update progress by the application layer

When the application layer is required to control the update progress report, you can use the tuya_iot_upgrade_gw_notify interface to disable the reporting by tuya_SDK.

tuya_iot_dev_upgd_progress_rept

OPERATE_RET tuya_iot_dev_upgd_progress_rept(IN CONST UINT_T percent, 
                                           IN CONST CHAR_T *devid, 
                                           IN CONST DEV_TYPE_T tp);

Functional description

Report the update progress.

Parameter description

Parameter	Description
percent	Update progress value ranging from 0 to 99.
devid	For a sub-device, pass in the sub-device ID. For a gateway, pass in NULL.
tp	Device type.

Return value

Return value	Description
OPRT_OK	Success.
Error code	Error codes returned on failure.

tuya_iot_dev_upgd_result_report

OPERATE_RET tuya_iot_dev_upgd_result_report(IN CONST CHAR_T *dev_id, 
                                           IN CONST DEV_TYPE_T type, 
                                           IN CONST INT_T result);

Functional description

Report the device update progress.

Parameter description

Parameter	Description
devid	For a sub-device, pass in the sub-device ID. For a gateway, pass in NULL.
tp	Device type.
result	Update result.

TI_UPGRD_STAT_S is defined as follows:

#define TUS_RD 1         // Get ready
#define TUS_UPGRDING 2   // Updating
#define TUS_UPGRD_FINI 3  // Completed
#define TUS_UPGRD_EXEC 4  // Exit after the update is completed

Return value

Return value	Description
OPRT_OK	Success.
Error code	Error codes returned on failure.

tuya_iot_refuse_upgrade

OPERATE_RET tuya_iot_refuse_upgrade(IN CONST FW_UG_S *fw, IN CONST CHAR_T *dev_id);

Functional description

Stop the update during the update process.

Parameter description

Parameter	Description
fw	Firmware information. See FW_UG_S.
devid	For a sub-device, pass in the sub-device ID. For a gateway, pass in NULL.

Return value

Return value	Description
OPRT_OK	Success.
Error code	Error codes returned on failure.

tuya_iot_gw_version_update

OPERATE_RET tuya_iot_gw_version_update(IN GW_PERMIT_DEV_TP_T type, IN CONST CHAR_T *ver);

Functional description

After the update is completed, update the firmware version number of the gateway or gateway adapter.

Parameter description

Parameter	Description
type	Gateway type.
Ver	Firmware version number.

GW_PERMIT_DEV_TP_T is defined as follows:

#define GP_DEV_ZB DEV_ZB_SNGL    // Zigbee 
#define GP_DEV_OTHER DEV_OTHER_SNGL // Others
#define GP_DEV_BLE DEV_BLE_SNGL     // Bluetooth
#define GP_DEV_INFRARED DEV_INFRARED_SNGL // IR
#define GP_DEV_MCU  DEV_NM_NOT_ATH_SNGL // MCU

Return value

Return value	Description
OPRT_OK	Success.
Error code	Error codes returned on failure.

Data points of device

Tuya provides the MQTT-based network application protocol to implement device control and status reporting. MQTT is a lightweight publish-subscribe mode messaging protocol that is designed for IoT applications in low-bandwidth and unstable network environments.

tuya_SDK encapsulates the implementation of the MQTT protocol layer, which is abstracted as the data point (hereinafter referred to as DP). DP supports types of numeric, Boolean, enumeration, string, fault, and raw data, as simple as defining a C variable.

You need to create data points based on device functions on the Tuya Developer Platform. For more information about DP creation, see Function Definition.

Features:

• Currently, up to 35 DPs can be created for each product. You need to use raw data to implement complex functions.
• For obj types, including Boolean (bool), numeric (value), string (string), enumeration (enum), and fault (bitmap), tuya_SDK filters continuously reported values and does not upload the identical values.

DP struct

TY_RECV_OBJ_DP_S

typedef struct {
   DP_CMD_TYPE_E cmd_tp;
   DP_TRANS_TYPE_T dtt_tp;
   CHAR_T *cid;
   CHAR_T *mb_id;
   UINT_T dps_cnt;
   TY_OBJ_DP_S dps[0];
} TY_RECV_OBJ_DP_S;

Summary

Obj type DP data structure.

Member description

Member name	Description
cmd_tp	Command type, specifying how the command is generated.
dtt_tp	Transmission type.
cid	If CID is NULL, it is a gateway device. Otherwise, it is a sub-device.
mb_id	If dtt_tp adopts multicast, mb_id indicates the group ID.
dps_cnt	The number of DP struct arrays.
dps_cnt	The DP struct array.

TY_RECV_RAW_DP_S

typedef struct {
   DP_CMD_TYPE_E cmd_tp;
   DP_TRANS_TYPE_T dtt_tp;
   CHAR_T *cid;
   BYTE_T dpid;
   CHAR_T *mb_id;
   UINT_T len;
   BYTE_T data[0];
} TY_RECV_RAW_DP_S;

Summary

Raw type DP data structure.

Member description

Parameter	Description
cmd_tp	Command type, specifying how the command is generated.
dtt_tp	Transmission type.
cid	If CID is NULL, it is a gateway device. Otherwise, it is a sub-device.
dpid	DP ID.
mb_id	If dtt_tp adopts multicast, mb_id indicates the group ID.
len	Raw data length.
data	Raw data cache.

TY_DP_QUERY_S

typedef struct {
   CHAR_T *cid;
   UINT_T cnt;
   BYTE_T dpid[0];
} TY_DP_QUERY_S;

Summary

Query the DP information.

Member description

Parameter	Description
cid	If CID is NULL, it is a gateway device. Otherwise, it is a sub-device.
cnt	The number of DPs. If it is equal to 0, it means all DPs.
dpid	The DP ID to be queried.

Callback of sending device commands

dev_obj_dp_cb

VOID dev_obj_dp_cb(IN CONST TY_RECV_OBJ_DP_S *dp);

Functional description

Register the callback function dev_obj_dp_cb of TY_IOT_CBS_S. Callback of obj DP.

Parameter description

Parameter	Description
dp	Obj type DP data that the SDK calls back to the user. See TY_RECV_OBJ_DP_S.

Return value

Void.

dev_raw_dp_cb

VOID dev_raw_dp_cb(IN CONST TY_RECV_RAW_DP_S *dp);

Functional description

Register the callback function dev_raw_dp_cb of TY_IOT_CBS_S. The callback of raw DPs.

Parameter description

Parameter	Description
dp	Raw type DP data that the SDK calls back to the user. See TY_RECV_RAW_DP_S.

Return value

Void.

dev_dp_query_cb

VOID dev_dp_query_cb(IN CONST TY_DP_QUERY_S *dp_qry);

Functional description

Register the callback function dev_dp_query_cb of TY_IOT_CBS_S. The callback of the entry to querying specific device data.

Parameter description

Parameter	Description
dp_qry	See TY_DP_QUERY_S.

Return value

Void.

Report the device status

dev_report_dp_json_async

OPERATE_RET dev_report_dp_json_async(IN CONST CHAR_T *dev_id, 
                                    IN CONST TY_OBJ_DP_S *dp_data,
                                    IN CONST UINT_T cnt);

Functional description

Report DP information in an asynchronous manner.

Parameter description

Parameter	Description
dev_id	Device ID.
dp_data	DP data struct.
cnt	The number of dp_data struct arrays.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

dev_report_dp_raw_sync

OPERATE_RET dev_report_dp_raw_sync (IN CONST CHAR_T *dev_id, 
                                   IN CONST BYTE_T dpid, 
                                   IN CONST BYTE_T *data,
                                   IN CONST UINT_T len, 
                                   IN CONST UINT_T timeout);

Functional description

The interface of synchronously reporting raw data. The caller guarantees the reliability of data reporting.

Parameter description

Parameter	Description
dev_id	Device ID.
dpid	DP ID.
data	Raw data.
len	Raw data length.
timeout	Timeout interval for blocked functions.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

dev_report_dp_stat_sync

#define dev_report_dp_stat_sync(dev_id, dp_data, cnt, timeout) \
   dev_report_dp_stat_sync_extend(dev_id, dp_data, cnt, timeout, TRUE)
OPERATE_RET dev_report_dp_stat_sync_extend(IN CONST CHAR_T *dev_id,
                                          IN CONST TY_OBJ_DP_S *dp_data,
                                          IN CONST UINT_T cnt,
                                          IN CONST UINT_T timeout, 
                                          IN CONST BOOL_T enable_auto_retrans);

Functional description

The interface of synchronously reporting struct data, which usually applies to reporting statistics data. The caller guarantees the reliability of data reporting.

Parameter description

Parameter	Description
dev_id	Device ID.
dp_data	DP information struct array. See TY_OBJ_DP_S.
cnt	Length of DP status array.
timeout	Timeout interval for blocked functions.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

Sub-device management

Sub-device pairing

Data transmission process

• This picture shows how to add a sub-device with the mobile app.
• The gateway can also call tuya_iot_gw_bind_dev to bind a sub-device.
• You shall implement the communication protocol between the sub-device and the gateway.

Interfaces and callback description

TY_IOT_GW_CBS_S

typedef struct {
   GW_PERMIT_ADD_DEV_CB gw_add_dev_cb;
   GW_DEV_DEL_CB gw_del_cb;
   GW_DEV_GRP_INFM_CB gw_dev_grp_cb;
   GW_DEV_SCENE_INFM_CB gw_dev_scene_cb;
   GW_BIND_DEV_INFORM_CB gw_ifm_cb;
} TY_IOT_GW_CBS_S;

Summary

The callback functions for the gateway to add and enable sub-devices, delete sub-devices, scenes, groups, and notify sub-device binding.

Member description

Member name	Description
gw_add_dev_cb	See gw_add_dev_cb.
gw_del_cb	See gw_del_cb.
gw_dev_grp_cb	See gw_dev_grp_cb.
gw_dev_scene_cb	See gw_dev_scene_cb.
gw_ifm_cb	See gw_ifm_cb.

gw_add_dev_cb

BOOL_T gw_add_dev_cb(IN CONST GW_PERMIT_DEV_TP_T tp, 
                    IN CONST BOOL_T permit, 
                    IN CONST UINT_T timeout);

Functional description

Register the callback function gw_add_dev_cb of TY_IOT_GW_CBS_S. When adding a sub-device, enable the network access function of the device in this callback.

Parameter description

Parameter	Description
tp	Sub-device type.
permit	Whether to allow adding sub-devices. TRUE indicates sub-devices can be added, and FALSE indicates sub-devices cannot be added.
timeout	Pairing timeout in seconds.

Return value

Return value	Description
TRUE	Operation succeeded.
FALSE	Failure.

gw_del_cb

VOID gw_del_cb(IN CONST CHAR_T *dev_id);

Functional description

Register the callback function gw_del_cb of TY_IOT_GW_CBS_S. When a sub-device is deleted, this callback is used to notify users.

Parameter description

Parameter	Description
dev_id	The ID of the deleted device.

Return value

Void.

tuya_iot_gw_bind_dev

OPERATE_RET tuya_iot_gw_bind_dev(IN CONST GW_PERMIT_DEV_TP_T tp, 
                                IN CONST USER_DEV_DTL_DEF_T uddd, 
                                IN CONST CHAR_T *id,
                                IN CONST CHAR_T *pk, 
                                IN CONST CHAR_T *ver);

Functional description

The interface for gateway binding sub-devices. When the Tuya-powered app enables the gateway to add sub-devices, call this interface to bind the discovered sub-devices.

Parameter description

Parameter	Description
tp	Sub-device type.
uddd	The user-defined device type to distinguish different types of devices.
id	Sub-device ID. The length cannot exceed 25 bytes.
pk	The product key of the sub-device. The length cannot exceed 16 bytes.
Ver	Firmware version number of the sub-device. The length cannot exceed 10 bytes.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

gw_bind_ifm_cb

VOID gw_bind_ifm_cb(IN CONST CHAR_T *dev_id, IN CONST OPERATE_RET op_ret);

Functional description

Register the callback function gw_bind_ifm_cb of TY_IOT_GW_CBS_S. After a sub-device is bound, this callback is used to notify users.

Parameter description

Parameter	Description
dev_id	The ID of the sub-device to be bound.
op_ret	The result of binding. OPRT_OK indicates the binding succeeded. Others indicate the binding failed.

Return value

Void.

Unbind sub-device

Interfaces and callback description

tuya_iot_gw_unbind_dev

OPERATE_RET tuya_iot_gw_unbind_dev(IN CONST CHAR_T *id);

Summary

Unbind a sub-device.

Parameter description

Parameter	Description
dev_id	The ID of the sub-device to be unbound from the gateway.

Return value

Void.

Sub-device firmware update (OTA)

Data transmission process

• The communication between the sub-device and the gateway device layer is implemented by yourself. It is briefly explained here.

• The update progress reporting can be completely controlled by the user. The progress report is only updated when the gateway sends the firmware package to the sub-device.

• 60s timeout mechanism of firmware update on the Tuya Smart app: Every time a package of progress update messages is received from the device, the timer will restart. The application layer can control the update progress report to extend the app timeout.

  

Interfaces and callback description

dev_ug_inform_cb

VOID dev_ug_cb(IN CONST CHAR_T *dev_id, IN CONST FW_UG_S *fw)

Functional description

Register the callback function dev_ug_cb of TY_IOT_CBS_S. Notify OTA firmware updates of the sub-device. It indicates that the latest firmware is available for the sub-device.

Parameter description

Parameter	Description
dev_id	The ID of the sub-device that has firmware updates.
fw	See FW_UG_S.

Return value

Void.

tuya_iot_upgrade_dev

OPERATE_RET tuya_iot_upgrade_dev_notify(IN CONST CHAR_T *devid, 
                                       IN CONST FW_UG_S *fw,
                                       IN CONST GET_FILE_DATA_CB get_file_cb,
                                       IN CONST UPGRADE_NOTIFY_CB upgrd_nofity_cb,
                                       IN CONST PVOID_T pri_data)

Functional description

The device firmware update interface includes the main control device of the gateway and each sub-device.

Parameter description

Parameter	Description
devid	Device ID string.
fw	Updated firmware information. See FW_UG_S.
get_file_cb	Download and store the files.
upgrd_nofity_cb	The callback function of notifying the download completion. The device update function needs to be called in this callback.
pri_data	The parameters passed to get_file_cb and upgrd_nofity_cb. For example, the handle of downloaded update files.

Return value

Return value	Description
OPRT_OK	Success.
Error code	Error codes returned on failure.

tuya_iot_gw_subdevice_update

OPERATE_RET tuya_iot_gw_subdevice_update (IN CONST CHAR_T *id, IN CONST CHAR_T *ver);

Functional description

Update the firmware version number of the sub-device.

Parameter description

Parameter	Description
dev_id	Sub-device ID. The length cannot exceed 25 bytes.
Ver	Firmware version number of the sub-device. See Tuya’s definition of the version number format in this topic.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

Online management of sub-devices

Enable the heartbeat detection mechanism of tuya_SDK. The following figure shows the interface call diagram when the SDK’s heartbeat keep-alive mechanism is enabled.

After starting the sub-device heartbeat management, call the function tuya_iot_set_dev_hb_timeout to set the sub-device heartbeat configuration when binding the sub-device. Note that after restarting the gateway application, call the function tuya_iot_dev_traversal to traverse the sub-device and set the sub-device heartbeat configuration.

tuya_iot_dev_online_stat_update

OPERATE_RET tuya_iot_dev_online_stat_update(IN CONST CHAR_T *dev_id, IN CONST BOOL_T online);

Functional description

The gateway updates the online/offline status of the sub-device.

Parameter description

Parameter	Description
dev_id	Sub-device ID.
online	Online status. TRUE means online. FALSE means offline.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_sys_mag_hb_init

OPERATE_RET tuya_iot_sys_mag_hb_init(IN CONST DEV_HEARTBEAT_SEND_CB hb_send_cb);

Functional description

Enable the heartbeat management capability of the sub-device.

Parameter description

Parameter	Description
hb_send_cb	The gateway checks all sub-devices every three seconds. If the sub-device does not send a heartbeat to the gateway within the timeout of the heartbeat packet, the gateway will set the sub-device offline, and notify the user at least three times through hb_send_cb.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_set_dev_hb_timeout

OPERATE_RET tuya_iot_set_dev_hb_timeout (IN CONST CHAR_T *dev_id, IN CONST TIME_S hb_timeout_time);

Functional description

The sub-device heartbeat timeout setting. If the gateway does not receive the sub-device heartbeat within the set time, the gateway will set the sub-device offline.

Parameter description

Parameter	Description
dev_id	Sub-device ID.
hb_timeout_time	The heartbeat timeout in seconds. If it is set to 0xffffffff, the sub-device will skip the heartbeat check and will always be online.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_fresh_dev_hb

OPERATE_RET tuya_iot_fresh_dev_hb(IN CONST CHAR_T *dev_id)

Functional description

When the gateway receives the heartbeat information of the sub-device, this function is called to refresh the heartbeat status of the sub-device.

Parameter description

Parameter	Description
dev_id	Sub-device ID.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

Get sub-device information

tuya_iot_dev_traversal

DEV_DESC_IF_S *tuya_iot_dev_traversal(INOUT VOID **iterator);

Functional description

Sub-device traversal. All sub-devices of the gateway can be traversed through this interface.

Parameter description

Parameter	Description
iterator	To temporarily save the linked list, you only needs to define a null pointer.

Return value

Return value	Description
DEV_DESC_IF_S	A pointer to the struct of the device information from which the user can read the device information.
NULL	The device information has been read.

Sub-device group control

gw_dev_grp_cb

OPERATE_RET gw_dev_grp_cb(IN CONST GRP_ACTION_E action, IN CONST CHAR_T *dev_id, IN CONST CHAR_T *grp_id);

Functional description

Register the callback function gw_dev_grp_cb of TY_IOT_GW_CBS_S. In this callback, the group operation processing command is implemented.

Parameter description

Parameter	Description
action	The operation type of the group. Add and delete groups.
dev_id	The ID of the sub-device added to the group grp_id.
grp_id	Group ID.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

Sub-device scene function

gw_dev_scene_cb

OPERATE_RET gw_dev_scene_cb(IN CONST SCE_ACTION_E action, 
                           IN CONST CHAR_T *dev_id, 
                           IN CONST CHAR_T *grp_id, 
                           IN CONST CHAR_T *sce_id);

Functional description

Register the callback function gw_dev_scene_cb of TY_IOT_GW_CBS_S. The scene processing command function is implemented in this callback.

Parameter description

Parameter	Description
action	The operation type of the scene. Add, delete, and execute scenes.
dev_id	Sub-device ID.
grp_id	Group ID.
sce_id	Scene ID.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

Sub-device reset callback

dev_reset_cb

VOID dev_reset_cb(IN CONST CHAR_T *dev_id, IN DEV_RESET_TYPE_E type)

Functional description

Register the callback function dev_reset_cb of TY_IOT_CBS_S. In this callback, the sub-device shall be reset.

Parameter description

Parameter	Description
dev_id	The ID of the sub-device that needs to be reset.
type	Reset type.

typedef enum {
   DEV_REMOTE_RESET_FACTORY, // Remove the device
   DEV_RESET_DATA_FACTORY, // Clear local data and remove the device 
} DEV_RESET_TYPE_E;

Return value

Void.

Log management

gw_app_log_path_cb

VOID app_log_path_cb(OUT CHAR_T *path, IN CONST INT_T len)

Functional description

Register the callback function app_log_path_cb of TY_IOT_GW_CBS_S. In this callback, the gateway log is uploaded by the user.

Parameter description

Parameter	Description
path	The path string of the local log file, which is an output parameter.
len	The maximum length of the local log file path string.

Return value

Void.

Note: Log management is vital for device maintenance and troubleshooting. It is recommended to leave about 5 MB to 10 MB space on the device for device’s operation log storage. When the device fails, you can pull the device log on the Tuya Developer Platform through the gateway device ID. In order to facilitate troubleshooting, this function must be implemented.

Pseudo-code

STATIC VOID app_log_path_cb(OUT CHAR_T *path, IN CONST INT_T len);
int main(void)
{
   tuya_iot_init(CFG_STORAGE_PATH);
   ......
   TY_IOT_APP_CBS_S iot_app_cbs =  {
       app_log_path_cb,
   };
   tuya_iot_app_cbs_init(&iot_app_cbs);
   ......
   while(1){
       sleep(10);
   }
}
/*****************************************************************
 
* @Function: app_log_path_cb
* @Description: Callback of getting local log 
* @Param[out]: path, the path string of the local log compressed file 
* @Param[in]: len, the maximum length of the local log compressed file path string 
* @Return: void
*****************************************************************/
STATIC VOID app_log_path_cb(OUT CHAR_T *path, IN CONST INT_T len)
{
   PR_DEBUG("app_log_path_cb，log_file_path maxlen:%d",len);
// This is just for reference, the saving and compression of log files shall be implemented by yourself 
   CHAR_T log_file_path[] = {"/tmp/tuya_log.tar.gz"};
 
   if( (strlen(log_file_path) < len) && (path ! = NULL) ){
       snprintf(path, len, "%s", log_file_path);
   }
}

Home security

tuya_iot_home_secruity_info_set

OPERATE_RET tuya_iot_home_secruity_info_set(IN CONST CHAR_T *mode_str,
									   IN CONST CHAR_T *node_id,
									   IN CONST CHAR_T *delay_str);

Functional description

Set the current arming and disarming mode. For example, set the arming and disarming mode with remote control.

Parameter description

Parameter	Description
mode_str	Arming mode. 0: Disarm (fixed). 1: Arm at home. 2: Arm away.
node_id	The device ID that triggered the setting. “0123456789”: Indicates that the device 0123456789 triggered the arming, which can be NULL.
delay_str	Delay arming time. JSON format: {“<mode_str>”:}. For example, JSON string: such as {"1":1000}, indicating that the delay time of arming when at home is 1000s, which can be NULL. The time set by the mobile app shall prevail. It is not required to be set currently.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_home_secruity_get_alarm_info

OPERATE_RET tuya_iot_home_secruity_get_alarm_info(OUT ALARM_INFO_S *alarm_info);

Functional description

Get the current security status information.

Parameter description

Parameter	Description
alarm_info	Security information struct. The current mode, alarm status, and arming delay status. See ALARM_INFO_S.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_home_secruity_alarm_status

OPERATE_RET tuya_iot_home_secruity_alarm_status(IN CONST BOOL_T alarm_status);

Functional description

Synchronize the alarm status. The status changes of security standard DP 32 on the application layer are synchronized to the SDK through the API.

Parameter description

Parameter	Description
alarm_status	Synchronization status. FALSE: Normal. TRUE: Alarming.

Return value

Return value
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

tuya_iot_net_mode_report

OPERATE_RET tuya_iot_net_mode_report(IN CONST HOME_SECURITY_NET_MODE net_mode);

Functional description

Synchronize the current network mode.

Parameter description

Parameter	Description
net_mode	Ethernet, Wi-Fi, and 4G. See the definition of HOME_SECURITY_NET_MODE.

typedef enum  {
   HOME_SECURITY_NET_MODE_WAN=0,     // wired
   HOME_SECURITY_NET_MODE_WIFI,      //wifi
   HOME_SECURITY_NET_MODE_4G,        //4G
} HOME_SECURITY_NET_MODE;

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

gw_home_security_if_cb

VOID app_gw_home_security_if_cb(IN CONST CHAR_T *mode_str, IN CONST UINT_T time, BOOL_T is_sound)

Functional description

Register the callback function gw_home_security_if_cb of TY_IOT_APP_CBS_S. The callback of notifying the application layer of arming mode switching.

Parameter description

Parameter	Description
mode_str	Arming mode. 0: Disarm (fixed). 1: Arm at home. 2: Arm away.
time	Delay time of the arming mode in seconds. 0 means no delay.
is_sound	Whether to play a sound. FALSE: It means the sound is not played, but only the mode is switched. It is used in the scenes where programs are started without playing sound. TRUE: Play the sound.

Return value

Void.

app_gw_home_security_alarm_dev_cb

VOID app_gw_home_security_alarm_dev_cb(IN CONST CHAR_T *cid, IN ty_cJSON *dp_inf)

Functional description

Register the callback function app_gw_home_security_alarm_dev_cb of TY_IOT_APP_CBS_S.

The DP of the non-environmental device triggers an alarm, notifies the application layer, and reports it through the security standard DP 26.

The non-environmental device is related to arming and disarming, and only alarms in arming mode.

Parameter description

Parameter	Description
cid	Device ID.
dp_inf	The information about the DP that triggered the alarm.

Return value

Void.

app_gw_home_security_alarm_env_dev_cb

VOID app_gw_home_security_alarm_env_dev_cb(IN CONST CHAR_T *cid, IN ty_cJSON *dp_inf)

Functional description

Register the callback function app_gw_home_security_alarm_env_dev_cb of TY_IOT_APP_CBS_S.

The DP of the environmental device triggers an alarm, notifies the application layer, and reports it through the security standard DP 26.

The environmental device is irrelevant to arming and disarming. As long as it is triggered, it will alarm.

Parameter description

Parameter	Description
cid	Device ID.
dp_inf	The information about the DP that triggered the alarm.

Return value

Void.

app_gw_home_security_alarm_delay_status

VOID app_gw_home_security_alarm_delay_status(IN ALARM_DELAY_STATE alarm_status)

Functional description

Register the callback function app_gw_home_security_alarm_delay_status of TY_IOT_APP_CBS_S.

The delayed alarm is implemented by the SDK. When there is a delayed alarm (not alarmed, and still in the delay period), the application is notified through this interface.

Parameter description

Parameter	Description
alarm_status	Alarm delay status. ALARM_DELAY_DONOT_CREATE: The alarm delay has not been created. ALARM_DELAY_COUNTDOWN: The alarm delay is in progress. ALARM_DELAY_END: The alarm delay is over.

typedef enum  {
   ALARM_DELAY_DONOT_CREATE=0, 
   ALARM_DELAY_COUNTDOWN,
   ALARM_DELAY_END,
} ALARM_DELAY_STATE;

Return value

Void.

app_gw_home_security_event

VOID app_gw_home_security_event(IN SECURITY_EVENT_E security_event_status, PVOID_T data)

Functional description

Register the callback function app_gw_home_security_event of TY_IOT_APP_CBS_S.

Notify the application of events.

Parameter description

Parameter	Description
security_event_status	Event type. DISARMED_EVENT: Disarm event (you can ignore when the if_cb interface has this notification). ARMED_EVENT: Enter arming (after the countdown, arming at home or away from home). BYPASS_EVNET: Ignorable events occur, which is used to trigger sound playing. WARING_COUNTDOWN: The alarm countdown starts, and the time is transmitted through the parameter data.
data	–

typedef enum  {
   DISARMED_EVENT,
ARMED_EVENT, //Enter arming (after the countdown, arming at home or away from home) 
BYPASS_EVNET, // Ignore 
WARING_COUNTDOWN, // Alarm countdown 
} SECURITY_EVENT_E;

Return value

Void.

gw_home_security_cancel_alarm

VOID gw_home_security_cancel_alarm(VOID)

Functional description

Register the callback function gw_home_security_cancel_alarm of TY_IOT_APP_CBS_S.

The callback function of canceling the alarm. After receiving this message, to cancel the alarm, the DP 32 reports FALSE.

Parameter description

Void.

Return value

Void.

ALARM_INFO_S

typedef struct {
   CHAR_T alarm_mode[ALARM_SECURITY_MODE_STR_LEN_MAX+1];
   BOOL_T alarm_status;
   BOOL_T enable_countdown_status;
} ALARM_INFO_S;

Functional description

Member description

Member name	Description
alarm_mode	Arming mode. 0: Disarm (fixed). 1: Arm at home. 2: Arm away.
alarm_status	Alarm status. TRUE: In alarm status (alarm delay and in alarm). FALSE: Normal status.
enable_countdown_status	Arming delay status. TRUE: Arming delay. FALSE: Others.

Project mode

tuya_iot_set_engineer_mode

VOID tuya_iot_set_engineer_mode(VOID);

Functional description

Set the SDK to be in the project mode. It is called before calling the gateway initialization function tuya_iot_gw_<*>_init.

Parameter description

Void.

Return value

Void.

tuya_iot_get_engineer_mode

BOOL_T tuya_iot_get_engineer_mode(VOID);

Functional description

Check whether it is in the project mode.

Parameter description

Void.

Return value

Return value	Description
BOOL_T	TRUE: In the project mode. FALSE: In the normal mode.

tuya_iot_gw_engineer_check

OPERATE_RET tuya_iot_gw_engineer_check(IN CONST CHAR_T *engineer_path, ENGR_TO_NORMAL_FINISH_CB cb);

Functional description

The gateway starts to restore from the project mode to the normal mode.

Parameter description

Parameter	Description
engineer_path	Storage path of the project mode.
cb	The callback of notifying switching to normal mode. In the callback, you shall delete the files stored in the project mode.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

TY_IOT_GW_CBS_ENGR_S

typedef struct {
   GW_PERMIT_ADD_DEV_CB gw_add_dev_cb;
   GW_DEV_DEL_CB gw_del_cb;
   GW_DEV_GRP_INFM_CB gw_dev_grp_cb;
   GW_DEV_SCENE_INFM_CB gw_dev_scene_cb;
   GW_BIND_DEV_INFORM_CB gw_ifm_cb;
   GW_SCE_PANEL_BIND_CB gw_sce_panel_cb;
} TY_IOT_GW_CBS_ENGR_S;

Functional description

The callback functions for the gateway to add and enable sub-devices, delete sub-devices, scenes, groups, notify sub-device binding, and set the scene panels.

Member description

Member name	Description
gw_add_dev_cb	It is consistent with the method used in TY_IOT_GW_CBS_S. See gw_add_dev_cb.
gw_del_cb	It is consistent with the method used in TY_IOT_GW_CBS_S. See gw_del_cb.
gw_dev_grp_cb	It is consistent with the method used in TY_IOT_GW_CBS_S. See gw_dev_grp_cb.
gw_dev_scene_cb	It is consistent with the method used in TY_IOT_GW_CBS_S. See gw_dev_scene_cb.
gw_ifm_cb	It is consistent with the method used in TY_IOT_GW_CBS_S. See gw_ifm_cb.
gw_sce_panel_cb	See gw_sce_panel_cb.

TY_IOT_CBS_ENGR_S

typedef struct {
    GW_STATUS_CHANGED_CB gw_status_cb;
    GW_UG_LAN_INFORM_CB gw_lan_ug_cb;
    GW_RESET_IFM_CB gw_reset_cb;
    DEV_OBJ_DP_CMD_CB dev_obj_dp_cb;
    DEV_RAW_DP_CMD_CB dev_raw_dp_cb;
    DEV_DP_QUERY_CB dev_dp_query_cb;
    DEV_UG_LAN_INFORM_CB dev_lan_ug_cb;
    DEV_RESET_IFM_CB dev_reset_cb;
    GW_SET_CHANNEL_CB gw_set_channel_cb;
    GW_GET_CHANNEL_CB gw_get_channel_cb;
    GW_GET_LOG_CB gw_get_log_cb;
    GW_SYNC_CONFIG_CB gw_sync_config_cb;
    GW_ENG_FIN_CB gw_engineer_finish_cb;
} TY_IOT_CBS_ENGR_S;

Functional description

Void.

Member description

Member name	Description
gw_status_cb	It is consistent with the method used in gw_status_cb of TY_IOT_CBS_S.
gw_lan_ug_cb	It is consistent with the method used in gw_ug_cb of TY_IOT_CBS_S.
gw_reset_cb	It is consistent with the method used in gw_reset_cb of TY_IOT_CBS_S.
dev_obj_dp_cb	It is consistent with the method used in dev_obj_dp_cb of TY_IOT_CBS_S.
dev_raw_dp_cb	It is consistent with the method used in dev_raw_dp_cb of TY_IOT_CBS_S.
dev_dp_query_cb	It is consistent with the method used in dev_dp_query_cb of TY_IOT_CBS_S.
dev_lan_ug_cb	It is consistent with the method used in dev_ug_cb of TY_IOT_CBS_S.
dev_reset_cb	It is consistent with the method used in dev_reset_cb of TY_IOT_CBS_S.
gw_set_channel_cb	See gw_set_channel_cb.
gw_get_channel_cb	See gw_get_channel_cb.
gw_get_log_cb	See gw_get_log_cb.
gw_sync_config_cb	See gw_sync_config_cb.
gw_engineer_finish_cb	See gw_engineer_finish_cb.

gw_sce_panel_cb

OPERATE_RET gw_sce_panel_cb(IN CONST CHAR_T *dev_id, 
      IN CONST SCE_PANEL_S *sce_panel,
      IN CONST INT_T btn_num)

Functional description

Register the callback function gw_sce_panel_cb of TY_IOT_GW_CBS_ENGR_S.

Set the scene panel callback.

Parameter description

Parameter	Description
dev_id	Scene panel device ID.
sce_panel	The panel information struct array to be set. See SCE_PANEL_S.
btn_num	The number of panels.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

gw_set_channel_cb

OPERATE_RET gw_set_channel_cb(IN INT_T channel)

Functional description

Register the callback function gw_set_channel_cb of TY_IOT_GW_CBS_ENGR_S.

Set the working channel of the gateway controller. If it is not wireless, set this callback to NULL.

Note: After the channel is reset, the sub-device might need to be bound again.

Parameter description

Parameter	Description
channel	Set the wireless working channel of the gateway controller.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

gw_get_channel_cb

OPERATE_RET gw_get_channel_cb(OUT INT_T *channel)

Functional description

Register the callback function gw_get_channel_cb of TY_IOT_GW_CBS_ENGR_S.

Get the wireless working channel of the gateway controller. If it is not wireless, set this callback to NULL.

Parameter description

Parameter	Description
*channel	Save the obtained wireless working channel of the gateway controller.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

gw_get_log_cb

OPERATE_RET gw_get_log_cb(OUT CHAR_T *path, IN CONST INT_T len)

Functional description

Register the callback function gw_get_log_cb of TY_IOT_GW_CBS_ENGR_S.

Callback of uploading the local log.

Parameter description

Parameter	Description
path	The log file path shall be uploaded. For example, /tmp/tuya.tar.gz.
len	The maximum length supported by the parameter path.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

gw_sync_config_cb

OPERATE_RET gw_sync_config_cb(VOID)

Functional description

Register the callback function gw_sync_config_cb of TY_IOT_GW_CBS_ENGR_S.

Synchronize project files to the normal mode for operation. SDK related files include: tuya_user.db and tuya_enckey.db.

Parameter description

Void.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

gw_engineer_finish_cb

OPERATE_RET gw_engineer_finish_cb(VOID)

Functional description

Register the callback function gw_engineer_finish_cb of TY_IOT_GW_CBS_ENGR_S.

The callback of notifying project deployment completion. The gateway application shall be restarted in the callback.

Parameter description

Void.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	Error codes returned on failure.

SCE_PANEL_S

typedef struct {
   INT_T btn;
   CHAR_T *grp;
   CHAR_T *sce;
   CHAR_T *sce_name;
} SCE_PANEL_S;

Functional description

Panel information struct.

Member description

Member name	Description
btn	Button ID.
grp	Group ID.
sce	Scene ID.
sce_name	Scene name.

Error code description

• Facilitate locating problem during development and debugging. The error code will be updated continuously.

Error code	Reason	Solution
-944	During DP reporting, the corresponding DPID is not under the product.	Log in to the Developer Platform and confirm.
-916	The long connection between the device and Tuya Cloud MQTT server is disconnected.	Check whether the device is connected to the internet correctly.
-926	When the device reports MQTT data, the server puback timed out.	Check the device network or reduce the frequency of reporting.
-945	DP attribute value does not match.	Check whether the reported DP attribute value is consistent with that defined on the Developer Platform.

For the definition of error code, see tuya_cloud_error_code.h.