IoT Platform:Create an MQTT gateway

Create a gateway

1. Log on to the IoT Platform console.

2. On the Overview tab, click the Exclusive Enterprise Edition instance that you want to manage.

3. In the left-side navigation pane, choose Devices > Gateway. On the page that appears, click Add Gateway.

4. In the Basic Information step, configure the parameters and click Next. The following table describes the parameters.

   Parameter	Description
   Gateway Name	The name of the gateway. The name must be unique in the instance. The name must be 4 to 30 characters in length and can contain letters, digits, and underscores (_).
   Protocol	Select MQTT.
   Custom Port Number	Valid values: 1024 to 65535. Default value: 1883.
   Enable Data Parsing	Specify whether to enable the data parsing feature for gateway devices. IoT Platform passes through the data of gateway devices. You can enable the data parsing feature based on your business requirements. You can implement the transformPayload() method in the data parsing script to convert the raw data that is submitted by a device into data in the standard JSON format or the data format that is defined in the Alink protocol for Thing Specification Language (TSL) models. For more information about the data parsing feature, see Message parsing.
   Authentication Type	One-party Verification If you select this option, you must import the verification information of a device to IoT Platform. The verification information includes the username, password, and serial number (SN) of the device. IoT Platform verifies the device based on the verification information. Third-party Certification If you select this option, you must specify the third-party verification service that you want to use. You can select Alibaba Cloud Function Compute or a HTTPS-based device verification service. For more information about Alibaba Cloud Function Compute, see What is Function Compute? Alibaba Cloud Function Compute: If you select this option, you must configure the Device-verified FC Service, Device-verified FC Function, and Authorize parameters. You can select an existing Function Compute function or create a new function for device verification. The input and output parameters of the function that you create must be valid. You can specify a custom function name. For information about the requirements for the input and output parameters of the device verification function, see Parameters of the Function Compute function for device verification. Click Create Service to go to the Function Compute console and create a service. For information about Function Compute services, see Manage services. Click Create Function to go to the Function Compute console and create a function. For information about Function Compute functions, see Manage functions. If the AliyunIOTAccessingFCRole role is not available, click Create RAM Role to go to the RAM console and create the role. For information about how to create a RAM role and grant permissions to the role, see Create a RAM role. External HTTPS: If you select this option, you must configure the HTTPS URL for Device Verification parameter. Custom Device Verification Parameters are optional. The URL for device verification must start with https://. IoT Platform sends HTTPS requests to call custom device verification services. The input and output parameters of the HTTP requests must be valid. For information about the parameter requirements, see Parameters of HTTPS requests for device verification. You can configure up to 10 custom device verification parameters in the key-value pair format. Parameter Key: the parameter name that can be up to 64 characters in length. Parameter Value: the parameter value that can be up to 64 characters in length. You can set the Parameter Value field to a variable in the ${Variable name} format. The following variables are supported: ${username}: the username that is submitted by the device to establish an MQTT connection. ${password}: the password that is submitted by the device to establish an MQTT connection. ${clientId}: the client ID that is submitted by the device to establish an MQTT connection. ${cert.***}: the device certificate. *** can be cn, serial, or issuer. ${userProperties.***}: the custom UserProperty data in the CONNECT packet. *** is a custom field.
   Enable X.509 certificate-based Device Verification	Enable the X.509 certificate-based device verification Valid values of the Enable OCSP parameter: Disabled OCSP Verification for Server Certificate OCSP Verification for Client Certificate Client and Server-side OCSP Verification Note Online Certificate Status Protocol (OCSP) is an Internet protocol that is used by a certificate authority (CA) to check the revocation status of a certificate. When a client sends a message to a server, the server performs OCSP verification on the client certificate. If the client certificate is revoked, the server closes the connection. The default time to live (TTL) of cached OCSP information ranges from 5 minutes to 1 hour. After the cached OCSP information expires, server-side OCSP stapling does not take effect until the OCSP information is re-obtained. Disable the X.509 certificate-based device verification Valid values of the Enable OCSP parameter: Disabled OCSP Verification for Server Certificate Note Online Certificate Status Protocol (OCSP) is an Internet protocol that is used by a certificate authority (CA) to check the revocation status of a certificate. When a client sends a message to a server, the server performs OCSP verification on the client certificate. If the client certificate is revoked, the server closes the connection. The default time to live (TTL) of cached OCSP information ranges from 5 minutes to 1 hour. After the cached OCSP information expires, server-side OCSP stapling does not take effect until the OCSP information is re-obtained.

   Table 1 Parameters of the Function Compute function for device verification

   Type	Parameter	Data type	Required	Description
   Request parameters	userName	String	Yes	The username that is required to connect a device to IoT Platform over MQTT. The username must be 4 to 32 characters in length, and can contain letters, digits, hyphens (-), underscores (_), at signs (@), periods (.), and colons (:). The username must be unique in the product.
   	password	String	Yes	The password that is required to connect the device to IoT Platform over MQTT. The password must be 1 to 32 characters in length, and can contain letters, digits, hyphens (-), underscores (_), at signs (@), periods (.), and colons (:).
   	clientId	String	Yes	The client ID that is required to connect the device to IoT Platform over MQTT.
   	certificateCommonName	String	No	The commonName field in the X. 509 certificate specification. If you use an X.509 certificate to verify the identity of the device, you must configure this parameter.
   Response parameters	result	String	Yes	The verification result. The value true indicates that the verification was successful. The value false indicates that the verification failed.
   	message	String	No	The error message that is returned if the verification failed.
   	deviceName	String	No	The DeviceName that corresponds to the username returned if the verification is successful. The first time you connect a device to IoT Platform, IoT Platform creates a device based on the return value of the deviceName parameter.

   Sample response of the Function Compute function for device verification:

   {
       "result":"true",
       "deviceName":"device_TH",
       "message":""
   }

   Table 2 Parameters of HTTPS requests for device verification

   Type	Parameter	Data type	Required	Description	Example
   Request method	Method	String	Yes	Set the value to POST.	POST Content-Type: application/json body:{ "username": "UN001", "password": "PW001", "certificateCommonName": "CN001" }
   Header	Content-Type	String	Yes	The data encoding format defined in HTTPS headers. Only application/json is valid. If another encoding format is specified, an error occurs.
   Request body	username	String	Yes	The username that is required to connect the device to IoT Platform over MQTT. The username must be 4 to 32 characters in length, and can contain letters, digits, hyphens (-), underscores (_), at signs (@), periods (.), and colons (:). The username of a device must be unique in a product.
   	password	String	Yes	The password that is required to connect the device to IoT Platform over MQTT. The password must be 1 to 32 characters in length, and can contain letters, digits, hyphens (-), underscores (_), at signs (@), periods (.), and colons (:).
   	certificateCommonName	String	No	The commonName field in the X.509 certificate specification. If you use an X.509 certificate to verify the identity of the device, you must configure this parameter.
   Response body	deviceName	String	Yes	The DeviceName that corresponds to the username returned if the verification is successful. The first time you connect a device to IoT Platform, IoT Platform creates a device based on the return value of the deviceName parameter.	body:{ "deviceName": "device_TH" }

