Gateway Extension SDK

Last Updated on : 2024-11-20 08:51:47download

The gateway extension SDK contains APIs for implementing communication between the gateway, Zigbee module, Tuya Developer Platform, and Tuya mobile app. This SDK is a quick approach to connecting your gateway product to the Tuya Developer Platform without worrying about server provisioning and configuration so that you can focus on application development.

Overview

The SDK communicates with the downstream network modules and the upstream Tuya Developer Platform and Tuya mobile app, on which you can base your application development. The following block diagram takes the Zigbee gateway as an example to show the application architecture of the SDK.

Gateway types

Developing with this SDK, you can build gateway variants to create product differentiation. The variants can be but are not limited to the following types.

Type	Description
Zigbee gateway	Develop a typical Zigbee gateway with Tuya’s low-code solution. The SDK enables the third-party system to have Zigbee gateway capabilities and interconnectivity with `Powered by Tuya` (PBT) devices communicating over Zigbee protocol.
Zigbee extension gateway	The SDK enables the third-party system to connect non-PBT Zigbee devices to the Tuya Developer Platform as sub-devices of the gateway.
Hybrid gateway	The SDK enables the third-party system to connect to sub-devices. This helps you develop a gateway of a hybrid of Zigbee and other protocols or standards, such as 433 MHz, KNX, and Z-Wave.
Multifunctional gateway	The SDK enables the third-party system to integrate with various IoT features such as night lights and siren alarms, which can be linked with a bunch of sensors to create smart scenes.

Prerequisites

You have created an account on the Tuya Developer Platform and got the required information such as product ID (PID) and license. For more information, see Create Products.

Hardware requirements

Flash memory: The output of the SDK varies depending on the compiler. A 5 MB or more read-write partition is required.
RAM: The SDK consumes about 5 MB of the memory while running.

Software requirements

Linux or Android 4.0 or later
TCP/IP stack

Get the SDK

The SDK is delivered as a dynamic-link library (.so) or static library (.a) in C language. You need to provide your cross compiler toolchain for SDK packaging.

The output of the SDK is hosted on GitHub. You can download the latest version for development. If you have any problems, contact Technical Support.

The directory of the SDK is as follows:

├── CHANGE_LOG.md   # Changelog.
├── Makefile
├── README.md       # SDK introduction.
├── build_app.sh    # Compilation script.
├── demos           # Sample code.
├── tools           # Tools, such as for Zigbee RF test.
└── sdk
	├── include     # Header file.
	└── lib         # Library file.

Development overview

You can develop user applications on top of the SDK. To make the guide straightforward, we divide it into sections in terms of the attributes of the features.

The basic features are required to develop any gateway product. For other features, you can develop them based on your business requirements.

Product type	Features
Zigbee gateway	Basic features
Multifunctional Zigbee gateway	Basic features + Data points (DPs)
Hybrid gateway	Basic features + Data points (DPs) + Device connection
Zigbee extension gateway	Basic features + Data points (DPs) + Device connection + Zigbee device connection

The gateway supports three modes of device pairing, namely wired, wireless, and wired and wireless combo.

Since the wired and wireless drivers vary depending on platforms, the adaptation interface is intended to be implemented by you.

If you choose the wireless or wired and wireless combo SDK, you must implement hal_wifi.c. For more information, see Device pairing.

If you choose the wired or wired and wireless combo SDK, you must implement hal_wired.c. For more information, see Device pairing.

Basic features

The basic features include the required and the optional, which build the basic functionality of a gateway product. The required features provide the very basic capabilities of a gateway. The optional features are implemented based on your needs.

The required features are SDK pre-initialization, SDK initialization, local log, gateway application restart, gateway update, and gateway reset. Others are optional.

The local log is used for troubleshooting after your product is delivered to the market. Once a failure occurs, you can get the device log from the Tuya Developer Platform to locate problems remotely.

SDK initialization

Description

Request memory allocation and initialize gateway basic services.

Gateway Extension SDK

Procedure

Assign attribute values such as serial device, baud rate, and storage path to the corresponding variables of the struct ty_gw_attr_s.
Implement the get_uuid_authkey_cb callback. Assign the UUID and AuthKey obtained from the Tuya Developer Platform to parameters uuid and authkey.
Implement the get_product_key_cb callback. Assign the product ID (PID) obtained from the Tuya Developer Platform to the parameter pk.
Implement other callbacks as needed.
Assign the callback to the corresponding variable of the callback struct ty_gw_infra_cbs_s.
Call tuya_user_iot_init and take the structs ty_gw_attr_s and ty_gw_infra_cbs_s as the input parameters.

Local log

Description

For products intended for the market, the local log pulled from the Tuya Developer Platform can help you troubleshoot remotely. Pulling log data will trigger the local log callback. You need to implement the callback for getting the local log.

Procedure

Implement the gw_fetch_local_log_cb callback to compress local logs. Assign the path and name of the compressed file to the variable path. Note that the total length of the path and file name cannot exceed path_len.
Assign this callback to the variable gw_fetch_local_log_cb of the callback struct ty_gw_infra_cbs_s.

Gateway application restart

Description

The gateway application will be restarted after the Zigbee module update or gateway reset. You need to implement the callback for restarting the gateway application.

Procedure

Implement the gw_reboot_cb callback to perform a gateway application restart.
Assign this callback to the variable gw_reboot_cb of the callback struct ty_gw_infra_cbs_s.

Gateway update

Description

When users trigger a gateway update on the mobile app, the gateway will download the updates and trigger the gateway update callback after updates verification. You need to implement the callback for updating the gateway.

Procedure

Implement the gw_upgrade_cb callback to get the firmware updates from the variable img and then perform the update.
Assign this callback to the variable gw_upgrade_cb of the callback struct ty_gw_infra_cbs_s.

Gateway reset

Description

When users initiate a gateway reset on the mobile app, the gateway reset callback will be triggered. You need to implement the callback for resetting the gateway.

Procedure

Implement the gw_reset_cb callback to perform a specific action based on your needs.
Assign this callback to the variable gw_reset_cb of the callback struct ty_gw_infra_cbs_s.

Gateway activation notification

Description

When users successfully bind or unbind their gateway, the notification callback for gateway activation will be triggered. You need to implement the callback for performing a specific action based on your needs, such as controlling an LED indicator.

Procedure

Implement the gw_active_status_changed_cb callback to perform a specific action based on the value of the variable status.
Assign this callback to the variable gw_active_status_changed_cb of the callback struct ty_gw_infra_cbs_s.

Gateway connection notification

Description

When a gateway is successfully connected to or disconnected from the Tuya Developer Platform, the notification callback for the gateway connection will be triggered. You need to implement the callback for performing a specific action based on your needs, such as controlling an LED indicator.

Procedure

Implement the gw_online_status_changed_cb callback to perform a specific action based on the value of the variable online.
Assign this callback to the variable gw_online_status_changed_cb of the callback struct ty_gw_infra_cbs_s.

Project deployment mode

Description

This mode is used for gateway provisioning when the internet is not available, which can work with the Tuya construction app. The system switches to the normal mode after provisioning is completed. After users bind their gateway, the configuration that is set in the project deployment mode, such as sub-devices, scenes, and automations, will be synced.

Procedure

When the SDK is initialized, assign 1 to the variable is_engr of the struct ty_gw_attr_s. 0 indicates the normal mode and 1 indicates the project deployment mode.
Implement the gw_engineer_finished_cb callback to restart the gateway application and enter the normal mode.

We recommend you set a system flag to have the application running in the appropriate mode. Flag the first system startup as the project deployment mode. Change the flag to the normal mode when the gw_engineer_finished_cb callback is triggered.
Assign this callback to the variable gw_engineer_finished_cb of the callback struct ty_gw_infra_cbs_s.

Bind a gateway

Description

The SDK allows binding a gateway through local control. You can use a valid token to bind a gateway with the Tuya Developer Platform. For example, a device can connect to the mobile app through Bluetooth and get an activation token.

Procedure

Get the activation token.
Call tuya_user_iot_active_gw and take the token as the input parameters.

Unbind a gateway

Description

