Merge branch 'mkdocs' into 'master'

Update source/configuration/configuration.rst,...

See merge request fabinfra/fabaccess/docs!7

.gitignore

@@ -1,2 +1,129 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
 build/
-.nfs*
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/

.gitlab-ci.yml

@@ -0,0 +1,24 @@
+image: python:3.8-buster
+
+before_script:
+  - pip install -r requirements.txt
+
+test:
+  stage: test
+  script:
+  - mkdocs build --strict --verbose --site-dir test
+  artifacts:
+    paths:
+    - test
+  rules:
+    - if: $CI_COMMIT_REF_NAME != $CI_DEFAULT_BRANCH
+
+pages:
+  stage: deploy
+  script:
+  - mkdocs build --strict --verbose
+  artifacts:
+    paths:
+    - public
+  rules:
+    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

.readthedocs.yaml

@@ -0,0 +1,20 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: requirements.txt

CONTRIBUTE.md

@@ -1,91 +0,0 @@
-# Contributing
-
-When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.
-
-Please note we have a code of conduct, please follow it in all your interactions with the project.
-
-## Build process
-
-- Install Sphinx packages for your system.
-
-```sudo pacman -S python-sphinx```
-or ```apt install python-sphinx```
-
-- Clone or update the gitlab-repo of the documentation
-
-```git clone git@gitlab.com:fabinfra/fabaccess-docs.git```
-or ```git pull```
-
-- cd into the cloned directory
-
-```cd fabaccess-docs```
-
-- Edit the sources with your favourite editor (vim / emacs / whatever).
-
-If you're not familiar with the Sphinx Documentation Generator, you may have a look at https://www.sphinx-doc.org/en/1.5.2/contents.html
-
-- Build the HTML-files:
-
-```make html```
-
- .. or the PDF-File:
-
-```make latexpdf```
-
-
-## Pull Request Process
-
-1. Ensure any install or build dependencies are removed before the end of the layer when doing a build.
-2. Update the README.md with details of changes. This includes useful file locations and parameters.
-3. Increase the version numbers in any examples files and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/).
-4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.
-
-
-## Code of Conduct
-
-### Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
-
-
-### Our Standards
-
-Examples of behavior that contributes to creating a positive environment include:
-- Using welcoming and inclusive language
-- Being respectful of differing viewpoints and experiences
-- Gracefully accepting constructive criticism
-- Focusing on what is best for the community
-- Showing empathy towards other community members
-
-
-### Examples of unacceptable behavior by participants include:
-
-- The use of sexualized language or imagery and unwelcome sexual attention or advances
-- Trolling, insulting/derogatory comments, and personal or political attacks
-- Public or private harassment
-- Publishing others' private information, such as a physical or electronic address, without explicit permission
-- Other conduct which could reasonably be considered inappropriate in a professional setting
-
-
-### Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
-
-
-### Scope
-
-This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
-
-
-### Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [info@fab-access.org]. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
-
-
-### Attribution
-
-This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at http://contributor-covenant.org/version/1/4
-

Makefile

@@ -1,20 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

README.md

@@ -1,3 +1,4 @@
 # fabaccess-docs
 
-Documentation for the fabaccess project.
+Documentation for the fabaccess project.
+You can find the rendered docs at: https://fab-access.readthedocs.io/ or https://docs.fab-access.org 

docs/api.md

@@ -0,0 +1 @@
+# API Reference

docs/index.de.md

@@ -0,0 +1 @@
+# Wilkommen DE

docs/index.en.md

@@ -0,0 +1 @@
+# Welcome EN

docs/usage.md

@@ -0,0 +1,3 @@
+Usage
+=====
+

make.bat

@@ -1,35 +0,0 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-set BUILDDIR=build
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd

mkdocs.yml

@@ -0,0 +1,27 @@
+site_name: FabAccess Documentation
+# site_url: https://pages.gitlab.io/mkdocs
+site_dir: public
+
+theme:
+  name: material
+  palette:
+    primary: blue
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        # See: https://mkdocstrings.github.io/python/usage/
+        python:
+          options:
+            docstring_style: sphinx
+  - i18n:
+      default_language: en
+      languages:
+        en: English
+        de: Deutsch
+
+markdown_extensions:
+  - markdown_include.include:
+      base_path: .
+  - admonition

requirements.txt

@@ -0,0 +1,68 @@
+#
+# This file is autogenerated by pip-compile with python 3.10
+# To update, run:
+#
+#    pip-compile docs/requirements.in
+#
+click==8.1.3
+    # via mkdocs
+ghp-import==2.1.0
+    # via mkdocs
+griffe==0.22.0
+    # via mkdocstrings-python
+importlib-metadata==4.12.0
+    # via mkdocs
+jinja2==3.1.2
+    # via
+    #   mkdocs
+    #   mkdocstrings
+markdown==3.3.7
+    # via
+    #   markdown-include
+    #   mkdocs
+    #   mkdocs-autorefs
+    #   mkdocstrings
+    #   pymdown-extensions
+markdown-include==0.6.0
+    # via -r docs/requirements.in
+markupsafe==2.1.1
+    # via
+    #   jinja2
+    #   mkdocstrings
+mergedeep==1.3.4
+    # via mkdocs
+mkdocs==1.3.0
+    # via
+    #   -r docs/requirements.in
+    #   mkdocs-autorefs
+    #   mkdocstrings
+mkdocs-autorefs==0.4.1
+    # via mkdocstrings
+mkdocstrings[python]==0.19.0
+    # via
+    #   -r docs/requirements.in
+    #   mkdocstrings-python
+mkdocstrings-python==0.7.1
+    # via mkdocstrings
+mkdocs-material == 7.1.11
+mkdocs-static-i18n == 0.18
+packaging==21.3
+    # via mkdocs
+pymdown-extensions==9.5
+    # via mkdocstrings
+pyparsing==3.0.9
+    # via packaging
+python-dateutil==2.8.2
+    # via ghp-import
+pyyaml==5.3.1
+    # via
+    #   mkdocs
+    #   pyyaml-env-tag
+pyyaml-env-tag==0.1
+    # via mkdocs
+six==1.16.0
+    # via python-dateutil
+watchdog==2.1.9
+    # via mkdocs
+zipp==3.8.0
+    # via importlib-metadata

source/concepts/claims.de.md

