docs: add Modbus safety considerations for spindle and drive control

[grandixximo]

Prompted by #4529: a VFD driven over Modbus holds the last written control word indefinitely, so a LinuxCNC exit, crash or dropped serial link leaves the spindle running and no stop command is ever sent. This was not documented anywhere, and shutdown.hal stop writes only cover the clean-exit case.

This adds a Safety Considerations section to the mb2hal driver doc describing the standard layered practice:

1. Hardwired enable/STO in the machine estop chain, the only layer that qualifies as safety
2. VFD communication-loss watchdog (Modbus timeout => fault/coast), which covers crashes and link drops
3. Splitting VFD command sources: run from a hardwired terminal driven by motion.spindle-on / motion.machine-is-on, Modbus carrying only speed, direction and status. This also avoids read-modify-write on VFDs that multiplex run/stop into one control register

The hm2_modbus man page SEE ALSO points to the new section, since the same considerations apply to every Modbus control path (mb2hal, hm2_modbus, ClassicLadder, custom drivers).

Intentionally does not touch mesa_modbus.adoc to stay conflict-free with #4530, which removes that page.

[rodw-au]

I've been reviewing this. The concensus is that 1 & 2 is mandatory but 3 is optional. There is nothing wrong or unsafe about using fieldbus for spindle on/off provided the other safety methods are implemented. My VFD has 2 options for estop. A single input and a dual redundant estop1, estop2 for use with safety relays.
LinuxCNC does do the right thing on startup as it turns a running spindle off.

[grandixximo]

Fair point, with a hardwired enable/STO layer in place, run and stop over fieldbus is accepted practice. I reworded the section so it no longer reads as all three items being mandatory:

• Item 1 stays the safety layer and now mentions dual redundant estop inputs for use with safety relays, and notes that run/stop over Modbus is fine once this layer exists.
• Item 2 is now "arrange a stop on communication loss" with two implementations: the VFD Modbus timeout parameter, or HAL-side detection. mb2hal has a num_errors pin per transaction (0 means the last transaction succeeded), and feeding it into a machine-off or estop chain stops LinuxCNC when the error count climbs. The HAL-side variant avoids digging through VFD parameterization and needs no rework when the VFD is replaced; the noted tradeoff is that PC-crash coverage then rests on the output hardware watchdog (Mesa watchdog, charge pump).
• Item 3 is explicitly optional now, keeping the note that it avoids read-modify-write when one control register multiplexes run, stop and other commands.

Also fixed the num_errors pin direction in the mb2hal man page while here: it is documented as "u32 in" but has been HAL_OUT in the source since the pin was introduced in 2012.

[rodw-au]

Thanks, I think its pretty good now. Thanks for doing that. I will review again when build a new control panel in a couple of weeks. Counting the errors is a robust idea. The Comp component could do that easily.

I know its only documentation but it is important to cover it due to safety concerns. I don't think I've ever seen this discussed on any modbus forum post.

[grandixximo]

It was undocumented tribal knowledge, now written down 😉

[rodw-au]

It was undocumented tribal knowledge, now written down 😉

It is now real knowledge! :)