## For instruction on writing tutorials ## http://www.ros.org/wiki/WritingTutorials #################################### ##FILL ME IN #################################### ## for a custom note with links: ## note = ## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links ## note.0=[[decision_making/Tutorials/CogniTAO]] ## descriptive title for the tutorial ## title = CogniTAO C++ Reference ## multi-line description to be displayed in search ## description = CogniTAO C++ Reference ## the next tutorial description (optional) ## next = ## links to next tutorial (optional) ## next.0.link= ## next.1.link= ## what level user is this tutorial for ## level= BeginnerCategory ## keywords = decision_making #################################### <> <> == Introduction == This page includes a Reference manual to TAO C++ syntax. If you wish to get an overview of several TAO examples go to one of the links below == TAO Machine definition == TAO's are defined in a CPP file, and declared in the header file. === TAO === TAO(''TAO_NAME''){ ... } . TAO machine definition === TAO_HEADER === TAO_HEADER(''TAO_NAME''); . TAO machine declaration in header (.h) files. == TAO State definition == === TAO_PLANS === TAO_PLANS{ ''PLAN_1'', ''PLAN_2'', ... } . List of plans. Must be located before TAO_START_PLAN === TAO_START === TAO_START_PLAN(''PLAN_NAME''); . Select start plan. Must be located before TAO_BGN === TAO_BGN - TAO_END === TAO_BGN{ ''PLANS'' }TAO_END . TAO logic description === TAO_PLAN === TAO_PLAN(''PLAN_NAME''){ . <
> ''START_CONDITION'' . <
> ''SUBPLAN_ALLOCATION'' . <
> ''ON_ENTRY_AND_EXIT_ACTIONS'' . <
> ''STOP_CONDITION'' . <
> ''NEXT_PLAN'' . <
> } . Description of one plan. Must be located inside of TAO_BGN-TAO_END block. All ''CALLs'' defined in ''ON_ENRTY_ACTION'' section run in parallel. == TAO Conditions == === TAO_START_CONDITION === TAO_START_CONDITION(''CONDITION'') . Start condition of plan. It's validated before the plan is selected for running. Must be located immediately after TAO_PLAN. === TAO_STOP_CONDITION === TAO_STOP_CONDITION(''CONDITION'') . Stop condition of plan. It's validated all the time* during the plan is running. Must be located before TAO_NEXT block. . <
>* : for each event == TAO Protocols == === TAO_NEXT === TAO_NEXT(''PROTOCOL''){ ''OPTIONS'' } . After ''STOP_CONDITION'' is satisfied, apply ''PROTOCOL'' for select next plan for execution. Must be located after TAO_STOP_CONDITION. TAO_NEXT_PLAN(''PLAN'') . Optional ''PLAN'' in current TAO for next selection. Must be located in TAO_NEXT block. === TAO_ALLOCATE === TAO_ALLOCATE(''PROTOCOL''){ ''OPTIONS'' } . After plan start running, apply allocation protocol for select one subgraph for execution. Must be located between START/STOP conditions. TAO_SUBPLAN(''TAO'') . Optional ''TAO'' for sub-plan selection. The real sub-plan is a start plan of selected ''TAO''. Must be located inside TAO_ALLOCATE block. == TAO Events == ''EventQueue'' is a events distribution system. * It's used for sharing events inside of TAO/HSM/BT machines. * It's possible to insert external events to the system (from ROS or other custom source). * It's thread safe. Each Event is a path containing: * all context names * when this event was created * an event short name at the end. Example: /Con/tex/Na/me/EventName. When you compare two events you can use Regular Expressions as the name of one event by writing @ on the begging of the name. Example: @/Con/.*/Event[NT]...e Events usage : (STOP event for example) . Outside of TAO: . Event e("/STOP") . global / without context Event e("STOP",call_context) . related to call_context events->raiseEvent(e); . raise event Inside of TAO: . TAO_RAISE(/STOP) . raise global event TAO_RAISE(STOP) . raise related to TAO context (without name of state) event TAO_RAISE(PLAN_NAME/STOP) . raise related to TAO PLAN context event TAO_STOP_CONDITION(event==TAO_EVENT(STOP)) . check condition. if satisfied ''do something'' TAO_EVENTS_DROP . clear current events queue Interface: . ''Event waitEvent()'' . blocked function up to new event arrived. ''Event tryGetEvent(bool& success)'' . unblocked function for get new event if exists ''void drop_all()'' . clear queue ''void close()'' . close event system. release all waited processes. ''bool isTerminated()const'' . check if event system is closed. ''spinOne()'' . send one /SPIN event for validation of STOP conditions. ''spin(double rate_in_hz = 10)'' . run spinOne() command with ''rate_in_hz'' ''async_spin(double rate_in_hz = 10, double start_delay=0)'' . run spin command after ''start_delay'' without blocking current code execution. Common extensions : . ''RosEventQueue'' is a connection of Ros (/decision_making/NODE_NAME/events topic) and internal EventQueue. Must be created after ''ros::init'' and ''ros_decision_making_init''. === TAO_RAISE === TAO_RAISE(''EVENT'') . Raise event to events publication system. This macro can be ''reaction'' for TAO_ON_EVENT or TAO_ON_CONDITION and can be ''on_entry_action'' inside TAO_PLAN block === TAO_EVENTS_DROP === TAO_EVENTS_DROP; . Clear events queue for current state. It's optional command. Must be located before TAO_TRANSITIONS. === TAO_EVENT === TAO_EVENT(''EVENT'') . Create decision_making::Event object with current CallContext. Can be usefull with TAO_ON_CONDITION with local special variable ''event'' Example: . TAO_STOP_CONDITION(event!=TAO_EVENT("/STOP")); == TAO Actions == === TAO_CALL_TASK === TAO_CALL_TASK(''TASK_NAME'') . call remote or local task or external robot_task client (actionlib http://wiki.ros.org/actionlib) or registred local function. === TAO_CALL_TAO === TAO_CALL_TAO(''TAO_NAME'') . call other TAO === TAO_CALL_BT === TAO_CALL_BT(''BT_NAME'') . call BehaviorTree === TAO_CALL_FSM === TAO_CALL_FSM(''FSM_NAME'') . call FSM === TAO_CLEANUP === TAO_CLEANUP_BGN{ ... }TAO_CLEANUP_END . Reaction on exit from current state. Must be located in TAO_PLAN block before TAO_STOP_CONDITION. Contains c++ code, TAO_CALL_* and TAO_RAISE macros. Plan transition will be blocked up to all calls in the block is finished. === TAO_RESULT === TAO_RESULT(''EVENT'',''RESULT'') . Stop TAO, raise event ''EVENT'' to global events system and return ''RESULT'' as result of TAO function. === Call TAO === TAO is a function with signature: {{{ TaskResult TaoNAME(const CallContext* ctx,EventQueue* events); }}} This function is blocked up to TAO is finished (preempted, stopped by TAO_RESULT or EventQueue is closed). So, just call this function. If you need special rates for decision making (stop conditions validation) use EventQueue::spin, spinOne or async_spin methods. . Parameters: . ''const CallContext* ctx'' : pointer to current context. Can be NULL. ''EventQueue* events'' : pointer to events system. Can not be NULL. == CallContext == This is a class for shearing parameters and context information through calls of TAO/HSM/BT machines. Interface: . ''void push(string name)'' . add new context name ''void pop()'' . remove last context name ''void createParameters(A* a= new A())'' . create parameter object of type A (template) ''bool isParametersDefined()const'' . check if parameters created ''A& parameters()const'' . get parameters. if not defined throw exception. ''A& parameters()'' . get parameters. if not defined create default instance. == Tasks == Task is an atomic preemptable action. decision making supports two types of Tasks 1. ROS remote task 1. Local task === ROS remote task === Special Activelib client. For create this kind of task, you need extend RobotTask class from robot_task package. === Local task === It's a callback function: {{{ TaskResult FUNCTION_NAME( string task_name, const CallContext& context, EventQueue& events) }}} You need to registrate local task before usage (otherwise, the system assumes that the task is remote). {{{ LocalTasks::registrate(''TASK_NAME'', ''CALLBACK'') }}} ## AUTOGENERATED DO NOT DELETE ## TutorialCategory ## FILL IN THE STACK TUTORIAL CATEGORY HERE