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 ofRobot
, orcontent
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