Skip to content

Commit a6787b2

Browse files
facontidavidefacontidavide
committed
new tutorials
1 parent a336668 commit a6787b2

12 files changed

+224
-9
lines changed

‎docs/guides/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "Guides",
3-
"position": 4,
3+
"position": 5,
44
"link": {
55
"type": "generated-index",
66
"description": "Become a behavior tree whisperer"

‎docs/guides/images/port_vs_blackboard.drawio

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
<mxfile host="Electron" modified="2024-03-05T12:54:40.845Z" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/23.1.5 Chrome/120.0.6099.109 Electron/28.1.0 Safari/537.36" etag="5YSRajxAK6bo9uk-gnCg" version="23.1.5" type="device">
2+
<diagram name="Page-1" id="gSZtd7ybaE-YaSdB-lf6">
3+
<mxGraphModel dx="717" dy="440" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
4+
<root>
5+
<mxCell id="0" />
6+
<mxCell id="1" parent="0" />
7+
<mxCell id="Tmei_RwYaEZryfnuTa6W-7" style="rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="Tmei_RwYaEZryfnuTa6W-2" target="Tmei_RwYaEZryfnuTa6W-3">
8+
<mxGeometry relative="1" as="geometry" />
9+
</mxCell>
10+
<mxCell id="Tmei_RwYaEZryfnuTa6W-10" style="rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="Tmei_RwYaEZryfnuTa6W-2" target="Tmei_RwYaEZryfnuTa6W-4">
11+
<mxGeometry relative="1" as="geometry" />
12+
</mxCell>
13+
<mxCell id="Tmei_RwYaEZryfnuTa6W-2" value="Sequence" style="rounded=0;whiteSpace=wrap;html=1;fontSize=16;" vertex="1" parent="1">
14+
<mxGeometry x="380" y="270" width="120" height="40" as="geometry" />
15+
</mxCell>
16+
<mxCell id="Tmei_RwYaEZryfnuTa6W-3" value="DetectObject" style="rounded=0;whiteSpace=wrap;html=1;fontSize=16;" vertex="1" parent="1">
17+
<mxGeometry x="305" y="360" width="120" height="40" as="geometry" />
18+
</mxCell>
19+
<mxCell id="Tmei_RwYaEZryfnuTa6W-4" value="GraspObject" style="rounded=0;whiteSpace=wrap;html=1;fontSize=16;" vertex="1" parent="1">
20+
<mxGeometry x="460" y="360" width="120" height="40" as="geometry" />
21+
</mxCell>
22+
<mxCell id="Tmei_RwYaEZryfnuTa6W-6" style="rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.75;exitY=1;exitDx=0;exitDy=0;entryX=0.25;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="Tmei_RwYaEZryfnuTa6W-5" target="Tmei_RwYaEZryfnuTa6W-3">
23+
<mxGeometry relative="1" as="geometry" />
24+
</mxCell>
25+
<mxCell id="Tmei_RwYaEZryfnuTa6W-5" value="Which object?&lt;div&gt;Is the result store in the&lt;/div&gt;&lt;div&gt;&lt;span style=&quot;background-color: initial;&quot;&gt;blackboard? Where?&lt;/span&gt;&lt;/div&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontColor=#3333FF;" vertex="1" parent="1">
26+
<mxGeometry x="178" y="254" width="162" height="63.5" as="geometry" />
27+
</mxCell>
28+
<mxCell id="Tmei_RwYaEZryfnuTa6W-9" style="rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=0.75;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="Tmei_RwYaEZryfnuTa6W-8" target="Tmei_RwYaEZryfnuTa6W-4">
29+
<mxGeometry relative="1" as="geometry" />
30+
</mxCell>
31+
<mxCell id="Tmei_RwYaEZryfnuTa6W-8" value="&lt;span style=&quot;background-color: initial;&quot;&gt;Where do we get the pose of the object to grasp?&lt;/span&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontColor=#3333FF;" vertex="1" parent="1">
32+
<mxGeometry x="559" y="285" width="146" height="32.5" as="geometry" />
33+
</mxCell>
34+
<mxCell id="Tmei_RwYaEZryfnuTa6W-11" style="rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="Tmei_RwYaEZryfnuTa6W-13" target="Tmei_RwYaEZryfnuTa6W-14">
35+
<mxGeometry relative="1" as="geometry" />
36+
</mxCell>
37+
<mxCell id="Tmei_RwYaEZryfnuTa6W-12" style="rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="Tmei_RwYaEZryfnuTa6W-13" target="Tmei_RwYaEZryfnuTa6W-15">
38+
<mxGeometry relative="1" as="geometry" />
39+
</mxCell>
40+
<mxCell id="Tmei_RwYaEZryfnuTa6W-13" value="Sequence" style="rounded=0;whiteSpace=wrap;html=1;fontSize=16;" vertex="1" parent="1">
41+
<mxGeometry x="377.5" y="446" width="120" height="40" as="geometry" />
42+
</mxCell>
43+
<mxCell id="Tmei_RwYaEZryfnuTa6W-14" value="DetectObject&lt;br&gt;&lt;font style=&quot;font-size: 11px;&quot;&gt;[IN] name = &quot;apple&quot;&lt;br&gt;[OUT] pose = &quot;{apple_pose}&quot;&lt;br&gt;&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fontSize=16;" vertex="1" parent="1">
44+
<mxGeometry x="262" y="536" width="160.5" height="88" as="geometry" />
45+
</mxCell>
46+
<mxCell id="Tmei_RwYaEZryfnuTa6W-15" value="GraspObject&lt;br style=&quot;font-size: 15px;&quot;&gt;&lt;font style=&quot;font-size: 11px;&quot;&gt;[IN] location = &quot;{apple_pose}&quot;&lt;br&gt;&lt;br&gt;&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fontSize=16;" vertex="1" parent="1">
47+
<mxGeometry x="457.5" y="536" width="163.5" height="88" as="geometry" />
48+
</mxCell>
49+
</root>
50+
</mxGraphModel>
51+
</diagram>
52+
</mxfile>

‎docs/guides/ports_vs_blackboard.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 5
2+
sidebar_position: 4
33
---
44

55
# Ports VS Blackboard

‎docs/guides/scripting.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
sidebar_position: 1
3+
sidebar_label: The Scripting Language
34
---
45

56
# Introduction to Scripting

‎docs/learn-the-basics/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"label": "Learn the Basic Concepts",
2+
"label": "Basic Concepts",
33
"position": 2,
44
"link": {
55
"type": "generated-index",

‎docs/tutorial-advanced/_category_.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Tutorials (Advanced)",
3+
"position": 4,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "5 minutes to learn the most important Docusaurus concepts."
7+
}
8+
}

