🧵 Filament Tracker

Suivi de filament et journal d'impressions pour imprimante 3D Creality K1SE — interface web PWA, synchronisation automatique avec Spoolman.

⚠️ USAGE LOCAL UNIQUEMENT — Ce projet est conçu pour tourner sur un réseau local de confiance (votre réseau domestique). L'API n'a pas d'authentification : ne l'expose jamais sur Internet sans ajouter une protection (reverse-proxy avec mot de passe, VPN, etc.). Connexions en clair (HTTP/WebSocket) — réservé à un usage maison.

🇬🇧 English version: README.en.md

Filament Tracker se connecte au WebSocket propriétaire (port 9999) de la K1SE (firmware CrealityOS), suit les impressions en temps réel, importe l'historique complet des impressions passées, télécharge les miniatures des modèles, et se synchronise avec Spoolman pour gérer le décompte du filament sur chaque bobine.

Votre K1SE tourne sous CrealityOS (Klipper sans Moonraker) : il n'existe aucun moyen simple de savoir ce qui a été imprimé, combien de filament a été consommé, et quelles impressions ont échoué. Filament Tracker comble ce manque :

• Vous imprimez → le journal se remplit automatiquement (nom du fichier, statut, filament réellement consommé)
• Toutes vos impressions passées sont importées depuis l'historique de l'imprimante (terminées et arrêtées)
• Vous voyez vos modèles avec leur miniature dans l'onglet « Filaments »
• Vous associez une impression à une bobine → le poids restant se décompte automatiquement dans Spoolman
• Un dashboard temps réel montre l'état de l'imprimante (températures buse/plateau, fichier en cours, statistiques)

Les seuils d'alerte sont calculés côté interface à partir de remaining_weight / initial_weight. Aucune donnée supplémentaire n'est écrite dans Spoolman.

┌─────────────────────────────┐        ┌──────────────────────┐
│  Creality K1SE (port 9999) │  WS   │  filament-tracker     │
│  - état temps réel         │ ─────▶ │  collector.py         │
│  - liste fichiers          │        │  - journal            │
│  - historique              │        │  - API web :8123      │
│  - miniatures (HTTP :80)   │ ─────▶ │  - déduplication      │
└─────────────────────────────┘        └──────────┬───────────┘
                                                  │ REST
                                                  ▼
                                       ┌──────────────────────┐
                                       │  Spoolman (port 7912)│
                                       │  bobines, poids rest.│
                                       └──────────────────────┘

• Docker + Docker Compose
• Une imprimante Creality K1SE accessible sur le réseau local
• (Optionnel) Spoolman déjà en place — le docker-compose le déploie automatiquement

# 1. Récupérer le code
git clone <votre-url-repo>
cd filament-tracker

# 2. Configurer l'adresse de l'imprimante (optionnel : l'IP par défaut est 192.168.1.41)
echo -e "K1_HOST=192.168.1.100\nK1_PORT=9999" > .env

# 3. Lancer
docker compose up -d --build

Puis ouvrir :

• Interface web : http://:8123
• Spoolman : http://:7912

Variables d'environnement (fichier .env ou docker-compose.yml) :

