MQTT Client

Content Type: Module
Categories: Internet-of-Things

Overview

Connector for sending and receiving MQTT messages. This module uses the Eclipse Paho library and has been tested with AWS IoT, The Things Network, and Mosquitto brokers.

Documentation

Mendix MQTT connector

Mendix module to send and receive MQTT messages. This module uses the Eclipse Paho library. Tested with AWS IoT, The Things network and mosquitto brokers.

Usage

Main java actions:

  • MqttPublish - publish a message to specified topic
  • MqttSubscribe - subscribe to a topic. Required you to specify a microflow which will be called upon receiving a message. This microflow should have two string parameters: Topic and Payload.
  • MqttUnsubscribe - unsubscribe from topic

MQTT Microflow actions toolbox

MQTT Publish

This activity allows you to publish a message to a specific MQTT topic. When you execute this activit the module will setup a connection to the topic and publish the message, it will retain the connection in memory for faster publishing in the future.

Parameters (if parameters are optional you can pass empty or ''):

  • Broker host (required): The url of your MQTT broker, needs to be the URL without protocol and without port. (e.g. 'test.mosquitto.org')
  • Broker port (required): The port of your broker
  • Broker organisation (optional): Some brokers use an organization as part of the URL, pass that here.
  • Timeout (required): Maximum timeout between broker and this application in Seconds (default=60)
  • Broker Username (optional): If your broker has username/password authentication pass the username here. If you set a username you must set a password.
  • Broker Password (optional): If your broker has username/password authentication pass the username here. If you set a password you must set a username.
  • Topic name (required): The full topic name you want to publish the message to. This needs to be the topic name starting at the root, but not including a leading slash. Example: 'iot-2/type/exampledevice/status'
  • Payload (required): The message that is passed to the broker, this can be any format. The message is passed as-is to the broker.
  • CA (optional): If the broker requires a (custom) SSL authentication pass the certificates here. This is the Certificate Authority used for the connection. Place the certificates inside of the resource folders. This value must be a relative path inside the resource folder. E.g.: 'cert/ca.pem' if your certificate is located in 'resources/cert/'.
  • Client certificate (optional): If the broker requires a (custom) SSL authentication pass the certificates here. This is the Client Certificate used for the connection. Place the certificates inside of the resource folders. This value must be a relative path inside the resource folder. E.g.: 'cert/client.pem' if your certificate is located in 'resources/cert/'.
  • Client key (optional): If the broker requires a (custom) SSL authentication pass the certificates here. This is the Client Key used for the connection. Place the certificates inside of the resource folders. This value must be a relative path inside the resource folder. E.g.: 'cert/client.key' if your certificate is located in 'resources/cert/'.
  • Certificate Password (optional): If the broker requires a (custom) SSL authentication pass the certificates here. This is password that is needed to use the client key.
  • QOS (required): Passes the Quality of Service parameter straight to the broker (At_Most_Once_0 / At_Least_Once_1 / Exactly_Once_2). See MQTT service definitions for more info, i.e.: https://mosquitto.org/man/mqtt-7.html#idm72 (In short, Higher levels of QoS are more reliable, but involve higher latency and have higher bandwidth requirements.)

MQTT Subscribe

This activity sets up the Subscription to an MQTT topic. When you execute this activit the module will setup a connection to the topic and wait for any message that comes in on the topic.

