Skip to content

Alerts

1 tools, defined in tools/notifications.py.

Tool Title Access
get_pending_alerts Get Pending Alerts read-only

get_pending_alerts

Get Pending Alerts ยท read-only

Return the queued state-change alerts for the named printer.

WHEN to use: poll for high-visibility transitions (job started, finished, failed, paused or resumed, active HMS faults appearing or clearing, job health shifts) since the last call. This works whether or not the MCP client supports resource subscriptions, and is the recommended polling path for all clients.

Sibling disambiguation: get_pending_alerts returns the queue of transitions that happened since you last read it, and by default empties that queue. get_hms_errors returns the HMS entries as they stand right now, each labelled active or Historical, and get_job_info returns the current job's state. Neither of those is a history of changes.

Parameters

  • name (string, required): Printer name (required).
  • clear (boolean, default true): If True (default), the pending alert queue is emptied after reading, so each alert is returned once. Pass False to peek without consuming.

Returns

A list of alert dicts. An empty list means nothing is queued: no new transitions, or another consumer drained the queue first (see Notes). If the printer is not connected, a one-element list [{"error": "Printer '<name>' not connected"}].

Each alert dict has:
  type      -- alert type key. One of: job_started, job_finished, job_failed,
               job_paused, job_resumed, stage_change, hms_error_new,
               hms_error_cleared, health_escalated, health_recovered.
  printer   -- printer name string.
  timestamp -- ISO 8601 UTC timestamp when the transition was detected.
  severity  -- "high", "medium", or "low".
  payload   -- type-specific fields (see the table below).

Notes

Alerts are queued in memory (at most 50 per printer, older ones dropped) as printer state updates arrive, so none are produced while the MQTT session is paused, and the first state seen for a printer after server start produces none. The queue is shared: GET /api/alerts drains it by default and DELETE /api/alerts clears it, so an alert read there is gone here. It is lost on server restart and is not reset when a printer session is stopped or restarted.

Transitions that produce each job alert: job_started only on a direct change to RUNNING from IDLE, FINISH, FAILED or an empty state (a PREPARE to RUNNING change produces none); job_finished on RUNNING or PAUSE to FINISH; job_failed on any change into FAILED; job_paused on RUNNING to PAUSE; job_resumed on PAUSE to RUNNING.

Payload fields by type (what the code currently emits):
  job_started:       {} (empty)
  job_finished:      {} (empty)
  job_failed:        {} (empty)
  job_paused:        stage_id (int, the printer's stage code when it paused; null if
                     the stage is not known), stage_name (the stage's name, e.g.
                     "Paused by user"; "unknown" when there is no stage)
  job_resumed:       {} (empty)
  stage_change:      stage_id, stage_name, prev_stage_id, prev_stage_name
  hms_error_new:     errors=[{code, description}, ...] (active faults only; description
                     is the decoded HMS message text for that code; "Unknown HMS
                     Error" for a code the HMS catalogue does not list, and "No
                     description in the HMS catalogue" for a code it lists with empty
                     text)
  hms_error_cleared: prev_error_count
  health_escalated:  from_verdict, to_verdict, score
  health_recovered:  from_verdict, to_verdict, score
The job payloads are meant to carry subtask_name, gcode_file and plate_num (and
job_finished elapsed_min and layer_num), but those fields are never populated: do
not index them.

stage_change is emitted when the printer enters a new stage other than "no stage" (codes -1 and 0), "Printing" (100) and "Completed" (255): pre-print calibration, filament operations and pause stages. Stage codes and names come from the printer library (bpm), the same ones get_job_info reports. A stage that simply continues does not alert again, and re-entering a stage that alerted less than 30 s ago is suppressed. The first stage seen for a printer after server start produces no alert.

HMS alerts are for ACTIVE faults only. A fault is active by the same rule get_hms_errors applies: a device_error (print_error != 0) plus the first device_hms entry. Every other device_hms entry is Historical, and a Historical entry never produces hms_error_new or hms_error_cleared, however often the telemetry re-sends or drops it. (bpm's raw HMS list carries no such label, so a stale code can read severity "Fatal" there and still be Historical here.) hms_error_new lists only newly active codes, and a code that alerted less than 30 s ago is not alerted again when it flaps back in. hms_error_cleared is emitted only after an hms_error_new was raised, and only when every active HMS code has cleared; a partial clear is silent, and so is a clear that follows only suppressed re-appearances.

Health alerts exist only while the camera job monitor is producing verdicts, are limited to one per 60 s, and are never emitted for the first verdict seen or for a "standby" verdict. from_verdict and to_verdict are the monitor's stable verdicts (the most common of its last five analyses), and score is the anomaly_score of its latest analysis: the weighted composite that verdict is thresholded on, the same figure open_job_state returns as score. So the score can sit on the other side of a threshold from to_verdict.

Known code defect: the job fields above are missing because SessionManager has no get_job_info() or get_progress() (the resulting errors are swallowed).

Call kb_get('bambu-state-change-alerts') for further documentation on each alert type, recommended actions, and severity guidance.