IoT Platform:Alink protocol

Overview

The Alink protocol is a JSON-based data exchange specification for bidirectional communication between devices and IoT Platform. It simplifies and standardizes business data interactions.

Available Link SDKs and supported languages are listed in Device-side Link SDK.

The following table lists Alink protocol topics by IoT Platform feature.

The following sections describe device connection and data upstream/downstream flows.

Device onboarding

Device connection to IoT Platform differs for directly connected devices and sub-devices, but both follow three steps: registration, activation and connection, and data reporting.

Directly connected devices can be connected in two ways:

• Use a device-specific certificate: Pre-burn the device certificate (ProductKey, DeviceName, and DeviceSecret) to the device. The device then registers, connects, and reports data.
• Use a product-specific certificate for dynamic registration: Pre-burn the product certificate (ProductKey and ProductSecret) to the device. The device then registers, connects, and reports data.

Sub-devices connect through a gateway using one of two methods:

• Use a device-specific certificate: Pre-burn the device certificate (ProductKey, DeviceName, and DeviceSecret) to the sub-device. The sub-device reports the certificate to the gateway. The gateway adds a topological relationship and reuses its channel to report data.
• Use dynamic registration: Pre-burn the ProductKey to the sub-device. The sub-device reports ProductKey and DeviceName to the gateway. IoT Platform verifies DeviceName and issues DeviceSecret. The sub-device reports the certificate to the gateway, which adds a topological relationship and relays data through its channel.

Report device properties or events

• Pass-through (custom) data format

  No.		Description
  1	The device reports pass-through data to a specific topic. For more information about topics, see Device properties, events, and services.
  	1.1	IoT Platform uses a data parsing script to parse the data reported by the device. The platform calls the rawDataToProtocol method in the script to convert the reported data into the standard data format of IoT Platform (Alink JSON format). The Data parsing topic explains how to write parsing scripts.
  	1.2	IoT Platform processes the business logic using the converted Alink JSON data. If the rules engine is configured, data is forwarded to a destination, such as another topic or a cloud service, based on data forwarding rules. Important The rules engine receives data that has been parsed by the script. When you configure data forwarding, set the source topic to a TSL model data reporting topic, such as /${productKey}/${deviceName}/thing/event/property/post or /${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post. For more information, see Configure data forwarding rules or Add a data source.
  	1.3	IoT Platform calls the protocolToRawData method in the data parsing script to convert the result data into a format that the device can receive.
  	1.4	IoT Platform pushes the parsed data to the device.
  2	You can call the QueryDevicePropertyData API operation to query the historical property data reported by the device. You can call the QueryDeviceEventData API operation to query the historical event data reported by the device.

• Non-pass-through (Alink JSON) data format

  No.		Description
  1	The device reports data to a specific topic for non-pass-through data. For more information about topics, see Device properties, events, and services.
  	1.1	IoT Platform processes the business logic. If the rules engine is configured, data is forwarded to a destination, such as another topic or a cloud service, based on data forwarding rules. Important When you configure data forwarding, set the source topic to a TSL model data reporting topic, such as /${productKey}/${deviceName}/thing/event/property/post or /${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post. For more information, see Configure data forwarding rules or Add a data source.
  	1.2	IoT Platform returns the processing result to the device.
  2	You can call the QueryDevicePropertyData API operation to query the historical property data reported by the device. You can call the QueryDeviceEventData API operation to query the historical event data reported by the device.

Invoke device services or set properties

• Asynchronous service invocation or property setting

  No.		Description
  1	Invoke a service in IoT Platform. Set properties: Call the SetDeviceProperty API operation to set specific properties for a device. Invoke a service: Call the InvokeThingService API operation to asynchronously invoke a service. A service is asynchronously invoked if its invocation method is set to asynchronous.
  	1.1	IoT Platform verifies the parameters that you submit.
  	1.2	IoT Platform sends data to the device asynchronously and returns the result. On success, the result contains the message ID. For pass-through (pass-through/custom) data, IoT Platform first calls the protocolToRawData method in the data parsing script to convert the data format. Then, it sends the converted data to the device.
  2	After the device receives the data, it processes the business logic. Note Message processing topics differ between pass-through (custom) and non-pass-through (Alink JSON) data. Set device properties and Device service invocation (asynchronous call).
  3	After the device processes the business logic, it returns the result to IoT Platform. After IoT Platform receives the result, it performs the following operations: If the data is in pass-through format, IoT Platform calls the rawDataToProtocol method in the data parsing script to convert the data format of the result returned by the device. If the rules engine is configured, data is forwarded to a destination, such as another topic or a cloud service, based on data forwarding rules. Important For pass-through data, the rules engine receives data that has been parsed by the script. When you configure data forwarding, set the source topic to a TSL model data reporting topic, such as /${productKey}/${deviceName}/thing/downlink/reply/message. For more information, see Configure data forwarding rules or Add a data source.

• Synchronous service invocation

  No.		Description
  1	Call the InvokeThingService API operation to invoke a synchronous service. A service is synchronously invoked if its invocation method is set to synchronous.
  	1.1	IoT Platform verifies the parameters that you submit.
  	1.2	IoT Platform uses a synchronous call to invoke a revert-RPC (RRPC) topic and send data to the device. For pass-through (pass-through/custom) data, IoT Platform first calls the protocolToRawData method in the data parsing script to convert the data format. Then, it sends the converted data to the device.
  	1.3	IoT Platform synchronously waits for the device to return a result.
  2	After the device processes the business logic, it returns the result to IoT Platform. If a timeout occurs, a timeout error message is returned.
  	2.1	After IoT Platform receives the result from the device, it returns the result to the caller. If the data is in pass-through format, IoT Platform calls the rawDataToProtocol method in the data parsing script to convert the data format of the result returned by the device.

Topological relationships