FabAccess Setup - Step By Step

ThisDieses documentDokument providesenthält aeine stepSchritt-für-Schritt-Anleitung, bywie step Instruction on how to getSie FabAcess running.zum AtLaufen thebringen. endAm ofEnde thisdieser descriptionBeschreibung youwerden willSie have:Folgendes haben:

• 1 oroder moremehrere ShelliesShellys registeredin toIhrem youSystem systemregistriert
• 1 oroder moremehrere usersBenutzer, registereddie toinm yourSystem systemregistriert sind
• QR-Codes generatedfür toden acessZugang azu machineeiner Maschine generiert
• 1 Shelly configuredkonfiguriert asals a door-openerTüröffner
• 1 Shelly configuredkonfiguriert, toum identifyzu iferkennen, aob machineeine isMaschine justnur switchedeingeschaltet onist oroder realywirklich runningläuft (TO-DO)

Schritt 1: Installieren des BFFH-Servers

StepEs 1gibt Installingmehrere theMöglichkeiten, den BFFH-Server

therezu areinstallieren. multipleDies wayskann toentweder install the BFFH server. This can bei either done viaüber

• dockerInstallation -mit seeDocker, docker installation documentoder
  
• installingInstallation fromaus sourcedem -Quellcode, see installing from source documentationoder
  
• installingInstallation onunter Ubuntu forfür dummiesDummies

Step

Schritt 22: InstallingInstallieren theder FabAccess App (Borepin)

Siehe Downloads / Demo

get

Schritt the3 App viamit AppleServer Store or Google Apps.

verbinden

StepZuerst 3müssen ConnectSie thedie AppIP-Adresse anddes theServers Server

herausfinden,

Firstfalls youdiese neednoch tonicht findbereits thebekannt IPist. ofDies thekann server.durch ThisEingabe can be done by typingvon ip a onauf theder consoleKonsole ofdes theSystems, systemauf wheredem theder BFFH-Server isläuft, running.erfolgen. UseVerwenden theSie adressdie listedunter underBROADCAST 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.

Step

Schritt 44: PrepareShellys your Shellies

vorbereiten

asSolange long as yourIhr Shelly hasnoch notkeine beenZugangsdaten givenfür theein credentialsWLAN forerhalten ahat, WLAN,erstellt iter willeinen createeigenen anAccess access pointPoint (AP) forzur configurationKonfiguration, whenwenn connecteder toan thedie supplyVersorgungsspannung voltage.angeschlossen Thiswird. Dieser AP will appearwird in yourIhrer listWLAN-Liste oferscheinen. WLAN.Verbinden ConnectSie tosich thismit diesem Shelly-AP andund connectstellen toSie 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 yourIhren browser.Router). AGeben configurationSie page should appear. If your Shelly is already connected to your WLAN, you must find the assigneddiese IP-Adress (e.g. by looking into your router). Enter this IP AdressAdresse in yourIhrem browserBrowser andein youund willSie geterhalten thedie configuration page.Konfigurationsseite.

Shelly MQTT MQTT-Client setupeinrichten

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 WLAN-Client setupeinrichten

gotoGehen “Sie zu „Internet & Security”Sicherheit“ -> “WIFI MODE„WIFI-MODUS - CLIENT”CLIENT“ SetWLAN-Zugangsdaten WLAN Credentialsfestlegen

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).
Use
mosquitto_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 use
mosquitto_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.

LinkDen theServer servermit to thedem MQTT-brokerBroker 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"
    },

PleaseBitte bebeachten awareSie, thatdass “„Identifier-of-your-Machine”Machine“ isdie the internalinterne ID forfür BFFH.BFFH Theist. nameDer ofName theder machineMaschine, shownder in theder App willangezeigt bewird, “ist „Name ofder the Machine”Maschine“.
TheDie givenangegebenen permissionsBerechtigungen aresind okfür toden startAnfang within Ordnung (ifwenn youSie diddie notRollen changedes theTestbenutzers rolesnicht ofgeändert the Testuser)haben). ToUm findmehr outüber moredas aboutBerechtigungskonzept thezu permissionerfahren, conceptlesen seeSie theden “configuration”Teil part„Konfiguration“ ofder the documentation.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 cankönnen beauf generatedverschiedenen onSeiten variousim pages in the internetInternet (e.g.z.B. https://www.qrcode-generator.de),de) thegeneriert “Type”werden, ofder the„Typ“ QRdes codeQR-Codes shouldsollte be„Text“ “Text”.sein. TheDer generatedgenerierte codeCode cankann bedirekt directlymit scanned by theder FabAccess App in theder machineMaschinenübersicht overview.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"
    },

IfWenn aein userBenutzer is„ChainsawUser/internal“ asignedzugewiesen toist, “ChainsawUser/internal”kann he/sheer/sie willdie be able to see and used the chainsawKettensäge in FabAccess.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

ItEs isist imporatantwichtig, alldass usersalle haveBenutzer adminüber akaAdmin- managebzw. permissions,Verwaltungsrechte asverfügen, theda requestdie toAufforderung openzum theÖffnen doorder byTür adurch user,einen thetBenutzer thedazu doorführt, “dass die Tür von diesem Benutzer „in Use”Gebrauch“ byist. thisDie user.Tür Thekann doornur canwieder onlyaktiviert bewerden, re-activatedwenn whender thevorherige previousBenutzer userdie “un-uses”Tür the„ent-benutzt“ dooroder orwenn ifein ananderer otheBenutzer userdie canTür “force„zwangsbefreien“ free”kann, thebevor doorer priorsie toselbst usingbenutzt.

the door hin/herself.

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”`).

**IdentifyErkennen, ifob aeine machineMaschine isnur justeingeschaltet switchedist onoder orwirklich realy runningläuft (TO-DO)