All Products
Document Center

GW & Sub-Device

Last Updated: May 13, 2020

This section usesexample/linkkit_gateway/linkkit_example_gateway.c as an example to explain the programming method of gateway products and sub devices.


Terms Description
Gateway A gateway can connect directly to the IoT Platform and provide sub-device management features. Sub-devices can only communicate with the IoT Platform through a gateway.
Sub-device A sub-device is essentially a device. Sub-devices cannot connect directly to the IoT Platform and need to connect through a gateway.
Device ID Device ID, which is also called the device handle, is used to identify a specific device in the gateway scenario. It is returned when calling IOT_Linkkit_Open.
Topological relationships The association between a sub-device and a gateway is a topological relationship. When the sub-device establishes a topological relationship with the gateway, you can reuse the physical channels of the gateway for data communications.
Dynamic registration of sub-devices When registering, sub-devices only need to report the productKey and deviceName to the gateway. The gateway (instead of the sub-device) initiates cloud identity authentication and the deviceSecret is returned to the gateway from the cloud for subsequent online operations.

Establishing a connection between gateway and cloud

The process for connecting the gateway is exactly the same as connecting a device.

  1. Call IOT_RegisterCallback to register the necessary callback-processing functions, such as connection event handling, device-to-cloud initialization processing, and property-setting event handling. The sub-device and the gateway share a set of callback handler functions and they distinguish devices by their DeviceID.
  1. IOT_RegisterCallback(ITE_CONNECT_SUCC, user_connected_event_handler);
  2. IOT_RegisterCallback(ITE_DISCONNECTED, user_disconnected_event_handler);
  3. IOT_RegisterCallback(ITE_PROPERTY_SET, user_property_set_event_handler);
  4. IOT_RegisterCallback (ITE_REPORT_REPLY, user_report_reply_event_handler );
  5. IOT_RegisterCallback(ITE_TIMESTAMP_REPLY, user_timestamp_reply_event_handler);
  6. IOT_RegisterCallback(ITE_INITIALIZE_COMPLETED, user_initialized);
  7. IOT_RegisterCallback(ITE_PERMIT_JOIN, user_permit_join_event_handler);
  1. Call IOT_Ioctl to make the necessary configurations, such as selecting a server site and choosing whether to use unique-certificate-per-product authentication.
  1. /* Choose Logon Server */
  2. int domain_type = IOTX_CLOUD_REGION_SHANGHAI;
  3. IOT_Ioctl(IOTX_IOCTL_SET_DOMAIN, (void *)&domain_type);
  4. /* Choose Logon Method */
  5. int dynamic_register = 0;
  6. IOT_Ioctl(IOTX_IOCTL_SET_DYNAMIC_REGISTER, (void *)&dynamic_register);
  1. Initialize a primary device resource by using the IOTX_LINKKIT_DEV_TYPE_MASTER parameter to call IOT_Linkkit_Open.
  1. iotx_linkkit_dev_meta_info_t master_meta_info;
  2. memset(&master_meta_info, 0, sizeof(iotx_linkkit_dev_meta_info_t));
  3. memcpy(master_meta_info.product_key, PRODUCT_KEY, strlen(PRODUCT_KEY));
  4. memcpy(master_meta_info.product_secret, PRODUCT_SECRET, strlen(PRODUCT_SECRET));
  5. memcpy(master_meta_info.device_name, DEVICE_NAME, strlen(DEVICE_NAME));
  6. memcpy(master_meta_info.device_secret, DEVICE_SECRET, strlen(DEVICE_SECRET));
  7. /* Create Primary Device Resources */
  8. user_example_ctx->master_devid = IOT_Linkkit_Open(IOTX_LINKKIT_DEV_TYPE_MASTER, &master_meta_info);
  9. if (user_example_ctx->master_devid < 0) {
  10. EXAMPLE_TRACE("IOT_Linkkit_Open Failed\n");
  11. return -1;
  12. }
  1. Similarly, establish a connection with the cloud by using the IOTX_LINKKIT_DEV_TYPE_MASTER parameter to call IOT_Linkkit_Connect.
  1. /* Start Connect Aliyun Server */
  2. res = IOT_Linkkit_Connect(user_example_ctx->master_devid);
  3. if (res < 0) {
  4. EXAMPLE_TRACE("IOT_Linkkit_Connect Failed\n");
  5. return -1;
  6. }
  1. After the gateway-to-cloud initialization is complete and can be confirmed in the ITE_INITIALIZE_COMPLETED event handler, you can proceed to the next step of adding sub-devices.

Add a sub-device