@@ -0,0 +1,22 @@
+# Claim Konzept
+Das Claim Konzept dienen als Abstraktion des Verleihens einer Ressource in FabAccess. Ihr Hauptzweck besteht darin, die Möglichkeiten zu verwalten, wie Benutzer Zugriff auf eine Ressource erhalten und diesen Zugriff untereinander teilen können.
+
+## Claims
+Ein "Claim" in FabAccess repräsentiert den gewährten Zugriff auf eine Ressource.
+
+Die Flexibilität von Claims ermöglicht es, verschiedene Szenarien des Ressourcenzugriffs effektiv zu unterstützen. Zum Beispiel können mehrere Benutzer gleichzeitig einen Claim für eine Ressource erhalten, was besonders in Umgebungen mit kollaborativem Arbeiten von Vorteil ist. Darüber hinaus bietet die Möglichkeit, sich in eine Warteschlange mit einem Interest einzutragen, eine praktische Lösung für Situationen, in denen die Verfügbarkeit einer Ressource begrenzt ist und Benutzer darauf warten müssen, darauf zugreifen zu können.
+
+Ein weiterer wichtiger Aspekt von Claims ist ihre Fähigkeit, Ressourcen zwischen Benutzern zu transferieren oder auszuleihen. Diese Funktionen ermöglichen eine flexible Nutzung der Ressourcen und fördern die Zusammenarbeit zwischen den Benutzern. Zum Beispiel kann ein Benutzer, der eine Ressource nicht mehr benötigt, diese einem anderen Benutzer übertragen, der sie gerade benötigt, oder ein Ausbilder kann einem Auszubildenden vorübergehend Zugriff auf eine Ressource gewähren, um bestimmte Fähigkeiten zu erlernen.
+
+## Interest
+Ein wichtiger Bestandteil des Claims-Konzepts sind "Interest", die Reservierungen abbilden, die entweder zeitbasiert oder auf einer Warteschlange basieren können. Diese Interessen bieten den Benutzern die Möglichkeit, einen zukünftigen Zugriff auf eine Ressource zu sichern, entweder basierend auf einer vordefinierten Zeit oder in der Reihenfolge des Eintritts in die Warteschlange.
+
+Mit einem Interest signalisiert der Nutzer dem System sein Interesse an einer bestimmten Ressource. Bei der nächsten Gelegenheit erhält der Nutzer entweder einen Claim auf die Ressource oder hat die Möglichkeit, seinen Interest auf einen Claim zu aktualisieren. Diese Flexibilität ermöglicht es den Benutzern, ihre Bedürfnisse anzupassen und auf Änderungen in der Verfügbarkeit der Ressourcen zu reagieren.
+
+
+## Notify
+Das letzte Element des Claim-Konzepts ist der "Notify". Durch den Notify können Nutzer den Status einer Ressource einsehen und sich über Änderungen benachrichtigen lassen.
+
+Der Notify ermöglicht es Benutzern, den aktuellen Zustand einer Ressource abzurufen und bei Bedarf auf Änderungen zu reagieren. Dies bietet eine wichtige Möglichkeit, den Zustand von Ressourcen zu überwachen und zeitnah auf relevante Ereignisse zu reagieren.
+
+Durch die Möglichkeit, sich für Benachrichtigungen über Zustandsänderungen zu registrieren, können Benutzer effektiv mit den Ressourcen interagieren und sicherstellen, dass sie stets über wichtige Entwicklungen informiert sind.

source/concepts/claims.en.md

@@ -0,0 +1,22 @@
+# Claim Concept
+
+The claim concept serves as an abstraction for allocating a resource in FabAccess. Its primary purpose is to manage the methods by which users gain access to a resource and share that access among themselves.
+
+## Claims
+A "claim" in FabAccess represents the granted access to a resource.
+
+The flexibility of claims enables effective support for various scenarios of resource access. For instance, multiple users can simultaneously claim access to a resource, which is particularly advantageous in collaborative working environments. Additionally, the ability to register in a queue with an interest provides a practical solution for situations where resource availability is limited, and users must wait to access it.
+
+Another significant aspect of claims is their capability to transfer or lend resources between users. These functionalities facilitate a flexible utilization of resources and foster collaboration among users. For example, a user who no longer requires a resource can transfer it to another user in need, or an instructor can temporarily grant access to a resource to a trainee to acquire specific skills.
+
+## Interest
+An integral part of the claim concept is "interest," which represents reservations that can be either time-based or queue-based. These interests allow users to secure future access to a resource, either based on a predefined time or in the order of entry into the queue.
+
+With an interest, the user signals their interest in a particular resource to the system. At the next opportunity, the user either receives a claim to the resource or has the option to upgrade their interest to a claim. This flexibility enables users to adapt to their needs and respond to changes in resource availability.
+
+## Notify
+The final element of the claim concept is the "notify." Through the notify, users can view the status of a resource and receive notifications about changes.
+
+The notify allows users to retrieve the current state of a resource and respond to changes as needed. This provides an essential means of monitoring resource status and reacting promptly to relevant events.
+
+By registering for notifications of state changes, users can effectively interact with resources and ensure they are informed about important developments at all times.

source/concepts/concepts.rst

@@ -0,0 +1,11 @@
+Concepts of FabAccess
+=================
+
+FabAccess utilizes several key concepts to facilitate the process of resource allocation and provide flexibility where needed to accommodate customization.
+
+.. toctree::
+   claims.md
+   traits.md
+   measurements.md
+   projects.md
+   terminals.md

source/concepts/measurements.de.md

@@ -0,0 +1,6 @@
+# Measurements
+Durch "Measurements" in FabAccess werden Daten von Ressourcen gesammelt, um deren Leistung und Nutzung zu erfassen. Das Ziel ist es, dass FabAccess diese Messwerte sammelt und an die Nutzer weitergibt.
+
+Die Funktion Measurements ermöglicht es FabAccess, wichtige Daten über die Nutzung von Ressourcen zu erfassen und den Nutzern zur Verfügung zu stellen. Dies umfasst Informationen wie Betriebsstunden, Auslastung und andere Leistungsindikatoren, die es den Nutzern ermöglichen, die Effizienz und Produktivität ihrer Arbeitsprozesse zu optimieren.
+
+**Das Konzept zu Projekten exitiert zwar, jedoch gibt es noch keine Spezifikation!**

source/concepts/projects.de.md

@@ -0,0 +1,6 @@
+# Projects
+Projekte in FabAccess sollen die Zusammenarbeit zwischen den Nutzern fördern und gleichzeitig die Abrechnung von Maschinenzeiten verbessern. Ein wichtiger Aspekt der Projektstruktur ist die Möglichkeit für Nutzer, Claims innerhalb desselben Projekts miteinander zu teilen, um gleichzeitig auf Ressourcen zugreifen zu können.
+
+Durch die Zuweisung von Nutzern zu Projekten können Teams effizient zusammenarbeiten und ihre Ressourcen optimal nutzen. Das Teilen von Claims innerhalb eines Projekts ermöglicht es den Teammitgliedern, nahtlos auf benötigte Ressourcen zuzugreifen und gemeinsam an Projekten zu arbeiten. Darüber hinaus erleichtert diese Funktionalität die Abrechnung von Maschinenzeiten, da die Nutzung der Ressourcen innerhalb eines Projekts besser nachverfolgt und zugeordnet werden kann.
+
+**Das Konzept zu Projekten exitiert zwar, jedoch gibt es noch keine Spezifikation!**

source/concepts/resourcenraum.md

