Print detailed documentation with `HELP MY_MACRO` command

Motivation

For Klipper commands, it is not always obvious what arguments a command accepts.
For built-in macros there is a useful website G-Codes - Klipper documentation and for marlin gcodes you have Gcode | Marlin Firmware.

For macros that are installed from somewhere on the internet, it might take a while to find the documentation or there is none available, which forces you to look into the macro source code. This takes time and is sometimes very annoying. For example when you have to look up if an argument is called TOOLHEAD_TEMP or EXTRUDER_TEMP.

User Interfaces like mainsail, fluidd or KlipperScreen alleviate this issue by parsing the macro source code to display the arguments:
image

The argument parsing only works with macros and does not help with commands implemented in python (or alternative gcode_macros like klipper_extras/extended_macro at main · droans/klipper_extras · GitHub). There is no documentation for the individual arguments, so you still do not know what they do.

Some macros embed their documentation in the description section, like for example here

The problem with this is that the output of the HELP command will become too long to find what you are searching for:


As can be seen in the screenshot, it is difficult to see where the help message of one command ends and the next one starts.

Other macros have their documentation only in the source code

(which is even worse, because sometimes macros are nested in some folders or in a file that does not have the name of the macro)

Proposed Solution

The HELP command should accept a second argument that can be used to get detailed documentation for a macro or command:

$ HELP M17
Enables the specified stepper motors.
If no flags are specified, all motors are enabled.

Usage: M17 [E] [X] [Y] [Z]

Parameters:
- [E] Enable extruder
- [X] Enable x stepper
- [Y] Enable y stepper
- [Z] Enable z stepper

https://marlinfw.org/docs/gcode/M017.html

I know that in Klipper each argument should be named like HELP NAME=M17, which might be implemented instead of the above.

Unresolved questions

Where should the HELP command get the documentation from? I have two ideas:

  1. The HELP command will no longer display all lines of the description: section, only the first line which should be a brief description of the command. The HELP COMMAND would then print the entire description.
  2. Add a new section to the gcode_macro like help:. I think this will be confusing, because then there would be two sections to document a macro.

I think this is a fantastic idea. The implementation without causing confusion is a “gotcha” though.

I wonder if description should be left the way it is, and maybe a syntax field can be added instead or something.

It’s tough because the console is very simple and I prefer it that way, but some way to understand how to use the macro rather than just a description would be very beneficial. Maybe a flag can be added similar to Linux commands when calling a macro like MY_MACRO —HELP and it would print what is in the help field of the macro.

1 Like

This right here is the issue, and why implementing something like this probably wouldn’t make any difference. Users who install random macros from “somewhere on the internet” without knowing why or what they do aren’t going to read documentation. And if macro authors aren’t already providing usage instructions, it’s not because of a lack of a dedicated mechanism. The existing description field is well suited for providing usage instructions if the author so desires. I’m not sure I understand the concern about the description being too long or confusing. The screenshot you provided looks concise and very clear to me.

1 Like

I’m not sure I understand the concern about the description being too long or confusing. The screenshot you provided looks concise and very clear to me.

Due to the command window being quite small, the screenshot might not have conveyed my problem with the current description field.

When I execute the HELP command on my printer, I currently get this output:

Available extended commands:
ACTIVATE_EXTRUDER: Change the active extruder
BED_MESH_CALIBRATE: Perform Mesh Bed Leveling
BED_MESH_CLEAR: Clear the Mesh so no z-adjustment is made
BED_MESH_MAP: Serialize mesh and output to terminal
BED_MESH_OFFSET: Add X/Y offsets to the mesh lookup
BED_MESH_OUTPUT: Retrieve interpolated grid of probed z-points
BED_MESH_PROFILE: Bed Mesh Persistent Storage management
BED_SCREWS_ADJUST: Tool to help adjust bed leveling screws
BLTOUCH_DEBUG: Send a command to the bltouch for debugging
BLTOUCH_STORE: Store an output mode in the BLTouch EEPROM
CALIBRATE_MPC: Calibrate MPC for the specified heater.
Usage: CALIBRATE_MPC HEATER=extruder Z=1.0

