Introduction

This document presents the Wirepas MQTT Console, a web based utility which allows to communicate with Wirepas based gateway(s) connected to an 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
  • Opened ports: 9001 and/or 9002 must be opened on the PC / firewall
  • A modern web browser
    1. The tool was tested to be functional on Mozilla Firefox, Google Chrome, Microsoft Edge and Safari
    2. 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:
    1. Can be local or remote
    2. Communication over Secured WebSocket or WebSocket
    3. Optional:
      • A Wirepas NMS backend (it provides a secured MQTT broker)
      • The Wirepas pre-built Raspberry Pi images provide a local MQTT broker
  • A Wirepas Mesh Network with:
    1. A gateway compatible with Wirepas Gateway to Cloud API.
    2. At least, one Sink attached to the Gateway
    3. Optional:
      • Nodes in the same network as the sink

Tool overview

Wirepas MQTT console is a 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’s 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, such as:
    1. traffic statistics i.e total uplink and downlink messages received/sent at the MQTT broker level
    2. total node count discovered i.e from which a message was received
    3. number of gateway connected (currently or at some point) to the MQTT broker
  • allows to:
    1. know the online status of all the gateways connected to the MQTT broker
    2. retrieve sink(s) configuration, its OTAP and stack related information
    3. remotely configure sink(s) i.e network parameters, diagnostics interval, application configuration data
    4. monitor traffic sent/received to and from the Wirepas mesh network i.e Uplink and Downlink traffic and
      • Data filtering
      • Metadata filtering
    5. list all nodes seen (from which a message was received on the MQTT broker) with some metadata such as:
      • 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
    6. 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.
    7. Export data in CSV format for data analysis
    8. Execute OTAP (programming devices over-the-air): upload a scratchpad, propagate and process a scratchpad (with or without a delay) and disable OTAP via the interface. It supports both OTAPv2 and legacy OTAP.

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
    1. If connection is OK then the following will be displayed

  1. If connection is not OK or the tool is disconnected then the following will be displayed

  1. A left click on this status area will open the MQTT Connection menu
  • on the bottom left corner the tool version is available as an hexadecimal value.

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 organized 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.

The available parameters are:

  • Address (MQTT broker address)
     This is a string.
  • Port (MQTT broker port)
     This is a number.
  • SSL (should secured websocket be established)
     This is a checkbox.
  • Optional: Username (MQTT username)
     This is a string. To be used if secured websocket is used.
  • Optional: Password (MQTT password)
     This is a string. To be used if secured websocket is used.

Once all are specified a click on the “Connect“ button will trigger the connection to the MQTT broker.
Similarly 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 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 URL address.
The base URL is https://wirepas-tools.github.io/mqtt-console/master/
Connection URL 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.
Gateways 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 the sinks associated to the gateway and some configuration menus.
 For offline gateways the following will appear:

The fact the gateway is Offline is stated and, if the gateway is not in use anymore or renamed, clicking on the cross will remove it from the list. In fact it will clear its retained MQTT status message on the broker.

For online gateways, it will list sinks connected to it so as some information about the gateways themselves (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 five sections Node Configuration, Application and Diagnostics Configuration, Configuration Data, Node information and Otap & Scratchpad status. Clicking 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 refresh the sink configuration a left click on the “update sink config” button is required. If the parameters values revert back to their previous value it means the configuration failed.

Under Application and Diagnostics Configuration, the diagnostics interval and 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.

Under OTAP section, it is possible to upgrade the devices in the network. From here, it is possible to upload a scratchpad and change the OTAP action:

  • NO_OTAP to disable the propagation of the scratchpad (if a new node becomes online in the network, it will not be upgraded)
  • PROPAGATE_ONLY to only transmit the scratchpad (the devices will not apply the update)
  • PROPAGATE_AND_PROCESS to apply immediately the update as it is received by each node
  • PROPAGATE_AND_PROCESS_WITH_DELAY to apply update after a delay (e.g. after all the devices received the update to reduce downtime or synchronize a stack change)
  • LEGACY_OTAP to do the upgrade using legacy protocol (for stack version 5.0 and below).

Additionally, you can get information about the scratchpad status on the sink and the scratchpad uploaded.

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 network ID
  • Source Address : Mesh address of the node ID emitting the message
  • Destination Address : Mesh address of the receiver(s). 
    1. Uplink: sink address
    2. Downlink: can be Unicast, Multicast and Broadcast
  • Endpoint source and destination
  • Quality of Service: should the message be prioritized in case of data traffic overload
  • 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 (from its source to the sink)
  • Payload Size: Size in bytes of the payload

*Note that this sink ID reflects the ID provided by the Gateway to identify the sink connected to it, and not the sink Mesh ID.

You can apply filters to select the messages to display:

Multiple 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 text field starting 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.

Important notice: you must pay attention to the naming and avoid any error in the IDs. Namely, white spaces are not filtered so extra caution when copying/pasting data to here (“MyGateway “ does not work but “MyGateway” does). 

Nodes page

This page displays the list of nodes that are seen by the MQTT broker, the Wirepas MQTT Console is connected to.

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

Revision History   

Date
Version
Notes

0.9

The first version.

1.0

Restarted the overall writing of the document

1.1

Replace WNT references with Wirepas NMS as new backend component

1.2

Update OTAP section

Legal Notice

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

Copyright © 2026 Wirepas Oy