initial documentation

Author: Davide Faconti

docs/02_BT_description.md

@@ -0,0 +1,146 @@
+# Introduction to BTs
+
+Unlike a Finite State Machine, a Behaviour Tree is a __tree of hierarchical nodes__ 
+that controls the flow of decision and the execution of "tasks" or, as we
+will call them further, "__Actions__".
+
+The __leaves__ of the tree are the actual commands, ie.e the place where
+our coordinating component interacts with the rest of the system.
+
+For instance, in a service-oriented architecture, the leaves would contain
+the "client" code that triggers an action.
+
+All the other nodes of the tree, those which are not leaves, control the 
+"flow of execution".
+
+To better understand how this flow takes place , imagine a signal, that we will further
+call "__tick__" that is executed at the __root__ of the tree and propagates through
+the branches until it reaches a leave.
+
+The result of a tick can be either:
+
+- __SUCCESS__
+- __FAILURE__
+- __RUNNING__
+
+The first two, as their names suggest, inform their parent that their operation
+ was a success or a failure.
+The latter usually means that the execution of the TreeNode is not completed
+and it needs more time to return a valid result.
+
+The result of a node is propagated back to the parent, that will decide
+which child should be ticked next or will return a result itself.
+
+## Types of nodes
+
+__ControlNodes__ are nodes which can have 1 to N children. Once a tick
+is received, this tick may be propagated to one or more of the children.
+It must be noted that children are always __ordered__, but it is up to the
+type of control node to decide if they are ticked in the given order.
+
+__DecoratorNodes__ can have only a single child. Their function is either 
+to transform the result they receive from the child, to terminate the child, 
+or repeat processing of the child, depending on the type of decorator.
+
+__ActionNodes__ are leaves and do not have children. The user should implement
+their own ActionNodes that perform the actual task.
+
+__ConditionNodes__ are equivalent to ActionNodes, with the exeption that
+they are alwais aotmic (they should not return RUNNING) and they should not 
+alter the state of the system.
+
+![UML hierarchy](images/TypeHierarchy.png)
+
+!!! warning
+    Actions and Conditions differ only in terms of __semantic__, the C++
+    framework can not enforce it unfortunately.
+
+## Learn by example
+
+To better understand how a BehaviorTree works let's focus on some practical
+examples. For the sake of simplicity we will not take into account what happens
+when an action return RUNNING.
+
+We will assume that each Action is executed atomically and synchronously.
+In future sections we will more thoughtfully analyze asynchronous actions.
+
+### Sequence
+
+Let's illustrate how a BT works using the most basic and frequently used 
+ControlNode: the [SequenceNode](SequenceNode.md).
+
+![Simple Sequence: fridge](images/SequenceBasic.png)
+
+It is important to notice that the children of a ControlNode are __ordered__.
+In this case the order of execution is __from left to right__.
+
+A Sequence works as described next:
+
+- If a child returns SUCCESS, tick the next one.
+- If a child returns FAILURE, then no more children are ticked and the Sequence returns FAILURE.
+- If all the children return SUCCESS, then the Fallback returns SUCCESS too.
+
+In this particular case, if the action __GrabBeer__ failed, the door of the fridge would
+remain opened, since the last action __CloseDoor__ is skipped.
+
+Let's take into accound another example:
+
+![Simple Sequence: Enter Room](images/Sequence2.png)
+
+In this case __Negation__ is a [DecoratorNode](DecoratorNode.md) that inverts 
+the result returned by its child. 
+
+This means that a Negation followed by the ConditionNode called
+__DoorOpen__ is equialent to "is the door closed?".
+
+As a result, the branch on the right side means: 
+
+    "If the door is closed, then open it".
+
+### Fallback
+
+[FallbackNodes](FallbackNode.md), known also as __"Selector"__ in the literature,
+Is a node that is used to express, as the name suggests, fallback strategies, 
+ie. what to do if a child return FAILURE.
+
+In short, it ticks the children in order, as usual from left to right and:
+
+- If a child returns FAILURE, tick the next one.
+- If a child returns SUCCESS, then no more children are ticked and the Fallback returns SUCCESS.
+- If all the children return FAILURE, then the Fallback returns FAILURE too.
+
+In the next example, you can see how Sequence and Fallbacks can be combined:
+
+    "Try to open the door, 
+    otherwise unlock it with a key (if you have it), 
+    otherwise smash it. 
+    If any of these actions succeeded, then enter the room".
+    
+![FallbackNodes](images/FallbackBasic.png)  
+
+### "Fetch me a beer" revisited
+
+We can now improve the previous example, which attempted to
+grab a beer from the fridge but left the door open if the beer was not there.
+
+In the next picture we use the color green to represent nodes which will return
+SUCCESS and red for those which return FAILURE.
+
+The action __GrabBeer__ will always fail.
+
+
+![FetchBeer failure](images/FetchBeer.png)
+
+Both the trees will close the door of the fridge, eventually, but:
+
+- the tree on the __left__ side will always return SUCCESS if we managed to
+ open and clode the fridge.
+- the tree on the __right__ side will return SUCCESS if the beer was there, 
+FAILURE otherwise.
+
+We can easily double-check what happen if __GrabBeer__ returns SUCCESS.
+
+![FetchBeer success](images/FetchBeer2.png)
+
+
+