Parameters:
- [HEATER] The heater to calibrate, by default the extruder.
- [Z] How close the nozzle should be to the bed for calibration.
CALIBRATE_PID: Calibrate PID for extruder and bed.
Usage: CALIBRATE_PID EXTRUDER_TEMP=215 BED_TEMP=60

Parameters:
- [EXTRUDER_TEMP] The temperature of the extruder when calibrating.
- [BED_TEMP] The temperature of the bed when calibrating.
CALIBRATE_PRESSURE_ADVANCE: Print calibration pattern for pressure advance value.
CALIBRATE_XYZ_CUBE: Print XYZ calibration cube.
CANCEL_PRINT: Cancel the actual running print
CANCEL_PRINT_1: Renamed builtin of 'CANCEL_PRINT'
CLEAR_PAUSE: Clears the current paused state without resuming the print
D117 : Emit a message to the console.
DEBUG_EXTRUDER_VALUES: Prints the extruder values that depend on nozzle/filament diameter, useful for debugging.
END_PRINT : G-Code macro
EXCLUDE_OBJECT: Cancel moves inside a specified objects
EXCLUDE_OBJECT_DEFINE: Provides a summary of an object
EXCLUDE_OBJECT_END: Marks the end the current object
EXCLUDE_OBJECT_START: Marks the beginning the current object as labeled
FIRMWARE_RESTART: Restart firmware, host, and reload config
G28 : Home one or more axes.
Usage:
G28 [O] [X] [Y] [Z]

Parameters:
- [O] Flag to skip homing if the position is already trusted ("smart home")
- [X] Flag to home X axis
- [Y] Flag to home Y axis
- [Z] Flag to home Z axis

https://marlinfw.org/docs/gcode/G028.html
G28.1 : Renamed builtin of 'G28'
GET_POSITION: Return information on the current location of the toolhead
GET_RETRACTION: Report firmware retraction paramters
HELP : Report the list of available extended G-Code commands
LINE_PURGE: A purge macro that adapts to be near your actual printed objects
LOAD_FILAMENT: Load filament into the active extruder.
Usage: LOAD_FILAMENT EXTRUDER_TEMP= PURGE_LENGTH= PURGE_FEEDRATE=
TRAVEL_SPEED=

Parameters:
- [EXTRUDER_TEMP] Temperature of the extruder for purging filament
- [PURGE_LENGTH] How much filament should be extruded (purged) in mm
- [PURGE_FEEDRATE] How fast the filament should be purged (in mm/s)
- [TRAVEL_SPEED] How fast the printer should move
M17 : Enables the specified stepper motors.
If no flags are specified, all motors are enabled.

Usage: M17 [E] [X] [Y] [Z]

Parameters:
- [E] Enable extruder
- [X] Enable x stepper
- [Y] Enable y stepper
- [Z] Enable z stepper

https://marlinfw.org/docs/gcode/M017.html
M18 : Disables the specified stepper motors.
If no flags are specified, all motors are disabled.

Usage: M18 [E] [S] [X] [Y] [Z]

Parameters:
- [E] Enable extruder
- [X] Enable x stepper
- [Y] Enable y stepper
- [Z] Enable z stepper
- [S] Inactivity Timeout. If none specified, disable now.

https://marlinfw.org/docs/gcode/M018.html
M18.1 : Renamed builtin of 'M18'
M600 : Change filament.
Usage: M600 [R] [B] [X] [Y] [Z]

Parameters:
- [R] Temperature of the extruder for purging filament, by default target temperature or 180°C if target is lower.
- [R] Temperature of the bed, by default remains unchanged.
- [X] X position for filament change
- [Y] Y position for filament change
- [Z] Z relative lift for filament change position

https://marlinfw.org/docs/gcode/M600.html
M701 : Load filament into the active extruder.
Usage: M701 [T] [L] [F] [S]

