Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@OscarMrZ
OscarMrZ authored Nov 6, 2023
1 parent 67455ec commit aaa577e
Showing 1 changed file with 53 additions and 87 deletions.
140 changes: 53 additions & 87 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@

## Introduction

BT Studio is an **open-source** tool crafted for the development of robotic applications. Its primary objective is to facilitate the quick deployment of behavior tree-based robotic applications within ROS. In BT Studio, a robotic app is defined as an XML tree coupled with actions scripted in Python, which the tool then translates into a ROS 2 package. This process circumvents the unnecessary complexities often associated with ROS-specific configurations, offering developers a more streamlined approach.
BT Studio is an **open-source** tool crafted for the development of robotic applications. Its primary objective is to facilitate the quick deployment of behavior tree-based robotic applications within ROS 2. In BT Studio, a robotic app is defined as an graphical tree coupled with actions scripted in Python, which the tool then translates into a ROS 2 package. This process circumvents the unnecessary complexities often associated with ROS-specific configurations, offering developers a more streamlined approach.

## Usage

Expand All @@ -33,24 +33,36 @@ cd bt-studio
sudo apt update
sudo apt install python3-vcstool python3-pip python3-rosdep python3-colcon-common-extensions -y
```
4. Install the tree_gardener library
4. Install the backend dependencies
```bash
cd modules/tree_gardener
python3 -m pip install .
cd backend
pip install virtualenv
virtualenv backend_env
source backend_env/bin/activate
pip install django djangorestframework
```
This is a custom library that the apps use for tree related stuff, like accessing ports. Its installation is crucial!

### Generating your first app
5. Launch the backend
```bash
python3 manage.py runserver
```

1. Write actions
Go to the tree_translator section
6. Setup the frontend

From the bt_studio folder:
```bash
cd ../../tree_translator
cd frontend
yarn install
yarn start
```
In the `actions/` folder, you can write actions using whatever dependencies you like, and with full ROS 2 integration.

The actions must follow the following template:
A new window in the browser should have opened. If not, go to [BT Studio](http://localhost:3000/)

### Generating apps

1. Write actions

You may create as many actions as needed using the file browser. The actions must have a .py extension and follow this structure:

```python
import py_trees
Expand Down Expand Up @@ -106,112 +118,66 @@ class TemplateAction(py_trees.behaviour.Behaviour):

For examples of how to use ports in your actions, please refer to the [example actions](tree_translator/actions) provided with the repo in the actions folder. Feel free to study and adapt them!

2. Write an xml tree

This is where the magic of your app happens. With the actions you have written, you can define a behavior tree in an XML file. All the nodes of [Davide Faconti's BT.cpp library](https://www.behaviortree.dev/docs/category/nodes-library) are fully supported in BT Studio.

```xml
<root>
<BehaviorTree ID="MainTree">
<ReactiveSequence name="main_seq">
<ReactiveFallback name="obs_fallback">
<CheckObstacle name="check_obstacle" obs_port="{n_obs}" amplitude="20"/>
<Turn name="avoid_obstacle"/>
</ReactiveFallback>
<Forward name="move_forward" speed="0.2" obs_port="{n_obs}"/>
</ReactiveSequence>
</BehaviorTree>
</root>
```
2. Define the tree structure

3. Generate a self-contained tree
Using the existing blocks, you may define the logic of your app. Here you have available all the defined actions. This can be done previously to step 1 if you prefer to define the logic of the tree before its implementation!

```bash
python3 generate_tree.py trees/tree.xml actions/ trees/self_contained_tree.xml
```
3. Downloading the app

Although it is not a common practice, self-contained trees allow greater portability and encapsulate all the complexity of a robotics app into a single file.
Clicking the green download button, a ROS 2 app is generated. This can be unziped in a ROS 2 workspace and installed as any other package.

4. Generate a ROS2 app
### Using the generated app

Given a self-contained tree, `tree_gardener` is already able to transform it into an executable tree to be executed within ROS. BT Studio, to offer greater ease of use and reduce the interaction with ROS, comes with an integrated app generation script. This script takes the previously generated tree and prepares a complete ROS 2 app, that can be directly installed. This is simply a ROS 2 package template with a prepared executor script, which calls all the necessary tree_gardener translator functions. If you know what you are doing, you can directly modify and use the [provided package template](tree_translator/ros_template).
1. Moving the app to a ROS 2 ws

```bash
python3 generate_app.py trees/self_contained_tree.xml you_app_name
mkdir -p your_ws/src
mv your_app.zip your_ws/src
unzip your_ws/src/your_app.zip
```

This generates a zip file with all the necessary files called `your_app_name.zip`

## Executing your first app

1. Creating a ROS 2 ws and moving the app to the src folder

The previous steps have generated an executable app, that should be placed inside a ROS 2 workspace.
2. Downloading auxiliary tools and dependencies

```bash
mkdir -p your_ws/src/your_app_name
cp your_app_name.zip your_ws/src/your_app_name
cd your_ws/src/your_app_name
unzip your_app_name.zip
cd src/your_app/
vcs import < demo/thirdparty.repos
cd ../..
rosdep install --from-paths src -r -y --ignore-src
```

2. Install execution dependecies
3. Compiling

#### BT Studio dependecies

Move to the src of the ws and download BT Studio depedencies
```bash
cd ..
vcs import < your_app/thirdparty.repos
colcon build --symlink-install
source install/setup.bash
```

A Thirdparty folder is created to store the dependecies.
4. Launching a testing environment

#### Dynamic app dependencies
Now, install the dependencies of your actions using rosdep. This is done this way as the dependencies of each app are variable and cannot be known at installation time.
```bash
cd ..
rosdep install --from-paths src -y --ignore-src
```
You may choose whatever environment for your app to execute into, but we provide some prepared packages for convenience.

3. Compile
4.
Now, we call colcon build so it prepares the packages for execution.
```bash
colcon build --symlink-install
ros2 launch tb4_sim tb4_launcher.py
py-trees-tree-viewer
```

4. Source the ws

This is necessary for ros to detect the newly installed packages.
```bash
source install/setup.bash
```
5. Launching the app

Now, using the app executor, you may launch the app itself.

5. Execution!

Finally, we can execute the app. If you are using the recommended simulator:
```bash
ros2 launch tb4_sim tb4_launcher.py
py-trees-tree-viewer
ros2 run your_app_name executor
ros2 run your_app executor
```

If you execute these commands from different terminals, please, remember to source the ws in each of them.

## Video
## Showcase

I have prepared this video to guide you through the installation process. Please, be aware this readme is the one and only source of truth of the project, the videos may not be updated.
You can see a running application as reference here:

[Installation](https://www.youtube.com/watch?v=MObIPLqlmGM&feature=youtu.be)
[Showcase video](https://www.youtube.com/watch?v=Bo4SJEiBKGQ)

## Roadmap

In the future, this project will have total integration with [RoboticsAcademy](https://github.com/JdeRobot/RoboticsAcademy), so developers will be able to develop trees in a graphical interface and deploy them in a dockerized environment. The expected roadmap is as follows:

* Local execution
* Web-based tree designer with local execution
* Integration with a dockerized environment
In the future, this project will have total integration with [RoboticsAcademy](https://github.com/JdeRobot/RoboticsAcademy), so developers will be able to deploy the trees in a dockerized environment.

<!-- MARKDOWN LINKS & IMAGES -->
[contributors-shield]: https://img.shields.io/github/contributors/JdeRobot/bt-studio
Expand Down

0 comments on commit aaa577e

Please sign in to comment.