build: Clarify pin mapping/don't override defines

[brianredbeard]

Previously all pin mapping of ganged axes was an exercise left to the user.

In ac96edd4 this behavior was changed to remove the burden from the user through the use of sensible default behavior.

This extends that work by:

• Clarifying the comments explaining the behavior (which were out of date in some cases)
• Expands the explainations to avoid potential mis-configurations
• Checking if the options if the following options were previously defined and only setting them in the event that they were not:
  • X_GANGED
  • X_AUTO_SQUARE
  • Y_GANGED
  • Y_AUTO_SQUARE
  • Z_GANGED
  • Z_AUTO_SQUARE

Users may now define _GANGED and _AUTO_SQUARE in my_machine.h without raising compiler warnings or having the values re-defined in the relevant map file.

All existing pin mappings were left as is to ensure there is no change in behavior for existing users.

[terjeio]

I have a commit pending that standardizes this across all drivers/boards that support ganged/auto-squared axes. Central to this is a file with 600 lines of preprocessor code that makes it easy to add ganged/auto-squared axes. It allows simple tests for unused motor pins, these can then be assigned to auxillary I/O or any other relevant use in the map file.

It is done by defining extra motors (beyond XY and Z) as M3 - M5, e.g for the T41U5XBB_map.h these motors are defined like this:

// Define ganged axis or A axis step pulse and step direction output pins.
#if N_ABC_MOTORS > 0
#define M3_AVAILABLE
#define M3_STEP_PIN         (8u)
#define M3_DIRECTION_PIN    (9u)
#define M3_LIMIT_PIN        (23u)
#define M3_ENABLE_PIN       (38u)
#endif

// Define ganged axis or B axis step pulse and step direction output pins.
#if N_ABC_MOTORS == 2
#define M4_AVAILABLE
#define M4_STEP_PIN         (26u)
#define M4_DIRECTION_PIN    (27u)
#define M4_LIMIT_PIN        (28u)
#define M4_ENABLE_PIN       (37u)
#endif

Increasing N_AXIS configuration will assign motor pins from M3 upwards, ganged/auto-squared axes from the highest available motor (M4 in this example) and downwards. So for the T41U5XBB board any combination of A and B axis and/or one or two ganged/autosquared axes that results in the use of these two motors is possible. Misconfigured axes will result in a compile time error.

There are board maps that supports more than 3 motors but do not have limit pins available for them, these are can only be assigned to a ganged axis. Some have both max and min limit switches available, this is handled as well.

Configuration in my_machine.h looks like this:

// If the selected board map supports more than three motors ganging and/or auto-squaring
// of axes can be enabled here.
#define X_GANGED            0
#define X_AUTO_SQUARE       0
#define Y_GANGED            0
#define Y_AUTO_SQUARE       1
#define Z_GANGED            1
#define Z_AUTO_SQUARE       0
// For ganged axes the limit switch input (if available) can be configured to act as a max travel limit switch.
// NOTE: If board map already has max limit inputs defined this configuration will be ignored.
#define X_GANGED_LIM_MAX    0
#define Y_GANGED_LIM_MAX    0
#define Z_GANGED_LIM_MAX    0
//

I have not spent much thought on how to document these options in my_machine.h, uncommenting to enable like the other options is a better way to do it? What do you think?

FYI I need to do a bit more testing before committing this change.