1. Ajoutez vos bobines dans Spoolman (http://:7912) avec leur poids mesuré
2. Ouvrez l'interface (http://:8123)
3. Onglet 📊 Dashboard : état de l'imprimante en direct (connexion, températures buse/plateau, statistiques)
4. Onglet 📋 Journal : toutes les impressions (passées + futures) avec statut et filament
5. Onglet 🧵 Filaments : les bobines Spoolman (poids restant, niveau) + les modèles de l'imprimante avec miniature + quantité + durée
6. Cliquez sur une session ou un modèle → choisissez la bobine → le poids se décompte

💡 Astuce mobile : sur Android/iOS, « Ajouter à l'écran d'accueil » installe Filament Tracker comme une appli.

La K1SE n'a pas d'API REST complète pour les fichiers (contrairement aux printers Klipper avec Moonraker). Le protocole CrealityOS a été entièrement compris par tests sur une machine réelle :

• Push : l'imprimante envoie son état en continu (state, printFileName, usedMaterialLength, nozzleTemp, bedTemp, err.errcode, ...)
• Requêtes : ReqPrinterPara, reqPrintObjects
• Liste des fichiers + historique : la combinaison complète et obligatoire :

  {"method":"get","params":{"reqGcodeFile":1,"reqGcodeList":1,"reqHistory":1,
    "reqElapseVideoList":1,"reqPrintObjects":1,"reqMaterialBoxsInfo":1}}

  → réponse retGcodeFileInfo2 (fichiers avec miniatures + filamentWeight) + historyList (jobs passés).

  ⚠️ reqGcodeList seul ne renvoie rien ! La K1 ignore les demandes partielles.

• Miniature : GET /downloads/humbnail/<fichier-sans-.gcode>.png → PNG 96×96

  ⚠️ Le firmware écrit humbnail (faute de frappe officielle de Creality) — pas « thumbnail ».

• Gcode complet : GET /downloads/gcode/<fichier>.gcode (le collecteur ne télécharge QUE les miniatures, jamais les .gcode complets pour économiser la bande passante)

Chaque job contient : id unique, filename, starttime, usagetime (s), usagematerial (mm), printfinish (1 = terminé, 0 = arrêté), thumbnail.

• Idempotent : la session est hachée (sha1(id|filename)) → pas de doublon au re-import
• Fusion live : si une session en direct existe déjà pour le même fichier/début, l'import la complète au lieu d'en créer une autre

L'imprimante éteinte brutalement laisse le WebSocket bloqué (aucune erreur levée). Le watchdog détecte le silence (>8 s → sonde, >30 s → fermeture) et relance la connexion toutes les 10 s.

Les données persistantes sont conservées dans deux volumes Docker nommés : collector-data (SQLite k1_sessions.db et miniatures) et spoolman-data (base Spoolman). Une mise à jour standard est additive :

git pull
docker compose up -d --build

Ne supprimez pas les volumes (docker compose down -v) : cela effacerait l'historique et les bobines. Les migrations SQLite intégrées utilisent CREATE TABLE IF NOT EXISTS et ajoutent uniquement les colonnes manquantes.

# Tester sans l'imprimante : lancer le mock sur 9999
python3 mock_k1.py 9999 demo_vase.gcode

# Lancer le collecteur en local (hors Docker)
K1_HOST=127.0.0.1 K1_PORT=9999 SPOOLMAN_URL=http://127.0.0.1:8000 python3 collector.py

Le protocole CrealityOS a été reverse-engineer et validé sur une K1SE réelle (firmware DWIN CR4CU220812S11 1.3.5.22). Le collecteur ne fait aucune supposition sur le modèle (il lit le modèle depuis l'imprimante) : tout appareil Creality utilisant le même WebSocket CrealityOS (port 9999) est compatible.

Familles connues pour utiliser ce protocole (confirmé par la communauté — intégrations HA open source, etc.) :

Points pratiques :

• Le collecteur se connecte au WebSocket port 9999 — vérifiez que votre imprimante est sur le même réseau local et que le port n'est pas bloqué par le pare-feu.
• Une fois connecté, tout est automatique : historique importé, fichiers + miniatures synchronisés, journal mis à jour en direct.
• Check rapide de compatibilité : si GET http://<imprimante>/downloads/humbnail/test.png répond (même une 404), le firmware serveur est là. L'appli détecte le modèle via le champ model du WS.
• Si votre firmware ne répond pas à la combinaison de requêtes, ouvrez une issue GitHub avec votre version de firmware — nous pourrons l'adapter.

⚠️ Ce projet n'a aucun lien avec Creality. Le protocole a été découvert par observation du trafic réseau ; il peut changer à tout moment avec une mise à jour du firmware.

• Décompte du filament : le collecteur lit usagematerial (mm) envoyé par l'imprimante, le convertit en grammes avec la densité du filament (défaut 1,24 g/cm³ pour le PLA) et décompte remaining_weight dans Spoolman.
• Bobines pesées : si vous avez pesé vos bobines à la balance, utilise la case « 🪙 Décompter » décochée pour les impressions antérieures à la pesée — sinon double comptage.
• Miniatures historiques : les thumbnails d'historique id-based ne sont pas servis par le firmware → le collecteur rattache la miniature du fichier correspondant.

📊 Dashboard imprimante — état temps réel (connexion, températures buse/plateau, statistiques globales) :

📋 Journal des impressions — chaque impression est enregistrée automatiquement (statut, durée, filament consommé) :

🧵 Bobines & filaments — inventaire Spoolman (matériau, couleur, poids restant) et bibliothèque d'association :

📱 Vue mobile — interface responsive, installable comme PWA sur téléphone :

Les captures montrent l'interface réelle (adresse IP de démonstration floutée).

MIT — voir LICENSE.