ros-wg-delib · ct2034 · Dec 6, 2024 · Dec 11, 2024 · Dec 11, 2024 · Dec 11, 2024
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
@@ -1,6 +1,5 @@
 name: Docker
 on:
-  pull_request:
   push:
     branches:
       - main

diff --git a/README.md b/README.md
@@ -3,6 +3,10 @@
 This repository contains materials for the [ROSCon 2024](https://roscon.ros.org/2024/) workshop on ROS 2 Deliberation Technologies.
 You can find the [slides here](https://drive.google.com/drive/folders/15H6QdkICynKpVlMn2Glz0ynS692LxZH8?usp=drive_link).
 
+__However, it is perfectly usable as a guided tutorial to learn all of the presented technologies at your own pace.__
+
+## Introduction to Robotic Deliberation
+
 Deliberation in robotics refers to the collection of technologies necessary to create highly capable autonomous robots.
 The key idea is the use of *models* of the robot and its environment to enable high-level decision-making for solving complex problems, as well as equipping robots with robust *skill representations* to successfully execute these tasks in the real world.
 
@@ -12,8 +16,6 @@ To learn more about deliberation, refer to [Ingrand and Ghallab (2017)](https://
 
 *Overview diagram of robot deliberation, [Ingrand and Ghallab (2017)](https://hal.science/hal-01137921)*
 
----
-
 ## Technology Overview
 
 In this hands-on workshop, you will get the opportunity to use a few ROS 2 enabled tools designed for robot deliberation.
@@ -27,8 +29,6 @@ Additionally, it can simulate failures and battery usage in the above actions.
 
 ![image](media/pyrobosim_world.png)
 
----
-
 ## Setup
 
 > [!NOTE]
@@ -45,7 +45,7 @@ You also need to have Docker and Docker Compose installed on your system.
 If you do not have these tools set up:
 
 * Install Docker Engine using [these instructions](https://docs.docker.com/engine/install/ubuntu/).
-  * **IMPORTANT:** Make sure you also go through the [Linux post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/).
+  * __IMPORTANT:__ Make sure you also go through the [Linux post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/).
 * Install Docker Compose using [these instructions](https://docs.docker.com/compose/install/).
 
 Once you are able to run `docker` and `docker compose` commands without `sudo`, you can move on to the installation steps below.
@@ -88,8 +88,6 @@ docker compose exec base bash
 
 > Note: This command must be executed from the `roscon24-workshop` repository folder.
 
----
-
 ## Developing in the Container
 
 By default, the whole ROS 2 workspace should have been built on setup.
@@ -108,14 +106,14 @@ When you are ready to shut down the container, enter the following command from
 docker compose down --remove-orphans
 ```
 
-**NOTE:** If you want to clean up any containers and colcon build artifacts mounted to your host system (in the `.colcon` folder of this repo), you can run the following command.
+__NOTE:__ If you want to clean up any containers and colcon build artifacts mounted to your host system (in the `.colcon` folder of this repo), you can run the following command.
 It will ask you for your `sudo` password.
 
 ```bash
 ./clean_environment.sh
 ```
 
-### Develop inside the container using VSCode
+### [optional] Use the Container as a Devcontainer
 
 If you want to develop inside the container using VSCode, you need to have the [Docker extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker) installed.
 To see the option "Attach Visual Studio Code", you also need to download the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
@@ -126,8 +124,10 @@ Attach to the container as shown in the image below:
 
 Once inside the container, open the folder `/delib_ws/src`.
 
----
-
 ## More information and troubleshooting
 
 Once you are all set up, refer to the [cheatsheet](./CHEATSHEET.md) for more information, including useful commands and troubleshooting steps.
+
+## Next steps
+
+If you are done with your setup and verified that everything is working, you can continue to learn about the [`problems`](./problems/README.md).
diff --git a/problems/README.md b/problems/README.md
@@ -1,12 +1,21 @@
 # Problems
 
-This folder contains all the initial files for the workshop.
+## Pre-requisites
+
+To run the problems, make sure you did the setup steps in the [main README](../README.md).
+
+## Introduction
+
+This folder contains all the files required to run the demo problems that will be used to try out the different deliberation tools.
 
 This includes the world models in [PyRoboSim](https://github.com/sea-bass/pyrobosim), and some simple Python abstractions for commanding simulated robots and retrieving their state.
 
-During this workshop, you will work through increasingly difficult problems as you become familiar with deliberation tools.
+The problems are designed to increase in complexity.
+While the first problem can be used to familiarize yourself with the repository setup in general, the later problems will be more complex.
+In particular, the later problems introduce the concept of battery usage and charging, as well as actions that can fail with some probability.
 
----
+When running the commands below, the PyRoboSim visualization will open up.
+You can use the PyRoboSim GUI to interact with the simulation and _play around_ to understand the problem setup and the actions available to you.
 
 ## Problem 1
 
@@ -26,8 +35,6 @@ Snacks in the kitchen pantry.
 * Place object
 * Move robot
 
----
-
 ## Problem 2
 
 ```bash
@@ -51,8 +58,6 @@ Hallways into the trash room are closed.
 * Open door
 * Close door
 
----
-
 ## Problem 3
 
 ```bash
@@ -79,8 +84,6 @@ Butter is in the fridge, which is closed.
 
 Actions may fail with some probability.
 
----
-
 ## Problem 4
 
 ```bash
@@ -113,3 +116,7 @@ Hallways into the trash room are closed.
 Actions may fail with some probability.
 
 Actions now use up battery, which can be fixed by navigating to the charger.
+
+## Next Steps
+
+After you have tried out the problems, you can move on to the [technologies](../technologies/README.md) folder to learn more about the available deliberation tools.
diff --git a/technologies/README.md b/technologies/README.md
@@ -1,26 +1,42 @@
 # Technologies
 
-This folder contains all the technology-specific implementations of ROS 2 Deliberation technologies.
+## Prerequisites
+
+To work with these tools, you need to have gone through the setup steps in the [root README](../README.md).
+Also, we advise you to go through the [problems](../problems/README.md) first, as they will serve as examples on which to apply these technologies.
 
-For a more complete collection of tools, refer to the [Awesome Robotic Deliberation](https://github.com/ros-wg-delib/awesome-ros-deliberation) repository.
+## Introduction
 
----
+This folder contains all the technology-specific implementations of ROS 2 Deliberation technologies.
+Here you will find the tools and libraries that you can learn about in this repository.
+
+For a more complete collection of tools and resources for deliberation in ROS 2, please refer to the [Awesome Robotic Deliberation](https://github.com/ros-wg-delib/awesome-ros-deliberation) repository.
 
 ## Skill Abstractions
 
 While is it possible to directly program our robots to perform complex, long-horizon tasks with plain code, it can be useful to think at higher levels of abstraction.
 There are several formalisms that can help you assemble robust, reactive behaviors for your robots.
 Arguably, the two most popular ones are **finite-state machines (FSMs)** and **behavior trees (BTs)**.
 
-In this workshop, you will be using the following software tools:
+Importantly, all these tools (and many others in the ROS ecosystem) provide a programmatic interface for you to write basic skills in code that leverages ROS, and a graphical interface to assemble the skills together into full behaviors and monitor their execution.
 
-* [BehaviorTree.CPP](https://github.com/BehaviorTree/BehaviorTree.CPP) - A C++ based library for behavior trees.
-* [ros_bt_py](https://github.com/fzi-forschungszentrum-informatik/ros2_ros_bt_py) - A Python based library for behavior trees.
-* [FlexBE](https://github.com/FlexBE) - A Python based library for hierarchical finite-state machines.
+With this repository, you will be able to use the following technologies:
 
-Importantly, all these tools (and many others in the ROS ecosystem) provide a programmatic interface for you to write basic skills in code that leverages ROS, and a graphical interface to assemble the skills together into full behaviors and monitor their execution.
+- [BehaviorTree.CPP](./BehaviorTree.CPP/README.md)
+  - A C++ based library for behavior trees.
+  - [github repo](https://github.com/BehaviorTree/BehaviorTree.CPP)
+  - [documentation](https://www.behaviortree.dev/)
+  - [**To start using it to solve the problems, refer to the BehaviorTree.CPP subfolder**](./BehaviorTree.CPP/README.md).
+
+- [ros_bt_py](./ros_bt_py/README.md)
+  - A Python based library for behavior trees.
+  - [github repo](https://github.com/fzi-forschungszentrum-informatik/ros2_ros_bt_py)
+  - [**To start using it to solve the problems, refer to the ros_bt_py subfolder**](./ros_bt_py/README.md).
 
----
+- [FlexBE](./FlexBE/README.md)
+  - A Python based library for hierarchical finite-state machines.
+  - [github org](https://github.com/FlexBE)
+  - [**To start using it to solve the problems, refer to the the FlexBE subfolder**](./FlexBE/README.md).
 
 ## Task Planning
 
@@ -29,15 +45,15 @@ While you can get far by programming your robots manually using finite-state mac
 If you have a *world model* and a set of *skills* that the robot is allowed to take, there are various algorithms to automatically search for plans that can achieve arbitrary goals possible within that world model.
 This is known as **task planning**, and you can learn more in [this blog post](https://roboticseabass.com/2022/07/19/task-planning-in-robotics/).
 
-In this workshop, you will explore task planning in the ROS 2 ecosystem using [SkiROS2](https://github.com/RobotLabLTH/skiros2).
+In this repository, you will explore task planning in the ROS 2 ecosystem using [SkiROS2](https://github.com/RobotLabLTH/skiros2).
 
-[Start here to solve the workshop problems with SkiROS2 and to additionally explore task planning.](https://github.com/matthias-mayr/skiros2_pyrobosim_lib).
-
----
+[Start here to solve the example problems using SkiROS2](./SkiROS2/skiros2_pyrobosim_lib/README.md)
 
 ## Formal Verification and Model Checking
 
-In addition to making it easier to program our robots, another benefit of using abstractions such as finite-state machines and behavior trees is the ability to analyze their robustiness via *formal verification*.
+In addition to making it easier to program our robots, another benefit of using abstractions such as finite-state machines and behavior trees is the ability to analyze their robustness via *formal verification*.
+
+One such project that aims to solve this problem is the [CONVINCE toolbox](https://convince-project.github.io/overview/).
+In this workshop, you will explore [AS2FM](https://github.com/convince-project/AS2FM), which is part of the CONVINCE toolbox, to perform *statistical model checking* on behavior trees.
 
-One such project that aims to solve this problem is the [CONVINCE toolchain](https://convince-project.github.io/overview/).
-In this workshop, you will explore [AS2FM](https://github.com/convince-project/AS2FM), which is part of the CONVINCE toolchain, to perform *statistical model checking* on behavior trees.
+[Start here to learn about statistical model checking with AS2FM](./convince/README.md)