Java Serial MQTT Bridge
Java application which forwards messages from serial ports to MQTT broker and vice-versa.
The intention of this bridge is making data received over serial interfaces (such as UART, RS232) available to MQTT brokers for general usage - and the other way around.
I created this little application when I wanted to forward serial messages of the MySensors home sensor/automation system to a general purpose MQTT broker to process these messages with multiple controllers (MyController and OpenHAB) for evaluation and for having a nice way of logging/debugging.
A special feature of SerialMqttBridge is a simple plugin system to modify messages before forwarding them via MQTT or UART. Sometimes it is necessary to adapt the content between both worlds. For example MySensors messages on the serial bus have to be reformatted for MQTT needs:
12;6;1;0;0;36.5\n (serial) <-> Topic: <topicPrefix>/12/6/1/0/0 with content: 36.5 (MQTT)
In the source code you find a class doing this conversion in the de.reitho.serialMqttBridge.plugins package. Taking this one as reference you can write your own adapters.
Function
SerialMqttBridge gets configured with a text file called config.properties. This file has to be in the application root folder.
The file contains the following parameters:
| Config parameter | Example values | Note |
|---|---|---|
| Serial connection properties | ||
| serial.port | COM5 (Windows), /dev/ttyS1 (Linux) | |
| serial.baudRate |
115200 | |
| serial.dataBits | 8 | |
| serial.stopBits | 1 | |
| serial.parity | 0 | |
| MQTT properties | ||
| mqtt.brokerUrl | tcp://localhost:1883 | Consists of protocol (tcp://), hostname (or IP) and port. |
| mqtt.brokerUsername | jdoe | optional, leave blank if no authentication needed |
| mqtt.brokerPassword | s3cr3t | optional, leave blank if no authentication needed |
| mqtt.clientId | mqttSerialBridge | |
| mqtt.topicPublish | serialgateway-out | This is the topic the bridges publishes the forwarded messages to. |
| mqtt.topicSubscribe | serialgateway-in/# | This is the topic the bridge subscribes for messages. Wildcards '#' and '+' are supported. |
| mqtt.qosSubscribe | 0 | QoS which should be used for subscriptions. |
| mqtt.qosPublish | 0 | QoS which should be used for publications. |
| Logging properties | ||
| logging.serialInbound | true, false | Defines whether incoming serial messages should be logged. |
| logging.serialOutbound | true, false | Defines whether outgoing serial messages should be logged. |
| logging.mqttInbound | true, false | Defines whether incoming MQTT messages should be logged. |
| logging.mqttOutbound | true, false | Defines whether outgoing MQTT messages should be logged. |
| Publishing preprocessor plugin properties | ||
| plugin.mqttPublishPreprocessor | com.foo.bar.MqttPreprocessor | Name of the class which preprocesses the serial message before publishing it. |
| plugin.serialSendPreprocessor | com.foo.bar.SerialPreprocessor | Name of the class which preprocesses the MQTT message before sending it out on serial interface. |
System requirements
Starting with release 1.1 the application needs Java Runtime version 13 or later to run. Older releases can be used with Java 8.
Usage
After downloading and extracting the release archive please check and modify the properties file first. Then you can start the application with
java -jar serialMqttBridge-<VERSION>.jar.
Developers
Developers can clone the code and build the application using Maven:
mvn package
Please note: Unfortunately there is no Maven Central artifact of the used jssc library yet. So if you want to compile the code yourself you have to download the dependency from Github (https://github.com/java-native/jssc/releases/download/v2.9.1/jssc-2.9.1.jar) and import it into your local Maven repository:
mvn install:install-file \
-Dfile=<path-to-file> \
-DgroupId=com.github.java-native \
-DartifactId=jssc \
-Dversion=2.9.1 \
-Dpackaging=jar \
-DgeneratePom=true
If you want to create your own preprocessor plugin just implement the according interfaces in the de.reitho.serialMqttBridge.plugins package, put the classes into the classpath and define them in the config file.
Outlook
Up to now you can only define one or zero preprocessor plugins. In the future I might expand this into a kind of workflow engine which allows custom logging, filtering or persistence.