MARIE Trunk aabehaviors

From MARIE

Contents 1 Version 2 Description 3 Requirements 4 Inputs 5 Outputs 6 Overview 7 Available behaviors 8 Configuration 8.1 Adapter configuration 8.2 Available logging tag 9 Usage 10 Executing aabehaviors in project 11 Executing aabehaviors with appman [deprecated] 11.1 Start component 11.2 Stop component 11.3 Quit component 12 How to add a behavior in your project 12.1 Autotools based project 12.2 Scons based project 13 Authors 14 Thanks to 15 License

Version

0.1

Description

This AA implements a behavior based decision making module enhanced by a behavior activation mechanism.

At a configurable frequency it outputs the result of a [subsumption] arbitration mechanism applied on commands generated by behaviors.

Behaviors are independent modules that produce motor commands when asked to do so by the arbitration mechanism. Commands are determined according to the information behaviors have about the world (user defined sensory inputs), parameters and activations given in the commandbehavior mandatory input. Only activated behaviors will have the opportunity to compute a command. If a behavior has given a valid command, behaviors with lower priorities are not asked for a command.

Technically, behaviors are plugins which are dynamically loaded at initialization according to configuration. This mechanism allows users to add new behaviors without any modification to the AA.

The configuration of the AA specify behaviors to load and their priority regarding the subsumption mechanism. Moreover a flexible mechanism allow user to specify custom inputs for their behaviors. User defined input are available to behaviors through a shared map associating inputs names with data received on ports.

Requirements

• This AA is built entirely with MARIE components. For now, it is only available in the MARIE SVN trunk version.

See MARIE SVN Trunk Installation Guide

Inputs

The predefined inputs are "hard coded" in the AA and deal with the configuration of the behavior.

1. configuration is used to configure at runtime all the behaviors. The data type used is a DataAssociativeMap which contains the behavior parameters to configure behaviors. Each behavior must implements a configure method which will look for specific parameters in the DataAssociativeMap and properly configure the behavior.
2. loggerconfig is used to configure logging entities at runtime. When a DataAssociativeMap is received on this port, logging entites associated with tags corresponding to map's keys are configured with the map's values as custom configuration string.

The user defined inputs allow to customize the stimuli of the behavior layer. When a data is received on an input, it is stored in a pool of avialable inputs which can be accessed by all behaviors. Each behavior must implements an input fetching method which should validate the proper state of the required inputs. User defined input commandbehavior is mandatory and must be defined in the AA's configuration. That input use a BehaviorsCommand datatype to specify the activation of the behaviors.

See anatomy of a behavior for more details.

Outputs

The adapter has three optional outputs :

1. commandmotor is the desired cinematic value determined by the subsumption arbitration mechanism at each iteration. The CommandMotor datatype is used.
2. exploitation is a copy of the input commandbehavior used for the arbitration which is added with the exploitation and results of the selected behavior.
3. debug output a DataAssociativeMap datatype which contains internal variables value of the behavior that are usefull for the debugging process of a behavior. See PROBE_DEBUG.h to see the handy inline functions available to modify the contains of the output.

Overview

http://marie.sf.net/explorer/aaBehaviors/images/aaBehaviors.jpg

Available behaviors

The following table list all the supported behaviors:

Behavior Type	Description
Idle	This behavior keeps the vehicle from moving. Linear and rotation velocities produced are always 0.
GoForward	This behavior makes the vehicle go forward. Linear velocity depends on parameter received on commandbehavior input or configuration.
Obey	This behavior makes the vehicle obey to a string parameter given in input.
AvoidLaser	This behavior makes the vehicle (sometimes) avoid obstacles according to laser readings.
Teleop	This behavior takes an CommandMotor input and apply it as the behavior output. It can be use to connect a joystick in order to teleoperate a vehicle.

User can develop their own behaviors and use them with the adapter (see this section).

Configuration

Note : see Configuration Description Language for syntax details.

Adapter configuration

# C aabehaviors

   # C adapter
      o KV  frequency
   
      # Q behaviors
         o T behavior
            # KV type
            * KV Behavior's specific KV configuration elements
 
      # Q inputsBinding
          * KV Key: [input port name] Value: [variable name] 

      o Q inputs
         o T port (type = Default, name = user defined)
         o T port (type = Default, name = configuration)
   
      o Q outputs
         o T port (type = Default, name = commandmotor)
         o T port (type = Default, name = exploitation)
         o T port (type = Default, name = debug)

• frequency : Output frequency of the aabehavior in ms.

• Q behaviors regroups all the behavior use in the aabehaviors (Most prioritised behavior is declare first and so on)
  • Each behavior is a T which have:
    • type: behavior type name (ex.: Idle)
    • Behavior's specific KV elements (see behaviors documentation for details)

