diff options
| -rw-r--r-- | docs/API_Server.md | 5 | ||||
| -rw-r--r-- | docs/Command_Templates.md | 208 | ||||
| -rw-r--r-- | docs/Overview.md | 2 | ||||
| -rw-r--r-- | docs/Status_Reference.md | 303 |
4 files changed, 310 insertions, 208 deletions
diff --git a/docs/API_Server.md b/docs/API_Server.md index 7c306a2a..eaa5bdb9 100644 --- a/docs/API_Server.md +++ b/docs/API_Server.md @@ -204,9 +204,8 @@ object name and the value is a dictionary containing its fields. The response message will also contain an "eventtime" field containing the timestamp from when the query was taken. -Available fields are documented in the -[Command Template](Command_Templates.md#the-printer-variable) -document. +Available fields are documented in the [Status +Reference](Status_Reference.md) document. ### objects/subscribe diff --git a/docs/Command_Templates.md b/docs/Command_Templates.md index b68de68b..a5e3d323 100644 --- a/docs/Command_Templates.md +++ b/docs/Command_Templates.md @@ -120,6 +120,9 @@ gcode: M106 S{ printer.fan.speed * 0.9 * 255} ``` +Available fields are defined in the [Status +Reference](Status_Reference.md) document. + Important! Macros are first evaluated in entirety and only then are the resulting commands executed. If a macro issues a command that alters the state of the printer, the results of that state change will @@ -136,211 +139,6 @@ objects. If the config section contains spaces in it, then one can access it via the `[ ]` accessor - for example: `printer["generic_heater my_chamber_heater"].temperature`. -The following are common printer attributes: -- `printer.fan.speed`: The fan speed as a float between 0.0 and 1.0. - This is also available on "heater_fan", "fan_generic", and - "controller_fan" config sections (eg, - `printer["fan_generic my_fan"].speed`). -- `printer.fan.rpm`: The measured fan speed in rotations per minute if - the fan has a tachometer_pin defined. This is also available on - "heater_fan", "fan_generic", and "controller_fan" config sections - (eg, `printer["fan_generic my_fan"].rpm`). -- `printer.gcode_move.gcode_position`: The current position of the - toolhead relative to the current G-Code origin. That is, positions - that one might directly send to a `G1` command. It is possible to - access the x, y, z, and e components of this position (eg, - `printer.gcode_move.gcode_position.x`). -- `printer.gcode_move.position`: The last commanded position of the - toolhead using the coordinate system specified in the config - file. It is possible to access the x, y, z, and e components of this - position (eg, `printer.gcode_move.position.x`). -- `printer.gcode_move.homing_origin`: The origin of the gcode - coordinate system (relative to the coordinate system specified in - the config file) to use after a `G28` command. The - `SET_GCODE_OFFSET` command can alter this position. It is possible - to access the x, y, and z components of this position (eg, - `printer.gcode_move.homing_origin.x`). -- `printer.gcode_move.speed`: The last speed set in a `G1` command (in - mm/s). -- `printer.gcode_move.speed_factor`: The "speed factor override" as - set by an `M220` command. This is a floating point value such - that 1.0 means no override and, for example, 2.0 would double - requested speed. -- `printer.gcode_move.extrude_factor`: The "extrude factor override" - as set by an `M221` command. This is a floating point value such - that 1.0 means no override and, for example, 2.0 would double - requested extrusions. -- `printer.gcode_move.absolute_coordinates`: This returns True if in - `G90` absolute coordinate mode or False if in `G91` relative mode. -- `printer.gcode_move.absolute_extrude`: This returns True if in `M82` - absolute extrude mode or False if in `M83` relative mode. -- `printer["gcode_macro <macro_name>"].<variable>`: The current value - of a gcode_macro variable. -- `printer.<heater>.temperature`: The last reported temperature (in - Celsius as a float) for the given heater. Example heaters are: - `extruder`, `extruder1`, `heater_bed`, `heater_generic - <config_name>`. -- `printer.<heater>.target`: The current target temperature (in - Celsius as a float) for the given heater. -- `printer.<heater>.power`: The last setting of the PWM pin (a value - between 0.0 and 1.0) associated with the heater. -- `printer.idle_timeout.state`: The current state of the printer as - tracked by the idle_timeout module. It is one of the following - strings: "Idle", "Printing", "Ready". -- `printer.idle_timeout.printing_time`: The amount of time (in - seconds) the printer has been in the "Printing" state (as tracked by - the idle_timeout module). -- `printer.pause_resume.is_paused`: Returns true if a PAUSE command - has been executed without a corresponding RESUME. -- `printer.toolhead.position`: The last commanded position of the - toolhead relative to the coordinate system specified in the config - file. It is possible to access the x, y, z, and e components of this - position (eg, `printer.toolhead.position.x`). -- `printer.toolhead.extruder`: The name of the currently active - extruder. For example, one could use - `printer[printer.toolhead.extruder].target` to get the target - temperature of the current extruder. -- `printer.toolhead.homed_axes`: The current cartesian axes considered - to be in a "homed" state. This is a string containing one or more of - "x", "y", "z". -- `printer.toolhead.axis_minimum`, - `printer.toolhead.axis_maximum`: The axis travel limits (mm) after homing. - It is possible to access the x, y, z components of this - limit value (eg, `printer.toolhead.axis_minimum.x`, - `printer.toolhead.axis_maximum.z`). -- `printer.toolhead.max_velocity`, `printer.toolhead.max_accel`, - `printer.toolhead.max_accel_to_decel`, - `printer.toolhead.square_corner_velocity`: The current printing - limits that are in effect. This may differ from the config file - settings if a `SET_VELOCITY_LIMIT` (or `M204`) command alters them - at run-time. -- `printer.toolhead.stalls`: The total number of times (since the last - restart) that the printer had to be paused because the toolhead - moved faster than moves could be read from the G-Code input. -- `printer.heaters.available_heaters`: Returns a list of all currently - available heaters by their full config section names, - e.g. `["extruder", "heater_bed", "heater_generic my_custom_heater"]`. -- `printer.heaters.available_sensors`: Returns a list of all currently - available temperature sensors by their full config section names, - e.g. `["extruder", "heater_bed", "heater_generic my_custom_heater", - "temperature_sensor electronics_temp"]`. -- `printer.query_endstops.last_query["<endstop>"]`: Returns True if - the given endstop was reported as "triggered" during the last - QUERY_ENDSTOP command. Note, due to the order of template expansion - (see above), the QUERY_ENDSTOP command must be run prior to the - macro containing this reference. -- `printer.probe.last_query`: Returns True if the probe was reported - as "triggered" during the last QUERY_PROBE command. Note, due to the - order of template expansion (see above), the QUERY_PROBE command - must be run prior to the macro containing this reference. -- `printer.probe.last_z_result`: Returns the Z result value of the - last PROBE command. Note, due to the order of template expansion - (see above), the PROBE (or similar) command must be run prior to the - macro containing this reference. -- `printer.configfile.settings.<section>.<option>`: Returns the given - config file setting (or default value) during the last software - start or restart. (Any settings changed at run-time will not be - reflected here.) -- `printer.configfile.config.<section>.<option>`: Returns the given - raw config file setting as read by Klipper during the last software - start or restart. (Any settings changed at run-time will not be - reflected here.) All values are returned as strings. -- `printer["gcode_macro <macro_name>"].<variable>`: The current value - of a [gcode_macro variable](#variables). -- `printer.webhooks.state`: Returns a string indicating the current - Klipper state. Possible values are: "ready", "startup", "shutdown", - "error". -- `printer.webhooks.state_message`: A human readable string giving - additional context on the current Klipper state. -- `printer.display_status.progress`: The progress value of the last - `M73` G-Code command (or `printer.virtual_sdcard.progress` if no - recent `M73` received). -- `printer.display_status.message`: The message contained in the last - `M117` G-Code command. -- `printer["filament_switch_sensor <config_name>"].enabled`: Returns - True if the switch sensor is currently enabled. -- `printer["filament_switch_sensor <config_name>"].filament_detected`: - Returns True if the sensor is in a triggered state. -- `printer.virtual_sdcard.is_active`: Returns True if a print from - file is currently active. -- `printer.virtual_sdcard.progress`: An estimate of the current print - progress (based of file size and file position). -- `printer.virtual_sdcard.file_position`: The current position (in - bytes) of an active print. -- `printer.print_stats.filename`, - `printer.print_stats.total_duration`, - `printer.print_stats.print_duration`, - `printer.print_stats.filament_used`, `printer.print_stats.state`, - `printer.print_stats.message`: Estimated information about the - current print when a virtual_sdcard print is active. -- `printer.firmware_retraction.retract_length`, - `printer.firmware_retraction.retract_speed`, - `printer.firmware_retraction.unretract_extra_length`, - `printer.firmware_retraction.unretract_speed`: The current settings - for the firmware_retraction module. These settings may differ from - the config file if a `SET_RETRACTION` command alters them. -- `printer["bme280 <sensor_name>"].temperature`, - `printer["bme280 <sensor_name>"].humidity`, - `printer["bme280 <sensor_name>"].pressure`, - `printer["bme280 <sensor_name>"].gas`: The last read values - from the sensor. -- `printer["htu21d <sensor_name>"].temperature`, - `printer["htu21d <sensor_name>"].humidity`: The last read values - from the sensor. -- `printer["lm75 <sensor_name>"].temperature`: The last read - temperature from the sensor. -- `printer["temperature_host <sensor_name>"].temperature`: The last read - temperature from the sensor. -- `printer["temperature_sensor <config_name>"].temperature`: The last read - temperature from the sensor. -- `printer["temperature_sensor <config_name>"].measured_min_temp`, - `printer["temperature_sensor <config_name>"].measured_max_temp`: The - lowest and highest temperature seen by the sensor since the Klipper - host software was last restarted. -- `printer["temperature_fan <config_name>"].temperature`: The last read - temperature from the sensor. -- `printer["temperature_fan <config_name>"].target`: The target - temperature for the fan. -- `printer["output_pin <config_name>"].value`: The "value" of the pin, - as set by a `SET_PIN` command. -- `printer["servo <config_name>"].value`: The last setting of the PWM - pin (a value between 0.0 and 1.0) associated with the servo. -- `printer.bed_mesh.profile_name`, `printer.bed_mesh.mesh_min`, - `printer.bed_mesh.mesh_max`, `printer.bed_mesh.probed_matrix`, - `printer.bed_mesh.mesh_matrix`: Information on the currently active - bed_mesh. -- `printer.hall_filament_width_sensor.is_active`: Returns True if the - sensor is currently active. -- `printer.hall_filament_width_sensor.Diameter`, - `printer.hall_filament_width_sensor.Raw`: The last read values from - the sensor. -- `printer.mcu.mcu_version`: The Klipper code version reported by the - micro-controller. -- `printer.mcu.mcu_build_versions`: Information on the build tools - used to generate the micro-controller code (as reported by the - micro-controller). -- `printer.mcu.mcu_constants.<constant_name>`: Compile time constants - reported by the micro-controller. The available constants may differ - between micro-controller architectures and with each code revision. -- `printer.mcu.last_stats.<statistics_name>`: Statistics information - on the micro-controller connection. -- `printer.system_stats.sysload`, `printer.system_stats.cputime`, - `printer.system_stats.memavail`: Information on the host operating - system and process load. -- `printer.palette2.ping`: Amount of the last reported Palette 2 ping - in percent. -- `printer.palette2.remaining_load_length`: When starting a Palette 2 - print, this will be the amount of filament to load into the extruder. -- `printer.palette2.is_splicing`: True when the Palette 2 is splicing - filament. - -The above list is subject to change - if using an attribute be sure to -review the [Config Changes document](Config_Changes.md) when upgrading -the Klipper software. The above list is not exhaustive. Other -attributes may be available (via `get_status()` methods defined in the -software). However, undocumented attributes may change without notice -in future Klipper releases. - Note that the Jinja2 `set` directive can assign a local name to an object in the `printer` hierarchy. This can make macros more readable and reduce typing. For example: diff --git a/docs/Overview.md b/docs/Overview.md index a82f372b..21daffe3 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -42,6 +42,8 @@ communication with the Klipper developers. - [Slicers](Slicers.md): Configure "slicer" software for Klipper. - [Command Templates](Command_Templates.md): G-Code macros and conditional evaluation. + - [Status Reference](Status_Reference.md): Information available to + macros (and similar). - [TMC Drivers](TMC_Drivers.md): Using Trinamic stepper motor drivers with Klipper. - [Skew correction](skew_correction.md): Adjustments for axes not diff --git a/docs/Status_Reference.md b/docs/Status_Reference.md new file mode 100644 index 00000000..c09ad0fb --- /dev/null +++ b/docs/Status_Reference.md @@ -0,0 +1,303 @@ +This document is a reference of printer status information that +available in Klipper [macros](Command_Templates.md), [display +fields](Config_Reference.md#display), and via the [API +Server](API_Server.md). + +The fields in this document are subject to change - if using an +attribute be sure to review the [Config Changes +document](Config_Changes.md) when upgrading the Klipper software. + +# bed_mesh + +The following information is available in the +[bed_mesh](Config_Reference.md#bed_mesh) object: +- `profile_name`, `mesh_min`, `mesh_max`, `probed_matrix`, + `mesh_matrix`: Information on the currently active bed_mesh. + +# configfile + +The following information is available in the `configfile` object +(this object is always available): +- `settings.<section>.<option>`: Returns the given config file setting + (or default value) during the last software start or restart. (Any + settings changed at run-time will not be reflected here.) +- `config.<section>.<option>`: Returns the given raw config file + setting as read by Klipper during the last software start or + restart. (Any settings changed at run-time will not be reflected + here.) All values are returned as strings. + +# display_status + +The following information is available in the `display_status` object +(this object is automatically available if a +[display](Config_Reference.md#display) config section is defined): +- `progress`: The progress value of the last `M73` G-Code command (or + `virtual_sdcard.progress` if no recent `M73` received). +- `message`: The message contained in the last `M117` G-Code command. + +# fan + +The following information is available in +[fan](Config_Reference.md#fan), [heater_fan +some_name](Config_Reference.md#heater_fan) and [controller_fan +some_name](Config_Reference.md#controller_fan) objects: +- `speed`: The fan speed as a float between 0.0 and 1.0. +- `rpm`: The measured fan speed in rotations per minute if the fan has + a tachometer_pin defined. + +# filament_switch_sensor + +The following information is available in [filament_switch_sensor +some_name](Config_Reference.md#filament_switch_sensor) objects: +- `enabled`: Returns True if the switch sensor is currently enabled. +- `filament_detected`: Returns True if the sensor is in a triggered + state. + +# firmware_retraction + +The following information is available in the +[firmware_retraction](Config_Reference.md#firmware_retraction) object: +- `retract_length`, `retract_speed`, `unretract_extra_length`, + `unretract_speed`: The current settings for the firmware_retraction + module. These settings may differ from the config file if a + `SET_RETRACTION` command alters them. + +# gcode_macro + +The following information is available in [gcode_macro +some_name](Config_Reference.md#gcode_macro) objects: +- `<variable>`: The current value of a [gcode_macro + variable](Command_Templates.md#variables). + +# gcode_move + +The following information is available in the `gcode_move` object +(this object is always available): +- `gcode_position`: The current position of the toolhead relative to + the current G-Code origin. That is, positions that one might + directly send to a `G1` command. It is possible to access the x, y, + z, and e components of this position (eg, `gcode_position.x`). +- `position`: The last commanded position of the toolhead using the + coordinate system specified in the config file. It is possible to + access the x, y, z, and e components of this position (eg, + `position.x`). +- `homing_origin`: The origin of the gcode coordinate system (relative + to the coordinate system specified in the config file) to use after + a `G28` command. The `SET_GCODE_OFFSET` command can alter this + position. It is possible to access the x, y, and z components of + this position (eg, `homing_origin.x`). +- `speed`: The last speed set in a `G1` command (in mm/s). +- `speed_factor`: The "speed factor override" as set by an `M220` + command. This is a floating point value such that 1.0 means no + override and, for example, 2.0 would double requested speed. +- `extrude_factor`: The "extrude factor override" as set by an `M221` + command. This is a floating point value such that 1.0 means no + override and, for example, 2.0 would double requested extrusions. +- `absolute_coordinates`: This returns True if in `G90` absolute + coordinate mode or False if in `G91` relative mode. +- `absolute_extrude`: This returns True if in `M82` absolute extrude + mode or False if in `M83` relative mode. + +# hall_filament_width_sensor + +The following information is available in the +[hall_filament_width_sensor](Config_Reference.md#hall_filament_width_sensor) +object: +- `is_active`: Returns True if the sensor is currently active. +- `Diameter`, `Raw`: The last read values from the sensor. + +# heater + +The following information is available for heater objects such as +[extruder](Config_Reference.md#extruder), +[heater_bed](Config_Reference.md#heater_bed), and +[heater_generic](Config_Reference.md#heater_generic): +- `temperature`: The last reported temperature (in Celsius as a float) + for the given heater. +- `target`: The current target temperature (in Celsius as a float) for + the given heater. +- `power`: The last setting of the PWM pin (a value between 0.0 and + 1.0) associated with the heater. + +# heaters + +The following information is available in the `heaters` object (this +object is available if any heater is defined): +- `available_heaters`: Returns a list of all currently available + heaters by their full config section names, e.g. `["extruder", + "heater_bed", "heater_generic my_custom_heater"]`. +- `available_sensors`: Returns a list of all currently available + temperature sensors by their full config section names, + e.g. `["extruder", "heater_bed", "heater_generic my_custom_heater", + "temperature_sensor electronics_temp"]`. + +# idle_timeout + +The following information is available in the +[idle_timeout](Config_Reference.md#idle_timeout) object (this object +is always available): +- `state`: The current state of the printer as tracked by the + idle_timeout module. It is one of the following strings: "Idle", + "Printing", "Ready". +- `printing_time`: The amount of time (in seconds) the printer has + been in the "Printing" state (as tracked by the idle_timeout + module). + +# mcu + +The following information is available in +[mcu](Config_Reference.md#mcu) and [mcu +some_name](Config_Reference.md#mcu-my_extra_mcu) objects: +- `mcu_version`: The Klipper code version reported by the + micro-controller. +- `mcu_build_versions`: Information on the build tools used to + generate the micro-controller code (as reported by the + micro-controller). +- `mcu_constants.<constant_name>`: Compile time constants reported by + the micro-controller. The available constants may differ between + micro-controller architectures and with each code revision. +- `last_stats.<statistics_name>`: Statistics information on the + micro-controller connection. + +# output_pin + +The following information is available in [output_pin +some_name](Config_Reference.md#output_pin) objects: +- `value`: The "value" of the pin, as set by a `SET_PIN` command. + +# palette2 + +The following information is available in the +[palette2](Config_Reference.md#palette2) object: +- `ping`: Amount of the last reported Palette 2 ping in percent. +- `remaining_load_length`: When starting a Palette 2 print, this will + be the amount of filament to load into the extruder. +- `is_splicing`: True when the Palette 2 is splicing filament. + +# pause_resume + +The following information is available in the +[pause_resume](Config_Reference.md#pause_resume) object: +- `is_paused`: Returns true if a PAUSE command has been executed + without a corresponding RESUME. + +# print_stats + +The following information is available in the `print_stats` object +(this object is automatically available if a +[virtual_sdcard](Config_Reference.md#virtual_sdcard) config section is +defined): +- `filename`, `total_duration`, `print_duration`, `filament_used`, + `state`, `message`: Estimated information about the current print + when a virtual_sdcard print is active. + +# probe + +The following information is available in the +[probe](Config_Reference.md#probe) object (this object is also +available if a [bltouch](Config_Reference.md#bltouch) config section +is defined): +- `last_query`: Returns True if the probe was reported as "triggered" + during the last QUERY_PROBE command. Note, if this is used in a + macro, due to the order of template expansion, the QUERY_PROBE + command must be run prior to the macro containing this reference. +- `last_z_result`: Returns the Z result value of the last PROBE + command. Note, if this is used in a macro, due to the order of + template expansion, the PROBE (or similar) command must be run prior + to the macro containing this reference. + +# query_endstops + +The following information is available in the `query_endstops` object +(this object is available if any endstop is defined): +- `last_query["<endstop>"]`: Returns True if the given endstop was + reported as "triggered" during the last QUERY_ENDSTOP command. Note, + if this is used in a macro, due to the order of template expansion, + the QUERY_ENDSTOP command must be run prior to the macro containing + this reference. + +# servo + +The following information is available in [servo +some_name](Config_Reference.md#servo) objects: +- `printer["servo <config_name>"].value`: The last setting of the PWM + pin (a value between 0.0 and 1.0) associated with the servo. + +# system_stats + +The following information is available in the `system_stats` object +(this object is always available): +- `sysload`, `cputime`, `memavail`: Information on the host operating + system and process load. + +# temperature sensors + +The following information is available in [bme280 +config_section_name](Config_Reference.md#bmp280bme280bme680-temperature-sensor), +[htu21d config_section_name](Config_Reference.md#htu21d-sensor), [lm75 +config_section_name](Config_Reference.md#lm75-temperature-sensor), and +[temperature_host +config_section_name](Config_Reference.md#host-temperature-sensor) +objects: +- `temperature`: The last read temperature from the sensor. +- `humidity`, `pressure`, `gas`: The last read values from the sensor + (only on bme280, htu21d, and lm75 sensors). + +# temperature_fan + +The following information is available in [temperature_fan +some_name](Config_Reference.md#temperature_fan) objects: +- `temperature`: The last read temperature from the sensor. +- `target`: The target temperature for the fan. + +# temperature_sensor + +The following information is available in [temperature_sensor +some_name](Config_Reference.md#temperature_sensor) objects: +- `temperature`: The last read temperature from the sensor. +- `measured_min_temp`, `measured_max_temp`: The lowest and highest + temperature seen by the sensor since the Klipper host software was + last restarted. + +# toolhead + +The following information is available in the `toolhead` object +(this object is always available): +- `position`: The last commanded position of the toolhead relative to + the coordinate system specified in the config file. It is possible + to access the x, y, z, and e components of this position (eg, + `position.x`). +- `extruder`: The name of the currently active extruder. For example, + in a macro one could use `printer[printer.toolhead.extruder].target` + to get the target temperature of the current extruder. +- `homed_axes`: The current cartesian axes considered to be in a + "homed" state. This is a string containing one or more of "x", "y", + "z". +- `axis_minimum`, `axis_maximum`: The axis travel limits (mm) after + homing. It is possible to access the x, y, z components of this + limit value (eg, `axis_minimum.x`, `axis_maximum.z`). +- `max_velocity`, `max_accel`, `max_accel_to_decel`, + `square_corner_velocity`: The current printing limits that are in + effect. This may differ from the config file settings if a + `SET_VELOCITY_LIMIT` (or `M204`) command alters them at run-time. +- `stalls`: The total number of times (since the last restart) that + the printer had to be paused because the toolhead moved faster than + moves could be read from the G-Code input. + +# virtual_sdcard + +The following information is available in the +[virtual_sdcard](Config_Reference.md#virtual_sdcard) object: +- `is_active`: Returns True if a print from file is currently active. +- `progress`: An estimate of the current print progress (based of file + size and file position). +- `file_position`: The current position (in bytes) of an active print. + +# webhooks + +The following information is available in the `webhooks` object (this +object is always available): +- `state`: Returns a string indicating the current Klipper + state. Possible values are: "ready", "startup", "shutdown", "error". +- `state_message`: A human readable string giving additional context + on the current Klipper state. |