CogniTAO C++ Reference

Description: CogniTAO C++ Reference

Keywords: decision_making

Tutorial Level: BEGINNER

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
2. 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'')