TTY2MQTT(1) General Commands Manual

NAME

tty2mqtt — Tool bridging between a serial port and an MQTT message broker for publishing or subscribing messages.

SYNOPSIS

tty2mqtt	∅ \| [ --config <config> ] [ -p <tty/port> ] [ -b <tty/baud> ] [ --data-bits <tty/dataBits> ] [ --stop-bits <tty/stopBits> ] [ --parity <tty/parity> ] [ --broker-url <mqtt/broker/url> ] [ --message-suffix <tty/message/suffix> ] [ --length-width <tty/message/length/width> ] [ --length-endianess <tty/message/length/endianess> ] [ --comment-prefix <tty/message/comment/prefix> ] [ --topic-prefix <tty/message/topic/prefix> ] [ --topic-separator <tty/message/topic/separator> ] [ --subscriber-mode <mqtt/subscriber/mode> ] [ --publisher-id <mqtt/publisher/id> ] [ --subscriber-topic <mqtt/subscriber/topic> ] [ --publisher-topic <mqtt/publisher/topic> ] [ --retained ] [ --qos <mqtt/publisher/qos> ] [ -q ] [ -d ] [ --broker-user <mqtt/broker/user> [ --broker-secret <mqtt/broker/secret> ] ]
tty2mqtt	-l [ -q ]
tty2mqtt	--init [ --config <config> ] [ -q ]
tty2mqtt	-h \| --sysinfo [ -q ]

DESCRIPTION

This manual page documents the tty2mqtt command: The tty2mqtt command listens on a serial (COM) port --port (configured with a baud rate --baud-rate, data bits --data-bits, stop bits --stop-bits and parity --parity) for incoming messages for passing them to an MQTT broker--broker-url (authorized for a user --broker-user with password --broker-secret) with the given publisher ID --publisher-id (and for the given topic --publisher-topic if not otherwise overridden by the message) or forwards incoming messages from the MQTT broker with the given topic --subscriber-topic to the serial (COM) port. A message from the serial port prefixed with the --comment-prefix is printed out to STDOUT only. The default publisher topic --publisher-topic for messages sent from the serial (COM) port to the MQTT broker can be overridden by a message of the format <tty/message/topic/prefix> + <topic> + <tty/message/topic/separator> + <message> + <tty/message/suffix> with <tty/message/topic/prefix> being the topic prefix --topic-prefix, <tty/message/topic/separator> being the separator --topic-separator between the topic and the message itself and <tty/message/suffix> being the message’s terminator --message-suffix. All being configurable --config in a tty2mqtt.ini configuration file.

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.

OPTIONS

-b --baud <tty/baud>:	The baud rate to use for the TTY (COM) serial port.
--broker-secret <mqtt/broker/secret>:	The user’ password to use when connecting with the MQTT broker.
--broker-url <mqtt/broker/url>:	The URL of the MQTT broker to connect with.
--broker-user <mqtt/broker/user>:	The user name to use when connecting with the MQTT broker.
--comment-prefix <tty/message/comment/prefix>:	The prefix for data from TTY (COM) serial port to ignore (log with INFO level) and NOT publish via MQTT broker.
--config <config>:	Specifies the resource (file) to use when loading the configuration.
-d --debug:	Enables the debug mode with additional (developer readable) informational output.
--data-bits <tty/dataBits>:	The data bits to use for the TTY (COM) serial port (usually a value of 7 or 8).
-h --help:	Shows this help.
--init:	Initialize the configuration (from a template).
--length-endianess <tty/message/length/endianess>:	The endianess to use for the prefixed length of the binary data: { LITTLE, BIG }
--length-width <tty/message/length/width>:	The number of bytes to use when prefixing the length of the binary data (usually a value of 1 or 2 denting max. lengths of 256 or 65536).
-l --list:	List all detected TTY (COM) serial ports.
--message-suffix <tty/message/suffix>:	End of message character for serial TTY (COM) data, a hex value (e.g. 0x00) denotes the actual value, an ‘\n’ denotes a newline.
-p --port <tty/port>:	The COM (serial) port to operate on.
--parity <tty/parity>:	The parity to use for the TTY (COM) serial port: { AUTO, NONE, ODD, EVEN, MARK, SPACE }
--publisher-id <mqtt/publisher/id>:	The MQTT publisher ID to use.
--publisher-topic <mqtt/publisher/topic>:	The (default) MQTT topic to publish to, in case not stated otherwise in the message from TTY (COM) serial port.
-q --quiet:	Enables the quiet mode without any informational output.
--qos <mqtt/publisher/qos>:	The QOS (“Quality-of-Service”) value to use when publishing from TTY to MQTT (defaults to <0>).
--retained:	The retained flag to use when publishing from TTY to MQTT (defaults to <false>).
--stop-bits <tty/stopBits>:	The stop bits to use for the TTY (COM) serial port: { AUTO, ONE, ONE_POINT_FIVE, TWO }
--subscriber-mode <mqtt/subscriber/mode>:	Denotes the mode of operation, either processing binary or textual data: { BINARY, ASCII }
--subscriber-topic <mqtt/subscriber/topic>:	The MQTT topic to subscribe to.
--sysinfo:	Shows some system information for debugging purposes.
--topic-prefix <tty/message/topic/prefix>:	The prefix identifying a MQTT topic of data from TTY (COM) serial port, the message is published to the MQTT broker with the according topic.
--topic-separator <tty/message/topic/separator>:	The character separating the data from TTY (COM) serial port into a MQTT topic and its message.
∅:	Uses the default configuration (file).

