Update Get it Running - Step by Step.md

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

@@ -44,7 +44,7 @@ as long as your Shelly has not been given the credentials for a WLAN, it will cr
 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
+**Shelly MQTT Client setup**
 
 goto "Internet & Security" -> "Advanced - Developer Settings"
 enable "MQTT"
@@ -57,15 +57,45 @@ note this ID for later
 **- save**
 **- re-check the settings!**
 
-Shelly WLAN Client setup
+**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 `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.<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/#` (change the IP adress to your needs).<br>
+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>
+
+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 = "Name-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.<br>
+Go to the line starting with `, machines =`. and after the `{` you can add a machine:<br>
+`Name-of-your-Machine =
+{ description = Some "I am your first Testmachine"
+    , disclose = "lab.test.read"
+    , manage = "lab.test.admin"
+    , name = "Shelly Rot"
+    , read = "lab.test.read"
+    , write = "lab.test.write"
+    },`
 
-20. Configure Diflouroborane
-Open the file "bffh.dhall" in the GUI Editor (just by double-clicking it)
-Change `Shelly_123` to your Shelly name, e.g. `shelly1-123456789ABC`  (**case sensitive!, dash sensitive!**) in "Link up machines to actors" and in "actors".
 Change the third IP-adress under "listens" to the IP-adress of your computer.
 **- save**