MQTT-PUBLISHER(1)

📦
version 2.9.4 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 mqtt-publisher — the MQTT glow-up for your HAL pins 💖

okay bestie, gather round, because this is the MQTT-PUBLISHER(1) page from the LinuxCNC Documentation and it is genuinely iconic. no cap.

✨ NAME ✨

mqtt-publisher — send HAL pin data to a MQTT broker, periodically, like clockwork, slay 💅

🌸 SYNOPSIS 🌸

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

🦋 DESCRIPTION 🦋

okay so mqtt-publisher is a non-realtime program. it reads your HAL values every so often and hands the values over to a MQTT broker. that's the whole vibe, and it does it beautifully ✨

when you're putting the MQTT settings in the INI file, this is the recommended setup, fr fr:

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
⚠️ real talk: this component needs the Paho python library installed to function. on debian that's available from the python3-paho-mqtt package. no paho, no publishing, periodt.

👑 OPTIONS 👑

  • keys=pin1[,pin2,...] — the name(s) of the HAL pins, signals and other values you wanna publish over MQTT. these names are also used as the JSON keys in the MQTT message that goes out to the broker. and if you pass multiple keys= options, the lists get merged. it's giving "the more the merrier" 💖
  • --dryrun — do NOT set up a MQTT connection, only print the message to stdout. super useful for debugging and testing. zero risk, all vibes 🔥
  • --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 that reads HAL values and publishes MQTT messages. that's the main character right there 🫶

🎀 PINS 🎀

  • mqtt-publisher.enable bit input — when TRUE, publish messages to the 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. beauty sleep, but make it networking 😴
  • 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, no gatekeeping here. 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. iykyk 🙈
💀 the 255-character jump scare: HAL limits a single option/token (for example "keys=") to 255 characters. to work around this issue use multiple "keys=" entries as shown. multiple keys entries = self care, honestly.

🧚 SEE ALSO 🧚

  • hal(3hal)

💜 AUTHOR 💜

component and documentation created by Petter Reinholdtsen, as part of the LinuxCNC project. we love a legend 👑

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.

and that's the whole page, bestie 🫶 go forth and publish those pins. this was LinuxCNC version, dated 03/17/2026 — mwah, take care of her 💅✨🎀

📦 where this page comes from