bambu-printer-mcp 1.1.51 → 1.1.53

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +33 -8
  2. package/dist/ams-mapping.d.ts +19 -0
  3. package/dist/ams-mapping.js +49 -0
  4. package/dist/bambu-network-bridge.d.ts +86 -9
  5. package/dist/bambu-network-bridge.js +284 -4
  6. package/dist/control-reply.d.ts +21 -0
  7. package/dist/control-reply.js +44 -0
  8. package/dist/counterpart/info.js +1 -0
  9. package/dist/counterpart/route.d.ts +37 -0
  10. package/dist/counterpart/route.js +78 -0
  11. package/dist/counterpart/schemas.d.ts +4 -0
  12. package/dist/counterpart/schemas.js +1 -0
  13. package/dist/design-guidance.d.ts +26 -0
  14. package/dist/design-guidance.js +177 -0
  15. package/dist/fusion-mcp-bridge.d.ts +8 -4
  16. package/dist/fusion-mcp-bridge.js +36 -10
  17. package/dist/index.js +206 -51
  18. package/dist/printers/bambu.d.ts +38 -13
  19. package/dist/printers/bambu.js +204 -69
  20. package/dist/printers/camera-sources.d.ts +8 -0
  21. package/dist/printers/camera-sources.js +66 -0
  22. package/dist/printers/camera-stream.d.ts +65 -0
  23. package/dist/printers/camera-stream.js +227 -0
  24. package/dist/printers/camera-tools.d.ts +192 -0
  25. package/dist/printers/camera-tools.js +29 -0
  26. package/dist/printers/camera-wire.d.ts +7 -0
  27. package/dist/printers/camera-wire.js +40 -0
  28. package/dist/safety/print-file.d.ts +3 -0
  29. package/dist/safety/print-file.js +11 -2
  30. package/dist/safety/printer-state.d.ts +7 -0
  31. package/dist/safety/printer-state.js +11 -1
  32. package/dist/slicer/layer-pauses.d.ts +47 -0
  33. package/dist/slicer/layer-pauses.js +130 -0
  34. package/dist/stl/stl-manipulator.d.ts +3 -0
  35. package/dist/stl/stl-manipulator.js +50 -4
  36. package/dist/tool-annotations.d.ts +25 -0
  37. package/dist/tool-annotations.js +96 -0
  38. package/package.json +2 -1
  39. package/src/ams-mapping.ts +52 -0
  40. package/src/bambu-network-bridge.ts +311 -8
  41. package/src/control-reply.ts +41 -0
  42. package/src/counterpart/info.ts +1 -0
  43. package/src/counterpart/route.ts +91 -0
  44. package/src/counterpart/schemas.ts +2 -0
  45. package/src/design-guidance.ts +188 -0
  46. package/src/fusion-mcp-bridge.ts +30 -10
  47. package/src/index.ts +199 -55
  48. package/src/printers/bambu.ts +194 -60
  49. package/src/printers/camera-sources.ts +53 -0
  50. package/src/printers/camera-stream.ts +165 -0
  51. package/src/printers/camera-tools.ts +29 -0
  52. package/src/printers/camera-wire.ts +39 -0
  53. package/src/safety/print-file.ts +12 -2
  54. package/src/safety/printer-state.ts +11 -1
  55. package/src/slicer/layer-pauses.ts +143 -0
  56. package/src/stl/stl-manipulator.ts +58 -5
  57. package/src/tool-annotations.ts +126 -0
package/README.md CHANGED
@@ -206,7 +206,7 @@ The optional FULU **BambuNetwork bridge** exposes `bambu_network_bridge_status`,
206
206
  - Set print speed mode (`silent`/`standard`/`sport`/`ludicrous`), clear HMS/print errors, trigger AMS RFID re-read, and control H2/P2 airduct mode (`cooling`/`heating`) via MQTT
207
207
  - **Start/stop AMS filament drying** (`set_ams_drying`) on heated AMS units (AMS Pro / AMS-HT). Sends `print.ams_control` MQTT command.
208
208
  - Set nozzle and bed temperature via G-code dispatch over MQTT