‎docs/tutorial-advanced/tutorial_12_default_ports.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
sidebar_position: 12
3+
sidebar_label: 12. Default Port values
4+
---
5+
6+
# Default Port values
7+
8+
When defining a port, it might be convenient to add a default value,
9+
i.e. the value that the port should have if not specified in the XML.
10+
11+
:::note
12+
Some of the examples shown in this tutorial will require version 4.5.2 or later.
13+
:::
14+
15+
## Default InputPorts
16+
17+
Let's consider a node initializing multiple ports. We use a custom type **Point2D**,
18+
but the same is true for simple types, such as `int`, `double` or `string`.
19+
20+
```cpp
21+
static PortsList providedPorts()
22+
{
23+
return {
24+
BT::InputPort<Point2D>("input"),
25+
BT::InputPort<Point2D>("pointA", Point2D{1, 2}, "default value is x=1, y=2"),
26+
BT::InputPort<Point2D>("pointB", "3,4", "default value is x=3, y=4"),
27+
BT::InputPort<Point2D>("pointC", "{point}", "point by default to BB entry {point}"),
28+
BT::InputPort<Point2D>("pointD", "{=}", "point by default to BB entry {pointD}")
29+
};
30+
}
31+
```
32+
33+
The very first one (`input`) has no default value and it is mandatory to providing either a value
34+
or blackboard entry in the XML.
35+
36+
### Default values
37+
38+
```cpp
39+
BT::InputPort<Point2D>("pointA", Point2D{1, 2}, "...");
40+
```
41+
42+
If the template specialization `convertFromString<Point2D>()` is implemented, we can use that too.
43+
44+
In other words, the following syntaxes should be equivalent, if our **converFromString** expects
45+
two comma-separated values:
46+
47+
```cpp
48+
BT::InputPort<Point2D>("pointB", "3,4", "...");
49+
// should be equivalent to:
50+
BT::InputPort<Point2D>("pointB", Point2D{3, 4}, "...");
51+
```
52+
53+
### Default blackboard entry
54+
55+
Alternatively, we can define the default blackboard entry that the port should point at.
56+
57+
```cpp
58+
BT::InputPort<Point2D>("pointC", "{point}", "...");
59+
```
60+
61+
If the name of the port and the blackboard entry are the **same**, you can use "{=}"
62+
63+
```cpp
64+
BT::InputPort<Point2D>("pointD", "{=}", "...");
65+
// equivalent to:
66+
BT::InputPort<Point2D>("pointD", "{pointD}", "...");
67+
```
68+
69+
## Default OutputPorts
70+
71+
Output ports are more limited and can only point to a blackboard entry.
72+
You can still use "{=}" when the two names are the same.
73+
74+
```cpp
75+
static PortsList providedPorts()
76+
{
77+
return {
78+
BT::OutputPort<Point2D>("result", "{target}", "point by default to BB entry {target}");
79+
};
80+
}
81+
```

