Messages

This provides a basic Message protocol for robot communication. Each message contains the ID of the sender and a dictionary of message contents. The values of the message contents may be any type, so the receiver must know how to process the data.

Additionally, Messages can optionally include a receiver type (rx_type). This is only needed if there are multiple types of robots in the World, and you only want certain types of robots to receive the message.

If no arguments are provided when a Message is created, it creates a null message, which signals that the robot is not broadcasting anything.

While it is possible to extend this class, the default Message class should meet most needs.

class gridsim.message.Message(tx_id: Optional[int] = None, content: Dict[str, Any] = {}, rx_type: Type[gridsim.robot.Robot] = <class 'gridsim.robot.Robot'>)

A message sent by robots

Messages can be either a null (empty) message if no arguments are provided to the constructor. Or it contains the sender’s ID, a dictionary of content, and (optionally) the type of robot that receives the message.

Parameters
  • tx_id (int, optional) – ID of the sending (transmitting) robot, by default None

  • content (Dict[str, Any]], optional) – Dictionary of message keys and values, by default an empty dictionary. Keys must be strings, but values can be of any type (incumbent on receiver to correctly interpret incoming data).

  • rx_type (Type[Robot], optional) – Type of the receiving robot, by default Robot (i.e., message will be processed by any Robot.)

Raises

TypeError – If rx_type is not a subclass of Robot, or content is not a dictionary with strings for keys

get(key: Optional[str] = None) → Optional[Dict[str, Any]]

Get the contents of the message

Parameters

key (str, optional) – Name of the parameter to retrieve, by default None. If not specified, a dictionary of all parameters will be returned.

Returns

Dictionary of the message contents

Return type

Dict[str, Any] or None

Raises

KeyError – If a key is provided but is not in the message contents

sender() → Optional[int]

Get the ID (32-bit integer) of the robot that sent the message

Returns

ID of the sending (transmitting) robot

Return type

int or None

set(key: Optional[str], value: Any)

Set the message contents

In the message contents, set the given key to have the given value. If this is an empty (null) message, this will raise an error. If the key already exists, the existing value will be overwritten.

Parameters
  • key (str) – Key in the message contents for which to set the value

  • value (Any) – Value to set for the given key. This will overwrite any existing value, if the key already exists.

Raises

ValueError – If the message is null/empty, the message contents cannot be set

set_all(content: Dict[str, Any])

Replace the whole message content of the dictionary.

This will replace all of the existing message content.

If you want to clear the message contents, you can pass any empty dictionary as the content ({}).

Parameters

content (Dict[str, Any]) – Complete dictionary to set as the message contents

Raises

ValueError – If the message is null/empty, the message contents cannot be set