Skip to main content

ProGlove Documentation

Connect Gateway to your network using MQTT integration

The MQTT integration path lets you connect the Gateway to your enterprise network. This is done using a network.json file with your network's credentials, and an mqtt.json file containing your MQTT integration settings.

The easiest way is to enter all details directly in the INSIGHT webportal while creating your Device Configuration. This allows you to add and define all the relevant parameters in a single place, and automatically create fully functional files that are ready for immediate use. You can then apply the configuration directly in INSIGHT by simply scanning a QR code, or apply it manually by transferring the files to your Gateway device.

If you prefer the manual process, you can still create your own network.json and mqtt.json files and add any relevant details using the main fields and examples provided below. Zip the files with any required certificates together in a .zip archive file, and upload it to your Gateway as a mass storage device.

Note

Read more about uploading files to the Gateway while in Mass storage mode.

Example 2. Example of the provision.zip file structure

  • provision.zip

    • mqtt.json

    • network.json

    • File 1 (e.g., ca_cert.pem )*

    • File 2 (e.g.,cert.pem)*

    • File 3 (e.g., key.pem)*

*This is required only for self-signed certificates or certificates that were signed by an unrecognized authority.



mqtt.json file configuration

To configure the MQTT integration add the fields described below to the mqtt_client namespace.

To get a better understanding of how to configure the mqtt.json fields, see the examples below.

Create a simple unencrypted mqtt.json file for configuration

  1. Open a text editor (E.g. Notepad, Sublime Text, VS Code)

  2. Copy the snippet below into the editor.

    {
    "mqtt_client": {
        "domain": "proglove.de",
        "client_id": "client-1234"
    }
}

    Note

    For additional configuration, see the main fields below.

  3. Under domain, type in the URL or the IP address of the MQTT broker you want to connect to.

  4. Under client_id define the client identifier to be used with the MQTT broker.

  5. Save the file as mqtt.json.

  6. Create a .zip archive of the mqtt.json file.

Apply the mqtt.json file

  1. Connect the Gateway's USB cable to your desktop.

    The Gateway boots up in about 1 minute. The USB LED on the Gateway glows green constantly.

  2. Scan the barcode on the Gateway with your scanner.

    The scanner connects to the Gateway and the Scanner LED on the Gateway glows green.

  3. Scan the barcode below to enable your Gateway as a mass Storage device.

    PEP_EnableMassStorage.png

    The Gateway displays as a mass storage device on your desktop.

  4. Upload the zipped mqtt.json file to your Gateway's storage, right next to the Status folder.

    Note

    If the Gateway is not connected to your network, upload the zipped network.json file too.

  5. Eject the Gateway as a Mass Storage device from your computer. Make sure to Safely Remove / Eject the Mass storage device on your desktop but do NOT disconnect the Gateway’s USB cable during upload.

    The upload takes a few seconds. All three LEDs flash green when done. The Gateway automatically connects to Wi-Fi and INSIGHT webportal, and the Cloud LED glows green.

    Note

    Ejecting the Mass storage device may vary depending on your operating system.

    Make sure to use the Safely Remove / Eject option to remove the Gateway as the Mass storage device on your desktop but do NOT disconnect the Gateway’s USB cable during upload.

Main fields

Field

Type

Description

Required

Default

protocol

Object (see Protocol)

Use the protocol to connect to the broker(plaintext or encrypted with SSL).

This defines which protocol the Gateway will use (plaintext or ssl).

No

Plaintext

domain

String

The domain or address of the broker (e.g., 192.168.0.1 or proglove.de.).

Yes

/

client_id

String

The client identifier to be used with the broker.

Yes

/

port

Integer

The port number to connect to the broker.

No

  • 80 in plaintext mode with WebSocket

  • 443 if using SSL

  • 1883 in plaintext with a direct MQTT connection

  • 8883 in SSL mode with a direct MQTT connection

topic_prefix

String

The topic prefix before the main topic.

No

/

credentials

Object (see: Credentials)

The credentials to use in case the connection requires an authentication.

No

/

qos

String (see: Quality of Service)

The quality of service to use for publishing and subscribing.

No

At most once

use_websockets

Boolean

Whether to use websockets for the connection or not.

No

False

Protocol

Field

Type

Description

plaintext

Object

Uses plaintext to talk to the broker.

ssl

Object (see SSL)

Uses an encrypted connection with SSL to talk to the broker.