The SDK allows unbinding a gateway through local control such as button-press. This action will not clear the data of sub-devices. When the gateway is activated again, the sub-device list will be restored.

Procedure

Call tuya_user_iot_unactive_gw.

Gateway reset

Description

The SDK allows gateway reset through local control of the device such as button-press. This action will clear the data of the gateway.

Procedure

Call tuya_user_iot_reset_gw.

Join the network

Description

The SDK allows enabling or disabling a sub-device to join the network through local control such as button-press.

Procedure

Call tuya_user_iot_permit_join.

API description

tuya_user_iot_init()

int tuya_user_iot_init(ty_gw_attr_s *attr,
                       ty_gw_infra_cbs_s *cbs)

Description

Initialize the basic services of the SDK.

Parameters

Parameter name	Description
attr	See the description of the struct ty_gw_attr_s.
cbs	See the description of the interface ty_gw_infra_cbs_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_active_gw()

int tuya_user_iot_active_gw(const char *token);

Description

Bind a gateway through local control.

Parameters

Parameter name	Description
token	Use a token to bind a gateway.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_unactive_gw()

int tuya_user_iot_unactive_gw(void);

Description

Unbind a gateway through local control.

Parameters

None

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_reset_gw()

int tuya_user_iot_reset_gw(void);

Description

Reset a gateway through local control.

Parameters

None

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_permit_join()

int tuya_user_iot_permit_join(bool permit, uint32_t timeout);

Description

Enable or disable a sub-device to join the network through local control.

Parameters

Parameter name	Description
permit	0: Disable network joining. 1: Enable network joining.
timeout	A timeout for joining the network, in seconds. If a timeout occurs, the system will reject this joining attempt.

Return value

Return value	Description
0	Succeeded
All other values	Failed

get_uuid_authkey_cb()

int (*get_uuid_authkey_cb)(char *uuid,
                           int uuid_size,
                           char *authkey,
                           int authkey_size);

Description

A callback for requesting the UUID and AuthKey. You need to assign the UUID and AuthKey of the product you created on the Tuya Developer Platform to variables uuid and authkey.

Parameters

Parameter name	Description
uuid	Assign UUID to this variable.
uuid_size	The buffer size for `uuid`.
authkey	Assign the AuthKey to this variable.
authkey_size	The buffer size for `authkey`.

Return value

Return value	Description
0	Succeeded
All other values	Failed

get_product_key_cb()

int (*get_product_key_cb)(char *pk,
                          int pk_size);

Description

A callback for requesting the PID. You need to assign the PID of the product you created on the Tuya Developer Platform to the variable pk.

Parameters

Parameter name	Description
pk	Assign PID to this variable.
pk_size	The buffer size for `pk`.

Return value

Return value	Description
0	Succeeded
All other values	Failed

gw_reboot_cb()

int (*gw_reboot_cb)(void);

Description

A callback for gateway application restart.

Parameters

None

Return value

Return value	Description
0	Succeeded
All other values	Failed

gw_reset_cb()

int (*gw_reset_cb)(void);

Description

A callback for gateway reset. You can implement clearing of data of the gateway as needed.

Parameters

None

Return value

Return value	Description
0	Succeeded
All other values	Failed

gw_upgrade_cb()

int (*gw_upgrade_cb)(const char *img);

Description

A callback for updating Tuya’s application. You need to implement the update feature.

Parameters

Parameter name	Description
img	The path of the gateway firmware.

Return value

Return value	Description
0	Succeeded
All other values	Failed

gw_fetch_local_log_cb()

int (*gw_fetch_local_log_cb)(char *path,
                             int path_len);

Description

A callback for requesting the device logs from the Tuya Developer Platform.

Parameters

Parameter name	Description
path	Assign the path of the log file to this variable.
path_len	The length of the variable `file`.

Return value

Return value	Description
0	Succeeded
All other values	Failed

gw_engineer_finished_cb()

int (*gw_engineer_finished_cb)(void);

Description

A callback for completed project deployment. You need to implement application restart and switching to the normal mode.

Parameters

None

Return value

None

gw_online_status_changed_cb()

int  (*gw_online_status_changed_cb)(bool online);

Description

A callback for the change of gateway connection status. You can specify an action to be performed based on the connection status.

Parameters

Parameter name	Description
online	Gateway connection status. 0: offline. 1: online.

Return value

Return value	Description
0	Succeeded
All other values	Failed

gw_active_status_changed_cb()

int  (*gw_active_status_changed_cb)(ty_gw_status_t status);

Description

A notification callback for successful binding or unbinding a gateway. You can specify an action to be performed based on the gateway status.

Parameters

Parameter name	Description
status	Gateway status. 0: unbound. 1: bound.

Return value

Return value	Description
0	Succeeded
All other values	Failed

ty_gw_attr_s

typedef struct {
    char          *storage_path;
    char          *cache_path;
    char          *tty_device;
    int            tty_baudrate;
    char          *ssid;
    char          *password;
    char          *ver;
    int            is_engr;
    int            is_fork;
    ty_conn_mode_t wifi_mode;
    ty_log_lovel_t log_level;
} ty_gw_attr_s;

Description

Initialize the attributes of the SDK.

Member variable

Member name	Description
storage_path	The read/write path for system data and file storage. The default is the current path. Note that the path must end with a backslash. For example, if you want to specify the path as `/etc`, you must assign `/etc/` to the variable `storage_path`.
cache_path	The read/write path for system temporary file storage. The default is the `/tmp`.
tty_device	The serial device used for the the serial communication between the gateway and the Zigbee module, such as `/dev/ttyS1`.
tty_baudrate	The baud rate for serial communication. Only `115200` and `57600` are supported currently. If you set the baud rate to `115200`, hardware flow control is required. If you set the baud rate to `57600`, hardware flow control is not required.
ssid	Specify the SSID of the access point (AP) broadcast from the gateway in AP mode.
password	Specify the password of the AP broadcast from the the gateway in AP mode.
ver	The version number of the gateway application for firmware update, which must take the format of `x.x.x`.
is_engr	0: normal mode. 1: project deployment mode.
is_fork	0: Start the Zigbee service in multithreading mode. 1: Start the Zigbee service in multiprocess mode.
wifi_mode	Specify the wireless pairing mode. TY_CONN_MODE_AP_ONLY: AP mode only. TY_CONN_MODE_EZ_ONLY: Wi-Fi Easy Connect (EZ) mode only. TY_CONN_MODE_AP_FIRST: Both AP mode and EZ mode are supported. The pairing mode is started in AP mode and switched to the other mode after the gateway is unbound or reset. TY_CONN_MODE_EZ_FIRST: Both AP mode and EZ mode are supported. The pairing mode is started in EZ mode and switched to the other mode after the gateway is unbound or reset.
log_level	Set the log level. You can enable the debug mode in the development progress.

ty_gw_infra_cbs_s

typedef struct {
    int  (*get_uuid_authkey_cb)(char *uuid, int uuid_size, char *authkey, int authkey_size);
    int  (*get_product_key_cb)(char *pk, int pk_size);
    int  (*gw_upgrade_cb)(const char *img_file);
    void (*gw_reboot_cb)(void);
    void (*gw_reset_cb)(void);
    void (*gw_engineer_finished_cb)(void);
    int  (*gw_fetch_local_log_cb)(char *path, int path_len);
    int  (*gw_configure_op_mode_cb)(ty_op_mode_t mode);
    int  (*gw_active_status_changed_cb)(ty_gw_status_t status);
    int  (*gw_online_status_changed_cb)(bool online);
} ty_gw_infra_cbs_s;

Description

Callbacks related to the gateway.

Member variable

Member name	Description
get_uuid_authkey_cb	A callback for requesting the UUID and AuthKey.
get_product_key_cb	A callback for requesting the PID.
gw_upgrade_cb	A callback for updating the gateway.
gw_reboot_cb	A callback for restarting the gateway application.
gw_reset_cb	A callback for reseting the gateway.
gw_engineer_finished_cb	A callback for completed project deployment.
gw_fetch_local_log_cb	A callback for requesting local logs.
gw_active_status_changed_cb	A notification callback for the change of gateway activation status.
gw_online_status_changed_cb	A notification callback for the change of gateway connection status.

