Generated from liblanguage.summary with ROBODoc v3.2.2 on Mon Sep 11 15:48:19 2000

TABLE OF CONTENTS

  1. language/_module
  2. language/langEvent
  3. language/langEventAny
  4. language/langEventAskTrack
  5. language/langEventCommand
  6. language/langEventPing
  7. language/langEventPlayMode
  8. language/langEventPong
  9. language/langEventPowerStatus
  10. language/langEventText
  11. language/langEventTrack
  12. language/langEventUnknown
  13. language/lang_angle2deg
  14. language/lang_angle2rad
  15. language/lang_deg2angle
  16. language/lang_init
  17. language/lang_messageWaiting
  18. language/lang_rad2angle
  19. language/lang_receive
  20. language/lang_release
  21. language/lang_send
  22. language/lang_sendFlush
  23. language/lang_transCmd
  24. language/lang_transName
  25. language/lang_transPri
  26. language/lang_transType
  27. language/pack
  28. language/unpack

language/_module

NAME

   The CIIPS Glory soccer language library

DESCRIPTION
   Simple but effective and flexible standard for inter-robot and
   Master control Program (MCP) communications.

   Use this library to communicate internally between robots and
   from the overhead tracking system to the robots.

   All coordinates are gived in millimeters, where positive Y runs
   from origo to opponents goal, and positive X runs from origo to
   the right when seen from the home goal.

       [opponent]
           +

           |
           Y
           |
      - ---+-X- +
           |
           |
           |

           -

         [home]

   Velocity is given in mm/second. Angles are anticlockwise and the
   unit is radians * 1024.  Global angles are gives relative to the
   positive X axes.

   The API is described in parselanguage.h, and the events are
   described in language.h.

   Protocol:

     |<timestamp>|<size><type><type-data>|<size><type><type-data>...|

   size is number of bytes following the size byte (sizeof(<type>) +
   sizeof(<type-data>).  All types are packed as mc68k endian.

EXAMPLE
      void my_lang_handler(langEvent *event, void *ref)
      {
         ...
      }
      ...
      lang_channel channel;
      ...
      channel = lang_init();
      if (0 == channel)
        fatalerror();
      while (!done)
        {
          int robotid;
          void *ref;
          ...
          for (robotid = 0; robotid < maxrobots; robotid++)
            {
               langEventTrack event;
               fillRobotInfo(event, robotid);
               lang_send(channel, (langEvent*)&event);
            }
          lang_sendFlush(channel);
          ...
          if (lang_messageWaiting(channel))
             lang_receive(channel, my_lang_handler, ref);
        }
      lang_release(channel);

 AUTHOR:
    Stephen Humble - initial list of messages (2000)
    Petter Reinholdtsen - language API and message packing/unpacking. (2000)

language/langEvent

DESCRIPTION
   The 'super type' of all event structs.  A union of all langEvent
   structs.  The 'type' member is the event type.  These are named
   langTypeName where 'Name' matches the event name.  Type in a
   langEventPing event would then be langTypePing.
SOURCE
    typedef union {
      unsigned char type;
      langEventAny any;
    
      langEventPing ping;
      langEventPing pong;
      langEventTrack track;
      langEventCommand command;
      langEventPowerStatus powerstatus;
      langEventText text;
      langEventPlayMode playmode;
    
      /* Unhandled at the moment */
      langEventAskTrack    asktrack;
    
      langEventUnknown unknown;
    } langEvent;
    
    enum {
      langTypeCommand     = 'C',
      langTypeText        = 'd',
      langTypePing        = 'p',
      langTypePong        = 'P',
      langTypeAskTrack    = 't',
      langTypeTrack       = 'T',
      langTypeUnknown     = 'u',
      langTypePowerStatus = 'w',
      langTypePlayMode    = 'm'
    };    

language/langEventAny

DESCRIPTION
   The common members in all event structs.  Time is measured in
   1/100 seconds since some time in the past.  Each sender might use
   different reference time.
SOURCE
    typedef struct {
      unsigned char type;
      int timestamp;
      unsigned char to;
      unsigned char from;
    } langEventAny;

language/langEventAskTrack

DESCRIPTION
   Request for track event.  Used to prompt another robot or the
   overhead tracking system for the location of something.

   name is the description of the object ie cLANBall ,cLANRobot,cLANGoal.
   num is a sub identifier usefull where there is .>1 instance of an object
SEE ALSO
   langEventTrack()
SOURCE
    typedef struct{
      unsigned char type;
      int timestamp;
      unsigned char to;
      unsigned char from;
    
      unsigned char name;
      unsigned char num;
    } langEventAskTrack;

language/langEventCommand

DESCRIPTION
   Issue a command to one or all of the robots.
SOURCE
    typedef struct {
      unsigned char type;
      int timestamp;
      unsigned char to;
      unsigned char from;
    
      unsigned char cmd;
      unsigned char pri;
      unsigned char name;
      unsigned char num;
      unsigned char name2;
      unsigned char num2;
    } langEventCommand;

language/langEventPing

DESCRIPTION
   Ping is a test event. The recipiant is expected to return a
   pong event.
SEE ALSO
   langEventPong()
SOURCE
    typedef struct {
      unsigned char type;
      int timestamp;
      unsigned char to;
      unsigned char from;
    } langEventPing;

language/langEventPlayMode

DESCRIPTION
   Notification of a change in play mode.  Mostly messages
   originating from the referee.
 SOURCE */
ypedef struct{
 unsigned char type;
 int timestamp;
 unsigned char to;
 unsigned char from;
  unsigned char mode;
 langEventPlayMode;
/* From the simulation league soccer server protocol yellow=left,blue=right*/
num {
 langModePlayBlue = 0,  /* direction */
 langModePlayYellow,
  langModeBeforeKickOff, /* play modes */
  langModeKickOffBlue,
 langModeKickOffYellow,
  langModeFreeKickBlue,
 langModeFreeKickYellow,
  langModeHalfTime,
 langModeTimeUp,
  langModeGoalBlue,
 langModeGoalYellow
;

language/langEventPong

DESCRIPTION
   Pong is a test event sent as a reply to a Ping message.  The
   timestamp from the ping packet is the only new member of the pong
   message.
SEE ALSO
   langEventPing()
SOURCE
    typedef struct {
      unsigned char type;
      int timestamp;
      unsigned char to;
      unsigned char from;
    
      int time;
    } langEventPong;

language/langEventPowerStatus

DESCRIPTION
   Report the current power (battery) status of the sending robot.
SOURCE
    typedef struct {
      unsigned char type;
      int timestamp;
      unsigned char to;
      unsigned char from;
    
      unsigned short int level; /* 0-1024 */
    } langEventPowerStatus;

language/langEventText

DESCRIPTION
   Event for raw data and text string transfers used to print
   messages, log error messages on the MCP or display messages on
   the eyebot display.  Text strings should be transfered with the
   trailing zero byte.
SEE ALSO
   langEventTrack()
SOURCE
    typedef struct {
      unsigned char type;
      int timestamp;
      unsigned char to;
      unsigned char from;
    
      unsigned char file;   /* describes what to do with the text */
      unsigned char length; /* Length of data */
      char *data;           /* Pointer to the text data. */
    } langEventText;
    
    enum { /* text file types */
      langTextFilePrint = 0,
      langTextFileError = 1,
      langTextFileLog   = 2
    };

language/langEventTrack

DESCRIPTION
  Track messages are used to describe position and velocity of an
  object(ball robot etc).  Position x,y are in millimeters.

  Track is used to tell a x,y position and v=velocity of movement
  a is direction in angles.

  name is the description of the object ie cLANBall ,cLANRobot,cLANGoal.
  num is a sub idenfifier usefull where there is .>1 instance of an object
SEE ALSO
   lang_rad2angle(), lang_deg2angle(), lang_angle2rad(), lang_angle2deg()
SOURCE
    typedef struct {
      unsigned char type;
      int timestamp;
      unsigned char to;
      unsigned char from;
    
      unsigned char name; /* Object type (ball, friend, foe) */
      unsigned char num;  /* Object id 1..255 - 0 is unknown */
      short int x, y;     /* in mm relative to field center */
      short int heading;  /* counter-clockwise, 0 is along positive X axis */
      short int velocity; /* mm/second */
    } langEventTrack;
    
    enum { /* Track / position objects */
      langNameBall          = 'O',
      langNameFriend        = 'F',
      langNameEnemy         = 'E',
      langNameBGoal         = 'G',
      langNameBDefence      = 'g',
      langNameYGoal         = 'H',
      langNameYDefence      = 'h',
      langNameOrigin        = '0',
      langNameCursor        = 'x',
      langNameZone          = 'Z',
      langNameWall          = 'W',
      langNamePath          = 'P',
    
      langNameCornerYLeft   = 'y',
      langNameCornerYRight  = 'Y',
      langNameCornerBLeft   = 'b',
      langNameCornerBRight  = 'B'
    };

language/langEventUnknown

DESCRIPTION
   Unknown event.  Used when a unknown/unhandled event was received
   by lang_receive().  length specifies the length of data, and data
   points to the message received (after the 'type' byte).
SEE ALSO
   lang_receive()
SOURCE
    typedef struct
    {
      unsigned char type;
      int timestamp;
      unsigned char to;
      unsigned char from;
    
      unsigned char length;
      unsigned char *data;
    } langEventUnknown;

language/lang_angle2deg

SYNOPSIS
   int lang_angle2deg(double deg);
DESCRIPTION
   Convert language specific angle unit(radians times 1024) to
   degrees (360 circle).
RESULT
   degrees
SEE ALSO
   lang_deg2angle()

language/lang_angle2rad

SYNOPSIS
   double lang_angle2rad(short int angle)
DESCRIPTION
   Convert language specific angle unit (radians times 1024) to
   radians (2 times PI circle).
RESULT
   radians
SEE ALSO
   lang_rad2angle()

language/lang_deg2angle

SYNOPSIS
   int lang_deg2angle(double deg);
DESCRIPTION
   Convert degrees (360 circle) to language specific angle unit(radians
   times 1024).
RESULT
   angle
SEE ALSO
   lang_rad2angle()

language/lang_init

SYNOPSIS
   lang_channel lang_init(void);
DESCRIPTION
   Initialize the language library.  Call this and make sure the
   return value is not 0 before calling any of the other language
   functions.
RESULT
   channel handle on success, 0 on failure.
SEE ALSO
   lang_send(), lang_release()

language/lang_messageWaiting

SYNOPSIS
   int lang_messageWaiting(lang_channel ch);
DESCRIPTION
   Check if there are radio messages waiting to be processed.  If
   this function return true (1), lang_receive() will not block.
RESULT
   0 if message queue is empty, 1 if there might be messages waiting
   or -1 if the channel is bogus.
SEE ALSO
   lang_init(), lang_receive()

language/lang_rad2angle

SYNOPSIS
   int lang_rad2angle(double radians)
DESCRIPTION
   Convert radians (2 times PI circle) to language specific angle
   unit (radians times 1024).
RESULT
   angle
SEE ALSO
   lang_deg2angle(), lang_angle2rad()

language/lang_receive

SYNOPSIS
   typedef int (*lang_handler_t)(langEvent *event, void *ref);
   int lang_receive(lang_channel ch, lang_handler_t handler, void *ref);
DESCRIPTION
   Parse radio messages and pass them on to the language handler as
   native structs.
PARAMETERS
   handler  Function pointer to call for each received event.
   ref      Reference passed on to the handler.
RESULT
   Number of events received.
SEE ALSO
   lang_send()

language/lang_release

SYNOPSIS
   int lang_release(lang_channel ch);
DESCRIPTION
   Release all resources allocated by lang_init().  After this
   function returns, call lang_init() before using this channel
   again.
RESULT
   0 on success, -1 of failure.
SEE ALSO
   lang_init()

language/lang_send

SYNOPSIS
   int lang_send(lang_channel ch, langEvent *event);
DESCRIPTION
   Buffer information given in 'event' to the other soccer players.
   Call lang_sendFlush() to send the information.
PARAMETERS
   event  Pointer to langEvent structure, where the type describes
          which specific struct this is.
RESULT
   0 on success and -1 if the event type is unknown.
SEE ALSO
   lang_receive(), lang_sendFlush()

language/lang_sendFlush

SYNOPSIS
   int lang_sendFlush(lang_channel ch);
DESCRIPTION
   Flush sendbuffer with all the information buffered by
   lang_send().  Does not do anything if there are no packages in
   the buffer.
RESULT
   0 on success and -1 on failure
SEE ALSO
   lang_send()

language/lang_transCmd

SYNOPSIS
   char *lang_transCmd(unsigned char code);
DESCRIPTION
   Returns english language strings translations of character codes.
RESULT
   Pointer to a static string.
SEE ALSO
   lang_send()

language/lang_transName

SYNOPSIS
   char *lang_transName(unsigned char code);
DESCRIPTION
   Returns english language strings translations of character codes.
RESULT
   Pointer to a static string.
SEE ALSO
   lang_send()

language/lang_transPri

SYNOPSIS
   char *lang_transPri(unsigned char code);
DESCRIPTION
   Returns english language strings translations of character codes.
RESULT
   Pointer to a static string.
SEE ALSO
   lang_send()

language/lang_transType

SYNOPSIS
   char *lang_transType(unsigned char code);
DESCRIPTION
   Returns english language strings translations of character codes.
RESULT
   Pointer to a static string.
SEE ALSO
   lang_send()

language/pack

SYNOPSIS
   int pack(BYTE *buffer, const char *format, ...);
DESCRIPTION
   Internal function.

   Pack values into m68k endian format for network transport.
   Returns number of bytes packed into the buffer.  Supports the
   following formats codes:
     d - 32 bit signed int
     D - 32 bit unsigned int
     w - 16 bit signed short
     W - 16 bit unsigned short
     c - 8 bit signed char
     C - 8 bit unsigned char
     f - 32 bit IEEE floating point
SEE ALSO
   unpack(), lang_send()

language/unpack

SYNOPSIS
   int unpack(BYTE *buffer, const char *format, ...);
DESCRIPTION
   Internal function.

   Unpack the values stored using pack().  Supports the same format
   codes as pack(), but requires pointers to the variables to store
   values in them.  Return number of bytes unpacked from the buffer.
SEE ALSO
   pack(), lang_receive()