Connected Devices

Once a device has been discovered by a device scan, it can be connected and used for measurements, calibrations and image acquisition. A connected device occupies the hub's communication channel to the hardware until it is explicitly disconnected (or the hub is shut down).

Endpoints Overview

Typical Workflow

1. Initialize lifecycle services
2. Start a device scan for the relevant device class
3. Poll GET /v1/available-devices until the target device appears
4. Connect with POST /v1/devices
5. Use the device for measurements, calibrations and image acquisition
6. Disconnect with DELETE /v1/devices/{deviceId}
7. Shut down lifecycle services

Connecting a Device

POST /v1/devices
Content-Type: application/json

{
  "deviceIdentifier": "12f1d7dd07ac42a088c8f961b39d68ff"
}

curl -X POST http://localhost:42042/v1/devices \
  -H "Content-Type: application/json" \
  -d '{ "deviceIdentifier": "12f1d7dd07ac42a088c8f961b39d68ff" }'

Request Body

Response

A successful connect returns the device record, now extended with a connectTime timestamp:

{
  "identifier": "12f1d7dd07ac42a088c8f961b39d68ff",
  "deviceClass": "aesthetix-inline",
  "serialNumber": "AXI8000027",
  "serialNumbers": ["AXI8000027"],
  "hardwareVersion": "…",
  "firmwareVersion": "…",
  "softwareVersion": "…",
  "componentVersions": [],
  "connectTime": "2025-11-12T08:16:02.1234567+00:00"
}

Listing Connected Devices

GET /v1/devices

Returns an array of connected devices in the same shape as the connect response. An empty array means no devices are currently connected.

Getting a Single Connected Device

GET /v1/devices/{deviceId}

Use the identifier value as {deviceId}. Returns the full device record or HTTP 404 (E5) if no device with that identifier is connected.

Reading a Single Property

GET /v1/devices/{deviceId}/serialNumber

The property-lookup endpoint returns the value of a single field of the device record. Useful when a client only needs one piece of information and wants to avoid parsing the full record. Returns HTTP 404 (E4) if the property does not exist on the device.

Disconnecting a Device

DELETE /v1/devices/{deviceId}

curl -X DELETE http://localhost:42042/v1/devices/12f1d7dd07ac42a088c8f961b39d68ff

Disconnect cleanly releases the device's communication channel and persists any pending calibration or configuration state. Always disconnect explicitly before shutting down the hub if possible — although POST /v1/lifecycle/shutdown will also disconnect every device, an explicit disconnect surfaces errors immediately instead of during shutdown.

Behaviour on Re-Connect

• Disconnecting and re-connecting the same device returns a new identifier — the identifier is tied to a discovery session, not the hardware. After a re-connect, update any cached identifiers on the client side.
• Calibration data is persisted by serial number and device class, so a re-connected device retains its previous calibration state without further action.

Best Practices

• Always check GET /v1/available-devices for the target serial number before calling POST /v1/devices — the identifier returned by an older scan may no longer be valid if the scan was stopped in between.
• Wrap the connect/use/disconnect sequence in a try/finally on the client side to guarantee disconnect even when measurement errors occur.
• For long-running integrations, prefer one persistent connection over repeated connect/disconnect cycles — the subprocess startup cost is the main reason connecting is slower than measuring.
• Use GET /v1/devices after start-up to detect devices that may already be connected (for example, after the hub was restarted while clients still held the previous identifier).

Error Cases

See Error Handling for the response format.