MQTT.fx is an Eclipse Paho-based Message Queuing Telemetry Transport (MQTT) client that is written in Java. MQTT.fx allows you to subscribe to and publish messages by using topics. This article describes how to connect a device to IoT Platform over MQTT by using a third-party tool. MQTT.fx is used in this example.
Prerequisites
A product and device are created in the IoT Platform console. The device certificate including the ProductKey, DeviceName, and DeviceSecret is obtained. For more information, see Create a product, Create a device, and Create multiple devices at a time.
Connect the device to IoT Platform by using MQTT.fx
- Download and install the MQTT.fx tool. For more information, visit the official MQTT.fx website.
- Open the MQTT.fx tool, click Extras in the menu bar, and then select Edit Connection Profiles.
- On the Edit Connection Profiles page, set the parameters.
- Edit the basic information.
Parameter Description Example Profile Name Enter a name. iot connection Profile Type Select MQTT Broker. MQTT Broker Profile Settings Broker Address Enter the endpoint. - The endpoint of the public instance is in the
${YourProductKey}.iot-as-mqtt. ${YourRegionId}.aliyuncs.com
format.- Replace the ${YourRegionId} variable with your region ID. For more information about region IDs, see Regions and zones.
a1oGs******.iot-as-mqtt.cn-shanghai.aliyuncs.com In this example, the public instance is used.- a1oGs****** is specified as the ProductKey.
- cn-shanghai is specified as the region ID.
Broker Port Enter a port number. Set this parameter to 1883. Client ID Format:
${ClientID}|securemode= ${Mode},signmethod= ${SignMethod}|
.The Client ID parameter specifies the ID of the MQTT.fx client. You must specify the following variables:
- ${ClientId}: the ID of the client, such as a device, mobile app, or web browser. In most cases, the client ID is the device ID. The client ID must be 1 to 64 characters in length, and can contain arbitrary characters. We recommend that you use the MAC address or serial number (SN) of the device as the client ID.
- securemode: the security mode.
- If you use a TCP connection, specify
securemode=3
. In this case, you do not need to set the SSL/TLS parameters. - If you use a TLS connection, specify
securemode=2
. In this case, you must set the SSL/TLS parameters.
- If you use a TCP connection, specify
- signmethod: the encryption algorithm. Valid values: hmacmd5 and hmacsha1.
Note- Do not confuse the usage of the Client ID parameter and the ${ClientId} variable.
- Do not omit the vertical bars (|) between and at the end of the variables.
- When you specify the variables, make sure that you remove all spaces from the values.
- After you specify the Client ID parameter, do not click Generate.
12345|securemode=2,signmethod=hmacsha1| - 12345 is specified for the ${ClientId} variable.
- securemode=2 indicates that a TLS connection is used.
- signmethod=hmacsha1 indicates the encryption algorithm.
On the General tab, you can use the default settings or set the parameters based on your business requirements.
- The endpoint of the public instance is in the
- Click the User Credentials tab. Set the User Name and Password parameters.
Parameter Description Example User Name Format:
${YourDeviceName}&${YourProductKey}
.The username consists of a DeviceName, ampersand (&), and ProductKey.
Light&a1oGs****** Light
indicates the DeviceName of the device.a1oGs******
indicates the ProductKey of the device.
Password To generate a password, you must select a signature algorithm, use the DeviceSecret of the device as a secret key, and then concatenate the required parameters and their values. Note- Your MQTT.fx client may show a masked password. If a password is pasted, the pointer moves to the end of the password. In this case, you do not need to paste the password again.
- Make sure that you specify valid uppercase and lowercase letters in parameters and parameter values.
You can use one of the following methods to generate a password:
-
Click here to download a generation tool. Decompress the downloaded package, and double-click the sign.html file to use the tool.
- Manually generate a password. You must perform the following steps:
- Concatenate the required parameters.
Format of a string to be encrypted:
clientId${clientId}deviceName${deviceName}productKey${productKey}timestamp${timestamp}
- Encrypt the string.
Format of the encryption function:
${signmethod} (${deviceSecret},clientId${clientId}deviceName${deviceName}productKey${productKey}timestamp${timestamp})
- Concatenate the required parameters.
Description of the parameters:
- productKey: the ProductKey of the product to which the device belongs. You can view the ProductKey on the Device Details page of the IoT Platform console.
- deviceName: the DeviceName of the device. You can view the DeviceName on the Device Details page of the IoT Platform console.
- deviceSecret: the DeviceSecret of the device. You can view the DeviceSecret on the Device Details page of the IoT Platform console.
- timestamp: the timestamp. This parameter is optional.
- clientId: the ID of the device. The value of this parameter must be the same as the value of the ${clientId} variable that you set in the Client ID field.
- method: the encryption algorithm. The value of the parameter must be the same as the value of the signmethod variable that you set in the Client ID field.
- Example of generating a password by using the tool
- Example of manually generating a password
The string to be encrypted:
clientId12345deviceNameLightproductKeya1oGs******
Encryption function:
hmacsha1(8DTASg0cf8rEmSJwc6y6msF0On******,clientId12345deviceNameLightproductKeya1oGs******)
Description of the parameters:
hmcsha1
indicates the encryption algorithm.8DTASg0cf8rEmSJwc6y6msF0On******
indicates the DeviceSecret of the device.12345
indicates the ID of the device.Light
indicates the DeviceName of the device.a1oGs******
indicates the ProductKey of the device.- The timestamp parameter is not specified in this example.
- If you use a TLS connection (
securemode=2
), click the SSL/TLS tab, select Enable SSL/TLS, and then select a protocol. We recommend that you select TLSv1.2.Note If you use a TCP connection (securemode=3
), use the default settings in the SSL/TLS tab, and go to the next step.
- Edit the basic information.
- Click OK in the lower-right corner.
- Click Connect.
Test downstream messaging
- In the MQTT.fx tool, click the Subscribe tab.
- In the Subscribe field, enter a custom topic that has the Subscribe permission. Then, click Subscribe to subscribe to this topic.Note
- To view the permissions of custom topics, go to the Product Details page of the IoT Platform console. On the Topic Categories tab, click Custom Topics.
- When you specify a custom topic, replace the
${deviceName}
variable with the DeviceName of your device. - For more information, see Customize a topic category.
After the subscription succeeds, the custom topic is displayed on the Subscribe tab.
- Log on to the IoT Platform console.Go to the Device Details page. On the Topic List tab, find the topic and click Publish Message.
- Enter a message and click OK.
- In the MQTT.fx tool, check whether the message is received.
Test upstream messaging
To check the connectivity between the device and IoT Platform, send a message by using the MQTT.fx tool and view the result on the Log tab of the MQTT.fx tool.
- In the MQTT.fx tool, click the Publish tab.
- In the Publish field, enter a topic that has the Publish permission. On the text box, enter a message
to be sent. Click Publish to publish the message to the topic.
- Log on to the IoT Platform console.Choose Maintenance > Device Log. You can view the message on the Cloud Run Log tab.
View logs
In the MQTT.fx tool, click the Log tab. On this tab, view operations logs and error logs.
