ben/Bambu-Run
1
0
Fork 0
mirror of https://github.com/RunLit/Bambu-Run.git synced 2026-06-22 22:19:03 +01:00
Code Issues Packages Projects Releases Wiki Activity

Filament tools that help upload bambu colors and filament types easily (#3)

Browse Source 
* added cover image

* bambu color import manage tool added

* added AMS hex color trimming

* updated instructions

* touch up readme

* fixed line chart noise x axis and add more date marker to split them up
This commit is contained in:
RunLit
2026-02-25 23:07:24 +11:00
committed by GitHub
parent ab6a7c0bcc
commit 5984bd6fa0
18 changed files with 1240 additions and 282 deletions
Download Patch File Download Diff File Expand all files Collapse all files

314
README.md
View File

@@ -1,239 +1,271 @@
# Bambu-Run
Unlock richer data access and powerful customization capabilities for your Bambu Lab 3D printer.
<p align="center">
<img src="docs/BambuRun.png" alt="Bambu-Run Logo" width="300"/>
</p>
Bambu-Run is a self-hosted web dashboard that tracks data of your Bambu Lab printer. It gives you:
- Real-time monitoring and logging (temperatures, fan speeds, print progress etc)
- Automatic filament inventory tracking and usage monitoring system (AMS required)
all running on hardware you own.
Richer data, powerful customization for your Bambu Lab 3D printer.
### Hardware Requirement
Bambu-Run is a self-hosted web dashboard that gives you:
- Real-time monitoring and logging (temperatures, fan speeds, print progress, and more)
- Automatic filament inventory tracking and usage monitoring (AMS required)
Recommend a raspberry pi, installed with Raspberry Pi OS (low cost running at the background) or an old PC/Laptop you probably never going to use again (install Linux).
## Getting Started (Beginner Friendly)
This guide walks you through setting up Bambu-Run on a **Raspberry Pi** from scratch. No prior server experience needed.
All running on hardware you own.
### What You'll Need
- A Raspberry Pi (3B+, 4, or 5) with Raspberry Pi OS installed and connected to your network
- Your Bambu Lab printer on the **same local network** as the Pi
- Your printer's **IP address**, **access token**, and **serial number** (we'll show you how to find these below)
- A computer on the same network to SSH into the Pi
Any always-on device works — a **Raspberry Pi** (3B+, 4, or 5) is ideal: beginner-friendly, runs Raspberry Pi OS out of the box, and quiet enough to tuck behind a desk. An old PC or laptop with Linux works too.
### Step 1: Find Your Bambu Lab Account Credentials
It runs quietly in the background 24/7, capturing every print, filament change, and AMS update the moment it happens. And the power bill? A Raspberry Pi 4 under light load draws about **5W**. That's roughly **43.8 kWh per year**, or the cost of **three cups of coffee**. ☕☕☕ Tuck it out of sight and forget it's there.
Bambu-Run connects to your printer through the **Bambu Lab Cloud** using your account login — the same email and password you use for Bambu Handy or Bambu Studio.
---
You'll need:
- **BAMBU_USERNAME** — Your Bambu Lab account email
- **BAMBU_PASSWORD** — Your Bambu Lab account password
## Table of Contents
> **First-time login requires email verification.** Bambu Lab will send a 6-digit code to your email. You'll enter this code during Step 5a below. After that, you'll receive a token that skips verification on future startups.
- [Quick Start: One-Click Docker Setup — Beginner Friendly](#quick-start-one-click-docker-setup--beginner-friendly)
- [What You'll Need](#what-youll-need)
- [Step 1: Connect to Your Raspberry Pi](#step-1-connect-to-your-raspberry-pi)
- [Step 2: Install Docker](#step-2-install-docker)
- [Step 3: Download and Configure](#step-3-download-and-configure)
- [Step 4: Build the Container](#step-4-build-the-container)
- [Step 5: First-Time Authentication](#step-5-first-time-authentication)
- [Step 6: Start Bambu-Run and Create Your Login](#step-6-start-bambu-run-and-create-your-login)
- [Step 7: Open the Dashboard](#step-7-open-the-dashboard)
- [Troubleshooting](#troubleshooting)
- [Batch Importing Filament Colors and Filament Types](#batch-importing-filament-colors-and-filament-types)
### Step 2: Connect to Your Raspberry Pi
---
From your computer, open a terminal (Mac/Linux) or PowerShell (Windows) and SSH into the Pi:
## Quick Start: One-Click Docker Setup — Beginner Friendly
Get Bambu-Run running on a **Raspberry Pi** in minutes. No prior server experience needed.
### What You'll Need
- A Raspberry Pi (3B+, 4, or 5) running Raspberry Pi OS 64-bit, with a 32 GB+ MicroSD card, connected to your network
- Your Bambu Lab printer on the **same local network**
- Your Bambu Lab account **email and password**
- A computer to SSH into the Pi
### Step 1: Connect to Your Raspberry Pi
From your computer, open a terminal (Mac/Linux) or PowerShell (Windows):
```bash
ssh pi@raspberrypi.local
```
> If `raspberrypi.local` doesn't work, use your Pi's IP address instead (check your router's admin page to find it).
> Can't connect? Use your Pi's IP address (find it in your router's admin page). Default password: `raspberry`
The default password is `raspberry` (you should change it after first login with `passwd`).
### Step 3: Install Docker
Docker lets you run Bambu-Run in a container — no need to install Python, databases, or anything else manually.
Run these commands one at a time:
### Step 2: Install Docker
```bash
# Download and run Docker's install script
curl -fsSL https://get.docker.com | sudo sh
# Let your user run Docker without sudo
sudo usermod -aG docker $USER
```
Installation issue? check installation methods for raspberry pi: https://docs.docker.com/engine/install/raspberry-pi-os/#installation-methods
**Important:** Log out and log back in for the group change to take effect:
Log out and back in for the change to take effect, then verify:
```bash
exit
```
Then SSH back in:
```bash
ssh pi@raspberrypi.local
docker --version # should show Docker version 27.x.x
```
Verify Docker is working:
> Installation issues? See: https://docs.docker.com/engine/install/raspberry-pi-os/
### Step 3: Download and Configure
```bash
docker --version
```
You should see something like `Docker version 27.x.x` — the exact number doesn't matter.
### Step 4: Download and Configure Bambu-Run
```bash
# Clone the project
git clone https://github.com/RunLit/Bambu-Run.git
cd Bambu-Run
# Create your configuration file
cp .env.example .env
```
Now edit the `.env` file with your printer details:
```bash
nano .env
```
Fill in your Bambu Lab account credentials from Step 1:
Fill in your Bambu Lab credentials:
```
BAMBU_USERNAME=your_email@example.com
BAMBU_PASSWORD=your_password
TIMEZONE=Australia/Melbourne # optional — find yours at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
```
Optionally set your timezone (defaults to UTC):
Save: `Ctrl + X`, `Y`, `Enter`
```
TIMEZONE=Australia/Melbourne
```
> You can find your timezone name at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
To save and exit nano: press `Ctrl + X`, then `Y`, then `Enter`.
### Step 5: Build and Start Bambu-Run
First, build the container:
### Step 4: Build the Container
```bash
docker compose build
```
This downloads all required software (takes a few minutes the first time).
This takes a few minutes the first time — it downloads all required software.
### Step 5a: First-Time Authentication
### Step 5: First-Time Authentication
The first time you connect, Bambu Lab requires email verification. You need to run the collector **interactively** (not in the background) so you can enter the 6-digit code.
First, set up the database:
Bambu Lab requires email verification on first login. Run these two commands:
```bash
docker compose run --rm bambu-run python standalone/manage.py migrate --noinput
```
Then run the collector (this is what triggers Bambu Lab to send the verification email):
```bash
docker compose run --rm bambu-run python standalone/manage.py bambu_collector --once
```
You'll see output like:
When prompted, enter the 6-digit code sent to your email. On success you'll see a token printed — copy it and add it to your `.env`:
```
BambuLab Authentication
Authenticating as: your_email@example.com
...
EMAIL VERIFICATION REQUIRED
A verification code has been sent to your email.
Enter verification code:
```bash
nano .env
```
1. Check your email for the 6-digit code from Bambu Lab
2. Type the code and press Enter
3. On success, you'll see a token printed:
```
Authentication successful!
Token: eyJhbGciOiJIUzI1N...
TIP: Save this token to BAMBU_TOKEN env var to skip login next time
```
```
BAMBU_TOKEN=eyJhbGciOiJIUzI1N...paste_full_token_here
```
4. **Copy the full token** and paste it into your `.env` file:
```bash
nano .env
```
Add/uncomment the `BAMBU_TOKEN` line:
```
BAMBU_TOKEN=eyJhbGciOiJIUzI1N...paste_full_token_here
```
> Saving the token lets future restarts skip re-verification automatically.
> **Why save the token?** With the token saved, future container restarts authenticate instantly without needing email verification again. Without it, you'd need to repeat this step every time the container restarts.
### Step 5b: Start Bambu-Run
Now start everything in the background:
### Step 6: Start Bambu-Run and Create Your Login
```bash
docker compose up -d
```
Check that it's running:
```bash
docker compose ps
```
You should see the `bambu-run` service with status `Up`.
### Step 6: Create Your Login Account
```bash
docker compose exec bambu-run python standalone/manage.py createsuperuser
```
You'll be prompted to choose a username, email (optional), and password. This is your login for the dashboard.
Choose a username and password — this is your dashboard login.
### Step 7: Open the Dashboard
On any device connected to your network (phone, tablet, computer), open a browser and go to:
On any device on your network, open a browser and go to:
```
http://raspberrypi.local:8000
```
> If that doesn't work, use your Pi's IP address: `http://<pi-ip-address>:8000`
> If that doesn't work, use your Pi's IP: `http://<pi-ip-address>:8000`
Log in with the account you just created. You should see your printer dashboard with live data flowing in.
Log in with the account you just created. Your printer dashboard should be live.
### Troubleshooting
**"Cannot connect to printer" or no data showing:**
- Make sure your printer is turned on and connected to the network
- Check the logs: `docker compose logs -f`
- If you see authentication errors, your token may have expired — re-run Step 5a to get a fresh token
**No data / cannot connect to printer:** Make sure the printer is on and on the same network. Check logs: `docker compose logs -f`. If you see auth errors, re-run Step 5 to get a fresh token.
**"Verification code" or "401 Unauthorized" errors:**
- Your `BAMBU_TOKEN` may have expired. Remove it from `.env` and re-run Step 5a
- Make sure `BAMBU_USERNAME` and `BAMBU_PASSWORD` are correct in your `.env` file
**401 Unauthorized / verification loop:** Remove `BAMBU_TOKEN` from `.env` and re-run Step 5.
**"Cannot connect to Docker daemon":**
- Did you log out and back in after Step 3? Docker group changes require a new session
**Docker daemon error:** Log out and back in after Step 2 — the group change requires a new session.
**Dashboard not loading in browser:**
- Verify the container is running: `docker compose ps`
- Try using the Pi's IP address instead of `raspberrypi.local`
**Dashboard not loading:** Run `docker compose ps` to confirm the service is `Up`, then try the Pi's IP address directly.
**Updating to a newer version:**
**Update Bambu-Run:**
```bash
cd ~/Bambu-Run
git pull
docker compose up -d --build
cd ~/Bambu-Run && git pull && docker compose up -d --build
```
**Stopping Bambu-Run:**
**Stop Bambu-Run:**
```bash
docker compose down
```
Your data is preserved in a Docker volume and will be there when you start it again.
---
## Batch Importing Filament Colors and Filament Types
Bambu-Run ships with a full Bambu Lab color catalog under `docs/Bambu_Color_Catalog/` (one `.txt` file per filament sub-type, e.g. `PLA Basic.txt`, `PETG HF.txt`). Importing these populates the **Filament Colors** database so the dashboard shows proper color names instead of raw hex codes.
### Adding your own colors
Need a filament type that isn't in the bundled catalog? Create your own `.txt` file and point the importer at it.
**File naming** — the filename determines the filament type and sub-type:
```
PLA Basic.txt → type: PLA, sub-type: PLA Basic
PETG HF.txt → type: PETG, sub-type: PETG HF
ABS.txt → type: ABS, sub-type: ABS
```
**File format** — list each color on its own line, either as two rows (name then hex) or on the same line:
```
Jade White
Hex:#FFFFFF
Black Walnut #4F3F24
```
Bambu Lab's website filament pages and their downloadable PDF catalogs are a reliable source — both list color names alongside hex codes you can copy directly.
### When to run this
Run the import **once after first setup** to seed the full color catalog in one go, rather than adding colors one by one. Run it again any time you want to add colors for a new filament type. Re-running is always safe — duplicates are detected and skipped automatically.
### Import all colors (recommended)
If the container is already running (`docker compose up -d`):
```bash
docker compose exec bambu-run python standalone/manage.py bambu_import_colors docs/Bambu_Color_Catalog/
```
If the container is not running yet:
```bash
docker compose run --rm bambu-run python standalone/manage.py bambu_import_colors docs/Bambu_Color_Catalog/
```
### Import a file from your computer
If your `.txt` color file lives on your Mac, Pi, or any machine running Docker (i.e. not inside the repo), copy it into the container first, then run the importer:
```bash
# Step 1 — copy the file from your machine into the container
docker compose cp /path/to/your/PLA\ Basic.txt bambu-run:/tmp/
# Step 2 — run the importer against the copied path
docker compose exec bambu-run python standalone/manage.py bambu_import_colors /tmp/PLA\ Basic.txt
```
To import a whole folder of files at once:
```bash
# Step 1 — copy the folder
docker compose cp /path/to/your/color_catalog/ bambu-run:/tmp/color_catalog/
# Step 2 — import everything in it
docker compose exec bambu-run python standalone/manage.py bambu_import_colors /tmp/color_catalog/
```
> **macOS tip:** You can drag a file from Finder into the terminal to paste its full path.
### Import a single filament type
To import only one sub-type from the bundled catalog (e.g. just PLA Basic):
```bash
docker compose exec bambu-run python standalone/manage.py bambu_import_colors "docs/Bambu_Color_Catalog/PLA Basic.txt"
```
### Preview before importing (dry run)
Check what would be added without writing anything to the database:
```bash
docker compose exec bambu-run python standalone/manage.py bambu_import_colors docs/Bambu_Color_Catalog/ --dry-run
```
### What the output means
```
Processing: PLA Basic.txt → type='PLA' sub_type='PLA Basic'
Parsed 40 color(s).
+ 'Bambu Green' #009F87 (PLA / PLA Basic)
+ 'Jade White' #FFFFFF (PLA / PLA Basic)
...
──────────────────────────────────────────────────
Created: 40
Skipped (duplicate): 0
```
- **Created** — new color entries added to the database
- **Skipped (duplicate)** — already existed, not changed
- **Skipped (no type)** — only shown if `--no-auto-create-filament-type` is used and the filament type isn't in the database yet