Set data point (DP)

Tuya shields specific protocols and abstracts each feature of a product into a DP. Six data types are supported, including value, Boolean, enum, string, fault, and raw. Implementing a feature is as easy as defining a variable in C.

Implement the callback dev_obj_dp_report_cb or dev_raw_dp_report_cb. Convert the received data from the input parameter of the callback to perform specific actions.
Assign the callback to the corresponding variable of the callback struct ty_dev_data_cbs_s.
Before SDK initialization, call tuya_user_iot_reg_dev_data_cb to register callbacks.

API description

tuya_user_iot_reg_dev_cmd_cb()

int tuya_user_iot_reg_dev_cmd_cb(ty_dev_cmd_cbs_s *cbs);

Description

Parameters

Parameter name	Description
cbs	See the description of the struct ty_dev_cmd_cbs_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_reg_dev_data_cb()

int tuya_user_iot_reg_dev_data_cb(const ty_dev_data_cbs_s *cbs);

Description

Parameters

Parameter name	Description
cbs	See the description of the struct ty_dev_data_cbs_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_report_obj_dp()

int tuya_user_iot_report_obj_dp(const char *dev_id,
                                ty_dp_s *dps,
                                uint32_t dps_cnt);

Description

Report the attribute value of obj DPs to the Tuya Developer Platform.

Parameters

Parameter name	Description
dev_id	If `dev_id` is `NULL`, it indicates a DP of the gateway. If `dev_id !` is `NULL`, it indicates a DP of the sub-device, and the value of `dev_id` is the MAC address of the sub-device.
dps	See the description of the struct ty_dp_s.
dps_cnt	The number of data points.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_report_raw_dp()

int tuya_user_iot_report_raw_dp(const char *dev_id,
                                uint32_t dpid,
                                uint8_t *data,
                                uint32_t len,
                                uint32_t timeout);

Description

Report the attribute value of raw DPs to the Tuya Developer Platform.

Parameters

Parameter name	Description
dev_id	If `dev_id` is `NULL`, it indicates a DP of the gateway. If `dev_id !` is `NULL`, it indicates a DP of the sub-device, and the value of `dev_id` is the MAC address of the sub-device.
dpid	The DP ID of a DP that you add or create on the Tuya Developer Platform.
data	The raw data for transparent transmission.
len	The length of raw data.
timeout	The longest duration of function blocking, in seconds.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_send_obj_cmd()

int tuya_user_iot_send_obj_cmd(const ty_obj_cmd_s *cmd);

Description

The function for local control of devices through obj DPs.

Parameters

Parameter name	Description
dp	See the description of the struct ty_obj_cmd_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_send_raw_cmd()

int tuya_user_iot_send_raw_cmd(const ty_raw_cmd_s *cmd);

Description

The function for local control of devices through raw DPs.

Parameters

Parameter name	Description
dp	See the description of the struct ty_raw_cmd_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

dev_obj_cmd_cb()

int (*dev_obj_cmd_cb)(ty_obj_cmd_s *dp);

Description

A callback for device control through obj DPs.

Parameters

Parameter name	Description
dp	See the description of the struct ty_obj_cmd_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

dev_raw_cmd_cb()

int (*dev_raw_cmd_cb)(ty_raw_cmd_s *dp);

Description

A callback for device control through raw DPs.

Parameters

Parameter name	Description
dp	See the description of the struct ty_raw_cmd_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

dev_obj_dp_report_cb()

int (*dev_obj_dp_report_cb)(const char *dev_id, const ty_dp_s *dps, uint32_t dps_cnt);

Description

A callback for reporting data of obj DPs.

Parameters

Same as the interface tuya_user_iot_report_obj_dp.

Return value

Return value	Description
0	Succeeded
All other values	Failed

dev_raw_dp_report_cb()

int (*dev_raw_dp_report_cb)(const char *dev_id, uint32_t dpid, uint8_t *data, uint32_t len);

Description

A callback for reporting data of raw DPs.

Parameters

Same as the interface tuya_user_iot_report_raw_dp.

Return value

Return value	Description
0	Succeeded
All other values	Failed

ty_dev_cmd_cbs_s

typedef struct {
	int (*dev_obj_cmd_cb)(ty_obj_cmd_s *dp);
	int (*dev_raw_cmd_cb)(ty_raw_cmd_s *dp);
} ty_dev_cmd_cbs_s;

Description

A callback for DPs.

Member variable

Member name	Description
dev_obj_cmd_cb	A callback for `obj` DPs.
dev_raw_cmd_cb	A callback for `raw` DPs.

ty_dev_data_cbs_s

typedef struct {
    int (*dev_obj_dp_report_cb)(const char *dev_id, const ty_dp_s *dps, uint32_t dps_cnt);
    int (*dev_raw_dp_report_cb)(const char *dev_id, uint32_t dpid, uint8_t *data, uint32_t len);
} ty_dev_data_cbs_s;

Description

A callback for DPs.

Member variable

Member name	Description
dev_obj_dp_report_cb	A callback for reporting data of `obj` DPs.
dev_raw_dp_report_cb	A callback for reporting data of `raw` DPs.

ty_obj_cmd_s

typedef struct {
    uint8_t      cmd_tp;
    uint8_t      dtt_tp;
    char        *cid;
    char        *mb_id;
    uint32_t     dps_cnt;
    ty_dp_s      dps[0];
} ty_obj_cmd_s;

Description

The format of control commands (JSON).

Member variable

Member name	Description
cmd_tp	Types of control commands. 0: LAN trigger. 1: MQTT trigger. 2: local schedule trigger. 3: scene trigger. 4: resending.
dtt_tp	Methods of transmission. 0: unicast. 1: broadcast. 2: multicast. 3: scene.
cid	If `cid` is `NULL`, it indicates a DP of the gateway. If `cid !` is `NULL`, it indicates a DP of the sub-device, and the value of `cid` is the MAC address of the sub-device.
mb_id	The group ID. This field is valid only when `dtt_tp` is `2`.
dps_cnt	The number of DPs that are sent, which is the length of `dps`.
dps	See the description of the struct ty_dp_s.

ty_dp_s

typedef struct {
	uint8_t dpid;
	uint8_t type;
	union {
		int       dp_value;
		uint32_t  dp_enum;
		char     *dp_str;
		int       dp_bool;
		uint32_t  dp_bitmap;
	} value;
	uint32_t time_stamp;
} ty_dp_s;

Description

The DP information.

Member variable

Member name	Description
dpid	The DP ID of a DP that you add or create on the Tuya Developer Platform.
type	The data type of a DP. For more information about the supported data types, see Custom Functions.
value	The value of a DP. The data type matches `type`.
time_stamp	The timestamp.

ty_raw_cmd_s

typedef struct {
	uint8_t   cmd_tp;
	uint8_t   dtt_tp;
	char     *cid;
	uint8_t   dpid;
	char     *mb_id;
	uint32_t  len;
	uint8_t   data[0];
} ty_raw_cmd_s;

Description

The format of control commands (raw).

Member variable

Member name	Description
cmd_tp	Types of control commands. 0: LAN trigger. 1: MQTT trigger. 2: local schedule trigger. 3: scene trigger. 4: resending.
dtt_tp	Methods of transmission. 0: unicast. 1: broadcast. 2: multicast. 3: scene.
cid	If `cid` is `NULL`, it indicates a DP of the gateway. If `cid !` is `NULL`, it indicates a DP of the sub-device, and the value of `cid` is the MAC address of the sub-device.
dpid	The DP ID of a DP that you add or create on the Tuya Developer Platform.
mb_id	The group ID. This field is valid only when `dtt_tp` is `2`.
len	The length of raw data.
data	The raw data for transparent transmission.

One-press pairing

One-press pairing applies to gateways with the wireless feature and enables a quick approach to pairing Wi-Fi devices by pressing a button on the gateway.

API description

tuya_user_iot_smconfig_init()

int tuya_user_iot_smconfig_init(const char *ifname, int (*cb)(char *ssid, \
                                                              uint32_t ssid_size, \
                                                              char *passwd, \
                                                              uint32_t passwd_size));

Description

