Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 481c45b

Browse files
author
Davide Faconti
committed
docs
1 parent 654177a commit 481c45b

11 files changed

+320
-53
lines changed

‎docs/images/CrossDoorSubtree.png

-15.2 KB
Loading

‎docs/images/ReadTheDocs.png

10.8 KB
Loading

‎docs/index.md

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@ which are loaded at run-time.
1818
- It includes a __logging/profiling__ infrastructure that allows the user
1919
to visualize, record, replay and analyze state transitions.
2020

21+
![ReadTheDocs](images/ReadTheDocs.png)
22+
23+
2124
## The problem
2225

2326
Many software systems, being robotics a notable example, are inherently
@@ -42,17 +45,17 @@ If we don't keep these concepts in mind from the very beginning, we create
4245
software modules/components which are highly coupled to a particular application,
4346
instead of being reusable.
4447

45-
Frequently ,the concern of __Coordination__ is mixed with __Computation__.
48+
Frequently, the concern of __Coordination__ is mixed with __Computation__.
4649
In other words, people address the problems of coordinating actions and take decisions
4750
locally.
4851

49-
The business logic becomes "spread" in many locations and it is hard for the developer
50-
to reason about it and to debug errors in the control flow.
52+
The business logic becomes "spread" in many locations and it is __hard for the developer
53+
to reason about it and to debug errors__ in the control flow.
5154

5255
To achieve strong separation of concerns it is better to centralize
5356
the business logic in a single location.
5457

55-
Finite State Machines were created specifically with this goal in mind, but in
58+
__Finite State Machines__ were created specifically with this goal in mind, but in
5659
the recent years __Behavior Trees__ gained popularity, especially in the game industry.
5760

5861

‎docs/tutorial_A_create_trees.md

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -54,31 +54,37 @@ a function pointer.
5454

5555
The only requirement of the functor is to have either one of these signatures:
5656

57+
``` c++
5758
BT::NodeStatus myFunction()
58-
BT::NodeStatus myFunction(TreeNode& self)
59+
BT::NodeStatus myFunction(BT::TreeNode& self)
60+
```
61+
62+
For example:
5963
6064
6165
``` c++
62-
BT::NodeStatus SayHello() {
66+
using namespace BT;
67+
68+
NodeStatus SayHello() {
6369
std::cout << "Robot says Hello" << std::endl;
64-
return BT::NodeStatus::SUCCESS;
70+
return NodeStatus::SUCCESS;
6571
}
6672
6773
class GripperInterface
6874
{
6975
public:
7076
GripperInterface(): _open(true) {}
7177
72-
BT::NodeStatus open() {
78+
NodeStatus open() {
7379
_open = true;
7480
std::cout << "GripperInterface::open" << std::endl;
75-
return BT::NodeStatus::SUCCESS;
81+
return NodeStatus::SUCCESS;
7682
}
7783
78-
BT::NodeStatus close() {
84+
NodeStatus close() {
7985
std::cout << "GripperInterface::close" << std::endl;
8086
_open = false;
81-
return BT::NodeStatus::SUCCESS;
87+
return NodeStatus::SUCCESS;
8288
}
8389
8490
private:
@@ -95,7 +101,13 @@ We can build a `SimpleActionNode` from any of these functors:
95101

96102
## A static Tree
97103

98-
``` c++
104+
Let's create instances of our TreeNodes and compose them into a tree.
105+
106+
- `BT::SequenceNode` is a built-in ControlNode provided by the library.
107+
- `BT::SimpleActionNode` is a synchronous ActionNode created passing a functor.
108+
- `DummyNodes::ApproachObject` is our user-defined ActionNode.
109+
110+
``` c++
99111
#include "dummy_nodes.h"
100112

101113
int main()

‎docs/tutorial_B_node_parameters.md

Lines changed: 22 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# How to use NodeParameters
22

3-
NodeParameters are like arguments of a function.
3+
NodeParameters are like arguments passed to a function.
44

5-
They are a list of __key/value__ (both strings) that are usually
5+
They are a map of __key/value__ pairs (both strings) that are usually
66
parsed from file.
77

88
To create a TreeNodes that accepts NodeParameters, you must follow these rules:
@@ -23,12 +23,10 @@ static const BT::NodeParameters& requiredNodeParameters()
2323
```
2424

2525

26-
## Example: an action with the parameter "message"
26+
## Example: an Action requiring the parameter "message"
2727

