Opentrons: An api to query opentrons robots

[aciceri]

This could be a naive request as I never used Opentrons and all I know came from reading the docs and sources. However I would like to know if there is an api to communicate with a specific robot, I would be mainly interested into getting the elaboration status of the currently running protocol and a log.

In the future I could be interested also into uploading a json protocol, but for now it's not a priority. Anyway, I'm not interested into protocols written using Python.

I opened this issue for two reasons: in the case what I ask is not currently possible this is a kind proposal to make it possible and in the case it's possibile this is a proposal to create a proper documentation.

I found here the declaration of the API, it looks splitted in different parts, the legacy part here (the most interesting for me?) includes a log endpoint here.

But how can I use it? How have I to manage the accesses and the sessions?

Anyway, this issue aside, for my problem I'm open to any solution, I just need to query a Opentrons robot and get the status and some form of log of the currently running protocol.

[mcous]

Hi @aciceri! An OT-2 robot has two "publicly" facing APIs:

• An HTTP API (documentation and testing available at http://${robot_ip_address}:31950/redoc
  
  
  
  • We're still working on publishing this documentation to http://docs.opentrons.com, see #4638
  
  
• A WebSocket-based RPC API
  
  
  
  • This API is in the process of being deprecated and removed
  
  
  • It is difficult to use, very entangled with the exact UI implementation of the Opentrons App, and buggy
  
  

Currently, most calibration processes and all protocol run logic is handled by the RPC API. On top of being difficult to use, the RPC API is unable to accurately report the state of a running protocol. So, the short version of your question is: right now querying the robot for calibration and run state is prohibitively hard to do.

The longer answer is that the access control and session management endpoints you linked to are new endpoints that are not yet ready to use, but they are the beginnings of our RPC replacement project. Over the coming months, we will be moving all calibration and protocol logic to publicly documented HTTP endpoints. For example, see these new endpoints going up for querying calibration data: #5553.

The log endpoint that you linked exposes system journalctl logs from the Linux system that the robot runs. They don't directly map to protocol processes. We will be building specific endpoints in the sessions module for access to the list of commands in a given protocol.

[aciceri]

Thank you for the fast answer, glad to know that you are already working on this, but actually I need to access to this information about the robot with the current software.

1. I'm thinking I could execute journalctl on the robot using ssh, what kind of information can I expect? Could I know at least when a particular protocol has started and finished? And know if the robot is still executing a protocol or is in idle?

2. I'm also reconsidering the use of python protocols, for example I could add in my protocols various requests (using the python requests builtin library) to an external logger/server to save the informations I need.
   This leads me to ask if a python protocol can execute arbitrary python code using all the builtin libraries, and if I can (and how) install other libraries (for example from PyPI).

I realize these solutions aren't optimal but I can't wait for the new APIs, what would you recommend? Which solution is more stable respect future updates?

Should be clear that I don't have the robot at hand right now: is there a way to emulate/virtualize the machine (maybe a docker image?) to try it out?
I tried opentrons_simulate.py for the python protocols but now I would like to test the machine, not the protocols.

[mcous]

1. I'm thinking I could execute journalctl on the robot using ssh, what kind of information can I expect? Could I know at least when a particular protocol has started and finished? And know if the robot is still executing a protocol or is in idle?

The best I can give you is "maybe". What's logged in journalctl is our (for example) log.debug('message') calls in the code. They are not designed to be stable nor are they designed to be hooked into as status information. I wouldn't recommend it.

1. I'm also reconsidering the use of python protocols, for example I could add in my protocols various requests (using the python requests builtin library) to an external logger/server to save the informations I need.
   This leads me to ask if a python protocol can execute arbitrary python code using all the builtin libraries, and if I can (and how) install other libraries (for example from PyPI).

Python protocols are executed on the OT-2's on-board computer and have access to all built-in libraries. You can SSH into the robot and pip install additional dependencies, as long as those dependencies do not require compilation.

For now, I would recommend (2), but do keep in mind that (if you're using the Opentrons App), your Python code will be executed twice: once for simulation and once during run. If you make external requests, you will want to make sure that you only make those requests during the actual run (there is an API to detect that in Python protocols).

Should be clear that I don't have the robot at hand right now: is there a way to emulate/virtualize the machine (maybe a docker image?) to try it out?
I tried opentrons_simulate.py for the python protocols but now I would like to test the machine, not the protocols.

You can either:

• Set up a local development environment (see CONTRIBUTING.md), where you can run the API server on your own machine
  
  
  
  • There are parameters you can set to simulate different hardware attachments
  
  
• If you have a Raspberry Pi B+ handy, you can burn the Robot OS onto an SD card and run the RPi as if it is an OT-2
  
  
  
  • You'd have to also set some parameters to simulate actual hardware attachments
  
  

[aciceri]

The best I can give you is "maybe". What's logged in journalctl is our (for example) log.debug('message') calls in the code. They are not designed to be stable nor are they designed to be hooked into as status information. I wouldn't recommend it.

And if I use json protocols? Is there a log.debug equivalent?

Set up a local development environment (see CONTRIBUTING.md), where you can run the API server on your own machine

I'll try this.

If you have a Raspberry Pi B+ handy, you can burn the Robot OS onto an SD card and run the RPi as if it is an OT-2

Do you mean that I can burn a modified ROS image with Opentrons? Could you please provide a link of the image?
I found your pi-bootstrapper repo but it looks archived.
In the past I tried emulating the RPi using QEMU, I think it would work with this image too.

For the rest you have been kind and clear, I understood everything, thank you.

[DerAndere1]

Do you mean that I can burn a modified ROS image with Opentrons? Could you please provide a link of the image?
I found your pi-bootstrapper repo but it looks archived.
In the past I tried emulating the RPi using QEMU, I think it would work with this image too.

I (not part the opentrons team) found this https://github.com/Opentrons/buildroot . To me the opentrons-build.sh looks like the script to build the the Linux OS that runs on the Raspberry Pi which is integrated in the Opentrons robot hardware. Never tested it, though.

[mcous]

@aciceri I'm just now coming back to this issue while doing some cleanup. To recap:

• The operating system that runs on the OT-2 is available at https://github.com/Opentrons/buildroot
  
  
  
  • We've recently cleaned up the "how to build" documentation in that repo so hopefully it's a little more clear than it was when you filed this ticket
  
  
  • The update images are also now attached to our releases in this repository
  
  
• Our intent is to expose current protocol run information over the robot's HTTP API
  
  
  
  • That work is ongoing and will be documented
  
  
  • We're have some very initial experimental work here going through a user-research program
  
  
  • If you're interested, it would be lovely if you were willing to chat with our researchers about your use case and needs out of such an API
  
  

I'm going to close this ticket since we have / will have work-focused tickets for building out these APIs