209
- - Confirm print starts and positive manual heating through a human preflight prompt. Hardware-error clearing requires explicit human acknowledgment; see [hardware safety and headless configuration](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md).
209
+ - Print, heating and resume start without a prompt; clearing hardware errors and resuming a file that could not be re-read still ask a person; see [hardware safety](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md).
210
210
  - Set fan speed (part, auxiliary, chamber) and chamber light mode (on/off/flashing) via MQTT
211
211
  - Read HMS (Health Management System) diagnostics as an MCP resource at `printer://{host}/hms` — read-only error summary from the printer, with automatic settle retry
212
212
  - Start G-code files already stored on the printer
@@ -643,6 +643,18 @@ Two transports are wired in, picked by `bambu_model`:
643
643
 
644
644
  Returns `{ status, format: "image/jpeg", sizeBytes, base64, savedTo?, transport }`. `transport` is `"tcp-6000"` or `"rtsps-322"` so callers can tell which path produced the frame. Pass `save_path` to also write the bytes to disk; otherwise only the base64 payload is returned.
645
645
 
646
+ #### camera_stream_start, camera_frame, camera_stream_stop
647
+
648
+ Development capability; discover these tools before using them with an installed server. Start one shared camera connection while a viewer is open, then request changed frames. The connection closes after 30 seconds without a viewer request. Snapshots reuse its latest frame. A1/P1 use the existing TLS protocol; X1/H2/P2S use one ffmpeg process for the stream lifetime.
649
+
650
+ ```json
651
+ {"fps": 1, "idle_timeout_ms": 30000, "bambu_model": "p1s"}
652
+ ```
653
+
654
+ Pass the usual optional `host`, `bambu_serial`, and `bambu_token` overrides to each tool. `camera_stream_start` returns `{status: "started" | "running", transport, fps, startedAt}`. Then call `camera_frame` with, for example, `{ "since_seq": 0, "wait_ms": 10000, "max_width": 300, "max_bytes": 20000 }`. A changed frame returns JPEG `base64`, `seq`, dimensions and capture time. Keep the last delivered `seq` on `unchanged`; those replies carry no image. `max_width` preserves aspect ratio; optional `max_bytes` caps JPEG bytes by downscaling further (base64 adds about one third), and `changed_only` defaults to true with a 0.02 normalized thumbnail threshold.
655
+
656
+ Stop requests close the shared connection immediately, affecting every viewer of that printer; normally let idle expiry close it. Other printers keep their own connections. These tools send no motion, heating or print commands. See [the camera stream contract](docs/CAMERA-STREAM.md) for limits, cancellation, availability and lifecycle details.
657
+
646
658
  #### delete_printer_file
647
659
 
648
660
  Delete a single file from the printer's SD card via FTPS. **Destructive.** Requires `confirm: true` — without it the call returns `status: "skipped"` and does not contact the printer. Path traversal segments (`..`) are rejected. Only files under `cache/`, `timelapse/`, and `logs/` can be deleted.
@@ -741,12 +753,12 @@ Resume a paused print job that this server inspected and started. Resume reheats
741
753
 
742
754
  1. A fresh report must show that job paused, with the inspected nozzle and filament still in place.
743
755
  2. The server downloads the job's file from the printer over FTPS and compares its SHA-256 with the inspected bytes. A P1S deletes an uploaded project once it starts printing and keeps the plate G-code it extracted, `cache/<name>_plate_<n>.gcode`, which is byte-identical to the 3MF's `Metadata/plate_<n>.gcode`. When the project is gone, the server compares that file with the inspected plate. A different file refuses the resume, and the job can no longer be resumed from here.
744
- 3. A person confirms through MCP elicitation: the prompt names the job, its peak temperatures, materials and SHA-256. `BAMBU_REQUIRE_CONFIRMATION=0` skips this prompt, as it does for print and heating prompts.
745
- 4. The printer is read again after the prompt, and on X2D and H2 the native helper rechecks it once more right before sending. Only then does the server send `UpdateState` with `state: "resume"`.
756
+ 3. The resume starts without a prompt when the bytes were verified. Only a file that could not be re-read asks a person; that prompt names the job, its peak temperatures, materials and SHA-256.
757
+ 4. The printer is read again, and on X2D and H2 the native helper rechecks it once more right before sending. Only then does the server send `UpdateState` with `state: "resume"`.
746
758
 
