TTY2MQTT manpage

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> ] [ --comment-prefix <tty/message/comment/prefix> ] [ --topic-prefix <tty/message/topic/prefix> ] [ --topic-separator <tty/message/topic/separator> ] [ --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).
-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-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/subscriber/topic=The serial port’s subscriber topic, e.g. ttyin
  • tty/port=The serial port, e.g. /dev/ttyS0
  • tty/baud=The serial port’s byud rate, e.g. 9600
  • 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/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: https://bitbucket.org/funcodez/funcodes-tty2mqtt

AUTHOR

Siegfried Steiner steiner@refcodes.org

SEE ALSO