mcp-3d-printer-server 1.2.24 → 1.2.26

package/dist/safety/print-file.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { readBoundedPrintFile, loadSafe3mfArchive } from './archive.js';
-import { MACHINE_LIMITS, normalizeMaterial, normalizeModel, validateStartupPurgeTemperature, validateTemperature } from './limits.js';
+import { projectFilaments } from "../ams-mapping.js";
+import { MACHINE_LIMITS, isDualNozzleModel, normalizeMaterial, normalizeModel, validateStartupPurgeTemperature, validateTemperature } from './limits.js';
 const NUMBER = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/;
 const fail = (message) => { throw new Error(`Print safety: ${message}`); };
 function list(value) {
@@ -35,6 +36,67 @@ function consistent(values, convert, field) {
         return fail(`contradictory ${field} metadata`);
     return converted[0];
 }
+/** Bambu Studio keeps filament options per variant in the project, but writes
+ * one selected row per filament in the plate header (Print::full_print_config).
+ * Match the declared 1-based self index and variant, never truncate the table
+ * or borrow the slicer's row-zero fallback for a missing selection.
+ */
+function firstLayerTemperatures(project, headers, count) {
+    const key = 'nozzle_temperature_initial_layer';
+    const field = 'first-layer nozzle temperature';
+    const temperatures = (value) => {
+        const entries = list(value);
+        return entries.length && entries.every(v => NUMBER.test(v) && Number.isFinite(Number(v))) ? entries.map(Number) : undefined;
+    };
+    const perFilament = (value) => {
+        const values = temperatures(value);
+        return values?.length === count ? values : undefined;
+    };
+    const selectedValues = metadataValues(headers, [key]);
+    if (project[key] === undefined)
+        return consistent(selectedValues, perFilament, field);
+    if (project.filament_extruder_variant === undefined && project.filament_self_index === undefined)
+        return consistent([project[key], ...selectedValues], perFilament, field);
+    const table = temperatures(project[key]);
+    const variants = list(project.filament_extruder_variant);
+    const ids = list(project.filament_self_index);
+    const validVariant = (value) => /^(Direct Drive|Bowden) (Standard|High Flow|Hybrid|TPU High Flow|E3D High Flow)$/.test(value);
+    if (!table || variants.length !== table.length || ids.length !== table.length ||
+        variants.some(v => !validVariant(v)) || ids.some(id => !/^[1-9]\d*$/.test(id) || Number(id) > count))
+        return fail(`unknown or malformed ${field} variant table`);
+    const selectedVariants = consistent(metadataValues(headers, ['filament_extruder_variant']), value => {
+        const values = list(value);
+        return values.length === count && values.every(validVariant) ? values : undefined;
+    }, 'selected filament extruder variant');
+    const selectedIds = consistent(metadataValues(headers, ['filament_self_index']), value => {
+        const values = list(value);
+        return values.length === count && values.every((id, index) => id === String(index + 1)) ? values : undefined;
+    }, 'selected filament self index');
+    // These are logical extruders: physical_extruder_map is used for spool
+    // routing, not this variant lookup. Hybrid selects the Standard variant.
+    const mappingKeys = ['filament_map', 'extruder_type', 'filament_volume_map'];
+    if (mappingKeys.every(key => metadataValues(headers, [key]).length)) {
+        const selection = (key) => consistent(metadataValues(headers, [key]), value => {
+            const entries = list(value);
+            return entries.length ? entries : undefined;
+        }, `selected ${key.replace(/_/g, ' ')}`);
+        const map = selection('filament_map');
+        const types = selection('extruder_type');
+        const volumes = selection('filament_volume_map');
+        const flows = { '0': 'Standard', '1': 'High Flow', '2': 'Standard', '3': 'TPU High Flow', '5': 'E3D High Flow' };
+        if (map.length !== count || volumes.length !== count || map.some(id => !/^[1-9]\d*$/.test(id) || Number(id) > types.length) ||
+            volumes.some(v => !Object.prototype.hasOwnProperty.call(flows, v)) || types.some(v => !['Direct Drive', 'Bowden'].includes(v)) ||
+            selectedVariants.some((variant, i) => variant !== `${types[Number(map[i]) - 1]} ${flows[volumes[i]]}`))
+            return fail('contradictory selected filament extruder variant mapping');
+    }
+    const resolved = selectedIds.map((id, index) => {
+        const rows = ids.flatMap((candidate, row) => candidate === id && variants[row] === selectedVariants[index] ? [row] : []);
+        if (rows.length !== 1)
+            return fail(`ambiguous or missing ${field} variant for filament ${id}`);
+        return table[rows[0]];
+    });
+    return consistent([resolved, ...selectedValues], perFilament, field);
+}
 function stripComments(line) {
     let clean = '';
     let depth = 0;
@@ -62,6 +124,11 @@ function stripComments(line) {
 /** A deliberately narrow parameter lexer for commands affecting heat/material selection.
  * Unknown nonthermal vendor commands do not require a global G-code allowlist.
  */
+/** True when the parameter is present, finite and within [low, high]. */
+function inRange(args, key, low, high) {
+    const value = args.get(key);
+    return value !== undefined && Number.isFinite(value) && value >= low && value <= high;
+}
 function parameters(text, flags = '') {
     const result = new Map();
     let rest = text.trim();
@@ -163,6 +230,7 @@ export async function inspectPrintFile(filePath, options) {
     const model = normalizeModel(options.model);
     if (!model)
         return fail(`unknown or missing printer model '${options.model}'`);
+    const dualNozzle = isDualNozzleModel(model);
     const plateIndex = options.plateIndex ?? 0;
     if (!Number.isInteger(plateIndex) || plateIndex < 0)
         return fail('selected plate index must be a nonnegative integer');
@@ -303,6 +371,24 @@ export async function inspectPrintFile(filePath, options) {
         const values = list(value);
         return values.length && values.every(v => !!normalizeMaterial(v)) ? values.map(v => normalizeMaterial(v)) : undefined;
     }, 'filament material');
+    // GCode.cpp uses 1-based filament_map logical extruders and then indexes
+    // physical_extruder_map to select the physical nozzle. Only this selected
+    // plate's headers establish that binding; unsliced project defaults do not.
+    const headerMap = (key, count, low, high) => {
+        const values = metadataValues(headers, [key]);
+        if (!values.length)
+            return undefined;
+        return consistent(values, value => {
+            const entries = list(value);
+            return entries.length === count && entries.every(v => NUMBER.test(v) && Number.isInteger(Number(v)) && Number(v) >= low && Number(v) <= high)
+                ? entries.map(Number) : undefined;
+        }, key.replace(/_/g, ' '));
+    };
+    const physicalExtruderMap = headerMap('physical_extruder_map', nozzleDiameters.length, 0, dualNozzle ? Math.min(nozzleDiameters.length, 2) - 1 : nozzleDiameters.length - 1);
+    if (physicalExtruderMap && new Set(physicalExtruderMap).size !== physicalExtruderMap.length)
+        fail('physical extruder map must be a complete permutation');
+    const filamentMap = headerMap('filament_map', materials.length, 1, nozzleDiameters.length);
+    const filamentNozzleIndices = filamentMap && physicalExtruderMap ? filamentMap.map(logical => physicalExtruderMap[logical - 1]) : undefined;
     const bedValues = metadataValues([...metadata, plate], ['curr_bed_type', 'bed_type']);
     const bedType = bedValues.length ? consistent(bedValues, normalizeBed, 'bed type') : undefined;
     if (options.bedType && (!bedType || normalizeBed(options.bedType) !== bedType))
@@ -365,17 +451,25 @@ export async function inspectPrintFile(filePath, options) {
             let line = stripComments(lines[index]);
             if (!line || line === '%')
                 continue;
-            // The official H2C template emits this literal separator without a semicolon.
+            // Accept only the exact vendor banners in their documented model/scope.
+            // X2D emits its filament-change banner throughout a print; H2C's record
+            // separator stays inside its explicitly bounded startup block.
+            if (line === '======== X2D filament_change gcode ==========' && model === 'x2d')
+                continue;
             if (line === '========== record data ==========' && h2cStartup(index))
                 continue;
             line = line.replace(/^N\d+\s*/i, '').replace(/\*\d+\s*$/, '');
             if (/[{}\[\]#]/.test(line))
                 fail('unresolved dynamic command syntax');
             if (/^SYNC(?=$|\s)/i.test(line)) {
-                // H2D change_filament_gcode emits SYNC T{ceil(flush_length / 125) * 5}.
-                // T is a synchronization duration here, not a nozzle temperature. The
-                // vendor template establishes no independent maximum duration.
+                // Vendor SYNC T is a duration, not a heater target. X2D and P2S
+                // startup templates additionally emit R0; no other R form is supported.
                 const args = parameters(line.slice(4));
+                if (args.has('R')) {
+                    if (!['x2d', 'p2s'].includes(model) || args.get('R') !== 0)
+                        fail('unsupported SYNC reset parameters');
+                    args.delete('R');
+                }
                 if (args.size !== 1 || !args.has('T') || !Number.isFinite(args.get('T')) || args.get('T') < 0)
                     fail('unsupported SYNC duration parameters');
                 commandCount++;
@@ -388,6 +482,33 @@ export async function inspectPrintFile(filePath, options) {
             const code = command[1].toUpperCase() + String(Number(base)) + (subcode === undefined ? '' : '.' + subcode);
             const argumentsText = line.slice(command[0].length).trim();
             commandCount++;
+            if (code === 'M9711') {
+                // Official X2D, H2D and H2C time-lapse capture (Bambu Studio and OrcaSlicer
+                // templates), emitted on every layer: M is the time-lapse mode and E the
+                // physical extruder, not a second command; T is a duration, not a heater.
+                // It sets no temperature. Positions stay inside the machine volume.
+                const invalid = () => fail('unsupported M9711 time-lapse parameters');
+                if (!['x2d', 'h2d', 'h2c'].includes(model))
+                    invalid();
+                let args;
+                try {
+                    args = parameters(argumentsText);
+                }
+                catch {
+                    return invalid();
+                }
+                const [width, depth, height] = MACHINE_LIMITS[model].volume;
+                const position = ['X', 'Y', 'U', 'V'].filter(key => args.has(key)).join('');
+                const limit = { X: width, U: width, Y: depth, V: depth };
+                if ([...args.keys()].some(key => !'MEXYUVZSCOT'.includes(key)) ||
+                    // These models have two physical extruders, whatever the file declares.
+                    ![0, 1].includes(args.get('M')) || !Number.isInteger(args.get('E')) || !inRange(args, 'E', 0, Math.min(nozzleDiameters.length, 2) - 1) ||
+                    args.get('S') !== 11 || args.get('C') !== 10 || args.get('O') !== 0 || !inRange(args, 'T', 0, 600000) ||
+                    !inRange(args, 'Z', 0, height) ||
+                    !['', 'XY', 'UV'].includes(position) || [...position].some(key => !inRange(args, key, 0, limit[key])))
+                    invalid();
+                continue;
+            }
             if (!['M117', 'M118', 'M1002', 'M1006', 'M900', 'M970', 'M983.1', 'G383'].includes(code) && /[GM]\s*\d/i.test(argumentsText))
                 fail('multiple commands on one line are unsupported');
             // Coordinated extrusion closes the startup-only allowance even when the
@@ -411,7 +532,15 @@ export async function inspectPrintFile(filePath, options) {
                 continue;
             }
             if (['M104', 'M109', 'M140', 'M190', 'M141', 'M191'].includes(code)) {
-                const args = parameters(argumentsText, 'A');
+                const args = parameters(argumentsText, code === 'M104' ? 'AM' : 'A');
+                // Studio 2.9's GCodeWriter marks layer-temperature changes with bare M.
+                // Accept only its exact S-target / optional T form; targets and tool
+                // selectors still pass through the independent thermal checks below.
+                if (args.has('M')) {
+                    if (!Number.isNaN(args.get('M')) || !args.has('S') || [...args.keys()].some(key => !'MST'.includes(key)))
+                        fail('unsupported M104 layer-change temperature parameters');
+                    args.delete('M');
+                }
                 // Official A1 and A1 mini start G-code waits with M109 S<target> H<limit>
                 // (S25 H140, S100 H170, S220 H300). H is not a heater target: S stays the
                 // checked target, so H is accepted only within those vendor bounds.
@@ -421,10 +550,7 @@ export async function inspectPrintFile(filePath, options) {
                     // editable maxima or an unchecked offset as thermal evidence.
                     if (code !== 'M104' || !h2cStartup(index) || args.size !== 2 || args.get('O') !== -80 || !Number.isNaN(args.get('A')))
                         fail('unsupported H2C startup offset parameters');
-                    const targets = consistent(metadataValues(metadata, ['nozzle_temperature_initial_layer']), value => {
-                        const values = list(value);
-                        return values.length === materials.length && values.every(v => NUMBER.test(v) && Number.isFinite(Number(v))) ? values.map(Number) : undefined;
-                    }, 'first-layer nozzle temperature');
+                    const targets = firstLayerTemperatures(project, headers, materials.length);
                     for (let position = 0; position < targets.length; position++) {
                         validateTemperature('nozzle', targets[position], model, [materials[position]]);
                         const preheat = Math.max(0, targets[position] - 80);
@@ -441,9 +567,16 @@ export async function inspectPrintFile(filePath, options) {
                     continue;
                 }
                 const vendorWait = code === 'M109' && ['a1', 'a1mini'].includes(model);
+                // Bambu Studio addresses a physical nozzle on dual-nozzle machines with N<index>
+                // (X2D `M104 T1 S25 N0` multi-extruder pre-cooling and wipe-tower reheats).
+                // N selects a nozzle, never a target, so it is accepted only on those models,
+                // only for nozzle heaters, and only within the declared nozzle count.
+                const nozzleIndex = ['M104', 'M109'].includes(code) && dualNozzle;
                 for (const key of args.keys())
-                    if (!'SRTA'.includes(key) && !(key === 'H' && vendorWait))
+                    if (!'SRTA'.includes(key) && !(key === 'H' && vendorWait) && !(key === 'N' && nozzleIndex))
                         fail(`unsupported ${code} temperature parameter ${key}`);
+                if (args.has('N') && (!Number.isInteger(args.get('N')) || args.get('N') < 0 || args.get('N') >= Math.min(nozzleDiameters.length, 2)))
+                    fail(`unsupported ${code} nozzle index N`);
                 if (args.has('H') && (!Number.isFinite(args.get('H')) || args.get('H') < 0 || args.get('H') > 300))
                     fail(`unsupported ${code} wait parameter H`);
                 if (!args.has('S') && !args.has('R'))
@@ -453,13 +586,13 @@ export async function inspectPrintFile(filePath, options) {
                 // Without a verified per-filament nozzle map, apply all possible materials.
                 if (args.has('T') && (!Number.isInteger(args.get('T')) || args.get('T') < 0 || args.get('T') >= nozzleDiameters.length))
                     fail('physical heater target has no declared nozzle');
-                const position = args.has('T') ? undefined : active;
+                const position = args.has('T') || args.has('N') ? undefined : active;
                 const commonFlush = code === 'M109' && args.size === 1 && args.get('S') === 290 && model === 'x1e' && !depositionStarted && !commonFlushUsed && boundedX1ePurge(lines, index);
                 if (commonFlush)
                     commonFlushUsed = true;
                 for (const key of ['S', 'R'])
                     if (args.has(key))
-                        heat(component, args.get(key), position, args.has('T') || args.has('A'), commonFlush);
+                        heat(component, args.get(key), position, args.has('T') || args.has('N') || args.has('A'), commonFlush);
             }
             else if (code === 'M620' || code === 'M621') {
                 const args = parameters(argumentsText, model === 'x2d' ? 'MAB' : model === 'h2c' ? 'MAN' : 'MA');
@@ -519,9 +652,10 @@ export async function inspectPrintFile(filePath, options) {
             }
             else if (code === 'M620.14') {
                 const args = parameters(argumentsText);
-                // H2C tower coordinates include the rear wipe area outside object bounds.
-                if (!h2cStartup(index) || args.size !== 2 || !['X', 'Y'].every(key => args.has(key) && Number.isFinite(args.get(key)) && args.get(key) >= 0 && args.get(key) <= 350))
-                    fail('unsupported H2C startup tower parameters');
+                // H2C uses these coordinates during startup and a selected filament change.
+                // The rear wipe area extends outside object bounds (official fallback Y336).
+                if (!(h2cStartup(index) || (model === 'h2c' && pending !== undefined)) || args.size !== 2 || !['X', 'Y'].every(key => args.has(key) && Number.isFinite(args.get(key)) && args.get(key) >= 0 && args.get(key) <= 350))
+                    fail('unsupported H2C tower parameters');
             }
             else if (model === 'h2c' && ['G383', 'G383.3', 'G383.7'].includes(code) && /U/i.test(argumentsText)) {
                 const args = parameters(argumentsText);
@@ -563,9 +697,12 @@ export async function inspectPrintFile(filePath, options) {
                 // H2D change_filament_gcode supplies the incoming filament's cooling
                 // temperature as C{new_filament_temp - filament_cooling_before_tower}.
                 const args = parameters(argumentsText);
-                if (args.size !== 1 || !args.has('C'))
+                // H2C also supplies P{filament_pre_cooling_temperature_nc[next_filament_id]}
+                // before switching hotends. P and C both constrain the incoming material.
+                const target = model === 'h2c' && args.has('P') ? 'P' : 'C';
+                if (args.size !== 1 || !args.has(target))
                     fail('unsupported M620.15 cooling temperature parameters');
-                heat('nozzle', args.get('C'), pending ?? active);
+                heat('nozzle', args.get(target), pending ?? active);
             }
             else if (code === 'M620.17') {
                 const args = parameters(argumentsText);
@@ -620,5 +757,5 @@ export async function inspectPrintFile(filePath, options) {
         return fail('selected G-code contains no printable commands');
     if (!used.size)
         materials.forEach((_, index) => used.add(index));
-    return { model, nozzleDiameters, materials, usedFilamentPositions: [...used].sort((a, b) => a - b), plateInternalPath, sha256, maxNozzleTemperature, maxBedTemperature, maxChamberTemperature, bedType, selectsAms, nozzleTypes, nozzleFlows };
+    return { model, nozzleDiameters, materials, usedFilamentPositions: [...used].sort((a, b) => a - b), plateInternalPath, sha256, maxNozzleTemperature, maxBedTemperature, maxChamberTemperature, bedType, selectsAms, nozzleTypes, nozzleFlows, filamentNozzleIndices, ...(Array.isArray(project.filament_type) ? { projectFilaments: projectFilaments(project) } : {}) };
 }

package/dist/safety/printer-state.d.ts

@@ -1,12 +1,5 @@
 import type { BambuClient } from "bambu-node";
-/**
- * Publish one MQTT command with a string sequence id and no ACK wait.
- * Unpatched bambu-node 3.22.21 command classes send numeric sequence ids;
- * bambu-printer-mcp patches them to strings for H2-series firmware. This
- * server does not install that patch, so safety-relevant commands are
- * published here with the patched wire shape: {category:{sequence_id,command,...}}.
- */
-export declare function publishBambuCommand(printer: Pick<BambuClient, "publish">, category: "print" | "pushing" | "info", command: string, extra?: Record<string, unknown>): Promise<void>;
+export declare const SERIAL_MODELS: Record<string, string>;
 /** Only raw reports received after this request are evidence. Never read printer.data here. */
 export declare function readFreshPrinterStatus(printer: BambuClient, serial: string, timeoutMs?: number): Promise<any>;
 export interface PrinterStateRequirements {
@@ -14,6 +7,8 @@ export interface PrinterStateRequirements {
     nozzleDiameters: number[];
     materials?: string[];
     usedFilamentPositions?: number[];
+    /** Verified physical nozzle index for each project filament, composed from the inspected plate mappings. */
+    filamentNozzleIndices?: number[];
     amsMapping?: number[];
     useAMS?: boolean;
     requireIdle?: boolean;
@@ -44,10 +39,66 @@ export interface ValidatedPrinterState {
     reportedNozzles: ReportedNozzle[];
     filaments: ReportedFilament[];
 }
+export declare function finiteNumber(value: unknown): number | undefined;
+/**
+ * X2D retains FAILED after a canceled job even with no active print error.
+ * Bambu Studio classifies FAILED as a finished job; its v02.08.02.61
+ * hms_en_20P table (926a7192574bcb9b3a732e1ec59a46d79cb45466)
+ * calls 0300400C "The task was canceled."
+ * Only this observed terminal condition qualifies, never an arbitrary failure.
+ * Callers still validate HMS, identity, hardware and material configuration,
+ * and print dispatch rechecks the identity of the observed job.
+ */
+export declare function isCancelledX2DJob(raw: Record<string, any>, model: string): boolean;
+/** Bambu Studio 2.8.2.61 marks FAILED as finished. Limit P1S recovery to
+ * a named prior job explicitly reporting idle, no print error and no HMS.
+ * Dispatch rechecks the observed job identity. */
+export declare function isFinishedP1SJob(raw: Record<string, any>, model: string): boolean;
 /** Nozzles whose reported diameter and type are configured settings rather than chip readings. */
 export declare function unchippedNozzles(raw: unknown): number[];
+export type HmsEntry = {
+    attr: number;
+    code: number;
+    severity: number;
+    hex: string;
+};
+export declare function hmsCode(entry: any): HmsEntry | undefined;
+/** The one key format for a reported entry, shared by the gate and clear_hms_errors. */
+export declare function reportedHmsKey(entry: unknown): string;
+/** Bambu's display form of a cleared-code key such as "hms:83887616:131184"; other keys unchanged. */
+export declare function describeHmsKey(key: string): string;
+/**
+ * A serious or common entry that Bambu lists for this serial prefix with empty
+ * text: Bambu Studio, Bambu Handy and the printer screen never show it, and
+ * the printer keeps printing with it (an X2D raises 0500-0600-0002-0070 at
+ * every boot). Bambu Studio selects the table by serial prefix, so this does
+ * too, but only when that prefix belongs to the verified model: a sparse report
+ * without a serial must not let a misconfigured serial pick another model's
+ * table. Fatal, invalid-level and unlisted entries never qualify.
+ */
+export declare function isHiddenNotice(serial: string, model: string, entry: HmsEntry): boolean;
+/** Labels of reported entries that pass only because Bambu hides them for this printer. */
+export declare function hiddenHmsNotices(raw: unknown, serial: string, model: string): string[];
+/** Cleared-code keys of reported hidden entries; clearing never removes them, so they are not re-acknowledged. */
+export declare function hiddenHmsKeys(raw: unknown, serial: string, model: string): string[];
 /** Verifies reported configuration, not a physical nozzle/spool inspection. */
 export declare function validatePrinterState(status: any, requirements: PrinterStateRequirements): ValidatedPrinterState;
 /** Manual M104 cannot remap filament slots. Validate the material already at the nozzle. */
 export declare function manualHeatingRequirements(status: any, model: string, nozzleDiameter: number, material: string): PrinterStateRequirements;
+export type ExternalStorageState = "none" | "normal" | "abnormal" | "readonly";
+/**
+ * The SD card or USB stick state, read as Bambu Studio does: the `sdcard`
+ * flag, then `home_flag` bits 8-9, then on firmware that reports cfg/fun/aux/stat
+ * the `aux` bits 12-13, each later source overriding the earlier one
+ * (DevStorage.cpp, DeviceManager.cpp parse_home_flag and parse_new_info).
+ */
+export declare function externalStorageState(raw: unknown): ExternalStorageState;
+/**
+ * Publish one MQTT command with a string sequence id and no ACK wait.
+ * Unpatched bambu-node 3.22.21 command classes send numeric sequence ids;
+ * bambu-printer-mcp patches them to strings for H2-series firmware. This
+ * server does not install that patch, so safety-relevant commands are
+ * published here with the patched wire shape: {category:{sequence_id,command,...}}.
+ */
+export declare function publishBambuCommand(printer: Pick<BambuClient, "publish">, category: "print" | "pushing" | "info", command: string, extra?: Record<string, unknown>): Promise<void>;
 export {};