Connect to IoT Platform using MQTT.fx

Video demonstration

Configure the MQTT.fx connection

1. Download and install MQTT.fx. For installation and usage instructions, see MQTT.fx.

   This topic uses mqttfx-5.2.0-windows-x64 as an example. Your UI may differ due to version updates.

   Note

   You must apply for a license to use the MQTT.fx tool.

2. Open the MQTT.fx software, click Extras in the menu bar, and select Edit Connection Profiles.

3. On the Edit Connection Profiles page, configure the following parameters.

   1. Configure the basic information.

      Parameter	Description
      Profile Name	Enter a custom name, such as iot connection.
      Profile Type	Select MQTT Broker.
      Broker Address	The MQTT connection endpoint. Use the mqttHostUrl from the Prerequisites section: a1***.iot-as-mqtt.cn-shanghai.aliyuncs.com. a1*** is the ProductKey of the product. cn-shanghai is the region ID. Enter only the domain name. Do not include the port number.
      Broker Port	Set to 1883.
      Client ID	An MQTT protocol field. Format: ${ClientId}|securemode=${Mode},signmethod=${SignMethod}|timestamp=${timestamp}|. Enter the clientId from the Prerequisites section: a1***.device1|securemode=2,signmethod=hmacsha256,timestamp=2524608000000|. Parameter description: ${ClientId}: The client ID for a device, app, or web client. Important Must be custom and up to 64 characters long. For devices, use the MAC address or serial number (SN). ${Mode}: Security mode. Set to 2 for direct TLS (requires SSL/TLS settings) or 3 for direct TCP (no SSL/TLS settings required). ${SignMethod}: Signature algorithm. Supported: hmacsha256, hmacmd5, and hmacsha1. ${timestamp}: Current time in milliseconds. The timestamp parameter is optional. By default, IoT Platform sets ${ClientId} to ${ProductKey}.${DeviceName}, ${Mode} to 2, and ${SignMethod} to hmacsha256. Modify these values as needed. Important Do not confuse the Client ID field of MQTT.fx with the ${ClientId} value of the device. Do not omit the vertical bars (|) between parameters or at the end of the string. Ensure that the parameter values have no leading or trailing spaces. After you enter the Client ID information, do not click Generate.
      General	Default settings are used in this example. Modify based on your scenario.

   2. Click User Credentials, select the Use Username/Password checkbox, and set User Name and Password.

      Parameter	Description
      User Name	The username is the device's DeviceName, an ampersand (&), and the product's ProductKey, in the format ${DeviceName}&${ProductKey}. Enter the username from the Prerequisites section: device1&a1***. device1 is the DeviceName of the device. a1*** is the ProductKey of the product.
      Password	The password is generated by encrypting concatenated parameters with the DeviceSecret as the key, using the selected signature algorithm. Enter the passwd from the Prerequisites section: 86761***21d. Important In some MQTT.fx versions, the password is masked after pasting. If the cursor moves to the end, the paste succeeded. Do not paste again. Parameters and their values are case-sensitive. If you changed ${ClientId} or ${SignMethod} in the Client ID, ensure the signature values match those in the Client ID, then recalculate the password. Calculate the password by using the web tool and Calculate the password by using a Node.js script.

   3. For a direct TLS connection (securemode=2), click SSL/TLS, select Enable SSL/TLS, and set Protocol to TLSv1.2.

      Important

      For a direct TCP connection (securemode=3), you do not need to configure SSL/TLS settings. Proceed to the next step.

4. Click OK in the lower-right corner.

5. Click Connect.

   A green indicator confirms a successful connection to IoT Platform.

   Verify the device status in the IoT Platform console. In your instance, navigate to Devices > Devices, select the product, and confirm the device status is Online.

The following sections test upstream and downstream messaging using custom topics and TSL communication topics. If your results differ, the connection failed — correct the settings based on the log information.

Use custom topics for communication

Upstream messaging

1. In MQTT.fx, click Publish. In the Publish text box, enter the topic with publish permission: /a1***/device1/user/update/error.

2. Enter the message content in the text editor and click Publish.

   Make sure that QoS is set to QoS 0 and the message body is, for example, This is a publish test..

3. In the IoT Platform console, open the Device Log page of your instance and check the device-to-cloud message logs. Query cloud-side running logs.

   Click View for a log entry. In the View Details dialog box, verify that the Topic is /a[ProductKey]/device1/user/update/error and the message content is This is a publish test..

Downstream messaging

1. In MQTT.fx, click Subscribe. In the Subscribe text box, enter the topic with Subscribe permission: /a1***/device1/user/get.

2. Click Subscribe.

   After subscription, the topic appears in the list.

3. In the IoT Platform console, navigate to Devices > Devices in your instance.

4. In the device's Actions column, click View to open the device details page.

5. Click the Topic List tab. In the Actions column for the subscribed topic, click Publish Message.

6. Enter a message, such as This is a test., and click OK.

7. Return to MQTT.fx to view the received message.

   On the Subscribe tab, the topic /a{ProductKey}/device1/user/get receives the message This is a test (QoS 0, decoded with Plain Text Decoder).

Use topics for TSL communication

