From 9ae9e80dcdd5f47db20a2093842a17b9cdb55ea9 Mon Sep 17 00:00:00 2001 From: Manuel Weiser Date: Sat, 30 Aug 2025 18:13:42 +0200 Subject: [PATCH] docs: add German and English wiki documentation --- .gitignore | 3 +- WIKI_DE.md | 468 +++++++++++++++++++++++++++++++++ WIKI_EN.md | 746 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 1216 insertions(+), 1 deletion(-) create mode 100644 WIKI_DE.md create mode 100644 WIKI_EN.md diff --git a/.gitignore b/.gitignore index a6e7ff5..7709e53 100644 --- a/.gitignore +++ b/.gitignore @@ -39,4 +39,5 @@ _local/* website/* release.sh .github/copilot-instructions.md -data \ No newline at end of file +data +wiki \ No newline at end of file diff --git a/WIKI_DE.md b/WIKI_DE.md new file mode 100644 index 0000000..b4ed552 --- /dev/null +++ b/WIKI_DE.md @@ -0,0 +1,468 @@ +# FilaMan Wiki - Deutsch + +## Inhaltsverzeichnis + +1. [Überblick](#überblick) +2. [Installation](#installation) +3. [Hardware-Anforderungen](#hardware-anforderungen) +4. [Ersteinrichtung](#ersteinrichtung) +5. [Konfiguration](#konfiguration) +6. [Benutzung](#benutzung) +7. [NFC-Tags](#nfc-tags) +8. [Bambu Lab Integration](#bambu-lab-integration) +9. [Spoolman Integration](#spoolman-integration) +10. [Octoprint Integration](#octoprint-integration) +11. [Hersteller Tags](#hersteller-tags) +12. [Fehlerbehebung](#fehlerbehebung) +13. [Support](#support) + +--- + +## Überblick + +FilaMan ist ein umfassendes Filament-Managementsystem für 3D-Drucker, das auf ESP32-Hardware basiert. Es bietet Gewichtsmessung, NFC-Tag-Management und nahtlose Integration mit Spoolman und Bambu Lab 3D-Druckern. + +### Hauptfunktionen + +- **Präzise Gewichtsmessung** mit HX711 Wägezellen-Verstärker +- **NFC-Tag Lesen und Schreiben** für Filament-Identifikation +- **OLED-Display** für Status-Anzeigen +- **WiFi-Konnektivität** mit einfacher Konfiguration +- **Webbasierte Benutzeroberfläche** mit Echtzeit-Updates +- **Spoolman-Integration** für Lagerverwaltung +- **Bambu Lab AMS-Steuerung** via MQTT +- **Openspool NFC-Format** Kompatibilität +- **Hersteller Tag Unterstützung** für automatische Einrichtung + +### Systemvoraussetzungen + +- **ESP32 Development Board** +- **Spoolman Instanz** (erforderlich für volle Funktionalität) +- **WiFi-Netzwerk** +- **Webbrowser** (Chrome/Firefox/Safari) + +--- + +## Installation + +### Einfache Installation (Empfohlen) + +1. **Öffnen Sie den [FilaMan Web-Installer](https://www.filaman.app/installer.html)** + - Verwenden Sie einen Chrome-basierten Browser + +2. **ESP32 vorbereiten** + - Verbinden Sie den ESP32 über USB mit Ihrem Computer + - Klicken Sie auf "Connect" + +3. **Port auswählen** + - Wählen Sie den entsprechenden USB-Port aus + - Bestätigen Sie die Auswahl + +4. **Installation starten** + - Klicken Sie auf "FilaMan installieren" + - Warten Sie, bis der Installationsvorgang abgeschlossen ist + +### Manuelle Kompilierung + +Für erfahrene Benutzer mit PlatformIO: + +```bash +git clone https://github.com/ManuelW77/Filaman.git +cd FilaMan/esp32 +pio lib install +pio run --target upload +``` + +--- + +## Hardware-Anforderungen + +### Erforderliche Komponenten + +| Komponente | Beschreibung | Amazon Link (Affiliate) | +|------------|--------------|-------------------------| +| ESP32 Development Board | Jede ESP32-Variante | [Amazon](https://amzn.to/3FHea6D) | +| HX711 + Wägezelle | 5kg Load Cell Amplifier | [Amazon](https://amzn.to/4ja1KTe) | +| OLED Display | 0.96" I2C 128x64 SSD1306 | [Amazon](https://amzn.to/445aaa9) | +| PN532 NFC Modul | V3 RFID-Modul | [Amazon](https://amzn.eu/d/gy9vaBX) | +| NFC Tags | NTAG213/NTAG215 | [Amazon](https://amzn.to/3E071xO) | +| TTP223 Touch Sensor | Optional für Tara-Funktion | [Amazon](https://amzn.to/4hTChMK) | + +### Pin-Konfiguration + +| Komponente | ESP32 Pin | Funktion | +|------------|-----------|----------| +| HX711 DOUT | 16 | Datenausgang Wägezelle | +| HX711 SCK | 17 | Takt Wägezelle | +| OLED SDA | 21 | I2C Daten | +| OLED SCL | 22 | I2C Takt | +| PN532 IRQ | 32 | Interrupt | +| PN532 RESET | 33 | Reset | +| PN532 SDA | 21 | I2C Daten (geteilt) | +| PN532 SCL | 22 | I2C Takt (geteilt) | +| TTP223 I/O | 25 | Touch-Sensor (optional) | + +### Wichtige Hinweise + +- **PN532 DIP-Schalter** müssen auf I2C-Modus eingestellt sein +- **3V Pin** vom ESP32 für Touch-Sensor verwenden +- **Wägezellen-Verkabelung**: E+ (rot), E- (schwarz), A- (weiß), A+ (grün) + +![Schaltplan](./img/Schaltplan.png) + +--- + +## Ersteinrichtung + +### Nach der Installation + +1. **ESP32 Neustart** + - Das System erstellt automatisch einen WiFi-Hotspot "FilaMan" + +2. **WiFi-Konfiguration** + - Verbinden Sie sich mit dem "FilaMan" Netzwerk + - Öffnen Sie einen Browser (automatisches Portal oder http://192.168.4.1) + - Konfigurieren Sie Ihre WiFi-Zugangsdaten + +3. **Erster Zugriff** + - Nach erfolgreicher WiFi-Verbindung ist das System unter http://filaman.local erreichbar + - Alternativ über die vom Router zugewiesene IP-Adresse + +### Spoolman Vorbereitung + +**Wichtiger Hinweis**: Spoolman muss im Debug-Modus laufen: + +```env +# In der .env Datei von Spoolman auskommentieren: +SPOOLMAN_DEBUG_MODE=TRUE +``` + +Dies ist erforderlich, da Spoolman noch keine CORS-Domain-Konfiguration unterstützt. + +--- + +## Konfiguration + +### Waagen-Kalibrierung + +1. **Kalibrierung starten** + - Gehen Sie zur "Scale" (Waage) Seite + - Bereiten Sie ein 500g Referenzgewicht vor (z.B. Wasserglas) + +2. **Kalibrierungsschritte** + - Folgen Sie den Anweisungen auf dem Display + - Legen Sie das Gewicht auf, wenn gefordert + - Warten Sie, bis die Kalibrierung abgeschlossen ist + +3. **Validierung** + - Testen Sie die Genauigkeit mit bekannten Gewichten + - Bei Bedarf "Tare Scale" für Nullstellung verwenden + +### Spoolman-Verbindung + +1. **Spoolman-URL eingeben** + - Gehen Sie zur "Spoolman/Bambu" Seite + - Geben Sie die vollständige URL Ihrer Spoolman-Instanz ein + - Format: `http://spoolman-server:7912` + +2. **Verbindung testen** + - Das System prüft automatisch die Verbindung + - Erfolgreiche Verbindung wird durch grünen Status angezeigt + +### Bambu Lab Drucker (optional) + +1. **Drucker-Einstellungen** + - Öffnen Sie das Einstellungsmenü auf Ihrem Bambu-Drucker + - Notieren Sie sich die folgenden Daten: + - IP-Adresse des Druckers + - Access Code + - Serial Number + +2. **FilaMan Konfiguration** + - Geben Sie die Drucker-Daten in der "Spoolman/Bambu" Seite ein + - Aktivieren Sie "Auto Send to Bambu" für automatische AMS-Zuordnung + +3. **Auto-Send Timeout** + - Konfigurieren Sie die Wartezeit für automatische Spulen-Erkennung + - Empfohlener Wert: 10-30 Sekunden + +--- + +## Benutzung + +### Grundlegende Bedienung + +1. **Filament wiegen** + - Platzieren Sie die Spule auf der Waage + - Das Gewicht wird automatisch auf dem Display und in der Weboberfläche angezeigt + +2. **NFC-Tag scannen** + - Halten Sie den Tag in die Nähe des PN532-Moduls + - Bei erkannten Tags wird die Spulen-Information angezeigt + - Das Gewicht wird automatisch in Spoolman aktualisiert + +3. **Status-Überwachung** + - **OLED-Display** zeigt aktuelles Gewicht und Verbindungsstatus + - **Weboberfläche** bietet detaillierte Informationen und Steuerung + +### Weboberfläche Navigation + +- **Startseite**: Hauptfunktionen und aktueller Status +- **Scale**: Waagen-Kalibrierung und -Einstellungen +- **Spoolman/Bambu**: System-Konfiguration +- **Statistics**: Nutzungsstatistiken (falls aktiviert) + +--- + +## NFC-Tags + +### Unterstützte Tag-Typen + +- **NTAG213**: 144 Bytes (grundlegende Funktionen) +- **NTAG215**: 504 Bytes (empfohlen) +- **NTAG216**: 888 Bytes (erweiterte Funktionen) + +### Tag beschreiben + +1. **Spule in Spoolman vorbereiten** + - Erstellen Sie eine neue Spule in Spoolman + - Stellen Sie sicher, dass alle erforderlichen Daten eingegeben sind + +2. **Tag-Beschreibung starten** + - Wählen Sie die Spule aus der Liste + - Klicken Sie auf "Write Tag" + - Das Display zeigt "Waiting for Tag" + +3. **Tag auflegen** + - Platzieren Sie den NFC-Tag auf dem PN532-Modul + - Warten Sie auf die Bestätigung + +4. **Erfolgsmeldung** + - Bei erfolgreichem Beschreiben wird ein Häkchen angezeigt + - Der Tag ist nun mit der Spoolman-Spule verknüpft + +### Tag lesen + +1. **Tag scannen** + - Platzieren Sie die Spule mit dem NFC-Tag auf die Waage über dem NFC-Reader + - Bei Problemen beim Lesen: Spule etwas anders positionieren (nicht ganz an den Rand) + - Die Spulen-Information wird automatisch geladen + +2. **Automatische Updates** + - Das aktuelle Gewicht wird in Spoolman übertragen + - Die Spule wird in der Weboberfläche automatisch ausgewählt + +--- + +## Bambu Lab Integration + +### AMS (Automatic Material System) + +1. **AMS-Status anzeigen** + - Die Weboberfläche zeigt den aktuellen Zustand aller AMS-Fächer + - Beladene Fächer werden mit Filament-Informationen angezeigt + +2. **Filament manuell zuordnen** + - Wählen Sie eine Spule aus der Spoolman-Liste + - Klicken Sie auf das entsprechende AMS-Fach-Symbol + - Das Filament wird dem Fach zugeordnet + +3. **Automatische Zuordnung** + - Nach dem Wiegen mit aktiviertem "Auto Send to Bambu" + - Das System wartet auf neue Spulen im AMS + - Kalibrierte Filamente werden automatisch zugeordnet + +### Bambu Studio Integration + +1. **Filament-Profile synchronisieren** + - Kalibrieren Sie Filamente in Bambu Studio + - Verwenden Sie Device → AMS → Bleistift-Symbol → Auswählen + +2. **Setting-IDs speichern** + - FilaMan erkennt verfügbare Setting-IDs automatisch + - Klicken Sie auf "Settings in Spoolman speichern" + - Die Profile werden für zukünftige Drucke verwendet + +### Verbindung wiederherstellen + +- Bei Verbindungsproblemen klicken Sie den roten Punkt in der Menüleiste +- Das System stellt automatisch eine neue Verbindung her + +--- + +## Spoolman Integration + +### Automatische Funktionen + +1. **Spulen-Synchronisation** + - Automatische Übertragung von Gewichtsänderungen + - Echtzeit-Updates der Spulen-Daten + +2. **Extra-Felder** + - FilaMan erstellt automatisch erforderliche benutzerdefinierte Felder + - NFC-Tag-UID wird als Referenz gespeichert + +3. **Filterung** + - "Nur Spulen ohne NFC-Tag anzeigen" für einfache Tag-Zuordnung + - Kategorisierung nach Herstellern und Materialtypen + +### Spoolman Octoprint Plugin + +Für Octoprint-Benutzer ist eine automatische Spulen-Zuordnung verfügbar: + +1. **Plugin installieren** + ``` + https://github.com/ManuelW77/OctoPrint-Spoolman-Filaman/archive/refs/heads/master.zip + ``` + +2. **FilaMan konfigurieren** + - Aktivieren Sie "Send to Octo-Plugin" + - Geben Sie Octoprint-URL und API-Key ein + +3. **Automatische Zuordnung** + - Nach dem Wiegen wird die Spule automatisch in Octoprint aktiviert + - Unterstützt aktuell nur Tool0 (erste Düse) + +--- + +## Hersteller Tags + +### Überblick + +Hersteller Tags ermöglichen es Filament-Produzenten, vorkonfigurierte NFC-Tags zu liefern, die automatisch alle notwendigen Einträge in Spoolman erstellen. + +### Erste Schritte mit Hersteller Tags + +1. **Tag scannen** + - Platzieren Sie die Spule mit dem Hersteller-Tag auf die Waage über dem NFC-Reader + - Bei Problemen beim Lesen: Spule etwas anders positionieren (nicht ganz an den Rand) + - Das System erkennt automatisch das Hersteller-Format + +2. **Automatische Erstellung** + - **Marke** wird in Spoolman angelegt (falls nicht vorhanden) + - **Filament-Typ** wird mit allen Spezifikationen erstellt + - **Spule** wird automatisch registriert + +3. **Zukünftige Scans** + - Nach der ersten Einrichtung nutzen Tags das Fast-Path-System + - Sofortige Gewichtsmessung ohne erneute Einrichtung + +### Unterstützte Hersteller + +- **RecyclingFabrik**: Erster offizieller Partner +- Weitere Hersteller folgen + +### Vorteile + +- ✅ **Null manuelle Einrichtung** +- ✅ **Perfekte Datengenauigkeit** +- ✅ **Sofortige Integration** +- ✅ **Zukunftssicher** + +--- + +## Fehlerbehebung + +### Häufige Probleme + +#### WiFi-Verbindung + +**Problem**: Kann nicht mit FilaMan-Hotspot verbinden +- Lösung: Stellen Sie sicher, dass der ESP32 gestartet ist +- Alternative: Manuell zu http://192.168.4.1 navigieren + +**Problem**: Weboberfläche nicht erreichbar +- Lösung: Prüfen Sie die IP-Adresse im Router +- Alternative: Verwenden Sie http://filaman.local + +#### Waage + +**Problem**: Ungenaue Gewichtsmessungen +- Lösung: Kalibrierung wiederholen +- Tipp: Verwenden Sie "Tare Scale" für Nullstellung + +**Problem**: Wägezelle reagiert nicht +- Lösung: Überprüfen Sie die Verkabelung (E+, E-, A+, A-) +- Tipp: Testen Sie mit einem Multimeter + +#### NFC-Tags + +**Problem**: Tag wird nicht erkannt +- Lösung: Überprüfen Sie die PN532 DIP-Schalter (I2C-Modus) +- Tipp: Spule etwas anders auf der Waage positionieren (nicht ganz an den Rand) + +**Problem**: Tag kann nicht beschrieben werden +- Lösung: Verwenden Sie NTAG215 für bessere Kompatibilität +- Tipp: Stellen Sie sicher, dass der Tag nicht schreibgeschützt ist + +#### Spoolman + +**Problem**: Verbindung zu Spoolman schlägt fehl +- Lösung: Aktivieren Sie SPOOLMAN_DEBUG_MODE=TRUE +- Tipp: Überprüfen Sie die URL-Formatierung + +**Problem**: Spulen werden nicht angezeigt +- Lösung: Stellen Sie sicher, dass Spoolman läuft +- Tipp: Prüfen Sie die Netzwerk-Firewall-Einstellungen + +#### Bambu Lab + +**Problem**: Drucker verbindet nicht +- Lösung: Überprüfen Sie Access Code und IP-Adresse +- Tipp: Stellen Sie sicher, dass der Drucker im LAN-Modus ist + +**Problem**: AMS-Status wird nicht angezeigt +- Lösung: Prüfen Sie die MQTT-Verbindung +- Hinweis: Bambu kann die API jederzeit schließen + +### Debug-Informationen + +Falls Sie Probleme haben, können Sie diese Schritte zur Diagnose verwenden: + +#### Serieller Monitor (für Entwickler) +- Verbinden Sie den ESP32 über USB mit Ihrem Computer +- Öffnen Sie einen seriellen Monitor (z.B. Arduino IDE) mit 115200 Baud +- Sie sehen detaillierte Log-Nachrichten des Systems + +#### Browser-Konsole +- Öffnen Sie die Weboberfläche von FilaMan +- Drücken Sie F12 um die Entwicklertools zu öffnen +- Schauen Sie in der Konsole nach Fehlermeldungen + +#### Neustart bei anhaltenden Problemen +1. ESP32 vom Strom trennen +2. 10 Sekunden warten +3. Wieder anschließen +4. 30 Sekunden für vollständigen Start warten + +--- + +## Support + +### Community + +- **Discord Server**: [https://discord.gg/my7Gvaxj2v](https://discord.gg/my7Gvaxj2v) +- **GitHub Issues**: [Filaman Repository](https://github.com/ManuelW77/Filaman/issues) +- **YouTube Kanal**: [Deutsches Erklärvideo](https://youtu.be/uNDe2wh9SS8?si=b-jYx4I1w62zaOHU) + +### Dokumentation + +- **Offizielle Website**: [www.filaman.app](https://www.filaman.app) +- **GitHub Wiki**: [Detaillierte Dokumentation](https://github.com/ManuelW77/Filaman/wiki) +- **Hardware-Referenz**: ESP32 Pinout-Diagramme in `/img/` + +### Entwicklung unterstützen + +Wenn Sie das Projekt unterstützen möchten: + +[![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png)](https://www.buymeacoffee.com/manuelw) + +### Lizenz + +Dieses Projekt ist unter der MIT-Lizenz veröffentlicht. Siehe [LICENSE](LICENSE.txt) für Details. + +--- + +**Letzte Aktualisierung**: August 2025 +**Version**: 2.0 +**Maintainer**: Manuel W. \ No newline at end of file diff --git a/WIKI_EN.md b/WIKI_EN.md new file mode 100644 index 0000000..5cee6e4 --- /dev/null +++ b/WIKI_EN.md @@ -0,0 +1,746 @@ +# FilaMan Wiki - English + +## Table of Contents + +1. [Overview](#overview) +2. [Installation](#installation) +3. [Hardware Requirements](#hardware-requirements) +4. [Initial Setup](#initial-setup) +5. [Configuration](#configuration) +6. [Usage](#usage) +7. [NFC Tags](#nfc-tags) +8. [Bambu Lab Integration](#bambu-lab-integration) +9. [Spoolman Integration](#spoolman-integration) +10. [Octoprint Integration](#octoprint-integration) +11. [Manufacturer Tags](#manufacturer-tags) +12. [Troubleshooting](#troubleshooting) +13. [Support](#support) + +--- + +## Overview + +FilaMan is a comprehensive filament management system for 3D printers based on ESP32 hardware. It provides weight measurement, NFC tag management, and seamless integration with Spoolman and Bambu Lab 3D printers. + +### Key Features + +- **Precise weight measurement** with HX711 load cell amplifier +- **NFC tag reading and writing** for filament identification +- **OLED display** for status information +- **WiFi connectivity** with easy configuration +- **Web-based user interface** with real-time updates +- **Spoolman integration** for inventory management +- **Bambu Lab AMS control** via MQTT +- **OpenSpool NFC format** compatibility +- **Manufacturer tag support** for automatic setup + +### System Requirements + +- **ESP32 Development Board** +- **Spoolman Instance** (required for full functionality) +- **WiFi Network** +- **Web Browser** (Chrome/Firefox/Safari) + +--- + +## Installation + +### Easy Installation (Recommended) + +1. **Open the [FilaMan Web Installer](https://www.filaman.app/installer.html)** + - Use a Chrome-based browser + +2. **Prepare ESP32** + - Connect ESP32 via USB to your computer + - Click "Connect" + +3. **Select Port** + - Choose the appropriate USB port + - Confirm selection + +4. **Start Installation** + - Click "Install FilaMan" + - Wait for installation to complete + +### Manual Compilation + +For advanced users with PlatformIO: + +```bash +git clone https://github.com/ManuelW77/Filaman.git +cd FilaMan/esp32 +pio lib install +pio run --target upload +``` + +--- + +## Hardware Requirements + +### Required Components + +| Component | Description | Amazon Link (Affiliate) | +|-----------|-------------|-------------------------| +| ESP32 Development Board | Any ESP32 variant | [Amazon](https://amzn.to/3FHea6D) | +| HX711 + Load Cell | 5kg Load Cell Amplifier | [Amazon](https://amzn.to/4ja1KTe) | +| OLED Display | 0.96" I2C 128x64 SSD1306 | [Amazon](https://amzn.to/445aaa9) | +| PN532 NFC Module | V3 RFID Module | [Amazon](https://amzn.eu/d/gy9vaBX) | +| NFC Tags | NTAG213/NTAG215 | [Amazon](https://amzn.to/3E071xO) | +| TTP223 Touch Sensor | Optional for tare function | [Amazon](https://amzn.to/4hTChMK) | + +### Pin Configuration + +| Component | ESP32 Pin | Function | +|-----------|-----------|----------| +| HX711 DOUT | 16 | Load cell data output | +| HX711 SCK | 17 | Load cell clock | +| OLED SDA | 21 | I2C data | +| OLED SCL | 22 | I2C clock | +| PN532 IRQ | 32 | Interrupt | +| PN532 RESET | 33 | Reset | +| PN532 SDA | 21 | I2C data (shared) | +| PN532 SCL | 22 | I2C clock (shared) | +| TTP223 I/O | 25 | Touch sensor (optional) | + +### Important Notes + +- **PN532 DIP switches** must be set to I2C mode +- **3V pin** from ESP32 for touch sensor +- **Load cell wiring**: E+ (red), E- (black), A- (white), A+ (green) + +![Wiring Diagram](./img/Schaltplan.png) + +--- + +## Initial Setup + +### After Installation + +1. **ESP32 Restart** + - System automatically creates a WiFi hotspot "FilaMan" + +2. **WiFi Configuration** + - Connect to the "FilaMan" network + - Open browser (automatic portal or ) + - Configure your WiFi credentials + +3. **First Access** + - After successful WiFi connection, access system at + - Alternative: Use IP address assigned by router + +### Spoolman Preparation + +**Important Note**: Spoolman must run in debug mode: + +```env +# Uncomment in Spoolman's .env file: +SPOOLMAN_DEBUG_MODE=TRUE +``` + +This is required as Spoolman doesn't support CORS domain configuration yet. + +--- + +## Configuration + +### Scale Calibration + +1. **Start Calibration** + - Go to "Scale" page + - Prepare a 500g reference weight (e.g., water glass) + +2. **Calibration Steps** + - Follow instructions on display + - Place weight when prompted + - Wait for calibration to complete + +3. **Validation** + - Test accuracy with known weights + - Use "Tare Scale" for zero adjustment if needed + +### Spoolman Connection + +1. **Enter Spoolman URL** + - Go to "Spoolman/Bambu" page + - Enter complete URL of your Spoolman instance + - Format: `http://spoolman-server:7912` + +2. **Test Connection** + - System automatically checks connection + - Successful connection shown by green status + +### Bambu Lab Printer (Optional) + +1. **Printer Settings** + - Open settings menu on your Bambu printer + - Note the following data: + - Printer IP address + - Access Code + - Serial Number + +2. **FilaMan Configuration** + - Enter printer data on "Spoolman/Bambu" page + - Enable "Auto Send to Bambu" for automatic AMS assignment + +3. **Auto-Send Timeout** + - Configure waiting time for automatic spool detection + - Recommended value: 10-30 seconds + +--- + +## Usage + +### Basic Operation + +1. **Weigh Filament** + - Place spool on scale + - Weight automatically displayed on screen and web interface + +2. **Scan NFC Tag** + - Hold tag near PN532 module + - Recognized tags display spool information + - Weight automatically updated in Spoolman + +3. **Status Monitoring** + - **OLED Display** shows current weight and connection status + - **Web Interface** provides detailed information and control + +### Web Interface Navigation + +- **Home**: Main functions and current status +- **Scale**: Scale calibration and settings +- **Spoolman/Bambu**: System configuration +- **Statistics**: Usage statistics (if enabled) + +--- + +## NFC Tags + +### Supported Tag Types + +- **NTAG213**: 144 bytes (basic functions) +- **NTAG215**: 504 bytes (recommended) +- **NTAG216**: 888 bytes (extended functions) + +### Writing Tags + +1. **Prepare Spool in Spoolman** + - Create new spool in Spoolman + - Ensure all required data is entered + +2. **Start Tag Writing** + - Select spool from list + - Click "Write Tag" + - Display shows "Waiting for Tag" + +3. **Place Tag** + - Position NFC tag on PN532 module + - Wait for confirmation + +4. **Success Message** + - Successful writing shows checkmark + - Tag is now linked to Spoolman spool + +### Reading Tags + +1. **Scan Tag** + - Place the spool with NFC tag on the scale over the NFC reader + - If reading fails: Reposition spool slightly (not completely at the edge) + - Spool information automatically loaded + +2. **Automatic Updates** + - Current weight transferred to Spoolman + - Spool automatically selected in web interface + +--- + +## Bambu Lab Integration + +### AMS (Automatic Material System) + +1. **Display AMS Status** + - Web interface shows current state of all AMS slots + - Loaded slots display filament information + +2. **Manual Filament Assignment** + - Select spool from Spoolman list + - Click corresponding AMS slot icon + - Filament assigned to slot + +3. **Automatic Assignment** + - After weighing with "Auto Send to Bambu" enabled + - System waits for new spools in AMS + - Calibrated filaments automatically assigned + +### Bambu Studio Integration + +1. **Sync Filament Profiles** + - Calibrate filaments in Bambu Studio + - Use Device → AMS → Pencil icon → Select + +2. **Save Setting IDs** + - FilaMan automatically detects available setting IDs + - Click "Save Settings to Spoolman" + - Profiles used for future prints + +### Restore Connection + +- For connection issues, click red dot in menu bar +- System automatically establishes new connection + +--- + +## Spoolman Integration + +### Automatic Functions + +1. **Spool Synchronization** + - Automatic transfer of weight changes + - Real-time updates of spool data + +2. **Extra Fields** + - FilaMan automatically creates required custom fields + - NFC tag UID stored as reference + +3. **Filtering** + - "Show only spools without NFC tag" for easy tag assignment + - Categorization by manufacturers and material types + +### Spoolman Octoprint Plugin + +For Octoprint users, automatic spool assignment is available: + +1. **Install Plugin** + + ```text + https://github.com/ManuelW77/OctoPrint-Spoolman-Filaman/archive/refs/heads/master.zip + ``` + +2. **Configure FilaMan** + - Enable "Send to Octo-Plugin" + - Enter Octoprint URL and API key + +3. **Automatic Assignment** + - After weighing, spool automatically activated in Octoprint + - Currently supports only Tool0 (first nozzle) + +--- + +## Manufacturer Tags + +### Overview + +Manufacturer tags allow filament producers to provide pre-configured NFC tags that automatically create all necessary entries in Spoolman. + +### Getting Started with Manufacturer Tags + +1. **Scan Tag** + - Place spool with manufacturer tag on the scale over the NFC reader + - If reading fails: Reposition spool slightly (not completely at the edge) + - System automatically recognizes manufacturer format + +2. **Automatic Creation** + - **Brand** created in Spoolman (if not present) + - **Filament type** created with all specifications + - **Spool** automatically registered + +3. **Future Scans** + - After initial setup, tags use fast-path system + - Immediate weight measurement without re-setup + +### Supported Manufacturers + +- **RecyclingFabrik**: First official partner +- More manufacturers coming soon + +### Benefits + +- ✅ **Zero manual setup** +- ✅ **Perfect data accuracy** +- ✅ **Instant integration** +- ✅ **Future-proof** + +--- + +## Troubleshooting + +### Common Issues + +#### WiFi Connection + +**Issue**: Cannot connect to FilaMan hotspot + +- Solution: Ensure ESP32 is started +- Alternative: Manually navigate to + +**Issue**: Web interface not accessible + +- Solution: Check IP address in router +- Alternative: Use + +#### Scale + +**Issue**: Inaccurate weight measurements + +- Solution: Repeat calibration +- Tip: Use "Tare Scale" for zero adjustment + +**Issue**: Load cell not responding + +- Solution: Check wiring (E+, E-, A+, A-) +- Tip: Test with multimeter + +#### NFC Tags + +**Issue**: Tag not recognized + +- Solution: Check PN532 DIP switches (I2C mode) +- Tip: Reposition spool slightly on scale (not completely at the edge) + +**Issue**: Cannot write tag + +- Solution: Use NTAG215 for better compatibility +- Tip: Ensure tag is not write-protected + +#### Spoolman + +**Issue**: Connection to Spoolman fails + +- Solution: Enable SPOOLMAN_DEBUG_MODE=TRUE +- Tip: Check URL formatting + +**Issue**: Spools not displayed + +- Solution: Ensure Spoolman is running +- Tip: Check network firewall settings + +#### Bambu Lab + +**Issue**: Printer won't connect + +- Solution: Check access code and IP address +- Tip: Ensure printer is in LAN mode + +**Issue**: AMS status not displayed + +- Solution: Check MQTT connection +- Note: Bambu may close API at any time + +### Debug Information + +If you have problems, you can use these steps for diagnosis: + +#### Serial Monitor (for developers) + +- Connect the ESP32 via USB to your computer +- Open a serial monitor (e.g., Arduino IDE) with 115200 baud +- You will see detailed log messages from the system + +#### Browser Console + +- Open the FilaMan web interface +- Press F12 to open developer tools +- Check the console for error messages + +--- + +## Maintenance and Updates + +### Firmware Update + +1. **Via Web Interface**: Access `http://filaman.local/upgrade.html` +2. **Select firmware file** (.bin format) +3. **Upload** - System restarts automatically +4. **Configuration preserved** - Settings remain intact + +### System Reset + +For persistent issues: + +1. Disconnect ESP32 from power +2. Wait 10 seconds +3. Reconnect +4. Wait 30 seconds for complete startup + +--- + +## Support and Information + +**Manufacturer**: Your Company Name +**Maintainer**: Manuel W. + +### Scale Technology + +#### Weight Stabilization + +The system uses multiple filters for precise measurements: + +```cpp +// Moving Average Filter with 8 values +#define MOVING_AVERAGE_SIZE 8 +// Low-Pass Filter for smoothing +#define LOW_PASS_ALPHA 0.3f +// Thresholds for updates +#define DISPLAY_THRESHOLD 0.3f // Display update +#define API_THRESHOLD 1.5f // API actions +``` + +#### Calibration Algorithm + +1. **System Pause**: All tasks are temporarily paused +2. **Zero Setting**: Tare scale without weight +3. **Reference Measurement**: 500g weight for 10 measurements +4. **Calculation**: `newValue = rawValue / SCALE_LEVEL_WEIGHT` +5. **NVS Storage**: Permanent value with verification +6. **Filter Reset**: New baseline for stabilization + +#### Auto-Tare Logic + +```cpp +// Conditions for Auto-Tare +if (autoTare && (weight > 2 && weight < 7) || weight < -2) { + scale_tare_counter++; + if (scale_tare_counter >= 5) { + // Automatic zero setting + scale.tare(); + resetWeightFilter(); + } +} +``` + +### NFC Technology + +#### PN532 Communication + +- **Interface**: I2C at 400kHz +- **IRQ Pin**: Interrupt-based tag detection +- **Reset Handling**: Automatic recovery from communication errors +- **DIP Switches**: Must be set to I2C mode (00) + +#### NDEF Implementation + +```json +// FilaMan Spoolman Format (with sm_id) +{ + "sm_id": "123", + "color": "#FF5733", + "type": "PLA", + "brand": "Example Brand" +} +``` + +#### Manufacturer Tag Schema + +Compact JSON format for storage efficiency: + +```json +{ + "b": "RecyclingFabrik", // brand + "an": "FX1_PLA-S175-1000-RED", // article number + "t": "PLA", // type + "c": "FF0000", // color (hex without #) + "cn": "Red", // color name + "et": "210", // extruder temp + "bt": "60", // bed temp + "di": "1.75", // diameter + "de": "1.24", // density + "sw": "240", // spool weight + "u": "https://www.yoururl.com/search?q=" // URL used vor Brand Link and Filament Link +} +``` + +### Display System + +#### OLED Architecture (SSD1306) + +- **Resolution**: 128x64 pixels monochrome +- **Areas**: + - Status bar: 0-16 pixels (version, icons) + - Main area: 17-64 pixels (weight, messages) +- **Update Interval**: 1 second for status line + +#### Icon System + +Bitmap icons for various states: + +```cpp +// Status Icons (16x16 pixels) +- icon_success: Checkmark for successful operations +- icon_failed: X for errors +- icon_transfer: Arrow for data transmission +- icon_loading: Loading circle for ongoing operations + +// Connection Icons with strikethrough indicator +- wifi_on/wifi_off: WLAN status +- bambu_on: Bambu Lab connection +- spoolman_on: Spoolman API status +``` + +### API Integration + +#### Spoolman REST API + +FilaMan interacts with the following endpoints: + +```http +GET /api/v1/spool/ # List spools +POST /api/v1/spool/ # Create new spool +PUT /api/v1/spool/{id}/ # Update spool + +GET /api/v1/vendor/ # List vendors +POST /api/v1/vendor/ # Create new vendor + +GET /api/v1/filament/ # List filaments +POST /api/v1/filament/ # Create new filament +``` + +#### Request Handling + +```cpp +// Sequential API processing +enum spoolmanApiStateType { + API_IDLE = 0, + API_PROCESSING = 1, + API_ERROR = 2 +}; +``` + +Prevents simultaneous API calls and deadlocks. + +#### Weight Update Logic + +```cpp +// Conditions for Spoolman update +if (activeSpoolId != "" && + weigthCouterToApi > 3 && // 3+ stable measurements + weightSend == 0 && // Not yet sent + weight > 5 && // Minimum weight 5g + spoolmanApiState == API_IDLE) { + updateSpoolWeight(activeSpoolId, weight); +} +``` + +### Bambu Lab MQTT + +#### Connection Parameters + +```cpp +// SSL/TLS Configuration +#define BAMBU_PORT 8883 +#define BAMBU_USERNAME "bblp" + +// Topic Structure +String topic = "device/" + bambu_serial + "/report"; +String request_topic = "device/" + bambu_serial + "/request"; +``` + +#### AMS Data Structure + +```cpp +struct AMSData { + String tray_id; + String tray_type; + String tray_color; + String tray_material; + String setting_id; + String tray_info_idx; + bool has_spool; +}; +``` + +#### Auto-Send Mechanism + +```cpp +// After tag recognition +if (bambuCredentials.autosend_enable) { + autoSetToBambuSpoolId = activeSpoolId.toInt(); + // Countdown starts automatically + // Waits for new spool in AMS +} +``` + +### WebSocket Communication + +#### Message Types + +```javascript +// Client → Server +{ + "type": "writeNfcTag", + "tagType": "spool", + "payload": { /* JSON data */ } +} + +{ + "type": "scale", + "payload": "tare|calibrate|setAutoTare", + "enabled": true +} + +// Server → Client +{ + "type": "heartbeat", + "freeHeap": 245, + "bambu_connected": true, + "spoolman_connected": true +} + +{ + "type": "amsData", + "data": [ /* AMS array */ ] +} +``` + +#### Connection Management + +- **Auto-Reconnect**: Client-side reconnection +- **Heartbeat**: Every 30 seconds for connection monitoring +- **Cleanup**: Automatic removal of dead connections + +### Watchdog and Error Handling + +#### System Watchdog + +```cpp +// WDT Configuration +esp_task_wdt_init(10, true); // 10s timeout, panic on overflow +esp_task_wdt_add(NULL); // Add current task +``` + +#### Error Recovery + +- **NFC Reset**: Automatic PN532 restart on communication errors +- **MQTT Reconnect**: Bambu Lab connection automatically restored +- **WiFi Monitoring**: Connection check every 60 seconds + +--- + +## Support + +### Community + +- **Discord Server**: [https://discord.gg/my7Gvaxj2v](https://discord.gg/my7Gvaxj2v) +- **GitHub Issues**: [Filaman Repository](https://github.com/ManuelW77/Filaman/issues) +- **YouTube Channel**: [German explanation video](https://youtu.be/uNDe2wh9SS8?si=b-jYx4I1w62zaOHU) + +### Documentation + +- **Official Website**: [www.filaman.app](https://www.filaman.app) +- **GitHub Wiki**: [Detailed documentation](https://github.com/ManuelW77/Filaman/wiki) +- **Hardware Reference**: ESP32 pinout diagrams in `/img/` + +### Support Development + +If you'd like to support the project: + +[![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png)](https://www.buymeacoffee.com/manuelw) + +### License + +This project is released under the MIT License. See [LICENSE](LICENSE.txt) for details. + +--- + +**Last Updated**: August 2025 +**Version**: 2.0 +**Maintainer**: Manuel W. \ No newline at end of file