From 46d10ea8029c6a42e6e1f0ba68a4a22668ef8027 Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Sat, 11 Dec 2021 18:35:43 +0100 Subject: [PATCH] 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