The Communication Module

The Communication Module (cmm) handles the exchange of messages between modules on different robots. As such it closely interacts with the Message System. From a user point of view, all Msg functions work as documented in "An implementation for the Message System". The destination parameter of MsgNewMessage is used to specify both a module ID and an ID for a (group of) team member(s). This last ID is called an alias. Throughout the whole robot software, aliases are used to identify objects, zones, shapes and markers or lists of these items. Aliases for lists are dynamic because their value may change during run-time. Their counterparts, aliases for objects, zones etc., are called static. Many aliases are predefined in Main.h, but aliases can also be created and destroyed during run-time. Run-time aliases are called unnamed dynamic aliases because they are not named in Main.h. 

The Communication Module has 3 major tasks: to maintain aliases, to forward incoming messages from other robots and to send outgoing messages to other robots. These last two tasks are transparent for the user and require no user actions and have no interface functions. All  interface functions return -1 when something goes wrong. In that case errno will contain the error code.

int CmmSetAlias(int alias, ...);

Set the dynamic alias to a list of aliases (maximum ALIAS_MAX). Members can be static or dynamic aliases. Each member will be included in the alias just once. The previous definition of the list will be forgotten. If alias is -1, this function will use a undefined unnamed alias (that is, an unnamed alias with no members). The return value is the alias actually used.
 

int CmmAddToAlias(int alias, ...);

Add a list of members (maximum ALIAS_MAX) to dynamic alias. Members can be static or dynamic aliases. Each member in the resulting list (after merging old and new members) will be unique. If alias is -1, this function will use a undefined unnamed alias (that is, an unnamed alias with no members). The return value is the alias actually used.
 

int CmmDelFromAlias(int alias,...);

Removes a list of members from dynamic alias.
 

int CmmGetAlias(int alias, int names[], int size);

Get the list of members of alias. Dynamic aliases will be recursively expanded, the result is a list of static aliases. The list will be returned in names. Only size aliases will be returned. The return value is the number of aliases in names.
 

int CmmPrintAliases(int alias);

Print the list of all defined aliases if alias is -1. Print the value for alias if alias is valid.
 

int CmmSaveAliases(void);

Not implemented yet.
 

int CmmReadAliases(void);

Not implemented yet.
 

int CmmMakeAddress(int alias, int module);

Make an address from alias and module, to use as the destination argument in MsgNewMessage. Alias should expand to static aliases for team members.
 

int CmmAliasFromAddress(int address);

Retrieve the alias from address. This should be used on the sender argument of MsgGetMessage to get the static alias for the robot which posted the message.
 

int CmmModuleFromAddress(int address);

Retrieve the alias from address. This should be used on the sender argument of MsgGetMessage to get the module ID  which posted the message.
 

Two special aliases exist, which act as flags. They can be added to and removed from aliases, but will not be returned by CmmGetAlias. The flag aliases are:

BROADCAST

This flag tells the Message System to use UDP broadcasting when possible. Normally the Message System tries to send a separate message to each member of an alias. If the members of an alias include this flag, the Message System will broadcast one message, free for any computer to receive. This reduces network traffic a lot, but increases the CPU load on all computers a little (every computer has to decided if the message is relevant or not).
 

RESERVED

This flag tells the Cmm an unnamed alias is not empty, even if it has no other members. Unnamed aliases with no members are eligible for use by CmmSetAlias and CmmAddToAlias when alias is -1. The RESERVED flag prevents this and in fact it allocates an unnamed alias.
 

Networking

The CMM uses UDP/IP to communicate with other team members. UDP/IP was chosen because it simple to use, allows broadcasting and does not depend on a receiver. Because it is datagram based, the CMM does not need to establish and maintain connections with the other team members. Broadcasting reduces network traffic and makes debugging easier. If a receiver is unreachable, the datagrams just will be lost, until the receiver works again.

When the CMM is started, it the aliases OT_PLAYERx and OT_COACH to the IP addresses of the hosts playerx c.q. coach. These hostnames can be "real" names in the DNS server, but it is sufficient to define them as alternate names in the /etc/hosts file.