@@ -0,0 +1,264 @@
+# Beispiel Space
++ Spacename: Resourcenraum
++ InstanceURL: resourcenraum.fab-access.space
++ User-Passwort: secret
++ User-PIN: 1234
+
+Der Beispielspace "Resourcenraum" ist ein Konstrukt, das entworfen wurde, um die verschiedenen Anforderungen und Konzepte verschiedener offener Werkstätten abzubilden. Auf diesem Space basieren auch die Tests für die API, mit denen die Funktionalität überprüft und Entwicklern ein Leitfaden gegeben werden kann.
+
+## Users
+### Admin - admin
+User für Debugging und Testing
+
+### User mit Aufgaben im Space
+#### Sarah Barth - sbarth
+- Adresse: Albrechtstrasse 73, 85003 Ingolstadt
+- E-Mail: sbarth@resourcenraum.fab-access.space
+- Rolle: Admin im Space mit allen Rechten
+- Projekt: Management, Ausbildung, Workshop
+- Card: 0000000000001
+
+#### Claudia Neustadt - cneustadt
+- Adresse: Bayreuther Strasse 25, 67661 Kaiserslautern Hohenecken
+- E-Mail: cneustadt@resourcenraum.fab-access.space
+- Rolle: Manage im Space für Metallbearbeitung
+- Projekt: Management, Ausbildung
+- Card: 0000000000002
+
+#### Thomas Naumann - tneumann
+- Adresse: Inge Beisheim Platz 6, 21339 Lüneburg
+- E-Mail: tneumann@resourcenraum.fab-access.space
+- Rolle: Manage im Space für Holzbearbeitung
+- Projekt: Management, Ausbildung
+- Card: 0000000000003
+
+#### Maik Pfeiffer - mpfeiffer
+- Adresse: Rudower Chaussee 15, 46238 Bottrop Batenbrock-Süd
+- E-Mail: mpfeiffer@resourcenraum.fab-access.space
+- Rolle: Manage im Space für Rapid Prototyping
+- Projekt: Management, Ausbildung
+- Card: 0000000000004
+
+#### Katharina Abendroth - kabendroth
+- Adresse: Storkower Strasse 34, 56332 Wolken
+- E-Mail: kabendroth@resourcenraum.fab-access.space
+- Rolle: Manage für alle Ressourcen zur Reparatur
+- Projekt: Management
+- Card: 0000000000005
+
+#### Ralf Luft - rluft
+- Adresse: An der Alster 3, 26721 Emden
+- E-Mail: rluft@resourcenraum.fab-access.space
+- Rolle: Manage für alle Ressourcen zur Reinigung
+- Projekt: Management
+- Card: 0000000000006
+
+#### Sabine Faerber - sfaerber
+- Adresse: Michaelkirchstr. 84, 34385 Bad Karlshafen
+- E-Mail: sfaerber@resourcenraum.fab-access.space
+- Rolle: Manage für User und Abrechnung
+- Projekt: Management
+
+#### Phillipp Blau - pblau
+- Adresse: Schönwalder Allee 15, 09218 Neukirchen
+- E-Mail: pblau@resourcenraum.fab-access.space
+- Rolle: Workshop für neue Leute für unspezialisierte Ressourcen
+- Projekt: Workshop
+- Card: 0000000000007
+
+### User die den Space nutzen
+#### Michael Ziegler - mziegler
+- Adresse: Leipziger Strasse 76, 33619 Bielefeld Niederdornberg
+- E-Mail: mziegler@resourcenraum.fab-access.space
+- Rolle: Neu im Space und hat noch keinen Account
+- Card: 0000000000008
+
+#### Leonie Fischer - lfischer
+- Adresse: Hauptstrasse 10, 10115 Berlin Mitte
+- E-Mail: lmueller@resourcenraum.fab-access.space
+- Rolle: Nutzender des Space, hat Zugang zu allen Bereichen
+- Card: 0000000000009
+
+#### Julia Schneider - jschneider
+- Adresse: Feldstrasse 5, 80333 München
+- E-Mail: jschneider@resourcenraum.fab-access.space
+- Rolle: Nutzende des Space, hat Zugang zur Metallbearbeitung
+
+#### Felix Wagner - fwagner
+- Adresse: Ludwig-Erhard-Strasse 20, 50679 Köln
+- E-Mail: fwagner@resourcenraum.fab-access.space
+- Rolle: Nutzender des Space, hat Zugang zur Holzbearbeitung
+- Card: 000000000000A
+
+#### Lara Schmidt - lschmidt
+- Adresse: Am Wehrhahn 50, 40211 Düsseldorf
+- E-Mail: lschmidt@resourcenraum.fab-access.space
+- Rolle: Nutzende des Space, hat Zugang zum Rapid Prototyping
+
+#### Lisa Meier - lmeier
+- Adresse: Musterstraße 123, 12345 Musterstadt
+- E-Mail: lmeier@resourcenraum.fab-access.space
+- Rolle: Nutzende des Space, hat Zugang zum Rapid Prototyping
+- Projekt: Horizon
+- Card: 000000000000B
+
+#### Tim Fischer - tfischer
+- Adresse: Beispielweg 456, 54321 Beispielstadt
+- E-Mail: tfischer@resourcenraum.fab-access.space
+- Rolle: Nutzender des Space, hat Zugang zum Rapid Prototyping
+- Projekt: Horizon
+
+#### Niklas Becker - nbecker
+- Adresse: Hauptplatz 8, 10178 Berlin Mitte
+- E-Mail: nbecker@resourcenraum.fab-access.space
+- Rolle: Keine zusätzlichen Berechtigungen
+- Card: 000000000000D
+
+## Resourcen
+### Allgemein
+#### Lötstation - solderstation
+- Ansteuerung: 230V - Zwischenstecker
+- Berechtigungen: Keine
+- Abhängigkeit: Keine
+- Trait: Powerable
+
+#### 3D-Scanner - 3dscanner
+- Ansteuerung: Keine
+- Berechtigung: Keine
+- Abhängigkeit: Keine
+- Trait: Keine
+
+#### Heißklebepistole - hotgluegun
+- Ansteuerung: 12V DC Lock (feste Position)
+- Berechtigung: Keine
+- Abhängigkeit: Keine
+- Trait: Doorable
+
+#### Schraubendrehersatz - screwdriverset
+- Ansteuerung: Keine
+- Berechtigung: Keine
+- Abhängigkeit: Keine
+- Trait: Keine
+
+#### Ringmaulschlüsselsatz - wrenchset
+- Ansteuerung: Keine
+- Berechtigung: Keine
+- Abhängigkeit: Keine
+- Trait: Keine
+
+#### Akkuschrauber - electricscrewdriver
+- Ansteuerung: 12V DC Lock (variable Position)
+- Berechtigung: Elektrowerkzeuge
+- Abhängigkeit: Keine
+- Trait: Locatable, Lockable
+
+### Stichsäge - jigsaw
+- Ansteuerung: 12V DC Lock (variable Position)
+- Berechtigung: Elektrowerkzeuge
+- Abhängigkeit: Keine
+- Trait: Locatable, Lockable
+
+### Winkelschleifer - anglegrinder
+- Ansteuerung: 12V DC Lock (variable Position)
+- Berechtigung: Elektrowerkzeuge
+- Abhängigkeit: Keine
+- Trait: Locatable, Lockable
+
+### Eingangstür - frontdoor
+- Ansteuerung: 12V DC Summer
+- Berechtigung: Keine
+- Abhängigkeit: Keine
+- Trait: Doorable (nur tmpOpen)
+
+### Projektraum - projectroom
+- Ansteuerung: 12V DC Summer
+- Berechtigung: Keine
+- Abhängigkeit: Keine
+- Trait: Doorable
+
+### Projektkiste (10 Stück) - projectbox
+- Ansteuerung: 12V DC Lock (variable Position)
+- Berechtigung: Jeweils pro Kiste
+- Abhängigkeit: Keine
+- Trait: Lockable, Locatable
+
+### E-Scooter - escooter
+- Ansteuerung: intern
+- Berechtigung: Keine
+- Abhängigkeit: Keine
+- Trait: Lockable, Locatable
+- Hint: Scooter
+
+### Holzbearbeitung
+#### Absaugung - centralsuction
+- Ansteuerung: 230V - Schütz
+- Berechtigung: Admin
+- Abhängigkeit: Keine
+- Trait: Powerable
+
+#### Formatkreissäge - circularsaw
+- Ansteuerung: 230V - Schütz
+- Berechtigung: Holzbearbeitung
+- Abhängigkeit: Absaugung
+- Trait: Powerable
+
+#### Bandsäge - bandsaw
+- Ansteuerung: 400V - Schütz
+- Berechtigung: Holzbearbeitung
+- Abhängigkeit: Absaugung
+- Trait: Powerable
+
+#### Oberfräse - woodrouter
+- Ansteuerung: 230V - Zwischenstecker
+- Berechtigung: Felix Wagner
+- Abhängigkeit: Keine
+- Trait: Powerable
+
+### Metallbearbeitung
+#### Schweißgeräte - weldingmachine
+- Ansteuerung: 230V - Zwischenstecker(intern), 12V DC Lock (feste Position)
+- Berechtigung: Schweißen
+- Abhängigkeit: Keine
+- Trait: Powerable, Lockable
+
+#### CNC - cnc
+- Ansteuerung: 400V - Schütz
+- Berechtigung: CNC
+- Abhängigkeit: Keine
+- Trait: Checkable
+
+### Rapid Prototyping
+#### 3D-Drucker FDM - 3dprinterfdm
+- Ansteuerung: 230V - Zwischenstecker
+- Berechtigung: 3D-Druck
+- Abhängigkeit: Keine
+- Trait: Powerable
+
+#### 3D-Drucker Farm (10 Stück) - 3dprinterfarm0 bis 3dprinterfarm9
+- Ansteuerung: 230V - Zwischenstecker
+- Berechtigung: 3D-Druck
+- Abhängigkeit: Keine
+- Trait: Powerable
+
+#### Lasercutter - lasercutter
+- Ansteuerung: 230V - Zwischenstecker
+- Berechtigung: Lasercut
+- Abhängigkeit: Keine
+- Trait: Powerable
+- Bemerkung: Keine Disclose Berechtigung und Alias
+
+## Terminals
+curved25519 Zertifikate
+
+### CNC - cnc
+- Resource: CNC
+
+### 3D-Drucker Farm - farm
+- Resource: 3D-Drucker Farm
+
+### Lasercutter - lasercutter
+- Resource: Lasercutter
+- Bemerkung: Alias QR Code
+
+### Warenausgabe - goodsissue
+- Resource: Schraubendrehersatz, Ringmaulschlüsselsatz

