IoT-Connector (Aka Product) Quickstart

In this quick-start, you will use MQTT Spy, a GUI-based tool to simulate a connected IoT device. MQTT Spy is an open source utility intended to help you interact with cloud services using MQTT protocol.

This example is based on the Murano MQTT Device API and we invite you to have a look to the reference page along with this guide.

Table of Contents


Setup

Cloud Setup

Create an empty Murano IoT-Connector product.

Hardware Setup

You will use the MQTT Spy in this guide. The purpose is to quickly show you how to connect to our cloud without any single line of coding. If you want to try with scripting language or even lower level hardware (embedded system level), check out the device APIs page.

Client Software Setup

Download the latest version from MQTT Spy Release page and follow the instructions on MQTT Spy Getting Started Guide.


Configure Murano IoT-Connector

In this section, you will learn to configure your Murano IoT-Connector in MQTT protocol in order to connect with your MQTT Spy, which acts as a simulated device.

We assume here you already have a Murano Iot-Connector created (if not, please go back and check the Cloud Setup).

In your web-browser, navigate to your IoT-Connector on the Murano 'Home' solution list page and click on it.

Connector list

Configure Protocol

Go to Settings -> Protocol and set 443 as your MQTT Port

mqtt port

Configure Auth Method

Go to Settings -> Provisioning -> Authentication and select Token as your Authentication.

token auth settings

Find out more about Connectivity Settings here.

Get the Connector Domain

Click the top left icon to copy the domain, i.e. murano:v1/mqtt://r1ll7tt5olb400000.m2.exosite.io and then remove the prefix murano:v1/mqtt:// and append with the port number :443, resulting as i.e. r1ll7tt5olb400000.m2.exosite.io:443.

Copy id btn

Define Your Device Resources

For General Use

Go to the Resource management page and define the following resources:

Add number resource

Note: Optionally, you can restrict these resources to specific Possible Values, i.e. environmental sensor information normally won't be set from cloud to the device.

resources 4

Find out more about Murano Resources here.


For ExoSense™

ExoSense™ uses a dedicated data structure allowing different data model per device. For this purpose 3 main resources are used all of type String:

So you would define the temperature in config_io resource as follow:

{  
  "channels": {
    "temperature": {
      "display_name": "Temperature",
      "description": "Value sent by the sensor",
      "properties": {
        "data_type": "TEMPERATURE"
      }
    }
  }
}

And the device would need to send the defined channels to the data_in resource as:

data_in={"temperature":42}

The write operations to the above resources could be done through either HTTP or MQTT device APIs.

Read more about ExoSense™ Data-model on:


Configure MQTT Spy

In this section, you will create an MQTT simulated device using MQTT Spy.

Create a New Connection

Add number resource


Configure Connectivity Tab

Connectivity tab

Please fill out the fields in the picture with the configurations shown in the following table

Field Value
Protocol Version MQTT 3.1.1
Server URI(s) i3b4kppfef8k00000.m2.exosite.io:443
Client ID [Empty]

Configure Security Tab

Security tab

Please be noted that there is no need to fill out the fields in the picture at this moment, before an MQTT device is being provisioning.

Field Value
User name [Empty]
Client ID [Empty]

Security tab

Field Value
TLS/SSL mode CA certificate
Protocol TLSv1
CA certificate file Download Here

Configure Publications Tab

mqtt_spy_publications_tab

Create MQTT topics for provisioning and publishing. Take an use case for an example, we are going to provision your MQTT device ID named mqtt101, and your device is designed to report humidity/temperature/state/uptime, so you will need topics named humidity, temperature, state and uptime for later use for publishing.

Note that the device ID should be a globally unique identifier for your device, usually it could be the MAC address of your device’s network interface, or a serial number from the manufacturer.

Topic Name Use
$provision/mqtt101 for provisioning an MQTT device with name mqtt101
$resource/humidity for publishing to humidity topic
$resource/temperature for publishing to temperature topic
$resource/state for publishing to state topic
$resource/uptime for publishing to uptime topic

Configure Subscriptions Tab

Please be noted that in Murano, device resource subscriptions are managed centrally. This means an MQTT device is not allowed to use the subscribe command; instead, it will automatically receive updates for resources according to the IoT-Connector configuration.

Subscriptions tab


Let's Have Fun

Up to this point, you have already have everything you need to connect to our cloud. In this section, you will learn go through the three main operations of our cloud service over MQTT: provision, publish and receive data.

MQTT Operations

Provision

Select $provision/mqtt101 and click publish

provisioning

If the device provisioning succeeds, it will return with a token.

provisioning

Left click on the tab and select Show broker's statistics to make the token copy-able.

provisioning

Copy the token and make sure you back it up in somewhere.

provisioning

Again, launch to your IoT-Connector Page. Click on the device tab to see the device you just provisioned and click on the device to check if its Resources are shown as you defined previously.

provisioning

provisioning

You now have a simulated IoT-Connector device created on Murano.


Publish

Go back to MQTT Spy configuration, in Security Tab, set mqtt101 in User name and the token you copied at provisioning success in Password. And then click on close and re-open existing connection to reconnect with the latest configurations you just made.

provisioning

Publish 56.32 to humidity topic

provisioning

Check if the resource humidity changes accordingly.

provisioning


Receive data

Since MQTT supports bi-directional communication, try to set the state resource manually and see how it shows up on the MQTT Spy. Let's try to set (0, 1, 0, 1, 0, 1, 0, 1).

provisioning

Check the result on MQTT-Spy and see if it changes as expected.

provisioning

Now you have know all the trick you can do over MQTT, let's move on how you can get a quick visualization on your cloud.


Create a Dashboard

In this section, you will create a dashboard to visualize the data from your simulated device remotely.

  1. From the Devices tab for the desired device, click the ACTIONS button and select "View dashboard".

    Device dashboard btn

  2. Click + ADD PANE to house the widgets you will create.

    Device dashboard

  3. In the pane that appears, click the plus sign "+" to add a widget.

    Device dashboard add

  4. In the widget popup that appears, select "Toggle Switch" from the TYPE drop-down menu and complete the remaining fields (TITLE: "Off / On"; VALUE: "resources["state"]"; ON VALUE: "On"; OFF VALUE: "Off"). Click SAVE.

    Toggle

  5. Toggle the on / off for the simulated device using the switch on your dashboard.

    Device dashboard 3 charts

  6. This will send a command value to the state resource and your device should react accordingly, which resulting the same as in the receive data section previously.

Congratulations, you just remotely turned a simulated device sensor on and off!


Next Step

Now that you have a basic understanding of Murano connectivity, you can get forward by: