diff --git a/README.md b/README.md index 58ea1eb..43f73bc 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # Bambu-Run +

+ Bambu-Run Logo +

+ 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: @@ -11,227 +15,132 @@ all running on hardware you own. 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) +## Quick Start: One-Click Docker Setup — Beginner Friendly -This guide walks you through setting up Bambu-Run on a **Raspberry Pi** from scratch. No prior server experience needed. +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) 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 +- A Raspberry Pi (3B+, 4, or 5) with Raspberry Pi OS, 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: Find Your Bambu Lab Account Credentials +### Step 1: Connect to Your Raspberry Pi -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 - -> **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. - -### Step 2: Connect to Your Raspberry Pi - -From your computer, open a terminal (Mac/Linux) or PowerShell (Windows) and SSH into the 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://:8000` +> If that doesn't work, use your Pi's IP: `http://: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 ```