Aliyun IoT .NET Core Client | CZGL.AliIoTClient: 1. Connect to Aliyun IoT

Document Directory:

 1) Alibaba Cloud IoT

Alibaba Cloud IoT supports multiple communication protocols. The CZGL.AliIoTClient uses the MQTT communication protocol with the communication library being M2MQTT.
There are two data transmission methods for Alibaba Cloud IoT: transparent transmission and Alink json. The two methods only differ in the four Types of Topic: property read/write, event reporting, and service calls. Other communication connections, general Topics, responses, etc. are identical. It is recommended to use the Alink json method for uploading and downloading data.

The CZGL.AliIoTClient supports both Alink json and transparent transmission, with two client classes in the SDK:

The two classes are largely consistent, with differences only in the data transmission method related to property events services. Therefore, the following explanation will primarily refer to AliIoTClientJson.

2) Connect to Alibaba Cloud IoT

2.1) Create Client

When creating the client class, a DeviceOptions object needs to be passed in. You must copy the device's key and other information from the Alibaba Cloud IoT console and fill it into the DeviceOptions.

Example:

            AliIoTClientJson client = new AliIoTClientJson(new DeviceOptions
            {
                ProductKey = "a1xrkGSkb5R",
                DeviceName = "mire",
                DeviceSecret = "CqGMkOBDiKJfrOWp1evLZC2O6fsMtEXw",
                RegionId = "cn-shanghai"
            });

2.2) Set the Topics to Subscribe

Before connecting the client, it is necessary to set the general Topics to be subscribed and configure whether to receive commands for property settings, service calls, and responses.

General topic

Set the topics to subscribe:

string[] topics = new string[] { ... , ... , ...  };

It is required to fill in the complete length of the Topic URI, which can be viewed in the console. For example, "/a1xrkGSkb5R/dockertest/user/update/error".

If you prefer not to complicate matters, you can use:

string[] topics = new string[] { client.CombineHeadTopic("get") };

You only need to enter the content after /user/, and AliIoTClientJson.CombineHeadTopic() will generate the full Topic address for you. For example, to subscribe to "/a1xrkGSkb5R/dockertest/user/update/error":

string[] topics = new string[] { client.CombineHeadTopic("update/error") };

In addition to general Topics, there are various data uploads from the device, receiving server responses, server setting device properties, service calls to device services, etc., which will be introduced in subsequent chapters.

3) Set Default Events

What would you like the program to do when a message is received? Write the corresponding methods and bind them to the delegate events. When the conditions are met, these methods will be triggered.
In this chapter, we will use the default delegate methods preset in CZGL.AliIoTClient. Subsequent chapters will detail how to customize these methods.

Use default events:

            client.UseDefaultEventHandler();

4) Client Connection

After configuring the settings before the connection, now connect to Alibaba Cloud IoT.

In CZGL.AliIoTClient, there are three methods concerning connection:

5) Example

Create a new product in the Alibaba Cloud IoT console, then create a new device under this product without adding other functionalities. Record the new device's key and other information.
In Visual Studio, create a new .NET Core console application, find CZGL.AliIoTClient in Nuget and add it. The console code is as follows:

            // Create Client
            client = new AliIoTClientJson(new DeviceOptions
            {
                ProductKey = "a1xrkGSkb5R",
                DeviceName = "mire",
                DeviceSecret = "CqGMkOBDiKJfrOWp1evLZC2O6fsMtEXw",
                RegionId = "cn-shanghai"
            });
        <span class="hljs-comment">// Set the Topic to subscribe, run the receiving content Topic
        <span class="hljs-keyword">string[] topics = <span class="hljs-keyword">new <span class="hljs-keyword">string[] { client.CombineHeadTopic(<span class="hljs-string">"get") };
        <span class="hljs-comment">// Use default events
        client.UseDefaultEventHandler();
        <span class="hljs-comment">// Connect to server
        client.ConnectIoT(topics,null,<span class="hljs-number">60);
        <span class="hljs-built_in">Console.ReadKey();


Open the Alibaba Cloud IoT console, refresh the device list, and you will see the device online.


6） Distributing Data
A newly created product has several default Topics. We do not need to make any other modifications; for the time being, we can use the default Topics for demonstration.
Run the previously written console program and do not close it.
Open the Aliyun IoT console, find the corresponding device, and locate the Topic list for the device to find the .../user/get Topic, for example: /a1xrkGSkb5R/dockertest/user/get.
Click on Publish Message, then enter the content to be sent, and finally check the console to see if the distributed message has been received.
Since the default event method in CZGL.AliIoTClient is used, in addition to the message content, some attribute information of this Topic message will also be output.

7） Uploading Data
In the device's Topic list, there is a .../user/update Topic, for example, /a1xrkGSkb5R/dockertest/user/update. This Topic allows the client to upload data. Below will explain how the client uploads data to the Aliyun IoT server.
Methods for uploading to a standard Topic:
I. Uploading byte
public int CommonToServer(string topicName, byte[] content)

Summary:
This method uploads data in the form of byte[]. Note the base of byte[].
Parameters: topicName: The complete name of the Topic, which can be obtained using the CombineHeadTopic() method.
content: The message content.
Return result: Message ID.
II. Standard String
public int CommonToServer(string topicName, string content)

Summary: Standard way to push Topic to the server, directly uploading a string.
Return result: Message ID.
III. Other Upload Methods
There are also several other methods, which will be explained together.
public int CommonToServer(string topicName, string content, 
                          [System.Text.Encoding encoding = null])

Note: Uploads data to a specified Topic, specifying the encoding format of the string. Aliyun IoT defaults to using UTF8.
CZGL.AliIoTClient also defaults to using UTF8 for data encoding, allowing for custom uploading of string encoding. Generally, there is no need to change it, otherwise, Chinese strings may become garbled.
public int CommonToServerBase64(string topicName, string content)

Note: After passing in a string, it will first be Base64 encoded and then uploaded.
public int CommonToServerBase64(string topicName, 
                                string content, 
                                [System.Text.Encoding encoding = null])

Note: After passing in a string, specify the encoding of the string, and then perform Base64 encoding before uploading.

8） Creating Topic
You can open a certain product in the Aliyun IoT console, create one or more new Topics in the product, and set this Topic with subscribe/publish permissions. Then modify the program to see if it can normally upload and distribute data.