Initialize the one-press pairing feature and request memory allocation. You need to specify the interface of 2.4 GHz wireless network and implement the callback for requesting the SSID and password.

Parameters

Parameter name	Description
ifname	The interface of 2.4 GHz wireless network.
cb	A callback for requesting the SSID and password.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_smconfig_start()

int tuya_user_iot_smconfig_start(uint32_t timeout);

Description

Enable the one-press pairing feature and call this interface to send the wireless packet.

Parameters

Parameter name	Description
timeout	A timeout, in seconds. In case of a timeout, one-press pairing will be turned off automatically.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_smconfig_stop()

int tuya_user_iot_smconfig_stop(void);

Description

Disable the one-press pairing feature and call this interface to stop sending the wireless packet.

Parameters

None

Return value

Return value	Description
0	Succeeded
All other values	Failed

Connect to sub-devices

The SDK allows you to connect sub-devices of the gateway to the Tuya Developer Platform.

Register callbacks

Description

The function for connecting to sub-devices is intended to be implemented by you, which will be called back for registering callbacks.

Procedure

Implement the required callback and specify it to the callback struct ty_misc_dev_cbs_s.
Before SDK initialization, call tuya_user_iot_reg_misc_dev_cb and take the struct ty_misc_dev_cbs_s as the input parameter.

Add devices

Description

Adding a sub-device with the mobile app will trigger the callback for adding devices. The specific service logic is intended to be implemented by you.

Procedure

Implement the misc_dev_add_cb callback to enable or disable a sub-device to join the network based on the parameter permit.
Implement the misc_dev_bind_ifm_cb callback to perform a specific action based on the binding status returned from the parameter result.
After a sub-device joins the network, the system calls tuya_user_iot_misc_dev_bind to bind this sub-device with the Tuya Developer Platform.
Before calling the registration callback tuya_user_iot_reg_misc_dev_cb, assign misc_dev_add_cb and misc_dev_bind_ifm_cb to the corresponding variable of the callback struct ty_misc_dev_cbs_s.

Heartbeat mechanism

Description

The heartbeat mechanism monitors the connection of a sub-device. Every time the gateway receives any data from the sub-device, it will refresh the heartbeat time. If the gateway does not receive any data within a predefined heartbeat timeout, it will send a heartbeat packet to the sub-device to determine if the connection is still valid.

Procedure

The sub-device sends a heartbeat at predefined intervals, or the gateway sends a heartbeat query at predefined intervals.
Implement the misc_dev_heartbeat_cb callback to read the data of a sub-device, such as the version number.
When the gateway receives data from the sub-device, call tuya_user_iot_misc_dev_fresh_hb to refresh the connection status of the sub-device.

Remove devices

Description

Removing a sub-device with the mobile app will trigger the callback for removing devices. You need to implement the callback for removing devices.

Procedure

Implement the misc_dev_del_cb callback to remove devices.
Before calling the registration callback, assign misc_dev_del_cb to the variable misc_dev_del_cb of the struct ty_misc_dev_cbs_s.

Reset devices

Description

Resetting a sub-device with the mobile app will trigger the callback for resetting devices. You need to implement the callback for restoring defaults.

Procedure

Implement the misc_dev_reset_cb callback to restore the sub-device to defaults.
Before calling the registration callback, assign misc_dev_reset_cb to the variable misc_dev_reset_cb of the struct ty_misc_dev_cbs_s.

Send commands

Description

Sub-device control with the mobile app will trigger the callback for sending control commands. You need to implement protocol conversion.

Procedure

Implement the dev_obj_cmd_cb callback to convert the DP data into the recognizable format for the sub-device and then send the control command to this sub-device.
After the sub-device executes the command, the gateway sends the current status data received from the sub-device to the Tuya Developer Platform. You need to convert this data into the DP format. Then, call tuya_user_iot_report_obj_dp to report the DP data to the platform.

Report status

Description

When the feature status of a sub-device changes, the sub-device will report the current value to the gateway. You need to implement data format conversion for syncing the status with the Tuya Developer Platform.

Procedure

After the sub-device executes the command, the gateway sends the current status data received from the sub-device to the Tuya Developer Platform. You need to convert this data into the DP format. Then, call tuya_user_iot_report_obj_dp to report the DP data to the platform.

Gateway Extension SDK

OTA firmware update

Description

When a new firmware version is available, users can trigger updates on the mobile app. The SDK will download updates and notify users of the OTA update after the firmware is verified.

Procedure

Implement the misc_dev_upgrade_cb callback to get the firmware updates from the variable img and retrieve the device to be updated by dev_id to update sub-devices.
Before calling the registration callback, assign misc_dev_upgrade_cb to the variable misc_dev_upgrade_cb of the struct ty_misc_dev_cbs_s.

Group control

Description

A device group allows users to add devices of different types to a group and control them by sending multicast commands.

Procedure

Implement the misc_dev_group_cb callback for creating and deleting groups.
Before calling the registration callback, assign misc_dev_group_cb to the variable misc_dev_group_cb of the struct ty_misc_dev_cbs_s.

Scene control

Description

Certain wireless protocols such as Zigbee support standard scene linkage without a gateway.

Procedure

Implement the misc_dev_scene_cb callback for creating, deleting, and executing scenes.
Before calling the registration callback, assign misc_dev_scene_cb to the variable misc_dev_scene_cb of the struct ty_misc_dev_cbs_s.

API description

tuya_user_iot_reg_misc_dev_cb()

int tuya_user_iot_reg_misc_dev_cb(ty_misc_dev_cbs_s *cbs);

Description

Parameters

Parameter name	Description
cbs	See the description of the struct ty_misc_dev_cbs_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_misc_dev_bind()

int tuya_user_iot_misc_dev_bind(ty_dev_tp_t tp,
                                uint32_t uddd,
                                const char *dev_id,
                                const char *pid,
                                const char *ver);

Description

Bind a sub-device with the Tuya Developer Platform.

Parameters

Parameter name	Description
tp	Protocol type
uddd	Define values to distinguish between devices of different protocols.
dev_id	The MAC address of a sub-device.
pid	The PID of a sub-device product created on the Tuya Developer Platform.
ver	The firmware version of a sub-device, used for firmware updates.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_misc_dev_unbind()

int tuya_user_iot_misc_dev_unbind(const char *dev_id);

Description

Unbind a sub-device from the Tuya Developer Platform.

Parameters

Parameter name	Description
dev_id	The MAC address of a sub-device.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_misc_dev_hb_cfg()

int tuya_user_iot_misc_dev_hb_cfg(const char *dev_id,
                                  uint32_t timeout,
                                  uint32_t max_retry,
                                  int lowpower);

Description

Configure the heartbeat of a sub-device.

Parameters

Parameter name	Description
dev_id	The MAC address of a sub-device.
timeout	Connection timeout, in seconds.
max_retry	The number of retransmissions to be carried out before declaring that a sub-device is disconnected.
lowpower	Whether a sub-device is in the low-power mode.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_misc_dev_fresh_hb()

int tuya_user_iot_misc_dev_fresh_hb(const char *dev_id);

Description

Refresh the connection status of the sub-device.

Parameters

Parameter name	Description
dev_id	The MAC address of a sub-device.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_misc_dev_ver_update()

int tuya_user_iot_misc_dev_ver_update(const char *dev_id, const char *version);

Description

Update the version number of the sub-device after firmware update.

Parameters

Parameter name	Description
dev_id	The MAC address of a sub-device.
version	Version number

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_misc_dev_desc_get()

DEV_DESC_IF_S *tuya_user_iot_misc_dev_desc_get(const char *dev_id);

Description

Get the basic information of the sub-device.

Parameters

Parameter name	Description
dev_id	The MAC address of a sub-device.

Return value

Return value	Description
DEV_DESC_IF_S *	Succeeded
NULL	Failed

tuya_user_iot_misc_dev_traversal()

DEV_DESC_IF_S *tuya_user_iot_misc_dev_traversal(void **iter);

Description

Traverse all the sub-devices.

Parameters

Parameter name	Description
iter	Iterator

Return value

Return value	Description
DEV_DESC_IF_S *	Succeeded
NULL	Failed

void *iter            = NULL;
DEV_DESC_IF_S *dev_if = NULL;

