🧑‍💻 Clean up the endstops situation

[thinkyhead]

The configuration and handling of end-stops have evolved over time to become a bit confusing and sometimes a little problematic. For example, bug report #25747 points out one problem with USE_ZMIN_PLUG.

Background

The endstops code implementation was originally set up to monitor any endstop pins that exist, based on the direction that the axis is homing, and endstop pins were simply undefined if they weren't going to be used. So the endstops.cpp code could just look for a pin and use that as the sole criterion for processing that endstop.

At some point we added the USE_*_PLUG options to allow unused endstop pins to remain defined so that they could be referenced for another usage, such as #define FIL_RUNOUT_PIN Z_MAX_PIN or when X2_USE_ENDSTOP == _XMAX_. Most likely we did it this way because we needed to do Conditionals voodoo related to endstops before the point where pins.h was included.

Meanwhile, this #define X2_USE_ENDSTOP == _XMIN_ thing could also be better.

This stuff was also developed before we had any boards with only 3 endstop pins, named X_STOP_PIN, etc., and before we had sensorless DIAG pins that may also wire to the regular endstop plugs.

A Problem

Issue #25747 implies that USE_ZMIN_PLUG can cause problems with the probe even though the endstop is not specified for homing, likely because Z_MIN_PIN is being monitored inappropriately. The machine is still homing to min, but the probe is probably not using the Z_MIN_PIN, and yet the state of Z_MIN_PIN is being applied. So that needs to be sorted out.

The Other Problem

Endstop pins aren't all that complicated, but we have a huge amount preprocessor junk to work around the stale implementation in `endstops.cpp'.

Solution

This PR is a work-in-progress to wrangle all these endstop issues:

• Simplify configuration so that USE_*_PLUG doesn't need to be specified.
• Always leave all the board endstop pins defined, so they can be seen in M43 reports and used freely.
• Don't use the PIN_EXISTS as a criterion for initializing and monitoring endstop pins.
• Related to that, get rid of the conditionals HAS_X_MIN, etc.
• Replace X2_USE_ENDSTOP, etc., with the clear define: #define X2_STOP_PIN X_MAX_PIN.

Other Things

• Consider allowing two endstops on a single axis, if desired, for things like CNC safety.
• Consider attaching special handlers to endstops for things like timelapse and multi-filament units.

[marciot]

@thinkyhead: I have a question about this commit. At some point in the past, it was possible to define "USE_XMAX_PLUG" even if the printer was homing to X min (i.e. X_HOME_DIR is -1). The reason for having both X_MIN and X_MAX active simultaneously is to prevent the printer from skipping steps if it tried to exceed the end stop on a non-homing move. After this cleanup, it is not clear to me how to tell Marlin that the X_MAX end-stop exists and should be checked during non-homing moves on a printer that homes to X_MIN.

This was needed by certain older LulzBot printers where the same firmware file was used on two generations of printers with slightly different travel limits. Rather than having two different firmware files with the correct X_MAX values for the printer, the soft limit was set to a value larger than the physical travel, with the consequence that during probing the head would hit the end-stop and movement would cease, thus making the same firmware work regardless of the printer model.

[thinkyhead]

I haven't entirely formalized that, but one of the points of the refactor is to get that formalized rather than relying on an unstated side-effect. So I stuck in a check for "(AXIS)_SAFETY_STOP" as a way to have more than one endstop on a single axis, but haven't added that as a configuration option yet, pending the collection of more information about use cases.

[marciot]

@thinkyhead: It sounds like "(AXIS)_SAFETY_STOP" is what I need for those old LulzBot printers. Thank you!

[marciot]

@thinkyhead: I tried grepping the code in bugfix-2.1.x for "SAFETY" and I see nothing. Has this been implemented yet?

[thinkyhead]

Check out #25758 which should be merged soon. I just have to work out a couple more details.

[MotoBarsteward]

Sorry, I'm slow on the uptake here. I have a Prusa that's modified to have a dual x carriage and it was working when I took the latest if February. Since then, you've done a lot of work on end stops. You used to be able to specify the X_MAX end stop for use in homing the second X carriage. Now there is no way to do it. Is it automatically done, now, just by specifying that there is an X2 motor? The problem I see is in line "if HAS_X2_STEPPER && DISABLED(DUAL_X_CARRIAGE)" which will always evaluate false if I define DUAL_X_CARRIAGE and X_DUAL_ENDSTOPS never gets defined.

[wnto]

in https://marlinfw.org/docs/configuration/configuration.html#endstops

Endstop Plugs #define USE_XMIN_PLUG #define USE_YMIN_PLUG #define USE_ZMIN_PLUG //#define USE_XMAX_PLUG //#define USE_YMAX_PLUG //#define USE_ZMAX_PLUG

continues to be suggested. If I try to compile using these options in config.h. I get an error.

#error "USE_*_PLUG settings are no longer needed and should be removed."

Should the documentation be updated by eliminating the plugs? If so, what else should be added to that part of the documentation?

I would be glad to help with the documentation text if I know where to look to understand what is the current state of endstops configurations.

[thisiskeithb]

Should the documentation be updated by eliminating the plugs?

Yes, the entire page needs to be wiped & redone using the current configs. Your best bet is to read the inline documentation in Configuration.h & Configuration_adv.h since those are the most up to date.

[wnto]

OK, I've compared the documentation site and the config.h. file. I made two simple changes that should bring a bit of clarity to this section.
MarlinFirmware/MarlinDocumentation@master...wnto:MarlinDocumentation:patch-1

Thanks for the pointers. This is my first pull request (?) ever, I hope I did it correctly.