Direkt zum Hauptinhalt

FabFire Tools

FabFire Adapter

Der FabFire Adapter übersetzt MQTT Nachrichten von der FabReader-Hardware in die API.

Hier geht's zum GitLab Repository: https://gitlab.com/fabinfra/fabaccess/fabfire_adapter

Installation

Projekt auschecken (als Benutzer bffh)

su - bffh
cd /opt/fabinfra/adapters/
git clone https://gitlab.com/fabinfra/fabaccess/fabfire_adapter.git --recursive
cd fabfire_adapter/
git checkout rebuild #wir verwenden den aktuelleren rebuild Branch

Weg 1: Eine einfache, native Installation ohne Overhead ist mit der virtuellen Python3-Umgebung möglich:

python3 -m venv env
. env/bin/activate
pip3 install -r requirements.txt

Weg 2: Alternative mit dem Dockerfile und Podman:

podman build -f Dockerfile -t fabinfra/fabfire_adapter

Konfiguration

Im Unterverzeichnis config/config.toml werden alle FabReader eingepflegt, die angebunden werden sollen.

Server-Verbindung

In der Sektion [mqtt] geben wir die Verbindung zum MQTT-Server an. Parameter sind:

  • hostname (Pflicht)
  • port (Pflicht)
  • username (optional)
  • password (optional)

Hinweis: aktuell kann keine MQTTS-Verbindung definiert werden. Siehe https://gitlab.com/fabinfra/fabaccess/fabfire_adapter/-/issues/3

Reader-Verbindungen

In der Sektion [reader] geben wir dann die Details der FabReader ein, diese sind:

  • [readers.<Reader-Name>] als Untersektion, eingerückt mit Tabulator - je Reader wird eine neue Sektion eröffnet (siehe Beispiel)
  • id - die FabReader ID
  • machine - die URN der Maschine, die der FabReader kontrollieren soll

Eine Beispielkonfiguration, wie sie auch auf unserem Raspberry Pi 3 Demo Server vorzufinden ist:

[mqtt]
hostname = "127.0.0.1"
port = 1883
username = "fabinfra101"
password = "fablocal"

[bffhd]
hostname = "127.0.0.1"
port = 59661

[readers]
    [readers.zam-raum1-ecke1-lamp]
    id = "00001"
    machine = "urn:fabaccess:resource:zam-raum1-ecke1-lamp"

    [readers.zam-raum1-ecke2-arrow]
    id = "00002"
    machine = "urn:fabaccess:resource:zam-raum1-ecke2-arrow"

Benutzung

Der FabFire Adapter kann manuell wie folgt gestartet werden:

/opt/fabinfra/adapters/fabfire_adapter/env/bin/python3 main.py

Oder mit Podman:

podman run localhost/fabinfra/fabfire_adapter:latest

Ein erfolgreicher Log Output sollte so aussehen:

INFO:root:Registered handler for reader 00001
INFO:root:Registered handler for reader 00002
INFO:root:Initialization done
fabreader/0001/startOTA
fabreader/0001/cancelOTA
fabreader/0001/requestOTA
fabreader/0001/startOTA
fabreader/0001/cancelOTA

Der Adapter muss in Betrieb bleiben, damit die Leser funktionieren. Deshalb installieren wir diesen als systemd Service:

sudo vim /etc/systemd/system/fabfire_adapter.service
[Unit]
Description=FabFire Adapter - translate MQTT messages from FabReader to API calls to bffhd
After=network-online.target
 
[Service]
User=bffh
Restart=on-failure
WorkingDirectory=/opt/fabinfra/adapters/fabfire_adapter/
ExecStart=/opt/fabinfra/adapters/fabfire_adapter/env/bin/python3 main.py
 
[Install]
WantedBy=multi-user.target

Danach aktivieren wir den Dienst und starten ihn. Die Logs prüfen wir über journalctl:

systemctl daemon-reload
systemctl enable fabfire_adapter.service --now
journalctl -f -u fabfire_adapter.service

Troubleshooting

OSError: File not found: schema/connection.capnp

Feb 14 18:35:43 fabaccess python3[6956]:   File "capnp/lib/capnp.pyx", line 4365, in capnp.lib.capnp.load
Feb 14 18:35:43 fabaccess python3[6956]:   File "capnp/lib/capnp.pyx", line 3561, in capnp.lib.capnp.SchemaParser.load
Feb 14 18:35:43 fabaccess python3[6956]: OSError: File not found: schema/connection.capnp

Dieser Fehler erscheint, wenn das Git-Archiv nicht rekursiv ausgecheckt wurde oder aber main.py nicht aus dem korrekten Arbeitsverzeichnis (WorkingDirectory) aus gestartet wird.

FabFire Provisioning Tool

Das FabFire Provisioning Tool dient zur Bereitstellung neuer Karten für das FabAccess-Kartensystem.

Unterstützt werden nur DESFire EV2 Karten!

Hier geht's zum GitLab Repository: https://gitlab.com/fabinfra/fabaccess/FabFire-Provisioning-Tool

Installation

Zunächst klonen wir das git Repository (als Benutzer, der eine Installation von rustup vorweist und damit die ausführbaren Befehle cargo und rustc). In unserem Demo Setup ist das der Benutzer fabinfra-root.

mkdir -p /opt/fabinfra/tools/
cd /opt/fabinfra/tools/
git clone https://gitlab.com/fabinfra/fabaccess/FabFire-Provisioning-Tool.git fabfire-provisioning
cd fabfire-provisioning/
sudo apt install libpcsclite-dev

Danach kompilieren wir zunächst die Anwendung, um eine ausführbare Binary zu erhalten:

cargo build --release

Benutzung

Eine allgemeine Übersicht der Programmiermöglichkeiten erhalten wir zunächst mit:

cargo run -- --help

Die erste Ausführung des Befehls führt eine Kompilierung durch.

Das Provisioning Tool wird wie folgt verwendet. Zunächst wird eine Mifare DESFire EV2 Karte auf einen FabReader aufgelegt. Diese sollte während des Schreibvorgangs nicht vom Gerät entfernt werden. Wir führen dann den folgenden Befehl mit Parametern aus, welche sich teilweise mit unserer Hauptkonfiguration decken, um die aufgelegte Karte für den ausgewählten Nutzer (im Beispiel für den Admin Benutzer) entsprechend zu formatieren:

  • --space - der Name des Spaces
  • --instance - der Name der FabAccess-Instanz. Ähnlich zu instanceurl, aber ohne Protokollteil. Kann z.B. ein Hostname oder ein FQDN sein.
  • --contact - die Angabe, wo bzw. wer im Falle des Kartenverlusts zu kontaktieren ist. Idealweise geben wir hier eine URL zu einer Kontakt- oder Impressumseite an
  • --token - der jeweilige Benutzername, wie er in z.B. in users.toml definiert ist
cargo run -- --space "FabAccess Demo Setup" --instance fabaccess.local --contact https://fab-access.org/impressum --token "Admin"

Die Ausgabe des Befehls spuckt einen Schlüssel aus (cardkey), den wir in die Benutzerdatenbank importieren müssen. Das geht aktuell mit Hilfe der Datei users.toml

Ein eigener Schlüssel und die Anwendungs-ID können mit den entsprechenden cmdline Argumenten angeben werden

Eine Karte formatieren (Reset)

Das Formatieren einer Karte löscht alle Dateien und Schlüssel geht so:

cargo run -- --format


nach oben