updated instructions

README.md

@@ -11,9 +11,31 @@ Bambu-Run is a self-hosted web dashboard that tracks data of your Bambu Lab prin
 - 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