Gateway Networking SDK

Last Updated on : 2022-11-24 09:20:06download

Using the networking capabilities of gateways, Tuya gateway networking SDK serves as the software middleware to build communication links with Tuya IoT 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 IoT 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 IoT Platform. Each device must have a unique UUID and authKey.

    Gateway Networking SDK

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 IoT 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 IoT 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 IoT 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

Gateway Networking SDK

  • 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)

Gateway Networking SDK

  • 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.

Gateway Networking SDK

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 IoT 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.

Gateway Networking SDK

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 IoT 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.

Gateway Networking SDK

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.

    Gateway Networking SDK

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.

Gateway Networking SDK

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 IoT 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>”:

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 IoT 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 IoT platform.

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