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 |
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);
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);
Initialize a primary device resource by using the
IOTX_LINKKIT_DEV_TYPE_MASTER
parameter to callIOT_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;
}
Similarly, establish a connection with the cloud by using the
IOTX_LINKKIT_DEV_TYPE_MASTER
parameter to callIOT_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;
}
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.
Initialize a sub-device resource by calling
IOT_Linkkit_Open
with theIOTX_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.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.Complete the online connection process for sub-devices by calling the
IOT_Linkkit_Report
with theITM_MSG_LOGIN
parameter.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 theITM_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 callIOT_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 theITE_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 informationCall the
IOT_Linkkit_TriggerEvent
to actively report the eventReceive pass-through data from the cloud in the
ITE_RAWDATA_ARRIVED
event callbackReceive service requests (synchronous and asynchronous services) in the
ITE_SERVICE_REQUEST
event callbackHandle the property settings from the cloud in the
ITE_PROPERTY_SET
event callbackHandle 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:
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;
}
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 theproductKey
of sub-devices and thetimeoutSec
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;
}
Add
FEATURE_DEVICE_MODEL_GATEWAY=y
to themake.setting
file in the primary directory of the SDK and run themake
command to compile the gateway routine.