dev_if = tuya_user_iot_misc_dev_traversal(&iter);
while (dev_if) {
    // Implemented by you.
    dev_if = tuya_user_iot_misc_dev_traversal(&iter);
}

misc_dev_add_cb()

int (*misc_dev_add_cb)(bool permit, uint32_t timeout);

Description

A callback for adding a sub-device.

Parameters

Parameter name	Description
permit	Enable or disable a sub-device to join the network.
timeout	A timeout for the pairing attempt, in seconds.

Return value

Return value	Description
0	Succeeded
All other values	Failed

misc_dev_del_cb()

int (*misc_dev_del_cb)(const char *dev_id);

Description

A callback for deleting a sub-device.

Parameters

Parameter name	Description
dev_id	The MAC address of a sub-device.

Return value

Return value	Description
0	Succeeded
All other values	Failed

misc_dev_bind_ifm_cb()

int (*misc_dev_bind_ifm_cb)(const char *dev_id,
                            int result);

Description

A notification callback for the result of binding a sub-device with the Tuya Developer Platform.

Parameters

Parameter name	Description
dev_id	The MAC address of a sub-device.
result	The binding result. 0: succeeded. 1: failed.

Return value

Return value	Description
0	Succeeded
All other values	Failed

misc_dev_reset_cb()

int (*misc_dev_reset_cb)(const char *dev_id);

Description

A callback for resetting a sub-device.

Parameters

Parameter name	Description
dev_id	The MAC address of a sub-device.

Return value

Return value	Description
0	Succeeded
All other values	Failed

misc_dev_upgrade_cb()

int (*misc_dev_upgrade_cb)(const char *dev_id, const char *img);

Description

A callback for notifying the sub-device of firmware updates.

Parameters

Parameter name	Description
dev_id	The MAC address of a sub-device.
img	The path of the firmware.

Return value

Return value	Description
0	Succeeded
All other values	Failed

misc_dev_heartbeat_cb()

int (*misc_dev_heartbeat_cb)(const char *dev_id);

Description

A callback for sending a heartbeat.

Parameters

Parameter name	Description
dev_id	The MAC address of a sub-device.

Return value

Return value	Description
0	Succeeded
All other values	Failed

misc_dev_group_cb()

void (*misc_dev_group_cb)(ty_group_action_t action,
                          const char *dev_id,
                          const char *grp_id);

Description

A callback for operations on a sub-device group.

Parameters

Parameter name	Description
action	Create or delete a group.
dev_id	The MAC address of a sub-device.
grp_id	Group ID.

Return value

Return value	Description
0	Succeeded
All other values	Failed

misc_dev_scene_cb()

void (*misc_dev_scene_cb)(ty_group_action_t action,
                          const char *dev_id,
                          const char *grp_id,
                          const char *sce_id);

Description

A callback for operations on a scene for the sub-device.

Parameters

Parameter name	Description
action	Create, delete, or execute a scene.
dev_id	The MAC address of a sub-device.
grp_id	The group ID.
sce_id	The scene ID.

Return value

Return value	Description
0	Succeeded
All other values	Failed

ty_misc_dev_cbs_s

typedef struct {
    void (*misc_dev_add_cb)(bool permit, uint32_t timeout);
    void (*misc_dev_del_cb)(const char *dev_id);
    void (*misc_dev_bind_ifm_cb)(const char *dev_id, int result);
    void (*misc_dev_upgrade_cb)(const char *dev_id, const char *img);
    void (*misc_dev_reset_cb)(const char *dev_id);
    void (*misc_dev_heartbeat_cb)(const char *dev_id);
    void (*misc_dev_group_cb)(ty_group_action_t action, const char *dev_id, const char *grp_id);
    void (*misc_dev_scene_cb)(ty_scene_action_t action, const char *dev_id, const char *grp_id, const char *sce_id);
} ty_misc_dev_cbs_s;

Description

Callbacks for sub-device management.

Member variable

Member name	Description
misc_dev_add_cb	A callback for adding a sub-device.
misc_dev_del_cb	A callback for deleting a sub-device.
misc_dev_bind_ifm_cb	A notification callback for binding a sub-device.
misc_dev_upgrade_cb	A notification callback for firmware updates.
misc_dev_reset_cb	A callback for resetting a sub-device.
misc_dev_heartbeat_cb	A callback for sending a heartbeat.
misc_dev_group_cb	A callback for operations on a sub-device group.
misc_dev_scene_cb	A callback for operations on a scene for the sub-device.

Connect to Zigbee devices

The SDK enables the third-party system to connect non-PBT Zigbee devices to the Tuya Developer Platform as sub-devices of the gateway.

This section describes how to connect to third-party Zigbee devices and use the APIs.

Device management

Description

The function for connecting to Zigbee sub-devices is intended to be implemented by you. You can register an allowlist to notify the SDK that the listed device is processed by a third party, so that the SDK will transmit the raw data to the application. If the allowlist is empty, it indicates all the devices are processed by a third party.

A callback for allowlist registration and device management.

Procedure

Implement the required callback and specify it to the callback struct TY_Z3_DEV_CBS_S.
Specify the allowlist to the struct TY_Z3_DEVLIST_S.
Before SDK initialization, call tuya_user_iot_zig_mgr_register and take the structs TY_Z3_DEVLIST_S and TY_Z3_DEV_CBS_S as the input parameters.

Join the network

Description

When an allowlisted Zigbee 3.0 sub-device is connected to the Zigbee network of the gateway, the system will trigger a callback for joining the network. This callback is intended to be implemented by you.

Procedure

Implement the join callback to parse the basic information of the sub-device and call tuya_user_iot_misc_dev_bind to bind this device with the Tuya Developer Platform.
Implement the report callback to read the attributes response and convert the Zigbee cluster library (ZCL) commands into Tuya’s DP data. Call tuya_user_iot_report_obj_dp to sync the sub-device status with the Tuya Developer Platform and call tuya_user_iot_misc_dev_hb_fresh to refresh sub-device connection status.
Assign join and report to the variables of the callback struct TY_Z3_DEV_CBS_S, and call tuya_user_iot_zig_mgr_register for registration.
Implement the misc_dev_bind_ifm_cb callback to read the attribute value of the sub-device and call tuya_user_iot_misc_dev_hb_cfg to configure the heartbeat.
Assign misc_dev_bind_ifm_cb to the variable of the callback struct ty_misc_dev_cbs_s.

Leave the network

Description

When an allowlisted Zigbee 3.0 sub-device leaves the Zigbee network of the gateway, the system will trigger a callback for leaving the network. You can implement specific actions in this callback.

Procedure

Implement the leave callback to call tuya_user_iot_misc_dev_unbind for unbinding this device from the Tuya Developer Platform.
Before calling the registration callback, assign this callback to the variable leave of the callback struct TY_Z3_DEV_CBS_S.

Report status

Description

When an allowlisted sub-device reports data, the system will trigger the callback for status reporting. You need to parse the ZCL data frame in this callback.

Procedure

Implement the report callback to convert the ZCL data frame into Tuya’s DP data. Call tuya_user_iot_report_obj_dp to sync with the Tuya Developer Platform and call tuya_user_iot_misc_dev_hb_fresh to refresh sub-device connection status.
Before calling the registration callback, assign this callback to the variable report of the callback struct TY_Z3_DEV_CBS_S.

Send commands

Description

Sub-device control with the mobile app will trigger the callback for sending control commands. You need to convert Tuya’s DP into the ZCL data frame in this callback.

Procedure

Implement the dev_obj_cmd_cb callback to convert the DP data into the ZCL data frame. Call tuya_user_iot_zig_send to send the control command to the sub-device.
Implement the report callback to convert the ZCL data frame into Tuya’s DP data. Call tuya_user_iot_report_obj_dp to sync with the Tuya Developer Platform and call tuya_user_iot_misc_dev_hb_fresh to refresh sub-device connection status.

Sync status

Description

The startup of the Zigbee module will trigger a notification callback to read the attribute values of all connected sub-devices.

Procedure