Parameters:
- [T] Temperature of the extruder for purging filament, by default 210°C.
- [L] How much filament should be extruded (purged) in mm, by default 50mm.
- [F] How fast the filament should be purged, by default 3
- [S] How fast the printer should move, by default 1000
https://marlinfw.org/docs/gcode/M701.html
M702 : Unload filament from the active extruder.
Usage: M702 [S]

Parameters:
- [S] Temperature of the extruder for purging filament, by default 210°C.

https://marlinfw.org/docs/gcode/M702.html
M84 : Disables the specified stepper motors.
If no flags are specified, all motors are disabled.

Usage: M84 [E] [S] [X] [Y] [Z]

Parameters:
- [E] Enable extruder
- [X] Enable x stepper
- [Y] Enable y stepper
- [Z] Enable z stepper
- [S] Inactivity Timeout. If none specified, disable now.

https://marlinfw.org/docs/gcode/M018.html
M84.1 : Renamed builtin of 'M84'
MANUAL_PROBE: Start manual probe helper script
MPC_CALIBRATE: Run MPC calibration test
MPC_ENABLE: Enable MPC algorithm for heating
MPC_UPDATE: Update values for the MPC algorithm
OFF : Macro to power off everything.
Usage: OFF

https://ellis3dp.com/Print-Tuning-Guide/articles/useful_macros/off.html
PAUSE : Pause the actual running print
PAUSE_BASE: Renamed builtin of 'PAUSE'
PID_CALIBRATE: Run PID calibration test
PRINT_VARIABLES: Prints all variables or only those that match a specific filter.
PROBE : Probe Z-height at current XY position
PROBE_ACCURACY: Probe Z-height accuracy at current XY position
PROBE_CALIBRATE: Calibrate the probe's z_offset
QUERY_ADC : Report the last value of an analog pin
QUERY_ENDSTOPS: Report on the status of each endstop
QUERY_FILAMENT_SENSOR: Query the status of the Filament Sensor
QUERY_PROBE: Return the status of the z-probe
RESPOND : Echo the message prepended with a prefix
RESTART : Reload config file and restart host software
RESTORE_GCODE_STATE: Restore a previously saved G-Code state
RESUME : Resume the actual running print
SAVE_CONFIG: Overwrite config file and restart
SAVE_GCODE_STATE: Save G-Code coordinate state
SCREWS_TILT_CALCULATE: Tool to help adjust bed leveling screws by calculating the number of turns to level it.
SDCARD_PRINT_FILE: Loads a SD file and starts the print. May include files in subdirectories.
SDCARD_RESET_FILE: Clears a loaded SD File. Stops the print if necessary
SET_DISPLAY_TEXT: Set or clear the display message
SET_EXTRUDER_ROTATION_DISTANCE: Set extruder rotation distance
SET_EXTRUDER_STEP_DISTANCE: Set extruder step distance
SET_FILAMENT_DIAMETER: Sets the filament diameter to the specified value
SET_FILAMENT_SENSOR: Sets the filament sensor on/off
SET_GCODE_OFFSET: Set a virtual offset to g-code positions
SET_GCODE_VARIABLE: Set the value of a G-Code macro variable
SET_HEATER_TEMPERATURE: Sets a heater temperature
SET_IDLE_TIMEOUT: Set the idle timeout in seconds
SET_NOZZLE_DIAMETER: Sets the nozzle diameter to the specified value
SET_PAUSE_AT_LAYER: Enable/disable a pause if a given layer number is reached
SET_PAUSE_NEXT_LAYER: Enable a pause if the next layer is reached
SET_PRESSURE_ADVANCE: Set pressure advance parameters
SET_PRINT_STATS_INFO: Overwrite, to get pause_next_layer and pause_at_layer feature
SET_PRINT_STATS_INFO_BASE: Renamed builtin of 'SET_PRINT_STATS_INFO'
SET_RETRACTION: Set firmware retraction parameters
SET_STEPPER_ENABLE: Enable/disable individual stepper by name
SET_VELOCITY_LIMIT: Set printer velocity limits
SHUTDOWN : Powers off the klipper host.
SIMPLE_PURGE_LINE: Implements the standard purge line on the left side of the bed.
START_PRINT: G-Code macro
STATUS : Report the printer status
STEPPER_BUZZ: Oscillate a given stepper to help id it
SWAP_FILAMENT: Change filament.
Usage: SWAP_FILAMENT [EXTRUDER_TEMP=] [BED_TEMP=] [X=] [Y=] [Z=]