EXAMPLES

List all available TTY (COM) ports:

tty2mqtt -l

Create an initial configuration file:

tty2mqtt --init --config <config>

Specific configuration file to use:

tty2mqtt --config <config>

Open the TTY (COM) serial port with given settings:

tty2mqtt -p <tty/port> -b <tty/baud> --data-bits <tty/dataBits> --parity <tty/parity>

Prefix and separator to parse TTY (COM) serial data:

tty2mqtt --topic-prefix <tty/message/topic/prefix> --topic-separator <tty/message/topic/separator>

Just log TTY (COM) serial data when prefixed:

tty2mqtt --comment-prefix <tty/message/comment/prefix>

Uses the default configuration (file):

tty2mqtt

To show the help text:

tty2mqtt -h

To print the system info:

tty2mqtt --sysinfo

FILES

The tty2mqtt.ini configuration file supports the following properties:

mqtt/broker/url=The MQTT broker’s URL, e.g. tcp://localhost:1883
mqtt/broker/user=The authorized MQTT broker’s user, e.g. heinz
mqtt/broker/secret=The authorized MQTT broker’s password, e.g. ketchup
mqtt/publisher/id=The serial port’s publisher ID, e.g. arduino
mqtt/publisher/retained=Whether or not messages published should be retained by the messaging engine, e.g. true
mqtt/publisher/qos=Sets the quality of service when publishing messages, e.g. 1
mqtt/subscriber/topic=The serial port’s subscriber topic, e.g. ttyin
mqtt/subscriber/mode=Denotes the mode of operation, either expecting binary (BINARY) or textual (ASCII) data, e.g. ASCII
tty/port=The serial port, e.g. /dev/ttyS0
tty/baud=The baud rate to use for the TTY (COM) serial port, e.g. 9600
tty/stopBits=The stop bits to use for the TTY (COM) serial port, e.g. AUTO
tty/parity=The parity to use for the TTY (COM) serial port, e.g. NONE
tty/dataBits=The data bits to use for the TTY (COM) serial port, e.g. 8
tty/message/suffix=The suffix terminating a message, e.g. \n
tty/message/comment/prefix=The prefix identifying a comment (to be printed out), e.g. #
tty/message/length/width=The number of bytes to use when prefixing the length of the binary data when mqtt/subscriber/mode is set to BINARY for data sent from MQTT to the TTY (COM) port, e.g. 2
tty/message/length/endianess=The endianess to use for the prefixed length of the binary data when mqtt/subscriber/mode is set to BINARY for data sent from MQTT to the TTY (COM) port, e.g. LITTLE
tty/message/topic/prefix=The prefix identifying the prefix of a message’s topic, e.g. @
tty/message/topic/separator=The delimiter separating a topic from the message, e.g. :

The tty2mqtt.ini configuration file must be located either in the current user’s working directory, the tty2mqtt executable’s folder or subfolder settings, etc or config or the user home’s ~/.config folder or in the /etc folder (in this precedence).

BUGS

See BitBucket issues at <https://bitbucket.org/funcodez/funcodes-tty2mqtt/issues>

AUTHOR

Siegfried Steiner steiner@refcodes.org

TTY2MQTT manpage

Categories

Tags