moonraker/docs/printer_objects.md

#
As mentioned in the API documentation, it is possible to
[query](web_api.md#query-printer-object-status) or
[subscribe](web_api.md#subscribe-to-printer-object-status)
to "Klipper Printer Objects."  There are numerous printer objects in
Klipper, many of which are optional and only report status if they are
enabled by Klipper's configuration.  Client's may retreive a list of
available printer objects via the
[list objects endpoint](web_api.md#list-available-printer-objects).  This
should be done after Klipper reports its state as "ready".

This section will provide an overview of the most useful printer objects.
If a developer is interested in retreiving state for an object not listed here,
look in Klipper's source code for module you wish to query.  If the module
contains a "get_status()" method, its return value will contain a dictionary
that reports state which can be queried.

## webhooks
```json
{
  "state": "startup",
  "state_message": "message"
}
```
The `webhooks` object contains the current printer state and the current
state message.  These fields match those returned via the `/printer/info`
endpoint.  This is provided as a convience, clients may subscribe to `webhooks`
so they are asynchonously notified of a change to printer state.  The `state`
may be `startup`, `ready`, `shutdown`, or `error`.  The `state_message`
contains a message specific to the current printers state.

## gcode_move
```json
{
    "speed_factor": 1.0,
    "speed": 100.0,
    "extrude_factor": 1.0,
    "absolute_coordinates": true,
    "absolute_extrude": false,
    "homing_origin": [0.0, 0.0, 0.0, 0.0],
    "position": [0.0, 0.0, 0.0, 0.0],
    "gcode_position": [0.0, 0.0, 0.0, 0.0]
}
```
The `gcode_move` object reports the current gcode state:

- `speed_factor`: AKA "feedrate", this is the current speed multiplier
- `speed`: The current gcode speed in mm/s.
- `extrude_factor`: AKA "extrusion multiplier".
- `absolute_coorinates`: true if the machine axes are moved using
  absolute coordinates, false if using relative coordinates.
- `absolute_extrude`: true if the extruder is moved using absolute
  coordinates, false if using relative coordinates.
- `homing_origin`: [X, Y, Z, E] - returns the "gcode offset" applied to
  each axis.  For example, the "Z" axis can be checked to determine how
  much offset has been applied via "babystepping".
- `position`: [X, Y, Z, E] - The internal gcode position, including
   any offsets (gcode_offset, G92, etc) added to an axis.
- `gcode_position`: [X, Y, Z, E] - The current gcode position
  sans any offsets applied.  For X, Y, and Z, this should match
  the most recent "G1" or "G0" processed assuming the machine is
  using absolute coordinates.

!!! Note
    The printer's actual movement will lag behind the reported positional
    coordinates due to lookahead.

## toolhead
```json
{
    "homed_axes": "xyz",
    "print_time": 0.0,
    "estimated_print_time": 0.0,
    "extruder": "extruder",
    "position": [0.0, 0.0, 0.0, 0.0],
    "max_velocity": 500.0,
    "max_accel": 3000.0,
    "max_accel_to_decel": 1500.0,
    "square_corner_velocity": 5.0
}
```
The `toolhead` object reports state of the current tool:

- `homed_axes`: a string containing the axes that are homed. If no axes
  are homed, returns a null string.
- `print_time`: internal value, not generally useful for clients
- `estimated_print_time`: internal value, not generally useful for clients.
- `extruder`: the name of the currently selected extruder, ie "extruder"
  or "extruder1".
- `position`: [X, Y, Z, E] - This the the last position toward which the tool
  was commanded to move.  It includes any offsets applied via gcode as well
  as any transforms made by modules such as "bed_mesh", "bed_tilt", or
  "skew_correction".
- `max_velocity`: The currently set maximum velocity of the tool (mm/s^2).
- `max_accel`:  The currently set maximum acceleration of the tool (mm/s^2).
- `max_accel_to_decel`:  The currently set maximum accel to decel of the tool.
  This value is the maximum rate at which the tool can transition from
  acceleration to deceleration (mm/s^2).
- `square_corner_velocity`: The currently set square corner velocity.  This
  is the maximum velocity at which the tool may travel a 90 degree corner.

!!! tip
    `max_velocity`, `max_accel`, `max_accel_to_decel`, and
    `square_corner_velocity` can be changed by the `SET_VELOCITY_LIMIT` gcode.
    `M204` can also change `max_accel`.

## configfile
```json
{
    "config": {},
    "settings": {},
    "save_config_pending": false
}
```
The `configfile` object reports printer configuration state:

- `config`:  This is an object containing the configuration as read from
  printer.cfg.  Each config section will be an object containing the
  configured options.  Values will ALWAYS be reported as
  strings.  Note that default values are not reported, only options
  configured in printer.cfg are present.
- `settings`:  Similar to `config`, however this object includes default
  values that may not have been included in `printer.cfg`.  It is possible
  for a value to be a string, integer, boolean, or float.
- `save_config_pending`: True if the printer has taken an action which
  has updated the internal configuration (ie: PID calibration, probe
  calibration, bed mesh calibration).  This allows clients to present
  the user with the option to execute a SAVE_CONFIG gcode which will
  save the configuration to printer.cfg and restart the Klippy Host.

## extruder
*Enabled when `[extruder]` is included in printer.cfg*
!!! note
    If multiple extruders are configured, extruder 0 is available as
    `extruder`, extruder 1 as `extruder1` and so on.
```json
{
    "temperature": 0.0,
    "target": 0.0,
    "power": 0.0,
    "pressure_advance": 0.0,
    "smooth_time": 0.0
}
```
The `extruder` object reports state of an extruder:

- `temperature`:  The extruder's current temperature (in C).
- `target`:  The extruder's target temperature (in C).
- `power`: The current pwm value applied to the heater.  This value is
  expressed as a percentage from 0.0 to 1.0.
- `pressure_advance`:  The extruder's current pressure advance value.
- `smooth_time`:  The currently set time range to use when calculating the
  average extruder velocity for pressure advance.

## heater_bed
*Enabled when `[heater_bed]` is included in printer.cfg*
```json
{
    "temperature": 0.0,
    "target": 0.0,
    "power": 0.0,
}
```
The `heater_bed` object reports state of the heated bed:

- `temperature`:  The bed's current temperature
- `target`:  The bed's target temperature
- `power`: The current pwm value applied to the heater.  This value is
  expressed as a percentage from 0.0 to 1.0.

## fan
*Enabled when `[fan]` is included in printer.cfg*
```json
{
    "speed": 0.0,
    "rpm": 4000
}
```
The `fan` object returns state of the part cooling fan:

- `speed`:  The current fan speed.  This is reported as a
  percentage of maximum speed in the range of 0.0 - 1.0.
- `rpm`:  The fan's revolutions per minute if the tachometer
  pin has been configured.  Will report `null` if no tach
  has been configured.

## idle_timeout
```json
{
   "state": "Idle",
   "printing_time": 0.0
}
```

The `idle_timeout` object reports the idle state of the printer:

- `state`: Can be `Idle`, `Ready`, or `Printing`.  The printer will
  transition to the `Printing` state whenever a gcode is issued that
  commands the tool, this includes manual commands.  Thus this should
  not be used to determine if a gcode file print is in progress.  It can
  however be used to determine if the printer is busy.
- `printing_time`:  The amount of time the printer has been in the
  `Printing` state.  This is reset to 0 whenever the printer transitions
  from `Printing` to `Ready`.

## virtual_sdcard
*Enabled when `[virtual_sdcard]` is included in printer.cfg*
```json
{
    "progress": 0.0,
    "is_active": false,
    "file_position": 0
}
```
The `virtual_sdcard` object reports the state of the virtual sdcard:

- `progress`: The print progress reported as a percentage of the file
  read, in the range of 0.0 - 1.0.
- `is_active`: Returns true if the virtual sdcard is currently processing
  a file.  Note that this will return false if a virtual sdcard print is
  paused.
- `file_position`:  The current file position in bytes.  This will always
  be an integer value

!!! Note
    `progress` and `file_position` will persist after a print has
    paused, completed, or errored.  They are cleared when the user issues
    a SDCARD_RESET_FILE gcode or when a new print has started.

## print_stats
*Enabled when `[virtual_sdcard]` is included in printer.cfg*
```json
{
    "filename": "",
    "total_duration": 0.0,
    "print_duration": 0.0,
    "filament_used": 0.0,
    "state": "standby",
    "message": ""
}
```
The `print_stats` object reports `virtual_sdcard` print state:

- `filename`:  The name of the current file loaded.  This will be a null
  string if no file is loaded.  Note that name is a path relative to the
  gcode folder, thus if the file is located in a subdirectory it would
  be reported as "my_sub_dir/myprint.gcode".
- `total_duration`:  The total time (in seconds) elapsed since a print
  has started. This includes time spent paused.
- `print_duration`:  The total time spent printing (in seconds).  This is
  equivalent to `total_duration` - time paused.
- `filament_used`:  The amount of filament used during the current print
  (in mm).  Any extrusion during a pause is excluded.
- `state`: Current print state.  Can be "standby", "printing", "paused",
  "complete", or "error".  If an error is detected the print will abort.
- `message`:  If an error is detected, this field contains the error
  message generated.  Otherwise it will be a null string.

!!! Note
    After a print has started all of the values above will persist until
    the user issues a SDCARD_RESET_FILE gcode or when a new print has started.

## display_status
*Enabled when `[display]` or `[display_status]` is included in printer.cfg*
```json
{
    "message": "",
    "progress": 0.0
}
```
The `display_status` object contains state typically used to update displays:

- `message`:  The message set by a M117 gcode.  If no message is set this will
  be a null string.
- `progress`:  The percentage of print progress, as reported by M73.  This
  will be in the range of 0.0 - 1.0.  If no M73 has been issued this value
  will fallback to the eqivalent of `virtual_sdcard.progress`.  Note that
  progress updated via M73 has a timeout.  If no M73 is received after 5
  seconds, `progress` will be set to the fallback value.

## temperature_sensor sensor_name
*Enabled when `[temperature_sensor sensor_name]` is included in printer.cfg.
It is possible for multiple temperature sensors to be configured.*
```json
{
    "temperature": 0.0,
    "measured_min_temp": 0.0,
    "measured_max_temp": 0.0
}
```
A `temperature_sensor` reports the following state:

- `temperature`:  Sensor's current reported temperature
- `measured_min_temp`: The mimimum temperature read from the sensor
- `measured_max_temp`: The maximum temperature read from the sensor

## temperature_fan fan_name
*Enabled when `[temperature_fan fan_name]` is included in printer.cfg.  It is
possible for multiple temperature fans to be configured.*
```json
{
    "speed": 0.0,
    "temperature": 0.0,
    "target": 0.0
}
```
A `temperature_fan` reports the following state:

- `speed`:  Current fan speed as a percentage of maximum speed, reported
  in the range of 0.0 - 1.0
- `temperature`:  Currently reported temperature of the sensor associated
  with the fan
- `target`:  The current target temperature for the `temperature_fan`.

## filament_switch_sensor sensor_name
*Enabled when `[filament_switch_sensor sensor_name]` is included in
printer.cfg.  It is possible for multiple filament sensors to be configured.*
```json
{
    "filament_detected": false,
    "enabled": true
}
```
A `filament_switch_sensor` reports the following state:

- `filament_detected`:  Set to true if the switch detects filament, otherwise
  false
- `enabled`: Set to true if the sensor is currently enabled, otherwise false

## output_pin pin_name
*Enabled when `[output_pin pin_name]` is included in printer.cfg.
It is possible for multiple output pins to be configured.*
```json
{
    "value": 0.0
}
```
An `output_pin` reports the following state:

- `value`: The currently set value of the pin, in the range of 0.0 - 1.0.
  A digital pin will always be 0 or 1, whereas a pwm pin may report a value
  across the entire range.

## bed_mesh
*Enabled when `[bed_mesh]` is included in printer.cfg.*
```json
{
    "profile_name": "",
    "mesh_min": [0.0, 0.0],
    "mesh_max": [0.0, 0.0],
    "probed_matrix": [[]],
    "mesh_matrix": [[]]
}
```
The `bed_mesh` printer object reports the following state:

- `profile_name`:  The name of the currently loaded profile.  If no profile is
  loaded then this will report a null string.  If the user is not using
  bed_mesh profile management then this will report `default` after mesh
  calibration completes.
- `mesh_min`: [X, Y] - The minimum x and y coordinates of the mesh.
- `mesh_max`: [X, Y] - The maximum x and y coordinates of the mesh.
- `probed_matrix`:  A 2 dimensional array representing the matrix of probed
  values. If the matrix has not been probed the the result is `[[]]`.
- `mesh_matrix`: A 2 dimension array representing the interpolated mesh.  If
  no matrix has been generated the result is `[[]]`.

!!! tip
    See [web_api.md](web_api.md##bed-mesh-coordinates) for an example
    of how to use this information to generate (X,Y,Z) coordinates.

## gcode_macro macro_name
*Enabled when `[gcode_macro macro_name]` is included in printer.cfg.
It is possible for multiple gcode macros to be configured.*

Gcode macros will report the state of configured `variables`.
While user defined macros likely won't report state that is useful
for a client, it is possible for client developers to recommend or
request a specific gcode_macro configuration, then have the client
take action based on the variables reported by the macro.