SerialLink

Introduction

SerialLink lets two V5 Brains communicate by sending and receiving raw serial data over VEX Link. Instead of labeled messages, SerialLink transmits a buffer (a string or a bytearray). This makes it useful for advanced robot-to-robot communication, such as streaming sensor data, sending custom packet formats, or building your own protocol on top of bytes.

Every usage of send adds data to the linked V5 Brain’s receive buffer. Data is read in the order it arrives (first-in, first-out). If multiple buffers are sent before the other V5 Brain uses receive, they remain queued and are returned one at a time in the order they were sent. Because data can queue, repeatedly sending large buffers every loop may create backlog; for time-critical links, send only what you need.

Important: Both robots must be running projects that use SerialLink at the same time, or no data will be sent/received.

This page uses link as the example SerialLink name. Replace it with your own configured name as needed.

Below is a list of available methods:

• is_linked – Returns whether this Brain is actively connected to its paired Brain.

• send – Sends a short message (with optional int/float data) to the paired Brain.

• receive – Waits for and returns the next incoming message.

• received – Registers a function to be called whenever a new message is received.

Create a Link

Create a SerialLink on both V5 Brains to establish a communication channel between them—either wirelessly with V5 Radios or through a wired Smart Cable—so the robots can send raw serial data to each other.

SerialLink(smartport, name, linktype, wired)

Parameter	Description
smartport	The Smart Port used for this link—the port the V5 Radio is connected to (wireless) or the Smart Cable is plugged into (wired). Written as Ports.PORTx where x is the port number.
name	The unique name to give this link as a string. Note: This name should be long enough to create a unique ID so it doesn’t accidentally match another team’s link.
linktype	The role this Brain will use for this link pair. Each pair must include one Manager and one Worker: VexlinkType.MANAGER – Use for the robot that will send more or larger messages. Managers have higher outbound bandwidth (~1040 bytes/sec). VexlinkType.WORKER – Use for the robot that will send fewer or smaller messages. Workers have lower outbound bandwidth (~520 bytes/sec).
wired	Optional. Whether this link is wired or wireless: True – The V5 Brains are connected via a Smart Cable. False (default) – The V5 Brains connect wirelessly using V5 Radios.

Code for Robot 1

"""
Create a wireless link in Port 1
name: VEXRoboticsLink123456789
linktype: Manager
"""
link = SerialLink(Ports.PORT1, "VEXRoboticsLink123456789", VexlinkType.MANAGER)

Code for Robot 2

"""
Create a wireless link in Port 1
name: VEXRoboticsLink123456789
linktype: Worker
"""
link = SerialLink(Ports.PORT1, "VEXRoboticsLink123456789", VexlinkType.WORKER)

Available Methods

Once your SerialLink is set up and the Brains are linked, you can use the methods below to send, receive, and respond to raw serial data.

is_linked

is_linked method returns whether the V5 Brains on a SerialLink are paired with one another.

• True – The two V5 Brains are paired and communicating on this link.

• False – The two V5 Brains are not paired on this link.

Note: It is good practice to always check to ensure the V5 Brains are linked at the start of a project before running any further code.

Usage:
link.is_linked()

Parameters	Description
	This method has no parameters.

Code for Robot 1

# Send a message to the other robot

# Create the link
link = SerialLink(Ports.PORT1, "VEXRoboticsLink123456789", VexlinkType.MANAGER)

# Do not run code UNTIL the Brains are linked
while not link.is_linked():
    wait(0.1, SECONDS)

brain.screen.print("Robot 1 - Manager")

link.send("HELLO")

Code for Robot 2

# Display the message that Robot 1 sends

# Create the link
link = SerialLink(Ports.PORT1, "VEXRoboticsLink123456789", VexlinkType.WORKER)

# Do not run code UNTIL the Brains are linked
while not link.is_linked():
    wait(0.1, SECONDS)

brain.screen.print("Robot 2 - Worker")
brain.screen.next_row()

def received_message(bytearray, length):
    # Slice the bytearray to the valid data
    data = bytearray[:length]  
    # Decode and strip the message before displaying it
    text = data.decode().strip()
    brain.screen.print("Got: ", text)

# Call received_message whenever a message is received
link.received(received_message)

send

send transmits raw serial bytes to the other linked V5 Brain.

When reading that data with receive, receive will only return once it has collected the number of bytes specified by its length parameter. Because of that, if your code always calls receive with a fixed length, you should ensure each message sent with send is exactly that many bytes (often by padding) so the receiver doesn’t block waiting for additional bytes.

If you don’t want to depend on an exact byte count, use received instead; it lets you handle whatever bytes are available without requiring a specific length.

Usage:
send(buffer)

Parameters	Description
buffer	The data to send to the other linked V5 Brain. This can be a string or a bytearray.

Code for Robot 1

