Skip to content

Nozzles

4 tools, defined in tools/nozzle.py.

Tool Title Access
get_nozzle_info Get Nozzle Info read-only
refresh_nozzles Refresh Nozzle Info write
set_nozzle_config Set Nozzle Config write
swap_tool Swap Active Extruder write

get_nozzle_info

Get Nozzle Info · read-only

Return nozzle diameter, type, and flow type for all extruders on the printer.

WHEN to use: check which nozzle hardware the MCP state believes is installed on each extruder, together with the active tray and tray state, before printing or before calling set_nozzle_config.

Sibling disambiguation: get_nozzle_info only reads the cached printer state. refresh_nozzles sends a command asking the printer to push back its current nozzle state, so call that first after physically swapping a nozzle; get_climate returns nozzle temperatures, not nozzle hardware.

Parameters

  • name (string, required): Printer name as returned by get_configured_printers.

Returns

{"nozzles": [{extruder_id, diameter_mm, nozzle_type, flow_type, encoded_id, active_tray_id, tray_state}]} on success, or {"error": "Printer '<name>' not connected"} when the printer has no session. Single-extruder printers return one entry; dual-extruder H2D printers return two. Each entry carries the normalized NozzleCharacteristics plus the active tray and tray state for that extruder.

Notes

Field semantics:

  • extruder_id: -1 on single-extruder printers; 0 = RIGHT nozzle (primary) and 1 = LEFT nozzle on H2D. A single-extruder entry with extruder_id 0 appears only before any telemetry has arrived. Do NOT pass a reported -1 to set_nozzle_config's extruder parameter: there it means "apply to all nozzles".
  • diameter_mm: float (e.g. 0.4).
  • nozzle_type: NozzleType enum name (e.g. 'HARDENED_STEEL', 'STAINLESS_STEEL', 'BRASS', 'TUNGSTEN_CARBIDE', 'E3D', 'UNKNOWN').
  • flow_type: NozzleFlowType enum name (e.g. 'STANDARD', 'HIGH_FLOW', 'TPU_HIGH_FLOW', 'UNKNOWN'). Single-extruder printers always report 'STANDARD' (fixed by bpm).
  • active_tray_id: the tray currently selected for that extruder, and what it counts differs by printer. Single-extruder printer: the printer's raw tray_now value, an absolute tray id (AMS unit n slot s reads 4n+s, so it can exceed 3). Dual-extruder printer: the slot INSIDE the unit assigned to that extruder (the low byte of the extruder's report: the AMS HT's slot 0 reads 0, not 128), which is not an absolute id. That unit is the one bpm has assigned to the extruder; for the active extruder it is the printer state's active_ams_id, and this tool does not return it. Either way 254 = the external spool holder (the only one on a single-nozzle printer, the LEFT holder on a dual-nozzle one), 255 = the RIGHT holder (dual-nozzle only), and -1 = no tray active.
  • tray_state: TrayState enum name: 'LOADED', 'UNLOADED', 'LOADING', 'UNLOADING'. It is DERIVED by bpm, not a measurement of filament in the hotend. Single-extruder: LOADING/UNLOADING come from the job stage, LOADED means an AMS tray is selected, and UNLOADED means none is selected or the external spool holder is in use, so a print from the external spool reports UNLOADED. Dual-extruder: derived from that extruder's reported filament state and status.
  • encoded_id is the raw nozzle identifier string from telemetry (may be a bare value such as "0") and is not used by any other tool.
  • When the printer has reported no nozzle data, diameter_mm is 0.0, nozzle_type and flow_type are "UNKNOWN" and encoded_id is "".

refresh_nozzles

Refresh Nozzle Info · write · needs user_permission=True

Ask the printer to push back its current nozzle state.

WHEN to use: after physically swapping a nozzle on an H2D or any other dual-extruder printer, to request that the printer report the nozzle now installed.

WRITE GUARD: publishes a REFRESH_NOZZLE command to the printer's request topic, asking the printer to push back its current nozzle state, which updates get_nozzle_info() once reported. The tool itself performs no active-print check. With user_permission False the tool changes nothing and returns the refusal string "Error: user_permission must be True to perform this action." followed by a sentence naming this consequence.

Sibling disambiguation: refresh_nozzles asks the printer to push back its current nozzle state; get_nozzle_info only reads the state already held by the MCP server. trigger_printer_refresh (string return) and force_state_refresh (dict return) are both guarded and re-request the printer's full state rather than nozzle state specifically.

Parameters

  • name (string, required): Printer name as returned by get_configured_printers.
  • user_permission (boolean, default false): Must be True to send the refresh command. Default False.

Returns

A plain string, never a dict. Success: "Nozzle refresh command sent to '<name>'." Errors, all strings: the "Error: user_permission must be True ..." refusal; "Error: Printer '<name>' not connected."; "Error refreshing nozzles on '<name>': <exception>".

Notes

Whether the firmware re-detects nozzle hardware is not established by this code. The command is published without checking the MQTT session state, but a paused session has unsubscribed from the report topic, so then the command is sent and get_nozzle_info() does not change. The success string means the command was published.

set_nozzle_config

Set Nozzle Config · write · needs user_permission=True

Inform the printer of the currently installed nozzle diameter and material type.

WHEN to use: after physically installing a different nozzle, to tell the printer its diameter, material and flow type so the firmware applies the correct temperature limits, flow rates and material compatibility checks.

