Skip to content

Filament & AMS

11 tools, defined in tools/filament.py.

Tool Title Access
calibrate_ams_remaining Rescan AMS Spool RFID write
get_ams_units Get AMS Units read-only
get_external_spool Get External Spool read-only
get_filament_catalog Get Filament Catalog read-only
load_filament Load Filament write
send_ams_control_command Send AMS Control Command write
set_ams_filament_setting Set AMS Filament Setting write
set_ams_user_setting Set AMS User Setting write
start_ams_dryer Start AMS Dryer write
stop_ams_dryer Stop AMS Dryer write
unload_filament Unload Filament write

calibrate_ams_remaining

Rescan AMS Spool RFID · write · needs user_permission=True

Ask the printer to re-scan the RFID tag on the specified AMS slot.

WHEN to use: have the printer re-read one slot's RFID tag so that slot's spool data, such as its remaining percentage, may be refreshed.

WRITE GUARD: sends an RFID re-read request for the slot to the printer, which is asked to rescan the tag. With user_permission False the tool changes nothing and returns the refusal string naming that consequence.

Sibling disambiguation: calibrate_ams_remaining triggers a one-time RFID re-scan of a single slot. set_ams_user_setting changes the standing RFID-scan and remaining- estimation settings, set_ams_filament_setting writes the slot's filament fields by hand, and get_spool_info reads the updated spool data.

Parameters

  • name (string, required): Configured printer name (see get_configured_printers).
  • unit_id (integer, required): AMS unit index (0-based position in the get_ams_units units list). A value outside that range is matched against the raw hardware ams_id.
  • slot_id (integer, required): Slot within the unit to scan (0-3).
  • user_permission (boolean, default false): Must be True to execute. Default False.

Returns

A str. Success: "RFID re-scan triggered for AMS unit <unit_id> slot <slot_id> on '<name>'.". Errors are "Error: ..." strings, never a dict: the _permission_denied refusal when user_permission is False, "Error: Printer '<name>' not connected.", "Error: AMS unit <unit_id> not found on '<name>'.", or "Error triggering RFID scan on '<name>': <exception>" when the command fails.

Notes

This asks the printer to re-read the RFID tag in the specified slot. Updated spool telemetry, which may include remaining_percent (see get_spool_info()), arrives later in a normal state push. The success string only means the request was published; it does not show that any value changed. Only RFID-equipped Bambu Lab spools carry tag data, and what the tag itself stores (remaining weight or otherwise) is not established by this code.

get_ams_units

Get AMS Units · read-only

Return all AMS units and their slot states for the named printer.

WHEN to use: read AMS temperature, humidity, heater and drying state and which slots hold a spool, or find the positional unit_id to pass to the AMS write tools in this module.

Sibling disambiguation: get_ams_units and get_ams_status return the same ams_status / ams_count / units payload from the same printer state; this tool's description is the field reference for the units list, and the order of that list is what unit_id indexes. get_spool_info is filament-centric (spool type, color, remaining percentage). get_external_spool reports the external spool holder.

Parameters

  • name (string, required): Configured printer name (see get_configured_printers).

Returns

{"ams_count": int, "ams_status": str, "units": [dict]}. ams_count is the number of connected AMS units, ams_status is the global AMS status text, and units is an empty list when the printer reports none. Each unit dict includes temperature, humidity, dryer state, and per-slot filament presence, as the fields ams_id, chip_id, model, temp_actual, humidity_index, humidity_raw, ams_info, dryer (an object, or null; see Notes), tray_exists (see Notes) and assigned_to_extruder; enum fields appear as their names. dryer holds state, sub_status, fan1_status, fan2_status, remaining_minutes, temp_target, duration_target_hours, filament_target, refusals, refusal_message, fail_code, fail_message and fail_count. Error shape: {"error": "Printer '<name>' not connected"}.

Notes

