CreatBotMoonraker/docs/external_api/printer.md

Printer Administration

These endpoints provide access to printer state and printer control. Klippy must be connected to Moonraker to receive a successful response, and in many cases Klippy must be in the ready state.

Most of these endpoints are registered with Moonraker by Klipper. Requests pass from the frontend through Moonraker directly to Klipper. Moonraker does not intervene.

Get Klippy host information

GET /printer/info

{
    "jsonrpc": "2.0",
    "method": "printer.info",
    "id": 5445
}

//// collapse-code

{
    "state": "ready",
    "state_message": "Printer is ready",
    "hostname": "pi-debugger",
    "klipper_path": "/home/pi/klipper",
    "python_path": "/home/pi/klipper/venv/bin/python",
    "process_id": 275124,
    "user_id": 1000,
    "group_id": 1000,
    "log_file": "/home/pi/printer_data/logs/klippy.log",
    "config_file": "/home/pi/printer_data/config/printer.cfg",
    "software_version": "v0.12.0-85-gd785b396",
    "cpu_info": "4 core ?"
}

////

/// api-response-spec open: True

Field	Type	Description
state	string	Klippy's current state.
state_message	string	A message describing Klippy's current state.
hostname	string	Hostname of the machine running Klippy.
klipper_path	string	Path on disk to the Klipper application.
python_path	string	Path on disk to the Python executable running Klippy.
process_id	int	The PID of the current Klippy process.
user_id	int	The UID of the user the Klippy process belongs to.
group_id	int	The GID of the group the Klippy process belongs to.
log_file	string	Path on disk to Klipper's log file.
configfile	string	Path on disk to Klipper's configuration file.
software_version	string	Version of the currently running instance of Klipper.
cpu_info	string	A brief description of the host machine's CPU.

