All Products
Search
Document Center

IoT Platform:Connect a device to IoT Platform by using MQTT.fx

Last Updated:Jan 23, 2024

MQTT.fx is an Eclipse Paho-based Message Queuing Telemetry Transport (MQTT) client that is written in Java. MQTT.fx supports the Windows, macOS, and Linux operating systems. You can use MQTT.fx to check whether a device can connect to IoT Platform. MQTT.fx also allows you to subscribe to and publish messages by using topics. This topic describes how to connect a simulated device to IoT Platform over MQTT by using MQTT.fx in Windows.

Prerequisites

  • A product and a device are created, and the MQTT connection parameters are obtained. For more information, see Create a product and a device and How do I obtain MQTT parameters for authentication.

    The following table describes the device certificate and MQTT connection parameters that are used in this example. For more information about the parameters, see Establish MQTT connections over TCP.

    Parameter

    Value

    ProductKey

    a1***

    DeviceName

    device1

    DeviceSecret

    f35***d9e

    clientId

    a1***.device1|securemode=2,signmethod=hmacsha256,timestamp=2524608000000|

    username

    device1&a1***

    passwd

    86761***21d

    mqttHostUrl

    a1***.iot-as-mqtt.cn-shanghai.aliyuncs.com

    port

    1883

  • A TSL model has been defined. It is used to test the two-way communication between the test device and IoT Platform through topics for TSL communication. For more information, see Define a TSL model for a product.

    The following figure shows the definition of the TSL model used in this example.TSL model

Important

MQTT.fx is used to simulate an online device and supports the transmission of non-pass-through data. To transmit pass-through data, you can use an actual device or an SDK for testing.

Configure MQTT.fx

  1. Download and install the MQTT.fx tool. For information about how to install and use MQTT.fx, see MQTT.fx.

    In this example, mqttfx-5.2.0-windows-x64 is used. The third-party tool is not regularly updated. We recommend that you download the latest tool from the website in the previous reference link.

    Note

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

  2. Start the MQTT.fx tool, click Extras in the menu bar, and then select Edit Connection Profiles.

    Edit Connection Profiles

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

    1. Specify the basic information.

      Parameter

      Description

      Profile Name

      Enter a custom name. In this example, enter iot connection.

      Profile Type

      Specify a connection mode. Select MQTT Broker.

      Broker Address

      Enter an MQTT endpoint, which is the value of the mqttHostUrl parameter that you obtained in the Prerequisites section. In this example, enter a1***.iot-as-mqtt.cn-shanghai.aliyuncs.com.

      • a1*** indicates the ProductKey.

      • cn-shanghai indicates the region ID.

      The port number is not needed.

      Broker Port

      Enter a port number. Set this parameter to 1883.

      Client ID

      Configure the parameters in the MQTT protocol.

      Format: ${ClientId}|securemode=${Mode},signmethod=${SignMethod}|timestamp=${timestamp}|.

      Enter the value of the clientId parameter that you obtained in the "Prerequisites" section of this topic. In this example, a1***.device1|securemode=2,signmethod=hmacsha256,timestamp=2524608000000| is specified.

      Parameter description:

      • ${ClientId}: the ID of the client, such as a device, an application, or a web browser.

        Important

        You must specify a custom client ID. The client ID must be 1 to 64 characters in length. When the client is a device, we recommend that you set this parameter to the MAC address or the serial number (SN) of the device. This allows you to easily identify your devices.

      • ${Mode}: the security mode. Valid values: 2 and 3. If you use a direct TLS connection, specify securemode=2. Then, you must configure the SSL/TLS parameters. If you use a direct TCP connection, specify securemode=3. You do not need to configure the SSL/TLS parameters.

      • ${SignMethod}: the signature algorithm. Valid values: hmacmd256, hmacmd5, and hmacsha1.

      • ${timestamp}: the timestamp of the request. Unit: milliseconds. This parameter is optional.

      In the connection parameters provided by IoT Platform, the value of the ${ClientId} parameter is a string in the ${ProductKey} + '.' + ${DeviceName} format. The default value of ${Mode} is 2, and the default value of ${SignMethod} is hmacsha256. You can configure the parameters based on your business requirements.

      Important
      • Do not confuse the Client ID parameter of the MQTT.fx tool with the ${ClientId} parameter of the device.

      • Do not omit the vertical bars (|) between and at the end of the parameters.

      • When you configure the parameters, make sure that you remove all spaces from the parameter values.

      • After you specify the Client ID parameter, do not click Generate.

      General

      In this example, the default values of the parameters are used. You can configure the parameters based on your business requirements.

    2. Click User Credentials. On the tab that appears, select Use Username/Password and enter a username and a password.

      Configure the parameters of MQTT.fx on the User Credentials tab

      Parameter

      Description

      User Name

      The username consists of a DeviceName, an ampersand (&), and a ProductKey. Format: ${DeviceName}&${ProductKey}.

      Enter the value of the username parameter that you obtained in the "Prerequisites" section of this topic. In this example, device1&a1*** is specified.

      • device1 indicates the DeviceName of the device.

      • a1*** 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.

      Enter the value of the passwd parameter that you obtained in the "Prerequisites" section of this topic. In this example, 86761***21d is specified.

      Important
      • Your MQTT.fx tool may display a masked password. If a password is already 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 the letters in parameter names and values are in the correct cases.

      • You may modify the ${clientId} and ${SignMethod} parameters when you configure the Client ID parameter. In this case, make sure that the specified signature algorithm is the same as the value of the corresponding parameter in Client ID. Then, recalculate a password. For more information about the parameters and calculation method, see Use the Node.js script.

    3. If you use a TLS connection (securemode=2), click the SSL/TLS tab, select Enable SSL/TLS, and then set the Protocol parameter to TLSv1.2.

      Important

      If you use a TCP connection (securemode=3), use the default settings on the SSL/TLS tab, and go to the next step.

      Enable SSL/TLS

  4. Click OK in the lower-right corner.

  5. Click Connect.

    If the indicator on the right side turns green, the connection is established. Connect

    To view the status of the device, perform the following steps: Log on to the IoT Platform console. Go to the instance details page of the instance to which the device belongs. In the left-side navigation pane, choose Devices > Devices. On the Device List tab, find the device and view the device status. The device is in the Online state if it is connected with IoT Platform.

    Online