Field semantics:

  • ams_id is the AMS unit id as reported by the printer (for example 0 for the first AMS 2 Pro, 128 for AMS HT). chip_id is a separate field holding the unit's hardware serial string; the two are not synonyms. The 0-based positional unit_id used by load_filament() and other write tools refers to the position of the unit in the ams_units list, not to either value.
  • tray_exists has one boolean per slot: four on a standard AMS unit (slots 0–3), one on an AMS HT, which has a single slot.
  • dryer is null on a unit that cannot dry. With model UNKNOWN that means the unit has not reported yet; with any other model (AMS_LITE, AMS_1) it has no dryer. Only an AMS 2 Pro or AMS HT carries one, and start_ams_dryer refuses the others.
  • The AMS model is identified by the model field (AMSModel enum name, e.g. 'AMS_2_PRO', 'AMS_HT'). See the enums knowledge module for all values.
  • On H2D: AMS 2 Pro (ams_id=0, first in list) feeds the RIGHT extruder (extruder 0); AMS HT (ams_id=128, second in list) feeds the LEFT extruder (extruder 1).
  • humidity_index scale: 1=WET (alert, filament needs drying), 5=DRY (good, no action needed). IMPORTANT: higher numbers mean DRIER — the scale is counterintuitive. Only humidity_index values of 1 or 2 indicate a moisture problem. A value of 5 means the filament is completely dry. 0 means the sensor reading is unavailable (uninitialized or not supported by this AMS model — do not treat as wet).
  • dryer.state: AMSHeatingState enum name — OFF, CHECKING (transient), DRYING (active), COOLING, STOPPING, ERROR, CANNOT_STOP_HEAT_OOC, PRODUCT_TEST. CHECKING is a brief transition state after issuing a start_ams_dryer() command; DRYING with sub_status=HEATING confirms active heating.
  • dryer.remaining_minutes: minutes left in the running dry; 0 when idle.
  • dryer.refusals: why a dry cannot start now, as the printer's raw dry_sf_reason ints (bpm AMSDryerRefusal: 2 AMS busy, 3 filament at the AMS outlet, 4 initiating, 6 drying in progress, ...). [] means a dry can start; [6] alone means one is running. dryer.refusal_message is Bambu Studio's text for them, "" when a dry can start; start_ams_dryer refuses while it is set.
  • dryer.temp_target / duration_target_hours / filament_target: the running dry's order (°C, hours, filament type); -1 / -1 / "" when idle. temp_target is the order, not a measurement; temp_actual is the measured temperature.
  • dryer.fail_code / fail_message: the printer's decoded reply to the last refused drying command (e.g. HMS_0500-C04B), "" after an accepted one; fail_count counts refused replies and only grows.
  • dryer.sub_status: AMSDryerSubStatus enum name — OFF, HEATING, DEHUMIDIFY. The current phase within an active drying cycle.
  • dryer.fan1_status / fan2_status: AMSDryerFanStatus enum name — OFF or ON. The two drying fans (bits 18–19 and 20–21 of ams_info). Only meaningful while state=DRYING.

get_external_spool

Get External Spool · read-only

Return the filament info for the external spool holder.

WHEN to use: check what filament sits on the external spool holder (or holders on a dual-nozzle printer), for example before load_filament with slot_id 254.

Sibling disambiguation: get_external_spool returns the external holder trays alone. get_spool_info returns every spool on the printer plus the active one, and get_ams_units returns the AMS units and their slot states.

Parameters

  • name (string, required): Configured printer name (see get_configured_printers).

Returns

{"loaded": True, "spool": <dict>, "spools": [<dict>, ...]} when any external tray entry exists, or {"loaded": False, "spool": None, "spools": []} when none does. loaded True means an entry exists, not that filament is on a holder: when telemetry carries vir_slot, the printer library adds a placeholder entry (empty type, slot_id -1) for each of 254 and 255 the printer reported no tray for. Check each entry's type; an empty string means no filament type is reported for that holder. Identify the holder by id (254 or 255), not by slot_id. "spool" is the entry that holds a filament type, preferring 254 over 255, and falls back to the first entry when none holds one. "spools" lists every external entry so a dual-nozzle caller can see both holders. Error shape: {"error": "Printer '<name>' not connected"}.

Notes

Telemetry names the holders 254 and 255. A single-nozzle printer has one physical holder, 254, but spools can still list both whenever vir_slot is reported. A dual-nozzle printer has a LEFT holder, 254, and a RIGHT holder, 255.

get_filament_catalog

Get Filament Catalog · read-only

Return Bambu filament profiles from the catalog bundled with bambu-printer-manager.

WHEN to use: find the filament_id (tray_info_idx, for example GFA00) to pass to set_ams_filament_setting, or read a profile's nozzle, bed and drying temperatures.

Sibling disambiguation: get_filament_catalog is static reference data and reads no printer. get_spool_info and get_ams_units report what is loaded in the AMS now.

