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 a device are created in the IoT Platform console. The device certificate is obtained. The certificate information includes the ProductKey, DeviceName, and DeviceSecret. 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

  1. Download and install the MQTT.fx tool. For more information, visit the official MQTT.fx website.
  2. Open the MQTT.fx tool, click Extras in the menu bar, and then select Edit Connection Profiles.
    Set MQTT parameters
  3. On the Edit Connection Profiles page, set the parameters.
    1. Edit the basic information.
      Edit the basic information of MQTT.fx
      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 for public instances 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****** indicates the ProductKey.
      • cn-shanghai indicates 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.
      • 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 parameters.
      • When you set parameters, make sure that you remove all spaces from parameter 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.

    2. Click the User Credentials tab. Set the User Name and Password parameters.
      Set the User Credentials parameters of MQTT.fx
      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 only a masked password. If the pointer moves to the end of a password after you paste the password in the Password field, it indicates that the password is pasted. Do not paste the password again.
      • Make sure that you specify valid uppercase and lowercase letters in parameter names and values.

      You can use one of the following methods to generate a password:

      • Download the generation tool . After you decompress the file, double-click the sign.html file.

      • Manually generate a password. You must perform the following steps:
        1. Concatenate the required parameters.

          Format of a string to be encrypted: clientId${clientId}deviceName${deviceName}productKey${productKey}timestamp${timestamp}

        2. Encrypt the string.

          Format of the encryption function: ${signmethod} (${deviceSecret},clientId${clientId}deviceName${deviceName}productKey${productKey}timestamp${timestamp})

      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 toolExample of generating a password by using the tool
      • Example of manually generating a password

        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.
    3. 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 on the SSL/TLS tab, and go to the next step.
      Set the SSL/TLS parameters of MQTT.fx
  4. Click OK in the lower-right corner.
  5. Click Connect.
    Connect MQTT.fx to IoT Platform

Test downstream messaging

To check the connectivity between the device and IoT Platform, send a message from IoT Platform and use the MQTT.fx tool to receive the message.
Note The MQTT.fx tool is a simulated device and supports transmitting non-passthrough data. To transmit passthrough data, you can use an SDK or test on an actual device.
  1. In the MQTT.fx tool, click the Subscribe tab.
  2. 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 Edit a topic category.

    After the subscription succeeds, the custom topic appears on the Subscribe tab.

    Custom topics are displayed on the Subscribe tab
  3. 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.
    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

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.

  1. In the MQTT.fx tool, click the Publish tab.
  2. In the Publish field, enter a topic that has the Publish permission. In the message editing area, enter a message to be sent. Click Publish to publish the message to the topic.
    Publish messages in MQTT.fx
  3. Log on to the IoT Platform console. Choose Maintenance > Device Log. You can view the message on the Cloud run log tab.
    View the message that is published to IoT Platform by MQTT.fx

View logs

In the MQTT.fx tool, click the Log tab. On the tab that appears, view operations logs and error logs.

View logs in MQTT.fx