Implement the notify callback to read the attribute values of all joined sub-devices.
Implement the report callback to read the attributes response and convert the attributes into Tuya’s DP data. Call tuya_user_iot_report_obj_dp to sync with the Tuya Developer Platform and call tuya_user_iot_misc_dev_hb_fresh to refresh sub-device connection status.
Before calling the registration callback, assign notify to the variable notify of the callback struct TY_Z3_DEV_CBS_S.

OTA firmware update

Description

When a new firmware version is available, users can trigger updates on the mobile app. The SDK will download updates and notify users of the OTA update after the firmware is verified.

Procedure

Implement the misc_dev_upgrade_cb callback get firmware updates from the variable img and retrieve the device to be updated by dev_id. Call tuya_user_iot_zig_upgrade to update sub-devices.
Before calling the registration callback, assign misc_dev_upgrade_cb to the variable misc_dev_upgrade_cb of the struct ty_misc_dev_cbs_s.

Remove sub-devices

Description

Removing a sub-device with the mobile app will trigger the callback for removing devices. You need to implement the callback for removing sub-devices.

Procedure

Implement the misc_dev_del_cb callback to call tuya_user_iot_zig_del for removing a sub-device.
Before calling the registration callback, assign misc_dev_del_cb to the variable misc_dev_del_cb of the struct ty_misc_dev_cbs_s.

API description

tuya_user_iot_zig_mgr_register()

OPERATE_RET tuya_user_iot_zig_mgr_register(TY_Z3_DEVLIST_S *devlist,
                                           TY_Z3_DEV_CBS_S *cbs);

Description

Parameters

Parameter name	Description
devlist	The allowlist of Zigbee sub-devices.
cbs	See the description of the struct TY_Z3_DEV_CBS_S.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_zig_send()

OPERATE_RET tuya_user_iot_zig_send(TY_Z3_APS_FRAME_S *frame);

Description

Send ZCL data frame to the Zigbee sub-device.

Parameters

Parameter name	Description
frame	See the description of the struct ty_z3_aps_frame_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_zig_del()

OPERATE_RET tuya_user_iot_zig_del(CONST CHAR_T *dev_id);

Description

Remove a Zigbee sub-device through local control.

Parameters

Parameter name	Description
id	The MAC address of a sub-device.

Return value

Return value	Description
0	Succeeded
All other values	Failed

tuya_user_iot_zig_upgrade()

OPERATE_RET tuya_user_iot_zig_upgrade(CONST CHAR_T *dev_id, CONST CHAR_T *img);

Description

Update a Zigbee sub-device through local control.

Parameters

Parameter name	Description
id	The MAC address of a sub-device.
img	The path of the firmware of the Zigbee sub-device.

Return value

Return value	Description
0	Succeeded
All other values	Failed

join()

VOID (*join)(TY_Z3_DESC_S *dev);

Description

A callback for the Zigbee sub-device joining the network, which is intended to be implemented by you.

Parameters

Parameter name	Description
desc	See the description of the struct ty_z3_desc_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

leave()

VOID (*join)(TY_Z3_DESC_S *dev);

Description

A callback for the Zigbee sub-device leaving the network, which is intended to be implemented by you.

Parameters

Parameter name	Description
id	The MAC address of a sub-device.

Return value

Return value	Description
0	Succeeded
All other values	Failed

report()

VOID (*report)(TY_Z3_APS_FRAME_S *frame);

Description

A callback for the Zigbee sub-device reporting status, which is intended to be implemented by you.

Parameters

Parameter name	Description
frame	See the description of the struct ty_z3_aps_frame_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

notify()

int (*notify)(void);

Description

A notification callback for the startup of the Zigbee module.

Parameters

None

Return value

Return value	Description
0	Succeeded
All other values	Failed

TY_Z3_DEV_CBS_S

typedef struct {
    VOID (*join)(TY_Z3_DESC_S *dev);
    VOID (*leave)(CONST CHAR_T *dev_id);
    VOID (*report)(TY_Z3_APS_FRAME_S *frame);
    VOID (*notify)(VOID);
    VOID (*upgrade_end)(CONST CHAR_T *dev_id, INT_T rc, UCHAR_T version);
} TY_Z3_DEV_CBS_S;

Description

A callback for Zigbee sub-device management.

Member variable

Member name	Description
notify	A notification callback for the completed startup of the Zigbee module.
join	A callback for Zigbee sub-device joining the network, which is intended to be implemented by you.
leave	A callback for the Zigbee sub-device leaving the network, which is intended to be implemented by you.
report	A callback for the Zigbee sub-device reporting status, which is intended to be implemented by you.
upgrade_end	A notification callback for the result of updating Zigbee sub-devices, which is intended to be implemented by you.

TY_Z3_DESC_S

typedef struct {
    CHAR_T     id[Z3_DEV_ID_LEN+1];
    UINT16_T   profile_id[MAX_EP_NUM];
    UINT16_T   device_id[MAX_EP_NUM];
    UINT16_T   cluster_id[MAX_EP_NUM][MAX_CLUSTER_NUM];
    UINT16_T   endpoint[MAX_EP_NUM];
    UCHAR_T    ep_num; // endpoints count
    UCHAR_T    uc_num; // clusters count
    UINT16_T   node_id;
    CHAR_T     manu_name[MANU_NAME_LEN+1];
    CHAR_T     model_id[MODEL_ID_LEN+1];
    CHAR_T     rejoin_flag;
    CHAR_T     power_source;
    UCHAR_T    version;
} TY_Z3_DESC_S;

Description

The basic information of a Zigbee sub-device.

Member variable

Member name	Description
id	The MAC address of a sub-device.
profile_id	The Zigbee profile ID.
device_id	The Zigbee device ID.
cluster_id	The Zigbee cluster ID.
endpoint	The Zigbee endpoint.
ep_num	The number of endpoints.
uc_num	The number of clusters.
node_id	The short address of a sub-device.
manu_name	The manufacturer name.
model_id	The device model.
rejoin_flag	The flag of rejoining the network.
power_source	The power source, indicating a electrical or ELV (extra-low voltage) device.
version	The application version.

TY_Z3_APS_FRAME_S

typedef struct {
    CHAR_T     id[Z3_DEV_ID_LEN+1];
    UINT16_T   node_id;
    UINT16_T   profile_id;
    UINT16_T   cluster_id;
    UCHAR_T    src_endpoint;
    UCHAR_T    dst_endpoint;
    UINT16_T   group_id;
    UCHAR_T    cmd_type;          // ZCL command type. 0x00: global command, 0x01: command is specific to a cluster.
    UCHAR_T    cmd_id;            // ZCL command ID
    UCHAR_T    frame_type;        // 0: unicast, 1: multicast, 2: broadcast
    UINT16_T   manufacturer_code;
    CHAR_T     disable_ack;
    UINT16_T   msg_length;
    UCHAR_T   *message;
} TY_Z3_APS_FRAME_S;

Description

The ZCL data frame encapsulated by Tuya.

Member variable

Member name	Description
id	The MAC address of a sub-device.
node_id	The short address of a sub-device.
profile_id	The Zigbee profile ID.
cluster_id	The Zigbee cluster ID.
src_endpoint	The source endpoint.
dst_endpoint	The destination endpoint.
group_id	The group ID, used for multicast.
cmd_type	The type of a ZCL command. `0` indicates global. `1` indicates a specific cluster.
cmd_id	The ZCL command ID.
frame_type	The transmission type. `0`: indicates unicast. `1`: indicates multicast. `2`: indicates broadcast.
disable_ack	Enable or disable response. `1`: disable response. `0`: enable response.
msg_length	The length of ZCL payload.
message	The ZCL payload.

Security features

Register callbacks

Description

You need to implement the function for controlling security devices in terms of arming and disarming, siren sound, and indicator, which will be called back for registering callbacks.

Procedure

Implement the required callback and specify it to the callback struct ty_home_security_cbs_s.
Before SDK initialization, call tuya_user_iot_reg_home_security_cb and take the struct ty_home_security_cbs_s as the input parameter.

API description

tuya_user_iot_reg_home_security_cb()

int tuya_user_iot_reg_home_security_cb(ty_home_security_cbs_s *cbs);

Description

Parameters

Parameter name	Description
frame	See the description of the struct ty_z3_aps_frame_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