source/concepts/terminals.de.md

@@ -0,0 +1,6 @@
+# Terminals
+Terminals ermöglichen einen eingeschränkten Zugriff auf den Server in FabAccess. Diese Terminals können nur auf ihnen zugewiesene Maschinen zugreifen und haben die Fähigkeit, Maschinen für andere Nutzer auszuleihen.
+
+Aufgrund ihrer beschränkten Zugriffsrechte eignen sich Terminals ideal für die Authentifizierung in FabFire. Durch die Verwendung von Terminals als Authentifizierungsmethode können Nutzer sicherstellen, dass nur autorisierte Benutzer auf die Ressourcen zugreifen und diese nutzen können.
+
+Die Verwendung von Terminals für die Authentifizierung bietet eine zusätzliche Sicherheitsebene und trägt dazu bei, die Integrität des Systems zu gewährleisten. Darüber hinaus ermöglicht es eine effiziente Verwaltung der Ressourcennutzung, indem nur autorisierten Benutzern Zugriff gewährt wird.

source/concepts/traits/checkable.md

@@ -0,0 +1,18 @@
+# Checkable
+Der komplexere Trait "Checkable" ermöglicht die Abbildung von Ressourcen, die nach der Benutzung überprüft werden müssen. Bei einer Überprüfung durch einen berechtigten Nutzer kann die Ressource entweder für alle wieder freigegeben oder zurückgewiesen werden. Falls die Ressource zurückgewiesen wurde, kann der ursprüngliche Nutzer die Ressource weiterhin verwenden oder erneut zur Überprüfung einreichen, nachdem die Fehler behoben wurden.
+
+## OID
+`1.3.6.1.4.1.61783.612.1.3`
+
+## States
+```mermaid
+stateDiagram
+    [*] --> FREE
+    FREE --> INUSE: use
+    INUSE --> CHECK: giveback
+    CHECK --> FREE: accept
+    CHECK --> REJECTED: reject
+    REJECTED --> INUSE: use
+    REJECTED --> CHECK: giveback
+    REJECTED --> FREE: accept
+```

source/concepts/traits/claimable.md

@@ -0,0 +1,7 @@
+# Claimable
+Der Trait "Claimable" stellt einen Sonderfall dar, da er dazu dient, dass sich ein Nutzer über den Claim-Zustand einer Ressource informieren kann.
+
+Nutzer können auf diesem Trait keine Aktionen ausführen, sondern lediglich den Zustand abfragen.
+
+## OID
+`1.3.6.1.4.1.61783.612.1.0`

source/concepts/traits/doorable.md

@@ -0,0 +1,17 @@
+# Doorable
+Der Trait "Doorable" ermöglicht die Abbildung von Türen oder anderen Schließsystemen. Dabei besteht die Möglichkeit, kurzzeitige Öffnungen zu realisieren. Die genaue Zeitdauer, für die die Ressource geöffnet wird, wird dabei vom Server bestimmt.
+
+## OID
+`1.3.6.1.4.1.61783.612.1.2`
+
+## States
+```mermaid
+stateDiagram
+    [*] --> CLOSED
+    CLOSED --> OPEN: unlock
+    OPEN --> CLOSED: lock
+    CLOSED --> tempOPEN: unlocktemp
+    tempOPEN --> OPEN: unlock
+    tempOPEN --> CLOSED: lock
+    tempOPEN --> CLOSED: AUTO
+```

