FEDEO/agents/fedeo-device-agent/README.md

FEDEO Geräte-Agent

Der FEDEO Geräte-Agent läuft lokal auf macOS, Linux oder Raspberry Pi OS. Er holt instanzweite Scan-Aufträge von FEDEO ab, führt sie auf einem lokal angeschlossenen Scanner aus und lädt das Ergebnis wieder in FEDEO hoch.

Der Agent ist nicht an einen Mandanten gebunden. Jeder Auftrag enthält seinen Tenant selbst.

Geführte Linux-Installation in FEDEO

Unter Administration → Scanner → Agent einrichten führt ein Assistent durch die Einrichtung:

1. Rechner benennen und den Agenten anlegen.
2. Die vom Scanner-Rechner erreichbare FEDEO-Serveradresse prüfen. Ein Backend-Pfad wie /backend muss erhalten bleiben. Optional den Autostart bei der Linux-Anmeldung aktivieren.
3. Linux-Installation herunterladen. Die Datei enthält die Software und die persönliche Konfiguration; ein Projekt-Checkout oder npm install ist nicht nötig.
4. Auf dem Scanner-Rechner im Download-Ordner den angezeigten Befehl bash fedeo-agent-<ID>.sh ausführen, ohne vorangestelltes sudo. Fehlende Pakete werden auf Mint/Ubuntu/Debian über sudo apt-get installiert. Node.js muss mindestens Version 20 haben; bei einer älteren Distribution gegebenenfalls zuerst Node.js aktualisieren.
5. Der Assistent wartet auf eine aktuelle Meldung des Agenten. Danach den erkannten Scanner und beispielsweise das Profil ScanSnap iX1600: A4, Duplex, PDF, 300 dpi wählen und abschließen.
6. Optional Testscan öffnen. Der eingerichtete Agent ist vorausgewählt. Erst ein Klick auf Scannen startet den Einzug; das Ergebnis landet im Hauptordner des aktuellen Mandanten.

Die Installationsdatei enthält einen Zugangstoken. Nach erfolgreicher Einrichtung löschen oder geschützt aufbewahren. Unter Einrichtung öffnen lässt sich ein bestehender Agent erneut installieren. Dafür den gespeicherten Token einfügen oder ausdrücklich einen neuen erzeugen; der bisherige Zugang wird dabei sofort ungültig.

Die Installation ist je Agent getrennt:

• Software: ~/.local/share/fedeo-device-agent/<ID>/
• Konfiguration mit Dateirechten 0600: ~/.config/fedeo-device-agent/<ID>.env
• Arbeitsdateien: ~/.local/state/fedeo-device-agent/<ID>/
• Benutzerdienst: fedeo-device-agent-<ID>.service

Die entsprechenden XDG-Verzeichnisse werden berücksichtigt. Der Autostart beginnt bei der Benutzeranmeldung. Ohne Autostart muss das gestartete Terminal geöffnet bleiben. Protokolle: journalctl --user -u fedeo-device-agent-<ID>.service -f. Eine erneute Installation ersetzt nur die Dateien dieses Agenten.

Voraussetzungen

macOS

brew install node sane-backends
scanimage -L

Für die Dateierstellung wird Python mit Pillow benötigt, beispielsweise über npm run setup:opencv (siehe unten).

Drucken nutzt später das macOS-Drucksystem/CUPS:

lpstat -p

Linux und Raspberry Pi OS

sudo apt update
sudo apt install -y nodejs npm sane-utils python3-pil
scanimage -L

Node.js muss mindestens Version 20 haben (node --version). CUPS ist nur für die optionale Druckererkennung erforderlich.

ScanSnap iX1600 unter Linux per USB

Der iX1600 wird vom SANE-Backend fujitsu per USB unterstützt. Die USB-ID ist 04c5:1632; die WLAN-Schnittstelle wird von diesem Backend nicht unterstützt. Quellen: SANE-Geräteliste, Fujitsu-Backend.

1. Scanner einschalten und per USB anschließen. lsusb -d 04c5:1632 und scanimage -L müssen ihn anzeigen. Den vollständigen Gerätenamen übernehmen, beispielsweise fujitsu:ScanSnap iX1600:123456.

2. Den oben beschriebenen Einrichtungsassistenten verwenden. Für eine manuelle Installation kann alternativ die API POST /api/instance-agents als Administrator einen Agenten und dessen einmalig ausgegebenen Token erstellen.

3. Im Verzeichnis agents/fedeo-device-agent die Abhängigkeiten installieren und konfigurieren:

   npm ci
   cp .env.example .env
   chmod 600 .env
   nano .env
   

   FEDEO_URL=https://deine-fedeo-instanz
   FEDEO_AGENT_TOKEN=fedeo_agent_DEIN_TOKEN
   FEDEO_SCANNER_NAME="fujitsu:ScanSnap iX1600:DEINE_SERIENNUMMER"
   FEDEO_SCAN_SOURCE="ADF Duplex"
   FEDEO_SCAN_FORMAT=pdf
   FEDEO_SCAN_RESOLUTION=300
   FEDEO_SCAN_MODE=Color
   FEDEO_SCAN_POSTPROCESS=false
   FEDEO_SCAN_TIMEOUT_SECONDS=900
   

   FEDEO_URL ist die Basis-URL, unter der /instance-agent/heartbeat erreichbar ist, ohne zusätzliches /api.

4. npm run build und npm start ausführen. In FEDEO muss der Agent als online erscheinen.

5. In der Scannerverwaltung das erkannte Gerät wählen, ScanSnap iX1600: A4, Duplex, PDF anklicken und speichern.

6. Papier einlegen. Unter Dateien → Scan den Agenten wählen und Scannen anklicken. Der gesamte Stapel landet als ein PDF im aktuellen Ordner. Für den ersten Test zwei Blätter mit markierten Vorder- und Rückseiten verwenden: Das PDF muss vier Seiten in dieser Reihenfolge enthalten.

Der Agent liest im SANE-Batch-Modus bis zum leeren Einzug. Vorder- und Rückseiten werden in der vom Scanner gelieferten Reihenfolge gespeichert, einschließlich leerer Rückseiten. Es gibt keine automatische Leerseitenentfernung. „ADF Front“ scannt einen Stapel einseitig, „Flatbed“ eine einzelne Seite. Einzug-Scans benötigen PDF; PNG und TIFF sind für Einzelseiten verfügbar. Die Optionen entsprechen dem scanimage-Handbuch.

Papierformat: Das iX1600-Profil verwendet A4 mit 210 × 297 mm, einschließlich der Fujitsu-Einstellungen für die Papiergröße. Für andere Größen die Einstellung anpassen; „Scanner-Vorgabe“ übernimmt den am Treiber eingestellten Scanbereich. Die SANE-Quellen und Optionen lassen sich ohne Scan mit scanimage -d 'DEIN_GERAETENAME' --source 'ADF Duplex' --help prüfen.

USB-Zugriff: Wenn lsusb das Gerät sieht, scanimage -L jedoch nicht, zuerst Kabel, Stromversorgung, SANE-Version und Zugriffsrechte prüfen. Debian/Ubuntu/Mint liefern normalerweise passende udev-Regeln mit libsane-common. Andere Scanprogramme schließen. Einen dauerhaft laufenden Agenten unter einem Benutzer betreiben, der ebenfalls mit scanimage -L auf das Gerät zugreifen kann.

Lange Stapel und Fehler: Das Scan-Zeitlimit beträgt standardmäßig 15 Minuten; die Dateierstellung hat ein eigenes gleich langes Limit. Der Agent hält seinen Online-Status währenddessen aktuell. Der Dialog kann im Hintergrund weiterlaufen; Schließen stoppt den Scan nicht. Verbindungsfehler beim Abfragen des Status lösen keinen neuen Scan aus. Bei Papierstau, unvollständigem Duplex-Scan oder Uploadfehler wird kein automatischer erneuter Papiereinzug gestartet. Die Rohseiten bzw. die fertige Datei bleiben im gemeldeten Arbeitsverzeichnis zur Wiederherstellung erhalten. Nach erfolgreichem Upload werden sie gelöscht. Das Upload-Limit beträgt 100 MiB pro PDF; gegebenenfalls den Stapel teilen oder die Auflösung reduzieren.

Konfiguration

cp .env.example .env
nano .env

Wichtige Werte:

FEDEO_URL=https://deine-fedeo-instanz
FEDEO_AGENT_TOKEN=fedeo_agent_...
FEDEO_SCANNER_NAME=
FEDEO_POLL_SECONDS=5

Wenn FEDEO_SCANNER_NAME leer bleibt, verwendet scanimage den Standard-Scanner.

Entwicklung

npm ci
npm run dev

Nach Änderungen am Agenten oder am Linux-Installationsskript das im Frontend ausgelieferte Paket neu erstellen und mitcommitten:

npm run build:installer

