From d21229e30fb7d33ab9640e35eac3fa786011b50d Mon Sep 17 00:00:00 2001
From: TheJoKlLa <thejoklla@gmail.com>
Date: Sun, 12 Dec 2021 00:43:57 +0100
Subject: [PATCH] Added: QR-Code
---
source/configuration/bffh_config.md | 89 ++++++++++++++++++-----------
source/index.rst | 1 +
source/usage/feature_qr.md | 7 +++
source/usage/usage.rst | 11 ++++
4 files changed, 76 insertions(+), 32 deletions(-)
create mode 100644 source/usage/feature_qr.md
create mode 100644 source/usage/usage.rst
diff --git a/source/configuration/bffh_config.md b/source/configuration/bffh_config.md
index 9445817..bed04b9 100644
--- a/source/configuration/bffh_config.md
+++ b/source/configuration/bffh_config.md
@@ -3,10 +3,9 @@
BFFH uses [DHALL](https://dhall-lang.org/) for Config-File structure
BFFH uses [RBAC](https://en.wikipedia.org/wiki/Role-based_access_control) for access control
+BFFH Config is in `bffh.dhall` file.
## General BFFH Config
-General BFFH Config is in `bffh.dhall` file.
-
-#### `listens`
+### `listens`
Contains the Addresses BFFH is listen for Connection for the API
Default Port for BFFH is `59661`
@@ -18,14 +17,14 @@ listens =
]
```
-#### `mqtt_url`
+### `mqtt_url`
Contains the Address for the MQTT Server BFFH connects to
**Example:**
```
mqtt_url = "tcp://localhost:1883"
```
-#### `db_path`
+### `db_path`
Contains the Path for the internal Database BFFH uses.
BFFH will create two files: `<db_path>` and `<db_path>-lock`.
Make sure that BFFH has write access in the relevant directory
@@ -34,7 +33,7 @@ Make sure that BFFH has write access in the relevant directory
db_path = "/tmp/bffh"
```
-Permissions
+## Permissions
---
BFFH uses a Path-style string as permission format, separated by ".".
So for example `this.is.a.permission` consists of the parts `this`, `is`, `a` and `permission`.
@@ -92,11 +91,9 @@ This way if you buy a different anycubic and split the permissions to e.g.
It still works out.
-Machine Config
----
-Machine Config is in ```machine.dhall``` file.
+## Machine Config
-#### `machines`
+### `machines`
Contains list of machines
Machines have different perission levels to interact with:
@@ -105,14 +102,23 @@ Machines have different perission levels to interact with:
* write: User can use the machine
* manage: User can interact with the machine as Manager (Check, ForceFree, ForceTransfer)
+Each machine must have an ID to reference the machine in other part of this config or over the API.
+And each machine must have a name.
+
+#### Optional Information
+To provide more information about the machine you can add it to the description or provid an external wiki link.
+Both attributes are only optional and do not need to be set.
+
**Example:**
```
machines =
{
- Testmachine =
+ machine123 =
{
name = "Testmachine",
description = Some "A test machine",
+ wiki = "https://someurl"
+
disclose = "lab.test.read",
read = "lab.test.read",
write = "lab.test.write",
@@ -120,12 +126,11 @@ machines =
}
}
```
+"machine123" is in this case the "Machine-ID"
-Roles Config
----
-Roles Config is in `roles.dhall` file.
+## Roles Config
-#### `roles`
+### `roles`
Contains list of roles
Roles have a list of permission and can be inherited.
@@ -156,43 +161,63 @@ roles =
}
```
-Actors Config
----
-Actors Config is in `actors.dhall` file.
+## Actors Config
-#### `actors`
+### `actors`
Contains list of actors
Actors are defined by a module and one or more paramters
Currenty supported actors:
-**`Shelly`**
-Parameters:
-`id` = ID of the Shelly
+#### `Shelly Actor`
+This actor connects BFFH over an MQTT-Server to an shelly device.
+
+You need to set the `topic` parameter of the Shelly to the Shelly specific MQTT-Topic.
+
+[Find shelly topic here](https://shelly-api-docs.shelly.cloud/gen1/#shelly-plug-plugs-overview)
+
+**Example:**
+```
+actors =
+{
+ Shelly_123 =
+ {
+ module = "Shelly",
+ params =
+ {
+ topic = "shellyplug-s-123456"
+ }
+ }
+}
+```
+"Shelly_123" is in this case the "Actor-ID".
+
+#### `Process Actor`
+This actor makes it possible for you to connect your own Devices to BFFH.
-**`Process`**
-Parameters:
`cmd` = Path of executable
+
`args` = Arguments for executable
**Example:**
```
actors =
{
- Shelly_1234 = { module = "Shelly", params =
- {
- id = "12345"
- }},
- Bash = { module = "Process", params =
+ Bash =
{
- cmd = "./examples/actor.sh",
- args = "your ad could be here"
- }}
+ module = "Process", params =
+ {
+ cmd = "./examples/actor.sh",
+ args = "your ad could be here"
+ }
+ }
}
```
#### `actor_connections`
Connects the actor with a machine
A machine can have multiple actors
+
+Use the "Machine-ID" and "Actor-ID".
**Example:**
```
actor_connections =
diff --git a/source/index.rst b/source/index.rst
index 849d6f0..5fccedb 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -18,3 +18,4 @@ We will inform you about breaking changes over our Zulip. Please subscript to it
installation/installation.rst
configuration/configuration.rst
+ usage/usage.rst
diff --git a/source/usage/feature_qr.md b/source/usage/feature_qr.md
new file mode 100644
index 0000000..f44668d
--- /dev/null
+++ b/source/usage/feature_qr.md
@@ -0,0 +1,7 @@
+# QR-Codes on Machines
+
+To imporve the selection of the right machine for youre users you can apply a QR-Code label on the machine.
+
+The QR-Code must have the following content:
+
+`urn:fabaccess:resource:{machine id}`
\ No newline at end of file
diff --git a/source/usage/usage.rst b/source/usage/usage.rst
new file mode 100644
index 0000000..0947adb
--- /dev/null
+++ b/source/usage/usage.rst
@@ -0,0 +1,11 @@
+Use FabAccess
+=================
+
+FabAccess is highly customisable so you can use FabAccess the way you like to.
+
+But to explain our Features we will documentated some best Practices.
+
+.. toctree::
+ feature_qr.md
+
+