Parameters:
- [EXTRUDER_TEMP] Temperature of the extruder for purging filament, by default 180°C.
- [BED_TEMP] Temperature of the bed for purging filament, by default 0°C.
- [X] X position for filament change
- [Y] Y position for filament change
- [Z] Z relative lift for filament change position
SWAP_RESUME: Resume a print after swapping filament.
SYNC_EXTRUDER_MOTION: Set extruder stepper motion queue
SYNC_STEPPER_TO_EXTRUDER: Set extruder stepper
TEMPERATURE_WAIT: Wait for a temperature on a sensor
TEST_BATTERIES_INCLUDED: A test macro to show that the script is working
TUNING_TOWER: Tool to adjust a parameter at each Z height
TURN_OFF_HEATERS: Turn off all heaters
UNLOAD_FILAMENT: Unload filament from the active extruder.
Usage: UNLOAD_FILAMENT EXTRUDER_TEMP=

Parameters:
- [EXTRUDER_TEMP] Temperature of the extruder for unloading filament
UPDATE_DELAYED_GCODE: Update the duration of a delayed_gcode
Z_OFFSET_APPLY_PROBE: Adjust the probe's z_offset

My own macros are the ones with more than one sentence as descriptions. I intentionally did not add more documentation (even though I want to), so I can still scroll through all commands.

The output in its current state is fine, but it will take a while to scroll through all of them and with multiline descriptions, it is easy to miss a command. For example here:

CALIBRATE_MPC: Calibrate MPC for the specified heater.
Usage: CALIBRATE_MPC HEATER=extruder Z=1.0

Parameters:
- [HEATER] The heater to calibrate, by default the extruder.
- [Z] How close the nozzle should be to the bed for calibration.
CALIBRATE_PID: Calibrate PID for extruder and bed.
Usage: CALIBRATE_PID EXTRUDER_TEMP=215 BED_TEMP=60

Parameters:
- [EXTRUDER_TEMP] The temperature of the extruder when calibrating.
- [BED_TEMP] The temperature of the bed when calibrating.
CALIBRATE_PRESSURE_ADVANCE: Print calibration pattern for pressure advance value.

one might overlook the CALIBRATE_PID command, because there isn’t any spacing between the descriptions.

Users who install random macros from “somewhere on the internet” without knowing why or what they do aren’t going to read documentation

Well, I am one of those people who install random macros like KAMP or klippain from somewhere on the internet. Like, why should you redo all the work that other people already did for you? This feature is obviously not for those who have no clue what they are doing or refuse to read documentation.

On Linux (and Windows, more like any operating system) it is the standard to provide some mechanism to get the usage documentation conveniently in the terminal. I do not want to open a browser window and search for docs every time I forget what some flag was called. Most people can not remember all the different ways a command can be used, or what the exact name of some command line flag was. For example, this is the help command for git:

