Bambu Labs Integration in text-to-cad: Dry-Runs, Upload, and Print Job Management

The text-to-cad repository provides a self-contained Bambu Labs skill that validates G-code files, packages them into Bambu-compatible .3mf archives via the bambox CLI, and manages print workflows through secure FTPS uploads and MQTT command publishing, all operating under a dry-run-by-default safety policy.

The earthtojake/text-to-cad repository includes a specialized skill for Bambu Labs printer integration that enables agents to safely bridge CAD generation with physical fabrication. Located under skills/bambu-labs/, this utility offers a complete workflow for preparing, uploading, and controlling print jobs while enforcing strict safety validations before any network traffic occurs.

Architecture and Safety-First Design

The Bambu Labs integration is implemented in skills/bambu-labs/scripts/bambu_lan_print.py as a standalone command-line tool that dispatches to specialized handlers for packaging, configuration, and printer communication.

Dry-Run-by-Default Policy

Every command that interacts with the printer or modifies files operates in dry-run mode unless explicitly overridden. The build_send_plan function (lines 30-38) constructs a JSON plan detailing the intended actions—such as FTPS upload paths, MQTT topics, and command payloads—while setting dry_run: true by default. Only when the user supplies the --execute flag does the script proceed with actual network operations or file writes, allowing operators to inspect the complete execution plan before committing resources.

Network Safety Validations

Before establishing any connection, the code validates that printer hostnames resolve to private IP addresses using validate_local_host and resolve_host_addresses (lines 29-33). This check prevents accidental targeting of public internet hosts unless the --allow-nonprivate-host flag is explicitly provided. Additionally, print-start commands require the --confirm-start-print flag to prevent unattended job initiation, with safety notes embedded in the plan output via build_common_send_plan (lines 75-82).

G-code Preparation and bambox Packaging

The skill supports two pathways for preparing print files: direct .gcode uploads or packaging into Bambu-native .3mf projects using the external bambox tool.

Input Validation

Before processing, inspect_gcode_file (lines 36-45) verifies that the supplied file is a plain .gcode file (rejecting .gcode.3mf or .3mf archives) and computes its MD5 hash and size for integrity tracking. This validation ensures that downstream packaging and upload operations receive valid input data.

Profile and Filament Verification

When using the bambox-project hand-off, the script invokes build_bambox_pack_command and validate_bambox_filaments (lines 84-106) to construct CLI arguments for the bambox packer. The BAMBOX_PROFILES table (lines 84-95) hardcodes supported printer profiles and allowed filament types, ensuring that generated project files match the target hardware capabilities before execution.

Secure File Upload via FTPS

For file transfer, the upload_ftps function (lines 141-170) establishes an implicit TLS connection to the printer's FTPS server using ImplicitFTP_TLS. The implementation includes storbinary_with_bambu_timeout_tolerance, which wraps the standard storbinary method to handle printer-side timeouts gracefully during large file transfers. By default, files are uploaded to the cache/ remote directory (defined in lines 28-35 alongside default FTPS port 990 and MQTT port 8883).

Print Job Management via MQTT

Once files are staged, the integration communicates with the printer through MQTT for real-time control. The publish_mqtt function and mqtt_publish_packet helper (lines 471-514) construct binary MQTT packets with appropriate QoS levels (0 or 1) to publish commands such as gcode_file (start print), pause, cancel, or clean_print_error. The MQTT client is implemented without external dependencies to maintain the skill's self-containment policy.

Practical CLI Examples

The following commands demonstrate common workflows using the bambu-labs skill CLI.

Dry-Run a Packaging Plan

Generate a JSON plan showing the bambox pack and validation steps without executing them:

bambu-labs package \
  --gcode my_part.gcode \
  --bambox-profile p1s-0.4 \
  --filament PLA \
  --output /tmp/my_part.3mf

Execute Packaging and Validation

Build the .3mf archive and validate filaments against the hardcoded profile table:

bambu-labs package \
  --gcode my_part.gcode \
  --bambox-profile p1s-0.4 \
  --filament PLA \
  --output /tmp/my_part.3mf \
  --execute

Upload and Start Print via FTPS and MQTT

Upload a plain G-code file and trigger a print job with safety confirmations:

bambu-labs send \
  --action upload-start \
  --gcode my_part.gcode \
  --printer my-printer-id \
  --host 192.168.1.42 \
  --access-code 12345678 \
  --confirm-start-print \
  --execute

Clear Printer Error State

Send an MQTT command to clear stale errors without file upload:

bambu-labs clear-error \
  --printer my-printer-id \
  --host 192.168.1.42 \
  --access-code 12345678 \
  --execute

Query Printer Status

Subscribe to MQTT status topics for 5 seconds to retrieve current printer state:

bambu-labs status \
  --printer my-printer-id \
  --host 192.168.1.42 \
  --topic device/$(bambu-labs serial)/report \
  --wait-after-publish 5 \
  --execute

Summary

• Dry-run-first architecture: All destructive operations require explicit --execute flags, with JSON plan inspection available via build_send_plan (lines 30-38).
• Input integrity checks: G-code files are validated for format compliance and hashed via inspect_gcode_file (lines 36-45) before processing.
• Bambox integration: Profile and filament validation against the BAMBOX_PROFILES table (lines 84-95) ensures hardware compatibility.
• Secure file transfer: FTPS uploads use ImplicitFTP_TLS with timeout-tolerant streaming via storbinary_with_bambu_timeout_tolerance (lines 141-170).
• Safety constraints: Private IP validation (validate_local_host, lines 29-33) and explicit print confirmation (--confirm-start-print) prevent accidental operations.

Frequently Asked Questions

What is the default execution mode for Bambu Labs commands?

By default, all commands operate in dry-run mode, outputting a JSON plan describing the intended actions without performing network operations or file modifications. You must append --execute to the command line to enable actual FTPS uploads, MQTT publishing, or file packaging, as implemented in the build_send_plan logic (lines 30-38).

How does the integration validate bambox profiles and filaments?

The code maintains a hardcoded BAMBOX_PROFILES dictionary (lines 84-95) that defines supported printer models, nozzle sizes, and allowed filament types. When processing a packaging request, validate_bambox_filaments (lines 84-106) cross-references the user-specified profile and filament against this table, rejecting incompatible combinations before invoking the external bambox CLI.

What safety mechanisms prevent unintended print starts?

The integration enforces multiple safeguards: validate_local_host and resolve_host_addresses (lines 29-33) ensure target printers reside on private networks unless --allow-nonprivate-host is specified; additionally, the --confirm-start-print flag is required to authorize actual print jobs, with warning notes embedded in the generated plan via build_common_send_plan (lines 75-82).

Can I upload files to printers on public IP addresses?

While technically possible using the --allow-nonprivate-host flag, the code explicitly discourages this by defaulting to private IP validation. The validate_local_host check (lines 29-33) will reject public addresses unless the override flag is provided, ensuring that agents do not accidentally expose print jobs to internet-facing hosts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}