Integrate the SDK on a WAN module that supports TCP

Perform operations on the Alibaba Cloud IoT Platform

To verify that the integrated SDK runs correctly on the module, you must connect a test device to IoT Platform. To do this, create a product on IoT Platform and then create a device instance for that product to obtain the device credentials.

1. Log on to the IoT Platform console. Module vendors must register an Alibaba Cloud account. Registration is free.

2. After you log on to the IoT Platform console, create a product. For more information, see Create a product. You can obtain the ProductKey and ProductSecret from the product page.

3. Add a test device. For more information, see Create a device. You can obtain the DeviceName and DeviceSecret from the device page.

SDK integration development process

Module vendors must follow this development process to integrate the SDK on a module.

SDK configuration and code extraction

Add the SDK code files to your compilation environment

Copy the Link SDK code files from the output directory to your project directory. Then, modify your compilation environment or development tool to integrate these code files.

Implement HAL porting functions

The Link SDK is designed to run on different operating systems or even on MCUs that do not have an operating system. Therefore, system-related operations are defined as Hardware Abstraction Layer (HAL) functions that you must implement. Additionally, because communication modules use different operating systems, TCP-related operations are also defined as HAL functions that you must implement.

All HAL functions are located in the output/eng/wrappers/wrapper.c file.

Port the related HAL functions

System-related HAL

Implement product features using the example

Module vendors can refer to eng/examples/mqtt_example.c in the output folder for feature debugging. Device manufacturers can copy this file to their product project, modify it, and use it.

This example connects the device to Alibaba Cloud, subscribes to a specified topic, and sends data to that topic. This means that messages reported by the device are sent back to the device by IoT Platform. The following figure shows an overview of the process:

Note: On IoT Platform, you must change the default permission for this topic from 'Subscribe' to 'Publish and Subscribe', as shown in the following figure:

Starting from the main() function, which is the program entry point, the first step is to call the HAL functions provided by the module to obtain the product's identity information:

int main(int argc, char *argv[])
{
    void                   *pclient = NULL;
    int                     res = 0;
    int                     loop_cnt = 0;
    iotx_mqtt_param_t       mqtt_params;

    HAL_GetProductKey(DEMO_PRODUCT_KEY);
    HAL_GetDeviceName(DEMO_DEVICE_NAME);
    HAL_GetDeviceSecret(DEMO_DEVICE_SECRET);

    EXAMPLE_TRACE("MQTT example");
            

Note:

• The three HAL_GetXXX functions retrieve the device credentials. Module vendors can fill in the credential information of the test device in the corresponding HAL functions.

Next, specify the MQTT connection parameters. You can modify the parameters as needed:

/* Initialize MQTT parameter */
    memset(&mqtt_params, 0x0, sizeof(mqtt_params));
    mqtt_params.port = sign_mqtt.port;
    mqtt_params.host = sign_mqtt.hostname;
    mqtt_params.client_id = sign_mqtt.clientid;
    mqtt_params.username = sign_mqtt.username;
    mqtt_params.password = sign_mqtt.password;
    mqtt_params.request_timeout_ms = 2000;
    mqtt_params.clean_session = 0;
    mqtt_params.keepalive_interval_ms = 60000;
    mqtt_params.read_buf_size = 1024;
    mqtt_params.write_buf_size = 1024;
    mqtt_params.handle_event.h_fp = example_event_handle;
    mqtt_params.handle_event.pcontext = NULL;
    pclient = IOT_MQTT_Construct(&mqtt_params);
            

Call the IOT_MQTT_Construct() API to trigger the SDK to connect to IoT Platform. If the return value is not NULL, the connection is successful. Then, call example_subscribe to subscribe to data from a specified topic:

res = example_subscribe(pclient);
            

Note:

• Device manufacturers must subscribe to their desired topics and register the corresponding handler functions based on their product design.

• In the example code, the first orange circle highlights the code that specifies the topic format: /$ProductKey/$DeviceName. This topic is generated by default when you create a product on IoT Platform.

• The second orange circle highlights the code that generates the topic content.

• The third box in the figure shows how to subscribe to a specified topic and the handler function for data received from that topic.

The following section demonstrates the MQTT publish feature, which reports business messages to IoT Platform:

 while (1) {
        if (0 == loop_cnt % 20) {
            example_publish(pclient);
        }

        IOT_MQTT_Yield(pclient, 200);

        loop_cnt += 1;
    }
            

Note:

• The preceding code periodically sends a fixed message to IoT Platform. Device manufacturers should upload data to IoT Platform only when necessary, based on their product features.

• You can delete the example_publish(pclient) statement in the main function to avoid periodically sending invalid data to IoT Platform.

• IOT_MQTT_Yield allows the SDK to receive data from the MQTT broker. The waiting time is 200 ms. If you have many messages or high real-time requirements, you can reduce this value.

In the figure, the first box shows the content of the message to be sent. The second box shows the call to the SDK-provided API to send the message to the specified topic.

Upload the module vendor code and module model

If module vendors want to submit their modules to Alibaba Cloud IoT for certification, they must report their vendor code and module model. This allows IoT Platform to collect statistics on the number of devices connected through a specific module vendor and a specific module model from that vendor.

Before you integrate the SDK, contact us to obtain the module vendor code and module model. Send a message using the following template to contact us.

Subject: Device Connection Link SDK Product - Module/Chip Model Application

After the module establishes a connection with IoT Platform, copy and call the following function to report the information. The 'pid' parameter is the module vendor code, and 'mid' is the model code:

#define PID_STRING_LEN_MAX          32  /* Maximum length of the PID string */
#define MID_STRING_LEN_MAX          32  /* Maximum length of the MID string */


int example_report_pid_mid(void *pclient, const char *product_key, const char *device_name, const char *pid, const char *mid)
{
    int res = 0;
    iotx_mqtt_topic_info_t topic_msg;

    const char topic_frag1[] = "/sys/";
    const char topic_frag2[] = "/thing/deviceinfo/update";
    char topic[sizeof(topic_frag1) + sizeof(topic_frag2) + IOTX_PRODUCT_KEY_LEN + IOTX_DEVICE_NAME_LEN] = {0};

    const char payload_frag1[] = "{\"id\":\"0\",\"version\":\"1.0\",\"params\":[{\"attrKey\":\"SYS_MODULE_ID\",\"attrValue\":\"";
    const char payload_frag2[] = "\",\"domain\":\"SYSTEM\"},{\"attrKey\":\"SYS_PARTNER_ID\",\"attrValue\":\"";
    const char payload_frag3[] = "\",\"domain\":\"SYSTEM\"}],\"method\": \"thing.deviceinfo.update\"}";
    char payload[sizeof(payload_frag1) + sizeof(payload_frag2) + sizeof(payload_frag3) + PID_STRING_LEN_MAX + MID_STRING_LEN_MAX] = {0};

    if (strlen(pid) > PID_STRING_LEN_MAX || strlen(mid) > MID_STRING_LEN_MAX) {
        return -1;
    }

    /* Assemble the MQTT topic string */
    memcpy(topic, topic_frag1, strlen(topic_frag1));
    memcpy(topic + strlen(topic), product_key, strlen(product_key));
    memcpy(topic + strlen(topic), "/", 1);
    memcpy(topic + strlen(topic), device_name, strlen(device_name));
    memcpy(topic + strlen(topic), topic_frag2, strlen(topic_frag2));

    /* Assemble the MQTT payload string. The payload contains the PID and MID strings. */
    memcpy(payload, payload_frag1, strlen(payload_frag1));
    memcpy(payload + strlen(payload), mid, strlen(mid));
    memcpy(payload + strlen(payload), payload_frag2, strlen(payload_frag2));
    memcpy(payload + strlen(payload), pid, strlen(pid));
    memcpy(payload + strlen(payload), payload_frag3, strlen(payload_frag3));

    topic_msg.qos = IOTX_MQTT_QOS0;
    topic_msg.retain = 0;
    topic_msg.dup = 0;
    topic_msg.payload = (void *)payload;
    topic_msg.payload_len = strlen(payload);

    /* Use the MQTT publish API to send the message that contains the PID and MID information. */
    res = IOT_MQTT_Publish(pclient, topic, &topic_msg);
    if (res < 0) {
        return -1;
    }

    return 0;
}

            

Feature debugging

The following screenshots are based on the mqtt_example.c example.