747
759
  The server keeps one resume record per printer. Cancelling the job ends it, and so does a report that the job finished, failed or went idle after it was seen running, or another job seen in its place. A later job with the same name, such as the same file reprinted from the touchscreen, is never resumed. The server watches every MQTT report it receives, not just its own reads. It doesn't see reports while its MQTT session is disconnected.
748
760
 
749
- The result is `{status, message, jobName, bytesVerified}`, where `jobName` is the name `counterpart_print_progress` reports. On the BambuNetwork and X2D native routes, Bambu's plug-in puts the file on the printer, so its FTPS path isn't verified. If the file can't be read back there, the resume matches the job by its unique name and returns `bytesVerified: false`, and the prompt says so. That prompt always appears, even with `BAMBU_REQUIRE_CONFIRMATION=0`, which skips only prompts for resumes whose bytes were verified. On every other route, a file that can't be re-read refuses the resume.
761
+ The result is `{status, message, jobName, bytesVerified}`, where `jobName` is the name `counterpart_print_progress` reports. On the BambuNetwork and X2D native routes, Bambu's plug-in puts the file on the printer, so its FTPS path isn't verified. If the file can't be read back there, the resume matches the job by its unique name and returns `bytesVerified: false`, and a person is asked, with the prompt saying so. On every other route, a file that can't be re-read refuses the resume.
750
762
 
751
763
  ```json
752
764
  {
@@ -907,7 +919,7 @@ Inspect a prepared sliced 3MF or textual G-code file offline before deciding wha
907
919
 
908
920
  `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.
909
921
 
910
- 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.
922
+ 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.
911
923
 
912
924
  #### Print options
913
925
 
@@ -970,7 +982,7 @@ Install Bambu Studio and its networking plug-in, plus the Apple command-line dev
970
982
 
971
983
  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.
972
984
 
973
- 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`. A job that uses only one external spool requires explicit `use_ams: false`; a job mixing AMS trays with the external spools maps them as `254` (left/deputy nozzle) and `255` (right/main nozzle). 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.
985
+ 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`. A job that uses only one external spool requires explicit `use_ams: false`; a job mixing AMS trays with the external spools maps them as `254` (left/deputy nozzle) and `255` (right/main nozzle). 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 and fresh printer-state checks 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.
974
986
 
975
987
  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.
976
988
 
@@ -1065,7 +1077,8 @@ If the project does not match those assumptions, the tool fails fast with a stru
1065
1077
 
