Welcome to UniteLabs
UniteLabs connects lab instruments to one common interface. Each instrument is paired with a connector that exposes its functions as typed actions that you can list, inspect, and call: from Python, over the REST API, or in the platform's web interface, with no vendor-specific code on your side. Workflows written in Python coordinate several instruments, execute on the platform, and record every run with its inputs, logs, and results.
The parts of the system
| Part | What it is | What it does |
|---|---|---|
| Connector | A small server, one per instrument, that speaks the device's own language over serial, TCP, or USB. | Exposes the instrument's functions through SiLA 2, the open standard for calling instrument functions, so Python, the REST API, and the web interface all reach the instrument the same way. |
| GroundControl | The UniteLabs application you install on each lab computer wired to instruments. | Downloads connectors from the UniteLabs registry, lets you configure them, then runs them and links them to your tenant. |
| UniteLabs Platform | Your organization's cloud workspace, called a tenant, as a web application you reach at its own URL. | The control center: shows every connected device with its live status, runs single actions from a form without code, and tracks deployed workflows and their runs with logs, results, and sample lineage. Also holds secrets, stored files, and a built-in Jupyter notebook. |
| UniteLabs SDK | Three Python packages: unitelabs-sdk with the API client and the tools for building workflows, unitelabs-liquid-handling with typed classes for Hamilton and Agilent liquid handlers, unitelabs-labware with plates, tips, and deck layouts. | What your code builds on, from a single instrument call up to a whole workflow. |
| REST API | The HTTPS API of your tenant, with a browsable Swagger UI. | Reaches the same functions from any language: call an instrument, start a workflow run, poll its status, fetch its results, subscribe to its lineage events. |
| Connector Development Kit (CDK) | An open-source Python framework. | Builds a connector for an instrument that has none yet. |
These parts sit in three places:
- In the lab: the connectors and GroundControl, on the computer wired to your instruments.
- On your machine: the scripts and workflows you write in your own editor, and from which you deploy workflows.
- In the cloud: your tenant, which the SDK, the REST API, and the web interface all talk to.
The lab always connects outward with one encrypted connection from the lab computer to your tenant, so no inbound ports need to be opened. Without that connection a connector still works, but only from inside the lab network. See How it works and Network requirements.
What it looks like
Calling a connected instrument from Python, once the four setup steps below are done:
import asyncio
from unitelabs.sdk import AsyncApiClient
from unitelabs.liquid_handling.hamilton import MicrolabSTAR
async def main():
# Connect by the name the instrument carries in your workspace
# AsyncApiClient() reads BASE_URL, AUTH_URL, and the client credentials from .env
hamilton = MicrolabSTAR(name="Microlab STAR", client=AsyncApiClient())
await hamilton.initialize()
# tip_rack and plate come from your deck layout
await hamilton.pipettes.pick_up_tips_from(channels=[0], rack=tip_rack)
await hamilton.pipettes.aspirate(plate["A1"], channels=[0], volume=[50])
await hamilton.pipettes.dispense(plate["B1"], channels=[0], volume=[50])
asyncio.run(main())
The same pattern works for any connected instrument, a thermocycler, a plate reader, a balance, a liquid handler. The use cases show where it leads, from a single device to workflows deployed across several workcells.
Set up your lab in four steps
Your workspace, called a tenant, and the credentials for it come from UniteLabs. Get access lists the five things you receive, where each one goes, and what to have ready on your side.
- Install GroundControl on the lab computer wired to your instruments.
- Add the instrument in GroundControl and pick its connector: browse the UniteLabs registry and download the one for your instrument, and GroundControl fetches the build matching your operating system. The UniteLabs Hub shows publicly what exists. One configuration covers both how the connector reaches the instrument and how it reaches your tenant.
- Prepare your development machine, then install the SDK. The registry credentials fetch the packages, the client credentials let your code authenticate.
- Run your first script: Control a device finds your instrument, lists what it can do, and calls it.
Prefer to work through this interactively? Try the self-paced setup guide.
How these docs are organized
The tabs along the top split the docs by what you're doing:
- Get Started: you're here. Setup comes first, then three tutorials: control a device, liquid handling as code, and automate your workflows. The self-paced setup guide closes the tab.
- Concepts: how UniteLabs models things, for when you want the why. Start with lab as code, then connectors and devices, liquid handling and robots, workflows, and data.
- How-to: short tasks you come back to: setup beyond the first run, connecting and calling devices, workflows, and data.
- Devices: one page per tested instrument. Connect it, check it responds, and run a first command.
- Liquid Handling and Robots: driving a liquid handler or robot in depth. The deck, pipetting, simulation, and what's specific to each device.
- Labware: the catalog of plates, tips, tubes, troughs, and carriers.
- API reference: the REST API and the reference for every UniteLabs Python package.
- CDK: building your own connector for an instrument that has none yet.
Resources and help
The UniteLabs Hub lists the connectors that already exist, so check there before building one. For technical problems and for anything wrong in these docs, write to support@unitelabs.io; for access, credentials, and commercial questions, talk to your UniteLabs contact or info@unitelabs.io. Support lists what each channel covers.
Last updated