jkef80 · davidkinnes · Feb 27, 2026 · Feb 27, 2026 · Feb 28, 2026 · Feb 28, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+CFSync is a local web application for tracking 3D printer filament/spool usage, built for Creality K2 Plus CFS (4x4 slot grid) and Klipper/Moonraker-based printers. It runs as a FastAPI backend with a vanilla JavaScript SPA frontend.
+
+## Development Commands
+
+```bash
+# Setup
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+
+# Run development server (with hot-reload)
+uvicorn main:app --reload --host 0.0.0.0 --port 8000
+
+# Health check
+curl http://localhost:8000/api/health
+```
+
+There are no automated tests, linting tools, or CI/CD pipelines configured.
+
+## Architecture
+
+**Backend:** Single-file FastAPI app (`main.py`, ~1500 lines) with Pydantic models in `models/schemas.py`. Data is persisted as JSON files in `data/` (state.json, config.json, profiles.json) — no database.
+
+**Frontend:** Vanilla JS SPA in `static/` (index.html, app.js, app.css, style.css). No build step, no framework — pure DOM manipulation. `fluidd-panel.js` is a standalone script injected into the Fluidd UI via bookmarklet or Tampermonkey userscript (generated from the settings page).
+
+**Moonraker integration:** Optional async background polling loop that queries the printer's Moonraker API for print job status, filament usage, and CFS slot info. Includes Creality K2 Plus-specific object parsing (box.T1-T4, filament_rack). Printer identity (`printer_name`, `printer_firmware`) is parsed from the Moonraker WebSocket.
+
+## Key Patterns
+
+- **Pydantic v1/v2 compatibility:** Helper functions `_model_dump()`, `_model_validate()`, `_req_dump()` abstract over version differences. Always use these instead of calling `.dict()` or `.model_dump()` directly.
+- **State migration:** `_migrate_state_dict()` handles legacy field names (e.g., `color` → `color_hex`, `vendor` → `manufacturer`) and older state.json formats.
+- **Two API tiers:** `/api/*` returns raw JSON; `/api/ui/*` wraps responses in `{"result": {...}}` for the frontend.
+- **Slot IDs:** Literal type `SlotId` = `"1A"` through `"4D"` (4 boxes × 4 colors, 16 total).
+- **Spool epochs:** Incrementing `spool_epoch` counter tracks spool changes per slot, enabling per-spool history filtering.
+- **History conventions:** `_hist_push()` prepends (newest-first); `_hist_upsert_by_src()` updates existing entries by source marker during live prints.
+- **Internal functions** are prefixed with `_` (e.g., `_http_get_json`, `_hist_push`).
+- **Filament calculation:** grams = density × π × (diameter/2)² × length, with material-specific density from profiles.json.
+
+## Spoolman Integration (Optional)
+
+Set `spoolman_url` in `data/config.json` to enable. This app acts as the only bridge between Spoolman and the printer (Moonraker's Spoolman plugin is not used). Spools are linked manually via the slot modal dropdown or auto-linked by RFID tag (`_spoolman_autolink_by_rfid()`). On link, `remaining_weight` is imported from Spoolman. Consumption is synced back via `PUT /api/v1/spool/{id}/use` (fire-and-forget) when prints finalize or manual allocations are made. Roll changes auto-unlink the Spoolman spool. All Spoolman calls are best-effort (`_spoolman_*` helpers) and never block local tracking.
+
+**Spoolman API endpoints:** `GET /api/ui/spoolman/spools`, `POST /api/ui/spoolman/link`, `POST /api/ui/spoolman/unlink`, `GET /api/ui/spoolman/spool_detail`.
+
+**Percentage calculation:** For RFID-linked spools, remaining % is calculated the same way as manual spools — using Spoolman's `remaining_weight` divided by the spool's initial weight.
+
+## Production Deployment
+
+Installs to `/opt/filament-management/` as a systemd service. See `install.sh`, `update.sh`, `uninstall.sh`, and `filament-management.service.example`.
diff --git a/README.md b/README.md
@@ -1,14 +1,137 @@
-# Filament-Management
+# CFSync
 
-Local filament / spool tracking for Creality CFS & Klipper via Moonraker.
+A local web dashboard for managing filament spools on **Creality K1 series printers with CFS** (Colour Filament System), including the K1, K1C, K1 Max, K1 SE, and K2 Plus. CFSync connects directly to one or more printers over WebSocket, reads live spool data from all CFS slots, and optionally syncs consumption back to [Spoolman](https://github.com/Donkie/Spoolman).
 
-Track filament usage per slot, handle color changes during prints and keep everything fully local.
+![CFSync screenshot](docs/screenshot.png)
 
-No cloud. No external services.
+## Features
 
----
+- Multi-printer support — monitor and manage multiple configured printers in one UI
+- Live CFS slot view — filament colour, material, and fill level per slot
+- RFID spool percent from printer sensor; calculated percent for non-RFID spools via Spoolman
+- Spoolman integration — link spools, track remaining weight, auto-report usage at job end
+- Moonraker job tracking — attributes `filament_used` proportionally across active slots at print completion
+- Clickable CFS box temperature/humidity values with historical graphs
+- Recent jobs panel with per-slot filament usage breakdown
+- Reallocate historical job usage to a different Spoolman spool (link/relink)
+- Printer name and firmware version shown in header (read from WebSocket)
+- Dark UI, no build step, runs as a systemd service
 
-## 🚀 Installation (One-Liner)
+## Screenshots
+
+### Dashboard
+
+![CFSync dashboard](docs/screenshot.png)
+
+### Recent jobs
+
+![Recent jobs](docs/screenshot-past-jobs.png)
+
+### Temperature history graph
+
+![Temperature history graph](docs/screenshot-temperature-graph.png)
+
+### Humidity history graph
+
+![Humidity history graph](docs/screenshot-humidity-graph.png)
+
+### Reallocate filament usage
+
+![Reallocate filament usage](docs/screenshot-reallocate-filament-usage.png)
+
+## Requirements
+
+- Linux host on the same network as the printer (e.g. a Pi or the printer's companion board)
+- Creality K1 series printer with CFS (K1, K1C, K1 Max, K1 SE, K2 Plus)
+- Python 3.10+
+- Optional: [Spoolman](https://github.com/Donkie/Spoolman) for spool tracking
+
+## Install
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/jkef80/Filament-Management/main/install.sh | sudo bash
+curl -fsSL https://raw.githubusercontent.com/koen01/CFSync/refs/heads/spoolman/install.sh | sudo bash
+```
+
+The installer will prompt for:
+
+| Prompt | Example |
+|---|---|
+| UI port | `8005` |
+| Printer IPs | `192.168.1.144, 192.168.1.145` |
+| Spoolman URL *(optional)* | `http://192.168.1.10:7912` |
+
+After install, open `http://<host-ip>:<port>` in your browser.
+
+## Configuration
+
+Settings are stored in `data/config.json`:
+
+```json
+{
+  "printers": [
+    { "id": "Creality k2 Pro", "address": "192.168.1.144" },
+    { "id": "Creality Hi", "address": "192.168.1.145" }
+  ],
+  "filament_diameter_mm": 1.75,
+  "spoolman_url": "http://192.168.1.10:7912"
+}
+```
+
+Alternative (IDs default to IP address):
+
+```json
+{
+  "printer_urls": ["192.168.1.144", "192.168.1.145"],
+  "filament_diameter_mm": 1.75,
+  "spoolman_url": "http://192.168.1.10:7912"
+}
+```
+
+## Spoolman — RFID auto-linking
+
+When an RFID-tagged spool is inserted into a CFS slot, CFSync automatically links it to the correct Spoolman spool — no manual selection needed. There are two mechanisms, used together:
+
+**1. Serial number via SSH (primary — works instantly with CFTag-tagged spools)**
+
+CFTag writes the Spoolman spool ID directly onto the RFID chip as its serial number. When CFSync detects a new RFID spool, it SSHes into the printer and reads the spool data file to extract the serial number. If it matches a Spoolman spool ID, the slot is linked immediately — no prior setup or manual linking required.
+
+**2. RFID code via Spoolman extra field (fallback)**
+
+When you manually link a spool via the CFSync slot modal, CFSync stores the slot's RFID code in a `cfs_rfid` extra field on that spool in Spoolman. Next time the same tag is detected in any slot, CFSync looks it up and auto-links. This requires the extra field to be pre-created in Spoolman:
+
+1. Open Spoolman → **Settings** → **Extra fields**
+2. Add a new field: **Name** `cfs_rfid`, **Field type** Text
+3. Save
+
+![Spoolman link modal](docs/spoolman-link.png)
+
+> **Note:** RFID tags are only present on spools with a Creality RFID chip. Spools without RFID can still be linked manually.
+
+## Workflow — adding a new spool with RFID
+
+The recommended flow uses **[CFTag](https://github.com/koen01/cftag)** (Android, NFC required) — a companion app built for this ecosystem. CFTag handles the entire tagging process in one session: it creates the spool in Spoolman, then guides you through writing both RFID tags on the spool back-to-back without re-entering any data.
+
+1. **Open CFTag** → fill in filament details → tap **Create in Spoolman**. CFTag creates the spool entry and immediately prompts you to write the first tag. Hold your phone to the tag, then flip the spool and write the second tag when prompted — done in one flow.
+2. **Load the spool** into a CFS slot.
+3. **CFSync auto-links** the slot to the Spoolman spool the moment it detects the RFID tag — no manual action needed.
+
+From this point on, inserting that spool into any CFS slot will auto-link it instantly. Filament consumption is reported back to Spoolman after each print.
+
+> Spools without a Creality RFID chip skip step 1 and must be linked manually each time they are loaded.
+
+## Update
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/koen01/CFSync/refs/heads/spoolman/update.sh | sudo bash
+```
+
+## Logs
+
+```bash
+sudo journalctl -u filament-management -f
+```
+
+## Credits
+
+- [jkef80/Filament-Management](https://github.com/jkef80/Filament-Management) — original Moonraker-based filament management that this project evolved from
+- [DaviBe92/k2-websocket-re](https://github.com/DaviBe92/k2-websocket-re) — reverse-engineered Creality K2 WebSocket protocol documentation that made the CFS integration possible
diff --git a/docs/screenshot-humidity-graph.png b/docs/screenshot-humidity-graph.png
diff --git a/docs/screenshot-past-jobs.png b/docs/screenshot-past-jobs.png
diff --git a/docs/screenshot-reallocate-filament-usage.png b/docs/screenshot-reallocate-filament-usage.png
diff --git a/docs/screenshot-temperature-graph.png b/docs/screenshot-temperature-graph.png
diff --git a/docs/screenshot.png b/docs/screenshot.png
diff --git a/docs/spoolman-link.png b/docs/spoolman-link.png
diff --git a/install.sh b/install.sh
@@ -3,7 +3,7 @@ set -euo pipefail
 
 APP_DIR="/opt/filament-management"
 SERVICE_NAME="filament-management"
-REPO_URL="https://github.com/jkef80/Filament-Management.git"
+REPO_URL="https://github.com/davidkinnes/CFSync.git"
 
 if [[ ${EUID} -ne 0 ]]; then
   echo "Please run with sudo"
@@ -28,17 +28,19 @@ ask() {
   echo "${var:-$default}"
 }
 
-echo "=== Filament Management Installer ==="
+echo "=== CFSync Installer ==="
 
 UI_PORT=$(ask "UI Port" "8005")
-MOON_HOST=$(ask "Moonraker Host/IP" "192.168.178.148")
-MOON_PORT=$(ask "Moonraker Port" "7125")
-POLL=$(ask "Poll interval (sec)" "5")
+PRINTER_IPS=$(ask "Printer IPs (comma-separated)" "192.168.1.144")
 DIAM=$(ask "Filament diameter (mm)" "1.75")
-AUTOSYNC=$(ask "CFS Autosync? (y/N)" "N")
+SPOOLMAN_URL=$(ask "Spoolman URL (optional, e.g. http://host:7912)" "")
 
-AUTOSYNC_BOOL=false
-if [[ "$AUTOSYNC" =~ ^[Yy]$ ]]; then AUTOSYNC_BOOL=true; fi
+PRINTER_JSON=$(echo "$PRINTER_IPS" | tr ',' '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | awk 'NF' | awk '{printf "\"%s\",", $0}' | sed 's/,$//')
+if [ -n "$PRINTER_JSON" ]; then
+  PRINTER_JSON="[$PRINTER_JSON]"
+else
+  PRINTER_JSON="[]"
+fi
 
 echo "Installing to $APP_DIR"
 
@@ -73,18 +75,17 @@ mkdir -p "$APP_DIR/data"
 
 cat > "$APP_DIR/data/config.json" <<CFG
 {
-  "moonraker_url": "http://${MOON_HOST}:${MOON_PORT}",
-  "poll_interval_sec": ${POLL},
+  "printer_urls": ${PRINTER_JSON},
   "filament_diameter_mm": ${DIAM},
-  "cfs_autosync": ${AUTOSYNC_BOOL}
+  "spoolman_url": "${SPOOLMAN_URL}"
 }
 CFG
 
 chown -R "$REAL_USER":"$REAL_USER" "$APP_DIR/data"
 
 cat > "/etc/systemd/system/${SERVICE_NAME}.service" <<SVC
 [Unit]
-Description=Filament Management
+Description=CFSync
 After=network-online.target
 Wants=network-online.target