update submodules, use coordinator, update readme

README.md

 # Artifact for the paper "Incremental Causal Connection for Self-Adaptive Systems Based on Relational Reference Attribute Grammars"
 
+Also available at <https://www.doi.org/10.5281/zenodo.6881226>.
+
 ## Installation and Preparation of the Case Study
 
 To quickly run the graphical example applications, Docker is used.
@@ -8,36 +10,62 @@ 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)
 - 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`
-    - Create a new directory `models2022` and unpack the archive `workspace.tar` there. It contains all (remaining) necessary parts for the docker-compose build
+    - Load the five docker images (they require around 7GB in total)
+        - `docker load -i models2022_web.tar`
+        - `docker load -i models2022_mosquitto.tar`
+        - `docker load -i models2022_rag_place.tar`
+        - `docker load -i models2022_coordinator.tar`
+        - `docker load -i models2022_ros_place.tar`
+    - Verify, that the docker images have loaded correctly by running `docker images` and check for the four names `models2022_rag_place`, `models2022_coordinator`, `models2022_ros_place`, `models2022_web` and `eclipse-mosquitto` (all with tag `latest`)
+    - Create a new directory `models2022` and unpack the archive `workspace.tar` there. It contains all (remaining) necessary parts for the docker-compose build. Please ensure, that there are empty directories `ros3rag`, `web-ros3rag` and `coordinator`. Otherwise docker-compose will produce an error.
 - 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)
 
+## Description of the Expected Outcome of the Case Study
+
+This case study showcases two systems (sites).
+Site A as a self-aware virtual environment and site B as a self-adaptive robotic system.
+Site A has a runtime model causally connected to the virtual environment in which the human operator performs pick-and-place tasks.
+**In this demonstrator** site A has a fixed goal state (that some human operator might have once defined).
+Site B has a runtime model causally connected to the physical robot arms and the movable objects.
+Additionally, site A and B are causally connected, too.
+All causal connections are realized using our approach, as depicted in fig. 5 in the paper.
+
+This case study involves multiple industrial robot arms collaborating to move items to positions defined in site A.
+Both sites A and B contain movable objects and regions identified by some id, and described by pose (position, rotation) and size.
+The relative spatial positions of regions at site A do not have to match those in site B; in fact, site A might look vastly different from site B.
+
+**In this demonstrator** all blue object are to be moved together in a small region that can only have two objects inside it, and all green and red objects must be moved to some region around the second robot.
+As some (green and red) object are near the first robot, both robots need to collaborate to move them to their goal region.
+The collaboration is secured by a collaboration zone, in which only one robot can operate at a time.
+This is shown by the transparent orange box between the two robots, which "blocks" the robot from entering the collaboration zone.
+In other words, if the box is not visible, the robot is allowed to enter.
+This is controlled by the runtime model.
+
 ## 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>`). Otherwise, check that the docker-compose service `mosquitto` is up and running (it should start automatically once the service `web` is started)
+        - **Note**: Please avoid refreshing the web UI (e.g., by pressing F5 or Cmd+R), as all intermediate state is lost in that case
+    - `docker-compose up coordinator`
     - `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).
+        - There will some log output, and a final `Published some bytes to coordinating/rag-a/status` for place A
+        - Place B should start right away, because the coordinator will send a start message to it, thus the last message should be `coordinating/rag-b/status ready`
+        - The coordinator described in the paper is included in this artifact, but with limited capabilities as running it as a docker container prohibits it from starting other docker containers easily. The coordinator must be started before all `rag*` and `ros*` places.
     - `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 section "*Commands Place B*".
+    - **Just in case the coordinator is not working, skip otherweise:** 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`)
+        - 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 robotic controllers
     - <http://localhost:6081/> (First robot)
     - <http://localhost:6082/> (Second robot)
@@ -45,29 +73,34 @@ Please note that the setup uses vnc and thus offers limited graphics performance
     - Right-click on "ros_ws" desktop entry -> "Open in terminal". A terminal window should open in directory "~/Desktop"
     - 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`