Parameters

  • filament_type (string, default ""): Keep only profiles of this type, for example PLA or ABS-GF. Case-insensitive exact match. Default "" keeps every type.
  • search (string, default ""): Keep only profiles whose tray_info_idx, name or vendor contains this text. Case-insensitive. Default "" keeps every profile.

Returns

{"count": int, "filaments": [ {...}, ... ]}. Each profile carries tray_info_idx, name, vendor, filament_type, nozzle_temperature, nozzle_temperature_range_low, nozzle_temperature_range_high and hot_plate_temp, plus drying fields keyed by AMS model where the catalog has them. Any payload over 300 characters is returned as a gzip+base64 envelope: {"compressed": True, "encoding": "gzip+base64", "original_size_bytes": int, "compressed_size_bytes": int, "data": str}. Filter to keep responses small. Error shape: {"error": "Error reading filament catalog: <exception>"}.

load_filament

Load Filament · write · needs user_permission=True

Load filament from a specific AMS unit and slot into the extruder.

WHEN to use: feed the filament in one AMS slot, or on the external spool holder, into the extruder while no print is active.

WRITE GUARD: sends a load-filament command to the printer, which starts feeding filament from the chosen slot into the extruder. With user_permission False the tool changes nothing and returns the refusal string naming that consequence. A second gate blocks the call while the printer is printing (see Returns).

Sibling disambiguation: load_filament feeds filament into the extruder; unload_filament retracts the loaded filament back into the AMS. set_ams_filament_setting only changes the filament metadata stored for a slot and moves no filament.

Parameters

  • name (string, required): Configured printer name (see get_configured_printers).
  • unit_id (integer, required): AMS index (0-based position in the get_ams_units units list). A value outside that range is matched against the raw hardware ams_id.
  • slot_id (integer, required): Slot within the unit (0-3). Use 254 to load from the external spool holder. On a dual-nozzle printer 254 is the LEFT holder and 255 is the RIGHT holder. bpm sends a holder load as Bambu Studio does (ams_id 254/255, slot_id 0, target 254/255); on hardware, neither holder load has been observed yet. The external spool holder is a separate filament feeder that attaches to the printer's side, holding one spool outside the AMS unit. get_external_spool() reports what is loaded on it.
  • user_permission (boolean, default false): Must be True to execute. Default False.

Returns

A str. Success: "Load filament command sent for AMS unit <unit_id> slot <slot_id> on '<name>'.", returned after waiting up to 5 seconds for a refusal. A refusal the printer sends back (for example while the unit is drying) returns "Error: '<name>' refused the load from AMS unit <unit_id> slot <slot_id>: <reason>" with the printer's own reason: bpm's command_error entry in hms_errors. Errors are strings, never a dict: the _permission_denied refusal when user_permission is False, "Error: Printer '<name>' not connected.", the active-print block message ("Blocked: '<name>' is currently <gcode_state>. load_filament is not safe while a print is active. ..."), "Error: AMS unit <unit_id> not found on '<name>'.", or "Error loading filament on '<name>': <exception>" when the command fails.

Notes

H2D dual-extruder pairing (AMS 2 Pro to the RIGHT extruder, AMS HT to the LEFT) is printer behavior that get_ams_units reports per unit as assigned_to_extruder; this code does not establish it. The tool sends only the resolved ams_id and slot_id: the printer library copies slot_id into the command's target field, which bpm's protocol reference describes as the extruder to load into, and it marks multi-unit loading unfinished (TODO: refactor to support multiple AMSs). Loading from a unit other than the first is therefore unverified.

To find the correct unit_id: call get_ams_units() and use the positional index (0-based) of the desired unit in the returned list. ams_id values are assigned by the printer and should not be hardcoded. unit_id must resolve to a connected AMS unit even when slot_id is 254; otherwise the tool returns the "AMS unit not found" error.

⛔ BLOCKED during active prints (gcode_state RUNNING or PREPARE), because a filament change during a print risks toolhead crashes or failed prints.

send_ams_control_command

Send AMS Control Command · write · needs user_permission=True

Send an AMS control command: pause, resume, reset, done or abort.

