From 010e4019c35e773d2e5e227f9902d9e3a26fcb12 Mon Sep 17 00:00:00 2001
From: rschoene <rene.schoene@tu-dresden.de>
Date: Thu, 21 Jul 2022 18:12:20 +0200
Subject: [PATCH] more readme, initial artifact creation script, update cloc
---
.gitignore | 1 +
README.md | 48 ++++++++++++++++++++++++++++++++++++++--------
create-artifact.sh | 39 +++++++++++++++++++++++++++++++++++++
links.md | 28 +++++++++++++++++++++++++++
ros3rag | 2 +-
5 files changed, 109 insertions(+), 9 deletions(-)
create mode 100644 .gitignore
create mode 100644 create-artifact.sh
create mode 100644 links.md
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..bc6717c
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+/shared_directory_images/
diff --git a/README.md b/README.md
index 3f4eb4e..5518a86 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,40 @@
# Artifact for the paper "Incremental Causal Connection for Self-Adaptive Systems Based on Relational Reference Attribute Grammars"
-## Installation and Preparation
+## Installation and Preparation of the Case Study
To quickly run the graphical example applications, Docker is used.
Please note that the setup uses vnc and thus offers limited graphics performance.
- Install Docker and docker-compose for your system (for Windows and Mac OS, install Docker Desktop)
-- 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`
- - Change into the workspace `cd models2022`
- - Prepare/Build all docker images: `docker-compose build` (this will take a while)
+- For artifact evaluation:
+ - Unpack the provided archive
+ - Load the four docker images (they require around 6.7GB in total)
+ - `docker load models2022_web.tar`
+ - `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
+- 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`
+ - Change into the workspace `cd models2022`
+ - Prepare/Build all docker images: `docker-compose build` (this will take a while)
## Running the Case Study
- 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>`)
- `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)
- `docker-compose up ros_place_b1`
- `docker-compose up ros_place_b2`
- 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*"
+ - 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)
- 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
- <http://localhost:6081/> (First robot)
@@ -42,6 +54,26 @@ Please note that the setup uses vnc and thus offers limited graphics performance
## Experiment with RagConnect
--> Still TODO (update 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 and at <https://git-st.inf.tu-dresden.de/jastadd/ragconnect-minimal>.
-To experiment with a less complex scenario and verify the functionality of the tool RagConnect itself, you can use the minimal example provided at <https://git-st.inf.tu-dresden.de/jastadd/ragconnect-minimal>.
+## Verifying Results of the Publication
+
+Several important results can be checked for:
+
+### Feasability of the Case Study
+
+- 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
+
+- 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`
+- Or attach to a running container after starting the case study with docker-compose. To attach, run `docker-compose exec rag_place_b /bin/bash`.
+- In both cases, you should have a terminal in the directory `/ros3rag`
+- Change directory to the `cloc` subdirectory, `cd cloc`
+- Execute the script to show lines of code, `./run-cloc.sh`
+
+### Ratio of messages skipped
+
+- 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)
diff --git a/create-artifact.sh b/create-artifact.sh
new file mode 100644
index 0000000..47e0e0d
--- /dev/null
+++ b/create-artifact.sh
@@ -0,0 +1,39 @@
+#!/bin/bash
+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)
+
+## 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)
+
+## containered
+image_id_web=$(docker images --format="{{.Repository}} {{.ID}}" | grep models2022_web | head -n1 | cut -d' ' -f2)
+image_id_mosquitto=$(docker images --format="{{.Repository}} {{.ID}}" | grep eclipse-mosquitto | head -n1 | cut -d' ' -f2)
+image_id_rag=$(docker images --format="{{.Repository}} {{.ID}}" | grep models2022_rag_place_a | head -n1 | cut -d' ' -f2)
+image_id_ros=$(docker images --format="{{.Repository}} {{.ID}}" | grep models2022_ros_place_b1 | head -n1 | cut -d' ' -f2)
+
+docker save ${image_id_web} > models2022_web.tar
+docker save ${image_id_mosquitto} > models2022_mosquitto.tar
+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/
+
+## bundle everything together
+zip models2022 \
+ workspace.tar \
+ ragconnect.tar \
+ ragconnect_pages.tar \
+ minimal_example.tar \
+ minimal_example_pages.tar \
+ models2022_web.tar \
+ models2022_mosquitto.tar \
+ models2022_rag_place.tar \
+ models2022_ros_place.tar \
+ README.md \
+ links.md
diff --git a/links.md b/links.md
new file mode 100644
index 0000000..10b0ba8
--- /dev/null
+++ b/links.md
@@ -0,0 +1,28 @@
+# The tool RagConnect
+
+Repository: <https://git-st.inf.tu-dresden.de/jastadd/ragconnect>
+
+Documentation: <https://jastadd.pages.st.inf.tu-dresden.de/ragconnect> (master) and <https://jastadd.pages.st.inf.tu-dresden.de/ragconnect-dev> (dev)
+
+# Minimal Examples
+
+Repository: <https://git-st.inf.tu-dresden.de/jastadd/ragconnect-minimal>
+
+Documentation: <https://jastadd.pages.st.inf.tu-dresden.de/ragconnect-minimal>
+
+# Case Study of the Paper ("ros3rag")
+
+Repositories
+- RAG part: <https://git-st.inf.tu-dresden.de/jastadd/ros3rag>
+- ROS parts: <https://git-st.inf.tu-dresden.de/ceti/ros/ccf>
+- Complete workspace: <https://git-st.inf.tu-dresden.de/ceti/ros/models2022>
+
+# Other Used Tools
+
+Visualization of Grammar: <https://jastadd.pages.st.inf.tu-dresden.de/grammar2uml/>
+
+Visualization of AST: <https://jastadd.pages.st.inf.tu-dresden.de/relast2uml/>
+
+RelAST: <https://jastadd.pages.st.inf.tu-dresden.de/relational-rags/>
+
+JastAdd: <http://jastadd.org/>
diff --git a/ros3rag b/ros3rag
index 7eab3ff..c9ce9ae 160000
--- a/ros3rag
+++ b/ros3rag
@@ -1 +1 @@
-Subproject commit 7eab3ff6f337970ceb2d345a2ac1c5ebf8231e02
+Subproject commit c9ce9aea2c0a9ce1c37a46b7864f216447b4c15d
--
GitLab