Message#

Introduction #

Two VEX AIM Coding Robots can be linked so they communicate during a project. Using Message, the robots can send and receive information to coordinate their actions.

Note: For messages to be sent and received, both robots must be running projects that handle messaging at the same time.

Below is a list of available methods:

Actions – Send messages between robots.

send_message – Sends a string and up to three numbers to the other linked robot.

Getters – Check for received messages and connection status.

get_message – Retrieve the most recent string received.
get_message_and_data – Retrieve the most recent string and numbers received as a tuple.
is_connected – Returns a Boolean indicating whether the robot is linked with another robot.
is_message_available – Returns a Boolean indicating whether the other linked robot has ever sent a message.

Callbacks – Run functions when events occur.

handle_message – Register a function to be called when a specific message is received.
connected – Register a function to be called when the robot is connected with another robot.
disconnected – Register a function to be called when the robot is disconnected with another robot.

Actions #

send_message #

send_message sends a string and up to three numbers to the other linked robot.

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

Parameter	Description
`message`	The string to send to the other linked robot.
`arg1`	Optional. A float or integer to send to the other linked robot.
`arg2`	Optional. A second float or integer to send to the other linked robot.
`arg3`	Optional. A third float or integer to send to the other linked robot.

# Send a message when the screen is pressed
def robot_send_message():
    robot.link.send_message("message")

robot.screen.pressed(robot_send_message)

# Display when a message is received
while not robot.link.is_message_available():
    wait(5, MSEC)
robot.screen.print("Received!")

# Send the current heading to the other robot
def robot_send_message():
    robot.link.send_message("message", robot.inertial.get_heading())

robot.screen.pressed(robot_send_message)

# Turn to match the other robot's heading
while True:
    if robot.link.is_message_available():
        message, heading = robot.link.get_message_and_data()
        robot.turn_to(heading)   
    wait(5, MSEC)

Getters #

get_message #

get_message returns the most recent string received from the other linked robot.

Usage:
robot.link.get_message(timeout)

Parameters	Description
`timeout`	Optional. The maximum time (in milliseconds) the function will wait for a message before continuing without one. The default is 1000.

# Send a message when the screen is pressed
def robot_send_message():
    robot.link.send_message("VEXcode!")

robot.screen.pressed(robot_send_message)

# Display when a message is received
while True:
    if robot.link.is_message_available():
        response = robot.link.get_message()
        robot.screen.print(response)
    wait(5, MSEC)

get_message_and_data #

get_message_and_data returns the most recent string and numbers received from the other linked robot and returns it as a tuple.

Usage:
robot.link.get_message_and_data(timeout)

Parameters	Description
`timeout`	Optional. The maximum time (in milliseconds) the function will wait for a message before continuing without one. The default is 1000.

# Send the current heading to the other robot
def robot_send_message():
    robot.link.send_message("message", robot.inertial.get_heading())

robot.screen.pressed(robot_send_message)

# Turn to match the other robot's heading
while True:
    if robot.link.is_message_available():
        message, heading = robot.link.get_message_and_data()
        robot.turn_to(heading)    
    wait(5, MSEC)

is_connected #

is_connected returns a Boolean indicating whether the robot is currently linked with another robot.

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.

# Turn off one of the linked robots to see the message change
while True:
    robot.screen.clear_screen(1, 1)
    robot.screen.print(robot.link.is_connected())
    wait(5, MSEC)

is_message_available #

is_message_available returns a Boolean indicating whether the other linked robot has ever used send_message yet in the current project.

True - send_message has been used by the other linked robot in the current project.
False - send_message has never been used by the other linked robot in the current project.

Usage:
robot.link.is_message_available()

Parameters	Description
	This method has no parameters.

# Send a message when the screen is pressed
def robot_send_message():
    robot.link.send_message("message")

robot.screen.pressed(robot_send_message)

# Display when a message is received
while not robot.link.is_message_available():
    wait(5, MSEC)
robot.screen.print("Received!")

Callbacks #

handle_message #

handle_message registers a method that runs when the robot receives a specific message string.

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

Parameters	Description
`callback`	A previously defined function that is called when the received message matches the specified string.
`message`	The string to check incoming messages against. If it matches, the `callback` runs.

# Show a smiling emoji
def robot_smile():
    robot.screen.show_emoji(HAPPY)

# If the message says "smile", show a smile
robot.link.handle_message(robot_smile, "smile")

# Send a message when the screen is pressed
def robot_send_message():
    # Change the message to not show the emoji
    robot.link.send_message("smile")

robot.screen.pressed(robot_send_message)

connected #

connected registers a function to be called when the robot is linked to another robot.

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

Parameters	Description
`callback`	A previously defined function that is called when the robot is linked to 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 face when connected
def robot_smile():
    robot.screen.show_emoji(HAPPY)

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

# Register both callbacks
# Turn off a robot to change the emoji
robot.link.connected(robot_smile)
robot.link.disconnected(robot_sad)

disconnected #

disconnected registers a function to be called when the robot is not linked to another robot.

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

Parameters	Description
`callback`	A previously defined function that is called when the robot is not linked to 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 face when connected
def robot_smile():
    robot.screen.show_emoji(HAPPY)

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

# Register both callbacks
# Turn off a robot to change the emoji
robot.link.connected(robot_smile)
robot.link.disconnected(robot_sad)