Connector

A connector is a small, standalone application that sits between a lab instrument and the rest of your automation stack. It speaks the instrument's native language on one side (serial, TCP, USB, whatever the device requires) and exposes a structured, typed, and introspectable API on the other. GroundControl, the UniteLabs platform, and the UniteLabs SDK all talk to that API without knowing anything about the instrument's own protocol.

How it fits together

 Lab Instrument
      │  (device protocol: serial, TCP, USB…)
      ▼
  Connector  ◄──── manages ────  GroundControl
      │  (SiLA 2 / gRPC)
      ▼
  UniteLabs Platform & REST API (Academic, Cloud, Enterprise, On-Prem)
      │
      ▼
  Platform UI  ·  UniteLabs SDK · 3rd Party Applications

The connector runs as a local process on the edge machine — the computer physically connected to the instrument. Connectors are distributed as self-contained executables that you can run in two ways:

• GroundControl: a desktop application that downloads, configures, and manages connector processes through a GUI. The recommended starting point for most labs.
• Direct executable: drop the binary on any Linux or Windows server, Raspberry Pi, or embedded device and manage it as a system service. No GUI required. See Headless install.

Terminology

UniteLabs uses one set of labels for connector capabilities across every surface — the platform UI, the Python SDK, the REST API, and GroundControl.

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:

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 weight
• LockController — 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:

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:

1. Start: the connector executable launches with a config.json file. It connects to the instrument and starts its local server.
2. Running: the connector is reachable locally. If cloud is configured, it maintains an outbound relay to the UniteLabs cloud.
3. 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.

Where connectors come from

Connector registry: UniteLabs maintains a catalogue of versioned connectors for common lab instruments. GroundControl can browse and download connectors from the registry with one click.

Custom connectors: For instruments not in the registry, you can build your own using the Connector Development Kit (CDK). The CDK lets you write a connector in pure Python using simple decorators — no knowledge of network protocols required.

Next steps

Both paths install and run connector processes on your edge machine, the computer physically connected to your instruments.

• Install GroundControl: the recommended path for workstations and lab PCs
• Headless install: for servers, Raspberry Pi, and other embedded Linux devices