docs/images/FallbackBasic.png

@@ -0,0 +1,89 @@
+
+# Home
+
+## About this library
+
+This  __C++__ library provides a framework to create BehaviorTrees.
+It was designed to be flexible, easy to use and fast.
+
+Even if out main use-case is __robotics__, you can use this library to build
+__AI for games__, or to replace Finite State Machines in you application with a
+more intuitive approach that focus on the execution of tasks, rather than a change in state.
+
+__BehaviorTree.CPP__ has many interesting features:
+
+- It makes asynchronous Actions, i.e. non-blocking, a first-class citizen.
+- It allows the creation of trees at run-time, using a textual representation (XML).
+- You can link staticaly you custom TreeNodes or convert them into plugins 
+which are loaded at run-time.
+- It includes a __logging/profiling__ infrastructure that allows the user 
+to visualize, record, replay and analyze state transitions.
+
+## The problem
+
+Many software systems, being robotics a notable example, are inherently
+complex.
+
+The usual approach to manage complexity, heterogeneity and scalability is to 
+use the concept of 
+[Component Base Software Engineering](https://en.wikipedia.org/wiki/Component-based_software_engineering).
+
+
+Any existing middleware for robotics took this approach either informally or formally,
+being [ROS](www.ros.org), [YARP](www.yarp.it) and 
+[SmartSoft](http://www.servicerobotik-ulm.de) some notable examples.
+
+A "good" software architecture should have the following characteristics:
+
+- Modularity.
+- Reusability.
+- Composability.
+- Good separation of concerns. 
+
+If we don't keep these concepts in mind from the very beginning, we create 
+software modules/components which are highly coupled to a particular application,
+instead of being reusable.
+
+Frequently ,the concern of __Coordination__ is mixed with __Computation__. 
+In other words, people address the problems of coordinating actions and take decisions
+locally.
+
+The business logic becomes spread in many locations and it is hard for the developer
+to reason about it and to degub errors in the control flow.
+
+A better solution is to have a strong separation of concern and to centralize
+as much as possible the business logic in a single location. 
+
+Finite State Machines were created specifically with this goal in mind, but in
+the recent years Behavior Trees gained popularity, especially in the game industry.
+
+
+## What is a Behavior Tree?
+
+A Behavior Tree (__BT__) is a way to structure the switching between different 
+tasks in an autonomous agent, such as a robot or a virtual entity in a computer game.
+
+BTs are a very efficient way of creating complex systems that are both modular and reactive. 
+These properties are crucial in many applications, which has led to the spread 
+of BT from computer game programming to many branches of AI and Robotics. 
+ 
+If you are already familiar with Finite State Machines (__FSM__), you will
+easily grasp most of the concepts but, hopefully, you will  find that BTs
+are more expressive and easier to reason about.
+
+The main advantages of Behavior Trees, when compared to FSMs are:
+
+- __They are intrinsically Hierarchical__: this means that we can _compose_
+complex behaviors including entire trees as sub-branches of a bugger one. 
+For instance, the behavior "Fetch Beer" may reuse in one of its nodes the tree
+"Grasp Object".
+
+- __Their graphical representation has a semantic meaning__: it is easier to 
+"read" a BT and understand the corresponding workflow. 
+State transitions in FSMs, by comparisons, are harder to understand
+both in their textual and graphical representation.    
+
+- __They are more expressive__: Ready to use ControlNodes and DecoratorNodes
+make possible to express more complex control flows. The use can extend the
+"vocabulary" with his/her own custo nodes.
+