From 3d2d224a88444c9d2b93640762d6513ef76face6 Mon Sep 17 00:00:00 2001 From: Christian Henkel <6976069+ct2034@users.noreply.github.com> Date: Fri, 6 Dec 2024 18:09:54 +0100 Subject: [PATCH 01/14] Guidance in main readme --- README.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4d656f6..9dffbf1 100644 --- 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. @@ -115,7 +119,7 @@ It will ask you for your `sudo` password. ./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). @@ -131,3 +135,7 @@ 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 continue to learn about the `problems`](./problems/README.md). From c3f0e2f50cc87457fd30c1837ee7595578f0604f Mon Sep 17 00:00:00 2001 From: Christian Henkel Date: Wed, 11 Dec 2024 09:10:15 +0100 Subject: [PATCH 02/14] linter fixes Signed-off-by: Christian Henkel --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9dffbf1..2c8a764 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ You can find the [slides here](https://drive.google.com/drive/folders/15H6QdkICy __However, it is perfectly usable as a guided tutorial to learn all of the presented technologies at your own pace.__ -## Introduction to Robotic Deliberation +## 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. @@ -49,7 +49,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. @@ -112,7 +112,7 @@ 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 @@ -136,6 +136,6 @@ Once inside the container, open the folder `/delib_ws/src`. Once you are all set up, refer to the [cheatsheet](./CHEATSHEET.md) for more information, including useful commands and troubleshooting steps. -## Next steps +## Next steps If you are done with your setup and verified that everything is working, you continue to learn about the `problems`](./problems/README.md). From b36680e035f7d3109550b547db2afa32ff399d32 Mon Sep 17 00:00:00 2001 From: Christian Henkel Date: Wed, 11 Dec 2024 09:18:01 +0100 Subject: [PATCH 03/14] references from the problem readme Signed-off-by: Christian Henkel --- README.md | 2 +- problems/README.md | 19 +++++++++++++++++-- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2c8a764..3c4b0c8 100644 --- a/README.md +++ b/README.md @@ -138,4 +138,4 @@ Once you are all set up, refer to the [cheatsheet](./CHEATSHEET.md) for more inf ## Next steps -If you are done with your setup and verified that everything is working, you continue to learn about the `problems`](./problems/README.md). +If you are done with your setup and verified that everything is working, you continue to learn about the [`problems`](./problems/README.md). diff --git a/problems/README.md b/problems/README.md index 0033677..ff4c32f 100644 --- a/problems/README.md +++ b/problems/README.md @@ -1,10 +1,21 @@ # Problems -This folder contains all the initial files for the workshop. +## Pre-requisites + +In order 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 problem setup in general, the later problems will require more complex. +In particular the later problems introduce the concept of battery usage and charging, as well actions that can fail with some probability. + +When running the commands below, the PyRoboSim visualization will open up. +Then you can use the PyRoboSim GUI to interact with the simulation and _play around_ with the problem setups in order to understand them and the actions available to you. --- @@ -113,3 +124,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. From 793f21354ebe4e5e9d390fa1f040cf0173196429 Mon Sep 17 00:00:00 2001 From: Christian Henkel Date: Wed, 11 Dec 2024 09:20:52 +0100 Subject: [PATCH 04/14] Don't build docker on PRs Signed-off-by: Christian Henkel --- .github/workflows/docker.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index a421234..3ba7895 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -1,6 +1,5 @@ name: Docker on: - pull_request: push: branches: - main From 67fb24f214f739af9cc9489f1dec3b8e279c6d3a Mon Sep 17 00:00:00 2001 From: Christian Henkel Date: Wed, 11 Dec 2024 13:17:10 +0100 Subject: [PATCH 05/14] technology readmes reworked for self-study. Signed-off-by: Christian Henkel --- README.md | 8 ------- problems/README.md | 8 ------- technologies/README.md | 48 ++++++++++++++++++++++++++++-------------- 3 files changed, 32 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 3c4b0c8..9a61723 100644 --- a/README.md +++ b/README.md @@ -16,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. @@ -31,8 +29,6 @@ Additionally, it can simulate failures and battery usage in the above actions. ![image](media/pyrobosim_world.png) ---- - ## Setup > [!NOTE] @@ -92,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. @@ -130,8 +124,6 @@ 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. diff --git a/problems/README.md b/problems/README.md index ff4c32f..75dd865 100644 --- a/problems/README.md +++ b/problems/README.md @@ -17,8 +17,6 @@ In particular the later problems introduce the concept of battery usage and char When running the commands below, the PyRoboSim visualization will open up. Then you can use the PyRoboSim GUI to interact with the simulation and _play around_ with the problem setups in order to understand them and the actions available to you. ---- - ## Problem 1 ```bash @@ -37,8 +35,6 @@ Snacks in the kitchen pantry. * Place object * Move robot ---- - ## Problem 2 ```bash @@ -62,8 +58,6 @@ Hallways into the trash room are closed. * Open door * Close door ---- - ## Problem 3 ```bash @@ -90,8 +84,6 @@ Butter is in the fridge, which is closed. Actions may fail with some probability. ---- - ## Problem 4 ```bash diff --git a/technologies/README.md b/technologies/README.md index 05181a3..9da549e 100644 --- a/technologies/README.md +++ b/technologies/README.md @@ -1,10 +1,16 @@ # Technologies -This folder contains all the technology-specific implementations of ROS 2 Deliberation technologies. +## Prerequisites + +To be able to work with these tool, you need to have performed the setup steps in the [root README](../README.md). +Also, we advise you to have go through the [problems](../problems/README.md) first, as they will serve as examples to apply these technologies to. -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 ROS2, please refer to the [Awesome Robotic Deliberation](https://github.com/ros-wg-delib/awesome-ros-deliberation) repository. ## Skill Abstractions @@ -12,15 +18,25 @@ While is it possible to directly program our robots to perform complex, long-hor 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) From 8e88e64c6bbc1a8df63b58e7b396508a4ccdc76f Mon Sep 17 00:00:00 2001 From: Christian Henkel <6976069+ct2034@users.noreply.github.com> Date: Tue, 17 Dec 2024 09:52:47 +0100 Subject: [PATCH 06/14] Update README.md Co-authored-by: Sebastian Castro <4603398+sea-bass@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9a61723..ec5855f 100644 --- a/README.md +++ b/README.md @@ -130,4 +130,4 @@ Once you are all set up, refer to the [cheatsheet](./CHEATSHEET.md) for more inf ## Next steps -If you are done with your setup and verified that everything is working, you continue to learn about the [`problems`](./problems/README.md). +If you are done with your setup and verified that everything is working, you can continue to learn about the [`problems`](./problems/README.md). From ccbcc952cd9207bf11e9aacbad319008eb5f4472 Mon Sep 17 00:00:00 2001 From: Christian Henkel <6976069+ct2034@users.noreply.github.com> Date: Tue, 17 Dec 2024 09:53:35 +0100 Subject: [PATCH 07/14] Feedback @sea-bass Co-authored-by: Sebastian Castro <4603398+sea-bass@users.noreply.github.com> From d4147794058b63e1030f55662770c76d581be642 Mon Sep 17 00:00:00 2001 From: Christian Henkel <6976069+ct2034@users.noreply.github.com> Date: Tue, 17 Dec 2024 09:54:15 +0100 Subject: [PATCH 08/14] Feedback @sea-bass Co-authored-by: Sebastian Castro <4603398+sea-bass@users.noreply.github.com> --- problems/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/problems/README.md b/problems/README.md index 75dd865..7855240 100644 --- a/problems/README.md +++ b/problems/README.md @@ -2,7 +2,7 @@ ## Pre-requisites -In order to run the problems, make sure you did the setup steps in the [main README](../README.md). +To run the problems, make sure you did the setup steps in the [main README](../README.md). ## Introduction From 0ae19d04e8a3932d586c309adb2f5234182875d8 Mon Sep 17 00:00:00 2001 From: Christian Henkel <6976069+ct2034@users.noreply.github.com> Date: Tue, 17 Dec 2024 09:54:24 +0100 Subject: [PATCH 09/14] Feedback @sea-bass Co-authored-by: Sebastian Castro <4603398+sea-bass@users.noreply.github.com> --- problems/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/problems/README.md b/problems/README.md index 7855240..b3a7ba3 100644 --- a/problems/README.md +++ b/problems/README.md @@ -11,7 +11,7 @@ This folder contains all the files required to run the demo problems that will b 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. The problems are designed to increase in complexity. -While the first problem can be used to familiarize yourself with the problem setup in general, the later problems will require more complex. +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 actions that can fail with some probability. When running the commands below, the PyRoboSim visualization will open up. From 6ceef656983447132b1dcda76140b0fc2c916cbd Mon Sep 17 00:00:00 2001 From: Christian Henkel <6976069+ct2034@users.noreply.github.com> Date: Tue, 17 Dec 2024 09:54:34 +0100 Subject: [PATCH 10/14] Feedback @sea-bass Co-authored-by: Sebastian Castro <4603398+sea-bass@users.noreply.github.com> --- problems/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/problems/README.md b/problems/README.md index b3a7ba3..bebff14 100644 --- a/problems/README.md +++ b/problems/README.md @@ -12,7 +12,7 @@ This includes the world models in [PyRoboSim](https://github.com/sea-bass/pyrobo 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 actions that can fail with some probability. +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. Then you can use the PyRoboSim GUI to interact with the simulation and _play around_ with the problem setups in order to understand them and the actions available to you. From 45aa9d229fd7e05446496002b043256f869845b7 Mon Sep 17 00:00:00 2001 From: Christian Henkel <6976069+ct2034@users.noreply.github.com> Date: Tue, 17 Dec 2024 09:54:42 +0100 Subject: [PATCH 11/14] Feedback @sea-bass Co-authored-by: Sebastian Castro <4603398+sea-bass@users.noreply.github.com> --- technologies/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/technologies/README.md b/technologies/README.md index 9da549e..cafbb9c 100644 --- a/technologies/README.md +++ b/technologies/README.md @@ -2,7 +2,7 @@ ## Prerequisites -To be able to work with these tool, you need to have performed the setup steps in the [root README](../README.md). +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 have go through the [problems](../problems/README.md) first, as they will serve as examples to apply these technologies to. ## Introduction From 28291a662afd209acdf206104b63e043dd5aa79c Mon Sep 17 00:00:00 2001 From: Christian Henkel <6976069+ct2034@users.noreply.github.com> Date: Tue, 17 Dec 2024 09:54:50 +0100 Subject: [PATCH 12/14] Feedback @sea-bass Co-authored-by: Sebastian Castro <4603398+sea-bass@users.noreply.github.com> --- problems/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/problems/README.md b/problems/README.md index bebff14..0a8da65 100644 --- a/problems/README.md +++ b/problems/README.md @@ -15,7 +15,7 @@ While the first problem can be used to familiarize yourself with the repository 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. -Then you can use the PyRoboSim GUI to interact with the simulation and _play around_ with the problem setups in order to understand them and the actions available to you. +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 From 2eb0fe701a80e5e6bb4691f2033c2e84c65734f2 Mon Sep 17 00:00:00 2001 From: Christian Henkel <6976069+ct2034@users.noreply.github.com> Date: Tue, 17 Dec 2024 09:55:03 +0100 Subject: [PATCH 13/14] Feedback @sea-bass Co-authored-by: Sebastian Castro <4603398+sea-bass@users.noreply.github.com> --- technologies/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/technologies/README.md b/technologies/README.md index cafbb9c..83d563f 100644 --- a/technologies/README.md +++ b/technologies/README.md @@ -3,7 +3,7 @@ ## 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 have go through the [problems](../problems/README.md) first, as they will serve as examples to apply these technologies to. +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. ## Introduction From 72690561d2e2a8ceeca2098f0a3eba7d65dfbb0b Mon Sep 17 00:00:00 2001 From: Christian Henkel <6976069+ct2034@users.noreply.github.com> Date: Tue, 17 Dec 2024 09:55:11 +0100 Subject: [PATCH 14/14] Feedback @sea-bass Co-authored-by: Sebastian Castro <4603398+sea-bass@users.noreply.github.com> --- technologies/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/technologies/README.md b/technologies/README.md index 83d563f..e457158 100644 --- a/technologies/README.md +++ b/technologies/README.md @@ -10,7 +10,7 @@ Also, we advise you to go through the [problems](../problems/README.md) first, a 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 ROS2, please refer to the [Awesome Robotic Deliberation](https://github.com/ros-wg-delib/awesome-ros-deliberation) 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