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 diff --git a/README.md b/README.md index 4d656f6..ec5855f 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. @@ -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 index 0033677..0a8da65 100644 --- 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 index 05181a3..e457158 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 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 @@ -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)