home_security_alarm_cb()

void (*home_security_alarm_cb)(void);

Description

A callback for emitting an alarm. You need to implement control of alarm sound or indicator.

Parameters

None

Return value

None

home_security_alarm_cancel_cb()

void (*home_security_alarm_cancel_cb)(void);

Description

A callback for canceling an alarm. You need to implement control of alarm sound or indicator.

Parameters

None

Return value

None

home_security_disarmed_cb()

void (*home_security_disarmed_cb)(void);

Description

A callback for disarming. You need to implement control of alarm sound or indicator.

Parameters

None

Return value

None

home_security_away_armed_cb()

void (*home_security_away_armed_cb)(void);

Description

A callback for arming away. You need to implement control of alarm sound or indicator.

Parameters

None

Return value

None

home_security_stay_armed_cb()

void (*home_security_stay_armed_cb)(void);

Description

A callback for arming stay. You need to implement control of alarm sound or indicator.

Parameters

None

Return value

None

home_security_arm_ignore_cb()

void (*home_security_arm_ignore_cb)(void);

Description

A callback for ignoring arming. You need to implement control of alarm sound or indicator.

Parameters

None

Return value

None

home_security_arm_countdown_cb()

void (*home_security_arm_countdown_cb)(uint32_t time);

Description

A callback for arming delay. You need to implement control of alarm sound or indicator.

Parameters

Parameter name	Description
time	The duration of the countdown timer.

Return value

None

home_security_alarm_countdown_cb()

void (*home_security_alarm_countdown_cb)(uint32_t time);

Description

A callback for alarm delay. You need to implement control of alarm sound or indicator.

Parameters

Parameter name	Description
time	The duration of the countdown timer.

Return value

None

home_security_door_opened_cb()

void (*home_security_door_opened_cb)(uint32_t time);

Description

A callback for contact sensor opening. You need to implement control of alarm sound or indicator.

Parameters

None

Return value

None

home_security_alarm_dev_cb()

void (*home_security_alarm_dev_cb)(char *dev);

Description

A callback for device alarm to get which device is alarming.

Parameters

Parameter name	Description
dev	The device name.

Return value

None

ty_home_security_cbs_s

typedef struct {
    void (*home_security_alarm_cb)(void);
    void (*home_security_alarm_cancel_cb)(void);
    void (*home_security_disarmed_cb)(void);
    void (*home_security_away_armed_cb)(void);
    void (*home_security_stay_armed_cb)(void);
    void (*home_security_arm_ignore_cb)(void);
    void (*home_security_arm_countdown_cb)(uint32_t time);
    void (*home_security_alarm_countdown_cb)(uint32_t time);
    void (*home_security_door_opened_cb)(void);
    void (*home_security_alarm_dev_cb)(char *dev);
} ty_home_security_cbs_s;

Description

Callbacks for controlling security devices.

Member variable

Member name	Description
home_security_alarm_cb	A callback for emitting an alarm.
home_security_alarm_cancel_cb	A callback for canceling an alarm.
home_security_disarmed_cb	A callback for disarming.
home_security_away_armed_cb	A callback for arming away.
home_security_stay_armed_cb	A callback for arming stay.
home_security_arm_ignore_cb	A callback for ignoring arming.
home_security_arm_countdown_cb	A callback for arming delay.
home_security_alarm_countdown_cb	A callback for alarm delay.
home_security_door_opened_cb	A callback for contact sensor opening.
home_security_alarm_dev_cb	A callback for device alarm.

Device pairing

The SDK provides complete framework functions for implementing device pairing guides. You only need to implement the required functions. This section describes how to use functions to implement device pairing services. Implementation of interfaces in the hal_wired.c or hal_wifi.c is recommended.

If you require both the AP mode and EZ mode, you must specify the variable wifi_mode in SDK initialization. This way, after the gateway is unbound or reset, the pairing mode can be switched automatically.

Assume that you specify wifi_mode as TY_CONN_MODE_AP_FIRST, the pairing mode is started in AP mode and switched to the other mode after the gateway is unbound or reset. When the gateway is started after the next unbinding or resetting, the pairing mode is switched to AP mode.

You can use an LED to indicate the pairing mode. Set LED control with hal_wifi_ap_start and hal_wifi_set_sniffer for AP mode and EZ mode respectively.

Wired mode

Description

The SDK has implemented the service logic for pairing in a wired network. You only need to implement the required interfaces in the hardware abstraction layer (HAL).

Procedure

Implement hal_wired_get_ip to get the IP address of the wired Ethernet.
Implement hal_wired_get_status to determine whether the Ethernet port is connected.

EZ mode

Description

In EZ mode (Wi-Fi Easy Connect), the mobile app broadcasts the SSID and password of the Wi-Fi network. The wireless interface listens for and captures the packet. Then, this interface decrypts the wireless network packet and initiates a connection.

Procedure

Before gateway initialization, set the variable wifi_mode of ty_gw_attr_s to TY_CONN_MODE_EZ.
Implement hal_wifi_get_work_mode to get the current Wi-Fi mode.
Implement hal_wifi_set_cur_channel to set the Wi-Fi channel based on the variable channel.
Implement hal_wifi_scan_all_ap to specify the scanned Wi-Fi information to the struct ap_scan_info_s.
Implement hal_wifi_set_sniffer to sniff packets and send the captured data to the SDK using the parameter cb.
Implement hal_wifi_set_work_mode to set the Wi-Fi mode based on the parameter mode.
Implement hal_wifi_get_cur_channel to get the current Wi-Fi channel.
Implement hal_wifi_connect_station to connect to the internet with the parameters ssid and passwd.
Implement hal_wifi_get_station_conn_stat to get the status of station mode and assign the result to the parameter stat.

AP mode

Description

When the gateway turns on AP, the mobile app connects to this AP and broadcasts the SSID and password of the Wi-Fi network to be configured over the user datagram protocol (UDP). The gateway initiates a connection after receiving the UDP packet and decrypting the SSID and password.

Procedure

Before gateway initialization, set the variable wifi_mode of ty_gw_attr_s to TY_CONN_MODE_AP. The SSID and password of the AP can be specified to variables ssid and password.
Implement hal_wifi_get_work_mode to get the current Wi-Fi mode.
Implement hal_wifi_ap_start and turn on the AP mode based on the parameters of the struct ap_cfg_info_s.
Implement hal_wifi_set_work_mode to set the Wi-Fi mode based on the parameter mode.
Implement hal_wifi_connect_station to connect to the internet with the parameters ssid and passwd.
Implement hal_wifi_get_station_conn_stat to get the status of station mode and assign the result to the parameter stat.
Implement hal_wifi_ap_stop to disable the AP of the gateway.

API description

hal_wifi_scan_all_ap()

int hal_wifi_scan_all_ap(ap_scan_info_s **aps,
                         uint32_t *num)

Description

Scan all APs in the current environment.

Parameters

Parameter name	Description
aps	See the description of the struct ap_scan_info_s.
num	The number of the APs in the current environment.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_scan_assigned_ap()

int hal_wifi_scan_assigned_ap(char *ssid,
                              ap_scan_info_s **aps)

Description

Scan the specified AP in the current environment.

Parameters

Parameter name	Description
ssid	Specify the SSID of an AP.
aps	See the description of the struct ap_scan_info_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_release_ap()

int hal_wifi_release_ap(ap_scan_info_s *ap)

Description

Release the information of the scanned AP that is stored in the stack.

Parameters

Parameter name	Description
ap	See the description of the struct ap_scan_info_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_set_cur_channel()

int hal_wifi_set_cur_channel(uint8_t channel)

Description

Set the channel of the Wi-Fi network.

Parameters

Parameter name	Description
channel	The channel value.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_get_cur_channel()

int hal_wifi_get_cur_channel(uint8_t *channel)

Description

Get the current channel of the Wi-Fi network.

Parameters

Parameter name	Description
channel	The channel value.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_set_sniffer()

int hal_wifi_set_sniffer(int enable,
                         sniffer_callback cb)

Description

Design the promiscuous mode.

Parameters

Parameter name	Description
enable	Enable or disable the sniffer mode.
cb	A callback used to send the captured IEEE 802.11 data frame to the SDK.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_get_ip()