source/concepts/traits/locatable.md

@@ -0,0 +1,15 @@
+# Locatable
+Der Trait "Locatable" ermöglicht die Identifizierung von Ressourcen, wie beispielsweise Schließfächer oder 3D-Drucker in einer Druckerfarm. Dabei kann entweder eine kurzfristige Identifikation abgegeben werden oder die Identifizierung dauerhaft gesetzt werden.
+
+## OID
+`1.3.6.1.4.1.61783.612.1.5`
+
+## States
+```mermaid
+stateDiagram
+    [*] --> IDLE
+    IDLE --> ACTIVE: setActive
+    IDLE --> ACTIVE: identify
+    ACTIVE --> IDLE: setIdle
+    ACTIVE --> IDLE: AUTO
+```

source/concepts/traits/lockers.md

@@ -0,0 +1,18 @@
+# Lockers
+"Lockers" ist einer der komplexeren Traits, mit dem Schlösser von Ressourcen genauer abgebildet werden können. Der Nutzer kann die Ressource nicht in jedem Zustand zurückgeben; erst wenn alles korrekt zurückgegeben wurde, kann die Ressource auch wieder gesperrt werden.
+
+Die Zustandsänderungen zwischen den vom Nutzer verwendbaren Übergängen können von einem Initiator herbeigeführt werden.
+
+## OID
+`1.3.6.1.4.1.61783.612.1.4`
+
+## States
+```mermaid
+stateDiagram
+    [*] --> locked
+    locked --> unlocked: unengage
+    unlocked --> locked: engage
+    unlocked --> open: AUTO
+    open --> unengaged: AUTO
+    unengaged --> locked: engage
+    unengaged --> open: AUTO

source/concepts/traits/powerable.md

@@ -0,0 +1,13 @@
+# Powerable
+"Powerable" ist der grundlegendste Trait, den FabAccess unterstützt. Er dient dazu abzubilden, ob eine Ressource eingeschaltet bzw. mit Strom versorgt ist.
+
+## OID
+`1.3.6.1.4.1.61783.612.1.1`
+
+## States
+```mermaid
+stateDiagram
+    [*] --> OFF
+    OFF --> ON: turnON
+    ON --> OFF: turnOFF
+```

source/concepts/traits/traits.rst

@@ -0,0 +1,17 @@
+Traits
+=================
+Traits bieten die Möglichkeit, den Zustand von Ressourcen zu ändern. Ressourcen können mehrere Traits besitzen und diese kombiniert nutzen.
+
+Mit Traits erhalten Nutzer Zugriff auf die Ressource, nachdem sie einen Claim erhalten haben. Dabei können Traits verwendet werden, um Ressourcen aus bestehenden Traits zusammenzusetzen oder spezifische Traits zu implementieren.
+
+Um eine optimale Anzeige der Traits für Nutzer in Clients zu ermöglichen, kann einer Ressource ein "Hint" hinzugefügt werden. Dieser ermöglicht es einem Client, eine verbesserte Ansicht der Ressource für Nutzer zu generieren.
+
+Traits werden anhand einer OID (Object Identifier) bereitgestellt. In FabAccess gibt es bereits vordefinierte Traits für grundlegende Funktionen, mit denen viele Zustände von Ressourcen abgebildet werden können.
+
+.. toctree::
+   claimable.md
+   powerable.md
+   doorable.md
+   lockers.md
+   checkable.md
+   locatable.md

source/conf.py

@@ -18,9 +18,9 @@ import sphinx_rtd_theme
 
 # -- Project information -----------------------------------------------------
 
-project = 'Fab-Access'
-copyright = '2020, Fab-Infra Team'
-author = 'Fab-Infra Team'
+project = 'FabAccess'
+copyright = '2020, FabInfra Team'
+author = 'FabInfra Team'
 
 
 # -- General configuration ---------------------------------------------------
@@ -30,7 +30,7 @@ author = 'Fab-Infra Team'
 # ones.
 extensions = [
         "sphinx_rtd_theme",
-        "recommonmark",
+        "recommonmark"
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -42,7 +42,7 @@ master_doc = 'index'
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = 'de'
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

source/configuration/bffh_config.md

@@ -0,0 +1,239 @@
+# bffh.dhall
+
+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
+### `listens`
+Contains the Addresses BFFH is listen for Connection for the API
+Default Port for BFFH is `59661`
+
+**Example:**
+```
+listens = 
+[ 
+    { address = "127.0.0.1", port = Some 59661 }
+]
+```
+
+### `mqtt_url`
+Contains the Address for the MQTT Server BFFH connects to.
+
+The Address has the format `<protocol>://[user]:[password]@<server>:[port]`
+
+* `protocol` is required and can be one of: `mqtt`,`tcp`,`mqtts`,`ssl`
+* `user` and `password` are optional
+* `server` is required and can be an ip address or a hostname
+* `port` is optional
+
+**Example:**
+```
+mqtt_url = "tcp://localhost:1883" 
+```
+
+### `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
+**Example:**
+```
+db_path = "/tmp/bffh"
+```
+
+## 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`.
+When requireing permissions, such as in machines you always need to give an exact permission, so for example `test.write`.
+When granting permissions, such as in roles you can either give an exact permission or you can use the two wildcards `*` and `+`.
+These wildcards behave similar to regex or bash wildcards:
+- `*` grants all permissions in that subtree.
+  So, `perms.read.*` will match for any of:
+  - `perms.read`
+  - `perms.read.machineA`
+  - `perms.read.machineB`
+  - `perms.read.machineC.manage`
+- `+` grants all permissions below that one.
+  So, `perms.read.+` will match for any of:
+  - `perms.read.machineA`
+  - `perms.read.machineB`
+  - `perms.read.machineC.manage`
+  - **but not** `perms.read`
+
+Wildcards are probably most useful if you group you machines around them, e.g. your 3D-printers and your one bandsaw require:
+
+1. Write permissions
+    - `machines.printers.write.prusa.sl1`
+    - `machines.printers.write.prusa.i3`
+    - `machines.printers.write.anycubic`
+    - `machines.bandsaws.write.bandsaw1`
+1. Manage permissions
+    - `machines.printers.manage.prusa.sl1`
+    - `machines.printers.manage.prusa.i3`
+    - `machines.printers.manage.anycubic`
+    - `machines.bandsaws.manage.bandsaw1`
+1. Admin permissions
+    - `machines.printers`
+        * For all printers
+    - `machines.bandsaws`
+        * For all bandsaws
+
+And you then give roles permissions like so:
+
+* Use any 3D printer:
+    * `machines.printers.write.+`
+* Only allow use of the "cheap" printers
+    * `machines.printers.write.anycubic.*`
+    * `machines.printers.write.prusa.i3`
+* Allow managing of printers:
+    * `machines.printers.+`
+* Allow administrating printers:
+    * `machines.printers.*`
+
+This way if you buy a different anycubic and split the permissions to e.g.
+
+- `machines.printers.write.anycubic.i3`
+- `machines.printers.write.anycubic.megax`
+
+It still works out.
+
+
+## Machine Config
+
+### `machines`
+Contains list of machines
+
+Machines have different perission levels to interact with:
+* disclose: User can see the machine in machine list
+* read: User can read information about the machine and there state
+* 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 = 
+{ 
+    machine123 = 
+    { 
+        name = "Testmachine",
+        description = Some "A test machine",
+        wiki = "https://someurl"
+
+        disclose = "lab.test.read",
+        read = "lab.test.read",
+        write = "lab.test.write",
+        manage = "lab.test.admin"
+    }
+}
+```
+"machine123" is in this case the "Machine-ID"
+
+## Roles Config
+
+The roles are configured in the bffh.dhall. If the file "roles.toml" is existing in the directory, it can be deleted and can't be used to manage roles.
+
+### `roles`
+Contains list of roles
+
+Roles have a list of permission and can be inherited.
+Permission can be wildcard in permission list.
+
+**Example:**
+```
+roles =
+{
+    testrole = 
+    {
+        permissions = [ "lab.test.*" ]
+    },
+    somerole =
+    { 
+        parents = ["testparent"],
+        permissions = [ "lab.some.admin" ]
+    }, 
+    testparent =
+    {
+        permissions =
+        [
+            "lab.some.write",
+            "lab.some.read",
+            "lab.some.disclose"
+        ]
+    }
+}
+```
+
+## Actors Config
+
+### `actors`
+Contains list of actors
+Actors are defined by a module and one or more paramters
+
+Currenty supported actors:
+#### `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.
+
+`cmd` = Path of executable
+
+`args` = Arguments for executable
+
+**Example:**
+```
+actors = 
+{
+    Bash =
+    { 
+        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 = 
+[
+    { machine = "Testmachine", actor = "Shelly_1234" },
+    { machine = "Another", actor = "Bash" },
+    { machine = "Yetmore", actor = "Bash2" }
+]
+```