Adding a sub-device is a three-step process.

  1. Initialize a sub-device resource by calling IOT_Linkkit_Open with the IOTX_LINKKIT_DEV_TYPE_SLAVE parameter.

    If you need to use dynamic registration, simply set the device_secret of the device information parameter as an empty string. To enable dynamic registration, you need to pre-register the DeviceName of the sub-device in the IoT console.

  2. Calling IOT_Linkkit_Connect connects the sub-device to the cloud. This is a synchronous interface, it can automatically complete sub-device registration and the addition of topological relationships.
  3. Complete the online connection process for sub-devices by calling the IOT_Linkkit_Report with the ITM_MSG_LOGIN parameter.
  4. After the initialization of the online connection process of sub-devices to cloud is complete and can be confirmed in the ITE_INITIALIZE_COMPLETED event handler function, you can start the data interaction between sub-devices and cloud.
  1. int example_add_subdev(iotx_linkkit_dev_meta_info_t *meta_info)
  2. {
  3. int res = 0, devid = -1;
  4. devid = IOT_Linkkit_Open(IOTX_LINKKIT_DEV_TYPE_SLAVE, meta_info);
  5. if (devid == FAIL_RETURN) {
  6. EXAMPLE_TRACE("subdev open Failed\n");
  7. return FAIL_RETURN;
  8. }
  9. EXAMPLE_TRACE("subdev open susseed, devid = %d\n", devid);
  10. res = IOT_Linkkit_Connect(devid);
  11. if (res == FAIL_RETURN) {
  12. EXAMPLE_TRACE("subdev connect Failed\n");
  13. return res;
  14. }
  15. EXAMPLE_TRACE("subdev connect success: devid = %d\n", devid);
  16. res = IOT_Linkkit_Report(devid, ITM_MSG_LOGIN, NULL, 0);
  17. if (res == FAIL_RETURN) {
  18. EXAMPLE_TRACE("subdev login Failed\n");
  19. return res;
  20. }
  21. EXAMPLE_TRACE("subdev login success: devid = %d\n", devid);
  22. return res;
  23. }
  • Sub-device logout: You can complete a sub-device logout by calling IOT_Linkkit_Reportwith the ITM_MSG_LOGOUT option. The logout function for sub-devices is mainly used to inform the cloud console that the device is offline.
  1. res = IOT_Linkkit_Report(devid, ITM_MSG_LOGOUT, NULL, 0);
  2. if (res == FAIL_RETURN) {
  3. EXAMPLE_TRACE("subdev logout Failed\n");
  4. return res;
  5. }
  6. EXAMPLE_TRACE("subdev logout success: devid = %d\n", devid);
  • Get a list of sub-devices: By using the ITM_MSG_QUERY_TOPOLIST option to call IOT_Linkkit_Query, the gateway can obtain information about all the sub-devices with which it has a topological relationship. List information will be returned in the ITE_TOPOLIST_REPLY event callback.

  • Logout sub-devices: To prevent accidental deletion of sub-devices due to incorrect user calls, the SDK does not provide APIs to logout sub-devices.

  • Delete sub-device topological relationships: The SDK does not provide APIs to delete topological relationships.

Data interaction of sub-devices

The data interaction between sub-devices and the cloud is exactly the same as that of individual devices. For example:

  • Call the IOT_Linkkit_Report to report properties and pass-through data, to update the device label information, and to delete the device label information

  • Call the IOT_Linkkit_TriggerEvent to actively report the event

  • Receive pass-through data from the cloud in the ITE_RAWDATA_ARRIVED event callback

  • Receive service requests (synchronous and asynchronous services) in the ITE_SERVICE_REQUST event callback

  • Handle the property settings from the cloud in the ITE_PROPERTY_SET event callback

  • Handle the property acquisition from local communications in the ITE_PROPERTY_GET event callback

For more information, please refer to the “Programming in Thing Specification Language “ section.


  1. The gateway device must support multiple threads and use a separate thread to run IOT_Linkkit_Yield
  1. void *user_dispatch_yield(void *args)
  2. {
  3. while (1) {
  5. }
  6. return NULL;
  7. }
  8. res = HAL_ThreadCreate(&g_user_dispatch_thread, user_dispatch_yield, NULL, NULL, NULL);
  9. if (res < 0) {
  10. EXAMPLE_TRACE("HAL_ThreadCreate Failed\n");
  11. IOT_Linkkit_Close(user_example_ctx->master_devid);
  12. return -1;
  13. }
  1. When connected to the Open Platform for Smart Living, you can only add sub-devices when you receive an ITE_PERMIT_JOIN event from the cloud.

    When users attempt to add sub-devices by scanning a code with the app, the app will send the PermitJoin command to the cloud, and the cloud will forward the command to the gateway. The ITE_PERMIT_JOIN event releases the productKey of sub-devices and the timeoutSec time window (normally 60 seconds) to enable sub-device access. Manufacturers can perform discovery and binding for sub-devices within this time window, add sub-devices, and report to the cloud. After a successful report, you can view the added sub-devices in the app interface. This feature allows effective controls over the addition of sub-devices. Sub-devices can only be added within the time window.

  1. int user_permit_join_event_handler(const char *product_key, const int time)
  2. {
  3. user_example_ctx_t *user_example_ctx = user_example_get_ctx();
  4. EXAMPLE_TRACE("Product Key: %s, Time: %d", product_key, time);
  5. user_example_ctx->permit_join = 1;
  6. return 0;
  7. }
  1. Add FEATURE_DEVICE_MODEL_GATEWAY=y to the make.setting file in the primary directory of the SDK and run the make command to compile the gateway routine.

Gateway related APIs

Function name Description
IOT_Linkkit_Open Creates local resources. Before performing network packet interaction, you must first call this API to get a handle for the session.
IOT_Linkkit_Connect Establishes communication between the primary device/gateway and the cloud. Registers the sub-device (if needed) with the cloud, and adds the topological relationship between the primary device and the sub-device.
IOT_Linkkit_Yield If the SDK occupies a separate thread, then this function is empty; otherwise, the SDK uses CPU to receive network packets and distribute packets to the user’s callback functions.
IOT_Linkkit_Close If the session handle in the input parameter is the primary device/gateway, it closes the network connection and releases all resources occupied by the SDK for this session.
IOT_Linkkit_Report Sends upstream packets that do not require cloud service data distribution to the cloud, including property values, device labels, pass-through data in binary format, and sub-device management.
IOT_Linkkit_Query Sends query packets that require cloud service data distribution to the cloud, including OTA status query, OTA firmware download, sub-device topology query, and NTP time query.
IOT_Linkkit_TriggerEvent Sends event packets to the cloud, such as error codes and exception alarms.
Other generic function names Description
IOT_Ioctl Sets the configurable options for the SDK runtime.
IOT_RegisterCallback Registers event callback functions.