Read the
manual.

Get from a fresh `pip install` to your first network-attached print in under 90 seconds.

QUICKSTART.md

Install, configure, first print.

CLI: beambam init

Interactive first-run wizard — discover, prompt for code, test, write credentials.

beambam is importable from Python. The high-level Printer class wraps the signed-MQTT and FTPS surfaces.

beambam.Printer

High-level facade. Lazy MQTT + Cloud. Context-manager protocol. 18 methods (state, start_print, pause, gcode, set_temp, ams_*, jog, home, upload, download, …).

beambam.config.Creds

Printer credentials. resolve(args) honours $X2D_IP/$X2D_CODE/$X2D_SERIAL/$X2D_PRINTER + ~/.x2d/credentials [printer:NAME] sections.

beambam.mqtt

sign_payload + BAMBU_CERT_ID + X2DClient. Bambu Connect cert is loaded lazily on first sign.

beambam.ftps

upload_file / download_file / list_files. Implicit TLS, session-reuse on PASV, INVALID_ALERT workaround for mid-print downloads.

beambam.schemas

TypedDicts for PushAllReport / PrintState / AmsBus / AmsUnit / AmsTray / StartPrintCommand. Mypy-friendly.

beambam.analyze

Print-plan dissector. Parse a .gcode.3mf into phases, count real flushes, project AMS-tray requirements.

beambam ships one daemon that publishes to every common downstream surface.

docs/HA.md

Home Assistant MQTT auto-discovery. ~69 entities including per-tray AMS color, humidity warnings, queue depth, HMS active count.

docs/HA_SETUP.md

Step-by-step HA install + dashboard YAML.

docs/MCP.md

Model Context Protocol stdio server. 25 tools for Claude Desktop, Cursor, Continue.

docs/WEBRTC.md

Chamber-camera streaming under 100ms latency.

docs/WEB_UI.md

Mobile-friendly multi-printer web UI.

docs/QUEUE.md

Persistent print queue with auto-dispatch and AMS validation.

docs/TIMELAPSE.md

Auto-recorded timelapses, ffmpeg stitched.

Wire-level reverse-engineering notes. Read these if you’re extending beambam or building something compatible.

docs/LOCAL_CONTROL_PATHS.md

LAN MQTT, FTPS, RTSPS, LVL-Local — every protocol the printer speaks on the local network.

docs/SIGNED_VS_UNSIGNED.md

Signed vs unsigned MQTT truth table per firmware version. Includes the leaked-cert background.

docs/X2D_RUNTIME_PIPELINE.md

How a print command flows from CLI through the bridge to the printer’s firmware.

docs/CLOUD_BRIDGE.md

Optional Bambu Cloud bridge — cloud-print, cloud-state, cloud-pause.

The things you’ll learn while operating beambam in the field.

Signed MQTT

Jan-2025+ firmware rejects every MQTT command lacking a header.sign_string that verifies against a recognised RSA cert. beambam signs every publish using the publicly-leaked Bambu Connect cert. Your access code stays on your LAN.

Credentials INI

~/.x2d/credentials is an INI file with [printer] (default) or [printer:NAME] sections. Multi-printer setups select via --printer NAME or X2D_PRINTER env var.

Phases + flush analysis

beambam analyze groups the print into contiguous layer ranges by which filaments are active. A tri-color phase against two nozzles forces flushes; the report flags it before you commit to printing.

AMS humidity scale

Bambu firmware reports humidity as a 0–4 level. beambam doctor warns at ≥3 and HA fires binary_sensor.ams_unit{N}_humidity_warn at the same threshold.