From 1cfe9e96e7a64e4a0da27f1f33c6033d5f82e97c Mon Sep 17 00:00:00 2001
From: rschoene <rene.schoene@tu-dresden.de>
Date: Fri, 22 Jul 2022 10:53:44 +0200
Subject: [PATCH] first version of artifact

---
 .gitattributes     |  1 +
 .gitignore         |  1 +
 README.md          | 43 ++++++++++++++++++++++++++++++-------------
 create-artifact.sh | 13 +++++++------
 models2022.zip     |  3 +++
 5 files changed, 42 insertions(+), 19 deletions(-)
 create mode 100644 .gitattributes
 mode change 100644 => 100755 create-artifact.sh
 create mode 100644 models2022.zip

diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..8b2889f
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1 @@
+models2022.zip filter=lfs diff=lfs merge=lfs -text
diff --git a/.gitignore b/.gitignore
index bc6717c..fccfa98 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 /shared_directory_images/
+!models2022.zip
diff --git a/README.md b/README.md
index 5518a86..8754148 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ Please note that the setup uses vnc and thus offers limited graphics performance
         - `docker load models2022_mosquitto.tar`
         - `docker load models2022_rag_place.tar`
         - `docker load models2022_ros_place.tar`
-    - Unpack the archive `workspace.tar`. It contains all (remaining) necessary parts for the docker-compose-build
+    - Create a new directory `models2022` and unpack the archive `workspace.tar` there. It contains all (remaining) necessary parts for the docker-compose build
 - For all others:
     - Clone this repo and its submodules (**Important**: Use `--recurse-submodules`):
         - `git clone --recurse-submodules https://git-st.inf.tu-dresden.de/ceti/ros/models2022.git models2022`
@@ -24,37 +24,50 @@ Please note that the setup uses vnc and thus offers limited graphics performance
 
 - Start the following containers (best to use different terminal tabs/windows):
     - `docker-compose up web`
-        - You should see a log output, that connection to MQTT was successful (`Connected to mosquitto at <datetime>`)
+        - You should see a log output, that connection to MQTT was successful (`Connected to mosquitto at <datetime>`). Otherwise, check that the docker-compose service `mosquitto` is up and running (it should start automatically once the service `web` is started)
     - `docker-compose up rag_place_a`
     - `docker-compose up rag_place_b`
         - There will some log output, and a final `Published some bytes to coordinating/rag-a/status` (or `coordinating/rag-a/status` for place B)
+        - The coordinator described in the paper is not included in this artifact, as running it as a docker container prohibits it from starting other docker containers easily. Thus, the coordinating commands to start the applications have to be sent manually (described later).
     - `docker-compose up ros_place_b1`
     - `docker-compose up ros_place_b2`
+        - This will only start the desktop environment(s) and not (yet) the robotic controller(s)
 - Open the Web-UI for the RAG application
     - <http://localhost:8050/>
     - This UI offers various controls (only a few are needed to control the case study), a filtered MQTT log, and a second tab to view the runtime model (see below)
-    - Start the RAG application for place B, hit "Start" in the (rightmost) section "*Commands Place B*".
-        - It is important, that the RAG application of place B is started *before* the scripts (`run1.sh` and `run2.sh`, see below) that start the two robots (The robotic controllers send their initial scene only once, and without receiving it, the RAG application is missing information about the objects in place B)
+    - Start the RAG application for place B, hit "Start" in the section "*Commands Place B*".
+        - It is important, that the RAG application of place B is started *before* the robotic controllers (`run1.sh` and `run2.sh`, see below). The robotic controllers send their initial scene only once, and without receiving it, the RAG application is missing information about the objects in place B.
     - You should then see a message with "ready" for the topic "coordinating/rag-b/status" (in a line like `[<datetime> @ coordinating/rag-b/status ] ready`)
-- Open VNC using your browser to start the two robots
+- Open VNC using your browser to start the two robotic controllers
     - <http://localhost:6081/> (First robot)
     - <http://localhost:6082/> (Second robot)
     - You should see a desktop environment with four desktop entries
     - Right-click on "ros_ws" desktop entry -> "Open in terminal". A terminal window should open in directory "~/Desktop"
-    - Start the controller using either `./run1.sh` (for the first robot) or `./run2.sh` (for the second robot)
+    - Start the controller using `./run1.sh` (for the first robot) and `./run2.sh` (for the second robot)
     - You should see some log output in the terminal and the visualization program (RViz) for the respective robot should open
 - Back in the Web-UI for the RAG application
     - You should see messages for the topics `/ceti_cell_placeworld/scene/update` and `/ceti_cell_placeworld2/scene/update`
-    - Start the RAG application for place A, hit "Start" in the (middle) section "*Commands Place A*"
+    - Start the RAG application for place A, hit "Start" in the section "*Commands Place A*"
     - Then the case study begins, you should see a "ready" for the topic "coordinating/rag-a/status" and the first commands sent. Also the two robots should start to move executing their command. From then on, observe the mqtt messages sent and/or the robots moving
+    - The complete case study takes about ??:?? min to finish
 - View the RAG runtime model
     - While the case study runs or after it is finished, you can view the runtime state in the tab named "*SVG Model B*"
     - After starting the RAG application for place B, the initial state is displayed
-    - To "request" a new model, hit the button "Model" in section "*Commands Place B*". This will both print the model (in the lower MQTT log) and create a visualization shown in the tab "*SVG Model B*"
+    - To "request" a new model, hit the button "Model" in section "*Commands Place B*". This will both print the model (in the lower MQTT log) and create a visualization shown in the tab "*SVG Model B*". Only the latest model will be visible in the tab "*SVG Model B*"
 