WHEN to use: recover from an AMS-triggered pause (filament runout, AMS fault) with 'RESUME', or pause the AMS feed or reset the AMS with 'PAUSE' or 'RESET'. During a filament load, answer the printer's prompt the way Bambu Studio's buttons do: 'RESUME' with resume_print=False for "Finished, Continue" and the Retry buttons, 'DONE' for "Filament Extruded, Continue", and 'ABORT' to cancel the load or unload. The buttons the printer offers are the actions of the device_error entry in get_hms_errors.

WRITE GUARD: sends the chosen AMS control command to the printer, which pauses the AMS feed, resets the AMS, tells a waiting load to go on, cancels the running load or unload ('ABORT'), or, for 'RESUME', unblocks the AMS feed and by default resumes the halted print job. With user_permission False the tool changes nothing and returns the refusal string naming that consequence.

Sibling disambiguation: send_ams_control_command acts on the AMS and, for 'RESUME', also resumes the print. pause_print and resume_print act on the print job itself; do not call resume_print after 'RESUME', as that would be a duplicate command.

Parameters

  • name (string, required): Configured printer name (see get_configured_printers).
  • cmd (string, required): One of 'PAUSE', 'RESUME', 'RESET', 'DONE', 'ABORT' (case-insensitive).
  • user_permission (boolean, default false): Must be True to execute. Default False.
  • resume_print (boolean, default true): With 'RESUME', also resume the print (default True). Pass False to answer a load prompt, which Studio does with the AMS command alone.

Returns

A str. Success: "AMS control command <CMD> sent to '<name>'." with CMD in upper case. Errors are "Error: ..." strings, never a dict: the _permission_denied refusal when user_permission is False, "Error: Printer '<name>' not connected.", "Error: Unknown AMS control command '<cmd>'. Must be one of: PAUSE, RESUME, RESET, DONE, ABORT.", or "Error sending AMS control command to '<name>': <exception>" when the command fails.

Notes

- 'PAUSE'  — pause the AMS feed mid-print.
- 'RESUME' — unblocks the AMS feed AND resumes the halted print job in a
  single operation. Use this for AMS-triggered pauses (filament runout,
  AMS fault). Do not also call resume_print() after this — that would be
  a duplicate command.
- 'RESET'  — reset the AMS to its idle/ready state.
- 'DONE'   — the filament is extruded; the waiting load goes on.
- 'ABORT'  — cancel the running filament load or unload.

set_ams_filament_setting

Set AMS Filament Setting · write · needs user_permission=True

Set filament details for a specific AMS slot on the named printer.

WHEN to use: record or correct the filament identity, color, and nozzle temperature range of one AMS slot, or clear the slot by passing filament_id 'no_filament'.

WRITE GUARD: sends the slot's filament setting (material code, name, type, color, and nozzle temperature range) to the printer in a single command, overwriting what the slot currently holds; filament_id, filament_name and filament_type left at their defaults are sent as empty strings, an empty color is not sent (opaque white is written instead), and temperatures left at -1 are sent as -1. With user_permission False the tool changes nothing and returns the refusal string naming the overwrite.

Sibling disambiguation: set_ams_filament_setting writes the slot's stored filament fields and moves no filament. calibrate_ams_remaining asks the printer to re-read the slot's RFID tag instead of writing fields, load_filament and unload_filament move filament, and get_spool_info reads the resulting spool data.

Parameters

  • name (string, required): Configured printer name (see get_configured_printers).
  • unit_id (integer, required): AMS unit index (0-based position in the get_ams_units units list). A value outside that range is matched against the raw hardware ams_id (for example 128 for AMS HT).
  • slot_id (integer, required): Slot within that unit (0-3).
  • filament_id (string, default ""): Bambu Lab catalog material code (tray_info_idx), e.g. 'GFA00' for Bambu PLA Basic. This is a primary identity field — a lookup key from Bambu's filament database that encodes temperature profiles, drying parameters, and flow characteristics. Pass 'no_filament' to clear the slot and mark it as empty. Default "" (sent as empty).
  • filament_name (string, default ""): Bambu Lab vendor-specific brand label (e.g. 'Bambu PLA Basic'). It is optional, absent on third-party spools, and NOT a reliable spool identifier. The true identity of a spool is color + filament_id (base profile), not this name field. Default "" (sent as empty).
  • filament_type (string, default ""): Short filament type string (e.g. 'PLA', 'PETG', 'ABS'). Default "" (sent as empty).
  • color (string, default ""): CSS color name or RRGGBB hex string. Default "" is NOT sent as empty: the library skips an empty color, so the command keeps its template default FFFFFFFF and the slot color is set to opaque white. Always pass the color you want.
  • nozzle_temp_min (integer, default -1): Minimum nozzle temperature in °C. The default -1 is sent as-is; whether the printer treats -1 as "leave unchanged" is not established by this code.
  • nozzle_temp_max (integer, default -1): Maximum nozzle temperature in °C. The default -1 is sent as-is; whether the printer treats -1 as "leave unchanged" is not established by this code.
  • user_permission (boolean, default false): Must be True to execute. Default False.

