Message Broker

Description

ezvpn-mqtt is the heart of IOhubTM environment; it is an internal MQTT service (provided as a Docker container image) acting as a broker between multiple internal containers.

In the IOhubTM architecture, each container can use ezvpn-mqtt as an internal communication hub.

Internal MQTT Schema

The ezvpn-mqtt container has no configuration and no authentication; it is for internal use only within the IOhubTM environment, and it doesn't map any port to and from the external network.

This container is used to exchange data internally between field drivers and field exchangers; it is not used to exchange data with the outside nor with other application layers.

If you need to establish communication with the cloud, you can use a specific container like Google PubSub, AWS Timestream, or any other generic MQTT Broker. These containers use ezvpn-mqtt to read/write data to the field and it is the right communication protocol to set up cloud communication.

By default, ezvpn-mqtt internally exposes the port 1883.

Internal MQTT conventions

Even if there is no restriction regarding the topic names, all the field containers adopt a naming convention, as described below.

Topic naming

The topic naming has this format:

fld/<protocol>/<direction>/<measurement>

fld: reserved name, all EZ VPN topics start with fld name. If you are going to develop a custom container using ezvpn-mqtt, we suggest using another prefix.

<protocol>: the field protocol (see documentation on FIELD CONTAINERS section).

<direction>: r from field, w to field.

<measurement>: address field name.

Example

fld/modbus/r/tempSP it is a topic publishing values from the Modbus protocol for the address tempSP

Message format

The standard message structure, in each topic, is:

{
    "value": "<value>",
    "ts": <unix timestamp>
}

where

  • value: the measurement value
  • ts: the UNIX timestamp in milliseconds

e.g.

{"value":33,"ts":1604304701324}

In the IOhubTM environment, the predefined topic names start with fld/. Please consider using a different name to use it for your custom application to avoid creating conflicts.

Persistence

By default ezvpn-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.

Environment variables

When you start the ezvpn-mqtt container, 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 (mapped to a volume).
  • MAX_QUEUED_MESSAGES: max number of queued messages. Default = 1000. Not used if persistence is not enabled.
  • AUTOSAVE_INTERVAL: seconds between each message autosave. Default = 300. Not used if persistence is not enabled.

This container derives from eclipse-mosquitto. Check the documentation if you want to customize its behavior.

Running locally with Docker

Example of running an ezvpn-mqtt Docker container locally.

docker run -it -p 1883:1883 \
    us-central1-docker.pkg.dev/ez-shared/iohub/iohub-mqtt

Example with docker-compose:

docker-compose.yml

version: "3"

services:
    myapp-mqtt:
        image: us-central1-docker.pkg.dev/ez-shared/iohub/iohub-mqtt
        expose:
            - 1883

Access MQTT messages from command line

To view the messages flowing through the broker, you can use the mosquitto_sub command.

docker exec -it <docker-mqtt-name> mosquitto_sub -v -t 'fld/#'

To send a message to the broker, you can use the mosquitto_pub command.

docker exec -it <docker-mqtt-name> mosquitto_pub -v \
    -t 'fld/<protocol>/w/<measurement>' -m '13'

Docker container details

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

Supported architecture: amd64

Changelog

v1.0.1
  • Persistence functionality added
v1.0.0
  • First Release