SSL

Field

Type

Description

Required

ca_cert_path

String

The path to the Root Certificate Authority file in the archive.

No*

*This is required only for self-signed certificates or certificates that were signed by an unrecognized authority.

Quality of Service

Value

Description

QOS_AT_MOST_ONCE

QoS 0 - The message is delivered according to the capabilities of the underlying network. No response is sent by the receiver and no retry is performed by the sender. The message arrives at the receiver either once or not at all.

QOS_AT_LEAST_ONCE

QoS 1 - At least once delivery This quality of service ensures that the message arrives at the receiver at least once.

QOS_EXACTLY_ONCE

QoS 2 - Exactly once delivery This is the highest quality of service, for use when neither loss nor duplication of messages are acceptable. There is an increased overhead associated with this quality of service.

Basic authentication - Credentials

Field

Type

Description

Required

username

string

The username used to authenticate with the broker.

Yes

password

string

The password used to authenticate with the broker.

Yes

Examples
Unencrypted

The examples in this section describe how to connect using an unencrypted connection.

Simple unencrypted connection

Connect to a broker on port 80 at the address proglove.de on the client id client-123.

Your Gateway/Gateway Plus will listen to topics at gateway/<serial_number>/<topic_name>

{
    "mqtt_client": {
        "domain": "proglove.de",
        "client_id": "client-1234"
    }
}
Simple unencrypted connection with Websocket broker

Connect to a WebSocket broker on port 80 at address proglove.de using the client id /client-1234.

Your Gateway/Gateway Plus will listen to topics at gateway/<serial_number>/<topic_name>

{
    "mqtt_client": {
        "domain": "proglove.de",
        "client_id": "client-1234",
        "use_websockets": true
    }
}
Unencrypted connection with specific topic prefix and port

Connect to a broker on port 4242 at address proglove.de with my_prefix as a topic prefix using the client Id client-1234.

{
    "mqtt_client": {
        "domain": "proglove.de",
        "client_id": "client-1234",
        "port": 4242,
        "topic_prefix": "my_prefix"
    }
}
Encrypted

The examples in this section describe how to connect using an encrypted connection.

Encrypted connection with default settings

Connect to an encrypted broker on port 443 at the address proglove.de on the client id client-1234.

Your Gateway/Gateway Plus will listen to topics at gateway/<serial_number>/<topic_name>

{
    "mqtt_client": {
        "domain": "proglove.de",
        "client_id": "client-1234",
        "protocol": {
            "ssl": {}
        }
    }
}
Encrypted connection with specific path and port

Connect to an encrypted broker on port 4242 at the address proglove.de using the client id client-1234.

Your Gateway/Gateway Plus will listen to topics at gateway/<serial_number>/<topic_name>

{
    "mqtt_client": {
        "domain": "proglove.de",
        "client_id": "client-1234",
        "protocol": {
            "ssl": {}
        }
    }
}
Encrypted connection with a root certificate

Connect to an encrypted broker on port 443 at the address proglove.de and using client id client-1234 and a root certificate located at ca.pem in the archive.

Your Gateway/Gateway Plus will listen to topics at gateway/<serial_number>/<topic_name>

{
    "mqtt_client": {
        "domain": "proglove.de",
        "client_id": "client-1234",
        "protocol": {
            "ssl": {
                "ca_cert_path": "ca.pem"
            }
        }
    }
}
Basic authentication

Basic authentication

Simple unencrypted connection with credentials

Connect to a broker on port 80 at the address proglove.de using the client ID client-1234 and Basic Authentication with username proglove and password password.

Your Gateway/Gateway Plus will listen to topics at gateway/<serialnumber>/<topic_name>

{
	"mqtt_client": {
		"domain": "proglove.de",
		"client_id": "client-1234",
		"credentials": {
			"basic_auth": {
				"username": "proglove",
    			"password": "password"
			}
		}
	}
}
Encrypted connection with credentials

Connect to a broker on port 443 at the address proglove.de using the client id client-1234 and Basic Authentication with username proglove and password password.

Your Gateway/Gateway Plus will listen to topics at gateway/<serialnumber>/<topic_name>

{
    "mqtt_client": {
        "domain": "proglove.de",
        "client_id": "client-1234",
        "credentials": {
            "basic_auth": {
                "username": "proglove",
                "password": "password"
            },
            "protocol": {
                "ssl": {}
            }
        }
    }
}
In this section: