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

Prerequisites

A product and a device are created in the IoT Platform console. The device certificate and MQTT connection parameters are obtained from the Device Details page. For more information, see the following articles:

In this example, a public instance of the previous version is used. The following table describes the device certificate and MQTT connection parameters. For more information about the parameters, see Establish MQTT over TCP connections.

Parameter Value
ProductKey a1***
DeviceName device1
DeviceSecret f35***d9e
clientId a1***.device1securemode=2,signmethod=hmacsha256,timestamp=2524608000000
username device1&a1***
passwd 86761***21d
mqttHostUrl a1***.iot-as-mqtt.cn-shanghai.aliyuncs.com
port 1883
Notice MQTT.fx is used to simulate an online device and allows you to transmit only non-passthrough 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 more information, visit the MQTT.fx.
  2. Start the MQTT.fx tool, click Extras in the menu bar, and then select Edit Connection Profiles.
    Configure MQTT parameters
  3. On the Edit Connection Profiles page, configure the parameters.
    1. Specify the basic information.
      Specify the basic information about MQTT.fx
      Parameter Description
      Profile Name Enter a custom name. In this example, iot connection is specified.
      Profile Type Specify a connection mode. Select MQTT Broker.
      MQTT Broker Profile Settings
      Broker Address Enter an MQTT endpoint, which is the value of the mqttHostUrl parameter that you obtained in the "Prerequisites" section of this article. In this example, a1***.iot-as-mqtt.cn-shanghai.aliyuncs.com is specified.
      • a1*** indicates the ProductKey.
      • cn-shanghai indicates the region ID.
      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 article. In this example, a1***.device1securemode=2,signmethod=hmacsha256,timestamp=2524608000000 is specified.

      The following table describes the parameters.

      • ${ClientId}: the ID of the client, such as a device, an application, or a web browser.
        Notice You can specify a client ID as needed. The client ID must be 1 to 64 characters in length. If the client ID is a device ID, we recommend that you specify the MAC address or the serial number (SN) of the device as the value of this parameter. This way, you can identify your devices in an efficient manner.
      • ${Mode}: the security mode. Valid values: 2 and 3. If you use a direct TLS connection, specify securemode=2. In this case, you must configure the SSL/TLS parameters. If you use a direct TCP connection, specify securemode=3. In this case, 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 modify the parameters as needed.

      Notice
      • Do not confuse the Client ID parameter of the MQTT.fx client 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 configure 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 the User Credentials tab. Configure the User Name and Password parameters.
      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 article. 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 the values of the parameters.

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

      Notice
      • Your MQTT.fx client may display 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 parameter names and values.
      • 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 the 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.
      Notice If you use a TCP connection (securemode=3), use the default settings on the SSL/TLS tab, and go to the next step.
      Configure the parameters of MQTT.fx on the SSL/TLS tab
  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 the MQTT.fx client to IoT Platform

    To view the status of the device, perform the following steps: Log on to the IoT Platform console. Choose Devices > Devices, select the product, and then find the device. The device is in the Online state.

    Online

In the following sections, downstream messaging and upstream messaging are tested 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.

Test downstream messaging

  1. Log on to the IoT Platform console. On the Product Details page, choose Topic Categories > Custom Topics. Then, find a custom topic that has the Subscribe permission.
    In this example, the /a1***/${deviceName}/user/get topic is used. You must replace the ${deviceName} variable with device1.

    For more information, see Custom topics.

  2. In the MQTT.fx tool, click Subscribe. In the Subscribe field, enter the topic that you specified in the previous step, and then click Subscribe.

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

    Custom topics are displayed on the Subscribe tab
  3. Go to the Device Details page in the IoT Platform console. On the Topic List tab, find the topic and click Publish Message.
    Publish messages to a topic that is subscribed by MQTT.fx
  4. Enter a message and click OK.
    Enter a message that you want to publish to the topic
  5. In the MQTT.fx tool, check whether the message is received.
    Check whether MQTT.fx receives the message
  6. Go to the Device Details page in the IoT Platform console. On the Device Log tab, click View. On the Device Log page, view cloud-to-device messages.
    Log data

Test upstream messaging

  1. Log on to the IoT Platform console. On the Product Details page, choose Topic Categories > Custom Topics. Then, find a custom topic that has the Subscribe permission.
    In this example, the /a1***/${deviceName}/user/get topic is used. You must replace the ${deviceName} variable with device1.

    For more information, see Custom topics.

  2. In the MQTT.fx tool, click Publish. In the Publish field, enter the topic that you specified in the previous step. In the editor, enter the message to be sent and click Publish.
    Publish messages in MQTT.fx
  3. Go to the Device Details page in the IoT Platform console. On the Device Log tab, click View. On the Device Log page, view device-to-cloud messages.
    View the message that MQTT.fx publishes to IoT Platform

View 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