From 479813b098337654616f438bcb2eb80e249dfe7a Mon Sep 17 00:00:00 2001 From: Valerio Magnago Date: Tue, 1 Sep 2020 15:37:17 +0200 Subject: [PATCH] docs: Small changes to tutorial 02 (#225) * 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 --- docs/tutorial_02_basic_ports.md | 60 ++++++++++++++++++++++++--------- 1 file changed, 45 insertions(+), 15 deletions(-) diff --git a/docs/tutorial_02_basic_ports.md b/docs/tutorial_02_basic_ports.md index 2d841b54131730..d5d9aee299c490 100644 --- a/docs/tutorial_02_basic_ports.md +++ b/docs/tutorial_02_basic_ports.md @@ -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 msg = self.getInput("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: @@ -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. @@ -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. @@ -172,24 +193,31 @@ In this example, a Sequence of 5 Actions is executed: `SaySomething2` is a SimpleActionNode. ```XML - - - - - - - - - - - + + + + + + + + + + + ``` 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"); @@ -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(); @@ -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`. + +