From 3e0cc49a305c7e1b8d5593a4346251a19487c6b5 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Mon, 14 Sep 2026 08:35:47 +0800 Subject: [PATCH] docs: add Modbus safety considerations for spindle and drive control A Modbus slave such as a VFD holds the last written control word indefinitely, so a LinuxCNC exit, crash or dropped serial link leaves the spindle running with no stop command ever sent (issue #4529). This was not documented anywhere. Add a Safety Considerations section to the mb2hal driver doc covering the standard layered practice: hardwired enable/STO in the estop chain as the only true safety layer, stopping on communication loss either via the VFD Modbus timeout or via HAL-side detection on the mb2hal num_errors pin (no VFD-specific parameterization, survives VFD replacement), and optionally splitting VFD command sources so run comes from a hardwired terminal driven by motion.spindle-on or motion.machine-is-on while Modbus carries only speed, direction and status. Note that shutdown.hal stop writes cover only the clean-exit case, and that run/stop over Modbus is accepted practice once the hardwired layer is in place. Point to the new section from the hm2_modbus man page SEE ALSO, since the same considerations apply to every Modbus control path. Also fix the num_errors pin direction in the mb2hal man page (it is HAL_OUT in the source). --- docs/src/drivers/mb2hal.adoc | 25 +++++++++++++++++++++++++ docs/src/man/man1/mb2hal.1.adoc | 4 ++-- docs/src/man/man9/hm2_modbus.9.adoc | 3 +++ 3 files changed, 30 insertions(+), 2 deletions(-) diff --git a/docs/src/drivers/mb2hal.adoc b/docs/src/drivers/mb2hal.adoc index d82568e76f0..64b35042666 100644 --- a/docs/src/drivers/mb2hal.adoc +++ b/docs/src/drivers/mb2hal.adoc @@ -26,6 +26,31 @@ Consider using MB2HAL if: * You want a protocol to connect your Arduino to HAL. Look the included sample configuration file, sketch and library for Arduino Modbus. +== Safety Considerations + +Modbus (RTU or TCP) is not suitable as the only run-enable path for a spindle or drive. +A Modbus slave such as a VFD holds the last value written to its control registers indefinitely. +If LinuxCNC exits, crashes, or the serial link drops while the spindle is running, no stop command is ever sent and the spindle keeps running. +MB2HAL is a non-realtime userspace component and performs no cleanup on exit, so this applies even to a clean shutdown. +Writing a stop command from `shutdown.hal` only covers the clean-exit case and is not a safety measure. + +The standard practice is to layer the control: + +. Wire the enable in hardware. + The VFD enable or STO (Safe Torque Off) inputs belong in the machine estop chain, independent of any communication bus. + This is the only layer that qualifies as safety. + Many VFDs offer dual redundant estop inputs for use with safety relays. + With this layer in place, run and stop over Modbus is accepted practice; the remaining layers decide what happens when the communication fails. +. Arrange a stop on communication loss. + Most VFDs provide a Modbus timeout parameter with a fault or coast-to-stop action; set it to a few hundred milliseconds, so a crash or dropped link stops polling and the VFD stops the motor. + Alternatively detect the loss in HAL: the `mb2hal.__m__.num_errors` pin counts failed transactions (0 means the last transaction succeeded), and feeding it into a machine-off or estop chain stops the machine when the link dies. + HAL-side detection avoids VFD-specific parameterization and needs no rework when the VFD is replaced, but coverage of a PC crash then rests on the output hardware watchdog, for example the Mesa hostmot2 watchdog or a parallel-port charge pump. +. Optionally split the command sources. + Configure run command from terminals and frequency reference from Modbus, drive the VFD run terminal from `motion.spindle-on` or `motion.machine-is-on` through a relay or digital output, and let Modbus carry only speed reference, direction and status. + This also avoids the read-modify-write problem when a single control register multiplexes run, stop and other commands. + +These considerations apply to every Modbus control path (MB2HAL, hm2_modbus, ClassicLadder or a custom driver), not only to MB2HAL. + == Usage .. Create a config file from the example below diff --git a/docs/src/man/man1/mb2hal.1.adoc b/docs/src/man/man1/mb2hal.1.adoc index 669e32d4b70..e5a5f8b49e6 100644 --- a/docs/src/man/man1/mb2hal.1.adoc +++ b/docs/src/man/man1/mb2hal.1.adoc @@ -72,8 +72,8 @@ See https://linuxcnc.org/docs/html/drivers/mb2hal.html[] for more information. === Each transaction -*mb2hal.m.num_errors* u32 in:: - Error counter +*mb2hal.m.num_errors* u32 out:: + Error counter (0 means the last transaction succeeded) m = HAL_TX_NAME or transaction number if not set + diff --git a/docs/src/man/man9/hm2_modbus.9.adoc b/docs/src/man/man9/hm2_modbus.9.adoc index 95515acd677..e8b81e5cb14 100644 --- a/docs/src/man/man9/hm2_modbus.9.adoc +++ b/docs/src/man/man9/hm2_modbus.9.adoc @@ -205,6 +205,9 @@ Each mbccb file will generate a set of pins as defined in the mbccb file. See *mesambccc*(1), *mesaflash*(1). +Safety considerations for Modbus-controlled spindles and drives: +https://linuxcnc.org/docs/html/drivers/mb2hal.html#_safety_considerations + == AUTHOR This man page written by B.Stultiens, as part of the LinuxCNC project.