WRITE GUARD: sends the nozzle configuration to the printer over MQTT (SET_ACCESSORIES on single-extruder printers, SET_NOZZLE on dual-extruder printers) and, when the target extruder differs from the cached active tool, first switches the active extruder with set_active_tool(), so the active extruder may change as a side effect. Blocked during active prints (gcode_state RUNNING or PREPARE) because a tool swap mid-print is catastrophic on H2D. With user_permission False the tool changes nothing and returns the refusal string "Error: user_permission must be True to perform this action." followed by a sentence naming this consequence.

Sibling disambiguation: set_nozzle_config records which nozzle hardware is installed; set_nozzle_temp sets a nozzle temperature target and does not describe the hardware. swap_tool also switches the active extruder but sends no nozzle settings. To read the current configuration use get_nozzle_info.

Parameters

  • name (string, required): Printer name as returned by get_configured_printers.
  • diameter (number, required): Nozzle diameter in mm. Pass one of 0.2, 0.4, 0.6, 0.8. Not fully enforced: 0 is accepted (NozzleDiameter.UNKNOWN) and sent to the printer, and a value that cannot be converted to a float (such as None) skips the "Invalid diameter" string and returns the generic "Error setting nozzle config" string.
  • nozzle_type (string, required): Nozzle material, case-insensitive. One of 'stainless_steel', 'hardened_steel', 'tungsten_carbide', 'brass', 'e3d'. 'brass' and 'e3d' work only on single-extruder printers. On a dual-extruder printer they have no encoded nozzle identifier, so the call returns "Error setting nozzle config on '<name>': Unsupported nozzle_type for encoded ID: NozzleType.BRASS" (or E3D) AFTER set_active_tool() has already switched the active extruder.
  • flow_type (string, default "standard"): Nozzle flow type, case-insensitive. Must be one of 'standard', 'high_flow', 'tpu_high_flow'. Default 'standard'. On dual-extruder printers this IS sent to the printer: it is encoded into the SET_NOZZLE command's nozzle-identifier SKU alongside nozzle_type. On single-extruder printers the underlying SET_ACCESSORIES command carries no flow field, so flow_type has no effect there.
  • extruder (integer, default 0): Extruder to configure on H2D: 0 = right nozzle, 1 = left nozzle, -1 = apply to all nozzles (extruder 0 then extruder 1). Default 0. Not range-checked: any other integer is forwarded to set_active_tool() and to the nozzle command.
  • user_permission (boolean, default false): Must be True to perform the change. Default False.

Returns

A plain string, never a dict. Success: "Nozzle config set to <diameter>mm <nozzle_type> on <extruder N | all extruders> of '<name>'." This means the MQTT command(s) were published; the printer's acceptance is not awaited, so verify with get_nozzle_info after the next telemetry update. On dual-extruder printers the SET_NOZZLE command also carries a fixed wear of 0. Errors, all strings: the "Error: user_permission must be True ..." refusal; "Error: Printer '<name>' not connected."; the active-print block message ("Blocked: '<name>' is currently <state>. ..."); "Error: Invalid diameter <diameter>. Valid values: [...]"; "Error: Unknown nozzle_type '<nozzle_type>'. Valid: [...]"; "Error: Unknown flow_type '<flow_type>'. Valid: [...]"; "Error setting nozzle config on '<name>': <exception>".

Notes

The switch decision compares extruder with the active tool read ONCE before the call. On a single-extruder printer the active tool reads -1, so a select_extruder command for extruder 0 is published before EVERY SET_ACCESSORIES (which applies to the currently active extruder), not only when extruders differ. On a dual-extruder printer SET_NOZZLE names its target extruder by id, so the set_active_tool() call is a side effect of this tool rather than a requirement of the command. For extruder=-1 the printer is left on extruder 1 when it started on extruder 0 or had no active tool (-1 or 15), and on extruder 0 when it started on extruder 1.

swap_tool

Swap Active Extruder · write · needs user_permission=True

Swap the active extruder on H2D dual-extruder printers.

WHEN to use: switch which extruder (0 = right, 1 = left) the printer uses for subsequent moves and extrusions, either by toggling or by selecting a specific extruder.

WRITE GUARD: sends a SET_ACTIVE_TOOL command over MQTT that changes the printer's active extruder. Blocked during active prints (gcode_state RUNNING or PREPARE): on H2D, swapping the active extruder mid-print crashes the inactive nozzle into the active print, and firmware provides NO protection against this because low-level command injection bypasses all print-job safety checks. With user_permission False the tool changes nothing and returns the refusal string "Error: user_permission must be True to perform this action." followed by a sentence naming this consequence.

Sibling disambiguation: swap_tool only selects the active extruder. set_nozzle_config describes the installed nozzle hardware (and switches the active extruder itself only as a side effect of that); set_nozzle_temp sets a nozzle temperature target.

Parameters

  • name (string, required): Printer name as returned by get_configured_printers.
  • extruder_id (integer or null, default null): None (default) toggles using the CACHED active tool: extruder 0 becomes 1, and any other cached value (-1 single-extruder, 15 transitional, or unknown) becomes 0, so it is a true toggle only when the cached value is 0 or 1. 0 or 1 selects that extruder directly, regardless of the current state; the value is not range-checked and any integer is published as the extruder index.
  • user_permission (boolean, default false): Must be True to perform the swap. Default False.

Returns

A plain string, never a dict. Success: "Tool selection command sent: extruder <N> now active on '<name>'." Errors, all strings: the "Error: user_permission must be True ..." refusal; "Error: Printer '<name>' not connected."; the active-print block message ("Blocked: '<name>' is currently <state>. ..."); "Error swapping tool on '<name>': <exception>".

Notes

The command is published whatever the printer type: there is no dual-extruder check, so a single-extruder printer still receives it and the tool still returns the success string. Whether that firmware ignores it is not established by this code. The success string means the command was published, not that the extruder changed.