Receiving MQTT messages by subscribing to MQTT topics
Back to Overview

IBM Knowledge Center
Learn how to use the MQTTSubscribe node to receive messages from an MQTT server.
Back To Gallery

Create the message flow and the device

Create a device that is connected to the IoT Foundation and will publish data on a topic that the message flow can subscribe to.

  1. On your smartphone/tablet/computer, start the simulator by browsing to http://quickstart.internetofthings.ibmcloud.com/iotsensor. The simulator connects automatically and starts publishing data. Keep your simulator window active and in the foreground.
  2. Note the MAC address of the simulated device (displayed in the top right corner of the device screen; for example AF:01:C7:BB:E5:72). You will need this to complete the configuration of the message flow.

Import and complete the configuration of the message flow.

  1. Click the Import button on the right of this view. The MQTTSubscribe application, which includes a partially complete message flow, will be imported into your workspace.
  2. The MQTTSubscribe message flow should be open in the Message Flow editor. If it is not, locate the message flow under the Flows section of the MQTTSubscribe application, and double click it to open for editing.
  3. Select the MQTTSubscribe node in the message flow and look at the Properties view.
    • Tip: To allow you to see the properties view and the tutorial steps at the same time, move this current tutorial steps view to the right side of the message flow editor, by dragging and dropping the Tutorial Steps View tab at the top of this view.
  4. Some of the MQTTSubscribe node properties have already been configured with values. The Host name and Port are configured to connect to the IoT Foundation MQTT server that is hosted on the internet.
  5. The Client ID property is blank and must be configured with a valid value. Enter the value a:quickstart:<unique-name> where <unique-name> is a value you choose that is unlikely to be chosen by anyone else. For example, you might choose your name and birth year to avoid clashing with other people, such as a:quickstart:hosie75.
    • You might like to know: In the MQTT protocol, the client ID is used to uniquely identify a device or an instance of an application that is connected to an MQTT server. Each device or application must specify a different client ID. In any particular instance of an MQTT server, there might be a defined convention to follow when choosing the client ID. In the case of the IBM IoT Foundation quickstart, the convention is that applications must specify a client ID with the form a:quickstart:<unique-name> where <unique-name> is a value chosen by the application to be unique across all applications connecting to the quickstart service. This convention must be followed, otherwise the application will fail to connect to the IoT Foundation.
  6. The Topic name property is blank and must be configured with a valid value. Enter the value iot-2/type/+/id/<deviceid>/evt/+/fmt/+ where <deviceid> is the MAC address of the device that you simulated in the earlier step, with the colons removed and all letters in lowercase. For example, if the MAC address of your device is C2:AC:80:42:DA:D7 then the Topic name must be entered as iot-2/type/+/id/c2ac8042dad7/evt/+/fmt/+.
    • You might like to know: When message data is published over MQTT, it is published on a particular topic. The topic string is hierarchical, and is normally used to indicate some categorization of the data that is meaningful in the particular domain. Receiving applications subscribe to particular topics and can use wildcards to subscribe to many topics within a single topic string. In the case of the IoT Foundation quickstart, the topic name includes the ID of the device that published the data. Subscribing applications must specify the device ID explicitly, although a wildcard (+) may be used elsewhere in the topic string, as shown in this tutorial.
  7. Save the message flow.
  8. Ensure that there are no errors associated with the message flow.

Find out more

Import

Deploy Application

Before deploying the application, you must ensure that the file system is ready for the data to be written to the output file by the message flow.

The FileOoutput node is configured to write the data to a file in the output directory C:\fileout

  • Create the output directory C:\fileout on your local file system, or change the Directory property of the FileOutput node to a directory that exists and that your current user ID has write access to.
    • If you are using Linux, then you probably will need to change the Directory property.

Once you have completed these steps, drag the MQTTSubscribe application from the Application Development view and drop it on an integration server in the Integration Nodes view. The application will be deployed to the integration server and the message flow will connect to the IoT Foundation, ready to receive the data published by your device.

  • If you have a firewall on your computer, you might be asked to allow the DataFlowEngine.exe process to connect to quickstart.messaging.internetofthings.ibmcloud.com. You must allow this connection in order to complete this tutorial.

Find out more

Follow these steps to complete the tutorial

The message flow will immediately start receiving data that is published by the device simulator that you launched in the Create step, and will write that data to a file in the directory that you created in the Prepare step.

Change some of the metrics (temperature/humidity) on the device simulator and open the output file to see new events with those values appended to the end of the file.

In addition to this, you can use the Flow Exerciser to inspect other publication information that is available in the message flow.

  1. Open the MQTTSubscribe message flow, and click the Flow Exerciser icon to start recording the message path through the flow.
    • Take care: If you have more than one integration server available, then you will have to choose which integration server to use to record this message flow. Ensure that you choose the same one that you deployed to in the Prepare step, otherwise you will have two separate instances of the message flow trying to connect to the MQTT server with the same client ID, and that will cause errors.
  2. Wait a few seconds to ensure that at least one event is published.
  3. In the Flow Exerciser toolbar, click the View Path icon View path to highlight the message path through the message flow. Click on the connection to see the message data that passed between the MQTTSubscribe node and the FileOutput node.
  4. In the Message tree of the data, you will see the Properties folder followed by a JSON folder, and this shows the same data that was written to the output file.
    • NOTE: the data is formatted as XML by the UI for the purpose of rendering it through the Flow Exerciser, but in fact it remains as JSON as it passes from the IoT Foundation, through the message flow, and into the output file.
  5. Expand the LocalEnvironment folder and you will see extra information about the publication. It is possible to add other nodes to the message flow that could process this information or even copy it to the output file.
  6. Click the Clean Up button at the top right of this page. If you do not do this then the message flow will continue to append data to the output file.

Find out more

Clean Up