HowTo use CommLang in your team
===================================
Created 2006-09-25 by David Landén
Last updated 2006-09-25 by Fredrik Heintz

The purpose of this HowTo is to describe how to get started using
CommLang in your team that you have already started (if you creata a
new team from the RoboSoc templates then you do not need to worry
about step 1-5).


1. Modify the configure.ac file for the Team assignment:

    > cd ~/Team
    > emacs configure.ac &
   
   Paste the following section into the configure.ac file, somewhere
   after the line with AC_SUBST(ROBOSOCDIR) (line ~157).

COMMLANG_INCLUDEPATH=${ROBOSOCDIR}/Framework/CommLang
COMMLANG_LIBPATH=${ROBOSOCDIR}/Framework/CommLang
AC_SUBST(COMMLANG_INCLUDEPATH)
AC_SUBST(COMMLANG_LIBPATH)


2. Modify the Makefile.am for the Team assignment:

    > cd ~/Team/src
    > emacs Makefile.am &

   Add @COMMLANG_INCLUDEPATH@ to the INCLUDES section. The section
   should look like:

INCLUDES = -I@RSVIEW_INCLUDEPATH@ -I@RSSKILL_INCLUDEPATH@ \
	-I@RSPREDICATE_INCLUDEPATH@ -I@RSSTRATEGY_INCLUDEPATH@ \
	-I@RSLIBRARY_INCLUDEPATH@ -I@RSBASICSYSTEM_INCLUDEPATH@ \
	-I@RSFRAMEWORK_INCLUDEPATH@ -I@RCCPARSER_INCLUDEPATH@ \
	-I@RSSS_INCLUDEPATH@ -I@COMMLANG_INCLUDEPATH@


3. Generate the configure-script

    > cd ~/Team
    > ./bootstrap

    
4. Run the configure script to generate the makefiles

    > ./configure


5. Make your decision maker inherit from FrameworkDecision instead of
   Decision.

   > emacs ~/Team/src/TeamDecision.h

   Include FrameworkDecision.h instead of Decision.h (line 42)
   replace
    #include "Decision.h"
   with
    #include "FrameworkDecision.h"
    
   Inherit from FrameworkDecision instead of Decision (line 66)
   replace
    class TeamDecision : public Decision {
   with
    class TeamDecision : public FrameworkDecision {

    
   > emacs ~/Team/src/TeamDecision.cc

   Initialize FrameworkDecision instead of Decision (line 54)
    replace
     : Decision(actuator_interface),
    with
     : FrameworkDecision(actuator_interface),


6. To parse the CommLang messages you have to implement
   onAuralPlayerSensorData to decode the message using the CommLang
   decoder and implement the appropriate callbacks.

   The following code decodes the message as soon as it arrives:
   void
   TeamDecision::onAuralPlayerSensorData()
   {
     const WorldObservation& wo = worldModelInterface->getObservation();
     if ( wo.teammateSpeakers.size() > 0 ) {
       decodeCommLangMsg(wo.teammateSpeakers[0], wo.teammateMessage);
     } else {
      RS_LOG( LA_DECISION, "heard message but do not know from whom" );
     }
   }

   The following methods can be added the TeamDecision.h and
   implemented in TeamDecision.cc to handle the information received
   from your teammates:
   virtual void onBallPos(int sender_unum, const Point& pos, int cycle_no);
   virtual void onBallVel(int sender_unum, const Vector& vel, int cycle_no);
   virtual void onOurPos(int sender_unum, const Point& pos);
   virtual void onOppPos(int sender_unum, int opp_unum,
	 		 const Point& pos, int cycle_no);
   virtual void onTeammatePos(int sender_unum, int teammate_unum,
			      const Point& pos, int cycle_no);
   virtual void onWeHaveBall(int sender_unum);
   virtual void onWeHaveBall(int sender_unum, int teammate_unum);
   virtual void onOppHaveBall(int sender_unum);
   virtual void onOppHaveBall(int sender_unum, int teammate_unum);
   virtual void onPassToPlayer(int sender_unum, int teammate_unum);
   virtual void onPassToCoord(int sender_unum, const Point& pos);
   virtual void onWantPass(int sender_unum);

       
7. Add code for encoding messages in your team

   To add a say command which encodes the ball position to an agent
   step use the following code.

   #include "SayMsgEncoder.h"
      
   const WorldModelInterface* wmi = WorldModelInterface::instance();
   const WorldModel& wm = wmi->getWorld();
   const BallObject& ball = wm.getBall();
   SayMsgEncoder *myencoder = new SayMsgEncoder();
   if ( ball.getPosition().isKnown() and ball.getObservationTime().isKnown() ) {
     Point ball_pos = ball.getPosition().getPoint();
     Time cycles = wmi->getCurrentTime() - ball.getObservationTime().getTime();
     bool rtn = true;
     rtn = myencoder->add( new BallPos(ball_pos.getX(),ball_pos.getY(), cycles.getT()) );
     if ( rtn ) {
       std::string str = myencoder->getEncodedStr();
       step.setSayCommand(new SayCommand(str));
     } else {
       RS_LOG( LA_DECISION, "Failed to encode ball pos" );
     }
     myencoder->clear();
   }

   Don't forget to send the step when you've added the say command.
   
    
8. Recompile the team

    > make