All Products
Search

This Product

    IoT Platform:Alink protocol

    Document Center

    IoT Platform:Alink protocol

    Last Updated:Apr 25, 2023

    IoT Platform provides Link SDKs that contain the communication protocols between devices and IoT Platform. You can use Link SDKs to develop devices. However, Link SDKs may not meet your business requirements in complex embedded environments. In this case, you can establish connections between devices and IoT Platform over the Alink protocol.

    Overview

    The Alink protocol is a data exchange standard for IoT development that allows devices and IoT Platform to efficiently exchange data in the JSON format.

    IoT Platform provides language-specific Link SDKs that you can use to develop devices. For more information about the features of each Link SDK, see Link SDKs.

    The following table describes the features of the Alink protocol for IoT Platform.

    Table 1. Features

    Feature

    Message format

    Device connection

    Messaging

    Device management

    Monitoring and O&M

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

    Connect devices to IoT Platform

    Devices that you can connect to IoT Platform are categorized into directly connected devices and sub-devices. If you want to connect a device to IoT Platform, 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 be connected 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 be connected to IoT Platform over 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

      No.

      Description

      1

      A device submits pass-through data to IoT Platform by using the topic that is used to send pass-through data. For more information about topics, see Device properties, events, and services.

      1.1

      IoT Platform uses a data parsing script to parse the data that is submitted from a device. The rawDataToProtocol function in the script is called to convert the submitted data into Alink JSON data.

      For more information, see What is data parsing?

      1.2

      IoT Platform processes the Alink JSON data.

      If the rules engine is configured, IoT Platform forwards data to a destination such as a topic or a cloud service based on a specified forwarding rule.

      Important

      • The data forwarded by the rules engine is parsed by using the data parsing script.

      • When you configure a data forwarding rule, you must specify the following topics for TSL data reporting as data sources: /${productKey}/${deviceName}/thing/event/property/post and /${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post. For more information, see Configure a data forwarding rule or Create a data source.

      1.3

      IoT Platform calls the protocolToRawData function in the data parsing script to convert the result data into a format that can be identified by the device.

      1.4

      IoT Platform sends parsed data to the device.

      2

      You can query submitted property data by calling the QueryDevicePropertyData operation and query submitted historical event data by calling the QueryDeviceEventData operation.

    • Alink JSON data

      Alink data

      No.

      Description

      1

      A device submits Alink JSON data to IoT Platform by using the topic that is used to send pass-through data. For more information, see Device properties, events, and services.

      1.1

      IoT Platform processes the submitted data.

      If the rules engine is configured, IoT Platform forwards data to a destination such as a topic or a cloud service based on a specified forwarding rule.

      Important

      When you configure a data forwarding rule, you must specify the following topics for TSL data reporting as data sources: /${productKey}/${deviceName}/thing/event/property/post and /${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post. For more information, see Configure a data forwarding rule or Create a data source.

      1.2

      IoT Platform returns a response to the device.

      2

      You can query submitted property data by calling the QueryDevicePropertyData operation and query submitted historical event data by calling the QueryDeviceEventData operation.

    Invoke device services or configure device properties

    • Asynchronously invoke device services or configure device properties Transmit Alink data.

      No.

      Description

      1

      Invoke a service in the IoT Platform console.

      • Configure a property: You can call the SetDeviceProperty operation to configure a property for a device.

      • Invoke a service: You can call the InvokeThingService operation to invoke a service in an asynchronous manner.

        If you set the invocation method of a service to asynchronous when you define the service, the service is asynchronously invoked.

      1.1

      IoT Platform verifies the parameters.

      1.2

      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.

      For pass-through data, IoT Platform calls the protocolToRawData function in the data parsing script to convert the data before IoT Platform sends the data to the device.

      2

      The device processes the received data.

      Note

      IoT Platform uses different topics to process pass-through or custom data and Alink JSON data. For more information, see Modify device properties and Call device services in asynchronous mode.

      3

      After the device processes the data, the device returns a response to IoT Platform.

      After IoT Platform receives the response, you can perform the following operations:

      • If pass-through data is received, IoT Platform calls the rawDataToProtocol function in the data parsing script to convert the data.

      • If the rules engine is configured, IoT Platform forwards data to a destination such as a topic or a cloud service based on a specified forwarding rule.

        Important

        • For pass-through data, the data forwarded by the rules engine is parsed by using the data parsing script.

        • When you configure a data forwarding rule, you can specify the following topic for TSL data reporting as a data source: /${productKey}/${deviceName}/thing/downlink/reply/message, For more information, see Configure a data forwarding rule or Create a data source.

    • Synchronously invoke device services

      Transmit Alink data

      No.

      Description

      1

      Call the InvokeThingService operation to synchronously invoke a device service. If you set the invocation method of a service to synchronous when you define the service, the service is synchronously invoked.

      1.1

      IoT Platform verifies the parameters.

      1.2

      IoT Platform synchronously uses the RRPC topic to send data to the device.

      For pass-through data, IoT Platform calls the protocolToRawData function in the data parsing script to convert the data before IoT Platform sends the data to the device.

      1.3

      IoT Platform synchronously waits for a response from the device.

      2

      After the device processes the data, the device returns a response to IoT Platform. If a request times out, IoT Platform returns a timeout error.

      2.1

      IoT Platform returns the response to the caller.

      If pass-through data is received, IoT Platform calls the rawDataToProtocol function in the data parsing script to convert the data.

    Add topological relationships

    Transmit Alink data

    No.

    Description

    1

    Connect a sub-device to a gateway.

    If a third party is required to add a topological relationship, perform the following steps:

    1.1

    The gateway can use the /sys/${productKey}/${deviceName}/thing/list/found topic to submit the information about the detected sub-device to IoT Platform.

    If the rules engine is configured, IoT Platform forwards the submitted data to a destination such as a cloud service.

    1.2

    You can obtain the data of the sub-device from the cloud service.

    1.3

    You can add a topological relationship between the sub-device and the gateway.

    If you want to add a topological relationship, you can call the NotifyAddThingTopo operation to notify the gateway to add a topological relationship with the sub-device by using the /sys/${productKey}/${deviceName}/thing/topo/add/notify topic.

    2

    • The gateway can use the /sys/${productKey}/${deviceName}/thing/topo/add topic to add a topological relationship with the sub-device. Then, IoT Platform returns the result.

    • The gateway receives the request, and then adds a topological relationship by using a topic.

    3

    You can request the gateway to delete the topological relationship with the sub-device. The gateway uses the /sys/${productKey}/${deviceName}/thing/topo/delete topic to delete the topological relationship with the sub-device.

    4

    You can call the GetThingTopo operation to query the /sys/${productKey}/${deviceName}/thing/topo/get topic to obtain the topological relationship between the gateway and the sub-device.