Tutorial: Connecting to a Trilobio Fleet

Goal: Connect to a Trilobio robot and jog it around.

Background

In this tutorial, you will send jog commands to a robot in a Trilobot fleet using the python wrapper for the TCode API.

This tutorial assumes that:

  • A trilobot fleet is booted up

  • You are on the fleet control computer

A basic understanding of Python is also assumed.

Step 1: Connect to Fleet

>>> from tcode_api.servicer import TCodeServicerClient
>>> client = TCodeServicerClient()
>>> status = client.get_status()
>>> print(status)
GetStatusResponse(command_id=None, operation_count=0, run_state=False, result=Result(success=True, code='success', message=None, details=None))

The program that reads TCode and turns it into robot commands is called the “TCode Servicer”. It runs on the fleet control computer. We will use the TCodeServicerClient class to connect to this program and talk to it. The first two lines create the client.

Note

Note that the TCodeServicerClient constructor is called with no arguments. By default, it connects to the TCode Servicer running on the local machine. If you are running this code on a different machine, look at the API documentation for how to specify the IP address and port of the target TCode Servicer.

from tcode_api.servicer import TCodeServicerClient
client = TCodeServicerClient()

The third line calls the get_status method to check that we are connected. In the response object, we can see a lot of information that will be useful later.

status = client.get_status()
print(status)

Step 2: Select a Robot

Now that we’ve successfully retrieved the fleet status, we are ready to select a robot to control! Let’s first tell the TCode servicer to find a robot on the fleet.

import tcode_api.api as tc
from tcode_api.utilities import generate_id()

# Generate the TCode script
robot_id = generate_id()
commands = []
commands.append(
  tc.ADD_ROBOT(id=robot_id, descriptor=tc.RobotDescriptor())
)

# Schedule the TCode script
client.schedule_commands(commands)

# Run the TCode script
client.execute_run_loop()
This script demonstrates the three main steps to run a TCode script on your fleet:

  1. Generate a list of TCode commands

  2. Schedule the script with your fleet

  3. Execute the script on your fleet

Let’s first look at step 1: .. code-block:: python

import tcode_api.api as tc from tcode_api.utilities import generate_id() from tcode_api.servicer import TCodeServicerClient

client = TCodeServicerClient()

When writing TCode, the primary python data structures for commands, errors, data structures. etc. are stored within tcode_api.api. We import this library as tc for shorthand.

In addition to the core API, tcode_api has a few helper functions to make writing TCode scripts in python easier. These functions are stored in tcode_api.utilities. Here, we’re importing a function to generate unique identifiers for TCode entities.

The TCodeServicerClient code we’ve seen before, so let’s move on.

robot_id = generate_id()

Next, we’ll instantiate an id for the robot. Entities that are referenced by TCode commands are referenced by identifier, and identifiers are linked to “real objects” on your fleet through ADD_*** commands. Typically, your tcode generation code will have a block of generate_id() calls at the top to create ids for all of your relevant objects.

commands = []

This line instantiates an empty list to store TCode commands. We’ll use append to serially write the script by adding commands to the end of this list.

Now: Let’s add our first command!

commands.append(
  rc.ADD_ROBOT(id=robot_id, descriptor=tc.RobotDescriptor())
)

This line appends our first command, tc.ADD_ROBOT. Into this function, we pass our generated identifier, and a descriptor of a robot. Note that this descriptor has no attributes specified, and so will match any robot in the fleet. If your fleet has only one robot, this is great. If your fleet has multiple robots, however, you must add more information to the descriptor to ensure that you control the expected robot.

How do we know that this is good TCode? Let’s ask the fleet, by calling the schedule_commands endpoint.

client.schedule_commands(commands)
This command will perform the following:

  1. Check that the TCode is valid

  2. Check that all of the entities resolve to valid “real-life” objects

  3. Schedule the commands.

Now, your robot has commands scheduled! All there is left to do is run the commands.

client.execute_run_loop()

The execute_run_loop() method is a bare-bones loop that monitors the fleet until it finished the script or raises an error. Internally, the basic logic looks similar to this snippet:

while True:
   try:
     time.sleep(0.1)  # Don't busy-wait
     status = client.get_status()

     # If we reached the end of the script, finish
     if status.operation_count == 0:
       client.set_run_state(False)
       return

     # If we hit an error, finish
     if not status.result.sucess:
       print(status.result.message)
       client.set_run_state(False)
       return

   # If we hit <Ctrl-C>, clear the robot & finish
   except KeyboardInterrupt:
     client.set_run_state(False)

     # Reset the robot state to empty deck, no commands
     client.clear_tcode_resolution()
     client.clear_labware()

With this interface, the function will run until the robot either finishes the script or hits an error, in which case it will print the error message, then stop. If you press <Ctrl-C>, the robot will also stop.

Now, try out the script!