Report device properties

1. In MQTT.fx, click Subscribe. In the Subscribe text box, enter the topic with subscribe permissions: /sys/a1****/device1/thing/event/property/post_reply.

2. In MQTT.fx, click Publish, and in the Publish text box, enter a topic with publish permission: /sys/a1****/device1/thing/event/property/post.

3. Enter the property data in the text editor and click Publish.

   Property data must use the standard Alink JSON format. Device reports properties. This example reports LightCurrent and LightSwitch properties. The topic is /sys/${ProductKey}/device1/thing/event/property/post, with this sample JSON payload: {"method":"thing.event.property.post","id":"162277852","params":{"LightSwitch":1,"LightCurrent":1.4},"version":"1.0.0"}.

4. On the Subscribe tab in MQTT.fx, view the response message from IoT Platform.

   On success, IoT Platform returns a response like:

   /sys/${YourProductKey}/device1/thing/event/property/post_reply
   {"code":200,"data":{},"id":"162277852","message":"success","method":"thing.event.property.post","version":"1.0"}

5. In the IoT Platform console, navigate to Devices > Devices in your instance.

6. Click View in the device's Actions column. On the device details page, click the TSL Data tab to view the reported data.

Set device properties

1. In MQTT.fx, click Subscribe. In the Subscribe text box, enter the topic with Subscribe permission: /sys/a1****/device1/thing/service/property/set.

2. In the IoT Platform console, navigate to Maintenance > Online Debug in your instance.

3. Select the device. On the Property Debugging tab, set LightSwitch to 0.

4. Click Set to send the command.

5. On the Subscribe tab in MQTT.fx, view the received message.

   /sys/axxxxx/device1/thing/service/property/set
   {"method":"thing.service.property.set","id":"2016306076","params":{"LightSwitch":0},"version":"1.0.0"}

View logs

• In the IoT Platform console, open the Device Log page of your instance to view runtime log messages, including time, TraceID, and business type. Query cloud-side running logs.

• In MQTT.fx, click the Log tab to view operation and error logs.

  INFO --- MqttFX ClientModel            : messageArrived() with topic: /ext/error/axxx0/device1
  INFO --- PublishController              : publish
  INFO --- MqttFX ClientModel            : attempt to add PublishTopic
  INFO --- MqttFX ClientModel            : addPublishTopic : /a1xxx/device1/user/get
  INFO --- MqttFX ClientModel            : sucessfully published message test to topic /axxx/device1/user/g
  INFO --- PublishController              : publish
  INFO --- MqttFX ClientModel            : attempt to add PublishTopic
  INFO --- MqttFX ClientModel            : sucessfully published message test to topic /axxx/device1/user/g
  INFO --- PublishController              : publish
  INFO --- MqttFX ClientModel            : attempt to add PublishTopic
  INFO --- MqttFX ClientModel            : sucessfully published message test to topic /axxx/device1/user/g
  INFO --- BrokerConnectorController     : onDisconnect
  INFO --- ScriptsController              : Clear console.
  INFO --- ScriptsController              : Cancel script excution.
  INFO --- ScriptsController              : Clear console.
  INFO --- ScriptsController              : Cancel script excution.
  INFO --- ScriptsController              : Clear console.
  INFO --- ScriptsController              : Cancel script excution.
  INFO --- BrokerConnectorController     : onConnect
  INFO --- ScriptsController              : Clear console.
  INFO --- MqttFX ClientModel            : MqttClient with ID a1xxx0.device1|securemode=2,signmethod=hmacsha...
  INFO --- MqttFX ClientModel            : session present: false
  INFO --- SubscribeController            : onSubscribe
  INFO --- MqttFX ClientModel            : rebuildMessagesList()
  INFO --- MqttFX ClientModel            : attempt to addRecentSubscriptionTopic
  INFO --- MqttFX ClientModel            : addRecentSubscriptionTopic : de.jensd.mqttfx.entities.Topixxx1
  INFO --- MqttFX ClientModel            : attempt to add PublishTopic
  INFO --- MqttFX ClientModel            : addPublishTopic : /axxx/device1/user/get
  INFO --- MqttFX ClientModel            : sucessfully subscribed to topic /a1xxxSp0/device1/user/get (QoS 0)
  INFO --- MqttFX ClientModel            : messageArrived() with topic: /a1Kucxxx/device1/user/get
  INFO --- MqttFX ClientModel            : messageArrived() added: message #1 to topic '/axxx/device1/user/...
  INFO --- PublishController              : publish
  INFO --- MqttFX ClientModel            : attempt to add PublishTopic
  INFO --- MqttFX ClientModel            : addPublishTopic : /a1xxx/device1/user/update/error
  INFO --- MqttFX ClientModel            : sucessfully published message This is a publish test. to topic /a1Kuc5xxx/device1/user/get

Related documents

• IoT Platform supports the MQTT protocol, widely used in IoT for resource-constrained, low-bandwidth environments. MQTT protocol specifications.

• To connect a device to IoT Platform, see the device connection guide.

• Topics serve as intermediaries for MQTT message publishing and subscribing. For topic concepts and definitions, see What is a topic?.