Mirror
/
klipper-dgus
mirror of https://github.com/Desuuuu/klipper.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Move status field reference to new Status_Reference.md file 

Move the reference of "printer" status fields from
Command_Templates.md to a new Status_Reference.md file.

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>
This commit is contained in:
Kevin O'Connor 2021-04-28 20:16:13 -04:00
parent 3b33d6652f
commit af7f27542f
4 changed files with 310 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/API_Server.md
View File

@ -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

208
docs/Command_Templates.md
View File

@ -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:

2
docs/Overview.md
View File

@ -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

303
docs/Status_Reference.md Normal file
View File

@ -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.