Message#

Introduction #

Two VEX AIM Coding Robots can be linked so they can communicate during a project. Message methods let one robot send a message to the other robot. A message can include text by itself, or text with up to three numbers.

Received messages are stored in a first-in, first-out (FIFO) queue. This means the first message received is the first message that will be read.

Use is_message_available to check whether a message is ready to read. Then use get_message to read the next text message. If the message also includes numbers, use get_message_and_data to read the text and numbers together.

Note: For messages to be sent and received, both robots must be linked and both robots must be running projects that use Message methods.

Below is a list of all methods:

Action — Send messages between robots.

send_message — Sends text and up to three numbers to the linked robot.

Getters — Read messages or check connection status.

get_message — Returns the next received text message.
get_message_and_data — Returns the next received text message and numbers.
is_connected — Returns whether the robot is linked with another robot.
is_message_available — Returns whether a message is available to read.
get_name — Returns the name of the linked robot.

Callbacks — Run functions when message events occur.

handle_message — Runs a function when a specific message is received.
connected — Runs a function when the robot is linked with another robot.
disconnected — Runs a function when the robot is no longer linked with another robot.

Action #

send_message #

send_message sends text and up to three numbers to the linked robot. Use this method on one robot when the other robot needs to receive a command, signal, or short piece of information. Send text by itself when the message is enough on its own. Add numbers when the message needs related values, such as sending “heading” with the robot’s current heading value.

On the receiving robot, use is_message_available to check that a message has arrived. Then use get_message for a text-only message, or get_message_and_data for a message that includes numbers.

Usage:
robot.link.send_message(message, arg1, arg2, arg3)

Parameter	Description
`message`	The text to send to the linked robot.
`arg1`	Optional. A number to send with the message.
`arg2`	Optional. A second number to send with the message.
`arg3`	Optional. A third number to send with the message.

Example

Code for Robot 1

# Press the screen to tell Robot 2 which way to turn
robot.screen.print("Robot 1")

while not robot.screen.pressing():
    wait(5, MSEC)

robot.link.send_message("right")

Code for Robot 2

# Turn in the direction that Robot 1 sends
robot.screen.print("Robot 2")

while not robot.link.is_message_available():
    wait(5, MSEC)

direction = robot.link.get_message()

if direction == "left":
    robot.turn_for(LEFT, 90)
elif direction == "right":
    robot.turn_for(RIGHT, 90)

# Robot 1: continuously send the current heading to Robot 2
robot.screen.print("Robot 1")

while True:
    robot.link.send_message("heading", robot.inertial.get_heading())
    wait(50, MSEC)

# Robot 2: turn to match Robot 1's heading
robot.screen.print("Robot 2")

while True:
    if robot.link.is_message_available():
        message, heading = robot.link.get_message_and_data()
        robot.turn_to(heading)

    wait(50, MSEC)

Getters #

get_message #

get_message returns the next received text message from the message queue. Use this method on the receiving robot when the linked robot sent a text-only message. A common order is to use is_message_available to check that a message has arrived, then use get_message before displaying, comparing, or using the returned text in another method.

Use send_message on the other robot to send a text-only message.

Usage:
robot.link.get_message(timeout)

Parameter	Description
`timeout`	Optional. The maximum time, in milliseconds, to wait for a message before continuing. The default is `1000`.

Example

Code for Robot 1

# Press the screen to send a message to Robot 2
robot.screen.print("Robot 1")

while not robot.screen.pressing():
    wait(5, MSEC)

robot.link.send_message("Hello, Robot 2!")

Code for Robot 2

# Display the message sent by Robot 1
robot.screen.print("Robot 2")
robot.screen.next_row()

while not robot.link.is_message_available():
    wait(5, MSEC)

message = robot.link.get_message()
robot.screen.print(message)

get_message_and_data #

get_message_and_data returns the next received text message and numbers from the message queue as a tuple. Use this method on the receiving robot when the linked robot sent text with one or more numbers. A common order is to use is_message_available to check that a message has arrived, then use get_message_and_data before using the returned text and numbers.

Use send_message on the other robot to send the text and numbers together.

Usage:
robot.link.get_message_and_data(timeout)

