docs: add exclude_object documentation

Also include sample macros to add M486 compatibility.

Signed-off-by: Franklyn Tackitt <git@frank.af>
Co-authored-by: Troy Jacobson <troy.d.jacobson@gmail.com>

1 files changed, 52 insertions, 0 deletions

diff --git a/config/sample-macros.cfg b/config/sample-macros.cfg
index fcb144e0..97e39016 100644
--- a/config/sample-macros.cfg
+++ b/config/sample-macros.cfg
@@ -186,3 +186,55 @@ gcode:
     {% if params.K is not defined and params.L is defined %}SDCARD_LOOP_BEGIN COUNT={params.L|int}{% endif %}
     {% if params.K is not defined and params.L is not defined %}SDCARD_LOOP_END{% endif %}
     {% if params.K is defined and params.L is not defined %}SDCARD_LOOP_DESIST{% endif %}
+
+# Cancel object (aka Marlin/RRF M486 commands) support
+#
+# Enable object exclusion
+[exclude_object]
+
+[gcode_macro M486]
+gcode:
+  # Parameters known to M486 are as follows:
+  #   [C<flag>] Cancel the current object
+  #   [P<index>] Cancel the object with the given index
+  #   [S<index>] Set the index of the current object.
+  #       If the object with the given index has been canceled, this will cause
+  #       the firmware to skip to the next object. The value -1 is used to
+  #       indicate something that isn’t an object and shouldn’t be skipped.
+  #   [T<count>] Reset the state and set the number of objects
+  #   [U<index>] Un-cancel the object with the given index. This command will be
+  #       ignored if the object has already been skipped
+
+  {% if 'exclude_object' not in printer %}
+    {action_raise_error("[exclude_object] is not enabled")}
+  {% endif %}
+
+  {% if 'T' in params %}
+    EXCLUDE_OBJECT RESET=1
+
+    {% for i in range(params.T | int) %}
+      EXCLUDE_OBJECT_DEFINE NAME={i}
+    {% endfor %}
+  {% endif %}
+
+  {% if 'C' in params %}
+    EXCLUDE_OBJECT CURRENT=1
+  {% endif %}
+
+  {% if 'P' in params %}
+    EXCLUDE_OBJECT NAME={params.P}
+  {% endif %}
+
+  {% if 'S' in params %}
+    {% if params.S == '-1' %}
+      {% if printer.exclude_object.current_object %}
+        EXCLUDE_OBJECT_END NAME={printer.exclude_object.current_object}
+      {% endif %}
+    {% else %}
+      EXCLUDE_OBJECT_START NAME={params.S}
+    {% endif %}
+  {% endif %}
+
+  {% if 'U' in params %}
+    EXCLUDE_OBJECT RESET=1 NAME={params.U}
+  {% endif %}