âžś  ~ git --help
usage: git [--version] [--help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           [--super-prefix=<path>] [--config-env=<name>=<envvar>]
           <command> [<args>]

These are common Git commands used in various situations:

start a working area (see also: git help tutorial)
   clone     Clone a repository into a new directory
   init      Create an empty Git repository or reinitialize an existing one

work on the current change (see also: git help everyday)
   add       Add file contents to the index
   mv        Move or rename a file, a directory, or a symlink
   restore   Restore working tree files
   rm        Remove files from the working tree and from the index

examine the history and state (see also: git help revisions)
   bisect    Use binary search to find the commit that introduced a bug
   diff      Show changes between commits, commit and working tree, etc
   grep      Print lines matching a pattern
   log       Show commit logs
   show      Show various types of objects
   status    Show the working tree status

grow, mark and tweak your common history
   branch    List, create, or delete branches
   commit    Record changes to the repository
   merge     Join two or more development histories together
   rebase    Reapply commits on top of another base tip
   reset     Reset current HEAD to the specified state
   switch    Switch branches
   tag       Create, list, delete or verify a tag object signed with GPG

collaborate (see also: git help workflows)
   fetch     Download objects and refs from another repository
   pull      Fetch from and integrate with another repository or a local branch
   push      Update remote refs along with associated objects

'git help -a' and 'git help -g' list available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.
See 'git help git' for an overview of the system.

For most programs, you can find all the necessary documentation through their help commands and don’t have to look up their help pages: Git - git Documentation. I think this is very convenient, and I do not understand why a similar convenience should not exist in klipper.

And if macro authors aren’t already providing usage instructions, it’s not because of a lack of a dedicated mechanism. The existing description field is well suited for providing usage instructions if the author so desires.

Because of the lack of a dedicated mechanism, many document their macros not in the description field, but on their github page or as a comment in the source code:

Most of the bigger macro repos do provide usage instructions, but they end up in places that are suboptimal for macro users. The description field seems to be intended as a short description of what the command does in a single line and dedicated documentation is supposed to be somewhere else (like for the built-in klipper commands).

fwiw: I almost totally agree that point 1 is the way forward. ie HELP should be consistent with the help in most OS terminals ie HELP COMMAND should print the help for that specific command.
I don’t think there is a need for en extra help section if the description parser is re-entrant.
My proposal would be that

  • if a description is provided on a single line, then act as the current HELP does.

  • if description has more than 1 line HELP should print the first line followed by an ellipsis… and a blank line to make it obvious that the user can expect more info if they type HELP COMMAND

  • if description contains different levels of indent then these can be suppressed until the user types HELP COMMAND PARAMETER

  • Any link containing HTTP or HTTPS should be displayed as a link in the help output and open a new browser window (people who don’t like lots of windows probably already have openNewWindow set to openNewWindowInNewTab)

As an example:

GET_POSITION: Return information on the current location of the toolhead
HELP : Report the list of available extended G-Code commands...

INIT_TMC : Initialize TMC stepper driver registers
LIGHT_OFF : G-Code macro

As an example of HELP HELP:

HELP : Report the list of available extended G-Code commands...
HELP COMMAND: List help for the given command
  if the command supports PARAMETER(s) you can type HELP COMMAND PARAMETER

As an example of a command called GRUNGIFY

GRUNGIFY:  A macro which does absolutely nothing but looks pretty...
  Usage: GRUNGIFY [X-Pos]|[Y-Pos]|Effect
  You can find more help by typing HELP GRUNGIFY EFFECT
  or check on http://a_random_url

The random_url should be a clickable link

[gcode_macro grungify xpos ypos effectstyle]
description: A macro which does absolutely nothing but looks pretty
  Usage: GRUNGIFY [X-Pos]|[Y-Pos]|Effect
  You can find more help by typing HELP GRUNGIFY EFFECT
  or check on http://a_random_url
    Effect: Effect is one of [random]|[rainbow]|[flame]
    Type  HELP GRUNGIFY EFFECT EFFECTNAME to see more
      random is totally Ronseal
      rainbow selects and loads your next filament from your autoloader
      flame causes a filament jam and sets fire to your printer
    to find more about individual effects
    type GRUNGIFY EFFECT and the effect name
gcode:
   some meaningless bit of code

Sorry several edits to this. I seem to be suffering some strange typo_blindness today

Not sure I understand correctly. Why not send the help command and the “ctrl + F” the macro name you’re looking for? Or am I misunderstanding this entirely?

@tymau5

The discussion is about how Klipper should interpret attempts to make Macros respond in a unified way to the Help command. At the moment it just outputs everything after a description: statement within the macro. Because the mechanism is very limiting, not many authors put anything at all, so htyping HELP with a macro name doesn’t actually give any useful help.

1 Like