FabAccess Installation
Wie wird FabAccess installiert? Das findet sich hier! FabAccess hat grundlegend eine Server-Client-Struktur. Diese Dienste müssen entsprechend separat installiert werden.
- Getting Started / Onboarding
- Downloads / Demo
- FabAccess Setup - Schritt für Schritt
- Server - Anleitung zum selber kompilieren
- Server - Installation mit Docker
- Server - Demo Server zum Ausprobieren von FabAccess ohne Installation
- Client (alle Plattformen) - Anleitung zum selber kompilieren
- Client für Android - HowTo: F-Droid Repository einbinden
- Client für Android - mit Waydroid auf Linux installieren
Getting Started / Onboarding
Wir freuen uns über eure Entscheidung, FabAccess in eurer Umgebung zu implementieren und möchten euch mit hier einen reibungslosen Einstieg in die Nutzung ermöglichen. Man fragt sich vielleicht, mit welchen Ressourcen begonnen werden und ob am Ende alles wie geplant funktionieren wird. Mit diesem Getting Started möchten wir euch die Angst nehmen und eine Anleitung geben, wie ihr Schritt für Schritt FabAccess bei euch einführen könnt.
Wir empfehlen euch
- sich vorher in die FabAccess Basics etwas einzulesen. Keine Angst! Am Anfang ist es nicht so einfach zu überschauen. Anhaltspunkte über die grundlegende Funktionsweise zu FabAccess findest du bei den Grundkonzepten.
- einen Überblick über euren Space zu erhalten und zu klären, wo und wie genau ihr FabAccess einsetzen möchtet. Das bezieht sich auf die Maschinen (Liste) und etwaige Berechtigungen (Rollen), die später einmal Anwendung finden sollen.
Gründe für die Nutzung von FabAccess
Warum sollten wir FabAccess nutzen? Die Gründe dafür können vielseitig sein. In der Regel sind es Ziele wie
- Maschinen, die gefährlich sind, viel Strom verbrauchen oder in Anschaffung und Reparatur kostenintensiv sind, nur geschulten / eingewiesenen Personen überlassen
- Eine Übersicht über die Gerätschaften und ggf. deren Nutzung (Zeiten) und/oder Verbräuche (Strom) erfassen
Was wird für FabAccess allgemein benötigt?
- ein oder mehrere Personen, die einen FabAccess Server aufsetzen und betreuen können/wollen - hierzu gibt es verschiedene Rollen, z.B. IT-Administrator, Lab Manager (Schichtleiter, Werstattverantwortlicher, Bereichsleiter oder sonstige Synonyme), Mitglieder, Studenten, sonstige Nutzer
- Zeit zur Integration von Hardware und Software
- Wille, sich Dokumentation durchzulesen und zu verstehen
- Motivation
Was sollten wir integrieren?
In FabAccess lässt sich grundsätzlich jeder Wunsch integrieren. Allerdings ist es nicht immer sinnvoll, da es entweder zu komplex ist, zu viel Zeit kosten würde oder sozial nicht verträglich ist.
Für einen guten Einstieg empfehlen wir, mit den Ressourcen beginnen, deren Nutzung eingeschränkt werden muss. Sobald die Nutzer das System verstanden haben, kann das System auf andere Ressourcen ausgeweitet werden.
Und wo sollen wir anfangen?
Ein guter Start bieten 3D-Drucker, da sich diese einfach mit 230V-Zwischensteckern freischalten lassen. Zudem gibt es dadurch eine direkte Referenz, von welchem Nutzer der letzte Druck stammt.
Welche Hardware sollte gekauft bzw. vorgehalten werden?
FabAccess ist frei skalierbar und der Bedarf hängt von der Werkstatt und den Nutzern ab. Je mehr Räume, Maschinen und Nutzer existieren, desto höher ist der Anspruch an das System.
Ein simples und kostengünstiges Setup von FabAccess lässt sich bereits mit einem Raspberry Pi, einer Fritz!Box und ein ein paar 230V-Schaltsteckdosen ("Zwischenstecker") mit MQTT-Schnittstelle aus. Mit diesen können bereits die ersten Ressourcen in ein funktionsfähiges FabAccess Setuo integriert werden. Alles andere an Hardware kann dann nachgerüstet werden, sobald das System läuft und die entsprechenden Berechtigungen vorhanden sind.
Nach oben hin gibt es bekanntlich keine Grenzen. Hinsichtlich Performance, Sicherheit und Administrierbarkeit ist für viele User durchaus auch ein Serveraufbau empfehlenswert. Hier gibt es verschiedenste Aufbauten.
Struktur-Beispiel Sternenlabor Plauen
- getrennte Wifi SSIDs in der Werkstatt: eine SSID für das "normale" Benutzernetz zum Surfen und eines für Geräte (IoT-Netz)
- Proxmox Server mit
- einer virtuellen Maschine, in der wiederrum mehrere Docker-Container laufen:
- Docker Container für FabAccess BFFH
- Docker Container für einzelne Prometheus Exporter (z.B. FabAccess Exporter, MQTT Exporter)
- Docker Container für Prometheus Service (Metriken sammeln)
- Docker Container für Grafana (Monitoring / Alerting)
- Docker Container für Watchtower (Docker Images automatisch aktualisieren, um alles auf den neuesten Stand zu halten)
- sonstige Container für gekapselte Dienste
- einer weiteren virtuellen Maschine, auf der Portainer läuft. Mit Portainer lassen sich die obigen Container über eine Web-Oberfläche gut administrieren/orchestrieren
- Systemübersicht mit Glances (eine Art
htop
-Variante mit Web Interface) - eine weitere virtuelle Maschine für OPNsense - eine Open Source Firewall, die es erlaubt, dass Nutzer aus dem normalen Benutzer-Wifi auf die FabAccess-Instanz zugreifen können, welche letztlich in einem anderen Netz agiert.
- einer virtuellen Maschine, in der wiederrum mehrere Docker-Container laufen:
Maschinenerfassung für die Integration mit FabAccess
Um einen detaillierten Überblick über eure Maschinen zu erhalten und eine reibungslose Integration mit FabAccess zu gewährleisten, haben wir eine gedankliche Tabellenstruktur vorbereitet, in der ihr die erforderlichen Informationen zu euren Maschinen eintragen könnt. Da FabAccess nicht nur für stationäre Maschinen konzipiert ist, könnt ihr auch andere Geräte in der Tabelle erfassen, deren Nutzung ihr nachverfolgen möchtet.
Welche Informationen sollten erfasst werden?
- Name, Modell und Anzahl
- Name: Gebt jeder Maschine einen eindeutigen Namen
- Modell: Erfasst das genaue Modell der Maschine
- Anzahl: Falls mehrere Maschinen dasselbe Modell haben, notiert die Anzahl
- Kategorie
- Weist jeder Maschine einer Kategorie zu für eine bessere Übersicht (z.B., 3D-Drucker, Lasercutter, Nähmaschine)
- Einweisung
- Klärt, ob eine Einweisung für die Nutzung der Maschine erforderlich ist
- Notiert, wenn es spezielle Einweisungen gibt. Für viele Maschinen ist keine Einweisung notwendig. Dennoch ist es hilfreich zu wissen, wer die Maschine nutzt und wie häufig sie in Gebrauch ist. Diese Informationen könnt ihr in FabAccess hinterlegen, um eine detaillierte Übersicht über die Nutzung zu erhalten.
- Wiki
- Falls bereits ein Wiki-Eintrag für eine Maschine existiert, fügt den entsprechenden Link in FabAccess hinzu
- Wifi
- Prüfe bei der Maschine, ob eine stabile Wifi Verbindung verfügbar ist. Maschinen müssen nicht über Wifi freigeschaltet werden, jedoch ist das der einfachste Einstieg in FabAccess. Wenn ihr FabAccess längerfristig einsetzen möchtet oder schon einen Umbau in eurem Space geplant habt, bietet es sich an auch eine Ethernet-Anbindung an der Maschine zur Verfügung zu haben. So kann der Betrieb mit FabAccess noch reibungsloser verlaufen.
- Freischaltung
- Gebt an, wie die Maschine freigeschaltet wird (z.B., smarte Steckdosen für 230V, Schütze für 400V). Um eine Maschine freizuschalten, benötigt FabAccess die Möglichkeit, einen Freischaltbefehl an die Maschine zu senden. Die Ansteuerung kann je nach Maschinentyp unterschiedlich erfolgen:
- Für einfache Maschinen mit einem 230V Anschluss: Hierfür können smarte Steckdosen verwendet werden
- Für Maschinen mit 400V Anschluss: Die Ansteuerung erfolgt über ein Schütz, um den Strom zuzuschalten
- Für Maschinen, die nicht hart ausgeschaltet werden sollten: Die Ansteuerung kann evtl. über den Not-Aus-Kreis erfolgen. Es ist wichtig zu beachten, dass bei der Ansteuerung über die Stromzufuhr darauf geachtet werden muss, dass die Maschine eine Abschaltung des Stroms während des Betriebs verkraften kann. Für mobile Geräte, die nicht über den Strom geschaltet werden können, empfiehlt sich die Verwendung eines elektromechanischen Schlosses zur Freigabe einer Aufbewahrungsbox.
- Gebt an, wie die Maschine freigeschaltet wird (z.B., smarte Steckdosen für 230V, Schütze für 400V). Um eine Maschine freizuschalten, benötigt FabAccess die Möglichkeit, einen Freischaltbefehl an die Maschine zu senden. Die Ansteuerung kann je nach Maschinentyp unterschiedlich erfolgen:
- Stromanschluss/Leistungsaufnahme
- Notiert den benötigten Stromanschluss (z.B., 230V, 400V)
- Notiert auch die Leistungsaufnahme der Maschine. Die verbrauchte Leistung der Maschine kann entweder durch eigene Messgeräte oder spezielle Zwischenstecker gemessen werden. Diese Informationen sind nicht nur wichtig, um die Nutzungsdauer der Maschine zu verstehen, sondern ermöglichen auch eine Abschätzung der Betriebskosten oder ein automatisiertes Abschalten, wenn die Maschine länger als eine einstellbare Zeit nicht aktiv ist. Mit diesen Informationen könnt ihr nun mit der Modellierung der Berechtigungen fortfahren.
Beispiel einer manuell ausgefüllten Tabelle (nicht ganz vollständig)
Diese Infos lassen sich zum Beispiel auch im FabAccess Config Generator erfassen, der viel Arbeit von obigen Konzepten generalisiert abnimmt!
Modellierung der Berechtigungen
FabAccess ermöglicht eine präzise Kontrolle über die Nutzung von Maschinen. Das System basiert auf einem Rollensystem, das die Berechtigungen für Maschinen in einer Rolle zusammenfasst. Nutzer können diese Rollen erhalten und erhalten dadurch die entsprechenden Maschinenberechtigungen. Maschinen verfügen über vier Berechtigungsfelder (read, write, disclose, manage). Diese Details finden sich unter RBAC (Benutzerrollen und Berechtigungen).
Für einen einfachen Einstieg in dieses System empfiehlt es sich, zwei Standardrollen zu verwenden:
- "Offene Rolle":
Jeder Nutzer, der sich im Space anmeldet, erhält diese Rolle. Mit dieser Rolle können alle frei zugänglichen Maschinen verwendet werden, und es besteht die Möglichkeit, alle öffentlichen Maschinen über die Maschinenliste zu entdecken und Informationen abzurufen. - Administrator-Rolle:
Diese Rolle ermöglicht das Anlegen von Nutzern, das Ansehen aller Maschinen und das Verwalten von Maschinen. Wichtig ist dabei, auch Berechtigungen für das Nutzermanagement hinzuzufügen. Sollten im Space weitere Unterstützer aktiv sein, die jedoch keine Nutzer und Rollen verwalten sollen, kann eine eigene Rolle mit Manage-Berechtigungen erstellt werden.
Für alle weiteren Rollen können diese nach Bedarf entsprechend den erforderlichen Einweisungen für die Maschinen erstellt werden. Als Beispiel: Wenn für 3D-Drucker eine Einweisung erforderlich ist, kann eine Rolle "3D-Drucken" erstellt werden. Wenn jedoch zwischen verschiedenen 3D-Drucker-Typen unterschieden werden soll, können zwei separate Rollen erstellt werden, wie "3D-Drucken FDM" und "3D-Drucken
SLA". Wenn Nutzer alle 3D-Drucker verwenden können sollen, kann entweder jedem Nutzer alle relevanten Rollen zugewiesen oder eine vererbte Rolle wie "3D-Drucken Gesamt" erstellt werden.
Es wird empfohlen, zu Beginn mit feinen Rollen zu arbeiten, da das Entfernen von Rollen für Nutzer im Nachhinein mehr Aufwand bedeutet.
Mit der Berechtigungstabelle könnt ihr erste Entscheidungen darüber treffen, wer auf welche Maschine zugreifen darf und welche Maschinen gemeinsam in einer Berechtigung genutzt werden können. Ebenso könnt ihr festlegen, welche Maschinen für alle zugänglich sein sollen und welche ausschließlich nach einer Freischaltung verwendet werden dürfen.
Die Installation von FabAccess Difluoroborane (BFFH) ist auf jedem Server möglich, der das Ausführen einer kompilierten Rust-Binary erlaubt. Das kann ein Bare Metal Linux Server, ein Proxmox, ein Docker-Container oder sonstige Systeme sein.
Neben der reinen Installation sind weitere Schritte der Vor- und Nachkonfiguration notwendig oder empfehlenswert, um ein sinnvolles und praxistaugliches System zu erhalten.
Vorüberlegungen und Best Practices
Die Installation von FabAccess Difluoroborane (BFFH) ist auf jedem Server möglich, der das Ausführen einer kompilierten Rust-Binary erlaubt. Das kann ein Bare Metal Linux Server, ein Proxmox, ein Docker-Container oder sonstiges System sein.
Neben der reinen Installation sind weitere Schritte der Vor- und Nachkonfiguration notwendig oder empfehlenswert, um ein sinnvolles und praxistaugliches System zu erhalten.
Separierte Netzwerke
Für ein funktionierendes FabAccess-System sollten die Geräte, die Ressourcen freischalten, in einem separaten Netzwerk betrieben werden - also zum Beispiel Tasmota Schaltsteckdosen oder FabReader. Dadurch wird das Risiko minimiert, dass unerwartete Freischaltungen stattfinden.
Wir separieren sozusagen Notebooks und Smartphones der Nutzer (und Gäste), die sich meistens im regulären Netz, von den IoT-Geräten (Maschinen), die die FabAccess-Struktur bilden.
Die Netzwerkseparation kann adminstrativ durch verschiedene Wege erfolgen - zum Beispiel durch VLANs oder eigens für die Geräte aufgespannte Wifi-SSIDs.
Nutzer anlernen und aktiv einbeziehen
- Erklärt das Konzept von FabAccess
- Erklärt, wie der Space FabAccess verwendet
Überautomatisierung vermeiden
Nicht alles, was automasiert werden kann, sollte auch automatisiert werden. Nicht jedes Werkzeug oder jede Maschine sollte weggeschlossen bzw. verriegelt werden. Das nimmt u.U. zu viele Grundrechte oder übertechnisiert den Ausstattungsbedarf und die Wartung des Spaces.
FabAccess sicher machen (physisch + digital)
- Vermeide den physischen Zugriff auf Schalter: Zum Schutz vor Manipulation können z.B. Tasmota Stecker oder Shellys außer Reichweite platziert werden - zum Beispiel unter dem Tisch oder über oder hinter dem Regal
- Etabliere eine sinnvolle Ausgabe von DESFire Karten zum Zugriff auf Maschinen, um die unerlaubte Weitergabe durch Nutzer zu unterbinden
- Verwende sichere Verschlüsselung für die Funkverbindung im MQTT-Netzwerk und anderen Stellen, wo es möglich ist (TLS Verschlüsselung, LetsEncrypt Zertifikate)
Erstelle regelmäßig Backups
Auch bei FabAccess ist es wichtig, regelmäßig Backups der Benutzerdatenbank und der Konfiguration zu erstellen. Nichts wirft einen mehr zurück als der Verlust aller zugewiesenen Rollen durch einen Ausfall.
Es gibt verschiedene Backup-Strategien, je nach vorhandener IT-Infrastruktur, eigenem Geschmack und natürlich auch der Art und Weise, wie FabAccess installiert wurde.
Backups könnten sein:
- kompletter System-Dump (Kopie der Festplatte mitsamt Betriebssystem)
- inkrementelle Backups des Systems oder der FabAccess-relevanten Daten
- Docker-Container Backup
- ein git-Repository, in das wir Konfigurationsdateien pushen und versionieren
Häufig lohnt es sich 1-2 Backup-Strategien zu kombinieren.
Tipp: Backups erstellen ist gut! Noch besser: Testen, ob die Backups im Ernstfall dann auch funktionieren, also ob ein Restore auch problemlos möglich ist!
Siehe auch Backup einrichten
Audit und Zeitsynchronisation
Für Abrechnungsvorgänge oder zum Nachvollziehen von Ereignissen in der Werkstatt sind genaue Zeitstempel wichtig. Es ist deshalb ratsam den Server, auf dem FabAccess BFFH läuft, mit einem Zeitserver zu synchronisieren. Generell ist es empfehlenswert, wenn sich alle Serverdienste und Clients in der Werkstatt auf den gleichen Zeitserver beziehen. Bei Verwendung von kleinen Geräten wie einem Raspberry Pi ist es zudem ggf. hilreich ein RTC (Echtzeituhr) einzubauen, da diese meistens keine eigene Uhrzeit haben. Im Falle eines Internetausfalls hat der Server so trotzdem eine valide Uhrzeitquelle.
Downloads / Demo
Borepin (Mobile App)
Der offizielle Borepin Icon
Borepin ist die Client-Anwendung zur Nutzung von FabAccess. Borepin ist in C# mit Xamarin geschrieben.
Ein paar Screenshots von Borepin
Sprache
Borepin ist derzeitig leider nur in Englisch verfügbar. Eine deutsche Version existiert nicht 😥.
Downloads
Hinweis: auf iOS heißt die App "Borepin", auf Android und Microsoft Windows heißt sie "FabAccess"
- Android *.apk (Version 0.3.11 Build: 791217633)
- Direkter Download von GitLab: https://gitlab.com/fabinfra/fabaccess/borepin/-/releases
- Google Play Store: https://play.google.com/store/apps/details?id=org.fab_infra.fabaccess
- Huawei App Gallery: https://appgallery.huawei.com/app/C107570627
- F-Droid: https://fdroid.fab-access.org/fdroid/repo (Anleitung: HowTo: F-Droid Repository einbinden)
- Apple iOS / iPadOS / macOS (Version 0.3.11)
- Apple Store: https://apps.apple.com/us/app/fabaccess/id1531873374
- Beta-Versionen: https://testflight.apple.com/join/KfeUaHT4
- Microsoft Windows - UWP (Universal Windows Platform - Win 10 + 11) (Version 0.3.6.0 Build: 6 - veraltet!)
- Microsoft App Store: https://apps.microsoft.com/detail/9p69mwzjf2mv
- Microsoft App Store: https://apps.microsoft.com/detail/9p69mwzjf2mv
- Linux
- der offizielle Linux-Build ist derzeit defekt. Die Alternativlösung besteht in der Verwendung von Waydroid (Android Emulator)
Die aktuelle Version von Borepin ist "Final INTERFACER" v0.3.11 vom 17.03.2023 (letztes Update dieser Seite: 23.10.2024)
Vorraussetzungen zum Installieren / Nutzen
- Minimale Apple Versionen:
- iOS: 8.0
- iPadOS: 8.0
- macOS: 11.0 (mit Apple M1 Chip oder neuer)
- Minimale Android Version: 5.0 (API Level 21)
-
- benötigt wird ein laufender, erreichbarer und konfigurierter FabAccess Server. Diese Server-Anwendung nennt sich Difluoroborane oder kurz "BFFH". Der Server muss selbst aufgesetzt sein (self hosted) und im eigenen Space laufen!
Bedienungsanweisungen
Ein Manual inkl. Troubleshooting-Hinweisen für Borepin findest du hier.
Server Anwendung Difluoroborane (BFFH)
Der offizielle BFFH Icon
Downloads
Die Server Files (Releases) finden sich unter GitLab. BFFH kann selbst kompiliert oder als Docker Image installiert werden. Eine vorpaketierte Version (z.B. als deb
oder rpm
Paket) ist derzeit noch nicht verfügbar!
Vorraussetzungen zum Installieren / Nutzen
Je nach Installationsmethode gibt es verschiedene Vorraussetzungen. BFFH ist in der Programmiersprache Rust geschrieben und die API, die verwendet wird, implementiert Cap'n Proto. BFFH kannst selbst kompiliert werden oder du verwendest z.B. ein fertiges Docker Image.
- Zeig mir die Installationsanleitungen.
- Zeig mir das Getting Started.
Die aktuelle Version von BFFH ist "interfacer" (entspricht v0.4.3 Alpha) vom 17.03.2023 (letztes Update dieser Seite: 23.10.2024)
Welche Version nutze ich eigentlich gerade?
Folgendes Kommando kann genutzt werden, um die von dir derzeitig verwendete Version von bffh auszulesen:
/opt/fabinfra/bffh/target/release/bffhd -V
difluoroborane 0.4.2
Changelogs und Versionen
Siehe FabAccess - Versionen, Changelog, Roadmap und beim jeweiligen Repository (siehe oben)
Demo Server
FabAccess vor dem Installieren einfach ausprobieren per Demo-Server. Siehe hier.
Übersicht Software-Lizenzen
Siehe hier: Lizenzübersicht
BookStack Wiki Offline-Download
Du kannst diese Wiki auch herunterladen. Sie wird täglich 1x komplett exportiert und unter https://downloads.fab-access.org bereitgestellt
FabAccess Setup - Schritt für Schritt
Dieses Dokument enthält eine Schritt-für-Schritt-Anleitung, wie Sie FabAcess zum Laufen bringen. Am Ende dieser Beschreibung werden Sie Folgendes haben:
- 1 oder mehrere Shellys in Ihrem System registriert
- 1 oder mehrere Benutzer, die inm System registriert sind
- QR-Codes für den Zugang zu einer Maschine generiert
- 1 Shelly konfiguriert als Türöffner
- 1 Shelly konfiguriert, um zu erkennen, ob eine Maschine nur eingeschaltet ist oder wirklich läuft (TO-DO)
Schritt 1: Installieren des BFFH-Servers
Es gibt mehrere Möglichkeiten, den BFFH-Server zu installieren. Dies kann entweder über
- Installation mit Docker, oder
- Installation aus dem Quellcode, oder
- Installation unter Ubuntu für Dummies
Schritt 2: Installieren der FabAccess App (Borepin)
Siehe Downloads / Demo
Schritt 3 App mit Server verbinden
Zuerst müssen Sie die IP-Adresse des Servers herausfinden, falls diese noch nicht bereits bekannt ist. Dies kann durch Eingabe von ip a
auf der Konsole des Systems, auf dem der BFFH-Server läuft, erfolgen. Verwenden Sie die unter BROADCAST angegebene Adresse.
Start the server. If you are using the docker, this is done by using docker-compose up -d
.
If you compiled the server on your system this is done by entering ./diflouroborane -c examples/bffh.dhall --load examples
and then ./diflouroborane -c examples/bffh.dhall
.
You will see some debug information, with probably some warnings.
Open the App. You will be asked to connect to a Host. Tap “DEMO HOST ADRESS” and change the IP to the IP of your Server, do not change the port number (everything after the IP. This should look like 192.168.1.15:59661
). Tap “SELECT HOST”.
You will be asked to sign in. For Version 0.2 only the Option “LOGIN WITH PASSWORD” ist available. Use Testuser
and the passwort secret
to log in.
You will find an overview of the installed machines including the option “SCAN QR-CODE”. Next step is setting up you machines so they can be switched on an off.
Schritt 4: Shellys vorbereiten
Solange Ihr Shelly noch keine Zugangsdaten für ein WLAN erhalten hat, erstellt er einen eigenen Access Point (AP) zur Konfiguration, wenn er an die Versorgungsspannung angeschlossen wird. Dieser AP wird in Ihrer WLAN-Liste erscheinen. Verbinden Sie sich mit diesem Shelly-AP und stellen Sie in Ihrem Browser eine Verbindung zu 192.168.33.1
her. Es sollte eine Konfigurationsseite erscheinen. Wenn Ihr Shelly bereits mit Ihrem WLAN verbunden ist, müssen Sie die zugewiesene IP-Adresse herausfinden (z.B. durch einen Blick in Ihren Router). Geben Sie diese IP-Adresse in Ihrem Browser ein und Sie erhalten die Konfigurationsseite.
Shelly MQTT-Client einrichten
goto “Internet & Security” -> “Advanced - Developer Settings” enable “MQTT” enter the IP-Adress from your Server in the field “IP-Adress” As we did not define MQTT credentials in mosquitto yet, no creadentials need to be filled in. To find the “ID” of your Shelly activate “Use custom MQTT prefix” (but do not change it!). This should be somthing like: shelly1-123456789ABC
for a Shelly 1 shelly1pm-123456
for a Shelly 1PM note this ID for later - save - re-check the settings!
Shelly WLAN-Client einrichten
Gehen Sie zu „Internet & Sicherheit“ -> „WIFI-MODUS - CLIENT“ WLAN-Zugangsdaten festlegen
Adding a Shelly to your server To understand the underlaying concept of actors and machines, please see the “configuration part” of the documentation. Four our example we will assume we have one actor (shelly) per machine.
Tip Prior to modifying the configuration files the proper working of the MQTT broker should be tested. To test the broker it is the best to use a second (linux) computer with a different IP adress. To test if the broker allows access from an external IP address open a MQTT subscriber on the second computer by typing mosquitto_sub -h 192.168.1.15 -t /test/topic
(change the IP adress to the adress of your server).
Usemosquitto_pub -h localhost -t /test/topic -m "Hallo from BFFH-Server!"
to send a message to the other computer. If the message appears, everything is ok. When not, this should be first solved, as a connection to the shellies will not be possible this way.
If you are interested in communication between the shellies and the BFFH-Server you can usemosquitto_sub -h 192.168.1.15 -t shellies/#
(change the IP adress to your needs). You will see some values popping op from time to time.
Configure Diflouroborane Open the file “bffh.dhall” in the GUI Editor (just by double-clicking it) or use nano bffh.dhall
in your console.
Den Server mit dem MQTT-Broker verbinden
find the line which starts with , listens
. You will find three lines stating addresses. The third address needs to be changed to the adress of your MQTT broker (most likely the IP adress of your BFFH server)
First you have to make your “actors” (in our case the Shellies) know to the system.
Go to the line where it starts with , actors =
and after the {
you can enter your Shelly with shelly1-123456789ABC = { module = "Shelly", params = {=}}
The ID of the Shelly should match the ID of your Shelly. Here you can enter as many actors as you want, each separated by a ,
.
Now you have to link a “machine” to an “actor”.
Go to the line starting with {actors_connections =
and after the following [
you add{ machine = "Identifier-of-your-Machine", actor = "shelly1-E8DB84A1CFF4" }
using your own Name-of-your-Machine and the Shelly-ID of the related actor.
Now you have to set the “access-permissions” to your “machine”.
Go to the line starting with , machines =
. and after the {
you can add a machine:Identifier-of-your-Machine =
{ description = Some "I am your first Testmachine"
, disclose = "lab.test.read"
, manage = "lab.test.admin"
, name = "Name of the Machine"
, read = "lab.test.read"
, write = "lab.test.write"
},
Bitte beachten Sie, dass „Identifier-of-your-Machine“ die interne ID für BFFH ist. Der Name der Maschine, der in der App angezeigt wird, ist „Name der Maschine“.
Die angegebenen Berechtigungen sind für den Anfang in Ordnung (wenn Sie die Rollen des Testbenutzers nicht geändert haben). Um mehr über das Berechtigungskonzept zu erfahren, lesen Sie den Teil „Konfiguration“ der Dokumentation.
- save (if you are using nano, this will be Ctrl-O )
-restart the BFFH-server Important every time you change the bffh.dhal you need to reload the settings (otherwise the App will not connect to the server on restart): ./diflouroborane -c examples/bffh.dhall --load examples/users.toml
and restart start Diflouroborane: ./diflouroborane -c examples/bffh.dhall
Open the App, an you should see the newly created machine in the list. By tapping “USE” you will activate the machine (Shelly will click, the MQTT-listener should promp an “on”), by tapping “GIVEBACK” you will deactivat the machine.
Creating a QR-Code for your machine A QR code allows users to directly enter the UI of the machine, where the machine can be used or given back. The QR code should contain the following content:urn:fabaccess:resource:{MachineID}
e.g.urn:fabaccess:resource:Identifyer-of-your-Machine
QR-Codes können auf verschiedenen Seiten im Internet (z.B. https://www.qrcode-generator.de) generiert werden, der „Typ“ des QR-Codes sollte „Text“ sein. Der generierte Code kann direkt mit der FabAccess App in der Maschinenübersicht gescannt werden.
Adding a user Adding a user to the system consists of two steps
- creating the user
- provide permissions
Users are defined in the file users.toml. To add a user simply add[Name-of-the-User]
roles = ["Name-of-a-role/internal", "Name-of-another-role/internal"]
priority = 0
passwd = "the-chosen-password"
noot = "whatever-this-means"
Adding users or changing existing users does NOT require to restart the system (tested?)
The permissions of the user are defined by the linked roles. The roles are defined in the file bffh.dhall. Open the file bffh.dhall an find the line starting with , roles =
The concept of the role management is described in the “configuration” part of the documentation. To keep it simple we create a role called “ChainsawUser” ChainsawUser =
{ permissions =
[ "lab.machines.chainsaw.write"
- allows the user to use the machine, "lab.machines.chainsaw.read"
- allows the user to read see the status of the machine, "lab.machines.chainsaw.disclose"
- allows the user to see the machine in the machine overview]
If a user assinged to this role uses the chainsaw, no other user is able to use it until this user gives the chainsaw back. To unlock the machine from the user, admin permissions are needed. So there could be an admin role like ChainsawAdmin =
{ parents = ["ChainsawUser"]
- inherits all the permissions of the ChainsawUser , permissions = ["lab.machines.chainsaw.admin"]
- addinional admin permissions }
The machine
should be defined as: Identifier-of-your-Chainsaw =
{ description = Some "Beware of Freddy!"
, disclose = "lab.machine.chainsaw.disclose"
, manage = "lab.machine.chainsaw.admin"
, name = "Chainsaw"
, read = "lab.machine.chainsaw.read"
, write = "lab.machine.chainsaw.write"
},
Wenn ein Benutzer „ChainsawUser/internal“ zugewiesen ist, kann er/sie die Kettensäge in FabAccess sehen und benutzen.
Using a Shelly as a door opener (electronic wise) In version 0.2 a door opener functionality is not implemented. The specific behaviour of a door opener is, to activate a door openeing relais only for a few seconds. This behaviour is not yet implemented in FabAccess, but there is decent way to implement it by other means. The simple Shellies (1, 1pm, 2.5) have an internal timer “AUTO-OFF” which can be set. To use this timer you have to access the settings of the Shelly via a browser on your computer. To do so, you have to know the IP adress your Shelly is assinged to. This can normally found out in the router of your Wifi. By entering this IP adress in your browser you will access the main menu of your Shelly.
Go to “Timer” and set the “AUTO-OFF” to e.g. 3 seconds.
Define a machine called “door” in the bffh.dhall
- define the actor:
shelly1-123456789ABC = { module = "Shelly", params = {=}}
- define the machine:
{ machine = "door", actor = "shelly1-123456789ABC" }
- set permissions for the machine:
door =
{ description = Some "close it firmly"
, disclose = "lab.door.disclose"
, manage = "lab.door.admin"
, name = "Door to the Lab"
, read = "lab.door.read"
, write = "lab.door.write"
},
- create a role having ALL permissions to the door
DoorUser =
{ permissions =
[ "lab.door.write"
- allows the user to use the door, "lab.door.read"
- allows the user to read see the status of the door, "lab.door.disclose"
- allows the user to see the machine in the machine overview, "lab.door.admin"
]
- assign the role DoorUser/internal to all users
Es ist wichtig, dass alle Benutzer über Admin- bzw. Verwaltungsrechte verfügen, da die Aufforderung zum Öffnen der Tür durch einen Benutzer dazu führt, dass die Tür von diesem Benutzer „in Gebrauch“ ist. Die Tür kann nur wieder aktiviert werden, wenn der vorherige Benutzer die Tür „ent-benutzt“ oder wenn ein anderer Benutzer die Tür „zwangsbefreien“ kann, bevor er sie selbst benutzt.
Note in this special case, where all users will need admin capabilities the role could also contain only the permission lab.door.use
and all permissions (disclos, manage, read, write) assigned to the machine would simply match lab.door.use
(e.g. disclose = “lab.door.use”`).
**Erkennen, ob eine Maschine nur eingeschaltet ist oder wirklich läuft (TO-DO)
Server - Anleitung zum selber kompilieren
FabAccess kann auf einer ganzen Reihe von Systemen zu Laufen gebracht werden, zum Beispiel:
Betriebssysteme
- auf Linux/Unix-Basis
- Ubuntu/Kubuntu
- Arch Linux
- Raspberry OS
- Fedora
- CentOS
- NixOS → Luca Lutz vom Hackwerk e.V. fragen
- Synology
- WSL (Windows Subsystem for Linux)
- FreeBSD
- MacOS
Container/Virtualisierung
- Docker
- Portainer
- Kubernetes → Luca Lutz vom Hackwerk e.V. fragen
- Moby
- Proxmox
- LXC
- runc
- Containerd
- VirtualBox
- Boxes
Empfehlungen für Hardware
Allgemeine Empfehlungen sind immer relativ schwer zu treffen. Je nach Größe der Institution und der vorhandenen Software- und Personallandschaft gibt es unterschiedlichste Auffassungen davon, was benötigt wird und wie es mit anderen Systemkomponenten zusammenspielen soll bzw. muss.Grundsätzlich versuchen wir, FabAccess Server mit möglichst wenig Ressourcenverbrauch zu installieren. Grundsätzlich benötigt:
- Festplattenspeicher: ≥16 GB
- BFFH schreibt u.U. fleißig Log-Files (Audit). Außerdem werden ggf. weitere Systeme installiert, wie z.B. Scripts oder Monitoring-Services. Wir empfehlen deshalb pauschal 16 GB oder mehr (für Betriebssystem, BFFH, Services, Log Files und Sonstige + Puffer)
- idealerweise eine schnelle SSD oder Industrial Grade SD-Karte (mit erhöhter Lebensdauer)
- Arbeitsspeicher: ≥ 1,5 GB (zum Kompilieren der Binary)
- CPU Kerne: ≥ 1
- OS Architektur: 64 Bit
- u.U. sinnvoll: USV (unterbrechungsfreie Stromversorgung)
- stabiles Wifi-Netzwerk (viele Aktoren werden u.U. lediglich per WLAN angebunden!)
Setup auf Raspberry Pi 3 mit Raspberry Pi OS (64 Bit)
Wir flashen auf einem beliebigen Rechner eine neue SD-Karte mit Hilfe von rpi-imager
. Siehe https://www.raspberrypi.com/software. Unser Raspberry Pi 3 Model B+ ist vergleichsweise ziemlich alt und hat folgende Specs:
- Broadcom BCM2837B0, Cortex-A53 (ARMv8) 64-Bit-SoC @ 1,4GHz
- 1GB LPDDR2 SDRAM
- 2,4GHz und 5GHz IEEE 802.11.b/g/n/ac Wireless LAN, Bluetooth 4.2, BLE
- Gigabit Ethernet über USB 2.0 (maximaler Durchsatz 300 Mbps)
- Erweiterte 40-polige GPIO-Stiftleiste
- HDMI® in voller Größe
- 4 USB 2.0-Anschlüsse
- CSI-Kamera-Port für den Anschluss einer Raspberry Pi-Kamera
- DSI-Display-Port für den Anschluss eines Raspberry Pi-Touchscreen-Displays
- 4-poliger Stereoausgang und Composite-Video-Anschluss
- Micro-SD-Anschluss zum Laden Ihres Betriebssystems und Speichern von Daten
- 5V/2.5A DC Stromeingang
- Power-over-Ethernet (PoE)-Unterstützung (separater PoE-HAT erforderlich)
Imaging / Provisioning
sudo apt install rpi-imager
Setup-Schritte mit Screenshots zeigen (aufklappen)
Wir vergeben als Benutzername fabinfra-root
und das Passwort vulca
Unser Image: Debian Bookworm Linux MP PREEMPT Debian 1:6.6.51-1+rpt3 (2024-10-08) aarch64
Standardpakete installieren
Wir installieren ein paar Defaults. Einige der folgenden Pakete sind unter Umständen bereits standardmäßig vorinstalliert. Wir geben sie der Vollständigkeit halber trotzdem an.
sudo apt update && sudo apt upgrade
sudo apt install -y vim gsasl libgsasl7-dev libssl-dev libclang-dev build-essential cmake clang capnproto cargo mosquitto mosquitto-clients
Die richtige Rust Version installieren (1.66.1)
rustc --version
cargo --version
rustc 1.63.0
cargo 1.65.0
# Da wir mit rust 1.63.0 Fehler beim Kompilieren von bffh bekommen, downgraden wir es!
apt purge rustc libstd-rust-1.63 libstd-rust-dev
# Wir installieren das aktuelle Rust (als normaler Nutzer). Jedoch mit dem Unterschied, dass dieses das Tool den Befehl "rustup" mitbringt, womit wir letztlich die korrekte, alte Zielversion 1.66.1 installieren können
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs > rust.sh
chmod +x rust.sh
./rust.sh -v #install rust - dauert ca. 10 Minuten - wir installieren die Standardvariante 1)
rm rust.sh
#cargo in .bashrc einfügen
echo 'source "$HOME/.cargo/env"' >> ~/.bashrc
source ~/.bashrc
#zu alter Version downgraden:
rustup install 1.66.1
rustup default 1.66.1
#Version erneut checken
rustc --version
cargo --version
rustc 1.66.1 (90743e729 2023-01-10)
cargo 1.66.1 (ad779e08b 2023-01-10)
Folgenden Fehler erhalten wir später beim Kompilieren von bffh, wenn rust zu neu ist, sodass wir gleich vorbeugen:
(signal: 11, SIGSEGV: invalid memory reference)
Mosquitto vorbereiten
sudo vim /etc/mosquitto/mosquitto.conf
Wir lassen Mosquitto auf IPv4 und IPv6 lauschen und binden es an alle Interfaces (0.0.0.0
bzw ::
), da unsere MQTT Aktoren im Netzwerk sonst den Server nicht erreichen. Aus Sicherheitsgründen erlauben wir keine anonymen Zugriffe (allow_anonymous false
). Außerdem legen wir eine Passwortdatei an, die mindestens einen Nutzer + Passwort enthält, gegen den sich sowohl der bffh Server, als auch die MQTT Geräte später authentifizieren.
# Place your local configuration in /etc/mosquitto/conf.d/
# /usr/share/doc/mosquitto/examples/mosquitto.conf.example
# note: :: does not automatically configure 0.0.0.0
listener 1883 ::
listener 1883 0.0.0.0
allow_anonymous false
password_file /etc/mosquitto/pw.file
pid_file /run/mosquitto/mosquitto.pid
persistence true
persistence_location /var/lib/mosquitto/
#log_dest file /var/log/mosquitto/mosquitto.log
#log to journald
log_dest syslog
include_dir /etc/mosquitto/conf.d
Passwortdatei anlegen
Wir erzeugen einen Standardnutzer und nennen ihn fabaccess-defaultuser
(kann beliebig genannt werden) und vergeben ein Passwort. Wir verwenden als Passwort den Wert default
sudo mosquitto_passwd -c /etc/mosquitto/pw.file fabaccess-defaultuser
sudo chmod 400 /etc/mosquitto/pw.file
Es können beliebig viele Nutzer in die Passwortdatei geschrieben werden. Das hängt vom gewünschten Setup ab!
Berechtigungen anpassen
sudo chown -R mosquitto:mosquitto /etc/mosquitto/
Mosquitto Dienst starten
sudo systemctl restart mosquitto.service
sudo journalctl -f -u mosquitto.service
Je nach Konfiguration von Mosquitto finden wir die Log-Einträge nun entweder per journalctl im syslog oder in einer separaten Datei.
Swap File erhöhen
BFFH benötigt zum Kompilieren mehr als 1 GB RAM. Ein Raspberry Pi 3 hat nur 1 GB. Dadurch stürzt er beim Kompilieren mit OOM-Fehlern ab. Deshalb erhöhen wir den Swap temporär auf 2 GB. Dieser Trick basiert auf https://www.alibabacloud.com/blog/optimization-on-memory-usage-during-rust-cargo-code-compiling_601189
sudo su
dphys-swapfile swapoff
echo "CONF_SWAPSIZE=2048" > /etc/dphys-swapfile
dphys-swapfile setup
dphys-swapfile swapon
# Überprüfen von "Swp" mit htop
htop
BFFH Nutzer anlegen
Wir legen einen gesonderten Nutzer zum Ausführen von BFFH an. Es ist ein Systembenutzer ohne eigenes Homeverzeichnis (-s
Parameter).
sudo useradd -m -s /bin/bash bffh
Damit der Nutzer bffh allerdings Python-Scripts ausführen darf, benötigt er weitere Gruppenberechtigungen
BFFH Installation (Version "interfacer" - entspricht v0.4.3 Alpha - vom 17.03.2023)
Nach dem Installieren von Mosquitto können wir uns unserem BFFH Server widmen. Wir arbeiten nachfolgend im Verzeichnis /opt/fabinfra/
. Es kann aber jedes andere Verzeichnis verwendet werden
mkdir -p /opt/fabinfra/
cd /opt/fabinfra/
git clone https://gitlab.com/fabinfra/fabaccess/bffh.git --recursive
cd /opt/fabinfra/bffh/
#wir wechseln den Branch auf die aktuellste Entwicklerversion. Siehe https://gitlab.com/fabinfra/fabaccess/bffh/-/commits/feature%2Fclaims_api -> das lassen wir, denn es klappt nicht mit "cargo build --release"
#git checkout feature/claims_api
#wir wechseln zum Branch "development"
git checkout development
# Submodules updaten
git submodule update --remote
# BFFH kompilieren
cargo build --release #dauert ca. 25-35 Minuten
# Standard-Dateien kopieren
cp -R /opt/fabinfra/bffh/examples/ /opt/fabinfra/bffh/target/release/
Zertifikat erzeugen (self signed)
Das Zertifikat benötigen wir für den bffh Server, da wir es in der Konfigurationsdatei angeben müssen.
sudo mkdir -p /opt/fabinfra/bffh-data/cert/
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /opt/fabinfra/bffh-data/cert/bffh-selfsigned.key -out /opt/fabinfra/bffh-data/cert/bffh-selfsigned.crt
Das Ergebnis der folgenden Prüfung muss lauten: Version: 3 (0x2)
sudo openssl x509 -in /opt/fabinfra/bffh-data/cert/bffh-selfsigned.crt -noout -text | grep "Version"
Konfiguration (bffh.dhall) anlegen
Wir legen ein neues Verzeichnis an und kopieren die Beispielkonfiguration dort hin.
mkdir -p /opt/fabinfra/bffh-data/config/
cp /opt/fabinfra/bffh/examples/bffh.dhall /opt/fabinfra/bffh-data/config/bffh.dhall
vim /opt/fabinfra/bffh-data/config/bffh.dhall
Wir passen die Konfiguration nun an unsere Wünsche an. Die Referenz für die Konfiguration findest du hier.
Nutzerdatenbank (users.toml) anlegen und importieren
cp /opt/fabinfra/bffh/examples/users.toml /opt/fabinfra/bffh-data/config/users.toml
vim /opt/fabinfra/bffh-data/config/users.toml
Hier geht's zur Dokumentationen der users.toml
Nach dem Anlegen der Nutzerdatenbank importieren wir diese in bffh mit folgendem Kommando (dabei ist auch die Hauptkonfiguration bffh.dhall
anzugeben!):
/opt/fabinfra/bffh/target/release/bffhd --config /opt/fabinfra/bffh-data/config/bffh.dhall --load /opt/fabinfra/bffh-data/config/users.toml
Bei jeder Änderung der users.toml
Datei muss ein Import durchgeführt werden, da bffh die Änderungen nicht automatisch einliest!
Berechtigungen und Besitzer anpassen
Damit nur Nutzer und Gruppe, nicht aber Externe auf die Dateien zugreifen können, beschränken wir den Zugriff auf unseren Ordner /opt/fabinfra
. In diesem Verzeichnis befinden sich nur Dienste und Configs, die von bffh
ausgeführt werden sollen. Sollten Dateien nachträglich hinzugefügt oder modifiziert werden ist darauf zu achten, dass der Eigentümer und die Berechtigungen entsprechend angepasst werden.
BFFH_DIR="/opt/fabinfra/"
sudo find $BFFH_DIR -type d -exec chmod 750 {} +
sudo find $BFFH_DIR -type f -exec chmod 640 {} +
chown -R bffh:bffh $BFFH_DIR
Achtung beim Naming
bffhd
ist unser bffh Daemon und impliziert mit seinem Namen, dass das Programm permanent laufen soll. Wir verwenden nachfolgend systemd zum Installieren von bffhd
als Service. Den Service nennen wir jedoch bffh.service
- so, wie der Serverdienst heißt.
Server starten (manueller Test)
Wir starten den Dienst bffhd
manuell und dann prüfen wir, ob er auf dem richtigen Port und Interface lauscht:
/opt/fabinfra/bffh/target/release/bffhd --verbose --config /opt/fabinfra/bffh-data/config/bffh.dhall --log-format Pretty
netstat -an | grep "LISTEN" | grep -v "LISTENING"
Hinweis: bffhd
erzeugt oder verwendet beim Starten zwei Dateien, und zwar eine Lock-Datei namens bffh-lock
und eine interne Datenbankdatei bffh
, die die Machine States und die Benutzer enthält, die aus users.toml
stammen.
systemd Service anlegen und bffh automatisch starten
Wenn unser manueller Test geklappt hat, dann sollten wir bffh als Dienst installieren und uns die Arbeit abnehmen lassen:
vim /opt/fabinfra/bffh-data/bffh.service
[Unit]
Description=FabAccess BFFH Service
After=network.target
[Service]
Type=simple
User=bffh
Group=bffh
ExecStartPre=/opt/fabinfra/bffh/target/release/bffhd --check --config /opt/fabinfra/bffh-data/config/bffh.dhall
#BFFH_LOG levels: trace,debug,warn,info,error
Environment="BFFH_LOG=warn"
#log-format: Full, Compact, Pretty
ExecStart=/opt/fabinfra/bffh/target/release/bffhd --verbose --config /opt/fabinfra/bffh-data/config/bffh.dhall --log-format Pretty
Restart=on-failure
RestartSec=30
ExecStopPost=/usr/bin/bash /opt/fabinfra/scripts/bffh-state.sh $EXIT_CODE
[Install]
WantedBy=multi-user.target
Dienst aktivieren, starten und prüfen
sudo ln -sf /opt/fabinfra/bffh-data/bffh.service /etc/systemd/system/bffh.service
sudo systemctl daemon-reload
sudo systemctl enable bffh.service --now
journalctl -f -u bffh.service
Log-Größe von journalctl beachten
Je nach Konfiguration des Log Levels von BFFH und der Anzahl der aktiven Nutzer kann die Logdatei innerhalb von 1-2 Wochen auf über 5 GB und mehr anwachsen und insbesondere bei Systemen auf Basis von SD-Karten zum Defekt des Schreibmediums führen, denn diese altern durch die vielen Schreibzyklen sehr schnell. im produktiven Fall ist deshalb zum einen darauf zu achten, dass die SD-Karte stets überlebt (Log Level auf Info
setzen), und dass das System nicht voll läuft. Hier ein paar Kommandos, um das Journal zu leeren (dies schützt nicht vor den Schreibzyklen, aber erlaubt eine bessere Übersicht).
sudo journalctl --rotate
sudo journalctl --vacuum-time=1s
Auch syslog läuft unter Umständen voll und kann geleert werden. Das ist allerdings ein sehr unschöner Trick und sollte nur zu absoluten Testzwecken angewendet werden:
sudo truncate -s 0 /var/log/syslog
Arch Linux
sudo pacman -Syu
sudo pacman -S make cmake clang gsasl
sudo pacman -S git rust capnproto
Todo ...
CentOS
sudo yum update
sudo yum install curl && curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
sudo yum install epel-release && sudo yum install capnproto
sudo yum install https://packages.endpointdev.com/rhel/7/os/x86_64/endpoint-repo.x86_64.rpm && sudo yum install git
sudo yum install centos-release-scl && yum install llvm-toolset-7 && scl enable llvm-toolset-7 bash (Change bash to youre shell)
sudo yum install gcc-c++ libgsasl-devel openssl-devel cmake
Todo ...
Server - Installation mit Docker
Docker Image can not run on armv6 (Raspberry Pi 1 or Raspberry Pi Zero)
-
Install Docker
On Raspberry Pi: https://phoenixnap.com/kb/docker-on-raspberry-pi
-
Install Docker-Compose
On Raspberry Pi: https://dev.to/elalemanyo/how-to-install-docker-and-docker-compose-on-raspberry-pi-1mo
-
Get Docker-Compose Files
git clone https://gitlab.com/fabinfra/fabaccess/dockercompose.git fabaccess-server
The Dockerfile is in the root directory of the main repo docker-compose.yml is available in a seperate git repo
-
Edit config files in
config
folder to taste -
Start Server with
docker-compose up -d
To make it eaysier to apply youre changes in your config and keep the dockercompose uptodate, you should “fork” this respository.
Get Server Logs: docker-compose logs
- Docker + certbot oder dnsrobocert + automatische Zertifikate für bffh und mosquitto
- dnsrobocert: kann wohl auch Zertifikate für nicht öffentliche erreichbare Server erstellen
Server - Demo Server zum Ausprobieren von FabAccess ohne Installation
Du bist neu und willst FabAccess vorher antesten? Dann lohnt sich der Aufwand der Installation vermutlich nicht, bevor du einen Eindruck gewonnen hast. Hier findest du Details zu unserem Demo Server. Informationen zum Download des Clients, den du für das Testen in jedem Fall benötigst, findest du hier.
Zwecke eines Demo-Servers
- Client damit verbinden, um diesen auszuprobieren - die getriggerten Aktionen durch den Server können in einem Log angezeigt werden
- dem Demo-Tester Zugriff auf ein Sample-Grafana-Monitoring geben, was an bffh gekoppelt ist
- weitere Idee: Nutzer können sich selbst eine Demo-Instanz spawnen, wo sie eine eigene Config schnell und einfach vor dem Live-Gehen ausprobieren können (als eine Art Staging-System)
siehe https://fab-access.readthedocs.io/en/0.9/de/example/usecases
Online Demo Server unter test.fab-access.org
Aktuell gibt es keinen laufenden Demo-Server unter test.fab-access.org. Das ist eine ToDo
Lokaler Demo Server mit Raspberry Pi 3 B+, Fritz!Box 4040 und Tasmota Nous A1T Schaltsteckdosen
Für die JHV des VOW zum 23.11.2024 wurde ein praktisches Demo-Setup angelegt (ein Raspberry Pi, ein Router, ein paar echte Aktoren und ein virtueller Script-Aktor). Dieses Setup wird hier geteilt. Es kann inspiziert, heruntergeladen und sogar für die eigene Werkstatt temporär ausgeliehen werden.
Wie sieht das Setup aus?
Das Setup basiert auf der Dokumentation Server - Anleitung zum selber kompilieren
Raspberry Pi Image Klon erzeugen
Dieser Schritt ist nur zu Informationszwecken abgebildet. Für den Nutzer des Demo Servers wird er nicht benötigt!
Hierzu wurde das SD-Karten Image vom Pi zunächst in eine Datei gedumped:
sudo dd if=/dev/sda of=~/fabinfra.img bs=1M status=progress
Das Image verkleinern wir dann mit PiShrink so, dass es auch auf schmalere SD-Karten passt (Unser Setup hat eine 64 GB SD, aber so lässt es sich auch auf z.B: 32 GB große Karten installieren). Wir installieren PiShrink zunächst:
sudo apt update && sudo apt install -y wget parted gzip pigz xz-utils udev e2fsprogs
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
chmod +x pishrink.sh
sudo mv pishrink.sh /usr/local/bin
Dann verkleinern wir das Image:
pishrink.sh ~/fabinfra.img
Im Anschluss verkleinern wir das Image nochmals, indem wir es packen. Damit können wir teilweise 20 GB große Images in 5 GB große *.gz Files komprimieren.
gzip --best --verbose ~/fabinfra.img > ~/fabinfra.img.gz
Raspberry Pi Image flashen
Du hast das Image heruntergeladen und möchtest es auf deinen Raspberry Pi 3 B+ installieren? Dafür benötigst du eine wenigsten 32 GB große MicroSD Karte und ein Flashing Tool deiner Wahl.
Wir empfehlen Balena Etcher. Der Flash-Vorgang ist hier sehr simpel: Image auswählen, Zieldatenträger auswählen, dann Flash! drücken und ein paar Minuten warten. Danach die SD-Karte unmounten und in den Raspberry Pi stecken und boooten. Fertig!
Fritz!Box 4040 Einstellungen
Wer eine Fritz!Box 4040 oder eine andere Fritz!Box mit Firmware 8.0.0 oder höher hat, kann die Einstellungen vom Demo-Setup simpel bei seiner eigenen Fritz!Box importieren und testen. Dazu loggen wir uns in die Fritz!Box ein und manövrieren zu System
→ Sicherung
→ Wiederherstellen
:
Das Passwort findet sich in der Auflistung Übersicht Geräte, Dienste und Credentials.
.
Übersicht Geräte, Dienste und Credentials
Fritz!Box 4040
- Hostname:
fabinfra101
- IPv4-Adresse:
192.168.188.1
- Web Interface(s): https://fabinfra101.fritz.box
- Benutzer:
fabmin
- Passswort:
QDa7YCPB68hYP58rNR89
- Benutzer:
- Wifi SSIDs
fabinfra101_2400
undfabinfra101_5000
- Passwort:
desfire.2019!
- Für Sicherung/Wiederherstellung der Grundkonfiguration (Sicherungsexport):
fabinfra101
- Firmware 8.0.0
Raspberry Pi 3 B+
- Hostname:
fabaccess
- IPv4-Adressen:
- LAN:
192.168.188.31
- Wifi:
192.168.188.34
- LAN:
- SSH-Zugang
- Benutzer:
fabinfra-root
- Passswort:
vulca
- Benutzer:
- FabAccess Server (BFFH) läuft auf Port
59661
- Grafana
- http://192.168.188.31:3000
- Admin Benutzer:
- Benutzer:
admin
- Passwort:
FABfana%2024-
- Benutzer:
- Viewer Benutzer:
- Benutzer:
viewer
- Passwort:
viewer
- Benutzer:
- http://192.168.188.31:3000
- Prometheus
- http://192.168.188.31:9090
- Basic Auth Benutzer:
- Benutzer:
admin
- Passwort:
prometheus
- Benutzer:
- Mosquitto MQTT Server
- Adresse:
192.168.188.31:1883
- Benutzer:
fabinfra101
- Passwort:
fablocal
- Adresse:
Aktoren
In unserem Demo-Setup sind 6 Nous A1T Schaltsteckdosen mit Tasmota Firmware vorkonfiguriert. Außerdem findet sich ein Sound Aktor zur Wiedergabe einer mp3 per Audioklinke (3,5mm) wieder.
- Schaltsteckdosen Nous A1T mit Tasmota Firmware 14.3.0
- Hostname:
tasmota_1
bistasmota_6
- IP-Adresse:
192.168.188.41
bis192.168.188.46
- Web-Interface: http://192.168.188.41 bis http://192.168.188.46
- Web Benutzer (überall gleich):
- Benutzer:
admin
- Passwort:
fabinfra101
- Benutzer:
Maschinenliste
maschinenliste.csv (erstellt für und genutzt mit FabAccess Config Generator).
Downloads
- Raspberry Pi 3 B+ SD-Card Image Dump (*.gz Format)
- Fritz!Box 4040 Konfigurationsbackup (Firmware 8.0.0)
- Anleitungsdokumente
- Maschinenliste (als ODS für PDF/CSV Export und Import in FabAccess Config Generator)
- URL: https://downloads.fab-access.org/?dir=rpi3bplus-demo-setup
Anleitungsdokumente anzeigen
Ausleihen - FabAccess Wander-Setup
Wer FabAccess als Demo ausprobieren will, kann sich die vorkonfigurierte Demo-Hardware ausleihen und damit herumtesten - als "FabAccess Wander-Setup" sozusagen. Hierzu tretet in Kontakt mit Mario Voigt. Er ist Maintainer des Setups und der Hardware. Er kümmert sich um
- Leihvertrag (mit Kaution/Pfand für die Hardware)
- Zurücksetzen der Konfiguration
- Versand der Hardware
Die Inhaltsliste des Wander-Setups umfasst:
- 1x Fritz!Box 4040 mit Firmware 8.0.0, Netzteil
- 1x Raspberry Pi 3 B+ mit 64 GB SD-Karte und Netzteil
- 1x Ethernet-Kabel
- 3x Steckdosenleiste 3-fach
- 6x Nous A1T Schaltsteckdosen inklusive Safebox
- eine Hand voll FabAccess Sticker
- Anleitungsdokumente als Ausdruck
- Alles funktional vorkonfiguriert!
- Kaution: Gesamtwert der Hardware liegt bei ca. 150 €
Noch benötigt von euch:
- Zeit zum Testen
- ein paar Geräte, die in die Tasmota Schaltsteckdosen angesteckt werden können
- Endgeräte mit vorinstalliertem Client
Client (alle Plattformen) - Anleitung zum selber kompilieren
On Windows
-
Install Visual Studio 2019 download Visual Studio
- with Xamarin
- with UWP
- with .NET Desktop
-
Install GTKSharp for Windows download GTKSharp
-
Install capnproto
3.1 If you have Chocolatey installed
$ choco install capnproto
3.2 else you can download it from here and add it to your PATH
-
Clone Borepin download Borepin
-
Load Borepin
-
Build Borepin
If Step 5. Build Borepin is failing because of GTKSharp, it could help to restart your PC.
Linux GTK
Auf Linux benötigen wir das große Paket für Mono. Mono ist eine alternative, quelloffene Implementierung von Microsofts .NET Framework. Sie ermöglicht die Entwicklung von plattformunabhängiger Software auf den Standards der Common Language Infrastructure und der Programmiersprache C#.
Ubuntu 24
Auf Ubuntu gehen wir wie folgt vor:
# Mono Repository hinzufügen
sudo apt install ca-certificates gnupg
sudo gpg --homedir /tmp --no-default-keyring --keyring /usr/share/keyrings/mono-official-archive-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
echo "deb [signed-by=/usr/share/keyrings/mono-official-archive-keyring.gpg] https://download.mono-project.com/repo/ubuntu stable-focal main" | sudo tee /etc/apt/sources.list.d/mono-official-stable.list
sudo apt update
# Mono und weitere Pakete installieren
sudo apt install mono-complete gtk-sharp2 libcanberra-gtk-module nuget capnproto git
nuget update -self
Projekt klonen
cd ~/
git clone https://gitlab.com/fabinfra/fabaccess/client.git --recurse-submodules
cd client/
In dem Repo herumstochern und Projekt kompilieren
cd ~/client/
#Entfernen, was wir nicht brauchen
rm -rf ~/client/Borepin/Borepin.Android/
rm -rf ~/client/Borepin/Borepin.UWP/
rm -rf ~/client/Borepin/Borepin.iOS/
rm -rf ~/client/Borepin/Borepin.macOS/
rm -rf ~/client/Borepin_Test/
rm -rf ~/client/FabAccessAPI_Test/
#diese Einträge entfernen wir außerdem in:
vim Borepin.sln
nuget restore
cd packages/
nuget install NLog
nuget install dryioc.dll -Version 4.7.7
#in den folgenden 3 Dateien tauschen wir die Version für DryIoc von 5.3.1 zu 4.7.7
vim ~/client/Borepin/Borepin.GTK/app.config
vim ~/client/Borepin/Borepin.GTK/Borepin.GTK.csproj
vim ~/client/Borepin/Borepin.GTK/packages.config
msbuild /restore
msbuild -t:Borepin_GTK
cp ~/client/packages/NLog.5.3.4/lib/net45/NLog.* ~/client/Borepin/Borepin.GTK/bin/Debug/
Borepin starten
Das konnte aktuell nicht erfolgreich durchgeführt werden
mono ~/client/Borepin/Borepin.GTK/bin/Debug/Borepin.GTK.exe
der StackTrace:
(Borepin.GTK:4704): Gtk-WARNING **: 01:31:17.439: Im Modulpfad »adwaita« konnte keine Themen-Engine gefunden werden,
Exception in Gtk# callback delegate
Note: Applications can use GLib.ExceptionManager.UnhandledException to handle the exception.
System.NullReferenceException: Object reference not set to an instance of an object
at Xamarin.Forms.Platform.GTK.Platform.GetRenderer (Xamarin.Forms.VisualElement element) [0x00000] in <db5c3415edd24a4aa8ae86f8bebc9a57>:0
at Xamarin.Forms.Platform.GTK.FormsWindow.OnConfigureEvent (Gdk.EventConfigure evnt) [0x00033] in <db5c3415edd24a4aa8ae86f8bebc9a57>:0
at Gtk.Widget.configureevent_cb (System.IntPtr widget, System.IntPtr evnt) [0x00014] in <7aab76e87bce48a4b45cf7fa613cb70c>:0
at GLib.ExceptionManager.RaiseUnhandledException (System.Exception e, System.Boolean is_terminal) [0x00000] in <ed39f21b9e9343dcbd442a17ad356a9f>:0
at Gtk.Widget.configureevent_cb (System.IntPtr widget, System.IntPtr evnt) [0x00000] in <7aab76e87bce48a4b45cf7fa613cb70c>:0
at Gtk.Application.gtk_main () [0x00000] in <7aab76e87bce48a4b45cf7fa613cb70c>:0
at Gtk.Application.Run () [0x00000] in <7aab76e87bce48a4b45cf7fa613cb70c>:0
at Borepin.GTK.MainClass.Main (System.String[] args) [0x00000] in <674198d89d1447e7b051f706516309ae>:0
oder mit Wine
Das konnte aktuell nicht erfolgreich durchgeführt werden
sudo apt install wine
sudo apt-get install winetricks
winetricks dotnet45
#Borepin starten
wine ~/client/Borepin/Borepin.GTK/bin/Debug/Borepin.GTK.exe
ArchLinux
pacman -S mono mono-msbuild gtk-sharp-2 nuget capnproto
... und so weiter
IDEs zum Entwickeln von Borepin
macOS / iOS
-
Install Visual Studio for Mac
-
Install capnproto If you install capnp with Homebrew you may have to symlink the capnp binary into ‘/usr/local/bin’, or bring it into your PATH another way.
-
Clone Borepin
$ git clone https://gitlab.com/fabinfra/fabaccess/client.git --recurse-submodules
-
Open in Visual Studio
-
Build
Client für Android - HowTo: F-Droid Repository einbinden
F-Droid ist ein alternativer Store Ersatz für den Google Play Store auf Android. Damit lassen sich viele Apps auch ohne Google Account installieren. Allerdings muss dafür zunächst der F-Droid Store installiert werden und im Anschluss bedarf es dem Einbinden einer externen Paketquelle (die von FabAccess).
Download von F-Droid: https://f-droid.org/de
1. Quelle hinzufügen
Wir öffnen im gestarteten F-Droid Einstellungen
→ Paketquellen (Zusätzliche Paketquellen hinzufügen)
→ +
Wir fügen den Link der Paketquelle ein: https://fdroid.fab-access.org/fdroid/repo
2. Nach FabAccess suchen und App installieren
Nach Einbinden und Aktualisieren sollte die Suche erfolgreich sein, wenn nach "fabaccess" gesucht wird:
Client für Android - mit Waydroid auf Linux installieren
Waydroid ist ein unter GNU GPL v3 lizensierter und einer von vielen gängigen Emulatoren für Android auf Linux-Systemen. Wir nutzen es, um FabAccess für Linux verfügbar zu machen (alternativ zum GTK Mono Client Build). Waydroid verwendet einen LXC-Unterbau (Container, ähnlich Docker), um zu spawnen. Wir berufen uns grundlegend auf die offizielle Dokumentation unter https://docs.waydro.id/usage/install-on-desktops.
Basic Setup
Diese Dokumentation beruht auf folgendem Beispielsystem:
- Setup Datum: 04.11.2024
- OS: Kubuntu 24.04 mit aktiviertem Wayland
- Waydroid 1.4.3 mit LineageOS 18.1 (Android 11)
Das grundlegende Setup:
sudo apt update && sudo apt upgrade
sudo apt install curl ca-certificates -y
curl -s https://repo.waydro.id | sudo bash
sudo apt install waydroid -y
# Die installierte Waydroid Version checken
dpkg -l | grep waydroid
#Init ausführen (Images installieren)
# Folgendes Images werden dabei automatisch von https://sourceforge.net/projects/waydroid/files/images/system/lineage/waydroid_x86_64/ geladen:
# - LineageOS 18.1 (20241102 VANILLA) - das Image ist ca. 800 MB groß
# - LineageOS 18.1 (20241102 MAINLINE) - das Image ist ca. 180 MB groß
sudo waydroid init
Service und Logs
Waydroid wird automatisch als Service installiert und auch gestartet. Wir können den Service starten, stoppen und neustarten, und darüberhinaus Logs auslesen:
sudo systemctl status waydroid-container.service
sudo systemctl start waydroid-container.service
sudo systemctl stop waydroid-container.service
# Journal und Log File:
sudo journalctl -f -u waydroid-container.service
sudo less /var/lib/waydroid/waydroid.log
#oder kurz:
waydroid log
Python pip und venv installieren
sudo apt install python3-pip python3-venv
Zwischenablage (Clipboard) reparieren
Bei der Installation klappt u.U. die geteilte Zwischenablage nicht. In diesem Fall benötigt es die folgenden Pakete
sudo apt install wl-clipboard
sudo pip install pyclip --break-system-packages #unsauberer Trick. Hat jemand eine bessere Lösung?
Session starten
# als normaler Nutzer
waydroid session start
# oder im Hintergrund:
nohup waydroid session start &
Optionen konfigurieren
Wir stellen an ein paar Schrauben!
Für das Ausführen muss eine Waydroid Session bereits laufen!
Multi-Window Option setzen
Aktiviert/Deaktiviert die Fensterintegration mit dem Desktop)
waydroid prop set persist.waydroid.multi_windows true
Auflösung des Fensters anpassen
Standardmäßig wird die Session im Vollbildmodus gestartet. Auf einem großen Monitor ist das ggf. screcklich. Das lässt sich optional setzen. Siehe https://github.com/waydroid/waydroid/issues/700
# Zum Zurücksetzen der Standardeinstellungen folgendes ausführen:
waydroid prop set persist.waydroid.width ""
waydroid prop set persist.waydroid.height ""
# Höhe aus Breite berechnen per Verhältnis (z.B. 16:9):
#width = 900 / 16 * 9 =~ 506
waydroid prop set persist.waydroid.height 900
waydroid prop set persist.waydroid.width 506
Netzwerk-Traffic zwischen Gast und Host erlauben
Falls nach der Installation Anwendungen in Waydroid keine Internetverbindung haben, fehlt möglicherweise eine Konfiguration in der Firewall und/oder in einem Waydroid-Script. Siehe auch https://github.com/waydroid/waydroid/issues/143
Fix in Waydroid Script
sudo sed -i~ -E 's/=.\$\(command -v (nft|ip6?tables-legacy).*/=/g' /usr/lib/waydroid/data/scripts/waydroid-net.sh
ARM-Builds auf x86-Systemen erlauben (libhoudini) und mehr
Normalerweise wird Waydroid vermutlich eher auf einem x86-System installiert werden. Android Applications (APKs) sind aber häufig nur für arm7/arm8 kompiliert. Dafür gibt es einen Workaround namens libhoudini. Dafür nutzen wir folgendes Script aus dem Projekt https://github.com/casualsnek/waydroid_script. Wir legen uns eine virtuelle Umgebung (venv) für das Projekt an und installieren die Requirements.
# als normaler Nutzer
cd ~
git clone https://github.com/casualsnek/waydroid_script
cd waydroid_script/
python3 -m venv venv
venv/bin/pip install -r requirements.txt
Danach führen wir aus und wählen libhoudini aus:
sudo venv/bin/python3 main.py
Mit der Leertaste können Pakete ab- oder zugewählt werden:
Danach startet die Installation. libhoudini ist ca. 100 MB groß.
FabAccess Client (Borepin) installieren
Wir laden den Client als APK-Datei direkt herunter:
# als normaler Nutzer
cd ~
wget https://gitlab.com/api/v4/projects/20862588/packages/generic/borepin/v0.3.11/org.fab_infra.fabaccess-Signed.apk
waydroid app install org.fab_infra.fabaccess-Signed.apk
# wir prüfen, ob das geklappt hat:
waydroid app list | grep fabaccess
# der Output sollte sein:
packageName: org.fab_infra.fabaccess
Siehe auch Downloads / Demo
Waydroid Client anzeigen und benutzen
Nachdem der Container gestartet ist und die Session läuft, können wir das User Interface anzeigen:
# als normaler Nutzer
waydroid show-full-ui
Die Standardoberfläche bei/nach dem Start:
Und letztlich Borepin in Waydroid:
Waydroid in einem Fenster anzeigen
Unter Wayland hat das Client-Fenster leider keine Drag&Drop-Funktion. Wir können es in einen Rahmen einsperren, in dem wir das Tool "cage" verwenden
sudo apt install cage
# und dann Waydroid ins Fenster zwingen:
cage waydroid show-full-ui
Dadurch erhalten wir folgende Ansicht:
FabAccess Borepin aus dem Startmenü heraus starten
Waydroid wird standardmäßig in das Menü eingebunden:
Im Menü-Editor kann dieser Eintrag auch angesehen werden:
FabAccess Borepin per Kommandozeile starten
Das geht auch:
waydroid app launch org.fab_infra.fabaccess
Waydroid Upgrade
Waydroid bekommt regelmäßig Updates. Wir können mit folgendem Befehl aktualisieren:
sudo waydroid upgrade