Skip to content

Commit

Permalink
docs: Small changes to tutorial 02 (microsoft#225)
Browse files Browse the repository at this point in the history
* docs: fix to my_tree.xml

Before my_tree.xml was containing an `SayHello` Action that was not registered
inside the BehaviourTreeFactory contained in the simple_bt.cpp

* docs: tutorial 1 my_tree.xml editable in Groot

Add to the xml tree definition the node declaration needed to edit the behavior
xml file with groot

* docs: clearer code for first tutorial

Now at the end of the tutorial the entire code that can be copied and pasted
directy to test the demo is provided.
In particular the needed include files are added which are not mentioned along
the tutorial and this spare a little time for new users to figure them out.

* docs: remove blank lines

* docs: little addition to tutorial_02 docs

- Provide a default implementation of `SaySomething2`
- Add Groot support in the xml file

* docs: Add missing SaySimple2

* docs: removed not useful stuff

Co-authored-by: Valerio Magnago <valerio.magnago@fraunhofer.it>
  • Loading branch information
ValerioMagnago and Valerio Magnago authored Sep 1, 2020
1 parent 422fdca commit 479813b
Showing 1 changed file with 45 additions and 15 deletions.
60 changes: 45 additions & 15 deletions docs/tutorial_02_basic_ports.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,27 @@ class SaySomething : public SyncActionNode

```

Alternatively the same functionality can be implemented in a simple function. This function takes an instance of `BT:TreeNode` as input in order to access the "message" Input Port:

```c++
// Simple function that return a NodeStatus
BT::NodeStatus SaySomethingSimple(BT::TreeNode& self)
{
Optional<std::string> msg = self.getInput<std::string>("message");
// Check if optional is valid. If not, throw its error
if (!msg)
{
throw BT::RuntimeError("missing required input [message]: ", msg.error());
}

// use the method value() to extract the valid message.
std::cout << "Robot says: " << msg.value() << std::endl;
return NodeStatus::SUCCESS;
}
```
When a custom TreeNode has input and/or output ports, these ports must be
declared in the __static__ method:
Expand All @@ -109,7 +130,7 @@ check the validity of the returned value and to decide what to do:
- Return `NodeStatus::FAILURE`?
- Throw an exception?
- Use a different default value?

!!! Warning "Important"
It is __always__ recommended to call the method `getInput()` inside the
`tick()`, and __not__ in the constructor of the class.
Expand All @@ -118,11 +139,11 @@ check the validity of the returned value and to decide what to do:
the nature of the input, which could be either static or dynamic.
A dynamic input can change at run-time, for this reason it should be read
periodically.

## Output ports

An input port pointing to the entry of the blackboard will be valid only
if another node have already wrritten "something" inside that same entry.
if another node have already written "something" inside that same entry.

`ThinkWhatToSay` is an example of Node that uses an __output port__ to write a
string into an entry.
Expand Down Expand Up @@ -172,24 +193,31 @@ In this example, a Sequence of 5 Actions is executed:
`SaySomething2` is a SimpleActionNode.

```XML
<root>
<BehaviorTree>
<Sequence name="root">
<SaySomething message="start thinking..." />
<ThinkWhatToSay text="{the_answer}"/>
<SaySomething message="{the_answer}" />
<SaySomething2 message="SaySomething2 works too..." />
<SaySomething2 message="{the_answer}" />
</Sequence>
</BehaviorTree>
</root>
<root main_tree_to_execute = "MainTree" >
<BehaviorTree ID="MainTree">
<Sequence name="root_sequence">
<SaySomething message="start thinking..." />
<ThinkWhatToSay text="{the_answer}"/>
<SaySomething message="{the_answer}" />
<SaySomething2 message="SaySomething2 works too..." />
<SaySomething2 message="{the_answer}" />
</Sequence>
</BehaviorTree>
</root>
```

The C++ code:

```C++
#include "behaviortree_cpp_v3/bt_factory.h"

// file that contains the custom nodes definitions
#include "dummy_nodes.h"

int main()
{
using namespace DummyNodes;

BehaviorTreeFactory factory;

factory.registerNodeType<SaySomething>("SaySomething");
Expand All @@ -202,7 +230,7 @@ int main()
factory.registerSimpleAction("SaySomething2", SaySomethingSimple,
say_something_ports );

auto tree = factory.createTreeFromText(xml_text);
auto tree = factory.createTreeFromFile("./my_tree.xml");

tree.tickRoot();

Expand All @@ -223,3 +251,5 @@ this means that they "point" to the same entry of the blackboard.
These ports can be connected to each other because their type is the same,
i.e. `std::string`.



0 comments on commit 479813b

Please sign in to comment.