Returns

A str. Success: "Filament setting updated for AMS unit <unit_id> slot <slot_id> on '<name>'.". Errors are "Error: ..." strings, never a dict: the _permission_denied refusal when user_permission is False, "Error: Printer '<name>' not connected.", "Error: AMS unit <unit_id> not found on '<name>'.", or "Error setting filament on '<name>': <exception>" when the command fails.

Notes

WARNING: This call sends ALL fields to the printer in a single command. Text fields left at their default go out as empty strings and temperatures left at -1 go out as -1; whether the printer treats an empty string as "clear this field" is not established by this code, and the refusal text's "empty fields clear existing values" is likewise unverified. Always pass ALL relevant fields in a single call (filament_id, filament_type, color, nozzle_temp_min, nozzle_temp_max) to avoid overwriting existing slot metadata.

To clear a slot, pass filament_id='no_filament': the library then ignores filament_name, filament_type, color and both temperatures and writes name "", type "", color FFFFFF00 and temperatures 0/0.

The tool computes the absolute tray id as ams_id + slot_id when the resolved ams_id is 128 or higher (AMS HT), otherwise ams_id * 4 + slot_id. The printer library then re-derives the command's ams_id as tray_id // 4 and slot_id as tray_id % 4 (only 254/255 are special-cased), so on AMS HT tray_id 128 goes out as ams_id 32, slot_id 0, tray_id 128. Whether that reaches an AMS HT slot is unverified against printer firmware; do not rely on it.

set_ams_user_setting

Set AMS User Setting · write · needs user_permission=True

Enable or disable an AMS user setting on the named printer.

WHEN to use: turn on or off spool-weight remaining estimation, the RFID scan at printer power-on, or the RFID scan when a spool is inserted.

WRITE GUARD: sends the AMS user-setting command to the printer, which changes one of the three AMS user settings on the printer. With user_permission False the tool changes nothing and returns the refusal string naming that consequence.

Sibling disambiguation: set_ams_user_setting changes a standing AMS behavior setting. calibrate_ams_remaining triggers a one-time RFID re-scan of a single slot, and set_ams_filament_setting writes one slot's filament fields.

Parameters

  • name (string, required): Configured printer name (see get_configured_printers).
  • setting (string, required): One of 'calibrate_remain_flag', 'startup_read_option', 'tray_read_option' (case-insensitive).
  • value (boolean, required): True to enable the setting, False to disable it.
  • user_permission (boolean, default false): Must be True to execute. Default False.

Returns

A str. Success: "AMS setting '<setting>' set to <value> on '<name>'.". Errors are "Error: ..." strings, never a dict: the _permission_denied refusal when user_permission is False, "Error: Printer '<name>' not connected.", "Error: Unknown setting '<setting>'. Supported: [...]", or "Error setting AMS user setting on '<name>': <exception>" when the command fails.

Notes

Supported settings: 'calibrate_remain_flag' (spool-weight based remaining
estimation), 'startup_read_option' (RFID scan on power-on), 'tray_read_option'
(RFID scan on spool insert).
'calibrate_remain_flag' = estimate remaining filament by tracking spool weight.
  Requires an AMS unit with built-in weight sensors (AMS 2 Pro only). AMS Lite
  and AMS HT do not have weight sensors — enabling this on those units has no effect.
'startup_read_option' = scan RFID tags on all loaded spools when the printer powers on,
  to detect filament changes made while the printer was off.
'tray_read_option' = scan the RFID tag when a spool is inserted into an AMS slot,
  auto-populating filament type, color, and temperature profile from the tag.

The tool passes no unit selector: the printer library sends the command with its default ams_id (0). The command includes all three settings: the named one is set to value and the other two come from the library's last-seen telemetry values, not a fresh read from the printer. Those default to False until a status report arrives, so calling this early in a session can write False for the other two.