In the following sections, downstream messaging and upstream messaging are tested by using custom topics and topics for TSL communication to check whether the MQTT.fx client is connected to IoT Platform. If your test results are different from the following sample results, the connection is not established. You must modify the settings based on the logs.

Use custom topics

For more information about custom topics, see Use custom topics for communication. In this example, the default custom topic provided by IoT Platform is used.

Topic

Permission

Description

/a1***/device1/user/update/error

Publish

Upstream messaging: The device sends messages to IoT Platform through the topic.

/a1***/device1/user/get

Subscribe

Downstream messaging: The device subscribes to the topic and receives messages sent from IoT Platform.

Upstream messaging

  1. In MQTT.fx, click Publish. In the Publish field, enter the path of the topic that has the Publish permission: /a1***/device1/user/update/error.

  2. In the editor, enter the message that you want to publish and click Publish.

    Publish messages in MQTT.fx

  3. Go to the Device Log page in the IoT Platform console and view the log whose workload type is Cloud-to-device-Message. For more information, see Query IoT Platform logs.

    View the message that MQTT.fx publishes to IoT Platform

Downstream messaging

  1. In MQTT.fx, click Subscribe. In the Subscribe field, enter the path of the topic that has the Subscribe permission: /a1***/device1/user/get.

  2. Click Subscribe.

    If the subscription is successful, the custom topic appears on the Subscribe tab.

    The custom topic is displayed on the Subscribe tab

  3. To view the status of the device, perform the following steps: Log on to the IoT Platform console. Go to the instance details page of the instance to which the device belongs. In the left-side navigation pane, choose Devices > Devices.

  4. On the Device List tab, click View in the Actions column corresponding to the device. The device details page appears.

  5. On the Topic List tab, find the topic and click Publish Message in the Actions column.

  6. In the dialog box that appears, enter a message, such as This is a test., and click OK.

  7. In the MQTT.fx tool, check whether the message is received.

    Receive a message

Use topics for TSL communication

For more information about topics for TSL communication, see Topics.

Topic

Permission

Description

/sys/a1****/device1/thing/event/property/post

Publish

Upstream messaging: The device sends property data to IoT Platform through the topic.

/sys/a1****/device1/thing/event/property/post_reply

Subscribe

Downstream messaging: The device subscribes to the topic and receives property data sent from IoT Platform.

/sys/a1****/device1/thing/service/property/set

Subscribe

Downstream messaging: The device subscribes to the topic and receives messages sent from IoT Platform.

Submit device properties

  1. In MQTT.fx, click Subscribe. In the Subscribe field, enter the path of the topic that has the Subscribe permission: /sys/a1****/device1/thing/event/property/post_reply.

  2. In MQTT.fx, click Publish. In the Publish field, enter the path of the topic that has the Publish permission: /sys/a1****/device1/thing/event/property/post.

  3. In the editor, enter the property data that you want to publish and click Publish.

    The property data to be published must be in the Alink JSON format. For more information, see Devices submit property data to IoT Platform. In this example, data of the LightCurrent and LightSwitch properties is published. Properties

  4. In the MQTT.fx tool, click Subscribe and view the response from IoT Platform.

    The following response is returned, which indicates that the device has successfully published the property data. Response

  5. To view the status of the device, perform the following steps: Log on to the IoT Platform console. Go to the instance details page of the instance to which the device belongs. In the left-side navigation pane, choose Devices > Devices.

  6. Click View in the Actions column to go to the Device Details page. Click the TSL Data tab, and view the data.

Set device properties

  1. In MQTT.fx, click Subscribe. In the Subscribe field, enter the path of the topic that has the Subscribe permission: /sys/a1****/device1/thing/service/property/set.

  2. To view the status of the device, perform the following steps: Log on to the IoT Platform console. Go to the instance details page of the instance to which the device belongs. In the left-side navigation pane, choose Maintenance > Online Debug.

  3. On the page that appears, select the device you want to debug. On the Property Debugging tab, set LightSwitch to 0.

  4. Click Set to send the command.

  5. In the MQTT.fx tool, click the Subscribe tab and view the message received by the device.

    Set properties

View logs

  • Go to the Device Log page in the IoT Platform console and view information of the logs, such as their time, trace IDs, and workload types. For more information, see Query IoT Platform logs.

  • In the MQTT.fx tool, click the Log tab. On the tab that appears, view the operation logs and error logs. View logs in MQTT.fx