int hal_wifi_get_ip(wifi_type_t type,
                    ip_info_s *ip)

Description

Get the IP information of the Wi-Fi interface.

Parameters

Parameter name	Description
type	The Wi-Fi connection mode. 0: station mode. 1: AP mode.
ip	See the description of the struct ip_info_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_get_mac()

int hal_wifi_get_mac(wifi_type_t type,
                     mac_info_t *mac)

Description

Get the MAC address of the Wi-Fi interface.

Parameters

Parameter name	Description
type	The Wi-Fi connection mode. 0: station mode. 1: AP mode.
mac	See the description of the struct mac_info_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_set_work_mode()

int hal_wifi_set_work_mode(wifi_work_mode_t mode)

Description

Set the mode of the Wi-Fi network.

Parameters

Parameter name	Description
mode	The working mode. 0: low power mode. 1: promiscuous mode. 2: station mode. 3: AP mode. 4: station and AP mode.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_get_work_mode()

int hal_wifi_get_work_mode(wifi_work_mode_t *mode)

Description

Get the mode of the Wi-Fi network.

Parameters

Parameter name	Description
mode	The working mode. 0: low power mode. 1: promiscuous mode. 2: station mode. 3: AP mode. 4: station and AP mode.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_connect_station()

int hal_wifi_connect_station(char *ssid,
                             char *passwd)

Description

Connect to the upstream AP.

Parameters

Parameter name	Description
ssid	The SSID of the upstream AP.
passwd	The password of the upstream AP.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_disconnect_station()

int hal_wifi_disconnect_station(void)

Description

Disconnect from the upstream AP.

Parameters

None

Return value

Parameter name	Description
0	Succeeded
All other values	Failed

hal_wifi_get_station_rssi()

int hal_wifi_get_station_rssi(char *rssi)

Description

Get the signal strength of the connection to the upstream AP in station mode.

Parameters

Parameter name	Description
rssi	The signal strength.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_get_station_conn_stat()

int hal_wifi_get_station_conn_stat(station_conn_stat_t *stat)

Description

Get the status of the connection to the upstream AP in station mode.

Parameters

Parameter name	Description
stat	Status value. STAT_IDLE: no connection. STAT_CONNECTING: connecting. STAT_PASSWD_WRONG: incorrect password. STAT_NO_AP_FOUND: AP not found. STAT_CONN_FAIL: connection failed. STAT_CONN_SUCCESS: connection succeeded. STAT_GOT_IP: connection succeeded and IP address is assigned.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_ap_start()

int hal_wifi_ap_start(ap_cfg_info_s *cfg)

Description

Enable AP mode.

Parameters

Parameter name	Description
cfg	See the description of the struct ap_cfg_info_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_ap_stop()

int hal_wifi_ap_stop(void)

Description

Disable AP mode.

Parameters

None

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_set_country_code()

int hal_wifi_set_country_code(char *code)

Description

Set the country code of the Wi-Fi network.

Parameters

Parameter name	Description
code	The country code.

Return value

Return value	Description
0	Succeeded
All other values	Failed

ap_scan_info_s

typedef struct {
	uint8_t channel;
	char rssi;
	uint8_t bssid[BSSID_MAX_LEN];
	uint8_t ssid[SSID_MAX_LEN+1];
	uint8_t s_len;
} ap_scan_info_s;

Description

The scanned AP information.

Member variable

Member name	Description
channel	The channel of the scanned specified AP.
rssi	The signal strength of the scanned specified AP.
bssid	The MAC address of the scanned specified AP.
ssid	The SSID of the scanned specified AP.
s_len	The length of the SSID of the scanned specified AP.

ip_info_s

typedef struct {
	char ip[ADDR_MAX_LEN];
	char mask[ADDR_MAX_LEN];
	char gateway[ADDR_MAX_LEN];
} ip_info_s;

Description

The IP information of the network interface.

Member variable

Member name	Description
ip	The IP address.
mask	The subnet mask.
gateway	The IP address of the gateway.

mac_info_s

typedef struct {
	uint8_t mac[MAC_MAX_LEN];
} mac_info_s;

Description

The MAC address of the network interface.

Member variable

Member name	Description
mac	The MAC addresses.

ap_cfg_info_s

typedef struct {
	uint8_t ssid[SSID_MAX_LEN+1];
	uint8_t s_len;
	uint8_t key[KEY_MAX_LEN+1];
	uint8_t p_len;
	uint8_t channel;
	ap_encryption_type_t type;
	uint8_t hidden;
	uint8_t max_conn;
	uint16_t ms_interval;
} ap_cfg_info_s;

Description

The configuration for the AP mode of the gateway.

Member variable

Member name	Description
ssid	SSID
s_len	The length of the SSID.
password	The password.
p_len	The length of the password.
channel	The current channel.
encryption	The encryption method.
hidden	Specify whether to hide the SSID.
max_conn	The maximum number of devices for the AP.
ms_interval	The beacon interval.

Description

Get the signal strength of the connection to the upstream AP in station mode.

Parameters

Parameter name	Description
rssi	The signal strength.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_get_station_conn_stat()

int hal_wifi_get_station_conn_stat(station_conn_stat_t *stat)

Description

Get the status of the connection to the upstream AP in station mode.

Parameters

Parameter name	Description
stat	Status value. STAT_IDLE: no connection. STAT_CONNECTING: connecting. STAT_PASSWD_WRONG: incorrect password. STAT_NO_AP_FOUND: AP not found. STAT_CONN_FAIL: connection failed. STAT_CONN_SUCCESS: connection succeeded. STAT_GOT_IP: connection succeeded and IP address is assigned.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_ap_start()

int hal_wifi_ap_start(ap_cfg_info_s *cfg)

Description

Enable AP mode.

Parameters

Parameter name	Description
cfg	See the description of the struct ap_cfg_info_s.

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_ap_stop()

int hal_wifi_ap_stop(void)

Description

Disable AP mode.

Parameters

None

Return value

Return value	Description
0	Succeeded
All other values	Failed

hal_wifi_set_country_code()

int hal_wifi_set_country_code(char *code)

Description

Set the country code of the Wi-Fi network.

Parameters

Parameter name	Description
code	The country code.

Return value

Return value	Description
0	Succeeded
All other values	Failed

ap_scan_info_s

typedef struct {
	uint8_t channel;
	char rssi;
	uint8_t bssid[BSSID_MAX_LEN];
	uint8_t ssid[SSID_MAX_LEN+1];
	uint8_t s_len;
} ap_scan_info_s;

Description

The scanned AP information.

Member variable

Member name	Description
channel	The channel of the scanned specified AP.
rssi	The signal strength of the scanned specified AP.
bssid	The MAC address of the scanned specified AP.
ssid	The SSID of the scanned specified AP.
s_len	The length of the SSID of the scanned specified AP.

ip_info_s

typedef struct {
	char ip[ADDR_MAX_LEN];
	char mask[ADDR_MAX_LEN];
	char gateway[ADDR_MAX_LEN];
} ip_info_s;

Description

The IP information of the network interface.

Member variable

Member name	Description
ip	The IP address.
mask	The subnet mask.
gateway	The IP address of the gateway.

mac_info_s

typedef struct {
	uint8_t mac[MAC_MAX_LEN];
} mac_info_s;

Description

The MAC address of the network interface.

Member variable

Member name	Description
mac	The MAC addresses.

ap_cfg_info_s

typedef struct {
	uint8_t ssid[SSID_MAX_LEN+1];
	uint8_t s_len;
	uint8_t key[KEY_MAX_LEN+1];
	uint8_t p_len;
	uint8_t channel;
	ap_encryption_type_t type;
	uint8_t hidden;
	uint8_t max_conn;
	uint16_t ms_interval;
} ap_cfg_info_s;

Description

The configuration for the AP mode of the gateway.

Member variable

Member name	Description
ssid	SSID
s_len	The length of the SSID.
password	The password.
p_len	The length of the password.
channel	The current channel.
encryption	The encryption method.
hidden	Specify whether to hide the SSID.
max_conn	The maximum number of devices for the AP.
ms_interval	The beacon interval.