= mqtt-publisher(1)

== 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.