# Send a message to the other robot

# Create the link
link = SerialLink(Ports.PORT1, "VEXRoboticsLink123456789", VexlinkType.MANAGER)

# Do not run code UNTIL the Brains are linked
while not link.is_linked():
    wait(0.1, SECONDS)

brain.screen.print("Robot 1 - Manager")

link.send("HELLO")

Code for Robot 2

# Display the message that Robot 1 sends

# Create the link
link = SerialLink(Ports.PORT1, "VEXRoboticsLink123456789", VexlinkType.WORKER)

# Do not run code UNTIL the Brains are linked
while not link.is_linked():
    wait(0.1, SECONDS)

brain.screen.print("Robot 2 - Worker")
brain.screen.next_row()

def received_message(bytearray, length):
    # Slice the bytearray to the valid data
    data = bytearray[:length]  
    # Decode and strip the message before displaying it
    text = data.decode().strip()
    brain.screen.print("Got: ", text)

# Call received_message whenever a message is received
link.received(received_message)

receive

receive returns serial data from the other linked V5 Brain in FIFO order (oldest unread data first).

Because receive waits for an exact byte count, fixed-length messaging often requires padding when using send so each message reaches the expected size. If the sender transmits fewer than length bytes, receive will continue waiting for the remaining bytes and not return anything.

If the queue is empty and you provide a timeout, receive waits up to that many milliseconds for new data. If nothing arrives in that window, it returns None. Any data sent afterward remains queued to be read later.

Usage:
receive(length, timeout)

Parameters	Description
length	The number of bytes to receive. receive waits until this many bytes have arrived, then returns them as a bytearray. If length is 0, receive returns None immediately. If you request more bytes than the sender transmits, receive will keep waiting. If the sender transmits more than this, the returned buffer is limited to length bytes.
timeout	Optional. How long in milliseconds receive will wait for a new message only if the queue is empty. Default is 300000 (300 seconds).

Code for Robot 1

# Send a math problem for the other Brain to solve

# Create the link
link = SerialLink(Ports.PORT1, "VEXRoboticsLink123456789", VexlinkType.MANAGER)

# Do not run code UNTIL the Brains are linked
while not link.is_linked():
    wait(0.1, SECONDS)

brain.screen.print("Robot 1 - Manager")

"""
Change whether to "add" or "subtract",
then what numbers to use in the operation.
"""
packet = "add,7,2.5"

# Pad with spaces until it's exactly 16 bytes
while len(packet) < 16:
    packet = packet + " "

link.send(packet)

Code for Robot 2

# Solve the math problem that the other Brain sends

# Create the link
link = SerialLink(Ports.PORT1, "VEXRoboticsLink123456789", VexlinkType.WORKER)

# Do not run code UNTIL the Brains are linked
while not link.is_linked():
    wait(0.1, SECONDS)

brain.screen.print("Robot 2 - Worker")
brain.screen.next_row()

# Receive exactly 16 bytes
buffer = link.receive(16)

# Remove the added " " padding
text = buffer.decode().strip()

# Separate the operator and numbers
parts = text.split(",")

operator = parts[0]
a = float(parts[1])
b = float(parts[2])

# Use what operator was sent
if operator == "add":
    result = a + b
elif operator == "subtract":
    result = a - b
# If not "add" or "subtract", do nothing
else:
    pass

brain.screen.print("Result = ", result)

received

received registers a function to be called whenever the V5 Brain receives serial data.

Usage:
link.received(callback)

Parameters	Description
callback	A previously defined function that executes when the V5 Brain receives serial data.

received callbacks are called with two arguments:

Callback Signature:
callback(buffer, length)

Argument	Description
buffer	A bytearray containing the received serial data. The bytearray may be larger than the received message.
length	The number of valid bytes received in buffer for this callback. Use buffer[:length] to access the received data.

Code for Robot 1

# Send a message to the other robot

# Create the link
link = SerialLink(Ports.PORT1, "VEXRoboticsLink123456789", VexlinkType.MANAGER)

# Do not run code UNTIL the Brains are linked
while not link.is_linked():
    wait(0.1, SECONDS)

brain.screen.print("Robot 1 - Manager")

link.send("HELLO")

Code for Robot 2

# Display the message that Robot 1 sends

# Create the link
link = SerialLink(Ports.PORT1, "VEXRoboticsLink123456789", VexlinkType.WORKER)

# Do not run code UNTIL the Brains are linked
while not link.is_linked():
    wait(0.1, SECONDS)

brain.screen.print("Robot 2 - Worker")
brain.screen.next_row()

def received_message(bytearray, length):
    # Slice the bytearray to the valid data
    data = bytearray[:length]  
    # Decode and strip the message before displaying it
    text = data.decode().strip()
    brain.screen.print("Got: ", text)

# Call received_message whenever a message is received
link.received(received_message)