‎docs/guides/blackboard_reference.md renamed to ‎docs/tutorial-advanced/tutorial_13_blackboard_reference.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
2-
sidebar_position: 4
2+
sidebar_position: 13
3+
sidebar_label: 13. Access a port by reference
34
---
45

56
# Zero-copy access to the blackboard

‎docs/tutorial-advanced/tutorial_14_subtree_model.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
sidebar_position: 14
3+
sidebar_label: 14. Subtree Models and autoremap
4+
---
5+
6+
# Subtree Models and autoremap
7+
8+
Subtree remapping was introduced in [Tutorial 6](../tutorial-basics/tutorial_06_subtree_ports.md).
9+
10+
Unfortunately, when using the same SubTree in multiple locations, we might find ourselves
11+
copying and pasting the same long XML tags.
12+
13+
Consider for instance a case like this:
14+
15+
```xml
16+
<SubTree ID="MoveRobot" target="{move_goal}" frame="world" result="{error_code}" />
17+
```
18+
19+
We don't want to copy and paste the three XML attributes `target`, `frame` and `result` every single time,
20+
unless their value IS different.
21+
22+
To avoid that, we can define their default values in `<TreeNodesModel>`.
23+
24+
25+
```xml
26+
<TreeNodesModel>
27+
<SubTree ID="MoveRobot">
28+
<input_port name="target" default="{move_goal}"/>
29+
<input_port name="frame" default="world"/>
30+
<output_port name="result" default="{error_code}"/>
31+
</SubTree>
32+
</TreeNodesModel>
33+
```
34+
Conceptually, this is similar to the
35+
default port explained in [Tutorial 12](tutorial-advanced/tutorial_12_default_ports.md).
36+
37+
If specified in the XML, the value of these remapped blackboard entries, will be overridden.
38+
In the example below, we are overriding the value of "frame", but keeping the default
39+
remapping otherwise.
40+
41+
```xml
42+
<SubTree ID="MoveRobot" frame="map" />
43+
```
44+
45+
## Autoremap
46+
47+
When the names of the entries in the SubTree and the parent tree are the **same**,
48+
you can use the attribute `_autoremap`.
49+
50+
For instance:
51+
52+
```xml
53+
<SubTree ID="MoveRobot" target="{target}" frame="{frame}" result="{result}" />
54+
```
55+
56+
Can be replaced by:
57+
```xml
58+
<SubTree ID="MoveRobot" _autoremap="true" />
59+
```
60+
61+
We can still override a specific value, and autoremap the others
62+
63+
```xml
64+
<SubTree ID="MoveRobot" _autoremap="true" frame="world" />
65+
```
66+
67+
:::caution
68+
The attribute `_autoremap="true"` will automatically remap **all** the entries in
69+
the SubTree, **unless** their name start with an underscore (character "_").
70+
71+
This could be a convenient way to mark an entry in a SubTree as "private".
72+
:::

‎docs/tutorial-basics/tutorial_11_replace_rules.md renamed to ‎docs/tutorial-advanced/tutorial_15_replace_rules.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
sidebar_position: 11
3-
sidebar_label: 11. Substitution Rules
2+
sidebar_position: 15
3+
sidebar_label: 15. Mocking and Nodes Replacement
44
---
55

66
# Mock testing in BT.CPP

0 commit comments

Comments
 (0)