From 4ab1aa8d016ca0706daa52622065562b271bc263 Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Sat, 11 Dec 2021 17:15:21 +0100 Subject: [PATCH 01/60] Added: Installation Overview Page --- source/conf.py | 10 ++++---- source/index.rst | 13 +++-------- source/installation/client_build.md | 1 + source/installation/client_store.md | 1 + source/installation/installation.rst | 34 ++++++++++++++++++++++++++++ source/installation/server_build.md | 1 + source/installation/server_docker.md | 1 + 7 files changed, 46 insertions(+), 15 deletions(-) create mode 100644 source/installation/client_build.md create mode 100644 source/installation/client_store.md create mode 100644 source/installation/installation.rst create mode 100644 source/installation/server_build.md create mode 100644 source/installation/server_docker.md diff --git a/source/conf.py b/source/conf.py index 7354987..e514ad6 100644 --- a/source/conf.py +++ b/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. diff --git a/source/index.rst b/source/index.rst index c3ecf73..7aac9e8 100644 --- a/source/index.rst +++ b/source/index.rst @@ -3,18 +3,11 @@ 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 documentation! ====================================== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + installation/installation.rst diff --git a/source/installation/client_build.md b/source/installation/client_build.md new file mode 100644 index 0000000..d2f76ad --- /dev/null +++ b/source/installation/client_build.md @@ -0,0 +1 @@ +# Build Client from Source \ No newline at end of file diff --git a/source/installation/client_store.md b/source/installation/client_store.md new file mode 100644 index 0000000..4fb9d3b --- /dev/null +++ b/source/installation/client_store.md @@ -0,0 +1 @@ +# Get Client from Store diff --git a/source/installation/installation.rst b/source/installation/installation.rst new file mode 100644 index 0000000..6801060 --- /dev/null +++ b/source/installation/installation.rst @@ -0,0 +1,34 @@ +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 diff --git a/source/installation/server_build.md b/source/installation/server_build.md new file mode 100644 index 0000000..6b35e13 --- /dev/null +++ b/source/installation/server_build.md @@ -0,0 +1 @@ +# Build Server from Source \ No newline at end of file diff --git a/source/installation/server_docker.md b/source/installation/server_docker.md new file mode 100644 index 0000000..a113107 --- /dev/null +++ b/source/installation/server_docker.md @@ -0,0 +1 @@ +# Run Server with Docker \ No newline at end of file From 46d10ea8029c6a42e6e1f0ba68a4a22668ef8027 Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Sat, 11 Dec 2021 18:35:43 +0100 Subject: [PATCH 02/60] Added: Existing Install Documentation --- source/installation/client_build.md | 75 ++++++++++- source/installation/client_store.md | 12 ++ source/installation/install_steps_ubuntu.md | 131 ++++++++++++++++++++ source/installation/installation.rst | 6 + source/installation/server_build.md | 17 ++- source/installation/server_docker.md | 23 +++- 6 files changed, 261 insertions(+), 3 deletions(-) create mode 100644 source/installation/install_steps_ubuntu.md diff --git a/source/installation/client_build.md b/source/installation/client_build.md index d2f76ad..5f98d58 100644 --- a/source/installation/client_build.md +++ b/source/installation/client_build.md @@ -1 +1,74 @@ -# Build Client from Source \ No newline at end of file +# 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 + diff --git a/source/installation/client_store.md b/source/installation/client_store.md index 4fb9d3b..4818ef4 100644 --- a/source/installation/client_store.md +++ b/source/installation/client_store.md @@ -1 +1,13 @@ # Get Client from Store + +## Hardware Requirements +Android SDK Version: 21 + +iOS Version: 13 + +Windows 10: 1709 - Build:16299 + +## 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://play.google.com/store/apps/details?id=org.fab_infra.fabaccess](https://testflight.apple.com/join/KfeUaHT4) ++ **Windows**: [https://play.google.com/store/apps/details?id=org.fab_infra.fabaccess](https://www.microsoft.com/de-de/p/fabaccess/9p69mwzjf2mv) \ No newline at end of file diff --git a/source/installation/install_steps_ubuntu.md b/source/installation/install_steps_ubuntu.md new file mode 100644 index 0000000..ff5b0e8 --- /dev/null +++ b/source/installation/install_steps_ubuntu.md @@ -0,0 +1,131 @@ +# 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` + +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. +`sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppa` +`sudo apt-get update` +`sudo apt-get install mosquitto` +`sudo apt-get install mosquitto-clients` +`sudo apt clean` +*find out which linux release is installed (for Ubuntu -> google)* +`uname -a` +`sudo wget http://repo.mosquitto.org/debian/mosquitto-bullseye.list` +*change "bullseye" according to your distro: bullseye, buster, stretch, jessie, ...* + +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 service mosquitto stop` +12. Change into the "etc/mosquitto/" directory (lots of `cd ..` then `cd etc`, `cd mosquitto`) +13. Create a configuration file: +`sudo touch file test.conf` +14. Edit the configuration fil: +`sudo nano -w test.conf` +add: +`listener 1883` +`allow_anonymous true` +Save (Strg-O) and close (Strg-X) +15. Start mosquitto +`mosquitto -v -c /etc/mosquitto/test.conf` + +16. Find the IP adress of your computer +**- new console** +`ip a` + +17. Configure your Shelly +as long as your Shelly has not been given the credentials for a WLAN, it will create an access point (AP) for configuration. 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. + +18. MQTT Client setup +goto "Internet & Security" -> "Advanced - Developer Settings" +enable "MQTT" +enter the IP-Adress from Step 16 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!** + +19. WLAN Client setup +goto "Internet & Security" -> "WIFI MODE - CLIENT" +Set WLAN Credentials + +20. Configure Diflouroborane +Open the file "bffh.dhall" in the GUI Editor (just by double-clicking it) +Change `Shelly_123` to your Shelly name, e.g. `shelly1-123456789ABC` (**case sensitive!, dash sensitive!**) in "Link up machines to actors" and in "actors". +Change the third IP-adress under "listens" to the IP-adress of your computer. +**- save** + +21. start Diflouroburane +change to the directory in the console where you checked for the ip-address +`cd BFFH/bffh/target/release` +load settings to Diflouroborane: +`./diflouroborane -c examples/bffh.dhall --load examples` +start Diflouroborane: +`./diflouroborane -c examples/bffh.dhall` + +**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` +and restart start Diflouroborane: +`./diflouroborane -c examples/bffh.dhall` + +Download the borepin APP as described previously +- start the App +- press: "Connect to new Server" +- press: Enter the IP of your computer in the "Host"-Field +- Enter your Username and Password. + +To connect to the demo instance +- start the App +- press: "Connect to new Server" +- press: "Demo Host Address" +- User: "Testuser" +- Passw: "secret" \ No newline at end of file diff --git a/source/installation/installation.rst b/source/installation/installation.rst index 6801060..0a8cc40 100644 --- a/source/installation/installation.rst +++ b/source/installation/installation.rst @@ -32,3 +32,9 @@ 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 diff --git a/source/installation/server_build.md b/source/installation/server_build.md index 6b35e13..de076b1 100644 --- a/source/installation/server_build.md +++ b/source/installation/server_build.md @@ -1 +1,16 @@ -# Build Server from Source \ No newline at end of file +# Build Server from Source + +1. Install [rustup.rs](rustup.rs). Distribution packages for rustc are generally way too old +1. `$ rustup install stable` +1. Get yourself a directory to clone BFFH into + * If you put this dir on a SSD you can speed up build times by 5-10 times. +1. `git clone --recursive --branch stable` + * ... stable ... TODO... + * You can also check out the `development` branch but keep in mind that until Beta it has no stability guarantee. It may work. It may make you a sandwich. But it may also set your hat on fire and fill your shoes with orange juice. *You have been warned*. +1. `cargo install --path .` + * if you add `--debug` you get a debug build. It gives you much more logging output but it's slower to run and is almost spammy +1. Make yourself a coffee. Or tea. Or open $beverage of your choice. You earned it! (And you'll be looking at "**Compiling** " for a while.) + * If you get `error: failed to run custom build command for 'gsasl-sys v0.2.3'` or something like that with the stderr output reading "[…]Unable to find libclang[…]": + * `export LIBCLANG_PATH=/usr/lib` + Or wherever `libclang.so` is installed on your computer. It's usually `/usr/lib/libclang.so` or `/usr/lib/llvm/12/lib/libclang.so` or similar. If you can't find it, consult your package manager + * If you get any other error open an issue \ No newline at end of file diff --git a/source/installation/server_docker.md b/source/installation/server_docker.md index a113107..0e0820a 100644 --- a/source/installation/server_docker.md +++ b/source/installation/server_docker.md @@ -1 +1,22 @@ -# Run Server with Docker \ No newline at end of file +# 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` + + 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` \ No newline at end of file From 42248a34b0463468ac8c83e26ce2106ee975f712 Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Sat, 11 Dec 2021 20:01:52 +0100 Subject: [PATCH 03/60] Added: BFFH Configuration --- source/configuration/bffh_config.md | 204 ++++++++++++++++++++ source/configuration/configuration.rst | 11 ++ source/configuration/user_config.md | 1 + source/index.rst | 7 + source/installation/install_steps_ubuntu.md | 2 +- 5 files changed, 224 insertions(+), 1 deletion(-) create mode 100644 source/configuration/bffh_config.md create mode 100644 source/configuration/configuration.rst create mode 100644 source/configuration/user_config.md diff --git a/source/configuration/bffh_config.md b/source/configuration/bffh_config.md new file mode 100644 index 0000000..9445817 --- /dev/null +++ b/source/configuration/bffh_config.md @@ -0,0 +1,204 @@ +# 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 + +## General BFFH Config +General BFFH Config is in `bffh.dhall` file. + +#### `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 +**Example:** +``` +mqtt_url = "tcp://localhost:1883" +``` + +#### `db_path` +Contains the Path for the internal Database BFFH uses. +BFFH will create two files: `` and `-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 +--- +Machine Config is in ```machine.dhall``` file. + +#### `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) + +**Example:** +``` +machines = +{ + Testmachine = + { + name = "Testmachine", + description = Some "A test machine", + disclose = "lab.test.read", + read = "lab.test.read", + write = "lab.test.write", + manage = "lab.test.admin" + } +} +``` + +Roles Config +--- +Roles Config is in `roles.dhall` file. + +#### `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 Config is in `actors.dhall` file. + +#### `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 + +**`Process`** +Parameters: +`cmd` = Path of executable +`args` = Arguments for executable + +**Example:** +``` +actors = +{ + Shelly_1234 = { module = "Shelly", params = + { + id = "12345" + }}, + 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 +**Example:** +``` +actor_connections = +[ + { machine = "Testmachine", actor = "Shelly_1234" }, + { machine = "Another", actor = "Bash" }, + { machine = "Yetmore", actor = "Bash2" } +] +``` \ No newline at end of file diff --git a/source/configuration/configuration.rst b/source/configuration/configuration.rst new file mode 100644 index 0000000..9fb737c --- /dev/null +++ b/source/configuration/configuration.rst @@ -0,0 +1,11 @@ +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 \ No newline at end of file diff --git a/source/configuration/user_config.md b/source/configuration/user_config.md new file mode 100644 index 0000000..782130f --- /dev/null +++ b/source/configuration/user_config.md @@ -0,0 +1 @@ +# user.toml diff --git a/source/index.rst b/source/index.rst index 7aac9e8..849d6f0 100644 --- a/source/index.rst +++ b/source/index.rst @@ -6,8 +6,15 @@ Welcome to FabAccess documentation! ====================================== +FabAccess is still in a state of development and has no stable Release. + +So there is no stability and backward compatibility between the versions. +Feel free to help us testing our software stack but not expect a full functional software. +We will inform you about breaking changes over our Zulip. Please subscript to it to stay up to date, because the server and client can get incompatible. + .. toctree:: :maxdepth: 1 :caption: Contents: installation/installation.rst + configuration/configuration.rst diff --git a/source/installation/install_steps_ubuntu.md b/source/installation/install_steps_ubuntu.md index ff5b0e8..669accb 100644 --- a/source/installation/install_steps_ubuntu.md +++ b/source/installation/install_steps_ubuntu.md @@ -128,4 +128,4 @@ To connect to the demo instance - press: "Connect to new Server" - press: "Demo Host Address" - User: "Testuser" -- Passw: "secret" \ No newline at end of file +- Passw: "secret" \ No newline at end of file From d21229e30fb7d33ab9640e35eac3fa786011b50d Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Sun, 12 Dec 2021 00:43:57 +0100 Subject: [PATCH 04/60] 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: `` and `-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 + + From cce3655453d67f345cf251609033910e3681d012 Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 08:42:41 +0000 Subject: [PATCH 05/60] Update install_steps_ubuntu.md --- source/installation/install_steps_ubuntu.md | 31 +++++++++------------ 1 file changed, 13 insertions(+), 18 deletions(-) diff --git a/source/installation/install_steps_ubuntu.md b/source/installation/install_steps_ubuntu.md index 669accb..cbbe080 100644 --- a/source/installation/install_steps_ubuntu.md +++ b/source/installation/install_steps_ubuntu.md @@ -39,38 +39,33 @@ there might be better places compared to where I created it, but it works... **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. -`sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppa` -`sudo apt-get update` -`sudo apt-get install mosquitto` -`sudo apt-get install mosquitto-clients` -`sudo apt clean` -*find out which linux release is installed (for Ubuntu -> google)* -`uname -a` -`sudo wget http://repo.mosquitto.org/debian/mosquitto-bullseye.list` -*change "bullseye" according to your distro: bullseye, buster, stretch, jessie, ...* +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 service mosquitto stop` -12. Change into the "etc/mosquitto/" directory (lots of `cd ..` then `cd etc`, `cd mosquitto`) -13. Create a configuration file: -`sudo touch file test.conf` -14. Edit the configuration fil: -`sudo nano -w test.conf` +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) -15. Start mosquitto -`mosquitto -v -c /etc/mosquitto/test.conf` +14. Enable mosquitto to start at each start of the system +`sudo systemctl enable mosquitto` +15. Restart the system. + +After restarting, the system is ready to be configured 16. Find the IP adress of your computer **- new console** @@ -128,4 +123,4 @@ To connect to the demo instance - press: "Connect to new Server" - press: "Demo Host Address" - User: "Testuser" -- Passw: "secret" \ No newline at end of file +- Passw: "secret" From b6a371e85cefbf46b65b6e91e91ab4fd7c1b60a2 Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 08:45:09 +0000 Subject: [PATCH 06/60] Add new file --- source/usage/Get it Running - Step by Step.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 source/usage/Get it Running - Step by Step.md diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/source/usage/Get it Running - Step by Step.md @@ -0,0 +1 @@ + From 80911f2ce10f2483f03d5903dcaaa498d5d32d10 Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 08:48:09 +0000 Subject: [PATCH 07/60] Update install_steps_ubuntu.md --- source/installation/install_steps_ubuntu.md | 58 --------------------- 1 file changed, 58 deletions(-) diff --git a/source/installation/install_steps_ubuntu.md b/source/installation/install_steps_ubuntu.md index cbbe080..d847924 100644 --- a/source/installation/install_steps_ubuntu.md +++ b/source/installation/install_steps_ubuntu.md @@ -66,61 +66,3 @@ Save (Strg-O) and close (Strg-X) 15. Restart the system. After restarting, the system is ready to be configured - -16. Find the IP adress of your computer -**- new console** -`ip a` - -17. Configure your Shelly -as long as your Shelly has not been given the credentials for a WLAN, it will create an access point (AP) for configuration. 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. - -18. MQTT Client setup -goto "Internet & Security" -> "Advanced - Developer Settings" -enable "MQTT" -enter the IP-Adress from Step 16 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!** - -19. WLAN Client setup -goto "Internet & Security" -> "WIFI MODE - CLIENT" -Set WLAN Credentials - -20. Configure Diflouroborane -Open the file "bffh.dhall" in the GUI Editor (just by double-clicking it) -Change `Shelly_123` to your Shelly name, e.g. `shelly1-123456789ABC` (**case sensitive!, dash sensitive!**) in "Link up machines to actors" and in "actors". -Change the third IP-adress under "listens" to the IP-adress of your computer. -**- save** - -21. start Diflouroburane -change to the directory in the console where you checked for the ip-address -`cd BFFH/bffh/target/release` -load settings to Diflouroborane: -`./diflouroborane -c examples/bffh.dhall --load examples` -start Diflouroborane: -`./diflouroborane -c examples/bffh.dhall` - -**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` -and restart start Diflouroborane: -`./diflouroborane -c examples/bffh.dhall` - -Download the borepin APP as described previously -- start the App -- press: "Connect to new Server" -- press: Enter the IP of your computer in the "Host"-Field -- Enter your Username and Password. - -To connect to the demo instance -- start the App -- press: "Connect to new Server" -- press: "Demo Host Address" -- User: "Testuser" -- Passw: "secret" From 123cff61eb7cab1e5bac6c179c6c991bccf1ce6a Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 09:12:29 +0000 Subject: [PATCH 08/60] Addes note that roles shall be managed in bffh.dhall and that the file "roles.toml" is depricated. --- source/configuration/bffh_config.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/configuration/bffh_config.md b/source/configuration/bffh_config.md index bed04b9..4d89111 100644 --- a/source/configuration/bffh_config.md +++ b/source/configuration/bffh_config.md @@ -130,6 +130,8 @@ machines = ## 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 @@ -226,4 +228,4 @@ actor_connections = { machine = "Another", actor = "Bash" }, { machine = "Yetmore", actor = "Bash2" } ] -``` \ No newline at end of file +``` From cd619cbf56baf16d53259b3914b2983d6cd95f35 Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 09:15:00 +0000 Subject: [PATCH 09/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index 8b13789..b731781 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -1 +1,70 @@ +*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 +- 2 Shellies registered to you system +- 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 +there are multiple ways to install the BFFH server. This can bei either done via +- a docker - see docker installation document. + +16. Find the IP adress of your computer +**- new console** +`ip a` + +17. Configure your Shelly +as long as your Shelly has not been given the credentials for a WLAN, it will create an access point (AP) for configuration. 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. + +18. MQTT Client setup +goto "Internet & Security" -> "Advanced - Developer Settings" +enable "MQTT" +enter the IP-Adress from Step 16 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!** + +19. WLAN Client setup +goto "Internet & Security" -> "WIFI MODE - CLIENT" +Set WLAN Credentials + +20. Configure Diflouroborane +Open the file "bffh.dhall" in the GUI Editor (just by double-clicking it) +Change `Shelly_123` to your Shelly name, e.g. `shelly1-123456789ABC` (**case sensitive!, dash sensitive!**) in "Link up machines to actors" and in "actors". +Change the third IP-adress under "listens" to the IP-adress of your computer. +**- save** + +21. start Diflouroburane +change to the directory in the console where you checked for the ip-address +`cd BFFH/bffh/target/release` +load settings to Diflouroborane: +`./diflouroborane -c examples/bffh.dhall --load examples` +start Diflouroborane: +`./diflouroborane -c examples/bffh.dhall` + +**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` +and restart start Diflouroborane: +`./diflouroborane -c examples/bffh.dhall` + +Download the borepin APP as described previously +- start the App +- press: "Connect to new Server" +- press: Enter the IP of your computer in the "Host"-Field +- Enter your Username and Password. + +To connect to the demo instance +- start the App +- press: "Connect to new Server" +- press: "Demo Host Address" +- User: "Testuser" +- Passw: "secret" From ea3db4961dcef711dad75dc7c3368ab8e5f7022b Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 09:59:55 +0000 Subject: [PATCH 10/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index b731781..567ae60 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -1,4 +1,4 @@ -*FabAcess Step By Step +#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 @@ -7,12 +7,17 @@ This document provides a step by step Instruction on how to get FabAcess running - 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 +##Step 1 Installing the BFFH-Server there are multiple ways to install the BFFH server. This can bei either done via -- a docker - see docker installation document. +- docker - see docker installation document +- installing from source - see installing from source documentation +- installing on Ubuntu for dummies + +##Get the FabAccess App +get the App via Apple Store or Google Apps. + + -16. Find the IP adress of your computer -**- new console** `ip a` 17. Configure your Shelly From 49d3ac1610555dbda1f95b5712635cb332cec6b3 Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 11:25:46 +0000 Subject: [PATCH 11/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 20 +++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index 567ae60..1d0dd41 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -1,4 +1,4 @@ -#FabAcess Step By Step +**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 @@ -7,18 +7,30 @@ This document provides a step by step Instruction on how to get FabAcess running - 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 +**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 -##Get the FabAccess App +**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 `docker-compose up -d`. If you compiled the server on your system this is done by entering `./diflouroborane -c examples/bffh.dhall --load examples` and then `./diflouroborane -c examples/bffh.dhall`. 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. 17. Configure your Shelly as long as your Shelly has not been given the credentials for a WLAN, it will create an access point (AP) for configuration. This AP will appear in your list of WLAN. From aa3d5a5fefd33ec70c8acf3b6616b931311df576 Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 11:38:33 +0000 Subject: [PATCH 12/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index 1d0dd41..7fc7f31 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -26,21 +26,25 @@ on the console of the system where the BFFH-Server is running. Use the adress li Start the server. If you are using the docker, this is done by using `docker-compose up -d`. If you compiled the server on your system this is done by entering `./diflouroborane -c examples/bffh.dhall --load examples` and then `./diflouroborane -c examples/bffh.dhall`. 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 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. -17. Configure your Shelly -as long as your Shelly has not been given the credentials for a WLAN, it will create an access point (AP) for configuration. This AP will appear in your list of WLAN. +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. -18. MQTT Client setup +Shelly MQTT Client setup + goto "Internet & Security" -> "Advanced - Developer Settings" enable "MQTT" -enter the IP-Adress from Step 16 in the field "IP-Adress" +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 @@ -49,10 +53,12 @@ note this ID for later **- save** **- re-check the settings!** -19. WLAN Client setup +Shelly WLAN Client setup goto "Internet & Security" -> "WIFI MODE - CLIENT" Set WLAN Credentials + + 20. Configure Diflouroborane Open the file "bffh.dhall" in the GUI Editor (just by double-clicking it) Change `Shelly_123` to your Shelly name, e.g. `shelly1-123456789ABC` (**case sensitive!, dash sensitive!**) in "Link up machines to actors" and in "actors". From 6b495a698a9b9303f111acb2f0b42764cc5dbec0 Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 11:39:17 +0000 Subject: [PATCH 13/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index 7fc7f31..d31c48c 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -1,4 +1,4 @@ -**FabAcess Step By Step** +***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 From 22fbc737d8400a45ba03cceadb013695c8eec4cb Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 11:39:48 +0000 Subject: [PATCH 14/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index d31c48c..d297971 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -1,4 +1,4 @@ -***FabAcess Step By Step*** +#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 From 760972bde3c73d5a5413c263e63b517b92d0ed6f Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 11:41:18 +0000 Subject: [PATCH 15/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index d297971..34a93f4 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -1,4 +1,4 @@ -#FabAcess Step By Step# +**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 @@ -24,7 +24,11 @@ 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 `docker-compose up -d`. If you compiled the server on your system this is done by entering `./diflouroborane -c examples/bffh.dhall --load examples` and then `./diflouroborane -c examples/bffh.dhall`. You will see some debug information, with probably some warnings. +Start the server. If you are using the docker, this is done by using
+`docker-compose up -d`.
+If you compiled the server on your system this is done by entering
+`./diflouroborane -c examples/bffh.dhall --load examples` and then `./diflouroborane -c examples/bffh.dhall`.
+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". From 0945518b905be7298a1457717631447b71af63fd Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 12:19:34 +0000 Subject: [PATCH 16/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 40 ++++++++++++++++--- 1 file changed, 35 insertions(+), 5 deletions(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index 34a93f4..4c0c692 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -44,7 +44,7 @@ as long as your Shelly has not been given the credentials for a WLAN, it will cr Connect to this Shelly-AP and connect to `192.168.33.1` in your browser. A configuration page should appear. If your Shelly is already connected to your WLAN, you must find the assigned IP-Adress (e.g. by looking into your router). Enter this IP Adress in your browser and you will get the configuration page. -Shelly MQTT Client setup +**Shelly MQTT Client setup** goto "Internet & Security" -> "Advanced - Developer Settings" enable "MQTT" @@ -57,15 +57,45 @@ note this ID for later **- save** **- re-check the settings!** -Shelly WLAN Client setup +**Shelly WLAN Client setup** + goto "Internet & Security" -> "WIFI MODE - CLIENT" Set WLAN Credentials +**Adding a Shelly to your server** +To understand the underlaying concept of actors and machines, please see the "configuration part" of the documentation. Four our example we will assume we have one actor (shelly) per machine. +**Tip** +Prior to modifying the configuration files the proper working of the MQTT broker should be tested. To test the broker it is the best to use a second (linux) computer with a different IP adress. To test if the broker allows access from an external IP address open a MQTT subscriber on the second computer by typing
+`mosquitto_sub -h 192.168.1.15 -t /test/topic` (change the IP adress to the adress of your server).
+Use `mosquitto_pub -h localhost -t /test/topic -m "Hallo from BFFH-Server!"` to send a message to the other computer. If the message appears, everything is ok. When not, this should be first solved, as a connection to the shellies will not be possible this way.
+If you are interested in communication between the shellies and the BFFH-Server you can use
+`mosquitto_sub -h 192.168.1.15 -t shellies/#` (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.
+ +First you have to make your "actors" (in our case the Shellies) know to the system.
+Go to the line where it starts with `, actors =` and after the `{` you can enter your Shelly with
+`shelly1-123456789ABC = { module = "Shelly", params = {=}}`
+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".
+Go to the line starting with `{actors_connections =` and after the following `[` you add
+`{ machine = "Name-of-your-Machine", actor = "shelly1-E8DB84A1CFF4" }` using your own Name-of-your-Machine and the Shelly-ID of the related actor. + +Now you have to set the access-permissions to your machine.
+Go to the line starting with `, machines =`. and after the `{` you can add a machine:
+`Name-of-your-Machine = +{ description = Some "I am your first Testmachine" + , disclose = "lab.test.read" + , manage = "lab.test.admin" + , name = "Shelly Rot" + , read = "lab.test.read" + , write = "lab.test.write" + },` -20. Configure Diflouroborane -Open the file "bffh.dhall" in the GUI Editor (just by double-clicking it) -Change `Shelly_123` to your Shelly name, e.g. `shelly1-123456789ABC` (**case sensitive!, dash sensitive!**) in "Link up machines to actors" and in "actors". Change the third IP-adress under "listens" to the IP-adress of your computer. **- save** From c2cb09e3b151085c54a48546943fc2d0d12ed503 Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 12:21:33 +0000 Subject: [PATCH 17/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index 4c0c692..c0946eb 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -87,14 +87,14 @@ Go to the line starting with `{actors_connections =` and after the following `[` Now you have to set the access-permissions to your machine.
Go to the line starting with `, machines =`. and after the `{` you can add a machine:
-`Name-of-your-Machine = -{ description = Some "I am your first Testmachine" - , disclose = "lab.test.read" - , manage = "lab.test.admin" - , name = "Shelly Rot" - , read = "lab.test.read" - , write = "lab.test.write" - },` +`Name-of-your-Machine =
+ { description = Some "I am your first Testmachine"
+ , disclose = "lab.test.read"
+ , manage = "lab.test.admin"
+ , name = "Shelly Rot"
+ , read = "lab.test.read"
+ , write = "lab.test.write"
+ },`
Change the third IP-adress under "listens" to the IP-adress of your computer. **- save** From 0a6eddf684778bcab953424e9cfbf89530be9a29 Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 12:23:50 +0000 Subject: [PATCH 18/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index c0946eb..f9916de 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -87,14 +87,14 @@ Go to the line starting with `{actors_connections =` and after the following `[` Now you have to set the access-permissions to your machine.
Go to the line starting with `, machines =`. and after the `{` you can add a machine:
-`Name-of-your-Machine =
- { description = Some "I am your first Testmachine"
- , disclose = "lab.test.read"
- , manage = "lab.test.admin"
- , name = "Shelly Rot"
- , read = "lab.test.read"
- , write = "lab.test.write"
- },`
+`Name-of-your-Machine =`
+` { description = Some "I am your first Testmachine"`
+` , disclose = "lab.test.read"`
+` , manage = "lab.test.admin"`
+` , name = "Shelly Rot"`
+` , read = "lab.test.read"`
+` , write = "lab.test.write"`
+` },`
Change the third IP-adress under "listens" to the IP-adress of your computer. **- save** From 85a611ed0ec09b854839a5971c37386eb125a8de Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 12:42:49 +0000 Subject: [PATCH 19/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 37 ++++++------------- 1 file changed, 12 insertions(+), 25 deletions(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index f9916de..8062fc7 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -76,6 +76,9 @@ 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.
+Link the server to the MQTT-broker
+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.
Go to the line where it starts with `, actors =` and after the `{` you can enter your Shelly with
`shelly1-123456789ABC = { module = "Shelly", params = {=}}`
@@ -83,45 +86,29 @@ 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".
Go to the line starting with `{actors_connections =` and after the following `[` you add
-`{ machine = "Name-of-your-Machine", actor = "shelly1-E8DB84A1CFF4" }` using your own Name-of-your-Machine and the Shelly-ID of the related actor. +`{ machine = "Identifyer-of-your-Machine", actor = "shelly1-E8DB84A1CFF4" }` using your own Name-of-your-Machine and the Shelly-ID of the related actor. -Now you have to set the access-permissions to your machine.
+Now you have to set the "access-permissions" to your "machine".
Go to the line starting with `, machines =`. and after the `{` you can add a machine:
-`Name-of-your-Machine =`
+`Identifyer-of-your-Machine =`
` { description = Some "I am your first Testmachine"`
` , disclose = "lab.test.read"`
` , manage = "lab.test.admin"`
-` , name = "Shelly Rot"`
+` , name = "Name of the Machine"`
` , read = "lab.test.read"`
` , write = "lab.test.write"`
` },`
-Change the third IP-adress under "listens" to the IP-adress of your computer. -**- save** +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".
+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. -21. start Diflouroburane -change to the directory in the console where you checked for the ip-address -`cd BFFH/bffh/target/release` -load settings to Diflouroborane: -`./diflouroborane -c examples/bffh.dhall --load examples` -start Diflouroborane: -`./diflouroborane -c examples/bffh.dhall` +**- 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` and restart start Diflouroborane: `./diflouroborane -c examples/bffh.dhall` -Download the borepin APP as described previously -- start the App -- press: "Connect to new Server" -- press: Enter the IP of your computer in the "Host"-Field -- Enter your Username and Password. - -To connect to the demo instance -- start the App -- press: "Connect to new Server" -- press: "Demo Host Address" -- User: "Testuser" -- Passw: "secret" +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. From 6beb4af5ea0fc13702d2bc4be8b03cae623c9c7a Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 12:52:10 +0000 Subject: [PATCH 20/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 26 +++++++++++++++---- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index 8062fc7..0feb8e5 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -27,7 +27,9 @@ on the console of the system where the BFFH-Server is running. Use the adress li Start the server. If you are using the docker, this is done by using
`docker-compose up -d`.
If you compiled the server on your system this is done by entering
-`./diflouroborane -c examples/bffh.dhall --load examples` and then `./diflouroborane -c examples/bffh.dhall`.
+`./diflouroborane -c examples/bffh.dhall --load examples`
+and then
+`./diflouroborane -c examples/bffh.dhall`.
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`). @@ -68,10 +70,12 @@ To understand the underlaying concept of actors and machines, please see the "co **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
`mosquitto_sub -h 192.168.1.15 -t /test/topic` (change the IP adress to the adress of your server).
-Use `mosquitto_pub -h localhost -t /test/topic -m "Hallo from BFFH-Server!"` to send a message to the other computer. If the message appears, everything is ok. When not, this should be first solved, as a connection to the shellies will not be possible this way.
+Use
+`mosquitto_pub -h localhost -t /test/topic -m "Hallo from BFFH-Server!"`
+to send a message to the other computer. If the message appears, everything is ok. When not, this should be first solved, as a connection to the shellies will not be possible this way.
If you are interested in communication between the shellies and the BFFH-Server you can use
-`mosquitto_sub -h 192.168.1.15 -t shellies/#` (change the IP adress to your needs).
-You will see some values popping op from time to time. +`mosquitto_sub -h 192.168.1.15 -t shellies/#`
+(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.
@@ -86,7 +90,8 @@ 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".
Go to the line starting with `{actors_connections =` and after the following `[` you add
-`{ machine = "Identifyer-of-your-Machine", actor = "shelly1-E8DB84A1CFF4" }` using your own Name-of-your-Machine and the Shelly-ID of the related actor. +`{ machine = "Identifyer-of-your-Machine", actor = "shelly1-E8DB84A1CFF4" }`
+using your own Name-of-your-Machine and the Shelly-ID of the related actor. Now you have to set the "access-permissions" to your "machine".
Go to the line starting with `, machines =`. and after the `{` you can add a machine:
@@ -112,3 +117,14 @@ 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:
+`urn:fabaccess:resource:{MachineID}`
+e.g.
+`urn:fabaccess:resource:Identifyer-of-your-Machine`
+ +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. + + + From c7f3f32ed2b87e32f3673e888ad5e2994422b0bf Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 13:56:30 +0000 Subject: [PATCH 21/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 81 +++++++++++++++++-- 1 file changed, 75 insertions(+), 6 deletions(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index 0feb8e5..a41867a 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/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 -- 2 Shellies registered to you system +- 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 -- 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".
Go to the line starting with `{actors_connections =` and after the following `[` you add
-`{ machine = "Identifyer-of-your-Machine", actor = "shelly1-E8DB84A1CFF4" }`
+`{ machine = "Identifier-of-your-Machine", actor = "shelly1-E8DB84A1CFF4" }`
using your own Name-of-your-Machine and the Shelly-ID of the related actor. Now you have to set the "access-permissions" to your "machine".
Go to the line starting with `, machines =`. and after the `{` you can add a machine:
-`Identifyer-of-your-Machine =`
+`Identifier-of-your-Machine =`
` { description = Some "I am your first Testmachine"`
` , disclose = "lab.test.read"`
` , manage = "lab.test.admin"`
@@ -104,7 +105,7 @@ Go to the line starting with `, machines =`. and after the `{` you can add a mac ` , write = "lab.test.write"`
` },`
-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".
+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".
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.
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
+`[Name-of-the-User]`
+`roles = ["Name-of-a-role/internal", "Name-of-another-role/internal"]`
+`priority = 0`
+`passwd = "the-chosen-password"`
+`noot = "whatever-this-means"`
+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 =`
+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 =`
+`{ permissions = `
+`[ "lab.machines.chainsaw.write"` - allows the user to use the machine
+`, "lab.machines.chainsaw.read"`- allows the user to read see the status of the machine
+`, "lab.machines.chainsaw.disclose"` - allows the user to see the machine in the machine overview
+`]` + +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 =`
+`{ parents = ["ChainsawUser"]`
- inherits all the permissions of the ChainsawUser +`, permissions = ["lab.machines.chainsaw.admin"]`
- addinional admin permissions +`}` + +The `machine` should be defined as: +`Identifier-of-your-Chainsaw =`
+` { description = Some "Beware of Freddy!"`
+` , disclose = "lab.machine.chainsaw.disclose"`
+` , manage = "lab.machine.chainsaw.admin"`
+` , name = "Chainsaw"`
+` , read = "lab.machine.chainsaw.read"`
+` , write = "lab.machine.chainsaw.write"`
+` },`
+ +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.
+Define a machine called "door" in the bffh.dhall
+-define the actor:
+`shelly1-123456789ABC = { module = "Shelly", params = {=}}`
+-define the machine:
+`{ machine = "door", actor = "shelly1-123456789ABC" }`
+-set permissions for the machine:
+`door =`
+` { description = Some "close it firmly"`
+` , disclose = "lab.door.disclose"`
+` , manage = "lab.door.admin"`
+` , name = "Door to the Lab"`
+` , read = "lab.door.read"`
+` , write = "lab.door.write"`
+` },`
+-create a role having ALL permissions to the door +`DoorUser =`
+`{ permissions = `
+`[ "lab.door.write"` - allows the user to use the door
+`, "lab.door.read"`- allows the user to read see the status of the door
+`, "lab.door.disclose"` - allows the user to see the machine in the machine overview
+`, "lab.door.admin"`
+`]`
+-assign the role DoorUser to all users From 47aa65b98b133d86de486a4a6b75d2b003770079 Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 14:03:45 +0000 Subject: [PATCH 22/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index a41867a..69d7319 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -175,11 +175,11 @@ The simple Shellies (1, 1pm, 2.5) have an internal timer "AUTO-OFF" which can be Go to "Timer" and set the "AUTO-OFF" to e.g. 3 seconds.
Define a machine called "door" in the bffh.dhall
--define the actor:
+- define the actor:
`shelly1-123456789ABC = { module = "Shelly", params = {=}}`
--define the machine:
+- define the machine:
`{ machine = "door", actor = "shelly1-123456789ABC" }`
--set permissions for the machine:
+- set permissions for the machine:
`door =`
` { description = Some "close it firmly"`
` , disclose = "lab.door.disclose"`
@@ -188,7 +188,7 @@ Define a machine called "door" in the bffh.dhall
` , read = "lab.door.read"`
` , write = "lab.door.write"`
` },`
--create a role having ALL permissions to the door +- create a role having ALL permissions to the door `DoorUser =`
`{ permissions = `
`[ "lab.door.write"` - allows the user to use the door
@@ -196,4 +196,7 @@ Define a machine called "door" in the bffh.dhall
`, "lab.door.disclose"` - allows the user to see the machine in the machine overview
`, "lab.door.admin"`
`]`
--assign the role DoorUser to all users +- 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 +**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"`). From 4eb15d3552e7602e3482ccf94791f4cb7eeda2c5 Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 14:05:42 +0000 Subject: [PATCH 23/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index 69d7319..564a1e0 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -5,7 +5,7 @@ This document provides a step by step Instruction on how to get FabAcess running - 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 +- 1 Shelly configured to identify if a machine is just switched on or realy running (TO-DO) **Step 1 Installing the BFFH-Server** @@ -198,5 +198,7 @@ Define a machine called "door" in the bffh.dhall
`]`
- 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 +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.
**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) From 2c90c4893c66be7dec8ed983487613e552b33396 Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 23 Dec 2021 14:06:59 +0000 Subject: [PATCH 24/60] Update Get it Running - Step by Step.md --- source/usage/Get it Running - Step by Step.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/Get it Running - Step by Step.md index 564a1e0..c83794c 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/Get it Running - Step by Step.md @@ -188,7 +188,7 @@ Define a machine called "door" in the bffh.dhall
` , read = "lab.door.read"`
` , write = "lab.door.write"`
` },`
-- create a role having ALL permissions to the door +- create a role having ALL permissions to the door
`DoorUser =`
`{ permissions = `
`[ "lab.door.write"` - allows the user to use the door
From e9fcc97018ffc25cb20a4a5fcc84c4d6abd208b6 Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Mon, 3 Jan 2022 19:35:58 +0100 Subject: [PATCH 25/60] Fixed Filenames --- .../usage/{Get it Running - Step by Step.md => setup_steps.md} | 2 +- source/usage/usage.rst | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) rename source/usage/{Get it Running - Step by Step.md => setup_steps.md} (99%) diff --git a/source/usage/Get it Running - Step by Step.md b/source/usage/setup_steps.md similarity index 99% rename from source/usage/Get it Running - Step by Step.md rename to source/usage/setup_steps.md index c83794c..eb95937 100644 --- a/source/usage/Get it Running - Step by Step.md +++ b/source/usage/setup_steps.md @@ -1,4 +1,4 @@ -**FabAcess Step By Step** +**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 diff --git a/source/usage/usage.rst b/source/usage/usage.rst index 0947adb..fe9b85f 100644 --- a/source/usage/usage.rst +++ b/source/usage/usage.rst @@ -7,5 +7,6 @@ But to explain our Features we will documentated some best Practices. .. toctree:: feature_qr.md + setup_steps.md From a597a9659a7880ff98a8f9804eca48404f472752 Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Mon, 3 Jan 2022 19:44:17 +0100 Subject: [PATCH 26/60] Fixed Missing Title in FabAccess Setup --- source/usage/setup_steps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/usage/setup_steps.md b/source/usage/setup_steps.md index eb95937..65b58ca 100644 --- a/source/usage/setup_steps.md +++ b/source/usage/setup_steps.md @@ -1,4 +1,4 @@ -**FabAccess Setup - Step By Step** +# 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 From ae1c8f4cb17baba1fc6502099c08cfcc798ad1db Mon Sep 17 00:00:00 2001 From: Joris Date: Fri, 7 Jan 2022 17:16:42 +0000 Subject: [PATCH 27/60] Update install_steps_ubuntu.md --- source/installation/install_steps_ubuntu.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/installation/install_steps_ubuntu.md b/source/installation/install_steps_ubuntu.md index d847924..0b51c7b 100644 --- a/source/installation/install_steps_ubuntu.md +++ b/source/installation/install_steps_ubuntu.md @@ -24,7 +24,7 @@ there might be better places compared to where I created it, but it works... `cd BFFH` 5. Clone the Diflouroborane repository -`git clone https://gitlab.com/fabinfra/fabaccess/bffh` +`git clone https://gitlab.com/fabinfra/fabaccess/bffh --recursive --branch main` 6. For compiling some dependencies were missing on Ubuntu `git submodule update —init` From ac54c90ba5d14eb22e49a803e184a797e1482301 Mon Sep 17 00:00:00 2001 From: Joris Date: Tue, 11 Jan 2022 18:08:04 +0000 Subject: [PATCH 28/60] Update install_steps_ubuntu.md --- source/installation/install_steps_ubuntu.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/installation/install_steps_ubuntu.md b/source/installation/install_steps_ubuntu.md index 0b51c7b..2ba4334 100644 --- a/source/installation/install_steps_ubuntu.md +++ b/source/installation/install_steps_ubuntu.md @@ -27,7 +27,7 @@ there might be better places compared to where I created it, but it works... `git clone https://gitlab.com/fabinfra/fabaccess/bffh --recursive --branch main` 6. For compiling some dependencies were missing on Ubuntu -`git submodule update —init` +`git submodule update --init` `sudo apt install libgsasl7-dev` `sudo apt install cmake` `sudo apt install libclang-dev` From 3a7a63af7d7fd65a584c4bac2f210bc282da0c24 Mon Sep 17 00:00:00 2001 From: Joris Date: Wed, 12 Jan 2022 15:40:43 +0000 Subject: [PATCH 29/60] Update install_steps_ubuntu.md --- source/installation/install_steps_ubuntu.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/source/installation/install_steps_ubuntu.md b/source/installation/install_steps_ubuntu.md index 2ba4334..2d12b8d 100644 --- a/source/installation/install_steps_ubuntu.md +++ b/source/installation/install_steps_ubuntu.md @@ -65,4 +65,12 @@ Save (Strg-O) and close (Strg-X) `sudo systemctl enable mosquitto` 15. Restart the system. -After restarting, the system is ready to be configured +The BFFH-server can be found at the /target/release folder. To start the server change into the directory by using `cd target/release` and using: +`./diflouroborane -c examples/bffh.dhall --load examples` +an then: +`./diflouroborane -c examples/bffh.dhall` + +#BUT# prior to starting bffh, you should first configure the bffh.dhall file (see the Use FabAcess section). + + + From 96c8b908216a4405e98dfe8b76c3eb4963783dcf Mon Sep 17 00:00:00 2001 From: Joris Date: Wed, 12 Jan 2022 15:41:32 +0000 Subject: [PATCH 30/60] Update install_steps_ubuntu.md --- source/installation/install_steps_ubuntu.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/installation/install_steps_ubuntu.md b/source/installation/install_steps_ubuntu.md index 2d12b8d..9ee1b85 100644 --- a/source/installation/install_steps_ubuntu.md +++ b/source/installation/install_steps_ubuntu.md @@ -70,7 +70,7 @@ The BFFH-server can be found at the /target/release folder. To start the server an then: `./diflouroborane -c examples/bffh.dhall` -#BUT# prior to starting bffh, you should first configure the bffh.dhall file (see the Use FabAcess section). +**BUT** prior to starting bffh, you should first configure the bffh.dhall file (see the "Use FabAcess" section). From bb20003a2ccd9f35bdca2c2a85248c60715e6c76 Mon Sep 17 00:00:00 2001 From: Joris Date: Wed, 12 Jan 2022 15:57:00 +0000 Subject: [PATCH 31/60] Update install_steps_ubuntu.md --- source/installation/install_steps_ubuntu.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/source/installation/install_steps_ubuntu.md b/source/installation/install_steps_ubuntu.md index 9ee1b85..5ecefa9 100644 --- a/source/installation/install_steps_ubuntu.md +++ b/source/installation/install_steps_ubuntu.md @@ -65,9 +65,13 @@ Save (Strg-O) and close (Strg-X) `sudo systemctl enable mosquitto` 15. Restart the system. -The BFFH-server can be found at the /target/release folder. To start the server change into the directory by using `cd target/release` and using: +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 start the server change into the directory by using `cd target/release` and using: + `./diflouroborane -c examples/bffh.dhall --load examples` an then: + `./diflouroborane -c examples/bffh.dhall` **BUT** prior to starting bffh, you should first configure the bffh.dhall file (see the "Use FabAcess" section). From c556fb6d950975dbbeb2daa499acea54c6687dfc Mon Sep 17 00:00:00 2001 From: Joris Date: Wed, 12 Jan 2022 16:25:25 +0000 Subject: [PATCH 32/60] Update install_steps_ubuntu.md --- source/installation/install_steps_ubuntu.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/source/installation/install_steps_ubuntu.md b/source/installation/install_steps_ubuntu.md index 5ecefa9..ec9e789 100644 --- a/source/installation/install_steps_ubuntu.md +++ b/source/installation/install_steps_ubuntu.md @@ -67,6 +67,20 @@ Save (Strg-O) and close (Strg-X) 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: `./diflouroborane -c examples/bffh.dhall --load examples` From a22ba4077a287e9fb1dbac55e1051eabc48bd4ef Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Sat, 5 Feb 2022 11:14:58 +0000 Subject: [PATCH 33/60] Update Store Links to Release --- source/installation/client_store.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/source/installation/client_store.md b/source/installation/client_store.md index 4818ef4..ac8f8d8 100644 --- a/source/installation/client_store.md +++ b/source/installation/client_store.md @@ -1,13 +1,10 @@ # Get Client from Store ## Hardware Requirements -Android SDK Version: 21 +Minimal Android Version: 5.0 (API Level 21) -iOS Version: 13 - -Windows 10: 1709 - Build:16299 +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://play.google.com/store/apps/details?id=org.fab_infra.fabaccess](https://testflight.apple.com/join/KfeUaHT4) -+ **Windows**: [https://play.google.com/store/apps/details?id=org.fab_infra.fabaccess](https://www.microsoft.com/de-de/p/fabaccess/9p69mwzjf2mv) \ No newline at end of file ++ **iOS**: [https://apps.apple.com/us/app/fabaccess/id1531873374](https://apps.apple.com/us/app/fabaccess/id1531873374) From 162346b88b6034ba26b6e7e1367c6740c17a850d Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Sat, 5 Feb 2022 11:22:29 +0000 Subject: [PATCH 34/60] Update index.rst --- source/index.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/index.rst b/source/index.rst index 5fccedb..32a9cc6 100644 --- a/source/index.rst +++ b/source/index.rst @@ -6,6 +6,8 @@ Welcome to FabAccess documentation! ====================================== +Version 0.3 is the current Beta Test. + FabAccess is still in a state of development and has no stable Release. So there is no stability and backward compatibility between the versions. From 67661273ac7e6a558fcfa43d2b04882c22848d5a Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Sat, 5 Feb 2022 11:33:56 +0000 Subject: [PATCH 35/60] Update client_store.md --- source/installation/client_store.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/installation/client_store.md b/source/installation/client_store.md index ac8f8d8..4be200d 100644 --- a/source/installation/client_store.md +++ b/source/installation/client_store.md @@ -7,4 +7,6 @@ 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) + +How to change to Beta Releases on Android: [https://support.google.com/googleplay/answer/7003180?hl=de](https://support.google.com/googleplay/answer/7003180?hl=de) ++ **iOS**: [https://testflight.apple.com/join/KfeUaHT4](https://testflight.apple.com/join/KfeUaHT4) From 4f529d1d2c6dda2403048a7717f87f83c2f3a0a0 Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Sat, 23 Apr 2022 21:57:56 +0000 Subject: [PATCH 36/60] Update server_build.md --- source/installation/server_build.md | 46 ++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 14 deletions(-) diff --git a/source/installation/server_build.md b/source/installation/server_build.md index de076b1..150a711 100644 --- a/source/installation/server_build.md +++ b/source/installation/server_build.md @@ -1,16 +1,34 @@ # Build Server from Source -1. Install [rustup.rs](rustup.rs). Distribution packages for rustc are generally way too old -1. `$ rustup install stable` -1. Get yourself a directory to clone BFFH into - * If you put this dir on a SSD you can speed up build times by 5-10 times. -1. `git clone --recursive --branch stable` - * ... stable ... TODO... - * You can also check out the `development` branch but keep in mind that until Beta it has no stability guarantee. It may work. It may make you a sandwich. But it may also set your hat on fire and fill your shoes with orange juice. *You have been warned*. -1. `cargo install --path .` - * if you add `--debug` you get a debug build. It gives you much more logging output but it's slower to run and is almost spammy -1. Make yourself a coffee. Or tea. Or open $beverage of your choice. You earned it! (And you'll be looking at "**Compiling** " for a while.) - * If you get `error: failed to run custom build command for 'gsasl-sys v0.2.3'` or something like that with the stderr output reading "[…]Unable to find libclang[…]": - * `export LIBCLANG_PATH=/usr/lib` - Or wherever `libclang.so` is installed on your computer. It's usually `/usr/lib/libclang.so` or `/usr/lib/llvm/12/lib/libclang.so` or similar. If you can't find it, consult your package manager - * If you get any other error open an issue \ No newline at end of file +## 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 + + +## 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` From c9ebe7c686cb433e45ddf7381047a28c60ad36d7 Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Tue, 26 Apr 2022 13:22:18 +0200 Subject: [PATCH 37/60] Added: Audit Log, NFC && Changed: Store Link --- source/installation/client_store.md | 5 ++- source/usage/audit_log.md | 5 +++ source/usage/nfc.md | 57 +++++++++++++++++++++++++++++ source/usage/usage.rst | 2 + 4 files changed, 67 insertions(+), 2 deletions(-) create mode 100644 source/usage/audit_log.md create mode 100644 source/usage/nfc.md diff --git a/source/installation/client_store.md b/source/installation/client_store.md index 4be200d..aece66f 100644 --- a/source/installation/client_store.md +++ b/source/installation/client_store.md @@ -7,6 +7,7 @@ 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) -How to change to Beta Releases on Android: [https://support.google.com/googleplay/answer/7003180?hl=de](https://support.google.com/googleplay/answer/7003180?hl=de) -+ **iOS**: [https://testflight.apple.com/join/KfeUaHT4](https://testflight.apple.com/join/KfeUaHT4) +## Beta Links - use on youre own risk ++ **iOS**: [https://testflight.apple.com/join/KfeUaHT4](https://testflight.apple.com/join/KfeUaHT4) \ No newline at end of file diff --git a/source/usage/audit_log.md b/source/usage/audit_log.md new file mode 100644 index 0000000..bdabd68 --- /dev/null +++ b/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}}}}` diff --git a/source/usage/nfc.md b/source/usage/nfc.md new file mode 100644 index 0000000..52372fa --- /dev/null +++ b/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:` + +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 \ No newline at end of file diff --git a/source/usage/usage.rst b/source/usage/usage.rst index fe9b85f..19818fa 100644 --- a/source/usage/usage.rst +++ b/source/usage/usage.rst @@ -8,5 +8,7 @@ But to explain our Features we will documentated some best Practices. .. toctree:: feature_qr.md setup_steps.md + audit_log.md + nfc.md From 530070951169b0b3b690374577c910afe02b023b Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Tue, 26 Apr 2022 13:27:07 +0200 Subject: [PATCH 38/60] Removed Beta Notification --- source/index.rst | 2 -- source/usage/usage.rst | 4 +--- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/source/index.rst b/source/index.rst index 32a9cc6..5fccedb 100644 --- a/source/index.rst +++ b/source/index.rst @@ -6,8 +6,6 @@ Welcome to FabAccess documentation! ====================================== -Version 0.3 is the current Beta Test. - FabAccess is still in a state of development and has no stable Release. So there is no stability and backward compatibility between the versions. diff --git a/source/usage/usage.rst b/source/usage/usage.rst index 19818fa..33499fa 100644 --- a/source/usage/usage.rst +++ b/source/usage/usage.rst @@ -9,6 +9,4 @@ But to explain our Features we will documentated some best Practices. feature_qr.md setup_steps.md audit_log.md - nfc.md - - + nfc.md \ No newline at end of file From 1c4709029f300804dffe53f24df7ebb4685cc103 Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Tue, 26 Apr 2022 13:31:43 +0200 Subject: [PATCH 39/60] Fix NFC --- source/usage/nfc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/usage/nfc.md b/source/usage/nfc.md index 52372fa..f420c4c 100644 --- a/source/usage/nfc.md +++ b/source/usage/nfc.md @@ -43,7 +43,7 @@ Examples: 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 +Application Identifier (AID): `0x464142` ## NFC Implementation C# - https://gitlab.com/fabinfra/fabaccess/nfc From 4e9961c916cbabc27264f76de36af3501cb7826c Mon Sep 17 00:00:00 2001 From: "T. Mulzer" <4284531-tmulzer@users.noreply.gitlab.com> Date: Mon, 2 May 2022 19:13:17 +0000 Subject: [PATCH 40/60] Mention proxmox as server-virtualization. --- source/installation/server_build.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/installation/server_build.md b/source/installation/server_build.md index 150a711..2b02111 100644 --- a/source/installation/server_build.md +++ b/source/installation/server_build.md @@ -1,5 +1,7 @@ # Build Server from Source +E.g. in a proxmox- or lxc-container. + ## Install Dependencies ### Ubuntu / Debian 1. `sudo apt update && sudo apt upgrade` From dd3924546d54a024b20d75834bc367dcc5f23e99 Mon Sep 17 00:00:00 2001 From: Nadja Reitzenstein Date: Tue, 10 May 2022 16:11:01 +0200 Subject: [PATCH 41/60] Fix the --load example for bffh --- source/usage/setup_steps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/usage/setup_steps.md b/source/usage/setup_steps.md index 65b58ca..2270813 100644 --- a/source/usage/setup_steps.md +++ b/source/usage/setup_steps.md @@ -113,7 +113,7 @@ The given permissions are ok to start with (if you did not change the roles of t **-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` +`./diflouroborane -c examples/bffh.dhall --load examples/users.toml` and restart start Diflouroborane: `./diflouroborane -c examples/bffh.dhall` From 5631c18d8a451b2b9b839261b7b4d687e3a648c4 Mon Sep 17 00:00:00 2001 From: Nadja Reitzenstein Date: Thu, 12 May 2022 16:36:19 +0200 Subject: [PATCH 42/60] Arch linux setup documentation --- README.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 752dafa..04d40a6 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,11 @@ # fabaccess-docs -Documentation for the fabaccess project. \ No newline at end of file +Documentation for the fabaccess project. + +## Setup +### Archlinux + +Install required packages: +```shell +$ pacman -S python-sphinx python-sphinx_rtd_theme python-recommonmark +``` From c794881d4f12a9fbd70cb735b6371704705cc67a Mon Sep 17 00:00:00 2001 From: Nadja Reitzenstein Date: Thu, 12 May 2022 16:42:18 +0200 Subject: [PATCH 43/60] Add `make serve` opening a local dev server --- Makefile | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index d0c3cbf..9592445 100644 --- a/Makefile +++ b/Makefile @@ -12,7 +12,11 @@ BUILDDIR = build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +serve: + @$(MAKE) html + cd $(BUILDDIR)/html && python -m http.server + +.PHONY: help serve Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). From ae074ffcf1df3eb50f2dbea8f99e08d3bf7e28b5 Mon Sep 17 00:00:00 2001 From: Nadja Reitzenstein Date: Thu, 12 May 2022 16:44:40 +0200 Subject: [PATCH 44/60] Okay we have setup docs in CONTRIBUTING nvm --- CONTRIBUTE.md | 2 +- README.md | 8 -------- 2 files changed, 1 insertion(+), 9 deletions(-) diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md index f774d34..74362d8 100644 --- a/CONTRIBUTE.md +++ b/CONTRIBUTE.md @@ -8,7 +8,7 @@ Please note we have a code of conduct, please follow it in all your interactions - Install Sphinx packages for your system. -```sudo pacman -S python-sphinx``` +```sudo pacman -S python-sphinx python-sphinx_rtd_theme python-recommonmark``` or ```apt install python-sphinx``` - Clone or update the gitlab-repo of the documentation diff --git a/README.md b/README.md index 04d40a6..ddb8955 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,3 @@ # fabaccess-docs Documentation for the fabaccess project. - -## Setup -### Archlinux - -Install required packages: -```shell -$ pacman -S python-sphinx python-sphinx_rtd_theme python-recommonmark -``` From 5d312045457a6414e3022555113ecffdd6bf68ec Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Tue, 24 May 2022 23:23:28 +0000 Subject: [PATCH 45/60] Update source/configuration/configuration.rst, source/configuration/log_config.md, source/configuration/default_roles.md --- source/configuration/configuration.rst | 4 +++- source/configuration/default_roles.md | 10 ++++++++++ source/configuration/log_config.md | 11 +++++++++++ 3 files changed, 24 insertions(+), 1 deletion(-) create mode 100644 source/configuration/default_roles.md create mode 100644 source/configuration/log_config.md diff --git a/source/configuration/configuration.rst b/source/configuration/configuration.rst index 9fb737c..78d528d 100644 --- a/source/configuration/configuration.rst +++ b/source/configuration/configuration.rst @@ -8,4 +8,6 @@ In the current state of FabAccess we will no support database migration so all p .. toctree:: bffh_config.md - user_config.md \ No newline at end of file + user_config.md + log_config.md + default_roles.md diff --git a/source/configuration/default_roles.md b/source/configuration/default_roles.md new file mode 100644 index 0000000..6f5dd7b --- /dev/null +++ b/source/configuration/default_roles.md @@ -0,0 +1,10 @@ +# Default Roles + +BFFH has some standard roles to assign to management and admin rights. + +## UserSystem +* `bffh.users.manage` - Get ManageInterface in UserSystem + +## User +* `bffh.users.info` - Get InfoInterface for every User +* `bffh.users.admin` - Get AdminInterface for every User diff --git a/source/configuration/log_config.md b/source/configuration/log_config.md new file mode 100644 index 0000000..8173c43 --- /dev/null +++ b/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` From ebde20d51e06941014f2b44cb422ee5fb9b2ed1b Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Tue, 19 Jul 2022 12:54:19 +0000 Subject: [PATCH 46/60] Update default_roles.md --- source/configuration/default_permission.md | 10 ++++++++++ source/configuration/default_roles.md | 10 ---------- 2 files changed, 10 insertions(+), 10 deletions(-) create mode 100644 source/configuration/default_permission.md delete mode 100644 source/configuration/default_roles.md diff --git a/source/configuration/default_permission.md b/source/configuration/default_permission.md new file mode 100644 index 0000000..55a6634 --- /dev/null +++ b/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) diff --git a/source/configuration/default_roles.md b/source/configuration/default_roles.md deleted file mode 100644 index 6f5dd7b..0000000 --- a/source/configuration/default_roles.md +++ /dev/null @@ -1,10 +0,0 @@ -# Default Roles - -BFFH has some standard roles to assign to management and admin rights. - -## UserSystem -* `bffh.users.manage` - Get ManageInterface in UserSystem - -## User -* `bffh.users.info` - Get InfoInterface for every User -* `bffh.users.admin` - Get AdminInterface for every User From 8d8894c267edbf8b6150d108cda4a18de3c52337 Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Tue, 19 Jul 2022 12:54:59 +0000 Subject: [PATCH 47/60] Update configuration.rst --- source/configuration/configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/configuration/configuration.rst b/source/configuration/configuration.rst index 78d528d..ec18fc4 100644 --- a/source/configuration/configuration.rst +++ b/source/configuration/configuration.rst @@ -10,4 +10,4 @@ In the current state of FabAccess we will no support database migration so all p bffh_config.md user_config.md log_config.md - default_roles.md + default_permissions.md From ca1f5d7bd6eb7c6b519cfcc2c27333caac20d680 Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Wed, 24 Aug 2022 12:18:19 +0000 Subject: [PATCH 48/60] Update source/configuration/configuration.rst --- source/configuration/configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/configuration/configuration.rst b/source/configuration/configuration.rst index ec18fc4..ca3b36e 100644 --- a/source/configuration/configuration.rst +++ b/source/configuration/configuration.rst @@ -10,4 +10,4 @@ In the current state of FabAccess we will no support database migration so all p bffh_config.md user_config.md log_config.md - default_permissions.md + default_permission.md From d366a69c3b52b04a88e25d69410c526dcf1968e1 Mon Sep 17 00:00:00 2001 From: Michael Michel Date: Mon, 31 Oct 2022 11:18:13 +0100 Subject: [PATCH 49/60] added first content to user_config.md --- source/configuration/user_config.md | 49 +++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/source/configuration/user_config.md b/source/configuration/user_config.md index 782130f..b98fd0b 100644 --- a/source/configuration/user_config.md +++ b/source/configuration/user_config.md @@ -1 +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" +``` \ No newline at end of file From dc40bebb1bfce3fead6fdd47ead38ab7400638fe Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Wed, 30 Nov 2022 20:13:01 +0000 Subject: [PATCH 50/60] Add link to documentation --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index ddb8955..770202d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ # fabaccess-docs Documentation for the fabaccess project. +You can find the rendered docs at: https://fab-access.readthedocs.io/ + From 80f82347b1b2e89c941a89cdc9dfcc524444ae98 Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Wed, 30 Nov 2022 20:17:30 +0000 Subject: [PATCH 51/60] rename docker compose project The reason I rename it is that I use several docker compose files on my computer The names of the directories are the docker container prefix. I would like to have a descriptive prefix. --- source/installation/server_docker.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/installation/server_docker.md b/source/installation/server_docker.md index 0e0820a..d27348d 100644 --- a/source/installation/server_docker.md +++ b/source/installation/server_docker.md @@ -10,7 +10,7 @@ Docker Image can not run on armv6 (Raspberry Pi 1 or Raspberry Pi Zero) 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` +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) @@ -19,4 +19,4 @@ Docker Image can not run on armv6 (Raspberry Pi 1 or Raspberry Pi Zero) 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` \ No newline at end of file +Get Server Logs: `docker-compose logs` From f0127d21116c298b5c418218063268eeb475f29a Mon Sep 17 00:00:00 2001 From: Kai Kriegel Date: Tue, 27 Dec 2022 15:26:23 +0000 Subject: [PATCH 52/60] improved docs for mqtt config --- source/configuration/bffh_config.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/source/configuration/bffh_config.md b/source/configuration/bffh_config.md index 4d89111..8731c8d 100644 --- a/source/configuration/bffh_config.md +++ b/source/configuration/bffh_config.md @@ -18,7 +18,15 @@ listens = ``` ### `mqtt_url` -Contains the Address for the MQTT Server BFFH connects to +Contains the Address for the MQTT Server BFFH connects to. + +The Address has the format `://[user]:[password]@:[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" From 2c7bbcf0b296009ef280a515fa154c4204770fe9 Mon Sep 17 00:00:00 2001 From: Kai Kriegel Date: Thu, 19 Jan 2023 00:27:39 +0000 Subject: [PATCH 53/60] update ubuntu example --- source/installation/install_steps_ubuntu.md | 28 ++++++++++++--------- 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/source/installation/install_steps_ubuntu.md b/source/installation/install_steps_ubuntu.md index ec9e789..fdfdaae 100644 --- a/source/installation/install_steps_ubuntu.md +++ b/source/installation/install_steps_ubuntu.md @@ -53,7 +53,7 @@ Diflouroborane uses mosquitto MQTT broker to communicate with the Shellies. Star 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 service mosquitto stop` +`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` @@ -62,31 +62,35 @@ add: `allow_anonymous true` Save (Strg-O) and close (Strg-X) 14. Enable mosquitto to start at each start of the system -`sudo systemctl enable mosquitto` +`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" } } }` +``` +-- , 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" } } }` +``` +, 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: -`./diflouroborane -c examples/bffh.dhall --load examples` +`./bffhd -c examples/bffh.dhall --load examples/users.toml` an then: -`./diflouroborane -c examples/bffh.dhall` +`./bffhd -c examples/bffh.dhall` **BUT** prior to starting bffh, you should first configure the bffh.dhall file (see the "Use FabAcess" section). From 578be5a47cbec64d48ee93a53951840cba982c3e Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Fri, 26 Apr 2024 15:03:25 +0200 Subject: [PATCH 54/60] Init Concepts --- source/concepts/claims.md | 16 ++++++++++++++++ source/concepts/concepts.rst | 13 +++++++++++++ source/concepts/measurements.md | 2 ++ source/concepts/projects.md | 2 ++ source/concepts/terminals.md | 2 ++ source/concepts/traits/checkable.md | 18 ++++++++++++++++++ source/concepts/traits/claimable.md | 5 +++++ source/concepts/traits/doorable.md | 16 ++++++++++++++++ source/concepts/traits/locatable.md | 15 +++++++++++++++ source/concepts/traits/lockable.md | 16 ++++++++++++++++ source/concepts/traits/powerable.md | 13 +++++++++++++ source/concepts/traits/traits.rst | 17 +++++++++++++++++ source/index.rst | 1 + 13 files changed, 136 insertions(+) create mode 100644 source/concepts/claims.md create mode 100644 source/concepts/concepts.rst create mode 100644 source/concepts/measurements.md create mode 100644 source/concepts/projects.md create mode 100644 source/concepts/terminals.md create mode 100644 source/concepts/traits/checkable.md create mode 100644 source/concepts/traits/claimable.md create mode 100644 source/concepts/traits/doorable.md create mode 100644 source/concepts/traits/locatable.md create mode 100644 source/concepts/traits/lockable.md create mode 100644 source/concepts/traits/powerable.md create mode 100644 source/concepts/traits/traits.rst diff --git a/source/concepts/claims.md b/source/concepts/claims.md new file mode 100644 index 0000000..6edd66d --- /dev/null +++ b/source/concepts/claims.md @@ -0,0 +1,16 @@ +# Claims +Ein Claim ist eine Zugang zu einer Resource um deren dynamischen Zustand zu ändern. Claims können dabei auch von mehreren Nutzern gleichzeitig erhalten werden. +Claims enthalten Traits, welche eine Liste an Methoden ist, um den Zustand einer Resource zu ändern. +Um einen Claim auf eine Resource zu erhalten kann man entweder ein Claim der Resource selber beziehen oder sich auf eine Liste mit einem Interest eintragen, welche als Queue abgearbeitet wird, sobald eine Resource disowned wird. + +Ein Interest bildet das Anmeleden eines Interesses an einer Resource beim Server an. Ein Interest ist hierbei verbindlich, sollte also ein Nutzer ein Interest auf eine Resource haben, dann wird ihm diese auch automatisch gegeben, sobald die Resource keinen Claim mehr hat. + +Um den Zustand einer Resource abzufragen kann auf eine Resource ein Notify geholt werden. Dieses Notify gibt den Zustand einer Resource zurück, also auch eine Möglichkeit auf einen Zustand zu einer Resource zu subscriben und Updates zu einer Änderung zu erhalten. + +Mit Claims sollen die verschienden Eigenschaften einer Resource abgebildet werden ohne, dass der Server das Konzept des Verleihens jedes mal neu Implementieren muss. + +Eine weitere Möglichkeit einen Claim zu erhalten ist über ein Transfer eines Claims. Hierbei holt sich der erste Nutzer ein Token, über transfer(), welches er per QR-Code oder NFC an einen zweiten Nutzer weitergibt. Dieser kann dann den Claim übernehmen, wenn er das Token beim Server einlöst. Dabei ist zu beachten, dass der übernehmende Nuter auch über die Berechtigung verfügen muss die Resource leihen zu dürfen. + +Die letzte Möglichkeit einen Claim zu erhalten ist in dem ein Ausbilder lend() auf dem Claim aufruft und ein Token erhält, welches er einer Auszubildenen übergibt. Dieser kann dann auch die Maschine nutzen, wenn er nicht die erforderliche Berechtigung hat. Dabei erhält nach erfolgreicher einlösung des Tokens der Ausbilder einen Interest, mit welchem er den Claim zurückfordern kann. Dieses Konzept kann recursiv angewendet werden. Bei einem Lend bleibt der übergeber des Tokens in Verantwortung, im gegensatz zum Transfer, in dem er die Verantwortung abgibt. + +# TODO diff --git a/source/concepts/concepts.rst b/source/concepts/concepts.rst new file mode 100644 index 0000000..da463bf --- /dev/null +++ b/source/concepts/concepts.rst @@ -0,0 +1,13 @@ +Concepts of FabAccess +================= + +FabAccess nutzt mehrer Konzept um den Process des Verleihens nutzbar zu machen. Und an den benötigten Stellen Freiheiten zugeben, um Anpassungen vornehmen zu können. + + + +.. toctree:: + claims.md + traits.md + measurements.md + projects.md + terminals.md \ No newline at end of file diff --git a/source/concepts/measurements.md b/source/concepts/measurements.md new file mode 100644 index 0000000..2d5259d --- /dev/null +++ b/source/concepts/measurements.md @@ -0,0 +1,2 @@ +# Measurements +Messwerte von Resourcen \ No newline at end of file diff --git a/source/concepts/projects.md b/source/concepts/projects.md new file mode 100644 index 0000000..a0904ec --- /dev/null +++ b/source/concepts/projects.md @@ -0,0 +1,2 @@ +# Projects +Claims mit einem Verweis auf Projekte beim Leihen von Resourcen \ No newline at end of file diff --git a/source/concepts/terminals.md b/source/concepts/terminals.md new file mode 100644 index 0000000..f721ec0 --- /dev/null +++ b/source/concepts/terminals.md @@ -0,0 +1,2 @@ +# Terminals +Eingeschränkte Nutzung von Resourcen bei Ausleih Terminals \ No newline at end of file diff --git a/source/concepts/traits/checkable.md b/source/concepts/traits/checkable.md new file mode 100644 index 0000000..3d3b3b3 --- /dev/null +++ b/source/concepts/traits/checkable.md @@ -0,0 +1,18 @@ +# Checkable +Trait welcher den Zustand von Resourcen abbildet, welche eine Überprüfung nach einer Nutzung benötigen. + +## 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 +``` \ No newline at end of file diff --git a/source/concepts/traits/claimable.md b/source/concepts/traits/claimable.md new file mode 100644 index 0000000..7b7f4a2 --- /dev/null +++ b/source/concepts/traits/claimable.md @@ -0,0 +1,5 @@ +# Claimable +Sonderfall um den Status des Claims anbieten zu können. + +## OID +`1.3.6.1.4.1.61783.612.1.0` \ No newline at end of file diff --git a/source/concepts/traits/doorable.md b/source/concepts/traits/doorable.md new file mode 100644 index 0000000..7524cc3 --- /dev/null +++ b/source/concepts/traits/doorable.md @@ -0,0 +1,16 @@ +# Doorable +Grundlegender Traits zum Ansteuern von Türen. + +## 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 +``` \ No newline at end of file diff --git a/source/concepts/traits/locatable.md b/source/concepts/traits/locatable.md new file mode 100644 index 0000000..0c9c65e --- /dev/null +++ b/source/concepts/traits/locatable.md @@ -0,0 +1,15 @@ +# Locatable +Grundlegender Trait zum Auffinden von Resourcen + +## 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 +``` \ No newline at end of file diff --git a/source/concepts/traits/lockable.md b/source/concepts/traits/lockable.md new file mode 100644 index 0000000..3b07e75 --- /dev/null +++ b/source/concepts/traits/lockable.md @@ -0,0 +1,16 @@ +# Lockers +Traits zum Abbilden von Schlössern + +## OID +`1.3.6.1.4.1.61783.612.1.4` + +## States +```mermaid +stateDiagram + [*] --> locked + locked --> unlocked: unengage + unlocked --> locked + unlocked --> open + open --> unengaged + unengaged --> locked: engage + unengaged --> open \ No newline at end of file diff --git a/source/concepts/traits/powerable.md b/source/concepts/traits/powerable.md new file mode 100644 index 0000000..0cdf096 --- /dev/null +++ b/source/concepts/traits/powerable.md @@ -0,0 +1,13 @@ +# Powerable +Grundlegender Trait, welcher Resourcen einschalten kann. + +## OID +`1.3.6.1.4.1.61783.612.1.1` + +## States +```mermaid +stateDiagram + [*] --> OFF + OFF --> ON: turnON + ON --> OFF: turnOFF +``` \ No newline at end of file diff --git a/source/concepts/traits/traits.rst b/source/concepts/traits/traits.rst new file mode 100644 index 0000000..175161b --- /dev/null +++ b/source/concepts/traits/traits.rst @@ -0,0 +1,17 @@ +Traits +================= + +Traits sind Implementierung speziell für eine Eigenschaft einer Resource. +Mit einem Traits können Zustände auf einer Resource geändert werden. + +TODO +===== +Es kann mehrere Traits pro Resource gebenb + +.. toctree:: + claimable.md + powerable.md + doorable.md + lockable.md + checkable.md + locatable.md \ No newline at end of file diff --git a/source/index.rst b/source/index.rst index 5fccedb..3a3cac5 100644 --- a/source/index.rst +++ b/source/index.rst @@ -19,3 +19,4 @@ We will inform you about breaking changes over our Zulip. Please subscript to it installation/installation.rst configuration/configuration.rst usage/usage.rst + concepts/concepts.rst From 14c71e1f39049b817714e3a0f96efda892e40f8e Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Mon, 13 May 2024 12:56:12 +0200 Subject: [PATCH 55/60] Added: concepts --- source/concepts/claims.de.md | 22 +++ source/concepts/claims.en.md | 22 +++ source/concepts/claims.md | 16 -- source/concepts/concepts.rst | 4 +- source/concepts/measurements.de.md | 6 + source/concepts/measurements.md | 2 - source/concepts/projects.de.md | 6 + source/concepts/projects.md | 2 - source/concepts/resourcenraum.md | 264 ++++++++++++++++++++++++++++ source/concepts/terminals.de.md | 6 + source/concepts/terminals.md | 2 - source/concepts/traits/checkable.md | 2 +- source/concepts/traits/claimable.md | 4 +- source/concepts/traits/doorable.md | 5 +- source/concepts/traits/locatable.md | 4 +- source/concepts/traits/lockable.md | 16 -- source/concepts/traits/lockers.md | 18 ++ source/concepts/traits/powerable.md | 2 +- source/concepts/traits/traits.rst | 12 +- source/index.rst | 11 +- 20 files changed, 367 insertions(+), 59 deletions(-) create mode 100644 source/concepts/claims.de.md create mode 100644 source/concepts/claims.en.md delete mode 100644 source/concepts/claims.md create mode 100644 source/concepts/measurements.de.md delete mode 100644 source/concepts/measurements.md create mode 100644 source/concepts/projects.de.md delete mode 100644 source/concepts/projects.md create mode 100644 source/concepts/resourcenraum.md create mode 100644 source/concepts/terminals.de.md delete mode 100644 source/concepts/terminals.md delete mode 100644 source/concepts/traits/lockable.md create mode 100644 source/concepts/traits/lockers.md diff --git a/source/concepts/claims.de.md b/source/concepts/claims.de.md new file mode 100644 index 0000000..bc5a243 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/source/concepts/claims.en.md b/source/concepts/claims.en.md new file mode 100644 index 0000000..d4f157b --- /dev/null +++ b/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. \ No newline at end of file diff --git a/source/concepts/claims.md b/source/concepts/claims.md deleted file mode 100644 index 6edd66d..0000000 --- a/source/concepts/claims.md +++ /dev/null @@ -1,16 +0,0 @@ -# Claims -Ein Claim ist eine Zugang zu einer Resource um deren dynamischen Zustand zu ändern. Claims können dabei auch von mehreren Nutzern gleichzeitig erhalten werden. -Claims enthalten Traits, welche eine Liste an Methoden ist, um den Zustand einer Resource zu ändern. -Um einen Claim auf eine Resource zu erhalten kann man entweder ein Claim der Resource selber beziehen oder sich auf eine Liste mit einem Interest eintragen, welche als Queue abgearbeitet wird, sobald eine Resource disowned wird. - -Ein Interest bildet das Anmeleden eines Interesses an einer Resource beim Server an. Ein Interest ist hierbei verbindlich, sollte also ein Nutzer ein Interest auf eine Resource haben, dann wird ihm diese auch automatisch gegeben, sobald die Resource keinen Claim mehr hat. - -Um den Zustand einer Resource abzufragen kann auf eine Resource ein Notify geholt werden. Dieses Notify gibt den Zustand einer Resource zurück, also auch eine Möglichkeit auf einen Zustand zu einer Resource zu subscriben und Updates zu einer Änderung zu erhalten. - -Mit Claims sollen die verschienden Eigenschaften einer Resource abgebildet werden ohne, dass der Server das Konzept des Verleihens jedes mal neu Implementieren muss. - -Eine weitere Möglichkeit einen Claim zu erhalten ist über ein Transfer eines Claims. Hierbei holt sich der erste Nutzer ein Token, über transfer(), welches er per QR-Code oder NFC an einen zweiten Nutzer weitergibt. Dieser kann dann den Claim übernehmen, wenn er das Token beim Server einlöst. Dabei ist zu beachten, dass der übernehmende Nuter auch über die Berechtigung verfügen muss die Resource leihen zu dürfen. - -Die letzte Möglichkeit einen Claim zu erhalten ist in dem ein Ausbilder lend() auf dem Claim aufruft und ein Token erhält, welches er einer Auszubildenen übergibt. Dieser kann dann auch die Maschine nutzen, wenn er nicht die erforderliche Berechtigung hat. Dabei erhält nach erfolgreicher einlösung des Tokens der Ausbilder einen Interest, mit welchem er den Claim zurückfordern kann. Dieses Konzept kann recursiv angewendet werden. Bei einem Lend bleibt der übergeber des Tokens in Verantwortung, im gegensatz zum Transfer, in dem er die Verantwortung abgibt. - -# TODO diff --git a/source/concepts/concepts.rst b/source/concepts/concepts.rst index da463bf..a3102c5 100644 --- a/source/concepts/concepts.rst +++ b/source/concepts/concepts.rst @@ -1,9 +1,7 @@ Concepts of FabAccess ================= -FabAccess nutzt mehrer Konzept um den Process des Verleihens nutzbar zu machen. Und an den benötigten Stellen Freiheiten zugeben, um Anpassungen vornehmen zu können. - - +FabAccess utilizes several key concepts to facilitate the process of resource allocation and provide flexibility where needed to accommodate customization. .. toctree:: claims.md diff --git a/source/concepts/measurements.de.md b/source/concepts/measurements.de.md new file mode 100644 index 0000000..99dd3b4 --- /dev/null +++ b/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!** \ No newline at end of file diff --git a/source/concepts/measurements.md b/source/concepts/measurements.md deleted file mode 100644 index 2d5259d..0000000 --- a/source/concepts/measurements.md +++ /dev/null @@ -1,2 +0,0 @@ -# Measurements -Messwerte von Resourcen \ No newline at end of file diff --git a/source/concepts/projects.de.md b/source/concepts/projects.de.md new file mode 100644 index 0000000..71fd380 --- /dev/null +++ b/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!** \ No newline at end of file diff --git a/source/concepts/projects.md b/source/concepts/projects.md deleted file mode 100644 index a0904ec..0000000 --- a/source/concepts/projects.md +++ /dev/null @@ -1,2 +0,0 @@ -# Projects -Claims mit einem Verweis auf Projekte beim Leihen von Resourcen \ No newline at end of file diff --git a/source/concepts/resourcenraum.md b/source/concepts/resourcenraum.md new file mode 100644 index 0000000..8910317 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/source/concepts/terminals.de.md b/source/concepts/terminals.de.md new file mode 100644 index 0000000..9c97055 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/source/concepts/terminals.md b/source/concepts/terminals.md deleted file mode 100644 index f721ec0..0000000 --- a/source/concepts/terminals.md +++ /dev/null @@ -1,2 +0,0 @@ -# Terminals -Eingeschränkte Nutzung von Resourcen bei Ausleih Terminals \ No newline at end of file diff --git a/source/concepts/traits/checkable.md b/source/concepts/traits/checkable.md index 3d3b3b3..c997aa1 100644 --- a/source/concepts/traits/checkable.md +++ b/source/concepts/traits/checkable.md @@ -1,5 +1,5 @@ # Checkable -Trait welcher den Zustand von Resourcen abbildet, welche eine Überprüfung nach einer Nutzung benötigen. +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` diff --git a/source/concepts/traits/claimable.md b/source/concepts/traits/claimable.md index 7b7f4a2..b348c87 100644 --- a/source/concepts/traits/claimable.md +++ b/source/concepts/traits/claimable.md @@ -1,5 +1,7 @@ # Claimable -Sonderfall um den Status des Claims anbieten zu können. +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` \ No newline at end of file diff --git a/source/concepts/traits/doorable.md b/source/concepts/traits/doorable.md index 7524cc3..add5eb8 100644 --- a/source/concepts/traits/doorable.md +++ b/source/concepts/traits/doorable.md @@ -1,5 +1,5 @@ # Doorable -Grundlegender Traits zum Ansteuern von Türen. +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` @@ -12,5 +12,6 @@ stateDiagram OPEN --> CLOSED: lock CLOSED --> tempOPEN: unlocktemp tempOPEN --> OPEN: unlock - tempOPEN --> CLOSED + tempOPEN --> CLOSED: lock + tempOPEN --> CLOSED: AUTO ``` \ No newline at end of file diff --git a/source/concepts/traits/locatable.md b/source/concepts/traits/locatable.md index 0c9c65e..666c128 100644 --- a/source/concepts/traits/locatable.md +++ b/source/concepts/traits/locatable.md @@ -1,5 +1,5 @@ # Locatable -Grundlegender Trait zum Auffinden von Resourcen +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` @@ -11,5 +11,5 @@ stateDiagram IDLE --> ACTIVE: setActive IDLE --> ACTIVE: identify ACTIVE --> IDLE: setIdle - ACTIVE --> IDLE + ACTIVE --> IDLE: AUTO ``` \ No newline at end of file diff --git a/source/concepts/traits/lockable.md b/source/concepts/traits/lockable.md deleted file mode 100644 index 3b07e75..0000000 --- a/source/concepts/traits/lockable.md +++ /dev/null @@ -1,16 +0,0 @@ -# Lockers -Traits zum Abbilden von Schlössern - -## OID -`1.3.6.1.4.1.61783.612.1.4` - -## States -```mermaid -stateDiagram - [*] --> locked - locked --> unlocked: unengage - unlocked --> locked - unlocked --> open - open --> unengaged - unengaged --> locked: engage - unengaged --> open \ No newline at end of file diff --git a/source/concepts/traits/lockers.md b/source/concepts/traits/lockers.md new file mode 100644 index 0000000..8fdfb83 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/source/concepts/traits/powerable.md b/source/concepts/traits/powerable.md index 0cdf096..0c204b1 100644 --- a/source/concepts/traits/powerable.md +++ b/source/concepts/traits/powerable.md @@ -1,5 +1,5 @@ # Powerable -Grundlegender Trait, welcher Resourcen einschalten kann. +"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` diff --git a/source/concepts/traits/traits.rst b/source/concepts/traits/traits.rst index 175161b..170e669 100644 --- a/source/concepts/traits/traits.rst +++ b/source/concepts/traits/traits.rst @@ -1,17 +1,17 @@ Traits ================= +Traits bieten die Möglichkeit, den Zustand von Ressourcen zu ändern. Ressourcen können mehrere Traits besitzen und diese kombiniert nutzen. -Traits sind Implementierung speziell für eine Eigenschaft einer Resource. -Mit einem Traits können Zustände auf einer Resource geändert werden. +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. -TODO -===== -Es kann mehrere Traits pro Resource gebenb +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 - lockable.md + lockers.md checkable.md locatable.md \ No newline at end of file diff --git a/source/index.rst b/source/index.rst index 3a3cac5..0b5b05b 100644 --- a/source/index.rst +++ b/source/index.rst @@ -3,19 +3,20 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to FabAccess documentation! +Welcome to FabAccess ====================================== -FabAccess is still in a state of development and has no stable Release. +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. -So there is no stability and backward compatibility between the versions. -Feel free to help us testing our software stack but not expect a full functional software. -We will inform you about breaking changes over our Zulip. Please subscript to it to stay up to date, because the server and client can get incompatible. +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: 1 :caption: Contents: + concepts/concepts.rst installation/installation.rst configuration/configuration.rst usage/usage.rst From c35f7b560f36bebbf72c6a7925f3575264c3484d Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Mon, 13 May 2024 13:00:03 +0200 Subject: [PATCH 56/60] Added: mkdocs example --- .gitignore | 129 +++++++++++++++++++++++++++++++++++++++++- .readthedocs.yaml | 20 +++++++ CONTRIBUTE.md | 91 ----------------------------- Makefile | 24 -------- docs/api.md | 3 + docs/index.md | 15 +++++ docs/requirements.in | 3 + docs/requirements.txt | 66 +++++++++++++++++++++ docs/usage.md | 34 +++++++++++ make.bat | 35 ------------ mkdocs.yml | 16 ++++++ 11 files changed, 285 insertions(+), 151 deletions(-) create mode 100644 .readthedocs.yaml delete mode 100644 CONTRIBUTE.md delete mode 100644 Makefile create mode 100644 docs/api.md create mode 100644 docs/index.md create mode 100644 docs/requirements.in create mode 100644 docs/requirements.txt create mode 100644 docs/usage.md delete mode 100644 make.bat create mode 100644 mkdocs.yml diff --git a/.gitignore b/.gitignore index 88c089c..b6e4761 100644 --- a/.gitignore +++ b/.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/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..d9222bb --- /dev/null +++ b/.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.10" + +mkdocs: + configuration: mkdocs.yml + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements.txt diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md deleted file mode 100644 index 74362d8..0000000 --- a/CONTRIBUTE.md +++ /dev/null @@ -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 python-sphinx_rtd_theme python-recommonmark``` -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 - diff --git a/Makefile b/Makefile deleted file mode 100644 index 9592445..0000000 --- a/Makefile +++ /dev/null @@ -1,24 +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) - -serve: - @$(MAKE) html - cd $(BUILDDIR)/html && python -m http.server - -.PHONY: help serve 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) diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..24b0824 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,3 @@ +# API Reference + +::: lumache diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..d489af8 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,15 @@ +{!README.md!} + +# Welcome to Lumache's documentation! + +**Lumache** (/lu\'make/) is a Python library for cooks and food lovers +that creates recipes mixing random ingredients. It pulls data from the +[Open Food Facts database](https://world.openfoodfacts.org/) and offers +a *simple* and *intuitive* API. + +Check out the [usage](usage) section for further information, including how to [install](usage#installation) the project. + +!!! note + + This project is under active development. + diff --git a/docs/requirements.in b/docs/requirements.in new file mode 100644 index 0000000..bec300c --- /dev/null +++ b/docs/requirements.in @@ -0,0 +1,3 @@ +mkdocs +mkdocstrings[python] +markdown-include diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..f6cb652 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,66 @@ +# +# 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 +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==6.0 + # 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 diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..efd1a2a --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,34 @@ +Usage +===== + +Installation +------------ + +To use Lumache, first install it using pip: + +```console +(.venv) $ pip install lumache +``` + +Creating recipes +---------------- + +To retrieve a list of random ingredients, you can use the +`lumache.get_random_ingredients()` function: + +::: lumache.get_random_ingredients + options: + show_root_heading: true + +
+ +The `kind` parameter should be either `"meat"`, `"fish"`, or `"veggies"`. +Otherwise, [`get_random_ingredients`][lumache.get_random_ingredients] will raise an exception [`lumache.InvalidKindError`](/api#lumache.InvalidKindError). + +For example: + +```python +>>> import lumache +>>> lumache.get_random_ingredients() +['shells', 'gorgonzola', 'parsley'] +``` diff --git a/make.bat b/make.bat deleted file mode 100644 index 6247f7e..0000000 --- a/make.bat +++ /dev/null @@ -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 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..2a5a12e --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,16 @@ +site_name: Basic MkDocs Example Project +theme: + name: readthedocs + highlightjs: true +plugins: + - search + - mkdocstrings: + handlers: + # See: https://mkdocstrings.github.io/python/usage/ + python: + options: + docstring_style: sphinx +markdown_extensions: + - markdown_include.include: + base_path: . + - admonition From 39284576d012db5675e271d431c4a77d5c055712 Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Mon, 13 May 2024 13:05:39 +0200 Subject: [PATCH 57/60] Fixed: OS Error --- .readthedocs.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index d9222bb..37ceb77 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,10 +6,10 @@ version: 2 # Set the version of Python and other tools you might need -# build: -# os: ubuntu-22.04 -# tools: -# python: "3.10" +build: + os: ubuntu-22.04 + tools: + python: "3.12" mkdocs: configuration: mkdocs.yml From df39998064b5a656a8e12b05c0d6f6fc4f3edf35 Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Mon, 13 May 2024 13:09:31 +0200 Subject: [PATCH 58/60] Fixed Exampl --- docs/api.md | 1 - docs/index.md | 11 ----------- docs/usage.md | 31 ------------------------------- 3 files changed, 43 deletions(-) diff --git a/docs/api.md b/docs/api.md index 24b0824..ecbc0fb 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,3 +1,2 @@ # API Reference -::: lumache diff --git a/docs/index.md b/docs/index.md index d489af8..1df4d0b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,14 +2,3 @@ # Welcome to Lumache's documentation! -**Lumache** (/lu\'make/) is a Python library for cooks and food lovers -that creates recipes mixing random ingredients. It pulls data from the -[Open Food Facts database](https://world.openfoodfacts.org/) and offers -a *simple* and *intuitive* API. - -Check out the [usage](usage) section for further information, including how to [install](usage#installation) the project. - -!!! note - - This project is under active development. - diff --git a/docs/usage.md b/docs/usage.md index efd1a2a..5aee3e3 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,34 +1,3 @@ Usage ===== -Installation ------------- - -To use Lumache, first install it using pip: - -```console -(.venv) $ pip install lumache -``` - -Creating recipes ----------------- - -To retrieve a list of random ingredients, you can use the -`lumache.get_random_ingredients()` function: - -::: lumache.get_random_ingredients - options: - show_root_heading: true - -
- -The `kind` parameter should be either `"meat"`, `"fish"`, or `"veggies"`. -Otherwise, [`get_random_ingredients`][lumache.get_random_ingredients] will raise an exception [`lumache.InvalidKindError`](/api#lumache.InvalidKindError). - -For example: - -```python ->>> import lumache ->>> lumache.get_random_ingredients() -['shells', 'gorgonzola', 'parsley'] -``` From f90018a31d051ce2c13e1f27344685a9bb0818ab Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Mon, 13 May 2024 13:17:16 +0200 Subject: [PATCH 59/60] Change Pyyaml version --- docs/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index f6cb652..b1e9e01 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -52,7 +52,7 @@ pyparsing==3.0.9 # via packaging python-dateutil==2.8.2 # via ghp-import -pyyaml==6.0 +pyyaml==5.3.1 # via # mkdocs # pyyaml-env-tag From 62798c809bc77703f23425d3fa78f7e518c7824d Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Mon, 13 May 2024 13:54:41 +0200 Subject: [PATCH 60/60] Added: Translation --- .gitlab-ci.yml | 24 +++++++++++++++++++++++ .readthedocs.yaml | 2 +- README.md | 3 +-- docs/api.md | 3 +-- docs/index.de.md | 1 + docs/index.en.md | 1 + docs/index.md | 4 ---- docs/requirements.in | 3 --- mkdocs.yml | 17 +++++++++++++--- docs/requirements.txt => requirements.txt | 2 ++ 10 files changed, 45 insertions(+), 15 deletions(-) create mode 100644 .gitlab-ci.yml create mode 100644 docs/index.de.md create mode 100644 docs/index.en.md delete mode 100644 docs/index.md delete mode 100644 docs/requirements.in rename docs/requirements.txt => requirements.txt (96%) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml new file mode 100644 index 0000000..c892a4c --- /dev/null +++ b/.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 diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 37ceb77..0518481 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -17,4 +17,4 @@ mkdocs: # Optionally declare the Python requirements required to build your docs python: install: - - requirements: docs/requirements.txt + - requirements: requirements.txt diff --git a/README.md b/README.md index 770202d..70ad3e3 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ # fabaccess-docs Documentation for the fabaccess project. -You can find the rendered docs at: https://fab-access.readthedocs.io/ - +You can find the rendered docs at: https://fab-access.readthedocs.io/ or https://docs.fab-access.org diff --git a/docs/api.md b/docs/api.md index ecbc0fb..b2fad2e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,2 +1 @@ -# API Reference - +# API Reference \ No newline at end of file diff --git a/docs/index.de.md b/docs/index.de.md new file mode 100644 index 0000000..7ca4df7 --- /dev/null +++ b/docs/index.de.md @@ -0,0 +1 @@ +# Wilkommen DE \ No newline at end of file diff --git a/docs/index.en.md b/docs/index.en.md new file mode 100644 index 0000000..6e695ee --- /dev/null +++ b/docs/index.en.md @@ -0,0 +1 @@ +# Welcome EN \ No newline at end of file diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 1df4d0b..0000000 --- a/docs/index.md +++ /dev/null @@ -1,4 +0,0 @@ -{!README.md!} - -# Welcome to Lumache's documentation! - diff --git a/docs/requirements.in b/docs/requirements.in deleted file mode 100644 index bec300c..0000000 --- a/docs/requirements.in +++ /dev/null @@ -1,3 +0,0 @@ -mkdocs -mkdocstrings[python] -markdown-include diff --git a/mkdocs.yml b/mkdocs.yml index 2a5a12e..ade9902 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,7 +1,12 @@ -site_name: Basic MkDocs Example Project +site_name: FabAccess Documentation +# site_url: https://pages.gitlab.io/mkdocs +site_dir: public + theme: - name: readthedocs - highlightjs: true + name: material + palette: + primary: blue + plugins: - search - mkdocstrings: @@ -10,6 +15,12 @@ plugins: python: options: docstring_style: sphinx + - i18n: + default_language: en + languages: + en: English + de: Deutsch + markdown_extensions: - markdown_include.include: base_path: . diff --git a/docs/requirements.txt b/requirements.txt similarity index 96% rename from docs/requirements.txt rename to requirements.txt index b1e9e01..087b4e3 100644 --- a/docs/requirements.txt +++ b/requirements.txt @@ -44,6 +44,8 @@ mkdocstrings[python]==0.19.0 # 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