28-
In the following example you can see a simple sunchronous ActionNodeBase.
29-
30-
The parameter with the __key__ "message" is passed as a NodeParameter. Its __value__ is
31-
printed on console, without any conversion.
28+
`SaySomething` is a simple synchronous ActionNodeBase which will print the
29+
string passed in the NodeParameter called "message".
3230

3331
Please note:
3432

@@ -37,8 +35,8 @@ Please note:
3735
- The __static__ method `requiredNodeParameters()` contains a single key/value pair.
3836
The string "default message" is the default value.
3937

40-
- Parameters MUST be accessed using the method `getParam()`, preferably in the
41-
`tick()` method, since this value may change over time.
38+
- Parameters must be accessed using the method `getParam()`, preferably in the
39+
`tick()` method.
4240

4341
``` c++ hl_lines="5 9 18"
4442
class SaySomething: public ActionNodeBase
@@ -182,9 +180,22 @@ To pass the parameter in the XML, use an attribute
182180
with the same name:
183181
184182
``` XML
185-
<MoveBaseAction goal="41.2;13.5;0.7"/>
186-
<SaySomething message="Destination reached"/>
183+
<Sequence>
184+
<MoveBaseAction goal="41.2;13.5;0.7"/>
185+
<SaySomething message="Destination reached"/>
186+
<SaySomething/> <!-- No parameter passed -->
187+
</Sequence>
187188
```
188189

190+
Expected output:
191+
192+
193+
[ MoveBase: STARTED ]: goal: x=41.2 y=13.5 theta=0.7
194+
[ MoveBase: FINISHED ]
195+
Robot says: Destination reached
196+
Robot says: default message
197+
198+
199+
189200

190201

‎docs/tutorial_C_blackboard.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
# Blackboards
22

3-
The blackboard is a a key/value storage that can be shared by all the Nodes
3+
The blackboard is a a __key/value__ storage that can be shared by all the Nodes
44
of a tree.
55

6-
The __key__ is a string and the value is a type-erased container (called `SafeAny::Any`)
6+
The __key__ is a string whilst the __value__ is a type-erased container (called `SafeAny::Any`)
77
that allows the user to store any C++ object and to cast it back to its original form.
88

99
Contrariwise to `boost::any` and `std::any`, this container will also try to
@@ -20,7 +20,6 @@ to create a persistent blackboard using a database.
2020

2121
## Assign a blackboard to a tree
2222

23-
2423
Let's start with the a `SimpleActionNode` that writes into the blackboard.
2524

2625
``` c++
@@ -38,15 +37,16 @@ NodeStatus CalculateGoalPose(TreeNode& self)
3837
return NodeStatus::SUCCESS;
3938
}
4039
else{
40+
// No blackboard passed to this node.
4141
return NodeStatus::FAILURE;
4242
}
4343
}
4444
```
4545
46-
Let's consider now the following XML tree definition:
46+
Let's consider the following XML tree definition:
4747
4848
``` XML
49-
<root main_tree_to_execute = "MainTree" >
49+
<root main_tree_to_execute = "MainTree">
5050
<BehaviorTree ID="MainTree">
5151
<SequenceStar>
5252
<CalculateGoalPose/>
@@ -60,16 +60,16 @@ Let's consider now the following XML tree definition:
6060

6161
The root SequenceStar will execute four actions:
6262

63-
- CalculateGoalPose sets writes into the key "GoalPose".
64-
- The syntax `${...}` tells to MoveBase to read the goal from the key "GoalPose" in the blackboard.
65-
- Alternatively, you can write a key/value pair into the Blackboard using the built-in action `SetBlackboard`.
63+
- `CalculateGoalPose` writes into the blackboard key "GoalPose".
64+
- The syntax `${...}` tells to `MoveBase` to read the goal from the key "GoalPose" in the blackboard.
65+
- Alternatively, you can write a key/value pair into the blackboard using the built-in action `SetBlackboard`.
6666
- Similar to step 2. Pose2D is retrieved from "OtherGoal".
6767

6868
!!! note
6969
For your information, __GoalPose__ is stored as a type erased Pose2D.
7070

7171
On the other hand, __OtherGoal__ is stored as a std::string, but is converted
72-
to Pose2D the method `getParam()` using the function `convertFromString<Pose2D>()`.
72+
to Pose2D by the method `getParam()` using the function `convertFromString<Pose2D>()`.
7373

7474
In the following code sample we can see two equivalent ways to assign a
7575
Blackboard to a tree.

‎docs/tutorial_D_subtrees.md

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,20 +6,21 @@ hierarchical__.
66
You might have noticed that it is always possible to raise the level of
77
abstraction looking one node up in the hierarchy of the tree.
88

