All Products
Search
Document Center

IoT Platform:GW & Sub-Device

Last Updated:Sep 03, 2023

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

Background information

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.

Procedure

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.

Result

    IOT_RegisterCallback(ITE_CONNECT_SUCC, user_connected_event_handler);
    IOT_RegisterCallback(ITE_DISCONNECTED, user_disconnected_event_handler);
    IOT_RegisterCallback(ITE_PROPERTY_SET, user_property_set_event_handler);
    IOT_RegisterCallback (ITE_REPORT_REPLY, user_report_reply_event_handler );
    IOT_RegisterCallback(ITE_TIMESTAMP_REPLY, user_timestamp_reply_event_handler);
    IOT_RegisterCallback(ITE_INITIALIZE_COMPLETED, user_initialized);
    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.

/* Choose Logon Server */
    int domain_type = IOTX_CLOUD_REGION_SHANGHAI;
    IOT_Ioctl(IOTX_IOCTL_SET_DOMAIN, (void *)&domain_type);

    /* Choose Logon Method */
    int dynamic_register = 0;
    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.

    iotx_linkkit_dev_meta_info_t master_meta_info;

    memset(&master_meta_info, 0, sizeof(iotx_linkkit_dev_meta_info_t));
    memcpy(master_meta_info.product_key, PRODUCT_KEY, strlen(PRODUCT_KEY));
    memcpy(master_meta_info.product_secret, PRODUCT_SECRET, strlen(PRODUCT_SECRET));
    memcpy(master_meta_info.device_name, DEVICE_NAME, strlen(DEVICE_NAME));
    memcpy(master_meta_info.device_secret, DEVICE_SECRET, strlen(DEVICE_SECRET));

    /* Create Primary Device Resources */
    user_example_ctx->master_devid = IOT_Linkkit_Open(IOTX_LINKKIT_DEV_TYPE_MASTER, &master_meta_info);
    if (user_example_ctx->master_devid < 0) {
        EXAMPLE_TRACE("IOT_Linkkit_Open Failed\n");
        return -1;
    }
  1. Similarly, establish a connection with the cloud by using the IOTX_LINKKIT_DEV_TYPE_MASTER parameter to call IOT_Linkkit_Connect.

/* Start Connect Aliyun Server */
    res = IOT_Linkkit_Connect(user_example_ctx->master_devid);
    if (res < 0) {
        EXAMPLE_TRACE("IOT_Linkkit_Connect Failed\n");
        return -1;
    }
  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.

int example_add_subdev(iotx_linkkit_dev_meta_info_t *meta_info)
{
    int res = 0, devid = -1;
    devid = IOT_Linkkit_Open(IOTX_LINKKIT_DEV_TYPE_SLAVE, meta_info);
    if (devid == FAIL_RETURN) {
        EXAMPLE_TRACE("subdev open Failed\n");
        return FAIL_RETURN;
    }
    EXAMPLE_TRACE("subdev open susseed, devid = %d\n", devid);

    res = IOT_Linkkit_Connect(devid);
    if (res == FAIL_RETURN) {
        EXAMPLE_TRACE("subdev connect Failed\n");
        return res;
    }
    EXAMPLE_TRACE("subdev connect success: devid = %d\n", devid);

    res = IOT_Linkkit_Report(devid, ITM_MSG_LOGIN, NULL, 0);
    if (res == FAIL_RETURN) {
        EXAMPLE_TRACE("subdev login Failed\n");
        return res;
    }
    EXAMPLE_TRACE("subdev login success: devid = %d\n", devid);
    return res;
}

Related sub-device management

  • Sub-device logout: You can complete a sub-device logout by calling IOT_Linkkit_Report with the ITM_MSG_LOGOUT option. The logout function for sub-devices is mainly used to inform the cloud console that the device is offline.

res = IOT_Linkkit_Report(devid, ITM_MSG_LOGOUT, NULL, 0);
    if (res == FAIL_RETURN) {
        EXAMPLE_TRACE("subdev logout Failed\n");
        return res;
    }
    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_REQUEST 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.

Note:

  1. The gateway device must support multiple threads and use a separate thread to run IOT_Linkkit_Yield

void *user_dispatch_yield(void *args)
    {
        while (1) {
            IOT_Linkkit_Yield(USER_EXAMPLE_YIELD_TIMEOUT_MS);
        }

        return NULL;
    }

    res = HAL_ThreadCreate(&g_user_dispatch_thread, user_dispatch_yield, NULL, NULL, NULL);
    if (res < 0) {
        EXAMPLE_TRACE("HAL_ThreadCreate Failed\n");
        IOT_Linkkit_Close(user_example_ctx->master_devid);
        return -1;
    }
  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.
int user_permit_join_event_handler(const char *product_key, const int time)
{
    user_example_ctx_t *user_example_ctx = user_example_get_ctx();

    EXAMPLE_TRACE("Product Key: %s, Time: %d", product_key, time);

    user_example_ctx->permit_join = 1;

    return 0;
}
  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.