Device

A connector is the software. A device is the physical thing the connector controls. UniteLabs keeps these two concepts distinct because a connector's identity (install, version, running process) evolves differently from a device's identity (serial number, location, calibration history, ownership).

The platform tracks two related but separate entities:

• Device Metadata — the catalog of known device types. "Hamilton Microlab STAR" as a product model, with manufacturer, device category, and part number. Read-only from a consumer's perspective; managed by UniteLabs.
• Device — your registered instance. "Our Hamilton STAR on Bench 3, serial SN-1234, owned by Lab Team A." You create, update, and delete devices. Each device links back to a Device Metadata entry to declare what type it is.

Why the split

A workflow that targets "any Hamilton STAR" is a different thing from a workflow that targets "the Hamilton STAR on Bench 3." Device Metadata gives you the former (the type system); Device gives you the latter (the instance). Audit trails, location filters, and ownership live on Device, not Device Metadata.

Registering a device

curl -X POST "$BASE_URL/v1/devices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hamilton STAR (Bench 3)",
    "metadataId": 618,
    "serialNumber": "SN-1234",
    "location": "Lab 2 / Bench A",
    "owner": "team-automation",
    "tags": ["liquid-handler", "production"]
  }'

metadataId is the numeric ID from /v1/device-metadata — it tells the platform what kind of device this is. All other fields describe your specific instance.

Browsing the catalog and the registry

# What types of devices does UniteLabs know about?
curl "$BASE_URL/v1/device-metadata?deviceCategory[like]=Liquid%20Handler" \
  -H "Authorization: Bearer $TOKEN"

# Which physical devices do we have registered?
curl "$BASE_URL/v1/devices?tags=liquid-handler&location=Lab%202" \
  -H "Authorization: Bearer $TOKEN"

Device Metadata is searchable by category, manufacturer, and name. Device is searchable by any combination of its fields — serial number, location, owner, tags, or creation / update dates.

How devices relate to connectors

A connector runs on the edge machine and controls one device. The link between them is created during connector setup: when you add a connector via GroundControl, you pick which registered Device it controls. The platform maintains this mapping so workflows can ask "which connector serves Device X?" and get a single, stable answer.

This indirection is why the service / connector / device trio exists as three distinct concepts rather than one — they have independent life cycles. A device can outlive any specific connector version; a connector process can be restarted without re-registering the device.

Soft delete

Devices are not hard-deleted by default. DELETE /v1/devices/{id} sets a deletedAt timestamp so the audit trail stays intact and historical runs that referenced the device remain queryable. Filter deleted devices out of list queries with the deletedAt field when you do not want to see decommissioned instruments.