State	Description
ready	Klippy has initialized and is ready for commands.
startup	Klippy is currently in its startup phase.
error	Klippy encountered an error during startup.
shutdown	Klippy is in the shutdown state. This can be initiated
	by the user via an emergency stop, or by the software
	if it encounters a critical error during operation.
{ #klippy-state-desc } Klippy State
///

Emergency Stop

POST /printer/emergency_stop

{
    "jsonrpc": "2.0",
    "method": "printer.emergency_stop",
    "id": 4564
}

/// Note This endpoint will immediately halt the printer and put it in a "shutdown" state. It should be used to implement an "emergency stop" button and also used if a user enters M112(emergency stop) via a console. ///

"ok"

Host Restart

Requests a Klipper "soft" restart. This will reload the Klippy application and configuration. Connected MCUs will not be reset.

POST /printer/restart

{
    "jsonrpc": "2.0",
    "method": "printer.restart",
    "id": 4894
}

"ok"

Firmware Restart

Requests a complete Klipper restart. Both the Klippy Application and connected MCUs will be reset.

POST /printer/firmware_restart

{
    "jsonrpc": "2.0",
    "method": "printer.firmware_restart",
    "id": 8463
}

"ok"

Printer Status Requests

List loaded printer objects

Returns a list of Klipper printer objects that are currently loaded. This can be used to determine if a specific object is available for query and/or subscription.

GET /printer/objects/list

{
    "jsonrpc": "2.0",
    "method": "printer.objects.list",
    "id": 1454
}

//// collapse-code

{
    "objects": [
        "gcode",
        "webhooks",
        "configfile",
        "mcu",
        "mcu linux",
        "heaters",
        "bme280 chamber",
        "temperature_sensor chamber",
        "filament_switch_sensor extruder_sensor",
        "output_pin sensor_toggle",
        "gcode_move",
        "bed_mesh",
        "exclude_object",
        "temperature_host RPi",
        "temperature_sensor RPi",
        "gcode_macro TURN_OFF_MOTORS",
        "gcode_macro SET_HOMING_CURRENT",
        "temperature_sensor ambient",
        "gcode_macro query_bme280",
        "pause_resume",
        "print_stats",
        "virtual_sdcard",
        "probe",
        "stepper_enable",
        "tmc2130 stepper_x",
        "tmc2130 stepper_y",
        "tmc2130 stepper_z",
        "tmc2130 extruder",
        "heater_bed",
        "heater_fan nozzle_cooling_fan",
        "fan",
        "menu",
        "display_status",
        "output_pin BEEPER_pin",
        "idle_timeout",
        "motion_report",
        "query_endstops",
        "system_stats",
        "manual_probe",
        "toolhead",
        "extruder"
    ]
}

////

/// api-response-spec open: True

Field	Type	Description
objects	[string]	A list Klipper printer objects currently loaded.
///

Query printer object status

Requests the status of a provided set of printer objects.

/// Tip See the Printer Objects document for details on the objects available for query. ///

POST /printer/objects/query
Content-Type: application/json

{
    "objects": {
        "gcode_move": null,
        "toolhead": ["position", "status"]
    }
}

/// details | Using the Query String The HTTP Request may also be performed using the query string. It is recommended to send the request in the body unless otherwise not possible.

GET /printer/objects/query?gcode_move&toolhead&extruder=target,temperature

The above will request a status update for all gcode_move and toolhead attributes. Only the temperature and target attributes are requested for the extruder. ///

{
    "jsonrpc": "2.0",
    "method": "printer.objects.query",
    "params": {
        "objects": {
            "gcode_move": null,
            "toolhead": ["position", "status"]
        }
    },
    "id": 4654
}

/// api-parameters open: True

Name	Type	Default	Description
objects	object	REQUIRED	An object whose key, value pairs represent one or
			more Printer Object Requests.

Key Description	Value Description
The keyshould be an available	The value specifies the attributes of the object that
Klipper printer object.	should be returned. If the value is null all attributes
{ width=40% }	will be returned. Alternatively a list of strings
	specifying the desired attributes can be provided.
{ #printer-obj-req-desc } Printer Object Request

//// Note If a requested printer object or attribute does not exist then the result will be omitted from the response. No error is returned. ////

///

//// collapse-code

{
    "eventtime": 578243.57824499,
    "status": {
        "gcode_move": {
            "absolute_coordinates": true,
            "absolute_extrude": true,
            "extrude_factor": 1,
            "gcode_position": [0, 0, 0, 0],
            "homing_origin": [0, 0, 0, 0],
            "position": [0, 0, 0, 0],
            "speed": 1500,
            "speed_factor": 1
        },
        "toolhead": {
            "position": [0, 0, 0, 0],
            "status": "Ready"
        }
    }
}

////

/// api-response-spec open: True

Field	Type	Description
eventtime	float	The time at which the status was received, according Klipper's
		monotonic clock.
status	object	An object containing the current state of the requested
		printer objects.
{ #object-query-response-spec }
///

Subscribe to printer object status updates

Requests status updates for a set of printer objects. A persistent connection (Websocket or Unix Socket) is required to fulfill this request.

Status updates for subscribed objects are sent asynchronously over the connection. See the notify_status_update notification for details.

/// Tip See the Printer Objects document for details on the objects available for subscription. ///

Not available

{
    "jsonrpc": "2.0",
    "method": "printer.objects.subscribe",
    "params": {
        "objects": {
            "gcode_move": null,
            "toolhead": ["position", "status"]
        }
    },
    "id": 5434
}

/// api-parameters open: True Parameters are identical to the query status parameters. A new request will override a previous request. If objects is set to an empty object then the subscription will be cancelled. ///

//// collapse-code

{
    "eventtime": 578243.57824499,
    "status": {
        "gcode_move": {
            "absolute_coordinates": true,
            "absolute_extrude": true,
            "extrude_factor": 1,
            "gcode_position": [0, 0, 0, 0],
            "homing_origin": [0, 0, 0, 0],
            "position": [0, 0, 0, 0],
            "speed": 1500,
            "speed_factor": 1,
        },
        "toolhead": {
            "position": [0, 0, 0, 0],
            "status": "Ready"
        }
    }
}

////

/// api-response-spec open: True The response spec is identical to the query response specification The response may be used to initialize local state without performing a separate query. ///

Query Endstops

GET /printer/query_endstops/status

{
    "jsonrpc": "2.0",
    "method": "printer.query_endstops.status",
    "id": 3456
}

//// collapse-code

{
    "x": "TRIGGERED",
    "y": "open",
    "z": "open"
}

////

/// api-response-spec open: True

Field	Type	Description
variable	string	The field is the name of the registered endstop. The value
		will be open or TRIGGERED.
///

GCode APIs

Run a gcode command

Executes a gcode command. Multiple commands may be executed by separating them with a newline (\n). The request returns when the command or series of commands have completed, or when the command results in an error.

/// warning When M112(emergency stop) is requested via this endpoint it will not immediately stop the printer. M112 will be placed on the gcode queue and executed after all previous gcodes are complete. If a frontend detects M112 via user input (such as a console) it should request the /printer/emergency_stop endpoint to immediately halt the printer. This may be done in addition to sending the M112 gcode if desired. ///

POST /printer/gcode/script
Content-Type: application/json

{
    "script": "G28"
}

{
    "jsonrpc": "2.0",
    "method": "printer.gcode.script",
    "params": {
        "script": "G28"
    },
    "id": 7466}

/// api-parameters open: True

Name	Type	Default	Description
script	string	REQUIRED	A GCode Command to run. Multiple commands may be
			specified, separated by a newline (\n).
///

"ok"

Get GCode Help

Retrieves a list of registered GCode Command Descriptions. Not all registered GCode commands have a description, so this list should not be treated as an exhaustive list of all supported commands.

GET /printer/gcode/help

{
    "jsonrpc": "2.0",
    "method": "printer.gcode.help",
    "id": 4645
}

//// collapse-code

{
    "RESTART": "Reload config file and restart host software",
    "FIRMWARE_RESTART": "Restart firmware, host, and reload config",
    "STATUS": "Report the printer status",
    "HELP": "Report the list of available extended G-Code commands",
    "SAVE_CONFIG": "Overwrite config file and restart",
    "SHUTDOWN_MACHINE": "G-Code macro",
    "SET_GCODE_VARIABLE": "Set the value of a G-Code macro variable",
    "REBOOT_MACHINE": "G-Code macro",
    "UPDATE_DELAYED_GCODE": "Update the duration of a delayed_gcode",
    "TURN_OFF_HEATERS": "Turn off all heaters",
    "TEMPERATURE_WAIT": "Wait for a temperature on a sensor",
    "QUERY_ADC": "Report the last value of an analog pin",
    "QUERY_FILAMENT_SENSOR": "Query the status of the Filament Sensor",
    "SET_FILAMENT_SENSOR": "Sets the filament sensor on/off",
    "SET_PIN": "Set the value of an output pin",
    "BED_MESH_CALIBRATE": "Perform Mesh Bed Leveling",
    "BED_MESH_PROFILE": "Bed Mesh Persistent Storage management",
    "BED_MESH_OUTPUT": "Retrieve interpolated grid of probed z-points",
    "BED_MESH_MAP": "Serialize mesh and output to terminal",
    "BED_MESH_CLEAR": "Clear the Mesh so no z-adjustment is made",
    "BED_MESH_OFFSET": "Add X/Y offsets to the mesh lookup",
    "SET_GCODE_OFFSET": "Set a virtual offset to g-code positions",
    "SAVE_GCODE_STATE": "Save G-Code coordinate state",
    "RESTORE_GCODE_STATE": "Restore a previously saved G-Code state",
    "GET_POSITION": "Return information on the current location of the toolhead",
    "EXCLUDE_OBJECT_START": "Marks the beginning the current object as labeled",
    "EXCLUDE_OBJECT_END": "Marks the end the current object",
    "EXCLUDE_OBJECT": "Cancel moves inside a specified objects",
    "EXCLUDE_OBJECT_DEFINE": "Provides a summary of an object",
    "TURN_OFF_MOTORS": "G-Code macro",
    "CLEAR_PAUSE": "Clears the current paused state without resuming the print",
    "SET_PRINT_STATS_INFO": "Pass slicer info like layer act and total to klipper",
    "SDCARD_RESET_FILE": "Clears a loaded SD File. Stops the print if necessary",
    "SDCARD_PRINT_FILE": "Loads a SD file and starts the print.  May include files in subdirectories.",
    "RESPOND": "Echo the message prepended with a prefix",
    "PROBE": "Probe Z-height at current XY position",
    "QUERY_PROBE": "Return the status of the z-probe",
    "PROBE_CALIBRATE": "Calibrate the probe's z_offset",
    "PROBE_ACCURACY": "Probe Z-height accuracy at current XY position",
    "Z_OFFSET_APPLY_PROBE": "Adjust the probe's z_offset",
    "GET_CURRENT_SKEW": "Report current printer skew",
    "CALC_MEASURED_SKEW": "Calculate skew from measured print",
    "SET_SKEW": "Set skew based on lengths of measured object",
    "SKEW_PROFILE": "Profile management for skew_correction",
    "SET_STEPPER_ENABLE": "Enable/disable individual stepper by name",
    "SET_TMC_FIELD": "Set a register field of a TMC driver",
    "INIT_TMC": "Initialize TMC stepper driver registers",
    "SET_TMC_CURRENT": "Set the current of a TMC driver",
    "DUMP_TMC": "Read and display TMC stepper driver registers",
    "PID_CALIBRATE": "Run PID calibration test",
    "SET_HEATER_TEMPERATURE": "Sets a heater temperature",
    "SET_DISPLAY_TEXT": "Set or clear the display message",
    "SET_DISPLAY_GROUP": "Set the active display group",
    "STEPPER_BUZZ": "Oscillate a given stepper to help id it",
    "FORCE_MOVE": "Manually move a stepper; invalidates kinematics",
    "SET_KINEMATIC_POSITION": "Force a low-level kinematic position",
    "SET_IDLE_TIMEOUT": "Set the idle timeout in seconds",
    "QUERY_ENDSTOPS": "Report on the status of each endstop",
    "SET_VELOCITY_LIMIT": "Set printer velocity limits",
    "MANUAL_PROBE": "Start manual probe helper script",
    "TUNING_TOWER": "Tool to adjust a parameter at each Z height",
    "SET_PRESSURE_ADVANCE": "Set pressure advance parameters",
    "SET_EXTRUDER_ROTATION_DISTANCE": "Set extruder rotation distance",
    "SYNC_EXTRUDER_MOTION": "Set extruder stepper motion queue",
    "SET_EXTRUDER_STEP_DISTANCE": "Set extruder step distance",
    "SYNC_STEPPER_TO_EXTRUDER": "Set extruder stepper",
    "ACTIVATE_EXTRUDER": "Change the active extruder",
    "BASE_PAUSE": "Renamed builtin of 'PAUSE'",
    "BASE_RESUME": "Renamed builtin of 'RESUME'",
    "BASE_CANCEL_PRINT": "Renamed builtin of 'CANCEL_PRINT'",
    "ACCEPT": "Accept the current Z position",
    "ABORT": "Abort manual Z probing tool",
    "TESTZ": "Move to new Z height"
}

////

/// api-response-spec open: True

Field	Type	Description
variable	string	The field is the name of the registered gcode command. The value
		is a string containing the associated help descriptions.

//// Note As mentioned previously, this list is not exhaustive. Help strings are not available for default gcode handlers such as G1, G28, etc, nor are they available for extended handlers that failed to register a description in Klipper's python source. ////

///

Print Job Management

Start a print job

POST /printer/print/start?filename=test_print.gcode

{
    "jsonrpc": "2.0",
    "method": "printer.print.start",
    "params": {
        "filename": "test_print.gcode"
    },
    "id": 4654
}

/// api-parameters open: true

Name	Type	Default	Description
filename	string	REQUIRED	The name of the gcode file to print. May be a path
			relative to the gcode folder.
///

"ok"

Pause a print job

POST /printer/print/pause

{
    "jsonrpc": "2.0",
    "method": "printer.print.pause",
    "id": 4564
}

"ok"

Resume a print job

POST /printer/print/resume

{
    "jsonrpc": "2.0",
    "method": "printer.print.resume",
    "id": 1465
}

"ok"

Cancel a print job

POST /printer/print/cancel

{
    "jsonrpc": "2.0",
    "method": "printer.print.cancel",
    "id": 2578
}

"ok"