NAME

       mqtt-publisher - send HAL pin data to MQTT broker periodically

SYNOPSIS

       loadusr -W mqtt-publisher [options] keys=pin1[,pin2...]

DESCRIPTION

       mqtt-publisher is a non-realtime program that reads HAL values periodically and passes the values to a
       MQTT broker.

       When specifying the MQTT settings in the INI file, this is the recommended setup:

       HAL file:

           loadusr -W mqtt-publisher [MQTT]DRYRUN --mqtt-broker=[MQTT]BROKER \
             --mqtt-user=[MQTT]USERNAME --mqtt-password=[MQTT]PASSWORD keys=halui.estop.is-activated

       INI file:

           [MQTT]
           DRYRUN = --dryrun
           BROKER = broker.local
           USERNAME = username
           PASSWORD = password

       This component need the Paho python library installed to function. On debian this is available from the
       python3-paho-mqtt package.

OPTIONS

       keys=pin1[,pin2,...]
           The name of HAL pins, signals and other values to publish using MQTT. The names are also used as the
           JSON keys in the MQTT message published with the broker. If multiple "keys=" options are specified,
           the lists are merged.

       --dryrun
           Do not set up MQTT connection, only print message to stdout. Useful for debugging and testing.

       --mqtt-broker=FQDN
           The fully qualified DNS name of the MQTT broker. The default broker name is "localhost".

       --mqtt-port=PORTNUMBER
           The port to use of the MQTT broker. The default port is 1883.

       --mqtt-user=USERNAME
           The user name to use when connecting to the MQTT broker.

       --mqtt-password=PASSWORD
           The password to use when connecting to the MQTT broker.

       --mqtt-prefix=PREFIX
           The MQTT prefix/topic to use when publishing to the MQTT broker. The default prefix is
           "devices/linuxcnc/machine".

FUNCTIONS

       mqtt-publisher
           The loop reading HAL values and publishing MQTT messages.

PINS

       mqtt-publisher.enable bit input
           When TRUE, publish messages to MQTT broker. When FALSE, do not publish messages. Default is TRUE.

       mqtt-publisher.period u32 input
           The number of seconds to sleep between publishing MQTT messages to the broker. Default is 10 seconds.

       mqtt-publisher.lastpublish u32 output
           When the last MQTT publication was published in number of seconds since EPOC. If no publication has
           taken place, the value is zero.

EXAMPLES

       Any set of HAL pins and signals can be published. This setup might be a useful starting point:

           loadusr -W mqtt-publisher \
             [MQTT]DRYRUN \
             --mqtt-broker=[MQTT]BROKER
             --mqtt-user=[MQTT]USERNAME \
             --mqtt-password=[MQTT]PASSWORD \
             keys=halui.axis.a.pos-feedback,halui.axis.b.pos-feedback,\
           halui.axis.c.pos-feedback,halui.axis.u.pos-feedback,\
           halui.axis.v.pos-feedback,halui.axis.w.pos-feedback,\
           halui.axis.x.pos-feedback,halui.axis.y.pos-feedback,\
           halui.axis.z.pos-feedback \
             keys=halui.estop.is-activated, halui.joint.0.is-homed,\
           halui.joint.1.is-homed,halui.joint.2.is-homed,halui.joint.3.is-homed,\
           halui.joint.4.is-homed,halui.joint.5.is-homed,halui.joint.6.is-homed,\
           halui.joint.7.is-homed,halui.joint.8.is-homed \
             keys=halui.machine.is-on,halui.max-velocity.value,halui.mode.is-auto,
           halui.mode.is-manual,halui.mode.is-mdi,halui.mode.is-teleop,
           halui.program.is-running

       Note: It is recommended to use the line continuation character "\" as shown here to improve readability.
       But note that spaces must be left in to delimit options, and must not be included (including at the
       beginning of a line) inside a single option.

       HAL limits a single option/token (for example "keys=") to 255 characters. To work around this issue use
       multiple "keys=" entries as shown.

SEE ALSO

       hal(3hal)

AUTHOR

       Component and documentation created by Petter Reinholdtsen, as part of the LinuxCNC project.

COPYRIGHT

       Copyright © 2023 Petter Reinholdtsen. This is free software; see the source for copying conditions. There
       is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

LinuxCNC                                           08/07/2025                                  MQTT-PUBLISHER(1)