start_ams_dryer

Start AMS Dryer · write · needs user_permission=True

Start the AMS filament dryer on the specified unit.

WHEN to use: dry the filament in one AMS unit at a chosen temperature and duration, for example when get_ams_units shows a low humidity_index.

WRITE GUARD: sends a start-drying command that turns on the unit's dryer heater at the given temperature for the given duration. With user_permission False the tool changes nothing and returns the refusal string naming that consequence.

Sibling disambiguation: start_ams_dryer turns the dryer on and waits up to 10 seconds for the unit to report DRYING; stop_ams_dryer turns it off. get_ams_units reads the resulting dryer.state and dryer.sub_status.

Parameters

  • name (string, required): Configured printer name (see get_configured_printers).
  • unit_id (integer, required): AMS unit index (0-based position in the get_ams_units units list). A value outside that range is matched against the raw hardware ams_id.
  • target_temp (integer, default 55): Drying temperature in °C. Default 55. Must be 45-65 on an AMS 2 Pro and 45-85 on an AMS HT (Bambu Studio's limits); anything else is refused, not clamped.
  • duration_hours (integer, default 4): Drying time in hours, 1-999, passed unchanged as the command's duration field. Default 4. Hours is settled by Bambu Studio's source and was measured on H2D firmware (72 h and 999 h accepted, 2026-09-26); there is no 24 h cap. The printer reports the time left (dryer.remaining_minutes) in minutes.
  • rotate_tray (boolean, default false): Passed to the printer as the rotate-tray flag for the drying command. Default False.
  • user_permission (boolean, default false): Must be True to execute. Default False.

Returns

A str. Success: "AMS dryer started on unit <unit_id> (ams_id=<ams_id>): <target_temp>°C for <duration_hours>h on '<name>'. heater_state=DRYING". Errors are "Error: ..." strings, never a dict: the _permission_denied refusal when user_permission is False, "Error: Printer '<name>' not connected.", "Error: AMS unit <unit_id> not found on '<name>'.", "Error: <reason> Nothing was sent to '<name>'." when the unit has no dryer, the temperature or duration is out of range, or the AMS reports a reason it cannot dry now (bpm's dryer.refusal_message, e.g. filament left in the AMS outlet; checked before anything is published), "Error: '<name>' refused the AMS dryer start on unit <unit_id> (ams_id=<ams_id>): <printer's reason> (<HMS code>)" as soon as the printer's reply refuses the command, "Error: AMS dryer command sent to unit <unit_id> (ams_id=<ams_id>) on '<name>' but heater_state did not reach DRYING within 10s (final state: <STATE or unknown>). Check get_ams_units for current state." (the command WAS sent in that case; it is returned after the full 10s, or sooner when heater_state reads ERROR or falls back to OFF after showing another state since the command), or "Error starting AMS dryer on '<name>': <exception>" when the command fails. One more outcome that is not an error: "AMS dryer command sent to unit <unit_id> (ams_id=<ams_id>) on '<name>', but the unit was already DRYING before the command and heater_state never changed, so it cannot show whether the command was accepted ...", returned after the full 10s. Drying is in progress; whether it follows the new temperature and duration has to be read from get_ams_units.

Notes

Only a unit whose dryer is set (an AMS 2 Pro or AMS HT) is sent the command. Any other unit (AMS Lite, the original AMS, one not reported yet) is refused before publishing, and so is a temperature outside the model's range, which the firmware does not clamp. The HTTP route /api/turn_on_ams_dryer applies the same checks.

filament_type is derived from the first spool in the target AMS unit that reports a type (spool.type, e.g. "ABS", "PLA") and falls back to "" if there is none. bpm documents it only as passed to firmware for validation; what the firmware does with an empty value is not established by this code.

Heater state transition: after the command is sent, dryer.state may briefly read CHECKING (a transitional state). Active drying is confirmed by state=DRYING with sub_status=HEATING. This tool polls once per second (first reading one second after the publish), up to 10 seconds, waiting for DRYING before returning. dryer.state is only rewritten when a telemetry frame carrying the AMS info word arrives, so until then it still holds whatever it held before the command (OFF, COOLING, DRYING, ERROR, anything). The tool records that value just before publishing and ignores every read equal to it; the first read that differs shows a post-command frame has landed, and every read after that counts. DRYING then means success. The tool stops polling early, and returns the "did not reach DRYING" error, when a post-command read is ERROR, or is OFF after another post-command state (CHECKING, COOLING and so on). That is what the code assumes a rejected command looks like; no such sequence has been observed on hardware, so treat it as unmeasured. A first post-command read of OFF (a unit that was COOLING, say) is waited out, not treated as a rejection. If the unit was already DRYING and never reports anything else, the reads cannot show whether the command was accepted, and the tool says so instead of claiming a start. A command the printer accepts but whose first frame arrives later than 10 seconds still ends in the timeout error with the command in effect; confirm with get_ams_units.

Sticky preferences: before presenting parameters to the user, look up stored values with get_user_pref(name, key), keys ams<unit_id>:target_temp, ams<unit_id>:duration_hours and ams<unit_id>:rotate_tray (for example ams0:target_temp). A null value means nothing is stored: use the factory default. Factory defaults: target_temp=55, duration_hours=4, rotate_tray=False. Label each "(your preference)" if stored value differs from factory default, "(default)" otherwise. After a successful call, store the confirmed values with set_user_pref(name, key, value) for each of the three keys.

stop_ams_dryer

Stop AMS Dryer · write · needs user_permission=True

Stop the AMS filament dryer on the specified unit.

WHEN to use: end a drying cycle early on one AMS unit, or make sure its dryer is off.

WRITE GUARD: sends a turn-off-drying command that switches the unit's dryer off and ends its drying cycle. With user_permission False the tool changes nothing and returns the refusal string naming that consequence.

Sibling disambiguation: stop_ams_dryer turns the dryer off; start_ams_dryer turns it on. get_ams_units reads the resulting dryer.state.

Parameters

  • name (string, required): Configured printer name (see get_configured_printers).
  • unit_id (integer, required): AMS unit index (0-based position in the get_ams_units units list). A value outside that range is matched against the raw hardware ams_id.
  • user_permission (boolean, default false): Must be True to execute. Default False.

Returns

A str. Success: "AMS dryer stopped on unit <unit_id> (ams_id=<ams_id>) on '<name>'.". Errors are "Error: ..." strings, never a dict: the _permission_denied refusal when user_permission is False, "Error: Printer '<name>' not connected.", "Error: AMS unit <unit_id> not found on '<name>'.", "Error: <reason>. Nothing was sent to '<name>'." when bpm refuses the unit (it has no dryer), or "Error stopping AMS dryer on '<name>': <exception>" when the command fails.

unload_filament

Unload Filament · write · needs user_permission=True

Unload the currently loaded filament from the extruder back into the AMS.

WHEN to use: retract the filament that is currently loaded in the extruder back into the AMS while no print is active.

WRITE GUARD: sends an unload-filament command to the printer, which starts retracting the loaded filament out of the extruder. With user_permission False the tool changes nothing and returns the refusal string naming that consequence. A second gate blocks the call while the printer is printing (see Returns).

Sibling disambiguation: unload_filament retracts the loaded filament back into the AMS and takes an optional unit, no slot; load_filament feeds a chosen slot into the extruder. get_spool_info shows which spool is currently loaded.

Parameters

  • name (string, required): Configured printer name (see get_configured_printers).
  • user_permission (boolean, default false): Must be True to execute. Default False.
  • unit_id (integer or null, default null): AMS unit to unload from, as in load_filament (positional index, or a raw ams_id). Default None: the unit, or external holder (254/255), the active tray is in; unit 0 when nothing is active.

Returns

A str. Success: "Unload filament command sent to '<name>'.", returned after waiting up to 5 seconds for a refusal. A refusal the printer sends back returns "Error: '<name>' refused the unload from AMS unit <ams_id>: <reason>", and an unknown unit_id returns "Error: AMS unit <unit_id> not found on '<name>'.". Errors are strings, never a dict: the _permission_denied refusal when user_permission is False, "Error: Printer '<name>' not connected.", the active-print block message ("Blocked: '<name>' is currently <gcode_state>. unload_filament is not safe while a print is active. ..."), or "Error unloading filament on '<name>': <exception>" when the command fails.

Notes

⛔ BLOCKED during active prints (gcode_state RUNNING or PREPARE), because a filament change during a print risks toolhead crashes or failed prints.

The command names one AMS unit (see unit_id). An unload naming an AMS HT (ams_id 128) has not been tried on hardware.