Introduction

This document presents the Wirepas MQTT Console, a web based utility to connect to a Wirepas MQTT Broker. This is a development and debugging tool which allows to:

  • connect to an MQTT broker
  • configure a Wirepas gateway and connected sinks
  • monitor online status of nodes in a Wirepas Mesh Network
  • monitor, display and record the Wirepas mesh data traffic coming from nodes

What you'll learn

  • How to use the Wirepas MQTT Console

Requirements

To start using the Wirepas MQTT console, you need some basic requirements and have a Wirepas Mesh Network to monitor.

So, you will need:

  • An internet connection
  • A modern web browser
    • The tool was tested to be functional on Mozilla Firefox, Google Chrome, Microsoft Edge and Safari
    • To get the best user experience it is recommended to use it on a large screen (e.g from a computer or a tablet).
  • An MQTT Broker:
    • Can be local or remote
    • Can be secured or not
    • Optional:
      • A WNT backend, version 4.x (it provides the MQTT broker in a secured )
      • The Raspberry Pi image provides a local MQTT broker
  • A Wirepas Mesh Network with:
    • A gateway compatible with Wirepas Gateway to Cloud API.
    • At least, one Sink attached to the Gateway
    • Optional:
      • Nodes in the same network as the sink

Tool overview

Wirepas MQTT console is an Open Source Tool made available by Wirepas. 

It can be accessed two ways:

The web browser version is to be preferred to always access the latest version of the tool.

The downloaded version is to be used when a non-secured MQTT broker needs to be accessed. In practice, as the web tool is hosted on an HTTPS domain, web browsers prevent downgrade of security. To use the downloaded version, extract the downloaded ZIP and open the index.html in a web browser. 

Upon loading the below listed interface is displayed.

This tool main purpose is to ease the development and the debugging phase of a Wirepas based system. It can to some extend also be used during troubleshooting.

The Wirepas MQTT Console:

  • gives some overall information about the system
    • traffic statistics i.e total uplink and downlink messages received/sent at the MQTT broker level
    • total node count discovered i.e from which a message was received
    • number of gateway connected (currently or at some point) to the MQTT broker
  • allows to
    • know the online status of all the gateways connected to the MQTT broker
    • retrieve sink(s) configuration, its OTAP and stack related information
    • remotely configure sink(s) i.e network parameters, diagnostics interval, application cofiguration data
    • monitor traffic sent/received to and from the Wirepas mesh network i.e Uplink and Downlink traffic
      • Data filtering is also available for instance to only see message sent/received from a specific gateway
      • Filtering is possible on the message metadata i.e Gateway, sink, Network address, source and destination endpoints, source and destination address
    • lists all nodes seen (from which a message was received on the MQTT broker) with some metadata
      • from which gateway and sink it was connected to
      • when was received its last message
      • number of message generated by this node since the tool is connected
    • record and restore a session
      A session contains all the information captured i.e all what is listed above when the tool was connected to an MQTT broker.
       It can especially be useful if you face some issue and you need to contact Wirepas support to get some help.

On the user interface:

  • The UI is reactive, hence on small screens, the Burger Menu lets you open the Main Menu. 
  • on the top right corner a connection status displays the tool connection status to the MQTT broker
    • If connection is OK then the following will be displayed

  • If connection is not OK or the tool is disconencted then the following will be displayed 

  • A left click on this status area will open the MQTT Connection menu
  • on the bottom left corner the tool version is available

The following sections will describe in detail the different menus available in the Wirepas MQTT Console tool.

Overview page

This is the default page displayed when loading the Wirepas MQTT console tool.
It lists the connection status to the MQTT broker (see MQTT Connection section for more information) and some overall statistics (see Network statistics section for more information).

MQTT Connection

This area will give the Wirepas MQTT console tool connection status i.e connected and for how long or disconnected to an MQTT broker and to which one.
 The interface is organised as follow

When it is not connected to any broker the following is displayed

When it is connected to an MQTT broker the area will look like this

A left click on the dark grey part will open the MQTT broker connection setting page (see MQTT Connection page section for more information).

Network statistics

This area will give some statistics about total traffic received by the Wirepas MQTT Console tool for the session duration.

The “Message“ tile will report the total count of Uplink packets (UL field) received by the MQTT broker from all the Wirepas mesh network connected to the MQTT broker. It will also report in the same manner the total count of Downlink packets (DL field).
A left click on the tile will open the Message menu (see Message page section for more information).

The “Nodes“ tile will report the node count seen (based on the source address of decoded messages) by the Wirepas MQTT console tool since the beginning of the session.
A left click on the tile will open the Nodes menu (see Nodes page section for more information).

Finally the “Gateways“ tile will report the total count of gateway recorded by the MQTT broker regardless of their status i.e online or offfline.
A left click on the tile will open the Gateways menu (see Gateways page section for more information).

MQTT Connection page

There are two ways to configure the Wirepas MQTT Console tool to connect to a given MQTT broker

  • via the “MQTT Connection“ page
  • via the URL

Both methods will be described in this section.

