From a06842be3e3d4d83c9281442fff8c4f5b9184aeb Mon Sep 17 00:00:00 2001 From: RNL Date: Tue, 24 Feb 2026 23:39:51 +1100 Subject: [PATCH] updated instructions --- README.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 130 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 43f73bc..26ef50e 100644 --- a/README.md +++ b/README.md @@ -7,13 +7,35 @@ Unlock richer data access and powerful customization capabilities for your Bambu Lab 3D printer. 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) +- 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. -### Hardware Requirement +### What You'll Need -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). +Any always-on device: +- A **Raspberry Pi** (3B+, 4, or 5) is ideal: beginner-friendly, runs Raspberry Pi OS out of the box, and silent enough to tuck behind a desk. +- Or an old PC or laptop with Linux works too. + +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. + +--- + +## Table of Contents + +- [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) + +--- ## Quick Start: One-Click Docker Setup — Beginner Friendly @@ -21,7 +43,7 @@ Get Bambu-Run running on a **Raspberry Pi** in minutes. No prior server experien ### What You'll Need -- A Raspberry Pi (3B+, 4, or 5) with Raspberry Pi OS, connected to your network +- 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 @@ -146,3 +168,107 @@ 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 can show 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 + +When you're lazy and don't want to add all possible color by manual input. + +Run the import **once after first setup**, and again any time you want to add colors for a new filament type. Re-running is 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