IoT Platform provides Link SDK that encapsulates the communication protocol between devices and IoT Platform. You can use Link SDK to develop devices. However, Link SDK may not meet your business requirements in complex embedded environments. In this case, you must encapsulate the Alink protocol to achieve communication between devices and IoT Platform.

IoT Platform provides Link SDK for multiple programming languages. For more information, see What is Link SDK?

The Alink protocol is a data exchange standard for IoT development. Devices and IoT Platform exchange data in the JSON format. This protocol achieves efficient communication between devices and IoT Platform.

The following sections describe how to connect devices with IoT Platform and transfer data by using the Alink protocol.

Connect devices to IoT Platform

A device can connect to IoT Platform as a directly connected device or a sub-device. You must perform the following steps: authenticate the device, connect the device to IoT Platform, and then submit data to IoT Platform.

A directly connected device can connect to IoT Platform by using one of the following methods:

  • If you use unique-certificate-per-device authentication, burn a device certificate on the device, connect the device to IoT Platform, and then submit data to IoT Platform. A device certificate includes a ProductKey, a DeviceName, and a DeviceSecret.
  • If you use unique-certificate-per-product authentication (dynamic registration), burn a product certificate on the device, connect the device to IoT Platform, and then submit data to IoT Platform. A product certificate includes a ProductKey and a ProductSecret.

A sub-device must connect to IoT Platform through a gateway by using one of the following methods:

  • If you use unique-certificate-per-device authentication, burn a device certificate on the sub-device. The sub-device sends the certificate information to the gateway. The gateway adds a topological relationship. Then, the sub-device can submit data to IoT Platform by using the communication channel of the gateway.
  • If you use dynamic registration, burn a ProductKey on the sub-device. The sub-device sends the ProductKey and DeviceName to the gateway. IoT Platform verifies the DeviceName and then sends a DeviceSecret to the sub-device. The sub-device sends the obtained ProductKey, DeviceName, and DeviceSecret to the gateway. The gateway adds a topological relationship. Then, the sub-device can submit data to IoT Platform by using the communication channel of the gateway.
Submit device data

Submit device properties or events

  • Pass-through data Pass-through data
    1. A device submits pass-through data to IoT Platform by using the topic that is used to send pass-through data.
    2. IoT Platform parses the submitted data by using a data parsing script. The rawDataToProtocol method in the script is called to convert the submitted data to Alink JSON data.
    3. IoT Platform processes the Alink JSON data.
      Note If you configure a data forwarding rule, IoT Platform forwards data to the specified destination cloud service.
      • The rules engine forwards the data that has been parsed by using the data parsing script.
      • To obtain device properties, specify /sys/{productKey}/{deviceName}/thing/event/property/post as the topic when you write an SQL statement for the rule.
      • To obtain device events, specify /sys/{productKey}/{deviceName}/thing/event/{tsl.event.identifier}/post as the topic when you write an SQL statement for the rule.
    4. IoT Platform calls the protocolToRawData method in the data parsing script to convert the result data to the data format of the device.
    5. IoT Platform pushes the converted data to the device.
    6. You can query submitted property data by using the QueryDevicePropertyData operation and query submitted event data by using the QueryDeviceEventData operation.
  • Alink JSON data Alink data
    1. A device submits Alink JSON data to IoT Platform by using the topic that is used to send Alink JSON data.
    2. IoT Platform processes the submitted data.
      Note If you configure a data forwarding rule, the rules engine of IoT Platform forwards data to the specified destination cloud service.
      • To obtain device properties, specify /sys/{productKey}/{deviceName}/thing/event/property/post as the topic when you write an SQL statement for the rule.
      • To obtain device events, specify /sys/{productKey}/{deviceName}/thing/event/{tsl.event.identifier}/post as the topic when you write an SQL statement for the rule.
    3. IoT Platform returns a response to the device.
    4. You can query submitted property data by using the QueryDevicePropertyData operation and query submitted event data by using the QueryDeviceEventData operation.

Call device services or set device properties

  • Asynchronously call device services or set device properties
    Transmit Alink data
    1. Set a device property or call a device service.
      Note
      • Call the SetDeviceProperty operation to asynchronously set a device property.
      • Call the InvokeThingService operation to asynchronously call a device service. When you define the service, you must specify the asynchronous calling method for the service.
    2. IoT Platform verifies the parameters.
    3. IoT Platform asynchronously sends a message to the device and returns a response. If the call is successful, the message ID is included in the response.
      Note For pass-through data, IoT Platform calls the protocolToRawData method in the data parsing script to convert the data before IoT Platform sends the data to the device.
    4. The device processes the received data.
      Note
      • If you send pass-through data, use the topic for pass-through data.
      • If you send Alink JSON data, use the topic for Alink JSON data.
    5. After the device processes the data, the device returns a response to IoT Platform.
    6. After IoT Platform receives the response, you can perform the following operations:
      • If pass-through data is received, IoT Platform calls the rawDataToProtocol method in the data parsing script to convert the data.
      • If you configure a data forwarding rule, IoT Platform forwards the data to the specified destination topic or cloud service.
        • When you write an SQL statement for the rule, specify /sys/{productKey}/{deviceName}/thing/downlink/reply/message as the topic to obtain the response.
        • For pass-through data, the rules engine forwards the data that has been parsed by using the data parsing script.
  • Synchronously call device services
    Transmit Alink data
    1. Call the InvokeThingService operation to synchronously call a device service. When you define the service, you must specify the synchronous calling method for the service.
    2. IoT Platform verifies the parameters.
    3. IoT Platform synchronously uses the RRPC topic to send data to the device and return a response.
      Note For pass-through data, IoT Platform calls the protocolToRawData method in the data parsing script to convert the data before IoT Platform sends the data to the device.
    4. After the device processes the data, the device returns a response to IoT Platform. If IoT Platform does not receive a response within the timeout period, IoT Platform sends an error message to the caller.
    5. IoT Platform returns the response to the caller.
      Note For pass-through data, IoT Platform calls the rawDataToProtocol method in the data parsing script to convert the data before IoT Platform sends the response to the caller.

Add topological relationships

Transmit Alink data
  1. After a sub-device is connected to a gateway, the gateway uses a topic to add a topological relationship between the gateway and the sub-device. IoT Platform processes the request and returns a response.
  2. The gateway can also use a topic to delete the topological relationship.
  3. You can call the GetThingTopo operation to query the topological relationship between the gateway and sub-device.
  4. If third parties are required to add a topological relationship, perform the following steps:
    1. The gateway submits the information about the detected sub-device to IoT Platform.
    2. If you configure a data forwarding rule, the rules engine of IoT Platform forwards the received information to the destination cloud service.
    3. After you obtain the sub-device information from the cloud service, you can determine whether to add a topological relationship. To add a topological relationship, call the NotifyAddThingTopo operation to send a request to IoT Platform.
    4. After IoT Platform receives the NotifyAddThingTopo request, IoT Platform sends a notification to the gateway by using a topic.
    5. The gateway receives the request and then add a topological relationship.
Note
  • The gateway can use the /sys/{productKey}/{deviceName}/thing/topo/add topic to add a topological relationship.
  • The gateway can use the /sys/{productKey}/{deviceName}/thing/topo/delete topic to delete the topological relationship.
  • The gateway can use the /sys/{productKey}/{deviceName}/thing/topo/get topic to query the topological relationship.
  • The gateway can use the /sys/{productKey}/{deviceName}/thing/list/found topic to submit the information about the detected sub-device.
  • IoT Platform can use the /sys/{productKey}/{deviceName}/thing/topo/add/notify topic to notify the gateway to add a topological relationship.