1066
1078
  [Counterpart](https://github.com/DMontgomery40/scan-to-make) (Scan to Make) reads printers through a small contract that this server and [mcp-3D-printer-server](https://github.com/DMontgomery40/mcp-3D-printer-server) share. Each tool declares an `outputSchema` and returns `structuredContent`, plus the same JSON as text for older clients. An error is returned as text only, because MCP clients check `structuredContent` against the schema even on errors. `counterpart_printer_info` and `counterpart_print_progress` take the usual optional `host`, `bambu_serial`, `bambu_token` and `bambu_model` (default `BAMBU_MODEL`) arguments.
1067
1079
 
1068
- - **`counterpart_printer_info`** returns `{contract, server: {name, version}, printer: {kind: "bambu", model, serial, host}, capabilities}`. `capabilities` lists progress, layers, the camera transport (`bambu-tcp` for A1/P1, `rtsp` for X1, P2S, H2 and X2D, `none` without a model), `filaments: "ams"`, pause, resume, cancel, `print3mf` and `gcode` (false on X2D). It sends nothing to the printer and never returns the access code.
1080
+ - **`counterpart_printer_info`** returns `{contract, server: {name, version}, printer: {kind: "bambu", model, serial, host}, capabilities}`. `capabilities` lists progress, layers, the camera transport (`bambu-tcp` for A1/P1, `rtsp` for X1, P2S, H2 and X2D, `none` without a model), `cameraStream: true` for supported camera models, `filaments: "ams"`, pause, resume, cancel, `print3mf` and `gcode` (false on X2D). It sends nothing to the printer and never returns the access code.
1081
+ - **`counterpart_print_route`** reads or changes how prints and Stop/Pause/Resume reach the printer: `{route, mode, type, choices, savedTo}`, where `route` is `lan` (the local network, in the configured `BAMBU_DEFAULT_CONNECTION_MODE`) or `cloud` (Bambu Cloud through the [FULU bridge](docs/FULU.md)). Pass `route` to change it; the next print and control use it at once, and it is written to the `.env` in the server's working directory when one exists (`savedTo`, otherwise `null`). It is not part of the shared contract: it has no `outputSchema`, and mcp-3D-printer-server has no Bambu Cloud route.
1069
1082
  - **`counterpart_print_progress`** returns `{contract, observedAt, state, job?, temps?, activeFilament?, problems}` from the printer's MQTT reports, which this server keeps while it is connected. A held session is answered from that cache without any printer traffic, and `observedAt` is when the printer sent the report. The server asks the printer for a full report only to fill an empty cache, and at most once every five minutes after the printer has been quiet that long. A printer that sends no report within 8 seconds is `offline`.
1070
1083
  - `state`: `IDLE` is `idle`, `PREPARE`/`SLICING` `preparing`, `RUNNING` `printing`, `PAUSE` `paused`, `FINISH` `finished` and `FAILED` `failed`. A `FAILED` job with `0300400C` ("The task was canceled.") in `print_error`, or in X2D's `fail_reason`, is `cancelled`. Any other or missing `gcode_state` on a connected printer is `busy`.
1071
1084
  - `job` (not for idle, busy or offline): `name` is `subtask_name`, else the basename of `gcode_file` (a raw G-code print reports only its file path; that basename is the `jobName` the print returns); `id` is `task_id`, omitted when it is the LAN placeholder `"0"`; `progress` is `mc_percent`; `remainingSec` is `mc_remaining_time` (minutes) × 60; `layer`/`totalLayers` appear once the printer reports a total; `stage` is Bambu Studio's words for `stg_cur` ("Heatbed preheating", "Auto bed leveling").
@@ -1165,7 +1178,7 @@ When `slicer_type` is `bambustudio` (the default), these additional parameters a
1165
1178
  | Parameter | Type | Description |
1166
1179
  |-----------|------|-------------|
1167
1180
  | `uptodate` | boolean | Update 3MF configs to latest BambuStudio presets |
1168
- | `repetitions` | number | Number of copies to print |
1181
+ | `repetitions` | number | Total STL copies, using the CLI's `--clone-objects`; do not also pass `clone_objects`. Copies may span plates, and `print_3mf` prints one selected plate per call. For 3MF repetitions, choose `slice_plate` explicitly. |
1169
1182
  | `orient` | boolean | Auto-orient model for optimal printability |
1170
1183
  | `arrange` | boolean | Auto-arrange objects on the build plate |
1171
1184
  | `ensure_on_bed` | boolean | Lift floating models onto the bed |
@@ -1389,6 +1402,18 @@ Resources follow the MCP resource protocol and can be read by calling `ReadResou
1389
1402
 
1390
1403
  **Example:** To read the status of the default printer, use URI `printer://192.168.1.100/status`. The host segment must match a configured printer IP; the server uses `PRINTER_HOST` if the default URI template is used.
1391
1404
 
1405
+ ### Design guidance
1406
+
1407
+ The server carries manufacturing judgment for agents that design or edit a model to print. It is served as MCP prompts, so the client attaches each piece when it applies; the server's `instructions` tell any client they exist.
1408
+
1409
+ - `fdm_design` -- for every design or model-editing task. Plan how the object prints as part of the design: geometry, orientation, supports, colours and assembly, using the actual printer, filaments and slice. It keeps what the person asked for and judges overhangs, bridges and supports locally, with no fixed 45-degree or bridge-length ban.
1410
+ - `fdm_multicolor` -- when several colours or support materials share a print: filament transitions across layers, colour placement, plate scheduling and flushing.
1411
+ - `fdm_assembly` -- when a split, accent insert or joint could materially improve the result.
1412
+ - `fdm_after_slice` -- a separate review turn after `slice_stl`, before presenting the manufacturing recommendation: keep, revise, or validate one specific uncertainty, using the returned `slicer_result`.
1413
+ - `guidance://fdm/capability-guidance` (resource) -- planning bands and sources for bridges and overhangs, for when one is consequential and there is no sufficiently specific measured capability for the printer, material and profile.
1414
+
1415
+ mcp-3D-printer-server serves the same guidance.
1416
+
1392
1417
  </details>
1393
1418
 
1394
1419
  <details>
@@ -17,3 +17,22 @@ export declare function bridgeAmsMapping2Entry(value: number, dualNozzle?: boole
17
17
  ams_id: number;
18
18
  slot_id: number;
19
19
  };
20
+ /** A project filament as the sliced 3MF's Metadata/project_settings.config declares it. */
21
+ export interface ProjectFilament {
22
+ type: string;
23
+ filamentId: string;
24
+ colour: string;
25
+ nozzle?: number;
26
+ }
27
+ /** Read every project filament (not just the plate's used ones) from project_settings.config. */
28
+ export declare function projectFilaments(projectSettings: Record<string, unknown>): ProjectFilament[];
29
+ /** The colour the printer reports for an absolute tray value (AMS, AMS-HT or external spool). */
30
+ export declare function trayColour(rawStatus: any, tray: number): string | undefined;
31
+ /**
32
+ * PrintParams.ams_mapping_info exactly as Bambu Studio and FULU's slicer build it
33
+ * (SelectMachineDialog::get_ams_mapping_result) and send it with every print: one entry per
34
+ * project filament. A mapped filament names its tray, its filament id and type, its colour as
35
+ * #RRGGBBAA and the tray's colour as the printer reports it; an unmapped one carries ams -1.
36
+ * Filament-map nozzle 1 (left) is cloud nozzle 1 and 2 (right) is 0 (CloudTaskNozzleId).
37
+ */
38
+ export declare function studioAmsMappingInfo(filaments: ProjectFilament[], mapping: number[], colourOfTray: (tray: number) => string | undefined): Array<Record<string, unknown>>;
@@ -74,3 +74,52 @@ export function bridgeAmsMapping2Entry(value, dualNozzle = false) {
74
74
  return { ams_id: 128, slot_id: value - 128 };
75
75
  return { ams_id: Math.floor(value / 4), slot_id: value % 4 };
76
76
  }
77
+ /** Read every project filament (not just the plate's used ones) from project_settings.config. */
78
+ export function projectFilaments(projectSettings) {
79
+ const list = (key) => Array.isArray(projectSettings[key]) ? projectSettings[key].map(String) : [];
80
+ const types = list("filament_type"), ids = list("filament_ids"), colours = list("filament_colour"), nozzles = list("filament_map");
81
+ return types.map((type, index) => ({
82
+ type, filamentId: ids[index] ?? "", colour: colours[index] ?? "",
83
+ ...(nozzles[index] !== undefined && Number.isInteger(Number(nozzles[index])) ? { nozzle: Number(nozzles[index]) } : {}),
84
+ }));
85
+ }
86
+ /** The colour the printer reports for an absolute tray value (AMS, AMS-HT or external spool). */
87
+ export function trayColour(rawStatus, tray) {
88
+ const units = Array.isArray(rawStatus?.ams?.ams) ? rawStatus.ams.ams : [];
89
+ let colour;
90
+ if (tray === 254 || tray === 255) {
91
+ const slots = Array.isArray(rawStatus?.vir_slot) ? rawStatus.vir_slot : [];
92
+ colour = slots.find(slot => Number(slot?.id) === tray)?.tray_color ?? (tray === 254 ? rawStatus?.vt_tray?.tray_color : undefined);
93
+ }
94
+ else if (tray >= 128) {
95
+ colour = units.find(unit => Number(unit?.id) === tray)?.tray?.[0]?.tray_color;
96
+ }
97
+ else if (tray >= 0) {
98
+ const unit = units.find(candidate => Number(candidate?.id) === Math.floor(tray / 4));
99
+ colour = (Array.isArray(unit?.tray) ? unit.tray : []).find((slot) => Number(slot?.id) === tray % 4)?.tray_color;
100
+ }
101
+ return typeof colour === "string" ? colour : undefined;
102
+ }
103
+ /**
104
+ * PrintParams.ams_mapping_info exactly as Bambu Studio and FULU's slicer build it
105
+ * (SelectMachineDialog::get_ams_mapping_result) and send it with every print: one entry per
106
+ * project filament. A mapped filament names its tray, its filament id and type, its colour as
107
+ * #RRGGBBAA and the tray's colour as the printer reports it; an unmapped one carries ams -1.
108
+ * Filament-map nozzle 1 (left) is cloud nozzle 1 and 2 (right) is 0 (CloudTaskNozzleId).
109
+ */
110
+ export function studioAmsMappingInfo(filaments, mapping, colourOfTray) {
111
+ return filaments.map((filament, position) => {
112
+ const tray = mapping[position];
113
+ if (tray === undefined || tray < 0)
114
+ return { ams: -1, targetColor: "", filamentId: "", filamentType: "" };
115
+ const hex = filament.colour.replace(/^#/, "").toUpperCase();
116
+ return {
117
+ ams: tray,
118
+ targetColor: colourOfTray(tray) ?? "",
119
+ filamentId: filament.filamentId,
120
+ filamentType: filament.type,
121
+ ...(filament.nozzle === 1 ? { nozzleId: 1 } : filament.nozzle === 2 ? { nozzleId: 0 } : {}),
122
+ sourceColor: /^[0-9A-F]{6}$/.test(hex) ? `#${hex}FF` : /^[0-9A-F]{8}$/.test(hex) ? `#${hex}` : "",
123
+ };
124
+ });
125
+ }
@@ -1,12 +1,39 @@
1
1
  /** A parenthesized explanation of a plug-in print result, or "" when it names no known cause. */
2
2
  export declare function describeBambuNetworkPrintError(value: number): string;
3
3
  /** Waits from native/bambu-native-print.cpp, which prints through the same plug-in calls. */
4
- export declare const LOCAL_PRINT_TIMING: Readonly<{
5
- connectTimeoutMs: 30000;
6
- pollMs: 250;
7
- settleMs: 3000;
8
- retryWaitMs: 8000;
9
- }>;
4
+ export type LocalTiming = {
5
+ connectTimeoutMs: number;
6
+ pollMs: number;
7
+ settleMs: number;
8
+ retryWaitMs: number;
9
+ };
10
+ export declare const LOCAL_PRINT_TIMING: Readonly<LocalTiming>;
11
+ /** A control waits briefly for the certificate message, then sends; -4/-4030 returns are retried after a reinstall. */
12
+ export type LocalControlTiming = LocalTiming & {
13
+ certificateWaitMs: number;
14
+ attempts: number;
15
+ deliveryMs: number;
16
+ };
17
+ export declare const LOCAL_CONTROL_TIMING: Readonly<LocalControlTiming>;
18
+ export { controlReply, isAuthorizationRefusal } from "./control-reply.js";
19
+ /** Cloud session waits: connection and printer subscription, certificate, settle after the state requests. */
20
+ export type CloudTiming = {
21
+ connectTimeoutMs: number;
22
+ pollMs: number;
23
+ settleMs: number;
24
+ certificateWaitMs: number;
25
+ };
26
+ export declare const CLOUD_PRINT_TIMING: Readonly<CloudTiming>;
27
+ export type CloudSession = {
28
+ settle: (ms: number) => Promise<void>;
29
+ /** Ask the plug-in to install the printer's certificate again, as Bambu Studio does after a failed send. */
30
+ installCertificate: () => Promise<void>;
31
+ /** Wait up to ms for device_cert_installed; true once it has arrived. */
32
+ certificateReadyWithin: (ms: number) => Promise<boolean>;
33
+ /** This printer's cloud messages, as they arrive. */
34
+ messages: string[];
35
+ jobUpdates: BridgeJobUpdate[];
36
+ };
10
37
  export type LocalPrinter = {
11
38
  devId: string;
12
39
  devIp: string;
@@ -22,8 +49,14 @@ export type BridgeJobUpdate = {
22
49
  export type LocalSession = {
23
50
  installCertificate: () => Promise<void>;
24
51
  settle: (ms: number) => Promise<void>;
52
+ /** Waits up to ms for FULU's certificate-installed message for this printer; false if it never came. */
53
+ certificateReadyWithin: (ms: number) => Promise<boolean>;
54
+ /** This printer's messages about stop/pause/resume, as they arrive. */
55
+ controlMessages: string[];
25
56
  jobUpdates: BridgeJobUpdate[];
26
57
  };
58
+ /** One line per FULU event or control send, for diagnosing controls. Never includes access codes. */
59
+ export type BridgeTrace = (entry: Record<string, unknown>) => void;
27
60
  type JsonObject = Record<string, unknown>;
28
61
  export type BambuNetworkBridgeOptions = {
29
62
  bridgeCommand?: string;
@@ -34,6 +67,8 @@ export type BambuNetworkBridgeOptions = {
34
67
  /** Trusted in-process preflight; never populated from tool arguments. */
35
68
  beforeDispatch?: (method: string) => Promise<void>;
36
69
  assertDispatchAllowed?: (method: string) => void;
70
+ /** Diagnostics for a print control: every FULU event and send in its session. */
71
+ trace?: BridgeTrace;
37
72
  onDispatched?: (method: string) => void;
38
73
  };
39
74
  export type BambuNetworkBridgeStatus = {
@@ -71,6 +106,16 @@ export type BambuNetworkBridgeStatus = {
71
106
  export declare function bambuNetworkCertDir(configDir: string, env?: NodeJS.ProcessEnv): string;
72
107
  export declare function prepareBambuNetworkCertDir(configDir: string, env?: NodeJS.ProcessEnv): string;
73
108
  export declare function defaultBambuNetworkConfigDir(): string;
109
+ /**
110
+ * The client identity FULU's GUI gives the plug-in before agent start
111
+ * (GUI_App::init_http_extra_header). Through the Linux bridge FULU presents
112
+ * itself as Bambu Studio at the version its plug-in ABI belongs to
113
+ * (PJarczakLinuxBridgeConfig.cpp forced_client_version, "02.05.02.51").
114
+ * Bambu's cloud issues the printer-control certificate and creates print
115
+ * tasks for this client, so an agent started without it is an unknown client.
116
+ * The device id is kept in the config folder so it stays the same per install.
117
+ */
118
+ export declare function bambuNetworkClientHeaders(configDir: string, env?: NodeJS.ProcessEnv): Record<string, string>;
74
119
  /**
75
120
  * FULU's Linux host opens its network and source libraries by bare name from
76
121
  * its working directory instead of PJARCZAK_BAMBU_PLUGIN_DIR
@@ -116,7 +161,7 @@ export declare class BambuNetworkBridge {
116
161
  * cannot encrypt or publish project_file (-4030). The session is closed
117
162
  * after `run`, so printer reports stop accumulating in the host's queue.
118
163
  */
119
- withLocalSession<T>(printer: LocalPrinter, options: BambuNetworkBridgeOptions, assertActive: () => void, timing: typeof LOCAL_PRINT_TIMING, run: (session: LocalSession) => Promise<T>): Promise<T>;
164
+ withLocalSession<T>(printer: LocalPrinter, options: BambuNetworkBridgeOptions, assertActive: () => void, timing: Readonly<LocalTiming>, run: (session: LocalSession) => Promise<T>): Promise<T>;
120
165
  private runLocalSession;
121
166
  /**
122
167
  * Run a LAN print method in a local session. A synchronous -4030 means the
@@ -124,10 +169,43 @@ export declare class BambuNetworkBridge {
124
169
  * exchange, as the native helper does; each attempt passes the caller's
125
170
  * fresh pre-dispatch checks.
126
171
  */
127
- startLocalPrint(printer: LocalPrinter, method: string, payload: JsonObject, options?: BambuNetworkBridgeOptions, assertActive?: () => void, timing?: typeof LOCAL_PRINT_TIMING): Promise<{
172
+ startLocalPrint(printer: LocalPrinter, method: string, payload: JsonObject, options?: BambuNetworkBridgeOptions, assertActive?: () => void, timing?: Readonly<LocalTiming>): Promise<{
128
173
  result: unknown;
129
174
  jobUpdates: BridgeJobUpdate[];
130
175
  }>;
176
+ /**
177
+ * A print control (stop, pause, resume) through the same authenticated LAN
178
+ * session as a FULU print. FULU's own app sends controls exactly this way
179
+ * (send_message_to_printer, qos 1, flag 0) on a connection whose certificate
180
+ * is installed. A fresh connection can report SEND_MSG_FAILED (-4) or
181
+ * LP_PUBLISH_MSG_FAILED (-4030) while that exchange finishes: those returns
182
+ * mean nothing was sent, so the certificate is reinstalled and the control
183
+ * tried again, as the native X2D helper does. Any other return is final.
184
+ * beforeDispatch runs before every send, so a resume re-checks the paused job.
185
+ */
186
+ sendLocalPrintCommand(printer: LocalPrinter, command: "stop" | "pause" | "resume", options?: BambuNetworkBridgeOptions, beforeDispatch?: () => Promise<void>, timing?: Readonly<LocalControlTiming>): Promise<Record<string, unknown>>;
187
+ /**
188
+ * Open the plug-in's Bambu Cloud session with a printer bound to the account, in the order
189
+ * Bambu Studio uses (GUI_App.cpp on_server_connected / on_printer_connected): wait for the
190
+ * cloud connection, select and subscribe to the printer, and when it connects request its
191
+ * state (pushall, get_version, get_access_code) and install its certificate for cloud use.
192
+ * Without that state the plug-in refuses a cloud print with -3140 (ENC_FLAG_NOT_READY).
193
+ * Shares the LAN session queue: one reader of the plug-in's events at a time.
194
+ */
195
+ withCloudSession<T>(devId: string, options: BambuNetworkBridgeOptions, assertActive: () => void, timing: Readonly<CloudTiming>, run: (session: CloudSession) => Promise<T>): Promise<T>;
196
+ /** A cloud print method (start_print) in a cloud session, so the plug-in has the printer's state. */
197
+ startCloudPrint(devId: string, method: string, payload: JsonObject, options?: BambuNetworkBridgeOptions, assertActive?: () => void, timing?: Readonly<CloudTiming>): Promise<{
198
+ result: unknown;
199
+ jobUpdates: BridgeJobUpdate[];
200
+ }>;
201
+ /**
202
+ * A print control over Bambu Cloud: how Bambu Studio and FULU's slicer control a printer
203
+ * bound to the account (MachineObject::publish_json → cloud_publish_json: send_message,
204
+ * qos 1, flag 0), in a cloud session. Held open like the LAN control.
205
+ */
206
+ sendCloudPrintCommand(devId: string, command: "stop" | "pause" | "resume", options?: BambuNetworkBridgeOptions, beforeDispatch?: () => Promise<void>, timing?: Readonly<LocalControlTiming>): Promise<Record<string, unknown>>;
207
+ /** Appends control diagnostics to control-trace.log in the bridge's config folder. */
208
+ private controlTrace;
131
209
  callWithAgent(method: string, payload?: JsonObject, options?: BambuNetworkBridgeOptions): Promise<unknown>;
132
210
  stop(): Promise<void>;
133
211
  private ensureStarted;
@@ -138,4 +216,3 @@ export declare class BambuNetworkBridge {
138
216
  private rejectAllPending;
139
217
  private needsExpectedVersionRetry;
140
218
  }
141
- export {};