npm test prüft mit check:installer, dass das Paket dem aktuellen Quellcode entspricht. Das Paket enthält keine Zugangsdaten; diese ergänzt erst der Browser beim Download. Die Installer-Tests verwenden temporäre Verzeichnisse und simulierte Systembefehle.

OpenCV-Nachbearbeitung

Für automatischen Zuschnitt, leichte Entzerrung, Rotation und Kontrastkorrektur kann die OpenCV-Pipeline aktiviert werden.

npm run setup:opencv

Konfiguration:

FEDEO_SCAN_POSTPROCESS=true
FEDEO_SCAN_POSTPROCESS_PROFILE=receipt
FEDEO_SCAN_POSTPROCESS_PYTHON=/pfad/zum/agent/.venv-opencv/bin/python
FEDEO_SCAN_POSTPROCESS_STRICT=false

Wenn FEDEO_SCAN_POSTPROCESS_PYTHON leer bleibt, verwendet der Agent automatisch .venv-opencv/bin/python, sofern diese Umgebung existiert, sonst python3. Pillow ist auch ohne Bildkorrektur für die Dateierstellung erforderlich. Falls OpenCV nicht installiert ist und FEDEO_SCAN_POSTPROCESS_STRICT=false gesetzt ist, werden die Rohseiten im gewünschten Ausgabeformat zusammengeführt. Eine fehlgeschlagene Korrektur verliert keine Seiten. Die Warnung erscheint im Scan-Ergebnis. Beim iX1600-Profil ist die Bildkorrektur zunächst ausgeschaltet, damit der vollständige A4-Scan erhalten bleibt.

Profile:

• receipt: Bons und schmale Belege werden bevorzugt hochkant zugeschnitten und kontrastiert.
• document: allgemeine Dokumente mit Farberhalt und moderater Verbesserung.
• raw: Zuschnitt/Entzerrung ohne starke Kontrastkorrektur.

Container-Betrieb

Auf Linux und Raspberry Pi OS kann der Agent komplett im Container laufen. Dadurch bleiben Node.js, Python, OpenCV und SANE im Image. Auf dem Host werden dann nur Docker und Zugriff auf den USB-Scanner benötigt.

cp .env.example .env
nano .env
docker compose -f docker-compose.example.yml up --build

Wenn FEDEO lokal auf dem Docker-Host läuft, verwende im Container nicht localhost, sondern:

FEDEO_URL=http://host.docker.internal:3100

Scanner im Container prüfen:

docker compose -f docker-compose.example.yml run --rm fedeo-device-agent scanimage -L

Wenn der Scanner nicht sichtbar ist, hilft je nach Gerät/Host manchmal privileged: true im Compose-Beispiel. Auf macOS ist Docker dafür nur eingeschränkt geeignet, weil Docker Desktop USB-Scanner normalerweise nicht direkt an Linux-Container durchreichen kann. Für macOS bleibt deshalb der native Agent oder später eine signierte App der bessere Weg.

Build

npm run build
npm start

Tests

npm test
npm run test:python

Die Tests benötigen Python 3 mit Pillow. Sie simulieren scanimage, erstellen echte PDFs und prüfen Duplex-/Simplex-Stapel, Seitenreihenfolge, Auflösung, leeren Einzug, Papierstau, beschädigte Seiten, Dateinamen und OpenCV-Ausfälle. Ein Test mit angeschlossenem iX1600 bleibt zusätzlich erforderlich.

Hardwareprüfung am 17.09.2026: ScanSnap iX1600 per USB unter Linux Mint 22.3 mit SANE 1.2.1. Zwei A4-Blätter wurden mit 300 dpi in Farbe beidseitig gescannt; das erzeugte PDF enthält vier A4-Seiten in der Reihenfolge Vorderseite/Rückseite. Alle vier Seiten wurden visuell geprüft. Der Test umfasste den lokalen Agenten bis zur PDF-Erstellung; der FEDEO-Upload wird separat mit einem simulierten Dateispeicher getestet.

FEDEO-Endpunkte

Der Agent nutzt:

• POST /instance-agent/heartbeat
• GET /instance-agent/scan-jobs/next
• POST /instance-agent/scan-jobs/:id/status
• POST /instance-agent/scan-jobs/:id/upload

macOS Autostart

Die Vorlage liegt unter system/macos/com.fedeo.device-agent.plist. Nach Anpassung der Pfade kann sie als LaunchAgent installiert werden:

mkdir -p ~/Library/LaunchAgents
cp system/macos/com.fedeo.device-agent.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.fedeo.device-agent.plist

Linux Autostart

Die Vorlage liegt unter system/linux/fedeo-device-agent.service.