source/configuration/configuration.rst

@@ -0,0 +1,13 @@
+Configure FabAccess
+===================
+
+To run FabAccess you have to configure the Server(BFFH).
+And add your Machines, Actors and Initiators.
+
+In the current state of FabAccess we will no support database migration so all persistent data are in configuration files.
+
+.. toctree::
+   bffh_config.md
+   user_config.md
+   log_config.md
+   default_permission.md

source/configuration/default_permission.md

@@ -0,0 +1,10 @@
+# Default Permissions
+
+BFFH has some standard permissions to assign to management and admin rights.
+
+## UserSystem
+* `bffh.users.manage` - Get ManageInterface in UserSystem (Access UserList)
+
+## User
+* `bffh.users.info` - Get InfoInterface for every User (Access UserInfos of other accounts)
+* `bffh.users.admin` - Get AdminInterface for every User (Add/Remove Users, Reset Passwords)

source/configuration/log_config.md

@@ -0,0 +1,11 @@
+# Configure BFFH Log
+BFFH's log level can be set via the environment variables or via bffh.dhall.
+
+`BFFH_LOG=debug`
+
+Supported levels are:
+* `trace`
+* `debug`
+* `warn`
+* `info`
+* `error`

source/configuration/user_config.md

@@ -0,0 +1,50 @@
+# user.toml
+This configuration is located under `/etc/bffh`. 
+
+Here the users, there Password, roles and cardkeys are stored. 
+
+Roles are defined in the bffh.dhall configuration. The [Docker-compose Repository](https://gitlab.com/fabinfra/fabaccess/dockercompose) has a good [example](https://gitlab.com/fabinfra/fabaccess/dockercompose/-/blob/main/config/bffh/users.toml)
+
+```exapmle of users.toml
+[Admin1]
+roles = ["Admin"]
+passwd = "secret"
+noot = "noot!"
+cardkey = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+
+[Admin2]
+roles = ["Admin"]
+passwd = "secret"
+noot = "noot!"
+cardkey = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+
+[ManagerA1]
+roles = ["ManageA", "UseA", "ReadA", "DiscloseA"]
+passwd = "secret"
+noot = "noot!"
+cardkey = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+
+[ManagerA2]
+roles = ["ManageA", "UseA", "ReadA", "DiscloseA"]
+passwd = "secret"
+noot = "noot!"
+cardkey = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+
+[ManagerB1]
+roles = ["ManageB", "UseB", "ReadB", "DiscloseB"]
+passwd = "secret"
+noot = "noot!"
+cardkey = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+
+[ManagerB2]
+roles = ["ManageB", "UseB", "ReadB", "DiscloseB"]
+passwd = "secret"
+noot = "noot!"
+cardkey = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+
+[ManagerC1]
+roles = ["ManageC", "UseC", "ReadC", "DiscloseC"]
+passwd = "secret"
+noot = "noot!"
+cardkey = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+```

source/index.rst

@@ -3,18 +3,21 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to fab-access's documentation!
+Welcome to FabAccess
 ======================================
 
+FabAccess is a powerful system that enables the management and allocation of resources. With its flexible API, resource ownership and states can be effectively mapped, with each resource being assignable to a specific user. Furthermore, FabAccess provides the capability to track status changes of resources, facilitating precise monitoring and management.
+
+A central aspect of FabAccess is the management of permissions, which allows for controlling access to specific resources. These permissions offer granular control over which user can access which resources, serving as a crucial tool for the security and efficiency of the system.
+
+In this documentation, we will provide a comprehensive overview of FabAccess' features and usage possibilities, as well as detailed instructions for integration and utilization. We invite you to become acquainted with our system and discover its diverse capabilities.
+
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   concepts/concepts.rst
+   installation/installation.rst
+   configuration/configuration.rst
+   usage/usage.rst
+   concepts/concepts.rst

source/installation/client_build.md

@@ -0,0 +1,74 @@
+# Build Client from Source
+
+## On Windows
+1. Install Visual Studio 2019
+    [download Visual Studio](https://visualstudio.microsoft.com/de/)
+    * with Xamarin
+    * with UWP
+    * with .NET Desktop
+2. Install GTKSharp for Windows
+    [download GTKSharp](https://www.mono-project.com/download/stable/#download-win)
+3. Install capnproto
+
+    3.1 If you have Chocolatey installed
+    ```shell
+    $ choco install capnproto
+    ```
+    3.2 else you can download it from [here](https://capnproto.org/install.html) and add it to your PATH
+
+4. Clone Borepin
+    [download Borepin](https://gitlab.com/fabinfra/fabaccess/client)
+6. Load Borepin
+7. Build Borepin
+
+If Step 5. Build Borepin is failing because of GTKSharp, it could help to restart your PC.
+
+## Build GTK Project
+1. Install mono
+    [download mono](https://www.mono-project.com/download/stable/#download-lin)
+2. Install mono, gtk-sharp, msbuild, nuget, capnproto
+    1.1 Debian based
+    ```shell
+    $ apt install mono-complete, gtk-sharp2, libcanberra-gtk-module, nuget, capnproto, git
+    ```
+    1.2 ArchLinux based
+    ```shell
+    $ pacman -S mono, mono-msbuild, gtk-sharp-2, nuget, capnproto
+    ```
+3. Update NuGet
+    ```shell
+    $ nuget update -self
+    ```
+3. Clone Borepin
+    ```shell
+    $ git clone https://gitlab.com/fabinfra/fabaccess/client.git --recurse-submodules
+    ```
+    
+4. Build Borepin
+    ```shell
+    $ cd client
+    $ nuget restore
+    $ msbuild -t:Borepin_GTK
+    ```
+4. Run Borepin
+    ```shell
+    $ mono ./Borepin/Borepin.GTK/bin/Debug/Borepin.GTK.exe
+    ```
+You can also use Rider or monodevelop as an IDE for development on Borepin
+
+## macOS / iOS
+
+1. Install Visual Studio for Mac 
+
+2. Install capnproto
+    If you install capnp with Homebrew you may have to symlink the capnp binary into '/usr/local/bin', or bring it into your PATH another way.
+
+3. Clone Borepin
+    ```shell
+    $ git clone https://gitlab.com/fabinfra/fabaccess/client.git --recurse-submodules
+    ```
+
+4. Open in Visual Studio
+
+5. Build
+

source/installation/client_store.md

@@ -0,0 +1,13 @@
+# Get Client from Store
+
+## Hardware Requirements
+Minimal Android Version: 5.0 (API Level 21)
+
+Minimal iOS Version: 8.0
+
+## Store Links
++ **Android**: [https://play.google.com/store/apps/details?id=org.fab_infra.fabaccess](https://play.google.com/store/apps/details?id=org.fab_infra.fabaccess)
++ **iOS**: [https://apps.apple.com/us/app/fabaccess/id1531873374](https://apps.apple.com/us/app/fabaccess/id1531873374)
+
+## Beta Links - use on youre own risk
++ **iOS**: [https://testflight.apple.com/join/KfeUaHT4](https://testflight.apple.com/join/KfeUaHT4)

source/installation/install_steps_ubuntu.md

@@ -0,0 +1,98 @@
+# Install on Ubuntu for "Dummies"
+
+This description is how to compile and set up Diflouroborane on Ubuntu 20.04.3 LTS clean install. Other releases or distros might work as well.
+The process is quite lengthy but at the end you will have a FabAccess running to you needs.
+... as I said: for complete dummies, if someone finds a better solution, please post suggestions on: 
+https://fabaccess.zulipchat.com/#narrow/stream/255963-General/topic/Demo
+
+1. Get your system up-to-date 
+`sudo apt-get update && sudo apt-get upgrade`
+
+2. Get rustup 
+`sudo apt install curl`
+`curl --proto 'https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+**restart the console**
+
+3. Get capnproto, gsasl and git
+`sudo apt-get install gsasl`
+`sudo apt-get install capnproto`
+`sudo apt install git`
+
+4. Create a target directory for BFFH
+there might be better places compared to where I created it, but it works...
+`mkdir BFFH`
+`cd BFFH`
+
+5. Clone the Diflouroborane repository
+`git clone https://gitlab.com/fabinfra/fabaccess/bffh --recursive --branch main`
+
+6. For compiling some dependencies were missing on Ubuntu
+`git submodule update --init`
+`sudo apt install libgsasl7-dev`
+`sudo apt install cmake`
+`sudo apt install libclang-dev`
+`sudo apt install libssl-dev`
+
+7. Open the subdirectory and start compiling
+`cd bffh`
+`cargo build --release`
+**if the compiler prompts somthing like "error: linker 'cc' not found":**
+`sudo apt install build-essential`
+`cargo build --release`
+ 
+
+8. Copy the configuration files (best done with the GUI filemanager of Ubuntu)
+copy files from "bffh/examples"
+paste them into "bffh/target/release/examples"
+
+9. Install mosquitto MQTT broker
+Diflouroborane uses mosquitto MQTT broker to communicate with the Shellies. Starting from Ubuntu version 18.04, Mosquitto is already inside the official repositories.
+`sudo apt update -y && sudo apt install mosquitto mosquitto-clients -y`
+
+
+10. Configuring mosquitto broker
+for some reason, starting with version 2.x mosquitto does not allow external communication via the broker per default. This needs to be changed via a config file:
+11. Stop mosquitto
+`sudo systemctl stop mosquitto`
+12. Change into the "etc/mosquitto/" directory (lots of `cd ..` then `cd etc/mosquitto`)
+13. Edit the configuration fil:
+`sudo nano  mosquitto.conf`
+add:
+`listener 1883` 
+`allow_anonymous true`
+Save (Strg-O) and close (Strg-X)
+14. Enable mosquitto to start at each start of the system
+`sudo systemctl enable --now mosquitto`
+15. Restart the system.
+
+The BFFH-server can be found at the /target/release folder. Prior to starting the system you need to copy the files from `bffh/examples` to `bffh/target/release/examples` This ist best done by using the GUI filemanager.
+
+To get at least minimum functionality the bffh.dhall should be modified. The lines:
+
+```
+-- , init_connections = [] : List { machine : Text, initiator : Text }
+, init_connections = [{ machine = "Testmachine", initiator = "Initiator" }]
+, initiators = --{=}
+{ Initiator = { module = "Dummy", params = { uid = "Testuser" } } }
+```
+
+should be modified to:
+
+```
+, init_connections = [] : List { machine : Text, initiator : Text }
+--, init_connections = [{ machine = "Testmachine", initiator = "Initiator" }]
+, initiators = {=}
+--{ Initiator = { module = "Dummy", params = { uid = "Testuser" } } }
+```
+
+To start the server change into the directory by using `cd target/release` and using:
+
+`./bffhd -c examples/bffh.dhall --load examples/users.toml`
+an then:
+
+`./bffhd -c examples/bffh.dhall`
+
+**BUT** prior to starting bffh, you should first configure the bffh.dhall file (see the "Use FabAcess" section).
+
+
+

source/installation/installation.rst

@@ -0,0 +1,40 @@
+Install FabAccess
+=================
+
+FabAccess has an Server an Client structure.
+
+So the Server and the Client must be installed seperatly.
+
+Install Server
+--------------
+The Server can be installed over two recommended ways.
+
+The easiest way is to use Docker with Docker-Compose.
+
+To add youre own Plugins and Software you should use the Build way.
+
+.. toctree::
+   server_build.md
+   server_docker.md
+
+Install Client
+--------------
+The Client communicates with the server over an API.
+So you can use any Client that support the current API Version of the Server.
+
+We provide an Native Client for the following Platforms:
+   * Android
+   * iOS
+   * UWP
+
+For MacOS and Linux(GTK) we will provide a Client later in our Development.
+
+.. toctree::
+   client_store.md
+   client_build.md
+
+Installation Example for FabAccess Enviroment
+---------------------------------------------
+
+.. toctree::
+   install_steps_ubuntu.md

source/installation/server_build.md

@@ -0,0 +1,36 @@
+# Build Server from Source
+
+E.g. in a proxmox- or lxc-container.
+
+## Install Dependencies
+### Ubuntu / Debian
+1. `sudo apt update && sudo apt upgrade`
+1. `sudo apt install curl && curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+1. `sudo apt install libgsasl7-dev libssl-dev build-essential`
+1. `sudo apt install git cmake clang capnproto`
+
+### Arch Linux
+1. `sudo pacman -Syu`
+1. `sudo pacman -S make cmake clang gsasl`
+1. `sudo pacman -S git rust capnproto`
+
+### CentOS
+1. `sudo yum update`
+1. `sudo yum install curl && curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+1. `sudo yum install epel-release && sudo yum install capnproto`
+1. `sudo yum install https://packages.endpointdev.com/rhel/7/os/x86_64/endpoint-repo.x86_64.rpm && sudo yum install git`
+1. `sudo yum install centos-release-scl && yum install llvm-toolset-7 && scl enable llvm-toolset-7 bash` (Change bash to youre shell)
+1. `sudo yum install gcc-c++ libgsasl-devel openssl-devel cmake`
+
+### FreeBSD
+TODO
+<!--- 1. `sudo pkg update -f`
+1. `sudo pkg install curl && curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+1. `sudo pkg install git` -->
+
+## Build BFFH
+Start new terminal - Rustup will not update path while install
+1. `git clone https://gitlab.com/fabinfra/fabaccess/bffh.git --recursive`
+1. `cd bffh`
+1. (Optional) `git checkout development && git submodule update --remote` (Change `development` to wanted branch)
+1. `cargo build --release`

source/installation/server_docker.md

@@ -0,0 +1,22 @@
+# Run Server with Docker
+
+Docker Image can not run on armv6 (Raspberry Pi 1 or Raspberry Pi Zero)
+
+1. Install Docker
+
+    On Raspberry Pi: 
+    [https://phoenixnap.com/kb/docker-on-raspberry-pi](https://phoenixnap.com/kb/docker-on-raspberry-pi)
+2. Install Docker-Compose
+
+    On Raspberry Pi: 
+    [https://dev.to/elalemanyo/how-to-install-docker-and-docker-compose-on-raspberry-pi-1mo](https://dev.to/elalemanyo/how-to-install-docker-and-docker-compose-on-raspberry-pi-1mo)
+4. Get Docker-Compose Files `git clone https://gitlab.com/fabinfra/fabaccess/dockercompose.git fabaccess-server`
+    
+    The Dockerfile is in the root directory of the main repo
+    docker-compose.yml is available in a seperate [git repo](https://gitlab.com/fabinfra/fabaccess/dockercompose)
+4. Edit config files in `config` folder to taste
+5. Start Server with `docker-compose up -d`
+
+To make it eaysier to apply youre changes in your config and keep the dockercompose uptodate, you should "fork" this respository.
+
+Get Server Logs: `docker-compose logs`

source/usage/audit_log.md

@@ -0,0 +1,5 @@
+# Audit Log
+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}}}}`

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}`

source/usage/nfc.md

@@ -0,0 +1,57 @@
+# NFC Cards (FabFire)
+## Functional Principle
+### Basic
+Card authentication using NXP/MiFare DESFire cards.
+These cards have the ability to restrict access for data on the cards using symmetric encryption and using a keyed Diffie-Hellman to prevent eavesdropping by any relaying party.
+A card has several "applications", containing up to 32 files. A file can be read or written. Both kinds of access can be restricted to parties knowing a PSK, on a file-to-file basis.
+
+### Files
+The current system uses File 0001 through File 0003:
+
+**File 0001** allows public (i.e. unauthenticated) read access and contains the Strings
+`FABACCESS`, `DESFIRE`, and `1.0` as packed list of UTF-8 encoded zero-terminated strings.
+
+Examples:
+- `FABACCESS\0DESFIRE\01.0\0`
+
+This file serves an identifier, allowing a server to verify if it is able to use this card.
+
+**File 0002** allows public read access and contains:
+An URL-encoded name of the issuing lab as URN in the format 
+`urn:fabaccess:lab:<labname>`
+
+Examples:
+- `urn:fabaccess:lab:innovisionlab`
+- `urn:fabaccess:lab:Bibliothek%20Neustadt%20Makerspace`
+- `urn:fabaccess:lab:Offene%20Werkstatt%20M%C3%A4rz`
+
+A valid IRI pointing towards the bffh instance running for this lab. This bffh SHOULD be reachable from the internet. Using private use IP addresses or IRIs that resolve to such may be necessary for labs behind restrictive firewalls or due to local policy.
+The IRI MUST use the "fabaccess" scheme, and SHOULD NOT contain an userinfo, path, query, or fragment part.
+Examples: 
+- `fabaccess://innovisionlab.de/`
+- `fabaccess://192.168.178.65`
+- `fabaccess://fabaccess-server.localnet`
+
+A zero-terminated list of UTF-8 encoded IRIs giving contact options to notify the issuer
+or owner in case the card has been lost. Issuers SHOULD set one value on card creation and MAY allow card owners to change or add values of their choosing.
+Examples:
+- `mailto:lostcard@innovisionlab.de`
+- `https://innovisionlab.de/lostcard`
+- `https://werkstatt-märz.decardlost.php?action=submitcardlost`
+
+**File 0003** allows public access or access using a key, at the issuers option.
+It contains a token that can be used by the home server of the card owner to identify the card owner. The format of the token MUST NOT be relied on by any party except the home server.
+
+## FabFire Specification
+Application Identifier (AID): `0x464142`
+
+## NFC Implementation
+C# - https://gitlab.com/fabinfra/fabaccess/nfc
+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 adapter translates mqtt messages from the reader hardware to api
+https://gitlab.com/fabinfra/fabaccess/fabfire_adapter

source/usage/setup_steps.md

@@ -0,0 +1,204 @@
+# FabAccess Setup - 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:
+- 1 or more 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 (TO-DO)
+
+
+**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 = "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>
+`Identifier-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 "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 )
+
+**-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/users.toml`
+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.
+
+**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<br>
+`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/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"`).
+
+**Identify if a machine is just switched on or realy running (TO-DO)

source/usage/usage.rst

@@ -0,0 +1,12 @@
+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
+   setup_steps.md
+   audit_log.md
+   nfc.md