Update Get it Running - Step by Step.md

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

@@ -1,11 +1,12 @@
 **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
+- 1 or more Shellies registered to you system
-- 2 Shellies registered to you system
+- 1 or more users registered to your system
+- QR-Codes generated to acess a machine
 - 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**
 
@@ -90,12 +91,12 @@ The ID of the Shelly should match the ID of your Shelly. Here you can enter as m
 
 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>
+`{ machine = "Identifier-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>
+`Identifier-of-your-Machine =` <br>
 `   { description = Some "I am your first Testmachine"`<br>
 `   , disclose = "lab.test.read"`<br>
 `   , manage = "lab.test.admin"`<br>
@@ -104,7 +105,7 @@ Go to the line starting with `, machines =`. and after the `{` you can add a mac
 `    , 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> 
+Please be aware that "Identifier-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 )
@@ -126,5 +127,73 @@ e.g.<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.
 
+**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<br>
+`[Name-of-the-User]`<br>
+`roles = ["Name-of-a-role/internal", "Name-of-another-role/internal"]`<br>
+`priority = 0`<br>
+`passwd = "the-chosen-password"`<br>
+`noot = "whatever-this-means"`<br>
+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 =`<br>
+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 =`<br>
+`{ permissions = `<br>
+`[ "lab.machines.chainsaw.write"` - allows the user to use the machine<br>
+`, "lab.machines.chainsaw.read"`- allows the user to read see the status of the machine<br>
+`, "lab.machines.chainsaw.disclose"` - allows the user to see the machine in the machine overview<br>
+`]`
+
+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 =`<br>
+`{ parents = ["ChainsawUser"]`<br> - inherits all the permissions of the ChainsawUser
+`, permissions = ["lab.machines.chainsaw.admin"]`<br> - addinional admin permissions
+`}`
+
+The `machine` should be defined as:
+`Identifier-of-your-Chainsaw =` <br>
+`   { description = Some "Beware of Freddy!"`<br>
+`   , disclose = "lab.machine.chainsaw.disclose"`<br>
+`   , manage = "lab.machine.chainsaw.admin"`<br>
+`    , name = "Chainsaw"`<br>
+`    , read = "lab.machine.chainsaw.read"`<br>
+`    , write = "lab.machine.chainsaw.write"`<br>
+`    },`<br>
+
+If a user is asigned to "ChainsawUser/internal" he/she will be able to see and used the chainsaw in FabAccess.
+
+**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.<br>
+Define a machine called "door" in the bffh.dhall<br>
+-define the actor:<br>
+`shelly1-123456789ABC = { module = "Shelly", params = {=}}`<br>
+-define the machine:<br>
+`{ machine = "door", actor = "shelly1-123456789ABC" }` <br>
+-set permissions for the machine:<br>
+`door =` <br>
+`   { description = Some "close it firmly"`<br>
+`   , disclose = "lab.door.disclose"`<br>
+`   , manage = "lab.door.admin"`<br>
+`    , name = "Door to the Lab"`<br>
+`    , read = "lab.door.read"`<br>
+`    , write = "lab.door.write"`<br>
+`    },`<br>
+-create a role having ALL permissions to the door
+`DoorUser =`<br>
+`{ permissions = `<br>
+`[ "lab.door.write"` - allows the user to use the door<br>
+`, "lab.door.read"`- allows the user to read see the status of the door<br>
+`, "lab.door.disclose"` - allows the user to see the machine in the machine overview<br>
+`, "lab.door.admin"`<br>
+`]`<br>
+-assign the role DoorUser to all users