Generated from liblanguage.summary with ROBODoc v3.2.2 on Mon Sep 11 15:48:19 2000
TABLE OF CONTENTS
- language/_module
- language/langEvent
- language/langEventAny
- language/langEventAskTrack
- language/langEventCommand
- language/langEventPing
- language/langEventPlayMode
- language/langEventPong
- language/langEventPowerStatus
- language/langEventText
- language/langEventTrack
- language/langEventUnknown
- language/lang_angle2deg
- language/lang_angle2rad
- language/lang_deg2angle
- language/lang_init
- language/lang_messageWaiting
- language/lang_rad2angle
- language/lang_receive
- language/lang_release
- language/lang_send
- language/lang_sendFlush
- language/lang_transCmd
- language/lang_transName
- language/lang_transPri
- language/lang_transType
- language/pack
- language/unpack
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)
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'
};
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;
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;
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;
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;
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
;
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;
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;
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
};
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'
};
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;
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()