Parameters (if parameters are optional you can pass empty or ''):

  • Broker host (required): The url of your MQTT broker, needs to be the URL without protocol and without port. (e.g. 'test.mosquitto.org')
  • Broker port (required): The port of your broker
  • Broker organisation (optional): Some brokers use an organization as part of the URL, pass that here.
  • Timeout (required): Maximum timeout between broker and this application in Seconds (default=60)
  • Broker Username (optional): If your broker has username/password authentication pass the username here. If you set a username you must set a password.
  • Broker Password (optional): If your broker has username/password authentication pass the username here. If you set a password you must set a username.
  • Topic name (required): The full topic name you want to publish the message to. This needs to be the topic name starting at the root, but not including a leading slash. Example: 'iot-2/type/exampledevice/status'
  • On message Microflow (required): The Microflow that will be executed for each message on the Topic. This microflow must have 2 parameters of type String: Topic & Payload.
  • CA (optional): If the broker requires a (custom) SSL authentication pass the certificates here. This is the Certificate Authority used for the connection. Place the certificates inside of the resource folders. This value must be a relative path inside the resource folder. E.g.: 'cert/ca.pem' if your certificate is located in 'resources/cert/'.
  • Client certificate (optional): If the broker requires a (custom) SSL authentication pass the certificates here. This is the Client Certificate used for the connection. Place the certificates inside of the resource folders. This value must be a relative path inside the resource folder. E.g.: 'cert/client.pem' if your certificate is located in 'resources/cert/'.
  • Client key (optional): If the broker requires a (custom) SSL authentication pass the certificates here. This is the Client Key used for the connection. Place the certificates inside of the resource folders. This value must be a relative path inside the resource folder. E.g.: 'cert/client.key' if your certificate is located in 'resources/cert/'.
  • Certificate Password (optional): If the broker requires a (custom) SSL authentication pass the certificates here. This is password that is needed to use the client key.
  • QOS (required): Passes the Quality of Service parameter straight to the broker (At_Most_Once_0 / At_Least_Once_1 / Exactly_Once_2). See MQTT service definitions for more info, i.e.: https://mosquitto.org/man/mqtt-7.html#idm72 (In short, Higher levels of QoS are more reliable, but involve higher latency and have higher bandwidth requirements.)

MQTT Unsubscribe

This activity will unsubscribe your application from listening to an MQTT topic. All values passed into this acitivity need to be identical to the subscribe action. These values are used to identify unique MQTT connections.

Parameters (if parameters are optional you can pass empty or ''):

  • Broker host (required): The url of your MQTT broker, needs to be the URL without protocol and without port. (e.g. 'test.mosquitto.org')
  • Broker port (required): The port of your broker
  • Broker organisation (optional): Some brokers use an organization as part of the URL, pass that here.
  • Broker Username (optional): If your broker has username/password authentication pass the username here. If you set a username you must set a password.
  • Topic name (required): The full topic name you want to publish the message to. This needs to be the topic name starting at the root, but not including a leading slash. Example: 'iot-2/type/exampledevice/status'

Examples

Usage with Amazon AWS IoT

You need to register your app as a Thing on AWS IoT. Download the generated certificates and store them in your resources folder of your app. When subscribing or publishing a message specify their location reletive to the resources folder.

Usage with TTN

For TTN you can leave the certificate info empty, instead provide username and password.

Microflow to subscribe to an MQTT topic:

MQTT subscribe to topic

Configuration of subscribe for TTN:

Microflow to handled messages received:

More info can be found here: Using Mendix with TTN

Usage with IBM IoT

To use IBM IOT you need to fill in your organisation ID with your organisation ID. For the Username & Password you need to use the API Key for the username and Authentication Token for password.

IBM IOT

Setting up your IBM Application

To get your API Key and Authentication token login to your IBM IOT Launchpad and click on apps. Then click new Generate New API Key. IBM Apps

Development

Java dependencies are managed using Apache Ivy. There are two configuration:

  • export - this is used to make sure only the required jars for the connector module are in userlib
  • default - this downloads all dependencies required to run the project

Before you export the connector module run runivy-export.cmd to ensure you have the correct set of libraries to be included in the connector mpk.

License

Apache License V2.0

Eclipse Public License

Releases

Version: 2.2.0
Framework Version: 8.12.5
Release Notes: Mx9 Compatibility Optimized logging to have less verbose and more consistent info/debug/trace logging Added reconnection functionality that does 10 attempts upon loss of connection Added validation for the onmessage microflow Memory optimization, reduced Java class instances and variables Removed the initialize Activity Upgrade to 8.12.5
Version: 2.1.0
Framework Version: 7.23.7
Release Notes: Updated to 7.23.7 to support 8.X
Version: 2.0.0
Framework Version: 7.16.0
Release Notes: Updated to include thingspeak support and timeout support