5. Complete the Certificate Configuration step and click OK.

   Configure certificates

   Note

   The certificates that are configured in this step are in the PEM format.

   • You must configure the Server Certificate and Private Key of Server Certificate parameters.

     A device that is connected to IoT Platform by using an MQTT gateway supports only Transport Layer Security (TLS). To ensure business security, you must specify the CA certificate and private key of the original server to which the device is connected.

     For example, your certificate chain contains certificates that are sorted in the following order: server root certificate, server intermediate certificates, and server certificate. Server intermediate certificates can include multiple levels of intermediate certificates, such as Intermediate Certificate A and Intermediate Certificate B. In this case, you must configure the parameters in this step based on the following instructions:

     • Server Certificate: Specify the certificates in the certificate chain in reverse order. Specify the server certificate first and then specify server intermediate certificates (Intermediate Certificate B and Intermediate Certificate A).

     • Private Key of Server Certificate: Specify the private key of the server certificate.

   • If you have enabled X.509 certificate-based device verification, you must configure the Device Root Certificate parameter.

     For example, your certificate chain contains certificates that are sorted in the following order: device root certificate, device intermediate certificates, and device certificate. Device intermediate certificates can include multiple levels of intermediate certificates, such as Intermediate Certificate A and Intermediate Certificate B. In this case, you must configure the parameters in this step based on the following instructions:

     Device Root Certificate: Specify the certificates in the certificate chain in reverse order. Specify the device intermediate certificates (Intermediate Certificate B and Intermediate Certificate A) first and then specify the device root certificate.

   • If you set the Enable OCSP parameter in the previous step to OCSP Verification for Server Certificate or Client and Server-side OCSP Verification, you must set the Trusted Certificate parameter to the server root certificate in this step.

6. View the information about the gateway that you created on the Gateway page, including the name, ID, gateway URL, status, and associated product.

   Important

   You must save the gateway URL. When you connect a device to IoT Platform over MQTT, you must replace the MQTT endpoint with the gateway URL. You can specify the gateway URL as the MQTT endpoint or configure a CNAME record to resolve the MQTT endpoint to the gateway URL.

   

(Optional) Modify a gateway

After you create a gateway, find the gateway on the Gateway page and click Edit in the Actions column. You can modify the name, certificate information, and Function Compute function of the gateway.