9-
For example, in the [Introduction](BT_basics.md) page we have seen this tree:
9+
In the [Introduction](BT_basics.md) we presented this tree:
1010

1111
![FallbackNodes](images/FallbackBasic.png)
1212

13-
The Sequence calle "Unlock" can be seen as an entire subtree with an arbitrary
13+
The Sequence called "Unlock" can be seen as an entire subtree; from the point
14+
of view of its parent, that subtree can have an arbitrary
1415
level of complexity.
1516

16-
BehaviorTree.CPP provides a way to create reusable and composable Subtrees
17+
__BehaviorTree.CPP__ provides a way to create reusable and composable Subtrees
1718
that can be included as nodes of a larger and more complex tree.
1819

1920
## Example: subtrees in XML
2021

21-
To use the Subtree funtionality, you __don't__ need to modify your
22-
__cpp__ code, nor your existing TreeNodes.
22+
To define and insert a Subtree you __don't need to modify your
23+
c++ code__, nor your existing TreeNodes implementations.
2324

2425
Multiple BehaviorTrees can be created and composed in the XML itself.
2526

‎docs/tutorial_E_plugins.md

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,18 @@ and linked statically into out projects.
55

66
We used the `BehaviorTreeFactory` to registed manualy these custom TreeNodes.
77

8-
We can avoid these steps loading user-defined TreeNodes at run-time using
9-
pre-compiled dynamic shared libraries, i.e. __plugins__.
8+
Alternatively, we can load user-defined TreeNodes at run-time using
9+
pre-compiled __dynamic shared libraries, i.e. plugins__.
1010

1111
# Example
1212

1313
Let's consider the [first tutorial](tutorial_A_create_trees.md).
1414

15-
We can encapsulate the registration of multiple TreeNodes into a single
15+
To do this we must encapsulate the registration of multiple TreeNodes into a single
1616
function like this:
1717

1818
``` c++
19+
// This is a macro. Just deal with it.
1920
BT_REGISTER_NODES(factory)
2021
{
2122
static GripperInterface gi; // we can't have more than instance
@@ -30,29 +31,26 @@ BT_REGISTER_NODES(factory)
3031
}
3132
```
3233
33-
34-
`BT_REGISTER_NODES` is a macro that defines a function which symbol can be loaded
35-
from a dynamic library.
36-
3734
!!! note
38-
This function must be placed in __.cpp__ file, not an header file.
35+
This function must be placed in __.cpp__ file, not the header file.
3936
4037
In this particular example we assume that BT_REGISTER_NODES and
41-
the definitions of our custom TreeNodes are defined in the file __dummy_nodes.cpp__.
38+
the definitions of our custom TreeNodes are all defined in the file __dummy_nodes.cpp__.
4239
43-
In __cmake__ the plugin can be compiled using the argument SHARED in
40+
If you compile the plugin using __cmake__, add the argument `SHARED` to
4441
`add_library`.
4542
4643
```cmake
44+
#your CMakeLists.txt
4745
add_library(dummy_nodes SHARED dummy_nodes.cpp )
4846
```
4947

50-
In Linux the file __libdummy_nodes.so__ is created.
48+
In Linux the file __libdummy_nodes.so__ will be created.
5149

52-
Our first tutorial is, as a result, much simpler now:
50+
The [first tutorial](tutorial_A_create_trees.md) becomes, as a result, much simpler:
5351

5452

55-
```c++ hl_lines="3 24"
53+
```c++ hl_lines="3 25"
5654
#include "behavior_tree_core/xml_parsing.h"
5755
#include "Blackboard/blackboard_local.h"
5856
// #include "dummy_nodes.h" YOU DON'T NEED THIS ANYMORE
@@ -75,6 +73,7 @@ const std::string xml_text = R"(
7573
int main()
7674
{
7775
using namespace BT;
76+
7877
BehaviorTreeFactory factory;
7978
factory.registerFromPlugin("./libdummy_nodes.so");
8079

@@ -96,11 +95,13 @@ int main()
9695
## Display the manifest of a plugin
9796

9897
BehaviorTree.CPP provides a command line tool called
99-
__bt_plugin_manifest__; it shows all user-defind TreeNodes
98+
__bt_plugin_manifest__.
99+
100+
It shows all user-defind TreeNodes
100101
registered into the plugin and their corresponding NodeParameters.
101102

102103

103-
```
104+
```
104105
$> ./bt_plugin_manifest ./libdummy_nodes.so
105106
106107
---------------

0 commit comments

Comments
 (0)