vmario/fabaccess-docs
1
0
Fork 0
mirror of https://gitlab.com/fabinfra/fabaccess/docs.git synced 2025-01-03 00:53:49 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'spelling_fixes' into 'v0.3'

Browse Source 
Fixed some typos/spelling errors

See merge request fabinfra/fabaccess/docs!5
This commit is contained in:
Pakue95 2024-07-17 19:15:14 +00:00
commit 0f98973431
3 changed files with 30 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
source/usage/audit_log.md
View File

@ -1,5 +1,5 @@
# Audit Log
Bffh will log state changes into the audit log file, one per line.
BFFH will log state changes into the audit log file, one per line.
Audit log entries are for now JSON:
`{"timestamp":1641497361,"machine":"Testmachine","state":{"state":{"InUse":{"uid":"Testuser","subuid":null,"realm":null}}}}`

4
source/usage/nfc.md
View File

@ -51,7 +51,7 @@ Rust - https://gitlab.com/fabinfra/fabaccess/nfc_rs
## Tools
Tool for provisioning new cards for use with the FabAccess card system.
https://gitlab.com/fabinfra/fabaccess/FabFire-Provisioning-Tool
[FabFire-Provisioning-Tool](https://gitlab.com/fabinfra/fabaccess/FabFire-Provisioning-Tool)
FabFire adapter translates mqtt messages from the reader hardware to api
https://gitlab.com/fabinfra/fabaccess/fabfire_adapter
[FabFire Adatper](https://gitlab.com/fabinfra/fabaccess/fabfire_adapter)

54
source/usage/setup_steps.md
View File

@ -3,9 +3,9 @@
This document provides a step by step Instruction on how to get FabAcess running. At the end of this description you will have:
- 1 or more Shellies registered to you system
- 1 or more users registered to your system
- QR-Codes generated to acess a machine
- QR-Codes generated to access a machine
- 1 Shelly configured as a door-opener
- 1 Shelly configured to identify if a machine is just switched on or realy running (TO-DO)
- 1 Shelly configured to identify if a machine is just switched on or really running (TO-DO)
**Step 1 Installing the BFFH-Server**
@ -23,7 +23,7 @@ get the App via Apple Store or Google Apps.
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.
on the console of the system where the BFFH-Server is running. Use the address listed under BROADCAST.
Start the server. If you are using the docker, this is done by using <br>
`docker-compose up -d`. <br>
@ -33,27 +33,27 @@ 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`).
Open the App. You will be asked to connect to a Host. Tap "DEMO HOST ADDRESS" 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 be asked to sign in. For Version 0.2 only the Option "LOGIN WITH PASSWORD" is available. Use `Testuser` and the password `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.
Next step is setting up you machines so they can be switched on and 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.
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.
If your Shelly is already connected to your WLAN, you must find the assigned IP-address (e.g. by looking into your router). Enter this IP address 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:
enter the IP-address from your server in the field "IP-address"
As we did not define MQTT credentials in mosquitto yet, no credentials 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 something like:
`shelly1-123456789ABC` for a Shelly 1
`shelly1pm-123456` for a Shelly 1PM
note this ID for later
@ -66,23 +66,23 @@ 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.
To understand the underlying 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>
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 address. 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 address to the address 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>
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.
(change the IP address 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)
Find the line which starts with `, listens`. You will find three lines stating addresses. The third address needs to be changed to the address of your MQTT broker (most likely the IP address 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>
@ -117,7 +117,7 @@ every time you change the bffh.dhal you need to reload the settings (otherwise t
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.
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 prompt an "on"), by tapping "GIVEBACK" you will deactivate 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>
@ -151,10 +151,10 @@ To keep it simple we create a role called "ChainsawUser"
`, "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
If a user assigned 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
`, permissions = ["lab.machines.chainsaw.admin"]`<br> - additional admin permissions
`}`
The `machine` should be defined as:
@ -167,11 +167,11 @@ The `machine` should be defined as:
` , 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.
If a user is assigned 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.
In version 0.2 a door opener functionality is not implemented. The specific behaviour of a door opener is, to activate a door opening relay 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 address your Shelly is assigned to. This can normally found out in the router of your WiFi. By entering this IP address 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>
@ -198,7 +198,7 @@ Define a machine called "door" in the bffh.dhall<br>
`]`<br>
- assign the role DoorUser/internal to all users
It is imporatant all users have admin aka manage permissions, as the request to open the door by a user, thet the door "in Use" by this user. The door can only be re-activated when the previous user "un-uses" the door or if an othe user can "force free" the door prior to using the door hin/herself.<br>
**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"`).
It is important all users have admin aka manage permissions, as the request to open the door by a user, that the door "in Use" by this user. The door can only be re-activated when the previous user "un-uses" the door or if another user can "force free" the door prior to using the door him/herself.<br>
**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 (disclose, manage, read, write) assigned to the machine would simply match `lab.door.use` (e.g. disclose = "lab.door.use"`).
**Identify if a machine is just switched on or realy running (TO-DO)
**Identify if a machine is just switched on or really running (TO-DO)