Skip to content

Commit 2934d05

Browse files
jocacacejocacace
committed
initial documentation reshaping
1 parent 846d0f1 commit 2934d05

File tree

1 file changed

+32
-113
lines changed

1 file changed

+32
-113
lines changed

‎README.md‎

Lines changed: 32 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -1,143 +1,62 @@
11
[![build](https://github.com/Eurecat/behaviortree_ros2/actions/workflows/build.yml/badge.svg)](https://github.com/Eurecat/behaviortree_ros2/actions/workflows/build.yml)
22

33

4-
# behaviortree_ros2
4+
# BehaviorTree.ROS2
5+
56

67
## Scope
7-
This repository contains a ROS 2 layer for wrapping the functionalities of [BehaviorTree.CPP](https://www.behaviortree.dev/) . In particular, it provides a standard way to implement:
8+
This repository contains a ROS 2 layer for wrapping the functionalities of [BehaviorTree.CPP](https://www.behaviortree.dev/).
89

9-
- Behavior Tree Executor with ROS 2 Action interface
10-
- Action clients
11-
- Service Clients
12-
- Topic Subscribers
13-
- Topic Publishers
10+
Using this package you will have an executor for ROS 2 behavior trees and different nodes already prepared to interface with the ROS 2 system, like node publisher subscribers, services and actions.
1411

12+
## Use BehaviorTree.ROS2
1513

14+
- Dockers is used to simplify the installation and the deployment of BehaviorTree.ROS2. To install the dockers [follow this guide](https://docs.docker.com/engine/install/ubuntu/).
1615

16+
- Your public ssh keys should be correcly installed on the github portal to succesfully download the dependencies using the docker container.
1717

18+
- To download and start the BT executore, move in the desired development folder and use the following command.
1819

20+
$ git clone [email protected]:Eurecat/BehaviorTree.ROS2.git
21+
$ cd BehaviorTree.ROS2/
22+
$ ./scripts/install.sh && ./scripts/compose.sh
1923

20-
## Use behaviortree_ros2
21-
To use this repository you can rely on [Docker](https://www.docker.com/) framework. In the source you will find convenient Dockerfile to compile the image and the docker-compose to transform the image into a container.
24+
__Note that, the first time you run this command it could take a more time than expected since it creates the image and compile the workspace with the BehaviorTree.ROS2 dependencies.__
2225

23-
To install the docker framework, you should install docker on your system: [follow this guide](https://docs.docker.com/engine/install/ubuntu/).
26+
- You can log into the contenier with one or more terminal using the following script.
27+
28+
$ ./scripts/exec.sh
2429

25-
After docker, use the following commands
2630

27-
$ [email protected]:Eurecat/behaviortree_ros2.git
28-
$ cd behaviortree_ros2
29-
$ ./scripts/install.sh
3031

31-
Now the image is correctly compiled and installed in your system. You can run it with the following one
32+
## Test the BehaviorTree.ROS2
3233

33-
$ ./scripts/compose.sh
34+
To check that everything is installed correctly, you can test the following example.
3435

35-
This last command will setup your workspace. First, it will download the needed dependencies:
36-
__TODO__: add deps
36+
- Start the executor
3737

38+
$ ros2 launch bt_examples executor.launch.xml
39+
40+
- Request to start the tree called ExampleTree1
41+
42+
$ ros2 action send_goal /bt_action_server_example btcpp_ros2_interfaces/action/ExecuteTree "{target_tree: ExampleTree1}"
3843

39-
First example
44+
- Monitor the execution status using groot
4045

41-
$ ros2 launch bt_examples executor.launch.xml
42-
$ ros2 action send_goal /bt_action_server_example btcpp_ros2_interfaces/action/ExecuteTree "{target_tree: ExampleTree1}"
46+
$ ros2 run groot Groot
4347

48+
__After opened groot, you must click on connect to start the monitoring__
4449

4550

46-
# BehaviorTree.ROS2
47-
<!-- [![Test](https://github.com/BehaviorTree/BehaviorTree.ROS2/actions/workflows/test.yml/badge.svg)](https://github.com/BehaviorTree/BehaviorTree.ROS2/actions/workflows/test.yml) -->
48-
49-
This repository contains useful wrappers to use ROS2 and BehaviorTree.CPP together.
50-
In particular, it provides a standard way to implement:
51-
52-
- Behavior Tree Executor with ROS Action interface.
53-
- Action clients.
54-
- Service Clients.
55-
- Topic Subscribers.
56-
- Topic Publishers.
57-
58-
Our main goals are:
59-
60-
- to minimize the amount of boilerplate.
61-
- to make asynchronous Actions non-blocking.
62-
63-
It uses [behaviortree_eut_plugins](https://ice.eurecat.org/gitlab/robotics-automation/behavior_tree_eut_plugins) for augmenting its original [public version](https://github.com/BehaviorTree/BehaviorTree.ROS2.git) with custom serialization and deserialization policies, providing out of the box json one, essentially adding the following plugins templates to be used with a one-liner:
64-
65-
Plugin Template | Deserialization Policy | Serialization Policy | Extra Pre/Post processing
66-
--- | --- | --- | ---
67-
Publisher | NoDeserialization | - | -
68-
AutoDesPublisher | AutomaticDeserialization | - | -
69-
| | |
70-
Subscriber | - | NoSerialization | -
71-
AutoSerSubscriber | - | AutomaticSerialization | -
72-
JsonSerSubscriber | - | JsonSerialization | -
73-
SmartJsonSerSubscriber | - | SmartJsonSerialization | &check;
74-
SmartTimeEnabledJsonSerSubscriber | - | SmartJsonSerialization | &check;
75-
| | |
76-
ServiceClient | NoDeserialization | NoSerialization | -
77-
AutoDesServiceClient | AutomaticDeserialization | NoSerialization | -
78-
JsonSerServiceClient | NoDeserialization | JsonSerialization | -
79-
AutoDesJsonSerServiceClient | AutomaticDeserialization | JsonSerialization | -
80-
AutoDesAutoSerServiceClient | AutomaticDeserialization | AutomaticSerialization | -
81-
AutoDesSmartJsonSerServiceClient | AutomaticDeserialization | SmartJsonSerialization | &check;
82-
| | |
83-
ActionClient | NoDeserialization | NoSerialization | -
84-
AutoDesJsonSerActionClient | AutomaticDeserialization | JsonSerialization | -
85-
AutoDesAutoSerActionClient | AutomaticDeserialization | AutomaticSerialization | -
86-
AutoDesSmartJsonSerActionClient | AutomaticDeserialization | SmartJsonSerialization | &check;
87-
88-
Explained in very simple terms these are how the aforementioned serialization / deserialization policies operate:
89-
90-
- **NoDeserialization** would treat the msg of type `T` with type `T`
91-
- **NoSerialization** would treat the msg of type `T` with type `T`
92-
- **AutomaticDeserialization** would explode the msg of type `T` with a port for each simple and raw type (e.g. uint8,.. uint64, int8, .., int64, bool, float, double, string ), except time related ones.
93-
- **JsonSerialization** would serialize the msg of type `T` into a `nlohmann::json`
94-
- **SmartJsonSerialization** would serialize the msg of type `T` into a `nlohmann::json` and offers additional pre/post processing utilities, specifically:
95-
- `ignore_fields` port to specify the `std::vector<std::String>` that shall be ignored during serialization avoiding not needed data processing and storage
96-
- possibilities of specialize template functions for pre or post processing of the message
97-
98-
- `void useMsgBeforeSerialization(const std::shared_ptr<T> _message, BT::TreeNode& _tree_node)`
99-
- `void processMsgPostSerialization(const std::shared_ptr<T> _message, nlohmann::json& json, BT::TreeNode& _tree_node)`
100-
101-
102-
## How to use
103-
To create a new plugin, you just need to write a .cpp file in your ros2 behaviortree_ros2 dependent package, include the msg, srv, action definitions that you are interested in a write simple one liners such as:
104-
105-
```
106-
#include "behaviortree_ros2/plugins.hpp"
107-
#include "behaviortree_ros2/serialized_sub_node.hpp"
108-
#include "behaviortree_ros2/serialized_pub_node.hpp"
109-
#include "behaviortree_ros2/serialized_srv_node.hpp"
110-
#include "behaviortree_ros2/serialized_act_node.hpp"
111-
112-
#include <std_msgs/msg/empty.hpp>
113-
114-
#include <std_srvs/srv/empty.hpp>
115-
116-
#include "btcpp_ros2_interfaces/action/sleep.hpp"
117-
118-
using namespace BT;
119-
120-
121-
BT_REGISTER_ROS_NODES(factory, params)
122-
{
123-
//SUBSCRIBERS
124-
factory.registerNodeType<SmartSerializedSubscriber<std_msgs::msg::Empty>>("MonitorStdEmpty",params);
125-
126-
//PUBLISHERS
127-
factory.registerNodeType<AutomaticPublisher<std_msgs::msg::Empty>>("PublishStdEmpty",params);
128-
129-
// SERVICE CLIENTS
130-
factory.registerNodeType<AutomaticServiceClient<std_srvs::srv::Empty>>("CallEmptyService",params);
131-
132-
// ACTION CLIENTS
133-
factory.registerNodeType<AutomaticSimpleActionClient<btcpp_ros2_interfaces::action::Sleep>>("TestActionSleep",params);
13451

135-
};
136-
```
13752

138-
As you can see, creating a new action client is as simple as adding a line, without avoiding repetition of redundant boiler plate code.
53+
### TODO: discuss a better example
54+
### TODO: document the nodes implemented in the plugins
55+
### TODO: describe how to implement new plugins
56+
57+
58+
### Dependencies
13959

140-
To generate a .so of plugins to be imported at run time, you need to add this into the CMakeLists.txt of your package:
14160

14261
// TODO
14362

0 commit comments

Comments
 (0)