MQTT Broker

Description

ezvpn-gw-mqtt is a service (provided as Docker container image) that acts as an MQTT Broker based on mosquitto.

MQTT Broker Container Schema

By using ezvpn-gw-mqtt, you can:

  • write data to IOhubTM using an external MQTT client.

  • read data from IOhubTM using an external MQTT client.

How to use it

ezvpn-gw-mqtt is a Docker container image pre-configured to communicate with MQTT clients.

It listens by default on the external port 1883 and topic and message needs to respect the internal MQTT conventions to communicate with IOhubTM. To read and write values from the IOhubTM environment, you can use the ezvpn-mqtt-mqtt container.

You can use ezvpn-gw-mqtt directly in IOhubTM for final production, or on your PC for testing purposes.

The ezvpn-gw-mqtt container included in the IOhubTM catalog, is pre-configured with the following credential:

Username: ezvpn

Password: ezvpn

For security reasons, we strongly recommend to change it.

To avoid overlapping the port 1883 with the internal MQTT broker, the ezvpn-gw-mqtt container is preconfigured to internally expose the port 1884. The internal port 1884 is mapped to the external port 1883.

If your IOhubTM hardware is configured in router mode, by default, access to any network port from WAN is denied. Please read the section "Access from WAN" to unlock it.

Persistence

By default ezvpn-gw-mqtt has persistence feature disabled. To prevent data loss in case of non-delivery of data outside of the box (cable disconnection or unreachability of external services), you must enable PERSISTENCE environment variable.

Remember to mount a local Volume on the container to /mosquitto/data to get data also on reboot or power loss otherwise you will loose you data on persistence.

The persistence functionality works in conjunction with containers that support buffering. Check that the containers you use have buffering functionality enabled.

Testing the MQTT broker

To test sending messages from a client to the MQTT broker we can use a generic MQTT client. You need to add the ezvpn-mqtt-mqtt to communicate with IOhubTM internal broker.

In this example, we will use the mosquitto_pub client to send messages and the mosquitto_sub client to listen for messages sent by the MQTT broker using IOhubTM message format. RAW messages are supported too, please check the message read and write summary to use the correct option in ezvpn-mqtt-mqtt container.

To send a message using the IOhubTM format.

mosquitto_pub -h <MQTT host> -p <MQTT port> -t 'fld/modbus/w/setpoint' -m '{"value":335}' -u "<username>" -P "<password>"

To listen for messages

mosquitto_sub -h <MQTT host> -p <MQTT port> -t "#" -u "<username>" -P "<password>"

Environment variables

When you start the ezvpn-gw-mqtt image, you can adjust the instance's configuration by passing one or more environment variables to the docker run command.

  • PERSISTENCE: if true, messages are saved on db. To get real persistence upon restart, the volume /mosquitto/data must be persisted.

  • MAX_QUEUED_MESSAGES: max number of queued messages. Default = 1000. Not used if persistence is not enabled.

  • AUTOSAVE_INTERVAL: second between each message autosave. Default = 300. Not used if persistence is not enabled.

  • AUTH_USERNAME: Username for url authentication. If absent, authentication is disabled.

  • AUTH_PASSWORD: Password for url authentication. If absent, authentication is disabled.

  • MQTT_PORT: Listening port. Defaults to 1883.

  • MQTT_LOG_FILE: if true, logs are saved on /mosquitto/log/mosquitto.log

  • MQTT_LOG_STDOUT: if true, logs are sent to stdout

Docker container details

Image: us-central1-docker.pkg.dev/ez-shared/iohub/iohub-gw-mqtt

Supported architecture: amd64

Changelog

v1.0.3
  • Fix data path
v1.0.2
  • AUTH_USERNAME Environment variable added
  • AUTH_PASSWORD Environment variable added
  • MQTT_LOG_FILE Environment variable added
  • MQTT_LOG_STDOUT Environment variable added
v1.0.1
  • PERSISTENCE Environment variable added
  • MAX_QUEUED_MESSAGES Environment variable added
  • AUTOSAVE_INTERVAL Environment variable added
v1.0.0
  • First Release