+    - In RViz you can set the "Frame rate" from the configured "30" to some lower value (e.g., "5") in order to lower CPU utilization. The main window of RViz is divided into a left side with properties, and a right side with the simulated robot. On the left side under 'Displays -> Frame Rate' you can change the value by clicking the current value (e.g. 30), enter a new value and hitting Enter.
+    - Once both robotic controllers are up and running, the case study begins and you should see the first commands sent in the Web-UI for the RAG application. From then on, observe the mqtt messages sent and/or the robots moving
+- The complete case study takes about 3 min to finish
+- **Just in case the coordinator is not working, skip otherweise:** Back in the Web-UI for the RAG application
+    - You should see messages for the topics `/ceti_cell_placeworld/scene/update` and `/ceti_cell_2_placeworld/scene/update`
     - 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
+    - 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.
 - 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*". Only the latest model will be visible in the tab "*SVG Model B*"
 
-## Documentation in the archive
+## Documentation in the Archive
 
 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`.
+Alternatively, you can view the documentation online using the links 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.
+All three demos require a running MQTT broker on your machine (the application will abort if no connection is possible).
+We recommend [mosquitto](https://mosquitto.org/) as it is easy to set up.
 
-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>).
+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
 
@@ -94,3 +127,31 @@ Several important results can be checked for:
 ### 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.
+
+## FAQ
+
+### The SVG Model B tab never shows anything
+
+There are some possible sources of errors.
+
+(1) The RAG application fails to write the SVG.
+This would be visible as a Java exception in the log output of `docker-compose up rag_place_b`.
+The directory `/ros3rag/ros3rag.placeB/images` has to exist in the container and must be writeable.
+Fixing this is not easy, a possibility is to create a new Dockerfile based on `models2022_rag_place` and add `RUN mkdir /ros3rag/ros3rag.placeB/images` to create this directory manually there.
+
+(2) The SVG was written but is not readable for the web UI.
+Everytime an SVG is received, its original and rewritten path is logged for the container of `docker-compose up web`.
+As an alternative, you can manually view these images, since they reside on your host machine in the directory `shared_directory_images`.
+
+### Error: build path [...] either does not exist, is not accessible, or is not a valid URL
+
+When running `docker-compose`, it still tries to access the directories where the Dockerfiles are located.
+Therefore, at least these directories need to exist.
+Normally, they are included in the `workspace.tar`.
+If not, please create empty directories `ros3rag` and `web-ros3rag` as siblings of `docker-compose.yml`.
+
+### What are the supported OS/docker versions?
+
+We have tested the artifact on Unix and Windows with the standard `docker`, `docker-compose` and `Docker Desktop`.
+Other docker implementations like `podman` are known to have issues and are not supported.
+Using the repository directly on Windows, there may be issues with line-endings as within containers Unix line-endings are expected.

config/config-b-docker.yaml

-mqttHost: "mosquitto"
+mqttHost: "localhost"
 filenameRegions: "src/main/resources/regions-b-placeworld.json"
 forB:
   topicsSceneUpdate:

config/ros3rag.coordinator

 components {
-  component robotCtrlA,  start using docker compose "ros_place_a",  report using mqtt "ros-place-a",  status "ready" after 1 sec
-  component robotCtrlB1, start using docker compose "ros_place_b1", report using mqtt "ros-place-b1", status "ready" after 1 sec
-  component robotCtrlB2, start using docker compose "ros_place_b2", report using mqtt "ros-place-b2", status "ready" after 1 sec
-  component ragA,       start using script "./place.sh a" in "ros3rag", report using mqtt "coordinating/rag-a"
-
-  component ragB,       start using script "./place.sh b" in "ros3rag", report using mqtt "coordinating/rag-b"
-  //component ragB, report using mqtt "coordinating/rag-b"
-
-  component mosquitto,  start using docker compose "mosquitto", status "ready" after 1 sec
-
-  // mqtt broker needed for all robot ctrl and rag nodes
-  mosquitto < robotCtrlA, robotCtrlB, ragA, ragB
-
-  // robot control needs to start before rag
-  robotCtrlA < ragA
-  robotCtrlB < ragB
+  component rosB1, status "ready" if mqtt "/ceti_cell_placeworld/scene/update"
+  component rosB2, status "ready" if mqtt "/ceti_cell_2_placeworld/scene/update"
+  component ragA, report using mqtt "coordinating/rag-a"
+  component ragB, report using mqtt "coordinating/rag-b"
 
   // rag place B needs to start before rag place A
   ragB < ragA
+
+  // rag place A should wait for robotic controllers
+  rosB1, rosB2 < ragA
 }

coordinator @ d89b0660

-Subproject commit 634f0effcdd41edfaf14e69eb7759cbe25b2a29e
+Subproject commit d89b06603434dd1d6e47b53346ae0e18f3954033

create-artifact.sh

@@ -12,18 +12,15 @@ my_directory=$(pwd -P)
 ( 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
+docker save models2022_web:latest > models2022_web.tar
+docker save eclipse-mosquitto:latest > models2022_mosquitto.tar
+docker save models2022_rag_place:latest > models2022_rag_place.tar
+docker save models2022_coordinator:latest > models2022_coordinator.tar
+docker save models2022_ros_place:latest > 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/*
+tar rf workspace.tar --no-recursion shared_directory_images ros3rag web-ros3rag coordinator
 
 ## bundle everything together
 zip models2022 \
@@ -35,6 +32,7 @@ zip models2022 \
     models2022_web.tar \
     models2022_mosquitto.tar \
     models2022_rag_place.tar \
+    models2022_coordinator.tar \
     models2022_ros_place.tar \
     README.md \
     links.md

docker-compose.yml

 version: '3'
 services:
   ros_place_b1:
+    image: models2022_ros_place:latest
     build:
       context: robotic-controller
-      dockerfile: Dockerfile-vnc
+      dockerfile: Dockerfile-vnc-foo
     volumes:
       - "./ros_place_b1_logs/:/home/root/.ros/log"
     ports:
       - "6081:80"
 
   ros_place_b2:
+    image: models2022_ros_place:latest
     build:
       context: robotic-controller
       dockerfile: Dockerfile-vnc
@@ -19,6 +21,7 @@ services:
       - "6082:80"
 
   rag_place_a:
+    image: models2022_rag_place:latest
     build: ros3rag
     environment:
       - "TARGET=ros3rag.placeA"
@@ -27,6 +30,7 @@ services:
       - "./config/config-a-docker.yaml:/ros3rag/config-a-docker.yaml"
 
   rag_place_b:
+    image: models2022_rag_place:latest
     build: ros3rag
     environment:
       - "TARGET=ros3rag.placeB"
@@ -35,7 +39,16 @@ services:
       - "./shared_directory_images:/ros3rag/images"
       - "./config/config-b-docker.yaml:/ros3rag/config-b-docker.yaml"
 
+  coordinator:
+    image: models2022_coordinator:latest
+    build: coordinator
+    environment:
+      - "CONFIG_FILE=/coordinator/ros3rag.coordinator"
+    volumes:
+      - "./config/ros3rag.coordinator:/ros3rag.coordinator"
+
   web:
+    image: models2022_web:latest
     build: web-ros3rag
     volumes:
       - "./shared_directory_images:/shared_directory_images"
@@ -46,7 +59,7 @@ services:
       - mosquitto
 
   mosquitto:
-    image: eclipse-mosquitto
+    image: eclipse-mosquitto:latest
     container_name: mqtt
     restart: unless-stopped
     volumes:

ros3rag @ f82dfa0b

-Subproject commit c9ce9aea2c0a9ce1c37a46b7864f216447b4c15d
+Subproject commit f82dfa0b12cfb128e7a8a661694346970ef724bd

web-ros3rag @ aea32b90

-Subproject commit a82654a868d585be3b3b9af33d3c82c28bc216a8
+Subproject commit aea32b90b5ce5c0511d5244e4e6d8c0f18c4a406