-## Experiment with RagConnect
+## Documentation in the archive
 
-To experiment with a less complex scenario and verify the functionality of the tool RagConnect itself, you can use the minimal example provided in the archive and at <https://git-st.inf.tu-dresden.de/jastadd/ragconnect-minimal>.
+For the minimal example and for the tool RagConnect, the documentation pages have been included in the archive.
+To view them, extract the archive (`minimal_example_pages.tar` or `ragconnect_pages.tar`) and start a local webserver in the extract directory `public` to view them (for single pages a browser is sufficient, but for navigation a webserver is recommended).
+As an example, a simple webserver is part of the Python installation and can be started using `python -m SimpleHTTPServer 8000` (Python 2) or `python3 -m http.server` (Python 3).
+Alternatively, you can view the documentation online using provided in `links.md`.
+
+## Experiment with RagConnect Minimal Example
+
+To experiment with a less complex scenario and verify the functionality of the tool RagConnect itself, you can use the minimal example provided in the archive `minimal_example.tar` and at <https://git-st.inf.tu-dresden.de/jastadd/ragconnect-minimal>.
+It is not dockerized, and requires a Java VM (tested with version 11) to run.
+
+Execute `./gradlew run` to start and choose one of the three demos by typing 1, 2, or 3 (and hitting Enter). Please refer to the documentation (in the archive `minimal_example_pages.tar` or at <https://jastadd.pages.st.inf.tu-dresden.de/ragconnect-minimal>).
 
 ## Verifying Results of the Publication
 
@@ -64,7 +77,7 @@ Several important results can be checked for:
 
 - By executing the case study, and seeing the robots move in the correct manner and order, one can verify that the RAG application computes and sends the correct commands, and (indirectly) that the causal connections update the model correctly
 
-### Lines of code
+### Lines of code of the Case Study
 
 - There is a script using `cloc` to get LOC numbers.
 - Either start a new container with the image of a RAG place, e.g., `docker run --rm -it models2022_rag_place_b /bin/bash`
@@ -73,7 +86,11 @@ Several important results can be checked for:
 - Change directory to the `cloc` subdirectory, `cd cloc`
 - Execute the script to show lines of code, `./run-cloc.sh`
 
-### Ratio of messages skipped
+### Ratio of messages skipped in the Case Study
 
 - When running the case study, every time the model of place B is requested (by hitting the button "Model" in the rightmost section "*Commands Place B*"), information about the processing of received and sent messages is shown as "evaluationCounters" in form of a csv file
-- After those information, the ratio is also printed (the ration between the sum of all skipped messages and the sum of all processed messages)
+- After those information, the ratio is also printed (the ratio between the sum of all skipped messages and the sum of all processed messages)
+
+### Feasability of the tool RagConnect
+
+Using the provided minimal example, the functionality of the tool RagConnect and its functionality can be assessed for the given and for new input specifications.
diff --git a/create-artifact.sh b/create-artifact.sh
old mode 100644
new mode 100755
index 47e0e0d..75fd253
--- a/create-artifact.sh
+++ b/create-artifact.sh
@@ -1,14 +1,15 @@
 #!/bin/bash
+set -e
+set -x
 my_directory=$(pwd -P)
-conda activate mypython3
 
 ## ragconnect
-(cd ~/git/jastadd/ragconnect && git archive > ${my_directory}/ragconnect.tar)
-(cd ~/git/jastadd/ragconnect/pages && mkdocs build && tar cf ${my_directory}/ragconnect_pages.tar ../public)
+( cd ~/git/jastadd/ragconnect && git archive -o ${my_directory}/ragconnect.tar dev )
+( cd ~/git/jastadd/ragconnect/pages && mkdocs build && tar cf ${my_directory}/ragconnect_pages.tar ../public/* )
 
 ## minimal example
-(cd ~/git/jastadd/minimal-ragconnect && git archive > ${my_directory}/minimal_example.tar)
-(cd ~/git/jastadd/minimal-ragconnect/pages && mkdocs build && tar cf ${my_directory}/minimal_example_pages.tar ../public)
+( cd ~/git/jastadd/minimal-ragconnect && git archive -o ${my_directory}/minimal_example.tar master )
+( cd ~/git/jastadd/minimal-ragconnect/pages && mkdocs build && tar cf ${my_directory}/minimal_example_pages.tar ../public/* )
 
 ## containered
 image_id_web=$(docker images --format="{{.Repository}} {{.ID}}" | grep models2022_web | head -n1 | cut -d' ' -f2)
@@ -22,7 +23,7 @@ docker save ${image_id_rag} > models2022_rag_place.tar
 docker save ${image_id_ros} > models2022_ros_place.tar
 
 ## this workspace
-tar cf workspace.tar docker-compose.yml config/* robotic-controller/vnc/* shared_directory_images/
+tar cf workspace.tar docker-compose.yml config/* robotic-controller/vnc/* shared_directory_images
 
 ## bundle everything together
 zip models2022 \
diff --git a/models2022.zip b/models2022.zip
new file mode 100644
index 0000000..1d22c5b
--- /dev/null
+++ b/models2022.zip
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e8fe55c5be75e85127c548c7e73a2e3534065b177f302e49e1a7cc6ed382e178
+size 2580994231
-- 
GitLab