Before You Begin

This tutorial shows you how to create and use the MQ Telemetry Transport (MQTT) Connector in Oracle IoT Production Monitoring Cloud Service.

Background

If your machines contain sensors that send data to a cloud service using the MQTT protocol, then you can on-board those machines to Oracle IoT Production Monitoring Cloud Service by creating an MQTT Production Monitoring Server Connector. You configure the connector with a set of machine types and their machines using a comma separated values (CSV) file and then, receive their telemetry data. The connector also has the ability to on-board new machines and their types dynamically based on the telemetry data received. Oracle IoT Production Monitoring Cloud Service has 3 options to on-board such machines and machine types:

1. Automatic: The option on-boards all machines and machine types when the connector is started.
2. Manual: The option lets you choose the machine types that need to be on-boarded.
3. CSV mapping: The option enables you to provide a CSV file containing specific machines that need to be on-boarded,

What Do You Need?

• URL and credentials to sign in to an Oracle IoT Production Monitoring Cloud Service instance
• Access to the MQTT Explorer tool
• Downloaded and saved Furnace.csv

Create a Factory

Before you create a connector, at least one factory should exist in your Oracle IoT Production Monitoring Cloud Service instance.

1. Sign in to your instance of Oracle IoT Production Monitoring Cloud Service.
2. The Map view of the Operation Center is displayed. Click Menu .
3. On the left navigation bar, click Design Center, and then select Factories.
4. On the Design Center: Factories page, verify that the details of a factory exists, note the Factory ID, and move to the next section. If no factories exist, then proceed to the next step of this section.

   

5. If a factory does not exist, click Add .
6. On the Factory page, enter the following details:
   • ID: SF Factory
   • Name: San Francisco factory
7. Note the Factory ID for later use. Click Save, and then click Back.

Create an MQTT Server Connector

You create an MQTT server connector in Oracle IoT Production Monitoring Cloud Service.

1. Click Menu , Design Center, and then Organization.
2. On the Organization page, click Connectors .
3. On the Connectors page, click Add .
4. On the Create New Connector page, enter or select the following details:
   • Name: mqtt_server_connector
   • Description: MQTT server connector
   • Type: MQTT Server
   • Onboarding mode: Automatic
   • Topic: data/#

     Note: If the machines would send messages to a different topic, you can change the default value of data/# to the specific topic name.

   • Machine Type Identifier: $(sys_mqtt_2)
   • Machine Identifier: $(sys_mqtt_3)

     Note: if the machine sends the data to the topic as data/<MachineTypeName>/<MachineId>.

   • Factory Name: SF Factory

   Note: The ID of the factory that you noted in the previous section.

   • Mapping File Name: Furnace.csv

     Note: Browse and select the specific CSV file that contains the machine type and its machine's definitions.

5. Click Save and then click Back.
6. On the Connectors page, verify that mqtt_server_connector is listed. Review the status of the connector and click Refresh until the status changes from Starting to Started.
7. For the connector, click Notifications . Review Content on creating machine types and machines.

   

8. To go back to the Connectors page, click Back.

Verify On-boarding of Machines

You verify that the MQTT Server connector has created machine types and machines in Oracle IoT Production Monitoring Cloud Service.

1. Click Design Center and then Machine Type .
2. Verify that a few machine types are displayed which are new and their names match with the names displayed on the Notifications page of mqtt_server_connector.

   

3. On the left navigation bar, click Design Center and then Machine .
4. Notice that the connector has created a set of machines whose machine types are the similar to those appearing in the connector's notification screen.

   

Send Messages Using MQTT Explorer Tool

You use the MQTT Explorer tool as a MQTT Client to send machine telemetry data to your Oracle IoT Production Monitoring instance. The user name that you'll configure in the tool should have the administrator role in your Oracle IoT Production Monitoring instance.

