fabaccess-docs/source/usage/Get it Running - Step by Step.md

**FabAcess Step By Step**

This document provides a step by step Instruction on how to get FabAcess running. At the end of this description you will have:
- 2 Users registered to your system
- 2 Shellies registered to you system
- 1 Shelly configured as a door-opener
- 1 Shelly configured to identify if a machine is just switched on or realy running
- 2 QR-Codes generate to acess a machine

**Step 1 Installing the BFFH-Server**

there are multiple ways to install the BFFH server. This can bei either done via 
- docker - see docker installation document
- installing from source - see installing from source documentation
- installing on Ubuntu for dummies

**Step 2 Installing the FabAccess App**

get the App via Apple Store or Google Apps.

**Step 3 Connect the App and the Server**

First you need to find the IP of the server. This can be done by typing
`ip a`
on the console of the system where the BFFH-Server is running. Use the adress listed under BROADCAST.

Start the server. If you are using the docker, this is done by using <br> 
`docker-compose up -d`. <br> 
If you compiled the server on your system this is done by entering <br>
`./diflouroborane -c examples/bffh.dhall --load examples` <br>
and then <br> 
`./diflouroborane -c examples/bffh.dhall`. <br>
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 4 Prepare your Shellies**

as long as your Shelly has not been given the credentials for a WLAN, it will create an access point (AP) for configuration when connected to the supply voltage. This AP will appear in your list of WLAN. 
Connect to this Shelly-AP and connect to `192.168.33.1` in your browser. A configuration page should appear.
If your Shelly is already connected to your WLAN, you must find the assigned IP-Adress (e.g. by looking into your router). Enter this IP Adress in your browser and you will get the configuration page.

**Shelly MQTT Client setup**

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 setup**

goto "Internet & Security" -> "WIFI MODE - CLIENT"
Set WLAN Credentials

**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 <br>
`mosquitto_sub -h 192.168.1.15 -t /test/topic` (change the IP adress to the adress of your server).<br>
Use<br> 
`mosquitto_pub -h localhost -t /test/topic -m "Hallo from BFFH-Server!"`<br> 
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.<br>
If you are interested in communication between the shellies and the BFFH-Server you can use<br>
`mosquitto_sub -h 192.168.1.15 -t shellies/#` <br>
(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.<br>

Link the server to the MQTT-broker<br>
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.<br>
Go to the line where it starts with `, actors =` and after the `{` you can enter your Shelly with <br>
`shelly1-123456789ABC = { module = "Shelly", params = {=}}`<br>
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".<br>
Go to the line starting with `{actors_connections =` and after the following `[` you add<br>
`{ machine = "Identifyer-of-your-Machine", actor = "shelly1-E8DB84A1CFF4" }` <br>
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".<br>
Go to the line starting with `, machines =`. and after the `{` you can add a machine:<br>
`Identifyer-of-your-Machine =` <br>
`   { description = Some "I am your first Testmachine"`<br>
`   , disclose = "lab.test.read"`<br>
`   , manage = "lab.test.admin"`<br>
`    , name = "Name of the Machine"`<br>
`    , read = "lab.test.read"`<br>
`    , write = "lab.test.write"`<br>
`    },`<br>

Please be aware that "Identifyer-of-your-Machine" is the internal ID for BFFH. The name of the machine shown in the App will be "Name of the Machine".<br> 
The given permissions are ok to start with (if you did not change the roles of the Testuser). To find out more about the permission concept see the "configuration" part of the documentation.

**- 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`
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:<br>
`urn:fabaccess:resource:{MachineID}`<br>
e.g.<br>
`urn:fabaccess:resource:Identifyer-of-your-Machine`<br>

QR-Codes can be generated on various pages in the internet (e.g. https://www.qrcode-generator.de), the "Type" of the QR code should be "Text". The generated code can be directly scanned by the FabAccess App in the machine overview.