From a33fff0ee7e70d5377cf821cab1fd1d7100904f4 Mon Sep 17 00:00:00 2001 From: "Markus M." Date: Sun, 30 Nov 2025 18:42:47 +0200 Subject: [PATCH 1/2] Move documentation to GitHub Pages --- README.md | 195 ++++++++--------------------------- docs/auto-spend.md | 17 +++ docs/demo-and-screenshots.md | 26 +++++ docs/deployment.md | 30 ++++++ docs/features.md | 40 +++++++ docs/index.md | 23 +++++ docs/pages-maintenance.md | 23 +++++ docs/setup.md | 25 +++++ 8 files changed, 227 insertions(+), 152 deletions(-) create mode 100644 docs/auto-spend.md create mode 100644 docs/demo-and-screenshots.md create mode 100644 docs/deployment.md create mode 100644 docs/features.md create mode 100644 docs/index.md create mode 100644 docs/pages-maintenance.md create mode 100644 docs/setup.md diff --git a/README.md b/README.md index 84cc75c2..1488f146 100644 --- a/README.md +++ b/README.md @@ -1,152 +1,43 @@ -# logo OpenSpoolMan -Use any filament like Bambu filaments with automatic recognition and filament usage updates in your AMS! - -No need for cloud or any special hardware, just your phone and some NFC tags! - -Similar functionality to https://github.com/spuder/OpenSpool using only your phone, server and NFC tags integrated with SpoolMan - -Everything works locally without cloud access, you can use scripts/init_bambulab.py script to access your PRINTER_ID and PRINTER_CODE if it is not available on your printer. - -Docker: https://ghcr.io/drndos/openspoolman - -### News -- 0.1.3 - 22.12.2024 - Added manual assignment for empty slots -- 0.1.4 - 09.02.2025 - Bugfixes, issue fixing WIP -- 0.1.7 - 17.04.2025 - https://github.com/drndos/openspoolman/releases/tag/v0.1.7 -- 0.1.8 - 20.04.2025 - https://github.com/drndos/openspoolman/releases/tag/v0.1.8 - -### Main features - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Information about your AMSFill tray directly from overviewPrint history
Information about your AMSFill tray directly from overviewPrint history
Assign NFC tags to your spools in SpoolManWrite the URL of the Spool detail to NFC tag directly from the browser
Assign NFC tags to your spools in SpoolManNFC write success
Bring Phone close to the NFC tag and open the spool detailPick the AMS slot where you want the spool to be loaded
Open NFC linkSpool infoPick tray
Automatically track the usage of your filaments based on the slicer estimates in SpoolManTrack Bambu filaments without additional NFC TagsResolve issues with few clicks (soon)
Slicer estimateBambu filament usgae trackingResolve issues
- -### Seeded demo & screenshots -- Export a live snapshot first (default path `data/live_snapshot.json`) with `python scripts/export_live_snapshot.py --output data/live_snapshot.json`. Snapshot-based runs expect this file and will warn if it is missing. -- Load the snapshot-backed test data with `OPENSPOOLMAN_TEST_DATA=1` or `--test-data` on the screenshot helper; override the snapshot path via `OPENSPOOLMAN_TEST_SNAPSHOT` or `--snapshot` when needed. -- Install the core app dependencies via `pip install -r requirements.txt`. Only install the screenshot extras when regenerating docs: `pip install -r requirements-screenshots.txt` followed by `python -m playwright install chromium`. -- Provide your own print-history database (default path `data/demo.db`) or override with `OPENSPOOLMAN_PRINT_HISTORY_DB=/path/to/history.db` or `--print-history-db` when using the screenshot helper. -- Configure which routes and devices get captured via `scripts/screenshot_config.json` (supports per-target or per-screenshot `max_height`, device-specific viewports, and automatic device-prefixed filenames). Override or extend it with `--config ` and target specific devices with `--devices desktop,mobile` when you run the generator. -- Run `python scripts/generate_screenshots.py` to start the app in snapshot-backed test mode, open the configured routes in headless Chromium, and refresh the images under `docs/img/` (or another folder via `--output-dir`). Screenshots default to the viewport height unless a per-target/device `max_height` is set (or `full_page: true`), and `--max-height` provides a config-wide fallback. -- Pass `--color-scheme dark` (or set `color_scheme` in the config) to capture pages in dark mode; omit it to follow the default auto/light behavior. -- To generate pictures from real printer/Spoolman data, run the generator in live mode to start the current app against your configured devices (`python scripts/generate_screenshots.py --mode live --live-readonly`). If you truly need to target a remote instance, pass `--base-url http://:`. Environment variables (`OPENSPOOLMAN_TEST_DATA=1 OPENSPOOLMAN_TEST_SNAPSHOT=data/live_snapshot.json` or `OPENSPOOLMAN_LIVE_READONLY=1`) work as alternatives. When live data is used or captured, the app and scripts automatically load `config.env` from the repository root (if present) so credentials and URLs are available even when running tools from subfolders. -- The script can be called in CI after UI changes to automatically regenerate and version the example screenshots. -- For unit tests, you can reuse the same seeded dataset without environment variables: add `--use-seeded-data` to your pytest command for auto-mocking, request the `seeded_data_overrides` fixture in a test, or wrap your test body in `with test_data.apply_test_overrides(): ...`. -- To generate documentation screenshots inside pytest, run `pytest -m screenshots --generate-screenshots` (optionally pass `--screenshot-output `, `--screenshot-mode live`, `--screenshot-devices `, or `--screenshot-config `); the test will spin up Flask in seeded mode by default and reuse the same capture logic as `scripts/generate_screenshots.py`. - -### What you need: - - Android Phone with Chrome web browser or iPhone (manual process much more complicated if using NFC Tags) - - Server to run OpenSpoolMan with https (optional when not using NFC Tags) that is reachable from your Phone and can reach both SpoolMan and Bambu Lab printer on the network - - Active Bambu Lab Account or PRINTER_ID and PRINTER_CODE on your printer - - Bambu Lab printer https://eu.store.bambulab.com/collections/3d-printer - - SpoolMan installed https://github.com/Donkie/Spoolman - - NFC Tags (optional) https://eu.store.bambulab.com/en-sk/collections/nfc/products/nfc-tag-with-adhesive https://www.aliexpress.com/item/1005006332360160.html - -### How to setup: - - Rename config.env.template to config.env or set environment properies and: - - set OPENSPOOLMAN_BASE_URL - that is the URL where OpenSpoolMan will be available on your network. Must be https for NFC write to work. without trailing slash - - set PRINTER_ID - On your printer clicking on Setting -> Device -> Printer SN - - set PRINTER_ACCESS_CODE - On your printer clicking on Setting -> Lan Only Mode -> Access Code (you _don't_ need to enable the LAN Only Mode) - - set PRINTER_IP - On your printer clicking on Setting -> Lan Only Mode -> IP Address (you _don't_ need to enable the LAN Only Mode) - - set SPOOLMAN_BASE_URL - according to your SpoolMan installation without trailing slash - - set AUTO_SPEND - to True if you want for system to track your filament spending (check AUTO_SPEND issues below) default to False - - Run the server (wsgi.py) - - Run Spool Man - - Add following extra Fields to your SpoolMan: - - Filaments - - "type","Type","Choice","Basic","Silk, Basic, High Speed, Matte, Plus, Flexible, Translucent","No" - - "nozzle_temperature","Nozzle Temperature","Integer Range","°C","190 – 230" - - "filament_id","Filament ID", "Text" - - Spools - - "tag","tag","Text" - - "active_tray","Active Tray","Text - - Add your Manufacturers, Filaments and Spools to Spool Man (when adding filament you can try "Import from External" for faster workflow) - - The filament id can be found in the json files in C:\Users\USERNAME\AppData\Roaming\BambuStudio\user\USERID\filament\base - It is the same for each printer and nozzle. - - Open the server base url in browser on your mobile phone - - Optionally add Bambu Lab RFIDs to extra tag on your Bambu Spools so they will be matching. You can get the tag id from logs or from browser in AMS info. - - With NFC Tags: - - For non Bambu Lab filaments click on the filament and click Write and hold empty NFC tag to your phone (allow NFC in popup if prompted) - - Attach NFC tag to your filament - - Load filament to your AMS by loading it and then putting your phone near NFC tag and allowing your phone to open the website - - On the website pick the slot you put your filament in - - Without NFC Tags: - - Click fill on the tray and select the desired spool - - Done - -### Deployment -Run locally in venv by configuring environment properties and running wsgi.py, supports adhoc ssl. - -Run in docker by configuring config.env and running compose.yaml, you will need more setup/config to run ssl. - -Run in kubernetes using helm chart, where you can configure the ingress with SSL. https://github.com/truecharts/public/blob/master/charts/library/common/values.yaml - -### AUTO SPEND - Automatic filament usage based on slicer estimate -You can turn this feature on to automatically update the spool usage in SpoolMan. -This feature is using slicer information about predicted filament weight usage (and in future correlating it with the progress of the printer to compute the estimate of filament used). - -This feature has currently following issues/drawbacks: - - Spending on the start of the print - - Not spending according to print process and spending full filament weight even if print fails - - Don't know if it works with LAN mode, since it downloads the 3MF file from cloud - - Not tested with multiple AMS systems - - Not handling the mismatch between the SpoolMan and AMS (if you don't have the Active Tray information correct in spoolman it won't work properly) - -### Notes: - - If you change the BASE_URL of this app, you will need to reconfigure all NFC TAGS - -### TBD: - - Filament remaining in AMS (I have only AMS lite, if you have AMS we can test together) - - Filament spending based on printing - - TODO: handle situation when the print doesn't finish - - TODO: test with multiple AMS - - Code cleanup - - Video showcase - - Docker compose SSL - - Logs - - TODOs - - Click to resolve issue - WIP - - Reduce the amount of files in docker container - - Cloud service for controlled redirect so you don't have to reconfigure NFC tags - - QR codes - - Add search to list of spools +# logo OpenSpoolMan + +Use any filament like Bambu filaments with automatic recognition and filament usage updates in your AMS — no cloud connection required. + +![Desktop home view](docs/img/desktop_home.PNG) + +## Quick links +- [Documentation home](https://drndos.github.io/openspoolman/) +- [Feature tour & screenshots](https://drndos.github.io/openspoolman/features.html) +- [Setup guide](https://drndos.github.io/openspoolman/setup.html) +- [Deployment options](https://drndos.github.io/openspoolman/deployment.html) +- [Seeded demo & screenshot generation](https://drndos.github.io/openspoolman/demo-and-screenshots.html) +- [AUTO SPEND notes](https://drndos.github.io/openspoolman/auto-spend.html) + +Full documentation is published via GitHub Pages (see the links above or the repository’s **Pages** site). + +### Documentation via GitHub Pages +- Documentation lives in the `docs/` folder and is served by GitHub Pages. +- Edit or add Markdown files under `docs/` and submit a pull request; Pages will update automatically after merge once the repo’s Pages settings point to `/docs` on the default branch. +- For details on configuring or mirroring the site, see `docs/pages-maintenance.md`. + +## Highlights +- NFC-driven workflow to identify, assign, and load spools directly from your phone. +- Automatic usage tracking, including Bambu filaments without extra tags. +- Works locally with your SpoolMan instance and Bambu Lab printers. +- Web app optimized for both desktop and mobile devices. +- Customizable spool sorting for tray views and searches (via `SPOOL_SORTING`). +- Fallback spool assignment after prints when automatic detection fails. + +## Compatibility +- Requires a server that can reach both SpoolMan and your Bambu Lab printer. +- NFC features require HTTPS on the server URL and a phone with NFC support. +- SpoolMan fields for filament type, nozzle temperature, filament ID, spool tags, and active trays are expected (see the [setup guide](https://drndos.github.io/openspoolman/setup.html) for details). + +## Release notes +- 0.1.9 — 25.05.2025 — +- 0.1.8 — 20.04.2025 — +- 0.1.7 — 17.04.2025 — +- 0.1.4 — 09.02.2025 — Bug fixes +- 0.1.3 — 22.12.2024 — Added manual assignment for empty slots + +## License +[Apache 2.0](LICENSE.txt) diff --git a/docs/auto-spend.md b/docs/auto-spend.md new file mode 100644 index 00000000..dc3c6324 --- /dev/null +++ b/docs/auto-spend.md @@ -0,0 +1,17 @@ +# AUTO SPEND notes + +`AUTO_SPEND` enables consumption tracking from printer telemetry so matched spools display precise remaining weights. + +## How it works +- When `AUTO_SPEND=True`, matched spools show remaining grams based on printer feedback instead of percentage estimates. +- Unmatched trays continue to show percentage values until a spool is assigned. +- The feature relies on a healthy connection to your Bambu printer and SpoolMan API. + +## Enabling +1. Set `AUTO_SPEND=True` in `config.env`. +2. Restart the application or redeploy the container. +3. Verify remaining weights update during prints; fall back to percentage views by setting `AUTO_SPEND=False`. + +## Tips +- Pair AUTO SPEND with `SPOOL_SORTING` to keep the best candidates at the top of tray searches. +- If prints are running in read-only environments, disable AUTO SPEND to avoid stale or incomplete telemetry. diff --git a/docs/demo-and-screenshots.md b/docs/demo-and-screenshots.md new file mode 100644 index 00000000..b15665e2 --- /dev/null +++ b/docs/demo-and-screenshots.md @@ -0,0 +1,26 @@ +# Seeded demo & screenshot generation + +Use the built-in seeded dataset to preview OpenSpoolMan or to generate consistent screenshots. + +## Quick demo with seeded data +1. Ensure dependencies for UI tests are installed: `pip install -r requirements-screenshots.txt`. +2. Start the app in seeded mode: + ```bash + OPENSPOOLMAN_TEST_DATA=1 python app.py + ``` +3. Open the UI and explore without connecting to live printers or SpoolMan. + +## Generate screenshots +1. Install Playwright browsers if you have not already: + ```bash + playwright install + ``` +2. Run the capture script (seeded mode by default): + ```bash + python scripts/generate_screenshots.py --mode seed --port 5001 + ``` +3. Outputs are written to the directories defined in `scripts/screenshot_config.json`. Use `--output-dir` to override. +4. To capture against a live server, point `--base-url` to your deployment and pass `--mode live`. Add `--allow-live-actions` if you intentionally want state changes during capture. + +## Using snapshots +The script can load a saved dataset with `--snapshot data/live_snapshot.json` and attach a print history database via `--print-history-db` for richer history screenshots. diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 00000000..e7ef7ed3 --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,30 @@ +# Deployment options + +OpenSpoolMan can run locally, via Docker Compose, or on Kubernetes with the provided Helm chart. + +## Docker Compose +1. Ensure `config.env` is populated (see the setup guide). +2. Start the stack: + ```bash + docker compose -f compose.yaml up -d + ``` +3. Access the UI on `http://localhost:8000` (or the host/port you mapped). + +## Docker images +- The repository builds multi-architecture images; you can also build locally with `docker build -t openspoolman:local .`. +- Set `OPENSPOOLMAN_BASE_URL` in `config.env` to match the public URL where the container will be served. + +## Helm (Kubernetes) +- A starter chart is available under `helm/openspoolman`. +- Populate values for ingress, environment variables, and image registry as needed, then install: + ```bash + helm upgrade --install openspoolman helm/openspoolman + ``` + +## Running from source +For development, install dependencies and start Flask directly: +```bash +pip install -r requirements.txt +python app.py +``` +Use `.env` or `config.env` to supply the same environment variables used in container deployments. diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 00000000..e21c1bf5 --- /dev/null +++ b/docs/features.md @@ -0,0 +1,40 @@ +# Feature tour & screenshots + +Explore the core OpenSpoolMan experience across desktop and mobile. + +## Desktop views +- **Home dashboard** with AMS status, spool assignments, and quick actions. + ![Desktop home view](img/desktop_home.PNG) +- **Tray management** for filling or assigning AMS slots. + ![Fill tray modal](img/desktop_fill_tray.PNG) +- **Print history** with spool usage context. + ![Desktop print history](img/desktop_print_history.PNG) + +## Mobile views +- **Mobile dashboard** tuned for quick AMS control. + ![Mobile home](img/mobile_home.PNG) +- **Assign trays via NFC** and confirm writes directly from your phone. + ![Mobile NFC assignment](img/mobile_assign_nfc.jpeg) + ![NFC write success](img/nfc_write_success.jpeg) +- **Tray changes on the go** with tap-friendly controls. + ![Mobile change spool](img/mobile_change_spool.PNG) + +## Spool insights +- **Spool details** at a glance, including vendor, material, and remaining weight. + ![Desktop spool details](img/desktop_spool_info.jpeg) + ![Mobile spool details](img/mobile_spool_info.jpeg) +- **Bambu tracking overlays** showing estimated usage from printer telemetry. + ![Bambu tracking](img/bambu_tracking.jpg) +- **Print estimates** from slicer data alongside AMS context. + ![Slicer estimate](img/slicer_estimate.jpg) + +## Workflow helpers +- **Resolve missing info** prompts to keep data clean and enforce NFC-assisted flows. + ![Resolve issues](img/resolve_issues.jpeg) +- **Tray picking shortcuts** that surface the best slot based on spool attributes. + ![Pick tray](img/pick_tray.jpeg) +- **Open SpoolMan links** from within the UI for deeper inventory edits. + ![Open in SpoolMan](img/open_link.jpeg) + +## Post-print assignment fallback +If automatic detection misses a spool after a print, OpenSpoolMan can prompt for a manual assignment so history and consumption stay accurate. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..c875c5db --- /dev/null +++ b/docs/index.md @@ -0,0 +1,23 @@ +# OpenSpoolMan documentation + +Manage and monitor Bambu Lab printer spools through SpoolMan with NFC-driven workflows, automatic usage tracking, and a responsive UI for desktop and mobile. + +## Quick navigation +- [Feature tour & screenshots](features.html) +- [Setup guide](setup.html) +- [Deployment options](deployment.html) +- [Seeded demo & screenshot generation](demo-and-screenshots.html) +- [AUTO SPEND notes](auto-spend.html) + +## Release 0.1.9 highlights +- Custom spool sorting for tray views and searches via `SPOOL_SORTING`. +- Post-print spool assignment fallback when automatic detection is unavailable. +- Works with Bambu Studio 2.x while preserving NFC-assisted workflows. + +## What you get +- NFC-driven spool identification, assignment, and loading from mobile or desktop. +- Automatic usage tracking for tagged and untagged Bambu filaments without cloud access. +- Views optimized for AMS tray selection, spool details, and print history. + +## Where to find images +All screenshots are stored in `docs/img/` and referenced throughout the pages linked above. diff --git a/docs/pages-maintenance.md b/docs/pages-maintenance.md new file mode 100644 index 00000000..fdf25991 --- /dev/null +++ b/docs/pages-maintenance.md @@ -0,0 +1,23 @@ +# GitHub Pages maintenance + +The documentation is published from the `docs/` folder via GitHub Pages. No submodule is required. + +## Configure Pages +1. Open the repository Settings → Pages. +2. Set **Source** to "Deploy from a branch" and choose the default branch with `/docs` as the folder. +3. Save to enable the site at `https://.github.io/openspoolman/`. + +## Updating docs +- Edit Markdown in `docs/` (e.g., `features.md`, `setup.md`, `deployment.md`). +- Add screenshots to `docs/img/` and reference them with relative links. +- Submit a pull request; the site will update automatically after merge. + +## Preview locally +You can preview the static Markdown with any web server: +```bash +python -m http.server --directory docs 4000 +``` +For full Jekyll rendering, use `bundle exec jekyll serve --source docs --livereload` if you have Ruby tooling installed. + +## Mirroring to a dedicated branch +If you prefer a separate `gh-pages` branch, copy the `docs/` folder into that branch via automation or a manual sync. The content remains the same; only the Pages source changes. diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 00000000..30e04247 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,25 @@ +# Setup guide + +Follow these steps to connect OpenSpoolMan to your Bambu Lab printer and SpoolMan instance. + +## Prerequisites +- A reachable SpoolMan server (the app expects `/api/v1` endpoints). +- Printer details: serial number, access code, local IP, and a friendly printer name. +- Bambu Studio 2.x is supported; NFC-assisted flows continue to work with that release. + +## Configure environment +1. Copy `config.env.template` to `config.env` in the repository root. +2. Fill in the printer and SpoolMan values: + - `OPENSPOOLMAN_BASE_URL` – public base URL where this app will be served. + - `PRINTER_ID`, `PRINTER_ACCESS_CODE`, `PRINTER_IP`, `PRINTER_NAME` – printer credentials and IP. + - `SPOOLMAN_BASE_URL` – base URL for your SpoolMan instance. +3. Optional tuning: + - `AUTO_SPEND` – set `True` to display precise remaining weights for matched spools using printer telemetry. + - `SPOOL_SORTING` – customize spool sort order for tray selection and searches (default: `filament.material:asc,filament.vendor.name:asc,filament.name:asc`). + - `TZ` – set your server timezone for correct timestamps. + +## Initialize printer metadata +Run `python scripts/init_bambulab.py` once to validate the printer connection and populate credentials. + +## Health check +Start the app locally (see deployment options) and hit `/health` to confirm connectivity to both SpoolMan and the printer before enabling NFC or AUTO SPEND in production. From 3c1dda35b3d5aeb91234eb16b4be255dc2341ef0 Mon Sep 17 00:00:00 2001 From: "Markus M." Date: Sun, 30 Nov 2025 20:27:51 +0200 Subject: [PATCH 2/2] Move documentation back into README --- README.md | 156 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 127 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 1488f146..20a54858 100644 --- a/README.md +++ b/README.md @@ -4,35 +4,133 @@ Use any filament like Bambu filaments with automatic recognition and filament us ![Desktop home view](docs/img/desktop_home.PNG) -## Quick links -- [Documentation home](https://drndos.github.io/openspoolman/) -- [Feature tour & screenshots](https://drndos.github.io/openspoolman/features.html) -- [Setup guide](https://drndos.github.io/openspoolman/setup.html) -- [Deployment options](https://drndos.github.io/openspoolman/deployment.html) -- [Seeded demo & screenshot generation](https://drndos.github.io/openspoolman/demo-and-screenshots.html) -- [AUTO SPEND notes](https://drndos.github.io/openspoolman/auto-spend.html) - -Full documentation is published via GitHub Pages (see the links above or the repository’s **Pages** site). - -### Documentation via GitHub Pages -- Documentation lives in the `docs/` folder and is served by GitHub Pages. -- Edit or add Markdown files under `docs/` and submit a pull request; Pages will update automatically after merge once the repo’s Pages settings point to `/docs` on the default branch. -- For details on configuring or mirroring the site, see `docs/pages-maintenance.md`. - -## Highlights -- NFC-driven workflow to identify, assign, and load spools directly from your phone. -- Automatic usage tracking, including Bambu filaments without extra tags. -- Works locally with your SpoolMan instance and Bambu Lab printers. -- Web app optimized for both desktop and mobile devices. -- Customizable spool sorting for tray views and searches (via `SPOOL_SORTING`). -- Fallback spool assignment after prints when automatic detection fails. - -## Compatibility -- Requires a server that can reach both SpoolMan and your Bambu Lab printer. -- NFC features require HTTPS on the server URL and a phone with NFC support. -- SpoolMan fields for filament type, nozzle temperature, filament ID, spool tags, and active trays are expected (see the [setup guide](https://drndos.github.io/openspoolman/setup.html) for details). - -## Release notes +## Inhalt +- [Überblick](#überblick) +- [Setup & Deployment](#setup--deployment) +- [SpoolMan-Felder](#spoolman-felder) +- [Funktions-Überblick mit Popovers](#funktions-%C3%9Cberblick-mit-popovers) +- [AUTO SPEND](#auto-spend) +- [Demo & Screenshots](#demo--screenshots) +- [Kompatibilität](#kompatibilit%C3%A4t) +- [Release Notes](#release-notes) +- [License](#license) + +## Überblick +- NFC-Unterstützung ist **optional** – die App funktioniert auch ohne NFC-Smartphone. +- Bambu-Cloud-Konten sind nicht nötig und werden nicht hinterlegt. Erforderlich sind nur **Seriennummer** und **Access Code** des Druckers. +- Spools lassen sich automatisch erkennen, sortieren (`SPOOL_SORTING`) und nach einem Druck manuell zuordnen, falls keine automatische Erkennung möglich war. + +## Setup & Deployment +Richte die Umgebung ein und starte den Container – alles in einem Durchgang. + +### Voraussetzungen +- Erreichbare **SpoolMan**-Instanz (`/api/v1`-Endpoint). +- Bambu Lab Drucker mit **Seriennummer**, **Access Code**, **lokaler IP** und einem Anzeigenamen. +- Öffentliche Basis-URL, unter der OpenSpoolMan erreichbar sein soll (`OPENSPOOLMAN_BASE_URL`). + +### Konfiguration vorbereiten +1. `cp config.env.template config.env` +2. Fülle die wichtigsten Variablen in `config.env` aus: + - `OPENSPOOLMAN_BASE_URL` – öffentlicher Basis-Pfad der App. + - `PRINTER_ID`, `PRINTER_ACCESS_CODE`, `PRINTER_IP`, `PRINTER_NAME` – Druckerkennung ohne Cloud-Login. + - `SPOOLMAN_BASE_URL` – Basis-URL Deiner SpoolMan-Instanz. +3. Optional anpassen: + - `AUTO_SPEND=True` für exakte Restgewichte aus Druckertelemetrie. + - `SPOOL_SORTING` für eigene Sortierreihenfolge (Standard: `filament.material:asc,filament.vendor.name:asc,filament.name:asc`). + - `TZ` für korrekte Zeitzonenstempel. + +### Docker-Start +1. Starte den Container (nutzt `config.env` automatisch): + ```bash + docker compose -f compose.yaml up -d + ``` +2. Öffne die UI unter `http://localhost:8000` (oder dem gemappten Host/Port). +3. Prüfe die Verbindung über `http://localhost:8000/health` – sowohl SpoolMan als auch der Drucker müssen **OK** melden. + +> Tipp: `docker-compose.yaml` mountet `logs/`, `data/` und `prints/` für persistente Daten. Passe Ports oder Volumes bei Bedarf an. + +### Entwicklung direkt aus dem Quellcode +```bash +pip install -r requirements.txt +python app.py +``` +Verwende dieselbe `config.env`, um die Umgebung auch lokal bereitzustellen. + +## SpoolMan-Felder +Diese Felder solltest Du beim Anlegen einer Spule pflegen, damit OpenSpoolMan sie sauber zuordnen und schreiben kann: + +| SpoolMan-Feld | Beispiel | Verwendung in OpenSpoolMan | +| --- | --- | --- | +| **Filament → Name** | Bambu PLA Matte Grau | Beschriftet Buttons und Tray-Auswahl. | +| **Filament → Material** | PLA | Filtert und sortiert (abhängig von `SPOOL_SORTING`). | +| **Filament → Vendor/Marke** | Bambu Lab | Wird in Listen und Tag-Infos angezeigt. | +| **Filament → Nozzle Temperature** | 210 | In Tag-Writes für Bambu kompatible Daten genutzt. | +| **Filament → Filament ID** | BBL-PLA-GRAY | Eindeutiger Identifikator, der auf NFC/AMS geschrieben wird. | +| **Spool → Tags** | `bambu`, `ams` | Kennzeichnet Spulen für AMS/NFC-Flows. | +| **Spool → Aktiver Tray** | AMS 1 / Slot A | Verknüpft Spulen mit Slots für automatische Auswahl. | +| **Spool → Gewichte** | Leer- & Vollgewicht | Basis für Restmengen, wenn `AUTO_SPEND` deaktiviert ist. | + +## Funktions-Überblick mit Popovers +Die Startseitenansicht ist oben sichtbar. Weitere Screenshots kannst Du direkt hier aufklappen, ohne die Seite zu verlassen. + +
+ Desktop: Tray füllen und Druckhistorie + + ![Fill tray modal](docs/img/desktop_fill_tray.PNG) + + ![Desktop print history](docs/img/desktop_print_history.PNG) +
+ +
+ Mobile: Dashboard, NFC und Tray-Wechsel + + ![Mobile home](docs/img/mobile_home.PNG) + + ![Mobile NFC assignment](docs/img/mobile_assign_nfc.jpeg) + + ![NFC write success](docs/img/nfc_write_success.jpeg) + + ![Mobile change spool](docs/img/mobile_change_spool.PNG) +
+ +
+ Spulendetails, Tracking & Slicer-Schätzungen + + ![Desktop spool details](docs/img/desktop_spool_info.jpeg) + + ![Mobile spool details](docs/img/mobile_spool_info.jpeg) + + ![Bambu tracking](docs/img/bambu_tracking.jpg) + + ![Slicer estimate](docs/img/slicer_estimate.jpg) +
+ +
+ Workflow-Helfer + + ![Resolve issues](docs/img/resolve_issues.jpeg) + + ![Pick tray](docs/img/pick_tray.jpeg) + + ![Open in SpoolMan](docs/img/open_link.jpeg) +
+ +## AUTO SPEND +- `AUTO_SPEND=True` ersetzt Prozentanzeigen durch exakte Restgewichte aus der Druckertelemetrie. +- Deaktiviere die Option, wenn der Drucker nur lesend erreichbar ist oder Telemetrie unzuverlässig ist. +- Kombiniere sie mit `SPOOL_SORTING`, um passende Spulen oben anzuzeigen. + +## Demo & Screenshots +- Mit Seed-Daten starten: `OPENSPOOLMAN_TEST_DATA=1 python app.py` +- Screenshots automatisch erzeugen: `python scripts/generate_screenshots.py --mode seed --port 5001` +- Playwright-Browser falls nötig installieren: `playwright install` + +## Kompatibilität +- Funktioniert lokal ohne Bambu-Cloud; Zugriff zum Drucker erfolgt direkt per IP, Seriennummer und Access Code. +- NFC-Workflows erfordern HTTPS auf der Server-URL, sind aber optional. +- Bambu Studio **2.x** wird unterstützt. + +## Release Notes - 0.1.9 — 25.05.2025 — - 0.1.8 — 20.04.2025 — - 0.1.7 — 17.04.2025 —