MQTT Toolbox – MQTTInspector

Guest blog post by: Christoph Krey

Short Profile

Type iOS App
License GPL source,
App Store $1.99
Operating Systems iOS
Website https://github.com/ckrey/MQTTInspector/

Description

Like many other awesome ideas, MQTTInspector is the result of a meeting with @jpmens at the best indian restaurant in Düsseldorf (#currybeer).

In 2013 we were starting with OwnTracks, the location tracker based on MQTT and felt the need for a monitoring tool which can be used while on the road on our iPhones or iPads. Now it has become available for all developers using MQTT with an iOS device.

MQTTInspector is based on the same MQTT-Client-Framework we use for OwnTracks which is by now very widely applied in iOS applications.

The app is written in Objective-C, is open source and I am happy to accept contributions. To
pay for the Apple Developer license, I ask $1.99 for it in the app store.

Feature Overview

MQTT 3.1 ok
MQTT 3.1.1 ok
LWT ok
SSL/TLS ok
Automatic Reconnect nok
MQTT over TCP ok
QoS 0 ok
QoS 1 ok
QoS 2 ok
Authentication ok
Scripting nok
MQTT over Websockets nok

Unique Features

  • Runs on your mobile device, wherever you are
  • Gives you access to messages, a topic view and inspects the protocol level
  • Filters messages on topic, message content or MQTT flags
  • Stores received messages for later review on all detail levels
  • Remembers your favorite broker, subscription, publish and filter settings
  • Shows messages content as JSON or text if appropriate
  • Connects via plain TCP, TLS or over Websockets
  • Auto connects to brokers and supports persistent sessions (cleansession=NO)
  • Configuration is possible via http or email configuration file

Setup

Install MQTTInspector form the App Store for iPhones or iPads running iOS 8.4 or higher.

The app sells for $1.99 or equivalent.

Start MQTTInspector and see the entry screen. To select a session, press „< Sessions“. The version of MQTTInspector (2.1.0) is displayed in the top right corner. MQTTInspectorSetup

For first time users, the app comes with two pre-configured test session with openly accessible brokers you can use to get the first impression of the app.

MQTTInspectorSetup2

Select one of the session to switch to the message display again.

MQTTInspectorSetup3

On this screen you see the defined subscriptions (left top), publish messages (left bottom) and the message area (right). To connect to the broker, press the ► button.

MQTTInspectorSetup4

The title will change to indicate detailed connection parameters. If you want to disconnect again, press the ✖ button.

Screen Shot 2016-02-22 at 12.48.03

The screen divider between the three areas can be dragged to split the screen in the way which is most suited for you. In addition to the draggable divider, the screen layout can be toggled between the „top left / bottom left / right“ layout to „top left / top right / bottom“ by a long tap in the message area and the device supports all interface orientations.

Message View

MQTTInspectorMessageView

To subscribe to one of the topics, tap on it. A successful subscription is indicated with a ✓ mark.

In the message area the incoming messages are displayed. The messages are colored according to the color of the most significantly matching subscribed topic. You may switch between T-opic, M -essage and proto-C-ol view in the message area. The number displayed indicates the number of different topics, publish messages or protocol messages captured.
The app stores up to the last 256 different topics, the last 512 publish messages and 1024 protocol messages.
You can scroll through the lines in the three display areas. The button button clears all the message data for this session. The progress bar indicates the processing status of incoming messages. You may pause processing of incoming messages with the switch to freeze the screen.

MQTTInspectorMessageView2

In topic view you see the topics in alphabetical order with a flashing red indicator when a new message arrives on the topic. The message content is shown with the date of arrival, the topic, QoS level, Retain flag, message Id, the length of the payload in brackets and the number of messages received for the topic (#).

MQTTInspectorMessageView3

In message view you see the messages in descending chronological order. The message content is shown with the date of arrival, the topic, QoS level, Retain flag, message Id, and the length of the payload in brackets.

MQTTInspectorMessageView4

In protocol view you see the protocol message length in brackets and the message in hex format including headers, etc. Outgoing and incoming messages are labeled and colored to easily tell the direction. The information part includes the time of arrival, direction label, the decoded message type and the Duplicate flag, the QoS level, the Retained flag and the message Id.

Publishing

MQTTInspectorPublishing

Press the Screen Shot 2016-02-22 at 13.09.43 button to get the Ad Hoc publish screen. You can override the topic and data and set the desired QoS level and Retail flag for the publish. To actually send, hit the PUBLISH button on the top right. You may use the placeholders %t and %c in your data, which will be replaced by the current timestamp (unix epoch) or the MQTT client id.

MQTTInspectorPublishing2

The screen returns to the message screen after you pressed publish. You will see the publish if you are in the protocol view or if you have subscribed to the topic you are publishing to. The last ad hoc publish is stored is stored in the publish view. To republish the same message, just tap on „“.

Detail Message View

DetailMessageView

Pressing the ℹ︎ button for a message opens the message in a separate view which allows to see the complete message content. This content is displayed in hex for protocol view.

DateilMessageView2
DetailMessageView3

For topic or message view, the message is displayed as an UTF8 decoded string or decoded, pretty formatted and sorted JSON. You may switch between UTF8 and JSON display.

Configuration

Configuation

If you want to delete sessions from the list, simply swipe left on the table row and confirm by pressing „Delete“.

Select the ℹ︎ button to change the settings for a session or use the button to create a new session configuration.

Configuration2

You may use the Screen Shot 2016-02-22 at 13.21.16 button to export the current session configuration for archiving or to transfer it to another device. Simply mail a configuration file (.mqti) to another device running MQTTInspector and open it from the mail application.

The Name of the session is used as an identifier on the overview screen.

Subscriptions, publish and filter presets can be managed by pressing the corresponding ℹ︎ button.

Use the host name or IP address to identify the host. Specifiy a port number to connect to.
Select whether you want to use TLS or not. Actioning the switch will put the defaults 1883 / 8883 into the port number. If you selected TLS, you may tell the app to allow to connect even if the MQTT broker returns an untrusted certificate. Select if you want to run the MQTT connection over Websockets.

Configuration3

You may enter a specific client ID. If you leave the field empty, a random client Id will be generated. Select if you want to tell the broker to clean previous session information with the same client ID. If you wish you can specify a keep alive interval other than the default 60 seconds.

Selecting auto connect causes the app to connect to the broker as soon as you select the session name from the overview.

Protocol level specifies the use of MQTT 3.1 (= 3) or MQTT 3.1.1 (= 4). Any other value will probably be rejected by the broker.

Size limit allows you to process only the given number of octets of incoming payloads.

If you select auth, the user and password given here are used when connecting the the MQTT broker.

Configuration4

For subscription and publish presets the same general editing commands as for sessions are available. Swipe left to delete a preset, press the ℹ︎ button to edit details and use the button to create a new preset.

Configuration5

For subscriptions you can specify a topic and a subscription QoS level.

Configuration6

For publish presets, you specify the payload data with the option to use placeholders as described above and the Retain flag.

Configuration7

One filter can be specified per session configuration. It is applied to all incoming messages. A regular expression is evaluated agains the topic, the attributes and the data. In the example above only messages with topics matching „abd“, and using QoS 2 and a payload starting with „start“ will be processed.
If include is selected, only messages matching all criteria are processed, otherwise those are excluded.

Author Information

ChristophKrey
Christoph Krey | OwnTracks UG
Christoph Krey is a freelance network application specialist who designs and implements client/server solutions in corporate environments since 1983. After a career in IT Management, he began his focus on protocols, mobile devices, and distributed applications. Christoph Krey maintains the MQTT client framework and has created MQTTInspector and OwnTracks for iOS.
  Website

2 comments

  1. Amey Kshirsagar says:

    Is it true that iOS MQTT client works only on WiFi and not on mobile data??

    1. Hi Amey,

      The MQTT Inspector works on WiFi and on mobile data.
      How did you get to the conclusion that it is not working on mobile data?

      Hope that helps,
      Christian from the HiveMQ team

Leave a Reply

Your email address will not be published. Required fields are marked *