mirror of
https://github.com/maziggy/bambuddy.git
synced 2026-09-30 03:01:21 +02:00
maziggy
d5153f1de3
End-to-end live progress, two correctness fixes, and a UX warning around
the upstream OrcaSlicer bugs we discovered while testing.
LIVE PROGRESS
=============
Wire OrcaSlicer / BambuStudio's --pipe progress channel through the
sidecar -> Bambuddy -> persistent toast so a user-initiated slice shows
"{name} -- Generating G-code (75%) -- 47s" instead of just elapsed time.
The same wiring covers the SliceModal's filament-analysis preview slice
(the real slice that fires before profile picking, used to discover
which AMS slots an unsliced plate consumes) and the embedded-settings
fallback path triggered by Orca's --load-settings segfault on complex
H2D models.
- Sidecar (orca-slicer-api/bambuddy/profile-resolver, separate commit):
switch /slice from execFile to spawn, mkfifo per request, parse the
CLI's structured JSON progress events into a per-process
ProgressStore, expose GET /slice/progress/:requestId.
- Bambuddy backend: slicer_api.slice_with_profiles + slice_without_profiles
accept request_id + on_progress, spawn a 1Hz parallel poller that
forwards each snapshot via SliceDispatchService.set_progress(job_id,
...) onto the matching SliceJob; GET /slice-jobs/:id includes the
latest snapshot on every poll. The 404 from the early-race window
(POST fired before sidecar's progressStore.start) is treated as a
retry rather than terminal -- otherwise the poller bailed before any
progress could ever arrive.
- /api/v1/slicer/preview-progress/:requestId proxies the sidecar's
progress endpoint for the modal's filament-discovery flow (the
/filament-requirements call is server-originated; the browser can't
reach the sidecar directly).
- Frontend: SliceJobTrackerContext re-renders the persistent toast with
the new format when a useful progress frame is present, falls back
to elapsed-time-only when the sidecar hasn't emitted yet or doesn't
support progress. SliceModal.FilamentAnalysisSpinner generates a
per-(source, plate) UUID, polls the proxy at 1Hz, and mirrors the
inline spinner contents into a separate persistent toast so the
preview slice doesn't feel silent either.
CORRECTNESS FIXES
=================
- MakerWorld imports were persisting URL-encoded filenames verbatim
("stormtrooper-helmet%20h2d.3mf"). Backend now urllib.parse.unquote
s the manifest-supplied name and the URL path-tail fallback before
passing to save_3mf_bytes_to_library; frontend defensively
decodeURIComponent s in the slice toast / analysis spinner so
already-imported rows display cleanly without a backfill migration.
- The fallback path's slice_without_profiles call now forwards the
same request_id + on_progress as the primary slice_with_profiles
call so the toast keeps updating across the segfault -> embedded-
settings retry boundary instead of going blank.
ORCASLICER WARNING
==================
Verified two upstream OrcaSlicer CLI bugs reproduce on the latest
nightly (2.4.0-dev, 2026-04-28) with the help of an isolated AppImage
extract and a minimal sentinel-value-injected cube fixture:
- OrcaSlicer/OrcaSlicer#12426 -- SIGSEGV in
update_values_to_printer_extruders_for_multiple_filaments on
painted multi-extruder 3MFs (commented on the existing thread,
not a new issue)
- OrcaSlicer/OrcaSlicer#13386 -- CLI strict-validates parameter
values BambuStudio writes by default (solid_infill_filament: 0,
tree_support_wall_count: -1, prime_tower_brim_width: -1) and
rejects with exit 238, even though Orca's own GUI tolerates
them (filed by us alongside this change)
Settings -> Workflow -> Slicer card renders an amber inline warning
under the preferred-slicer dropdown when orcaslicer is selected,
linking both upstream issues and recommending BambuStudio until the
fixes land. Option stays pickable -- users who only slice STLs aren't
affected by either bug.
Bambuddy
Self-hosted print archive and management system for Bambu Lab 3D printers
Features • Screenshots • Quick Start • Documentation • Forum • Discord • Contributing
📣 Contributors Wanted — Help Shape Bambuddy
Bambuddy is a community-driven project and I'm actively looking for contributors — especially for two areas I can't cover alone:
- 📝 Documentation writers — help improve the wiki, guides, and feature docs so new users have a smooth onboarding
- ⚙️ Discourse admin — our Discourse forum is now live at forum.bambuddy.cool but still needs to be configured, themed, and tuned (categories, permissions, SSO, email, plugins, backups). If you know Discourse or want to dig in, I'd love your help.
- 💬 Forum moderators — help welcome newcomers, answer questions, and keep discussions healthy on the new forum
You don't need to be a developer for the docs or moderator roles. If you enjoy writing, helping others, or keeping a community friendly, you're exactly who we're looking for.
Get in touch:
- 🗣️ Forum — chats, longer discussions, guides, and community Q&A
- 💬 Discord — fastest way to chat
- 🐙 GitHub Discussions — open a thread
- 📧 martin@bambuddy.cool — email Martin directly (no GitHub or Discord needed)
🌐 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 brings Bambuddy into your tailnet, so virtual printers are reachable from any tailnet device over a private WireGuard tunnel without port forwarding (setup). Bambuddy's self-signed CA import is still required for the slicer side because both Bambu Studio and OrcaSlicer only accept IP addresses in the Add Printer dialog — the Tailscale benefit here is the tunnel, 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.
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
Click to watch the demo on YouTube
📸 Screenshots
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
Docker (Recommended)
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 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
uvicorn backend.app.main:app --host 0.0.0.0 --port 8000
Open http://localhost:8000 and add your printer!
Need detailed instructions? See the Installation Guide
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 |
🛠️ 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! I'm especially looking for help with documentation and our new Discourse forum — see Contributors Wanted above. Other ways to help:
- 📝 Document — Improve the wiki and guides (urgently needed!)
- ⚙️ Admin Discourse — Help configure and tune the forum (urgently needed!)
- 💬 Moderate — Welcome newcomers and keep forum discussions healthy (urgently needed!)
- Test — Report issues with your printer model
- Translate — Add new languages
- Code — Submit PRs for bugs or features
Not sure where to start? Reach out on Discord, post on the forum, or email martin@bambuddy.cool — I'll help you find something that fits.
# Development setup
git clone https://github.com/maziggy/bambuddy.git
cd bambuddy
# Backend
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
DEBUG=true uvicorn backend.app.main:app --reload
# Frontend (separate terminal)
cd frontend && npm install && npm run dev
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
If you like Bambuddy and want to support it, you can buy Martin a coffee.
Made with ❤️ for the 3D printing community
Forum •
Join our Discord •
Report Bug •
Request Feature •
Documentation