1. Launch the MQTT Explorer tool.
2. To create a new connection, click Add .
3. On the MQTT Connection page, select or enter the following values:
   • Name: my_mqtt_connection
   • Validate Certificate: Enabled
   • Encryption: Enabled
   • Protocol: mqtt://
   • Host: instance name.oraclecloud.com

     Note: Obtain the instance URL from the Connectors page of your Oracle IoT Production Monitoring instance, when you view your MQTT connector details.

   • Port: 8883
   • Username: mqtt_server_connector/IDCS username

     Note: Enter the name of the MQTT connector that you created in the Oracle IoT Production Monitoring instance followed by your identity management cloud service user name to access the instance. This user should have the administrator role in your Oracle IoT Production Monitoring instance.

   • Password: password

     Note: Enter the password to access your Oracle IoT Production Monitoring instance.

4. Click Save and then click Connect. Verify that the connection with the Oracle IoT Production Monitoring instance is successful.

   

   Note: During the MQTT server connector startup, Oracle IoT Production Monitoring instance used the information in furnace.csv and created a machine type Furnace and a machine F1,

5. On the Connection screen, in the Topic field enter data/Furnace/F1
6. From the radio buttons, select JSON, and in the text area beneath it, enter the following:.

   	{
      "t": 120,
   	  "p": "45.78",
   	  "h": true
   }

   Based on the information in Furnce.csv, you specify the values for the temperature, pressure, and humidity, which are referred as t, p, and h respectively, for the machine F1.

7. To send the data to the MQTT server connector of your Oracle IoT Production Monitoring instance, click Publish.

Review Device Messages

Verify that the device messages are received by your Oracle IoT Production Monitoring Cloud Service instance from the MQTT Explorer Tool.

1. Click Menu and then click Operation Center. The Map view appears.
2. On the map, locate and zoom in to the area where SF_Factory is located.
3. Click the Factory icon. On the floor plan of the factory click a furnace machine icon.
4. The dashboard of the furnace machine appears. On the navigation bar, click Machine Sensors .
5. On the sensor data graph, select Time Period as Live. Notice that the live values of the humidity and temperature attributes are displayed on the graph.

Perform Manual On-boarding of Machine Types

If you wish to selectively on-board specific machines types from the MQTT clients, you can configure the MQTT server connector to manually on-board the machines. During manual on-boarding, you need to opt for the machine types from the list of discovered machine types. You can also choose the machine type attributes that you wish to include from the list of available attributes of a machine type.

1. Complete the Steps of Section 2, Create an MQTT Server Connector. Ensure that in Step 3, you enter my_mqtt_connector_manual for the Name field, and select Manual for the Onboarding Mode field.
2. On the Connectors page, verify that my_mqtt_connector_manual is listed. Review the status of the connector and wait until the status changes from Starting to Started.
3. For the connector, click Notifications .
4. In the list of notifications, notice that in the Actions column, a check mark and a cross mark appears for each machine type. This allows you to accept or reject the discovered machine type. For a machine type, in the Actions column, click the check mark .

   

5. On the Attributes page, enable or disable the attributes, click Accept, and then Close. Repeat the step for all the device types that has been discovered and notified by the connector.

   

6. To verify that the machines are on-boarded successfully, complete the steps of Section 3, 4, and 5.

Upload CSV Files of Machine Types

While creating a connector, you can upload a CSV file to add specific machines of a machine type in Oracle IoT Production Monitoring Cloud Service. For each machine type, you need to create and upload a separate CSV file. In this section, you review a sample Furnace.csv that is used when the machine types does not exist in your Oracle IoT Production Monitoring Cloud Service instance.

1. To review the structure of a CSV file, open Furnace.csv. The diagram shows the components of the csv file.

   