Graphical User Interface connection

The MQTT Connection page is as follow

It allows to configure all the required parameters to connect to a given MQTT broker.
Once all are specified a click on the “Connect“ button will trigger the connection to the MQTT broker.
Similarily the “Disconnect“ button will terminate the connection.
The “Session log“ area will be populated and list all connection/disconnection event and when they occured.
 The “Reset form“ button allows to clear all parameters fields to their default value.

URL based connection

Alternatively the tool support URL based parameters which means you can directly configure it to connect to a specific broker (and quickly switch from one configuration to the other) via the address.
The default URL format is https://wirepas-tools.github.io/mqtt-console/master/
Connection related parameters can be specified after the character “?“ appended to the base URL and separated by “&“ like this
https://wirepas-tools.github.io/mqtt-console/master/?param1=somevalue1&param2=somevalue2

The available parameters are

  • host (MQTT broker address)
     This is a string.
  • port (MQTT broker port)
     This is a number.
  • ssl (should encrypted connection to MQTT broker be established)
     This is a boolean.
  • user (MQTT username)
     This is a string.
  • pwd (MQTT password)
     This is a string.
  • connect (should connection to the MQTT broker be established)
     This is a boolean.

To connect upon page loading to MQTT broker hosted at mymqttbroker.com, on port 9002, with ssl under user user1 with password user1password the URL will be

https://wirepas-tools.github.io/mqtt-console/master/?host=mymqttbroker.com&port=9002&ssl=true&user=user1&pwd=user1password&connect=true

Gateways page

This page lists all the gateways (either online or offline) recorded by the MQTT broker. It also allows to retrieve and manage sinks configuration/status which are connected to the selected gateway.
Gateway are identified by their ID i.e. their MQTT client name.
 Online gateways will be displayed in green while offline ones in grey.

A left click on a gateway name will display a new menu.
 For offline gateways the following will appear

The fact the gateway is Offline is clearly stated and a left click on the cross will remove it from the list. In fact it will clear its retained MQTT status message on the broker.

For online gateway, it will list sinks connected to it so as some information about the gateway itself (model and version as reported over the Wirepas Gateway to Cloud API) as shown below.

From that point a left click on any of the listed sink will give access to its related option aggregated under 4 sections Node Configuration, Application and Diagnostics Configuration, Otap & Scratchpad status and Node information. A left click on the section title will either expand or collapse it. The image presents how the menu looks like and is provided for illustration purposes.

Under Node Configuration all related mesh network parameters can be (re)configured so as the stack state, node role and Operating mode. To update the sink configuration a left click on the “update sink config“ button is required. If the parameters values reverts back to their previous value it means the configuration failed.

Under Application and Diagnostics Configuration, the diagnostics interval so as the Application Configuration Data can be managed. A left click on the “update app config“ button will send the new configuration to the sink. Again if the the action fails the former values will be displayed again.

Under Node information, some Wirepas stack related information will be listed.

Finally under Otap & Scratchpad status, information about the scratchpad stored on the sink will be listed so as the OTAP action (if the stack version support OTAPv2). The OTAP action configuration is not available at the moment .

Message page

This page displays in real-time or not all the messages received by the MQTT broker. 

For each message displayed, different metadata are displayed:

  • Uplink (arrow up) / Downlink (arrow down)
  • The Timestamp of the PC (on which you operate the Wirepas MQTT Console)
  • The Gateway ID / The sink ID / The node ID
  • Source Address : Mesh address of the node ID emitting the message
  • Destination Address : Mesh address of the receiver(s). This can be Unicast, Multi cast and Broadcast
  • Endpoint source and destination
  • Quality of Service: should the message be reliable or not
  • Hop Count : number of routers the message has gone through to reach the sink.
  • Travel Time: Time the message has spent in the Wirepas Mesh Network
  • Payload Size: Size in bytes of the payload

You can apply filters to select the messages to display:

  • From which Gateway
  • From Which Sink ID (be aware that in case of many Gateways, the sinks may have the same ids)
  • From which Network
  • From which Node
  • To which address
  • From which sxource endpoint
  • To which source Endpoint

Different filters can be added and will be applied to the original set of messages.

Using the underneath fields, one can also send messages through the MQTT API. 

One need to set the Gateway ID, the sink ID, the destination address precising the Unicast, Multicast or Broadcast type, the endpoints and the reliability of the message. THe textfield strating with 0x allows to send raw data in hexadecimal format.

To avoid/enable the message auto-scrolling, you can deactivate/activate the Live Update.

The “Export CSV” button allow to save all the received messages from the beginning of the session, with all filters applied. 

Nodes page

This page displays the list of nodes that are seen by the broker. 

This page allow for live update of the node statuses.

Session page

This page allows to save and restore a complete session without filters applied to the stored messages. 

Save button allows to save the complete session. The file extension of the saved session is .session.

Choose file button allows to select a session file to Restore

Legal Notice

Use of this document is strictly subject to Wirepas’ Terms of Use and Legal Notice.

Copyright © 2024 Wirepas Oy