The TTY2MQTT command line tool is a bridge between TTY (COM) serial communication and an MQTT message broker and provides a CLI for publishing and subscribing data from and to a serial port from and to an MQTT message broker. You can download TTY2MQTT from this site’s downloads section.
You may operate TTY2MQTT on a Raspberry Pi to which Arduino boards are attached to by USB. The USB connections by default act as serial TTY (COM) connections over USB, so that the Raspberry Pi directly can communicate with the Arduino boards via serial communication. The TTY2MQTT tool now bridges this serial communication to an MQTT message broker.
Depending on the executable’s flavor the command might also be named tty2mqtt-x.y.z.jar, tty2mqtt-bundle-x86_64-x.y.z.elf, tty2mqtt-bundle-x86_64-x.y.z.exe, tty2mqtt-installer-x86_64-x.y.z.msi, tty2mqtt-launcher-x.y.z.sh, tty2mqtt-launcher-x86_64-x.y.z.elf, tty2mqtt-launcher-x86_64-x.y.z.exe, tty2mqtt-native-x86_64-x.y.z.elf where x.y.z stands for the version of the tty2mqtt command. The according executable’s name will be referenced to in this manual as tty2mqtt.
./tty2mqtt --init: Create an initial
To get an impression of all the functionality, just go for
./tty2mqtt --help, which shows the tool’s help.
./tty2mqtt: Start the tool
1 2 Serial.println("@button1:Button 1 pressed") // Use topic "button1" when TTY2MQTT publishes the message Serial.println("# The button one on the Arduino has been pressed!") // This is a comment, TTY2MQTT just logs this text
MQTT topic to publish to is
and the payload is “
Button 1 pressed”. Before this example works, you must configure
your TTY (COM)
port to attach to on the one side and the
broker to attach to on the other side. Next we will go through the various configuration
properties to, amongst others, do so.
You may prepare multiple configurations and launch
TTY2MQTTmultiple times with the according configuration file as argument, e.g
./tty2mqtt --config someConfigA.ini
tty2mqtt.ini is found at the end of this article and may be tweaked
MQTT message broker
MQTT message broker to use is configured
[[broker]] portion of the
URLof the message broker in question.
user: The user to use when accessing the according message broker.
secret: The user’s password to use when accessing the according message broker.
Publishing from the serial port
id: The ID we give the publisher on the
serial portto be used when sending
MQTTmessages to the
topic: Use this topic in case none is found in the TTY (COM) serial payload (fallback), leave empty if messages without a topic are to be ignored (just logged). A topic can be defined in the serial port’s payload (see configuration further down).
Subscribing to the serial port
topic: The name of the topic which’s messages are to be passed from the
MQTTmessage broker to the TTY (COM) port.
serial port is configured in
port: The TTY (COM) port to use, e.g.
COM1on Windows or
BPSto be used when communicating with the TTY (COM) port.
parity: The parity to use when operating the TTY (COM) port, see
./tty2mqtt --helpfor possible values.
dataBits:The number of data bits to use when operating the TTY (COM) port.
stopBits:The number of stop bits to use when operating the TTY (COM) port.
Serial port messages
The format of a message on the
is configured in the
[[message]] portion of the
suffix: The suffix identifying the end of a TTY (COM) serial payload. A hex value (e.g.
0x00) denotes the actual value, an
\ndenotes a newline.
Serial port comments
Sometimes it is useful to still use the TTY (COM)
for printing out debugging information. This information must not be forwarded to
MQTT message broker. In such cases,
the device attached to the TTY (COM)
port may mark its payload as being a comment. The format of a comment on the
is configured in the
[[[comment]]] portion of the
prefix: The prefix character for TTY (COM) serial payloads which just to print out with INFO log level.
1 Serial.println("# The button one on the Arduino has been pressed!") // This is a comment, TTY2MQTT just logs this text
Topics in serial port payloads
The format of a topic embedded in the payload on the
is configured in the
[[[topic]]] portion of the
prefix: The prefix character identifying an
separator: The separator character separating the topic from the actual message.
In general, the layout of a payload containing a topic is as follows:
<prefix>+ “topic” +
<separator>+ “message” +
For example using the topic prefix “@” and a separator “:”, a payload with a topic and a message might look as follows:
1 Serial.println("@button1:Button 1 pressed") // Use topic "button1" when TTY2MQTT publishes the message
Serial.printlnalready suffixes the text to be printed with a
\nis not explicitly specified in the string to be printed.
You can use
TOML) notations (including plain simple
*.properties files with
value pairs). Below find configurations using
INI notation and also using plain properties:
Extended INI notation
INInotation, the configuration is organized by sections embedded in square braces
Note that the hierarchical order of the properties is achieved by the number of nested square braces, e.g. a portion belonging to a section
[...]gets additional square braces as of
[[...]]and is placed below the parent section it belongs to.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 [mqtt] [[broker]] url=tcp://localhost:1883 user=heinz secret=ketchup [[publisher]] id=arduino # Use this topic in case none is found in the TTY (COM) serial payload (fallback), # leave empty if messages without a topic are to be ignored (just logged): # topic=debug [[subscriber]] topic=ttyin [tty] port=/dev/ttyS0 baud=9600 [[message]] # The suffix identifying the end of a TTY (COM) serial payload. A hex value (e.g. # 0x00) denotes the actual value, an '\n' denotes a newline: suffix=\n [[[comment]]] # Just log any TTY (COM) serial payload prefixed with this char with INFO log level: prefix=# [[[topic]]] prefix=@ separator=:
Java properties notation
This notation uses plain simple files with
value pairs for each line.
Note that the hierarchical order of the properties is achieved by representing the properties with a path alike notation.
1 2 3 4 5 6 7 8 9 10 11 mqtt/broker/url=tcp://localhost:1883 mqtt/broker/user=heinz mqtt/broker/secret=ketchup mqtt/publisher/id=arduino mqtt/subscriber/topic=ttyin tty/port=/dev/ttyS0 tty/baud=9600 tty/message/suffix=\n tty/message/comment/prefix=# tty/message/topic/prefix=@ tty/message/topic/separator=: