Skip to main content

MQTT

MQTT is a lightweight M2M pub/sub messaging protocol mainly used for IoT communication.

The protocol uses a topic structure delimited by forward slashes /. OpenFMB topics names conform to the following pattern:

openfmb/<module name>/<profile name>/<subject name>

Configuration

mqtt:
enabled: false
max-queued-messages: 100 # how many messages to buffer before discarding the oldest
server-address: tcp://localhost:1883
client-id: client1
connect-retry-delay-ms: 5000
security:
security-type: none
publish: # to the MQTT broker
- profile: SwitchReadingProfile
topic-suffix: "*" # * or an mRID
- profile: SwitchStatusProfile
topic-suffix: "*" # * or an mRID
subscribe: # from the MQTT broker
- profile: SwitchControlProfile
topic-suffix: "*" # * or an mRID
ParameterDescription
enabledtrue to enable MQTT plugin, false to disable.
max-queued-messagesNumber of messages to keep in the publishing queue before discarding the oldest.
server-addressConnection address of the MQTT server. The protocol can be tcp or ssl.
client-idClient ID, which must be unique per client and broker.
connect-retry-delay-msNumber of milliseconds to wait before trying to re-establish a connection to the server.
securitySee Security.
publishList of profiles to publish to MQTT network (from the internal bus to MQTT)
subscribeList of profiles to subscribe from the MQTT network (from MQTT to the internal bus)

For the publish and subscribe parameters, a list of profiles is specified. Provide both the profile name (profile) and which equipment you want to publish/subscribe to (subject). The subject name can either be * to publish/subscribe to all the profiles, or a specific conducting equipment mRID.

Security

The content of the security section depends on the security-type value.

security:
security-type: none
security:
security-type: tls_server_auth
ca-trusted-cert-file: server_cert.pem
username: "username"
password: "password"
security:
security-type: tls_mutual_auth
ca-trusted-cert-file: server_cert.pem
client-private-key-file: client_key.pem
client-cert-chain-file: client_cert.pem

If no security is needed, the security-type can be set to none.

To learn how to produce self-signed certificates with OpenSSL, check Self-signed certificates.

Server Authentication + Username/Password

The server must run with a TLS certificate, a username and a password. In the mosquitto.conf, add the following lines:

cafile ~/certs/client_cert.pem
certfile ~/certs/server_cert.pem
keyfile ~/certs/server_key.pem
password_file /etc/mosquitto/passwd
allow_anonymous false

And generate the passwd file:

> sudo mosquitto_passwd -c /etc/mosquitto/passwd username

Finally, configure the Adapter to establish a TLS encrypted session, accepting only the certificate. The username and the password are embedded in the connection URL.

mqtt:
enabled: true
max-queued-messages: 100 # how many messages to buffer before discarding the oldest
server-address: ssl://localhost:1883
client-id: client1
connect-retry-delay-ms: 5000
security:
security-type: tls_server_auth
ca-trusted-cert-file: server_cert.pem
username: "username"
password: "password"
# ...

Mutual Authentication

The server must run with a TLS certificate and must validate the client certificate. In the mosquitto.conf, add the following lines:

cafile ~/certs/client_cert.pem
certfile ~/certs/server_cert.pem
keyfile ~/certs/server_key.pem
require_certificate true
#password_file /etc/mosquitto/passwd
#allow_anonymous false

If you want to require username/password in addition to mutual authentication, de-comment the last two lines.

And configure the Adapter to establish a TLS encrypted session with mutual authentication.

mqtt:
enabled: true
max-queued-messages: 100 # how many messages to buffer before discarding the oldest
server-address: ssl://localhost:1883
client-id: client1
connect-retry-delay-ms: 5000
security:
security-type: tls_mutual_auth
ca-trusted-cert-file: server_cert.pem
client-private-key-file: client_key.pem
client-cert-chain-file: client_cert.pem
#username: "username"
#password: "password"
# ...

If a username/password is required, then uncomment the last two lines.