Parameter	Description
`timeout`	Optional. The maximum time, in milliseconds, to wait for a message before continuing. The default is `1000`.

Example

Code for Robot 1

# Continuously send the current heading to Robot 2
robot.screen.print("Robot 1")

while True:
    robot.link.send_message("heading", robot.inertial.get_heading())
    wait(50, MSEC)

Code for Robot 2

# Turn to match Robot 1's heading
robot.screen.print("Robot 2")

while True:
    if robot.link.is_message_available():
        message, heading = robot.link.get_message_and_data()
        robot.turn_to(heading)

    wait(50, MSEC)

is_connected #

is_connected returns whether the robot is linked with another robot. Use this method before sending or waiting for messages if the project needs to check that the robot-to-robot connection is ready.

True — The robot is linked with another robot.
False — The robot is not linked with another robot.

Usage:
robot.link.is_connected()

Parameters	Description
	This method has no parameters.

# Display whether the robot is connected
while True:
    robot.screen.clear_screen()
    robot.screen.set_cursor(1, 1)
    robot.screen.print(robot.link.is_connected())
    wait(50, MSEC)

is_message_available #

is_message_available returns whether a message is waiting in the message queue. Use this method before get_message or get_message_and_data so the receiving robot only tries to read a message after one has arrived.

True — There is a message available to be read.
False — There are no messages available to be read.

Usage:
robot.link.is_message_available()

Parameters	Description
	This method has no parameters.

Example

Code for Robot 1

# Press the screen to send a message to Robot 2
robot.screen.print("Robot 1")

while not robot.screen.pressing():
    wait(5, MSEC)

robot.link.send_message("Hello, Robot 2!")

Code for Robot 2

# Wait until a message is available, then display it
robot.screen.print("Robot 2")
robot.screen.next_row()

while not robot.link.is_message_available():
    wait(5, MSEC)

message = robot.link.get_message()
robot.screen.print(message)

get_name #

get_name returns the name of the linked robot. Use this method to show which robot is connected before sending or receiving messages. If no robot is linked, this method returns None.

Usage:
robot.link.get_name()

Parameters	Description
	This method has no parameters.

# Display the name of the linked robot
robot.screen.print(robot.link.get_name())

Callbacks #

handle_message #

handle_message registers a function that runs when the robot receives a specific text message. Use this method when the robot should respond automatically to a known message instead of checking the message queue in a loop. Define the callback function first, then register it with handle_message and the message text to watch for.

Usage:
robot.link.handle_message(callback, message)

Parameter	Description
`callback`	A previously defined function that runs when the received message matches `message`.
`message`	The text to check incoming messages against.

Example

Code for Robot 1

# Press the screen to send "smile" to Robot 2
robot.screen.print("Robot 1")

while not robot.screen.pressing():
    wait(5, MSEC)

robot.link.send_message("smile")

Code for Robot 2

# Show a happy emoji when Robot 1 sends "smile"
def robot_smile():
    robot.screen.show_emoji(HAPPY)

robot.link.handle_message(robot_smile, "smile")

while True:
    wait(50, MSEC)

connected #

connected registers a function that runs when the robot is linked with another robot. Use this method when the project should respond as soon as the robot-to-robot connection is made. Define the callback function first, then register it with connected.

Usage:
robot.link.connected(callback, args)

Parameter	Description
`callback`	A previously defined function that runs when the robot is linked with another robot.
`args`	Optional. A tuple containing arguments to pass to the callback function. See Using Functions with Parameters for more information.

# Show a happy emoji when connected
def robot_smile():
    robot.screen.show_emoji(HAPPY)

robot.link.connected(robot_smile)

disconnected #

disconnected registers a function that runs when the robot is no longer linked with another robot. Use this method when the project should respond as soon as the robot-to-robot connection is lost. Define the callback function first, then register it with disconnected.

Usage:
robot.link.disconnected(callback, args)

Parameter	Description
`callback`	A previously defined function that runs when the robot is no longer linked with another robot.
`args`	Optional. A tuple containing arguments to pass to the callback function. See Using Functions with Parameters for more information.

# Show a sad emoji when disconnected
def robot_sad():
    robot.screen.show_emoji(SAD)

robot.link.disconnected(robot_sad)