188 lines
8.6 KiB
Markdown
188 lines
8.6 KiB
Markdown
# 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.
|
||
|
||
## Voraussetzungen
|
||
|
||
### macOS
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
lpstat -p
|
||
```
|
||
|
||
### Linux und Raspberry Pi OS
|
||
|
||
```bash
|
||
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](https://sane-project.gitlab.io/website/sane-mfgs.html), [Fujitsu-Backend](https://sane-project.gitlab.io/website/man/sane-fujitsu.5.html).
|
||
|
||
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. In FEDEO unter **Administration → Scanner** einen Agenten anlegen und den einmalig angezeigten Token sichern.
|
||
3. Im Verzeichnis `agents/fedeo-device-agent` die Abhängigkeiten installieren und konfigurieren:
|
||
|
||
```bash
|
||
npm ci
|
||
cp .env.example .env
|
||
chmod 600 .env
|
||
nano .env
|
||
```
|
||
|
||
```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](https://sane-project.gitlab.io/website/man/scanimage.1.html).
|
||
|
||
**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
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
nano .env
|
||
```
|
||
|
||
Wichtige Werte:
|
||
|
||
```env
|
||
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
|
||
|
||
```bash
|
||
npm ci
|
||
npm run dev
|
||
```
|
||
|
||
## OpenCV-Nachbearbeitung
|
||
|
||
Für automatischen Zuschnitt, leichte Entzerrung, Rotation und Kontrastkorrektur kann die OpenCV-Pipeline aktiviert werden.
|
||
|
||
```bash
|
||
npm run setup:opencv
|
||
```
|
||
|
||
Konfiguration:
|
||
|
||
```env
|
||
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.
|
||
|
||
```bash
|
||
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:
|
||
|
||
```env
|
||
FEDEO_URL=http://host.docker.internal:3100
|
||
```
|
||
|
||
Scanner im Container prüfen:
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
npm run build
|
||
npm start
|
||
```
|
||
|
||
## Tests
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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`.
|