MQTT integration

Allows you to integrate the ProGlove INSIGHT Mobile (Android) app with your system using the MQTT protocol.

Streams API is used to define events and messages that can be exchanged between your system and ProGlove apps. This way your server would be able to exchange messages with INSIGHT Mobile as the client.

To enable this connection, use our Config tool in INSIGHT to set up MQTT client and make the connection with your MQTT broker.

Devices and communication setup

Download the latest .apk version of the INSIGHT Mobile (Android) app and install it on your Android device.

Next, create a ProGlove.proconfig file by creating a device configuration for Android in the INSIGHT Config tool and set up all the required fields. Refer to the table below for more details about the available and necessary fields.

Once you have created the file, apply it to your Android device. This can be done in two ways:

Copy the ProGlove.proconfig file to the following location on your Android device: yourphone/InternalStorage/Android/data/de.proglove.connect/Files
Pair your scanner with the INSIGHT Mobile app and scan the QR code generated in the Config tool in INSIGHT to apply the configuration. Note that this QR code could be provided in any visual form, i.e. screenshot, digital image or a printed version.
Note
Due to limitations of Android 11, you can no longer copy files to the Android/data/de.proglove.connect folder using the Android device only or via MDM (Mobile Device Management). For earlier Android versions, downloading the .apk directly to the Android device still works. On Android 11, you can still use the adb push command to push or pull files or folders to Android/data/de.proglove.connect. Additionally, permissions for installing third party applications (unknown sources) must be granted on your Android device.

Protocol

When defining the Protocol within your Device configuration → Integration, there are several options you can choose from. See below for details.

Insecure TCP - This is an unencrypted connection and the default setting with 1883 as the default port.
SSL enabled - This enables encryption of the connection where the broker needs to present a valid SSL certificate trusted by the Android OS. The default port is 8883. In case of a self-signed certificate, follow this procedure to install it properly.
MQTT over WebSockets - This option is better suited for web applications and offers seamless and secure communication in diverse environments. The default port is 80.
MQTT over WebSockets with SSL - This adds encryption and ensures that the exchanged MQTT messages are secure. The default port is 44.

Next, enter the Host information and define the Client ID. You can enter a Client ID manually or keep the default option Connectivity device serial number as ID, which will retrieve the serial number of your Android device to serve as an identifier.

Both Client ID options affect the topic names, which you can further specify in the next section (see below).

Note

Using the same/duplicate Client IDs is not recommended and can result in connection issues.

Topic Options

You can choose to add a string as a Topic Prefix before the topic name, as well as enable sending messages to multiple topics by simply checking the box next to the Use topic per command and Use topic per event settings.

This feature supports sending and receiving messages to multiple topics even though, by default, Android devices use a single topic for the request commands and sending events. Each of these topics will then be expanded by the prefix and a hardcoded string ("gateway"), followed by the device serial previously specified in the Client ID field, as shown in the image below.

Note that the topic name will not expose the scanners' serial numbers. However, they will be included in the Stream API events and when parsing commands. For additional details, see Supported streams.

Connection options

These settings determine how your Android device connects and interacts with the MQTT broker, i.e. the server that handles message distribution.

Keep alive signal - Determines how long the broker will wait for the signal before assuming the device is offline. The default time is 30 seconds, but you can configure the timeout manually.
QoS (Quality of Service) - Controls how reliably messages will be delivered and there are three options to choose from:
- At most once - This is the default setting, and the simplest and fastest way to send messages. The device will send the message once and it does not depend or wait for the broker to receive it. Its mostly used for non-critical data where occasional message loss is acceptable.
- At least once - With this setting, the device will continue sending the message until it gets a delivery confirmation from the broker. Use it for important data, when you need to ensure the message is delivered.
- Exactly once - This option will guarantee the message is delivered to the broker, even when there are network issues. It is the slowest but also the most reliable option, which is used for critical data where duplicates are not accepted or would cause problems.
Clean session - Determines whether the broker should remember previous connections with your device.
- Disabled - This is the default setting allowing the broker to remember your device and any existing subscriptions. In case of a disconnection, any queued messages will be delivered once the device reconnects.
- Enabled - Each connection is treated as a brand new one, and the broker "forgets" any previous subscriptions or undelivered messages.
Authentication - Used with any type of protocol, this serves as a basic authentication method required to access your system.

