Connector
A connector is a standalone application that represents a single lab instrument in UniteLabs. It runs on the edge machine — the computer physically connected to the instrument — and exposes the instrument's capabilities through a structured, typed, and introspectable API that GroundControl, the UniteLabs SDK, and the REST API can all call.
Terminology
UniteLabs uses one set of labels for connector capabilities across every surface — the platform UI, the Python SDK, the REST API, and GroundControl.
| Docs concept | UI label | Python SDK | REST API |
|---|---|---|---|
| Module | Module | .modules | /modules |
| Property action (scalar read) | Property | action with type=PROPERTY | /actions (filter type=PROPERTY) |
| Sensor action (stream) | Sensor | action with type=SENSOR | /actions (filter type=SENSOR) |
| Control action (trigger) | Control | action with type=CONTROL | /actions (filter type=CONTROL) |
| Subscription | live-stream panel on Sensor | async for | /subscriptions |
Every action has a type: Property (read a scalar once), Sensor (subscribe to a stream), or Control (trigger an action). The UI groups actions into three sections by type; the SDK and REST API expose the type as a field on each action.
In the REST API a connector itself is called a service (endpoint: /v1/services). In this documentation we use "connector" because it is the term the product is built around — the Connector Development Kit, the connector registry, and GroundControl's Connectors tab all use it. Mentally: service = connector instance.
Identity
Every connector has four pieces of identity:
| Field | Description |
|---|---|
| Name | Human-readable label, e.g. Hamilton STAR (Bench 3) |
| UUID | Stable unique identifier — assigned on first start and never changes |
| Type | The instrument category, e.g. liquid_handler, balance, thermocycler |
| Version | The connector software version |
The UUID is how the UniteLabs SDK and REST API reference a specific connector instance. The name is what appears in GroundControl and the platform UI.
Modules
A connector groups its capabilities into modules. Each module represents one functional aspect of the instrument. For example, a balance connector might expose:
WeighingService— tare, zero, read weightLockController— exclusive device locking to prevent concurrent access
Modules are the unit of organization within a connector's API. Expanding a module in the UI reveals its actions, grouped by type into Properties, Sensors, and Controls.
Built-in modules
Every connector — regardless of instrument — ships with these modules automatically:
| Module | Purpose |
|---|---|
| Service metadata | Lists the connector's other modules so clients can introspect capabilities. Required for discovery. |
LockController | Lets clients acquire exclusive access to the instrument |
SimulationController | Toggle simulation mode — the connector responds with realistic fake values instead of talking to the hardware |
Simulation mode is useful for developing workflows before the instrument is available, or for testing without consuming physical resources.
How connectors talk to instruments
Under the hood, connectors implement one of several integration protocols — SiLA 2 (the UniteLabs default, used by any connector built with the CDK), OPC-UA LADS (for vendors shipping LADS-compliant instruments), and adapters for LIMS / ELN systems. From a consumer's perspective this is invisible: every connector exposes the same Module / Action / Subscription model regardless of what it is speaking to the instrument. If you are building a connector, read SiLA in the CDK docs for the protocol-layer detail.
Lifecycle
Regardless of how a connector is managed, its lifecycle is the same:
- Start: the connector executable launches with a
config.jsonfile. It connects to the instrument and starts its local server. - Running: the connector is reachable locally. If cloud is configured, it maintains an outbound relay to the UniteLabs cloud.
- Stop / Restart: the connector receives a shutdown signal, closes its instrument connection, and exits cleanly.
Via GroundControl: the GUI manages the process directly and shows status, logs, and restart controls in the interface. Connectors can be registered for auto-restart.
Via systemd (or another process supervisor): the connector runs as a system service that starts automatically on boot and restarts on failure. This is the typical setup for headless Linux servers and Raspberry Pi devices.
Configuration
Each connector has a configuration file that captures the instrument-specific settings — typically the instrument's hostname or IP address, port, and any authentication details. GroundControl generates a configuration form from the connector's own schema when you add a device, so you fill in fields specific to that instrument rather than editing a file manually.
For connectors run as standalone executables, configuration is stored in a config.json file alongside the binary. Run the connector once with the config create command to generate the default file, then edit it before starting the connector for real.