• Q inputsBinding allows to store incoming data on a user defined input port in a variable which is accessible by all behavior. (See behaviors documentation to know what variable they need.)
  • Key: name of the user defined input port
  • Value: variable name to store incoming data

• Q inputs regroups all the desired inputs of the aabehaviors
  • user defined input port : port with a user defined name (commandbehavior is the name to use to activate the behaviors)
  • configuration input port : port receiving behavior configuration request

• Q outputs regroups all the desired outputs of the aabehaviors
  • commandmotor output port : port sending CommandMotor
  • exploitation output port : port sending the exploited behavior (BehaviorsCommand)
  • debug output port : port sending the debug information store in a DataAssociativeMap (See PROBE_DEBUG.h for details)

See available Ports for port configuration details.

Available logging tag

Tag	Level	Format	Filename
AABehaviors.Behaviors.[BehaviorType].behave	[DEBUG, WARNING, ERROR]	string	BehaviorsAbstract.cpp
AABehaviors.Behaviors.[BehaviorType].configure	[DEBUG]	string	BehaviorsAbstract.cpp
AABehaviors.Behaviors.[BehaviorType].fetchInputs	[DEBUG, WARNING, ERROR]	string	BehaviorsAbstract.cpp
AABehaviors.Appman.abort	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Appman.configure	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Appman.init	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Appman.quit	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Appman.reset	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Appman.resume	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Appman.start	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Appman.stop	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Appman.suspend	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Arbitration	[DEBUG, WARNING]	string	BehaviorsComponentHandler.cpp
AABehaviors.ArbitrationData	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.ArbitrationData.BehaviorsCommand	[INFO]	DataAbstract	BehaviorsComponentHandler.cpp
AABehaviors.ArbitrationData.CommandMotor	[INFO]	DataAbstract	BehaviorsComponentHandler.cpp
AABehaviors.ArbitrationData.DebugProbe	[INFO]	DataAbstract	BehaviorsComponentHandler.cpp
AABehaviors.ArbitrationData.Input.[InputName]	[INFO]	DataAbstract	BehaviorsComponentHandler.cpp
AABehaviors.CommReceiver.BehConfig	[DEBUG, WARNING]	string	BehaviorsComponentHandler.cpp
AABehaviors.CommReceiver.Input	[DEBUG, WARNING]	string	BehaviorsComponentHandler.cpp
AABehaviors.CommReceiver.InputData.[InputName]	[DEBUG]	DataAbstract	BehaviorsComponentHandler.cpp
AABehaviors.Init	[DEBUG, INFO, ERROR]	string	BehaviorsComponentHandler.cpp
AABehaviors.Init.Behaviors	[INFO]	string	BehaviorsComponentHandler.cpp
AABehaviors.Init.Input	[INFO, ERROR]	string	BehaviorsComponentHandler.cpp
AABehaviors.Init.Output	[INFO, WARNING]	string	BehaviorsComponentHandler.cpp
AABehaviors.Init.Visitor	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Request.BehConfig.create	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Request.BehConfig.delete	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Request.BehConfig.call	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Request.Input.create	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Request.Input.delete	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Request.Input.call	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Request.Quit.create	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Request.Quit.delete	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Request.Quit.call	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Request.Output.create	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Request.Output.delete	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.Request.Output.call	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.RequestHandler.BehConfig	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.RequestHandler.BehConfig.Data	[INFO]	DataAbstract	BehaviorsComponentHandler.cpp
AABehaviors.RequestHandler.Input.[InputName]	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.RequestHandler.InputData.[InputName]	[DEBUG]	DataAbstract	BehaviorsComponentHandler.cpp
AABehaviors.RequestHandler.Output	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.RequestHandler.Output.BehaviorsCommand	[DEBUG, WARNING]	string	BehaviorsComponentHandler.cpp
AABehaviors.RequestHandler.Output.CommandMotor	[DEBUG, WARNING]	string	BehaviorsComponentHandler.cpp
AABehaviors.RequestHandler.Output.ProbeDebug	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.RequestHandler.Timeout	[DEBUG]	string	BehaviorsComponentHandler.cpp
AABehaviors.BehaviorsFactory.addBehaviorsPath	[DEBUG, INFO]	string	BehaviorsFactory.cpp
AABehaviors.BehaviorsFactory.createBehaviors	[DEBUG, WARNING, ERROR]	string	BehaviorsFactory.cpp
AABehaviors.BehaviorsFactory.deleteBehaviors	[DEBUG, WARNING]	string	BehaviorsFactory.cpp
AABehaviors.BehaviorsFactory.loadAllBehaviors	[DEBUG, INFO, ERROR]	string	BehaviorsFactory.cpp
AABehaviors.BehaviorsFactory.registerBehaviors	[INFO, ERROR]	string	BehaviorsFactory.cpp
AABehaviors.InputsContainer.addInputEntry	[DEBUG, ERROR]	string	BehaviorsInputContainer.cpp
AABehaviors.InputsContainer.getInputReference	[DEBUG, ERROR]	string	BehaviorsInputContainer.cpp
AABehaviors.InputsContainer.setInputValue	[DEBUG, ERROR]	string	BehaviorsInputContainer.cpp
AABehaviors.Behaviors.[BehaviorType].visitor	[DEBUG, WARNING, ERROR]	string	BehaviorsVisitor.cpp
AABehaviors.Init.Visitor	[DEBUG, WARNING, ERROR]	string	BehaviorsVisitorAdapterConfiguration.cpp