Fields and sample messages

Field	Type	Description	Value example	Required / configurable
`Domain/IP Address`	String	The domain or address of the broker.	broker.MQTTdashboard.com	Mandatory / Yes
`port`	Integer	The port number to connect to the broker.	1883	Mandatory / Yes
`MQTT over Web socket`	Boolean	Which protocol to use. If `MQTT over Web socket` is disabled, tcp will be used and a `tcp://` prefix will be automatically added before the domain. If `MQTT over Web socket` is enabled, web socket protocol will be used and a `ws://` prefix will be automatically added before the domain.	false	Mandatory / Yes
`username`	String	Username	Proglove	Optional / Yes
`password`	String	The password to use in case the connection requires an authentication.	Proglove-scanX	Optional / Yes
`qos`	Integer	The quality of service to use for publishing and subscribing.	Exactly once	Mandatory / Yes
`topic_prefix`	String	This is an optional prefix to be included before every predefined topic (see below).	prefix/gateway/gw_id/request prefix/gateway/gw_id/event	Optional / Yes
`subscribe_topic`	String	A predefined topic that the broker should listen in order to receive events from client. In the example on the right, `gw_id` represents a unique identifier of the Gateway/Android that runs the client. If available, `gw_id` is Android device’s serial number. Since the serial number is not available on most of the latest Android OS versions, as a fallback - unique installation ID is used. Unique installation ID is created when app is installed, and it is preserved with the app updates. If app is uninstalled then installed again, new unique installation ID is created.	gateway/gw_id/event	Optional / No
`publish_topic`	String	A predefined topic to which the INSIGHT Mobile’s MQTT client is subscribed in order to receive the requests that should be executed. In the example on the right, `gw_id` represents some unique identifier of the Gateway/Android that runs the client. For more details about it see the `subscribe_topic` description.	gateway/gw_id/request	Optional / No

You can publish various Streams API request messages to for execution of the commands or to gather some information. Ensure these are all published on the same request topic (e.g. gateway/3a142769-95de-4c46-b38e-a4e97f315c57/request).

See below for example messages of scan events and scan requests:

Scan event message containing barcode data:

{
    "api_version":"1.0",
    "event_type":"scan",
    "event_id":"22d4a950-b373-42a3-8428-7a3887e78583",
    "time_created":1699621609245,
    "scan_code":"YVQGZZNSXU",
    "device_serial":"MDMR102104863"
}

Scan request message that will display data on the connected scanner's display:

{
   "api_version":"1.0",
   "event_type":"display!",
   "event_id":"02114da8-feae-46e3-8b00-a3f7ea8672df",
   "time_created":1546300800000,
   "time_validity_duration":5000,
   "device_serial":"MDMR000000064",
   "display_template_id":"PG3",
   "display_refresh_type":"DEFAULT",
   "display_fields":[
      {
         "display_field_id":1,
         "display_field_header":"Storage Unit",
         "display_field_text":"R15"
      },
      {
         "display_field_id":2,
         "display_field_header":"Item",
         "display_field_text":"Engine 12"
      },
      {
         "display_field_id":3,
         "display_field_header":"Quantity",
         "display_field_text":"10"
      }
   ]
}

Make sure that the device_serial value corresponds to your scanner's serial number.

Note that, in this example, the data will be displayed for exactly 5000 milliseconds, after which the scanner will continue displaying the previous screen. In order to remove the time limit, edit the time_validity_duration value to 0.

Additional information

For more information on Streams API, see supported streams.

Table 21. Feature availability

Devices	Subscription plan	Lifecycle status	Resources
MARK Basic, MARK Display, MARK 2 LEO, MARK 3 Gateway INSIGHT Mobile (Android)	INSIGHT Visibility, INSIGHT Analytics	Released	Firmware Release notes

Devices

Subscription plan

Lifecycle status

Resources

MARK Basic, MARK Display, MARK 2

LEO, MARK 3

Gateway

INSIGHT Mobile (Android)

INSIGHT Visibility, INSIGHT Analytics

Released

Firmware Release notes

In this section:

ProGlove Documentation

MQTT integration

Devices and communication setup

Note

Protocol

Note

Topic Options

Connection options

Fields and sample messages

Additional information

Search results