bambu-printer-mcp 1.1.26 → 1.1.28

package/CONTRIBUTORS.md

@@ -6,6 +6,9 @@ Thank you to everyone who builds, tests, reports problems, and shares real print
 
 | Contributor | Contribution |
 | --- | --- |
+| [mygrexit](https://github.com/mygrexit) | Contributes pinned x86-64 Linux X2D native setup, emergency routing and one-shot cleanup in [#56](https://github.com/DMontgomery40/bambu-printer-mcp/pull/56), checked Orca/time-lapse G-code forms in [#57](https://github.com/DMontgomery40/bambu-printer-mcp/pull/57), and model-specific hidden-HMS notices in [#58](https://github.com/DMontgomery40/bambu-printer-mcp/pull/58). Supplies regressions, review corrections, and contributor-reported Debian/X2D read-only, heater-off and print-start evidence in [#55](https://github.com/DMontgomery40/bambu-printer-mcp/issues/55); maintainer validation is offline and mocked. |
+| [patrikmadoran-cyber](https://github.com/patrikmadoran-cyber) | Adds explicit Standard/High Flow nozzle selection across slicing and print auto-slicing in [#54](https://github.com/DMontgomery40/bambu-printer-mcp/pull/54), with unsupported-variant regressions and real Windows BambuStudio 02.06.00.51 H2S 0.6 slicing evidence. No physical print is claimed. |
+| [Patrick Juchli (@patrickjuchli)](https://github.com/patrickjuchli) | Maintains basic-ftp and supplies the 6.2.3 fixes for rejected-command recovery, asynchronous credential-error crashes, and password redaction used by direct FTPS transfers. |
 | [Aleksei Popovich (alexpapay)](https://github.com/alexpapay) | Fixes cross-platform AMS profile resolution and packed P2S chamber status in [#43](https://github.com/DMontgomery40/bambu-printer-mcp/pull/43), contributes regressions, and supplies read-only Windows P2S/AMS 2 Pro status and local slicing evidence. No physical print is claimed for this contribution. |
 | [Adam (@adamkaplan)](https://github.com/adamkaplan) | Identifies the reversed H2C/H2D Pro serial prefixes in [#47](https://github.com/DMontgomery40/bambu-printer-mcp/issues/47), verifies corrected H2C status locally, and isolates the official H2C startup commands and config-block marker failure in [#48](https://github.com/DMontgomery40/bambu-printer-mcp/issues/48). Provides exact Bambu Studio version/template hash and unsafe-file reproductions; maintainer validation is offline and mocked. |
 | [travismcashan](https://github.com/travismcashan) | Reports stock X2D material-switch and runout-purge rejection, misleading unchecked confirmation, and stdout diagnostics in [#44](https://github.com/DMontgomery40/bambu-printer-mcp/issues/44). Supplies exact preset syntax and firmware evidence, then reports a clean physical X2D cube print with a local workaround; maintainer validation remains isolated and mocked. Reports the accepted native job and subsequent helper teardown crash in [#46](https://github.com/DMontgomery40/bambu-printer-mcp/issues/46), with completed-print and macOS crash evidence informing result preservation and duplicate-print warnings. |
@@ -13,6 +16,7 @@ Thank you to everyone who builds, tests, reports problems, and shares real print
 | [Steavie (steavie)](https://github.com/steavie) | Reports the reversed A1/A1 mini serial prefixes in [#39](https://github.com/DMontgomery40/bambu-printer-mcp/issues/39), with A1 status and configuration evidence that identifies the status and fresh-identity regression. |
 | [JaviOFC](https://github.com/JaviOFC) | Reports the X2D identity rejection in [#36](https://github.com/DMontgomery40/bambu-printer-mcp/issues/36) and supplies current firmware, connection-mode, status-field, serial-prefix, and cloud-job evidence showing that `model_id` can contain a print-job identifier while `model` correctly identifies the printer. |
 | [Izzy Mansurov (sapoepsilon)](https://github.com/sapoepsilon) | Fixes Bambu Studio 02.08 P2S extruder-variant metadata and airduct-command inspection in [#33](https://github.com/DMontgomery40/bambu-printer-mcp/pull/33). Supplies regression tests and offline inspection evidence from four real P2S 0.6 mm PLA/PETG jobs and unsafe mutated copies; this contribution does not claim a physical print. |
+| [Bambuddy](https://github.com/maziggy/bambuddy) contributors | Document that Bambu lists some `hms[]` codes with empty text and never shows them, with P2S evidence for `0500-0600-0002-0070` and H2C evidence for `-0005` and `-0006` in [#2728](https://github.com/maziggy/bambuddy/issues/2728) and [#1840](https://github.com/maziggy/bambuddy/issues/1840); this informs the hidden-HMS notice handling. |
 | [Boardy (@boardyai)](https://x.com/boardyai) | Raises the nozzle-verification question that informs the added printer safety checks. |
 | Fable red-team review, shared by David Montgomery | Supplies archive-ambiguity reproductions and hardware-safety review findings used for plate binding, upload checks, temperature policy, and human preflight. Network/security suggestions remain outside this hardware-safety release. |
 | [Sebastian (sebas1986)](https://github.com/sebas1986) | Isolates the multi-filament CLI crash with real BambuStudio bisection, contributes per-slot colours and multi-nozzle prime-tower placement, and verifies X2D identification, status, and slicing in [#18](https://github.com/DMontgomery40/bambu-printer-mcp/pull/18). Also isolates FTPS session-host identity and supplies physical X2D USB upload/size/deletion evidence in [#24](https://github.com/DMontgomery40/bambu-printer-mcp/pull/24); that test does not establish MQTT print dispatch. |

package/README.md

@@ -49,7 +49,7 @@ an existing slicer before suggesting an install. For FULU/Orca CLI auto-slicing,
 require MCP 1.1.11+ and its matching installed profile tree (see guide).
 A slicer is not needed here to print a pre-sliced file. Configure the optional FULU
 BambuNetwork bridge only if I choose it, and explain its runtime/auth needs.
-X2D supports status and slicing; native printing requires macOS and a locally built helper.
+X2D supports status and slicing; native printing requires macOS or x86-64 Linux and a locally built helper.
 
 If this harness does not already provide code mode or an equivalent, suggest
 a compatible code-mode integration as an optional addition. It is not required;
@@ -196,7 +196,7 @@ The optional FULU **BambuNetwork bridge** exposes `bambu_network_bridge_status`,
 - Capture a JPEG snapshot from the chamber camera. Supports A1, A1 mini, P1S, P1P (TCP-on-6000), and X1, X1C, X1E, P2S, H2, H2S, H2D, H2C, H2D Pro, X2D (RTSP via ffmpeg). Requires ffmpeg in PATH for the RTSP path.
 - Upload and print pre-sliced `.3mf` projects with checked plate selection and calibration flags. Legacy `.gcode.3mf` routes require a single external-spool-only plate; see the [slicing guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md).
 - Slice through BambuStudio CLI with automatic BBL inheritance/include resolution, per-slot filament colours, and fallback prime-tower placement for multi-nozzle printers. Missing dependencies stop the slice; custom settings and saved project tower positions are preserved. Multi-colour slicing is verified by the contributor on BambuStudio 02.08.02.60 for Windows; older CLI versions have separate limitations. See [slicing guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md).
-- Recognize X2D status and slice with its own installed BambuStudio preset (`BAMBU_MODEL=x2d`). On macOS, `print_3mf` selects the native eMMC route after resolving the model, including an elicited model. Install the optional helper as described below; Linux/Windows native print requests fail before slicing or contacting the printer. Legacy FTPS and remote G-code starts remain unsupported for X2D.
+- Recognize X2D status and slice with its own installed BambuStudio preset (`BAMBU_MODEL=x2d`). On macOS and x86-64 Linux, `print_3mf` selects the native eMMC route after resolving the model, including an elicited model. Install the optional helper as described below; Windows native print requests, and Linux requests without the helper, fail before slicing or contacting the printer. Legacy FTPS and remote G-code starts remain unsupported for X2D.
 - Parse AMS mapping from the 3MF's embedded slicer metadata (`Metadata/plate_<n>.json` + gcode filament header) and send it correctly formatted per the OpenBambuAPI spec, with correct H2S/H2D/H2C `ams_mapping2` parallel array format
 - **Auto-match AMS slots by RFID** (`auto_match_ams` flag on `print_3mf`). Resolves required `tray_info_idx` from the sliced 3MF against live AMS inventory. Handles same-SKU different-color filaments by matching on `(tray_info_idx, tray_color)` and tracking already-claimed slots. Dry-run with `resolve_3mf_ams_slots` before printing.
 - Cancel, pause, and resume in-progress print jobs via MQTT
@@ -878,6 +878,24 @@ To stop drying:
 }
 ```
 
+#### inspect_print_file
+
+Inspect a prepared sliced 3MF or textual G-code file offline before deciding what to export or print. This tool copies the file into a private read-only snapshot and reuses the same archive, selected-plate, model/nozzle/material and temperature checks used by print preflight. It never contacts a printer or auto-slices an unsliced project.
+
+```json
+{
+  "file_path": "/path/to/bracket.gcode.3mf",
+  "bambu_model": "p1s",
+  "plate_index": 0,
+  "nozzle_diameters": [0.4],
+  "bed_type": "textured_plate"
+}
+```
+
+`file_path` and explicit `bambu_model` are required; the model is never inferred from configuration. `plate_index` is zero-based and defaults to 0. Nozzle/bed checks are optional comparisons against file declarations, not observations of installed hardware. Only these five argument names are accepted; credentials, host and executable/bridge overrides are not part of this tool.
+
+The generic result has `receipt_version: "1"`, `evidence: "file-only"`, `dispatch_authorized: false`, `artifact` (`sha256`, `byte_length`, `file_format`), the requested `selection`, and the original `inspection` including declared model, nozzles, materials/used filament positions, internal plate path and checked temperature peaks. Hash and byte length identify the exact inspected snapshot; a consumer must compare them with its own artifact and selected plate. The temporary snapshot is removed, and its path is not a dispatch capability. The receipt does not prove printer readiness, physical material/nozzle contents, fit, full motion simulation or permission to print. Actual print routes still independently inspect the dispatched snapshot and require fresh hardware state and human preflight.
+
 #### print_3mf
 
 The primary tool for starting a Bambu print. **Recommended input: a pre-sliced `.gcode.3mf` exported from FULU OrcaSlicer-bambulab, OrcaSlicer, or Bambu Studio** — see [slicing guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md). This tool handles the complete workflow:
@@ -886,7 +904,7 @@ The primary tool for starting a Bambu print. **Recommended input: a pre-sliced `
 2. If no G-code is found, attempts to auto-slice via the configured slicer. Profile preparation or slicing failures stop the operation before upload. See the slicing guide for tested CLI versions and combinations.
 3. Parses the sliced 3MF to extract the correct plate file and compute its MD5 hash.
 4. Reads slicer metadata and any explicit AMS selection to build the filament mapping.
-5. Uploads via `basic-ftp` to the model-specific location: SD root for H2/full-size A1, `cache/` for P1/X1/A1 mini/P2S. X2D `print_3mf` instead uses its checked native eMMC route on macOS.
+5. Uploads via `basic-ftp` to the model-specific location: SD root for H2/full-size A1, `cache/` for P1/X1/A1 mini/P2S. X2D `print_3mf` instead uses its checked native eMMC route on macOS or Linux.
 6. Sends the correct MQTT print command for the target printer family. For H2S/H2D/H2C that means `project_file` with project-length `ams_mapping`, parallel `ams_mapping2`, and H2-compatible calibration flags.
 
 ```json
@@ -908,7 +926,7 @@ The primary tool for starting a Bambu print. **Recommended input: a pre-sliced `
 
 `bambu_model` is **required** for model-specific routing and preset selection. It does not by itself validate pre-sliced G-code. BambuStudio, FULU, and Orca CLI preparation additionally require the exact model/nozzle machine preset and reject incomplete profiles. Using the wrong model can damage hardware. If `bambu_model` is not provided in the tool call and `BAMBU_MODEL` is not set in the environment, the server will ask you interactively via MCP elicitation (if your client supports it) or return a clear error.
 
-`bed_type` defaults to `textured_plate` if omitted. `nozzle_type` (`stainless_steel`, `hardened_steel`, `tungsten_carbide`, `brass`; default `BAMBU_NOZZLE_TYPE`) sets the installed nozzle when the project must be auto-sliced; the job's nozzle type must match the printer's report, and stock P1S/P1P/A1 presets assume stainless steel. After an MQTT print command the server listens to the printer's pushed reports for up to 15 seconds (`BAMBU_DISPATCH_CHECK_MS`) and returns `dispatch: "started"` or `"unconfirmed"`; if firmware 01.08.05+ refuses the command (HMS 0500-0500-0001-0007, needs LAN Only Mode and Developer Mode), the call fails and says so; clear that fatal HMS entry with `clear_hms_errors` before printing again. `ams_slots` is the preferred override input; `ams_mapping` remains the raw escape hatch. On AMS-equipped H2 printers, `use_ams: false` does not suppress mapping lookup if the sliced file declares filaments. If no mapping is provided for an H2 pre-sliced job with declared filaments, the server fails before sending; pass explicit `ams_slots`, raw `ams_mapping`, or `auto_match_ams: true`.
+`bed_type` defaults to `textured_plate` if omitted. `nozzle_type` (`stainless_steel`, `hardened_steel`, `tungsten_carbide`, `brass`; default `BAMBU_NOZZLE_TYPE`) sets the installed nozzle when the project must be auto-sliced; the job's nozzle type must match the printer's report, and stock P1S/P1P/A1 presets assume stainless steel. `nozzle_volume_type` (`standard`, `high_flow`; default `BAMBU_NOZZLE_VOLUME_TYPE`) likewise sets the installed nozzle's flow type for auto-slicing; it must match the printer's reported nozzle flow. After an MQTT print command the server listens to the printer's pushed reports for up to 15 seconds (`BAMBU_DISPATCH_CHECK_MS`) and returns `dispatch: "started"` or `"unconfirmed"`; if firmware 01.08.05+ refuses the command (HMS 0500-0500-0001-0007, needs LAN Only Mode and Developer Mode), the call fails and says so; clear that fatal HMS entry with `clear_hms_errors` before printing again. `ams_slots` is the preferred override input; `ams_mapping` remains the raw escape hatch. On AMS-equipped H2 printers, `use_ams: false` does not suppress mapping lookup if the sliced file declares filaments. If no mapping is provided for an H2 pre-sliced job with declared filaments, the server fails before sending; pass explicit `ams_slots`, raw `ams_mapping`, or `auto_match_ams: true`.
 
 Set `auto_match_ams: true` to match the sliced 3MF's `tray_info_idx` values against the live AMS inventory and use the matching `ams_slots`. The matcher joins on `(tray_info_idx, tray_color)` and tracks already-claimed slots, so prints with two filaments of the same SKU but different colors (e.g. two GFG02 PETG HF in black and white) resolve correctly. Falls back to SKU-only when the 3MF's filament has no color set or only one tray of that SKU is loaded. Returns a structured `missing` report (`reason: "no_loaded_match" | "color_mismatch" | "exhausted" | "no_sku"`) when a filament can't be resolved. Ignored when you provide `ams_slots` or `ams_mapping` explicitly.
 
@@ -926,14 +944,28 @@ Call an allowed read-only probe such as `{"method": "net.is_user_login", "payloa
 
 #### X2D native transport (macOS)
 
-Install Bambu Studio and its networking plug-in, plus the Apple command-line developer tools (`clang++`). The plug-in is loaded at runtime and is not redistributed. In the installed `bambu-printer-mcp` package directory, run `npm run build:native`. For a global install, locate that directory with `npm root -g`; for an extracted desktop extension, run the same command in the extension directory. Rebuild after updating the package. Linux and Windows can still use status and slicing, but this native helper supports macOS only.
+Install Bambu Studio and its networking plug-in, plus the Apple command-line developer tools (`clang++`). The plug-in is loaded at runtime and is not redistributed. In the installed `bambu-printer-mcp` package directory, run `npm run build:native`. For a global install, locate that directory with `npm root -g`; for an extracted desktop extension, run the same command in the extension directory. Rebuild after updating the package. For Linux, see [X2D native transport (Linux)](#x2d-native-transport-linux); Windows can use status and slicing only.
 
-The npm package and desktop bundle include `native/bambu-native-print.cpp` and `scripts/build-bambu-native.zsh`, never a developer's compiled binary. The server finds the built helper relative to its installed package, regardless of the launch directory. A trusted server setting `BAMBU_NATIVE_HELPER` can select an alternate executable.
+The npm package and desktop bundle include `native/bambu-native-print.cpp`, `scripts/build-bambu-native.sh` and the Linux setup script, never a developer's compiled binary. The server finds the built helper relative to its installed package, regardless of the launch directory. A trusted server setting `BAMBU_NATIVE_HELPER` can select an alternate executable.
 
 For X2D, `print_3mf` defaults to `connection_mode: "bambu_native"`; legacy `lan_mqtt_ftps` requests are redirected to it. Supply `ams_slots`, a complete project-level `ams_mapping`, or `auto_match_ams: true`. An external-spool job requires explicit `use_ams: false`. Raw `ams_mapping2` and nozzle/extra-option overrides are rejected before dispatch; the server derives both AMS representations from the checked structured mapping. Model/nozzle/material inspection, fresh printer-state checks, and human preflight apply before the helper receives a private snapshot. The native helper requests fresh shared printer-state authorization immediately before each print submission, including a certificate retry, and before checked heating, resume, or error-clearing commands; custom helpers must support this handshake. Stop and heater-off remain available without preflight. Native upload-only requests use the same all-plate inspection as FTPS uploads. They accept `project_name`, `preset_name`, `bed_type`, and an existing `plate_index`; AMS, nozzle, and calibration print options are rejected. Use `print_3mf` for checked print settings.
 
 The helper waits for connection/certificate exchange and retries only the initial `-4030` send once. Rebuild the helper after upgrading to receive the teardown fix. A successful dispatch receipt ends the helper before plug-in cleanup can turn an accepted job into an error. If an older/custom helper crashes after dispatch, the server reports uncertainty: check the printer state and job name before retrying, because resending can duplicate a print. Previous hardware testing reached `RUNNING` on X2D; this revision is validated with mocked transport regressions and clean installs, not a new physical print. `bambu_connect` is an optional macOS handoff for user review in Bambu Connect and does not start a print. Native task, heater, and error controls retain the common safety checks; raw controls cannot bypass them. Request cancellation, stop, and heater-off interrupt pending native helpers; the server waits for process exit before releasing a checked file. A command already sent to the printer cannot be recalled by cancelling the request, so verify printer state before retrying.
 
+#### X2D native transport (Linux)
+
+On x86-64 Linux, one command builds the helper and installs Bambu's networking plug-in and the Bambu Studio certificates. It needs a C++ compiler (`g++` or `clang++`) and network access; no desktop or slicer is required:
+
+```bash
+npx -y -p bambu-printer-mcp bambu-printer-mcp-native-setup
+```
+
+Use the same package version as the server, for example `bambu-printer-mcp@1.2.3`; when the installation is missing or stale, the server's error names the exact command. The setup downloads the Linux plug-in that Bambu Studio itself installs, pinned to an exact version and SHA-256, and stores it with the certificates under `~/.config/bambu-printer-mcp/bambu-native` (`BAMBU_NATIVE_HOME` or `XDG_CONFIG_HOME` move it; set the same value for the server). The plug-in is not redistributed by this package, and Bambu Studio's own auto-updating copy is never used. The server finds the installation automatically and passes the plug-in and certificate paths to the helper. Rerun the setup with the server's package version after upgrading: the server refuses a helper built from another version. Only missing or changed files are downloaded again. The setup then loads the plug-in once, offline, so missing system libraries are reported during installation rather than on a stop command. `--verify` repeats these checks without network access. On Linux the server uses only this managed helper or `BAMBU_NATIVE_HELPER`; a package-local `npm run build:native` binary is not used.
+
+`--check-update` asks Bambu's plug-in service for the newest Linux plug-in and compares the `PrintParams` layout in the matching Bambu Studio header with the helper. It reports only: the setup never installs an unpinned plug-in, because a changed layout would send wrong print parameters. A pin is raised by a package release after the check passes and a hardware test.
+
+Once the helper, plug-in and certificates are installed, X2D printing, upload and controls use the same routing, safety checks and authorization handshake described for macOS above. On Linux, stop and heater-off go out over the native route and MQTT at the same time, so a stuck helper cannot delay them. MQTT is sent again once every older print or heating helper for that printer has exited, so none can dispatch after it; either the native route or that later MQTT send succeeding counts, and the result lists all sends under `routes`. A repeated stop or heater-off is harmless. macOS keeps its native-only route. The server accepts only the pinned plug-in checksums; `BAMBU_NATIVE_ALLOW_UNPINNED_PLUGIN=1` is a trusted override for testing another build at your own risk. Without a complete installation, Linux keeps its previous behavior: X2D status and slicing work, stop, pause and heater-off use MQTT, and native print requests name the setup command before contacting the printer. Bambu publishes the Linux plug-in for x86-64 only; other architectures keep the MQTT behavior.
+
 #### x2d_native_control
 
 This optional X2D metadata tool accepts `ams_filament_setting` and `extrusion_cali_sel`, plus the read-only queries `extrusion_cali_get`, `extrusion_cali_get_result`, and `flowrate_get_result`. It validates command fields, numeric metadata, and AMS unit/slot selection. Motion, filament loading, heating, safety-setting changes, and task control are not exposed through raw JSON; use the dedicated checked tools where available. A metadata declaration does not verify the physical spool contents.
@@ -1102,6 +1134,7 @@ When `slicer_type` is `bambustudio` (the default), these additional parameters a
 | `skip_objects` | string | Object indices to skip, comma-separated (e.g. `"3,5,10"`) |
 | `load_filaments` | string | Filament profile paths, semicolon-separated |
 | `load_filament_ids` | string | Filament-to-object mapping, comma-separated |
+| `nozzle_volume_type` | string | Installed nozzle flow type: `standard` or `high_flow` (default: `BAMBU_NOZZLE_VOLUME_TYPE`, else the preset's Standard default). `high_flow` uses the presets' High Flow values, such as the filament's High Flow max volumetric speed, and is refused if the machine preset declares no High Flow variant. Also on `slice_with_template`. |
 | `filament_colours` | string | Slot colours, one `#RRGGBB` per filament slot, semicolon-separated. Explicit values take priority, followed by input 3MF colours, each custom profile's colour, then the BambuStudio default. |
 | `enable_timelapse` | boolean | Enable timelapse-aware slicing |
 | `allow_mix_temp` | boolean | Allow mixed-temperature filaments on one plate |
@@ -1246,9 +1279,11 @@ Understanding these constraints will help you avoid frustrating errors and set a
 
 5. **Status and command submission are separate evidence.** Local MQTT connections are reused and status is read from received printer reports. Reports can lag during startup, sleep, or state transitions. Inspect HMS errors and the printer's actual state after submitting a job; a tool's success response is not physical-print confirmation.
 
-6. **Network requirements depend on the path.** Direct MQTT/FTPS tools require local reachability and compatible LAN/Developer Mode settings. FULU bridge cloud jobs use BambuNetwork and require its runtime, internet access, and authentication. Standard status, camera, file, and control tools remain local; bridge printing does not turn them into cloud tools.
+6. **Only hidden or informational HMS entries let an operation proceed.** Fatal, serious and common HMS entries block printing, heating and resume. The exceptions are info-level entries and serious or common entries that Bambu lists for the exact printer model with empty text: the printer screen, Bambu Studio and Bambu Handy never show those, and the printer keeps printing with them. An X2D, for example, raises the hidden camera code `HMS 0500-0600-0002-0070` at every boot. The list comes from the bundled HMS tables of a pinned Bambu Studio commit (`scripts/generate-hidden-hms.mjs`), selected by the printer's serial prefix as Bambu Studio does, and covers X2D, P2S, H2D, H2D Pro, H2S and H2C. Each model's own table decides: `0500-0600-0002-0070` is hidden in the X2D table, but the P2S table does not list it, so it still blocks a P2S. If Bambu later publishes text for a listed code, the gate keeps passing it until the list is regenerated from a newer Studio release. The print preflight names any hidden entry it passes, and the first check that passes each one logs it on stderr, so headless runs still record it. `clear_hms_errors` leaves hidden entries alone. Unlisted codes and other models' tables never qualify.
+
+7. **Network requirements depend on the path.** Direct MQTT/FTPS tools require local reachability and compatible LAN/Developer Mode settings. FULU bridge cloud jobs use BambuNetwork and require its runtime, internet access, and authentication. Standard status, camera, file, and control tools remain local; bridge printing does not turn them into cloud tools.
 
-7. **Self-signed TLS certificate.** The printer's FTPS server uses a self-signed certificate. The `basic-ftp` client is configured with `rejectUnauthorized: false` to accept it. This is standard for local network Bambu connections but assumes a trusted local network environment.
+8. **Self-signed TLS certificate.** The printer's FTPS server uses a self-signed certificate. The `basic-ftp` client is configured with `rejectUnauthorized: false` to accept it. This is standard for local network Bambu connections but assumes a trusted local network environment.
 
 </details>
 

package/dist/bambu-native.d.ts

@@ -49,7 +49,62 @@ export type BambuNativeTemperatureCommand = {
     temperature: number;
     messageJson: string;
 };
+/**
+ * Hosts for which the native helper and Bambu's networking plug-in exist.
+ * Bambu publishes its Linux plug-in for x86-64 only.
+ */
+export declare function isBambuNativePlatform(platform?: NodeJS.Platform, arch?: string): boolean;
+/**
+ * Private directory used by `bambu-printer-mcp-native-setup` on Linux. Mirrors
+ * nativeHomeDir() in native/bambu-native-print.cpp: empty values count as unset.
+ */
+export declare function bambuNativeHomeDir(env?: NodeJS.ProcessEnv): string;
+export declare const BAMBU_NATIVE_CERTIFICATES: readonly ["slicer_base64.cer", "printer.cer"];
+/**
+ * The networking plug-in followed by the library it loads from its own
+ * directory for the eMMC file tunnel; without it uploads fail with -4.
+ */
+export declare const BAMBU_NATIVE_PLUGIN_LIBRARIES: readonly ["libbambu_networking.so", "libBambuSource.so"];
+/**
+ * The only Linux plug-in build whose PrintParams layout matches the helper
+ * (Bambu Studio v02.08.02.61, network agent 02.08.02.54). The setup installs
+ * exactly these files and the server refuses anything else.
+ */
+export declare const BAMBU_NATIVE_PINNED_PLUGIN: Readonly<{
+    version: "02.08.02.54";
+    sha256: Readonly<Record<"libbambu_networking.so" | "libBambuSource.so", string>>;
+}>;
+/** Layout shared by the Linux setup script, the server and the helper's environment. */
+export declare function bambuNativeManagedPaths(env?: NodeJS.ProcessEnv): {
+    home: string;
+    helper: string;
+    plugin: string;
+    certDir: string;
+    configDir: string;
+    receipt: string;
+};
+export declare const BAMBU_NATIVE_SOURCE: string;
+export declare function sha256Hex(data: Buffer | string): string;
+export declare function sha256File(file: string): string;
+/**
+ * Name the setup from this server's own version, whose helper source it
+ * accepts, and its own install directory when that is not the default.
+ */
+export declare function bambuNativeSetupCommand(version?: string, env?: NodeJS.ProcessEnv): string;
 export declare function assertBambuNativeAvailable(): void;
+/**
+ * True when X2D controls should use the native route. macOS keeps its
+ * unconditional routing. Linux opts in only with a complete installation, so
+ * stop, pause and heater-off keep their MQTT route otherwise.
+ */
+export declare function bambuNativeControlsAvailable(): boolean;
+/** Why native X2D controls are not used on this host, or undefined when they are. */
+export declare function bambuNativeUnavailableReason(): string | undefined;
+/**
+ * Interrupt this printer's pending print, upload and heating helpers and
+ * resolve once they have exited, so none can still dispatch afterwards.
+ */
+export declare function interruptNativeOperations(serial: string): Promise<void>;
 export declare function buildBambuNativeFanCommand(fan: string | number, speed: number, sequenceId?: string): BambuNativeFanCommand;
 export declare function buildBambuNativeTemperatureCommand(component: string, temperature: number, sequenceId?: string): BambuNativeTemperatureCommand;
 export declare function validateBambuNativeControlMessage(messageJson: string): {

package/dist/bambu-native.js

@@ -1,32 +1,228 @@
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 function firstExistingExecutable(candidates) {
     return candidates.find((candidate) => {
         try {
-            return fs.statSync(candidate).isFile() && (fs.statSync(candidate).mode & 0o111) !== 0;
+            const stat = fs.statSync(candidate);
+            return stat.isFile() && (stat.mode & 0o111) !== 0;
         }
         catch {
             return false;
         }
     });
 }
+/**
+ * Hosts for which the native helper and Bambu's networking plug-in exist.
+ * Bambu publishes its Linux plug-in for x86-64 only.
+ */
+export function isBambuNativePlatform(platform = process.platform, arch = process.arch) {
+    return platform === "darwin" || (platform === "linux" && arch === "x64");
+}
+/**
+ * Private directory used by `bambu-printer-mcp-native-setup` on Linux. Mirrors
+ * nativeHomeDir() in native/bambu-native-print.cpp: empty values count as unset.
+ */
+export function bambuNativeHomeDir(env = process.env) {
+    if (env.BAMBU_NATIVE_HOME)
+        return env.BAMBU_NATIVE_HOME;
+    const configHome = env.XDG_CONFIG_HOME || path.join(env.HOME || os.homedir(), ".config");
+    return path.join(configHome, "bambu-printer-mcp", "bambu-native");
+}
+export const BAMBU_NATIVE_CERTIFICATES = ["slicer_base64.cer", "printer.cer"];
+/**
+ * The networking plug-in followed by the library it loads from its own
+ * directory for the eMMC file tunnel; without it uploads fail with -4.
+ */
+export const BAMBU_NATIVE_PLUGIN_LIBRARIES = ["libbambu_networking.so", "libBambuSource.so"];
+/**
+ * The only Linux plug-in build whose PrintParams layout matches the helper
+ * (Bambu Studio v02.08.02.61, network agent 02.08.02.54). The setup installs
+ * exactly these files and the server refuses anything else.
+ */
+export const BAMBU_NATIVE_PINNED_PLUGIN = Object.freeze({
+    version: "02.08.02.54",
+    sha256: Object.freeze({
+        "libbambu_networking.so": "bba49709c8dea14ba70251b43965646c0a5e2cde8fd133c64f764d425691bdf2",
+        "libBambuSource.so": "4e05f16fa02740fd12f0040b9efc3e70d43446c7a1a877c6a3926ef0758ca7db",
+    }),
+});
+/** Layout shared by the Linux setup script, the server and the helper's environment. */
+export function bambuNativeManagedPaths(env = process.env) {
+    const home = bambuNativeHomeDir(env);
+    return {
+        home,
+        helper: path.join(home, "bin", "bambu-native-print"),
+        plugin: path.join(home, "plugins", BAMBU_NATIVE_PLUGIN_LIBRARIES[0]),
+        certDir: path.join(home, "cert"),
+        configDir: path.join(home, "config"),
+        receipt: path.join(home, "install.json"),
+    };
+}
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const BAMBU_NATIVE_SOURCE = path.join(PACKAGE_ROOT, "native", "bambu-native-print.cpp");
+export function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+export function sha256File(file) {
+    return sha256Hex(fs.readFileSync(file));
+}
+let nativeSourceSha256;
+/** The packaged helper source never changes while the server runs. */
+function packagedHelperSha256() {
+    nativeSourceSha256 ?? (nativeSourceSha256 = sha256File(BAMBU_NATIVE_SOURCE));
+    return nativeSourceSha256;
+}
+function packageVersion() {
+    try {
+        return String(JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8")).version || "");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Name the setup from this server's own version, whose helper source it
+ * accepts, and its own install directory when that is not the default.
+ */
+export function bambuNativeSetupCommand(version = packageVersion(), env = process.env) {
+    const home = bambuNativeHomeDir(env);
+    const defaultHome = bambuNativeHomeDir({ HOME: env.HOME });
+    const homeOption = home === defaultHome ? "" : ` --home ${JSON.stringify(home)}`;
+    return `npx -y -p bambu-printer-mcp${version ? `@${version}` : ""} bambu-printer-mcp-native-setup${homeOption}`;
+}
+const linuxSetupHint = () => `Run \`${bambuNativeSetupCommand()}\` to build the helper and install the pinned networking plug-in.`;
+const verifiedLibraries = new Map();
+/** Hash a plug-in library once per file version; it is ~16 MB. */
+function libraryMatches(file, expected) {
+    const stat = fs.statSync(file);
+    const key = `${fs.realpathSync(file)}\n${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}`;
+    let digest = verifiedLibraries.get(key);
+    if (!digest) {
+        digest = sha256File(file);
+        verifiedLibraries.set(key, digest);
+    }
+    return digest === expected;
+}
+function samePath(a, b) {
+    try {
+        return fs.realpathSync(a) === fs.realpathSync(b);
+    }
+    catch {
+        return path.resolve(a) === path.resolve(b);
+    }
+}
+function isRegularFile(file) {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve a complete native installation. On Linux the helper, the pinned
+ * plug-in and both certificates must be present before any native route is
+ * chosen, and their resolved paths are handed to the helper so server and
+ * helper can never disagree about which plug-in is loaded.
+ */
+function resolveNativeInstall() {
+    if (!isBambuNativePlatform()) {
+        throw new Error("Bambu native X2D transport requires macOS or x86-64 Linux and Bambu's networking plug-in.");
+    }
+    const helper = resolveNativeHelper();
+    if (process.platform !== "linux")
+        return { helper, env: {} };
+    const managed = bambuNativeManagedPaths();
+    const plugin = process.env.BAMBU_NATIVE_PLUGIN || managed.plugin;
+    const certDir = process.env.BAMBU_NATIVE_CERT_DIR || managed.certDir;
+    const configDir = process.env.BAMBU_NATIVE_CONFIG_DIR || managed.configDir;
+    const certFile = process.env.BAMBU_NATIVE_CERT_FILE || BAMBU_NATIVE_CERTIFICATES[0];
+    if (!isRegularFile(plugin)) {
+        throw new Error(`Bambu networking plug-in is not installed at ${plugin}. ${linuxSetupHint()}`);
+    }
+    for (const library of BAMBU_NATIVE_PLUGIN_LIBRARIES.slice(1)) {
+        if (!isRegularFile(path.join(path.dirname(plugin), library))) {
+            throw new Error(`Bambu networking library ${library} is missing beside ${plugin}. ${linuxSetupHint()}`);
+        }
+    }
+    // A different plug-in build can change the PrintParams layout passed by
+    // value to start_local_print. Only an explicit trusted opt-in skips this.
+    if (process.env.BAMBU_NATIVE_ALLOW_UNPINNED_PLUGIN !== "1") {
+        const files = [
+            [plugin, BAMBU_NATIVE_PINNED_PLUGIN.sha256[BAMBU_NATIVE_PLUGIN_LIBRARIES[0]]],
+            ...BAMBU_NATIVE_PLUGIN_LIBRARIES.slice(1).map(library => [path.join(path.dirname(plugin), library), BAMBU_NATIVE_PINNED_PLUGIN.sha256[library]]),
+        ];
+        for (const [file, expected] of files) {
+            if (!libraryMatches(file, expected)) {
+                throw new Error(`${file} is not the pinned Bambu plug-in ${BAMBU_NATIVE_PINNED_PLUGIN.version}. ${linuxSetupHint()}`);
+            }
+        }
+    }
+    for (const certificate of new Set([certFile, ...BAMBU_NATIVE_CERTIFICATES.slice(1)])) {
+        if (!isRegularFile(path.join(certDir, certificate))) {
+            throw new Error(`Bambu certificate ${certificate} is missing from ${certDir}. ${linuxSetupHint()}`);
+        }
+    }
+    if (samePath(helper, managed.helper)) {
+        // A setup run from another package version builds a different helper.
+        let built;
+        try {
+            built = JSON.parse(fs.readFileSync(managed.receipt, "utf8")).helperSourceSha256;
+        }
+        catch {
+            built = undefined;
+        }
+        if (built !== packagedHelperSha256()) {
+            throw new Error(`The installed native helper was built from a different bambu-printer-mcp version. ${linuxSetupHint()}`);
+        }
+    }
+    return {
+        helper,
+        env: { BAMBU_NATIVE_PLUGIN: plugin, BAMBU_NATIVE_CERT_DIR: certDir, BAMBU_NATIVE_CONFIG_DIR: configDir },
+    };
+}
 export function assertBambuNativeAvailable() {
-    if (process.platform !== "darwin")
-        throw new Error("Bambu native X2D transport requires macOS and the installed Bambu Studio networking plug-in.");
-    resolveNativeHelper();
+    resolveNativeInstall();
+}
+/**
+ * True when X2D controls should use the native route. macOS keeps its
+ * unconditional routing. Linux opts in only with a complete installation, so
+ * stop, pause and heater-off keep their MQTT route otherwise.
+ */
+export function bambuNativeControlsAvailable() {
+    return bambuNativeUnavailableReason() === undefined;
+}
+/** Why native X2D controls are not used on this host, or undefined when they are. */
+export function bambuNativeUnavailableReason() {
+    if (process.platform === "darwin")
+        return undefined;
+    if (process.platform !== "linux")
+        return "Native X2D controls require macOS or x86-64 Linux.";
+    try {
+        resolveNativeInstall();
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
 }
 function resolveNativeHelper() {
     const configured = process.env.BAMBU_NATIVE_HELPER?.trim();
-    const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+    // Linux uses only the setup-managed helper, whose receipt proves it matches
+    // this package; a package-local build could be stale after an update.
     const candidates = [
         configured,
-        path.resolve(packageRoot, "native/bambu-native-print"),
+        process.platform === "linux" ? bambuNativeManagedPaths().helper : path.resolve(PACKAGE_ROOT, "native/bambu-native-print"),
     ].filter((value) => Boolean(value));
     const helper = firstExistingExecutable(candidates);
     if (!helper) {
-        throw new Error("Bambu native helper is not installed. Build native/bambu-native-print with clang++ or set BAMBU_NATIVE_HELPER.");
+        throw new Error(process.platform === "linux"
+            ? `Bambu native helper is not installed. ${linuxSetupHint()} Alternatively set BAMBU_NATIVE_HELPER.`
+            : "Bambu native helper is not installed. Build native/bambu-native-print with clang++ or set BAMBU_NATIVE_HELPER.");
     }
     return helper;
 }
@@ -48,7 +244,11 @@ function isEmergencyCommand(messageJson) {
         (command?.command === "set_bed_temp" && command.temp === 0) ||
         (command?.command === "set_nozzle_temp" && command.target_temp === 0);
 }
-async function interruptNativeOperations(serial) {
+/**
+ * Interrupt this printer's pending print, upload and heating helpers and
+ * resolve once they have exited, so none can still dispatch afterwards.
+ */
+export async function interruptNativeOperations(serial) {
     const pending = [...activeHelpers.values()].filter(helper => helper.serial === serial && !helper.emergency);
     for (const helper of pending)
         helper.interrupt();
@@ -63,11 +263,10 @@ function runNativeHelper(mode, env, timeoutMs, onUpdate, execution = {}) {
     if (needsAuthorization && typeof execution.beforeDispatch !== "function") {
         throw new Error("Native dispatch requires a beforeDispatch fresh-state check.");
     }
-    assertBambuNativeAvailable();
-    const helper = resolveNativeHelper();
+    const install = resolveNativeInstall();
     return new Promise((resolve, reject) => {
-        const child = spawn(helper, [mode], {
-            env,
+        const child = spawn(install.helper, [mode], {
+            env: { ...env, ...install.env },
             stdio: ["pipe", "pipe", "pipe"],
         });
         let markClosed;
@@ -514,7 +713,7 @@ export async function probeBambuNative(host, token) {
         BAMBU_NATIVE_ACCESS_CODE: token,
     }, 20000);
     if (result.resultCode !== 0) {
-        throw new Error(`Bambu native local tunnel probe failed (${result.resultCode}).`);
+        throw new Error(`Bambu native local tunnel probe failed (${result.resultCode}): ${result.updates.join(" | ") || tail(result.stderr, 500)}`);
     }
     return { status: "ok", route: "bambu:///local", updates: result.updates };
 }