Usage

usage :  aabehaviors -n component_name [-t component_type] [-d director_port_number] [-c configurator_port_number]

      -n     #Specify component's name
              
      -t     #Specify component's control type :
             #  DEFAULT - use when controlled by appman Application Manager (default)
             #  MPI     - use when controlled by ammpi Application Manager
               
      -d     #Specify director server socket port number (mandatory in DEFAULT component's control type)
      -c     #Specify configurator server socket port number (mandatory in DEFAULT component's control type)

Executing aabehaviors in project

This section shows how to use aabehaviors in a Project..

In .setup file, add the following process :

aabehaviors

# T process
   # KV name
   # KV type = MARIE:MPI
   # KV executableName = aabehaviors
  
   # KV configFile

• name : Specify a reference name for the process
• type : Specify component's control type
• executableName : Specify the executable name
• configFile : Specify path to aabehaviors configuration file (see Configuration)

Executing aabehaviors with appman [deprecated]

This section shows how to use aabehaviors with appman Application Manager from a terminal script.

Start component

aabehaviors -n component_name -t MARIE -d director_port_number -c configurator_port_number
sleep 4    # Sleep time (plateform specific)

appman -p configurator_port_number -c sxml:PathToConfigFile
sleep 1    # Sleep time (plateform specific)

appman -p director_port_number -c init
sleep 1    # Sleep time (plateform specific)

appman -p director_port_number -c start

Component can take couple of seconds to boot, configure and initialize before being ready to receive requests on director and configurator ports. Delays are required and must be adjusted depending on the running platform.

Stop component

appman -p director_port_number -c stop
sleep 1    # Sleep time (plateform specific)

Component can take couple of seconds to stop before being ready to receive requests on director and configurator ports. Delay is required and must be adjusted depending on the running platform.

Quit component

appman -p director_port_number -c quit

How to add a behavior in your project

Autotools based project

• Add MARIE detection and variable substitution in your configure.ac :

dnl Check for marie
PKG_CHECK_MODULES(MARIE,[marie >= 0.5], MARIE_FOUND="yes", MARIE_FOUND="")

if test "$MARIE_FOUND" = "yes"; then
   
   MARIE_INCLUDES=$MARIE_CFLAGS
   AC_SUBST(MARIE_INCLUDES)
   AC_SUBST(MARIE_LIBS)
else
   echo 
   echo "error : marie not found. Is marie.pc in your pkg-config search path ?"
   exit
fi

dnl Check for mariebehaviors
PKG_CHECK_MODULES(MARIE_BEHAVIORS,[mariebehaviors >= 0.5], MARIE_BEHAVIORS_FOUND="yes", MARIE_BEHAVIORS_FOUND="")

if test "$MARIE_BEHAVIORS_FOUND" = "yes"; then
   
   MARIE_BEHAVIORS_INCLUDES=$MARIE_BEHAVIORS_CFLAGS
   AC_SUBST(MARIE_BEHAVIORS_INCLUDES)
   AC_SUBST(MARIE_BEHAVIORS_LIBS)
else
   echo 
   echo "error : mariebehaviors not found. Is mariebehaviors.pc in your pkg-config search path ?"
   exit
fi

• In the Makefile.am of your behavior sources add :

INCLUDES = $(MARIE_INCLUDES) $(MARIE_BEHAVIORS_INCLUDES)

lib_LTLIBRARIES = libmariebehaviors_BehaviorName.la

libmariebehaviors_BehaviorName_la_SOURCES = BehaviorName.cpp

libmariebehaviors_BehaviorName_la_LIBADD = $(MARIE_LIBS) $(MARIE_BEHAVIORS_LIBS)

include_HEADERS = BehaviorName.h

Scons based project

Authors

• Patrick Frenette
• Clement Raievsky

Thanks to

• Carle Cote

License

MARIE - Mobile and Autonomous Robotics Integration Environment Copyright (C) 2004-2007 Patrick Frenette, Clement Raievsky

This library and its documentation are free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library and documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You can contact MARIE development team at http://marie.sourceforge.net.