mirror of
https://github.com/maziggy/bambuddy.git
synced 2026-09-30 03:01:21 +02:00
maziggy
3bc96254ef
A sliced file numbers its filaments 1..4; which AMS tray each came from is
decided when the job is sent. #2768 gave the Spoolman writer two ways to
recover that decision when the print did not come through Bambuddy: the
printer's own mapping field, and a colour match of the 3MF's slots against the
loaded trays. An A1 satisfies neither. It publishes no mapping field, and it
drops the MQTT connection when we subscribe to its request topic, so the
slicer's instruction never arrives either. That leaves the colour match, and it
compares hex strings exactly.
The reporter sliced with a generic black profile against a tray they had set to
charged slot 1 to whatever sat in the first tray -- 2.17 g onto a grey PLA+
spool, while the print was fed from tray 3. Their bundle carries the printer's
own answer: "Tray change during print: tray=3 at layer=0", recorded 90 seconds
in, and read further down the same completion pass by _print_used_tray_keys to
decide which slots the print had touched. The same pass then charged tray 0 on
a guess, and logged "AMS0-T3: remain% did not fall over the print" about the
tray that had actually done the work.
_single_slot_tray_from_state adds the third rung. For a print with exactly one
slot carrying usage, the one slot came from the one tray, so the printer's tray
reporting answers the question directly: the mid-print tray-change log, then
the tray loaded at print start, then the current one, then the last real tray
seen. That is the ladder usage_tracker.on_print_complete has consulted since it
started resolving mappings at completion -- Spoolman users were the only ones
not getting it, which is why an install running the built-in inventory has
never shown this. On this printer only the first and last rungs can fire:
tray_now_at_start is 255 because print start runs before the filament is
loaded, and the A1 parks tray_now back at 255 the moment a print ends.
Gated on exactly one slot with usage, like the internal writer: a multi-colour
print moves tray_now on every change, so one reading cannot then be attributed
to one slot. It also declines when the log holds more than one switch, because
an AMS-backup runout is split per segment (#1793) and a single-tray mapping
would land the whole print on one spool.
That gate needed the guess warning to exclude the split path too. The split
never reads slot_to_tray at all -- it charges each segment to the tray the
printer announced switching to, which is the same evidence this fallback is
built on -- so a declined mapping there is not a guess, and calling it one
suppressed the archive rewrite for exactly the prints whose attribution is best
supported. Nothing covered that combination; a test does now.
Where nothing names a tray the positional default still stands, because it is
right for an AMS loaded in slicer order. It now says so at warning level so a
support bundle carries the reason, and it no longer restamps the archive's
filament colour and material from a spool it picked by position. That restamp
is what made the fault read as data loss: the grams can be put back, whereas
overwriting what the slicer recorded leaves nothing to compare against, and the
reporter's archive had already been rewritten from #000000 to the wrong spool's
grey. A slot that consumed nothing also stops claiming a tray in the handled
set -- it was never charged, so the remain-delta path should stay free to cover
it rather than be suppressed by an estimate of zero.
The request-topic probe is the same failure reached from the other side. A
printer that refuses kills the TCP connection instead of returning a SUBACK
failure, so the only signal is "we subscribed, then got disconnected", and that
was believed the first time it happened. Every other reason a connection drops
inside the same window looks identical -- a network blip, the printer
rebooting, the container stopped mid-probe -- and the verdict was cached per
serial with no re-probe anywhere, so on a printer that supports the topic one
unlucky drop cost mapping capture for the rest of the process and every slicer
print after it was charged by tray position. It now takes two consecutive
drops, and a disconnect we asked for is not counted. A printer that genuinely
refuses answers the same way every time and pays one extra reconnect; one
already known to refuse still skips the subscription outright rather than
reopening a reconnect loop.
Bambuddy
Your printers. No cloud. Your rules.
Self-hosted command center for Bambu Lab — from one A1 to an entire print farm.
Backed by
🎮 Try the Live Demo • Features • Screenshots • Quick Start • Documentation • Discord • Contributing
Spin up your own private Bambuddy in ~10 seconds — no install, no signup, 30-minute session.
Important
H2-series and P2S owners — how you send a print decides what gets archived. Bambu Studio's Print button sends sliced files to the printer's internal memory, which Bambuddy cannot read — so those prints archive with a name and timing but no thumbnail, filament total or cost. The printer's "Store sent files on external storage" option does not change it (measured on an H2C and an H2D with it enabled); BambuStudio#10481 tracks the default upstream. Start the print from Bambuddy, or slice in OrcaSlicer — both put the file on the card in one step. Staying in Bambu Studio means using Send with External picked and starting the print afterwards, because Print itself offers no choice. All of them need a card or stick in the printer; X1 and P1 series are unaffected. Why this happens →
📰 As Featured In
"Bambuddy is the companion app that Bambu Lab should have built from day one." — Adam Conway, XDA-Developers
Two leading 3D-printing publications independently concluded that Bambuddy's feature set already exceeds Bambu's own cloud:
"The features seem to exceed those provided by Bambu Lab's own cloud." — Fabbaloo
"The list of functions seems so extensive that it even goes beyond what Bambu Lab offers in its own cloud." — 3Druck.com
🌐 NEW: Remote Printing with Proxy Mode
Print from anywhere in the world — Bambuddy's new Proxy Mode acts as a secure relay between your slicer and printer:
- 🔒 End-to-end TLS encryption — FTP, file transfer, and camera are transparently proxied with the printer's real TLS certificate
- 🛡️ Optional Tailscale integration — per-VP toggle + Docker socket mount surface the host's Tailscale IP on the VP card, so you know which
100.x.x.xto paste into the slicer when you want a virtual printer reachable over your tailnet (setup). Bambuddy's self-signed CA import is still required on the slicer side: Bambu Studio / OrcaSlicer validate printer TLS against a bundled BBL CA (not the system trust store), and their Add Printer dialog is IP-only (no hostname to match an LE cert against), so a publicly-trusted cert can't help on either dimension. Tailscale's role is the private tunnel (reachability from anywhere, no port forwarding), not cert-import elimination. - 🌍 No cloud dependency — Direct connection through your own Bambuddy server
- 🔑 Uses printer's access code — No additional credentials needed
- ⚡ Full-speed printing — Transparent TCP proxy, only MQTT is decrypted for IP rewriting
Perfect for remote print farms, traveling makers, or accessing your home printer from work.
🍰 NEW: Integrated Slicing — Slice & Print, All In One Place
No desktop slicer required. Drop an STL or 3MF into Bambuddy's File Manager, hit Slice, and the result lands as a ready-to-print .gcode.3mf in the same folder — without ever opening Bambu Studio or Orca Slicer.
- 🍰 One-click slicing — Slice from any browser. The job runs server-side in a tiny sidecar container, progress streams back as a toast, and the sliced file appears in your library when it's done.
- 📱 Slice from your phone or tablet — Bambuddy's PWA + the new server-side slicer means you can drop an STL in from mobile and queue a print without ever touching a desktop.
- 🎒 Bring your own profiles — Import a
Printer Preset Bundle(.bbscfg) exported from Bambu Studio: pick a curated printer + process + filament triplet from a dropdown in the Slice dialog, no more juggling JSON files. - 🔄 Re-slice for a different printer in one click — Open any sliced archive in Bambuddy and re-slice it for any printer, including across the single-nozzle ↔ dual-nozzle (H2D / H2D Pro) boundary that BambuStudio's CLI would normally reject. Bambuddy detects the class change and auto-arranges objects laid out for the source bed (e.g. X1C 256×256) so they land safely on the target (e.g. H2D 350×320 with its per-nozzle dead zones).
- 🍱 Slice all plates at once — Multi-plate projects (parted statues, multi-part kits) get a "Slice all N plates" toggle in the Slice dialog. One click produces a single
.gcode.3mfcontaining every plate's gcode, ready for the printer. The toast shows "Plate 2 of 5 — Generating G-code (47%)" as the loop runs. - 🔁 Same dispatch as the rest of Bambuddy — The sliced output flows into the existing queue / plate-picker / AMS-mapping path, so all the regular conveniences (multi-printer dispatch, AMS routing, scheduled prints) just work.
Optional but recommended — drop the slicer-api/ Compose stack next to your Bambuddy install and the Slice button lights up everywhere.
🧩 NEW: Slicer Pipelines — Save a Recipe, Reuse in One Click
Stop re-picking the same printer + process + filament + bed-type combination every slice. Save a Slicer Pipeline once from the Slice dialog, then apply the whole bundle to any file with a single click — from File Manager, Archives, or MakerWorld imports.
- 🧩 One-click reuse — A pipeline captures the entire Slice modal selection (printer + process + per-AMS-slot filaments + bed type) and surfaces as Run with pipeline → <name> on every sliceable row.
- 🎯 Specific printer or printer class — Pin a pipeline to one printer, or to a class (e.g. any X1C) and let the queue scheduler pick the first available match. Identical-fleet farms get a single recipe instead of one-per-printer.
- 🪢 Multi-copy fanout — Slice once, dispatch up to N copies. With class targeting the copies fan out across the matching printers in parallel — Spread (fastest wall-clock), Single printer (minimise colour-change overhead), or First N (one to each).
- 📊 Runs dashboard — A new Pipelines tab on the Print Queue page lists every run with colour-coded status badges (queued / slicing / dispatching / in-progress / completed / partial-failure / failed / cancelled), per-copy detail on expand, filter dropdowns (Pipeline / Status / Target), and a Retry failed button that re-runs only the copies that didn't complete — successful copies are never re-printed.
- 🔒 Permission-gated — Three permissions (
pipelines:read/pipelines:write/pipelines:run) let you split authoring the recipe from spending filament with it.
Why Bambuddy?
- Own your data — All print history stored locally, no cloud dependency
- Works offline — Uses Developer Mode for direct printer control via local network
- Full automation — Schedule prints, auto power-off, get notified when done
- Multi-printer support — Manage your entire print farm from one interface
✨ Features
📦 Print Archive
📊 Monitoring & Control
⏰ Scheduling & Automation
📁 File Manager (Library)
🌍 MakerWorld Integration
📁 Projects
|
🔔 Notifications
🧵 Spool Inventory
🔧 Integrations
🖨️ Virtual Printer & Remote Printing
🛠️ Maintenance & Support
🔒 Optional Authentication
|
Plus: Configurable slicer (Bambu Studio / OrcaSlicer) • Customizable themes (style, background, accent) • Mobile responsive • Keyboard shortcuts • Multi-language (EN/DE/JA/IT) • Auto updates • Database backup/restore • System info dashboard
🎬 Demo
Spin up your own private Bambuddy with simulated printers and pre-loaded print history. Click around freely — it's your sandbox. ~10 seconds to spawn, 30-minute session, no signup.
Prefer a video walkthrough?
Click to watch the demo on YouTube
📸 Screenshots
Refreshed printer card in 1.2.5b2 — tighter layout, popovers for all controls (temperature setpoints, fan speeds, jog), and a bottom-aligned power row. The screenshots below predate the refresh.
Click to expand screenshots
Real-time printer monitoring with AMS status
Print archive with 3D preview and project assignment
Re-print with AMS filament mapping preview
Built-in timelapse editor with trim, speed, and music
Group related prints into projects
Project detail view with assigned archives
Project timeline and print history
Print scheduling and queue management
Schedule prints for specific date and time
Customizable statistics dashboard
Maintenance tracking per printer
Configure maintenance types and intervals
Bambu Cloud filament profiles
Edit filament preset settings
Pressure advance (K-factor) profiles
Edit K-factor profile settings
General configuration and integrations
Smart plug control and energy monitoring
Multi-provider notification system
API keys and webhook endpoints
Virtual printer configuration
Virtual printer appears in Bambu Studio/Orca Slicer
MQTT debug logging for troubleshooting
Quick power plug control in sidebar
🚀 Quick Start
Requirements
- Python 3.10+ (3.11/3.12 recommended)
- Bambu Lab printer with Developer Mode enabled (see below)
- "Store sent files on external storage" enabled in Bambu Studio/OrcaSlicer
- Same local network as printer
Installation
Windows (Native Installer)
Self-contained .exe — no Python, Node, Docker, or Git required on the target machine. The installer bundles Python 3.13, the React frontend, ffmpeg, and registers Bambuddy as a Windows service.
Download the latest installer:
https://github.com/maziggy/bambuddy/releases/latest/download/bambuddy-windows-x64-setup.exe
Run it (one-time UAC prompt — admin install) → Bambuddy starts as a Windows service and the dashboard opens at http://localhost:8000 automatically. Data lives at C:\ProgramData\Bambuddy\, install at C:\Program Files\Bambuddy\. To update, just run a newer installer over the existing install — your database and archives are preserved.
SmartScreen warning: until our SignPath OSS code-signing approval lands, you'll see "Windows protected your PC" on first run. Click More info → Run anyway.
See the Windows Installer Guide for service management, logs, and troubleshooting.
Docker (Linux / macOS / Windows via Docker Desktop)
Option A: Pre-built image (fastest)
mkdir bambuddy && cd bambuddy
curl -O https://raw.githubusercontent.com/maziggy/bambuddy/main/docker-compose.yml
docker compose up -d
Option B: Build from source
git clone https://github.com/maziggy/bambuddy.git
cd bambuddy
docker compose up -d --build
Open http://localhost:8000 in your browser.
Multi-architecture support: Pre-built images are available for
linux/amd64andlinux/arm64(Raspberry Pi 4/5).
macOS/Windows users: Docker Desktop doesn't support
network_mode: host. Edit docker-compose.yml: comment outnetwork_mode: hostand uncomment theports:section. Printer discovery won't work - add printers manually by IP.
Linux users: If you get "permission denied" errors, either prefix commands with
sudo(e.g.,sudo docker compose up -d) or add your user to the docker group.
Docker Configuration & Commands
Environment Variables:
| Variable | Default | Description |
|---|---|---|
TZ |
UTC |
Your timezone (e.g., America/New_York, Europe/Berlin) |
PORT |
8000 |
Port BamBuddy runs on (with host networking mode) |
DEBUG |
false |
Enable debug logging |
LOG_LEVEL |
INFO |
Log level: DEBUG, INFO, WARNING, ERROR |
Data Persistence:
| Volume | Purpose |
|---|---|
bambuddy.db |
SQLite database with all your print data (not used with PostgreSQL) |
archive/ |
Archived 3MF files and thumbnails |
logs/ |
Application logs |
Updating:
# Pre-built image: just pull the latest
docker compose pull && docker compose up -d
# From source: rebuild after pulling changes
cd bambuddy && git pull && docker compose up -d --build
Daily Beta Builds:
Beta builds with the latest fixes are pushed regularly to the same beta version tag:
# Pull the current beta
docker pull ghcr.io/maziggy/bambuddy:0.2.2b1
# or from Docker Hub
docker pull maziggy/bambuddy:0.2.2b1
Use Watchtower (image nickfedor/watchtower) to automatically update when new daily builds are pushed.
Note: Beta builds use version tags like
0.2.2b1— they are never tagged aslatest. Your stable installation won't auto-update to a beta unless you explicitly pull a beta tag.
Useful Commands:
# View logs
docker compose logs -f
# Stop/Start
docker compose down
docker compose up -d
# Shell access
docker compose exec bambuddy /bin/bash
Custom Port:
ports:
- "3000:8000" # Access on port 3000
Reverse Proxy (Nginx):
server {
listen 443 ssl http2;
server_name bambuddy.yourdomain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 86400;
}
}
Note: WebSocket support is required for real-time printer updates.
Network Mode Host (required for printer discovery and camera streaming):
services:
bambuddy:
build: .
network_mode: host
Note: Docker's default bridge networking cannot receive SSDP multicast packets for automatic printer discovery. When using
network_mode: host, Bambuddy auto-detects your network subnet and can discover printers via subnet scanning in the Add Printer dialog.
Manual Installation (Linux/macOS)
# Clone and setup
git clone https://github.com/maziggy/bambuddy.git
cd bambuddy
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Run (--loop asyncio avoids a uvloop TLS bug that can truncate VP FTP uploads)
uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --loop asyncio
Open http://localhost:8000 and add your printer!
Need detailed instructions? See the Installation Guide
Windows Native Installation
Windows PowerShell (run as Administrator — the installer self-elevates via UAC if not):
powershell -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/maziggy/bambuddy/main/install/windows-installer.ps1 -OutFile windows-installer.ps1; .\windows-installer.ps1"
Installs Bambuddy natively on Windows using Git, Python, a virtual environment, separate data/log directories, and optional NSSM Windows Service registration. See the Windows Installer Guide for parameters and unattended-install options.
Enabling Developer Mode
Developer Mode allows third-party software like Bambuddy to control your printer over the local network.
- On printer: Settings → Network → LAN Only Mode → Enable
- Enable Developer Mode (appears after LAN Only Mode is enabled)
- Note the Access Code displayed
- Find IP address in network settings
- Find Serial Number in device info
Note: Developer Mode disables cloud features but provides full local control. Standard LAN Mode (without Developer Mode) only allows read-only monitoring.
Slicer Settings
In Bambu Studio or OrcaSlicer, enable "Store sent files on external storage" so that print files (3MF) are saved to the printer's SD card. Bambuddy needs these files to extract thumbnails and 3D model previews.
- Open Bambu Studio or OrcaSlicer
- Go to the Device tab for your printer
- In Print Options, enable Store Sent Files on External Storage
📚 Documentation
Full documentation available at wiki.bambuddy.cool:
- Installation — All installation methods
- Getting Started — First printer setup
- Features — Detailed feature guides
- Troubleshooting — Common issues & solutions
- API Reference — REST API documentation
🖨️ Supported Printers
| Series | Models |
|---|---|
| X1 | X1, X1 Carbon, X1E |
| X2 | X2D |
| H2 | H2D, H2D Pro, H2C, H2S |
| P1 | P1P, P1S |
| P2 | P2S |
| A1 | A1, A1 Mini |
| A2 | A2L |
🛠️ Tech Stack
| Component | Technology |
|---|---|
| Backend | Python, FastAPI, SQLAlchemy |
| Frontend | React, TypeScript, Tailwind CSS |
| Database | SQLite (default) or PostgreSQL |
| 3D Viewer | Three.js |
| Communication | MQTT (TLS), FTPS |
🤝 Contributing
Contributions welcome! Ways to help:
- 📝 Document — Improve the wiki and guides (urgently needed!)
- Test — Report issues with your printer model
- Translate — Add new languages
- Code — Submit PRs for bugs or features
- 🔒 Security review — (specifically wanted, see below)
Not sure where to start? Reach out on Discord or email martin@bambuddy.cool — I'll help you find something that fits.
🔒 Looking for a security-focused contributor
I'm bringing on a contributor whose specific focus is keeping an eye on Bambuddy's security.
Concretely:
Track the dev branch and flag changes touching auth, permissions, token handling, or the CI security backstops. Async post-merge — no gating of in-flight PRs.
What matters more than formal qualifications: fail-closed thinking by default, comfortable reading the auth layer (FastAPI + SQLAlchemy on the backend, a small React surface), willing to push back on except Exception shapes in security-sensitive code.
No fixed time commitment. If you're interested — or know someone who fits — email martin@bambuddy.cool or DM on Discord.
See CONTRIBUTING.md for guidelines.
📄 License
AGPL-3.0 License — see LICENSE for details.
🙏 Acknowledgments
- SpoolEase by yanshay — early inspiration for NFC-based spool tracking and AMS inventory concepts
- Bambu Lab for amazing printers
- The reverse engineering community for protocol documentation
- All testers and contributors
💖 Support Bambuddy
Bambuddy stays independent because real people support it directly. If Bambuddy makes your printers more useful, please consider:
- GitHub Sponsors — five recurring tiers from $5/mo (Backer) to $300/mo (Corporate). Supporter+ ($15/mo) get access to a private sponsors space with a monthly newsletter and early release notes. Patron+ ($35/mo) vote on the quarterly roadmap. Sustaining Sponsor+ ($150/mo) get a direct async email line for technical questions (~2-3 business days). Corporate ($300/mo) get priority email response (next business day), README header logo, sitewide footer logo on bambuddy.cool, and Press page placement.
- Ko-fi — one-time tip or recurring.
Sponsors get listed in BACKERS.md. Need commercial support (SLA, multi-printer consulting)? Email martin@bambuddy.cool.
Made with ❤️ for the 3D printing community
Join our Discord •
Report Bug •
Request Feature •
Documentation