2. Review the following from Furnace.csv:

   # @version : 1.0
   ,"Furnace", "temperature=payload.t", "pressure|STRING=payload.p", "humidity|BOOLEAN=payload.h"
   
   F1, "Furnace-1", , ,
   
   F2, "Furnace-2", , payload.press, ,
   
   F3, "Furnace-3", , , sys_mqtt.5:hum
   
   *, "Wild-Furnace-", , , 
   

   • The first line contains a CSV comment with an annotation (@version), which indicates the CSV file format's version. The version supported is 1.0. This is an optional annotation and when not present, the connector assumes version 1.0.
   • The second line contains names of column headings.
   • The first column heading is left blank. If machine types already exist in your Oracle IoT Production Monitoring Cloud Service instance or imported from Oracle Manufacturing Cloud, then add the machine type ID field name in the first column of the mapping file.
   • Second column heading is the name of the machine type, which is Furnace in the example. Third column heading onwards is a list of sensor attribute mappings. A sensor attribute mapping links a sensor attribute definition to a sensor value reference. Humidity and Temperature are attribute examples.
   • Sensor attribute definition consists of a attribute-name and optionally the associated datatype. If no datatype is specified, then the attribute's datatype defaults to NUMBER.
   • Sensor value reference, refers to where in the MQTT message the sensor value is sent. Two kinds of value references, payload and MQTT topic, are supported.
     • Payload - The reference contains the name of the JSON attribute that contains the value for the sensor attribute.
     • MQTT Topic - This reference contains a topic path segment number and a name that references the value. For example 5,hum indicates that the value for the sensor attribute is specified at the fifth segment of the topic and the topic segment name is hum.
   • In the CSV file, there are three sensor attributes, temperature, pressure, and humidity with value references to t, p, and h respectively in the JSON payload.
   • By default, when a CSV file is specified for the connector, the instance does not allow any new machine-type and machine to be created dynamically, based on the incoming telemetry. You can allow new machines to be created dynamically for the machine-type specified in the CSV file by specifying the following line: *, , . This allows the connector to create a new machine when telemetry arrives for the machines that the connector has not seen before. In the sample CSV file,, *,"Wild-Furnace-", , , will create new machines with name Wild-Furnace- as the prefix.

     Note: A new machine-type never gets created dynamically with the incoming telemetry. Only machines get created and associated with the machine-type mentioned in the csv.

3. Review the sample telemetry data sent by the machines that are defined in Furnace.csv.

   Machine ID	Machine Name	MQTT Message	Sensor Value References
   F1	Furnace 1	PUB data/Furnace/F1 { "t" : 75.32, "p" : "45", "h" : true }	"temperature=payload.t", "pressure|STRING=payload.p", "humidity|BOOLEAN=payload.h"
   F2	Furnace 2	PUB data/Furnace/F1 { "t" : 75.32, "press" : "45", "h" : true }	"temperature=payload.t", "pressure|STRING=payload.press", "humidity|BOOLEAN=payload.h"
   F3	Furnace 3	PUB data/Furnace/F1 { "t" : 75.32, "p" : "45", } PUB data/Furnace/F3/sensor/hum false	"temperature=payload.t", "pressure|STRING=payload.p", "humidity|BOOLEAN=payload.hum"
   WF1	Wild Furnace 1	PUB data/Furnace/F1 { "t" : 75.32, "p" : "45", "h" : true }	"temperature=payload.t", "pressure|STRING=payload.p", "humidity|BOOLEAN=payload.h"

4. To upload the CSV file, create a connector by completing Steps 1-10 of Section 2, Create an MQTT Server Connector.
5. In the Specifications section, click upload, browse to the folder where you have saved the CSV files, select Furnace.csv, and click Open.

   

6. Click Save and then click Back.
7. The machine type and the machines from the MQTT Clients that correlate to those defined in the CSV file gets added to your instance. Perform the steps of Section 3, Verify On-boarding of Machines to review the machine type and machines added to your Oracle IoT Production Monitoring Cloud Service instance.

Want to Learn More?

• Connect to External Systems
• Create and Manage Connectors