moonraker/docs/printer_objects.md

As mentioned in the API documentation, it is possible to query or subscribe 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 retrieve a list of available printer objects via the list objects endpoint. 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 retrieving 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

{
  "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

{
    "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_coordinates: 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

{
    "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

{
    "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.

{
    "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

{
    "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

{
    "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

{
   "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

{
    "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

{
    "filename": "",
    "total_duration": 0.0,
    "print_duration": 0.0,
    "filament_used": 0.0,
    "state": "standby",
    "message": "",
    "info": {
        "total_layer": null,
        "current_layer": null
    }
}

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 one of the following values:
  • "standby"
  • "printing"
  • "paused"
  • "complete"
  • "cancelled"
  • "error" - Note that 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.
• info: This is a dict containing information about the print provided by the slicer. Currently this is limited to the total_layer and current_layer values. Note that these values are set by the SET_PRINT_STATS_INFO gcode command. It is necessary to configure the slicer to include this command in the print. SET_PRINT_STATS_INFO TOTAL_LAYER=total_layer_count should be called in the slicer's "start gcode" to initalize the total layer count. SET_PRINT_STATS_INFO CURRENT_LAYER=current_layer should be called in the slicer's "on layer change" gcode. The user must substitute the total_layer_count and current_layer with the appropriate "placeholder syntax" for the slicer.

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

{
    "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.

{
    "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.

{
    "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.

{
    "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.

{
    "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.

{
    "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 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.