# Connected Devices

> [!note] Ta strona nie została jeszcze przetłumaczona i jest wyświetlana w języku angielskim.


Once a device has been discovered by a [device scan](rhopoint-elements-hub-endpoints-functionality-device-scans.md), 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

| Method | Endpoint | Description |
| --- | --- | --- |
| POST | `/v1/devices` | Connect a previously discovered device |
| GET | `/v1/devices` | List all currently connected devices |
| GET | `/v1/devices/{deviceId}` | Get a single connected device by identifier |
| GET | `/v1/devices/{deviceId}/{propertyName}` | Read a single property of a connected device |
| DELETE | `/v1/devices/{deviceId}` | Disconnect a device |

### Typical Workflow

1. [Initialize lifecycle services](rhopoint-elements-hub-endpoints-functionality-lifecycle.md)
2. [Start a device scan](rhopoint-elements-hub-endpoints-functionality-device-scans.md) 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](rhopoint-elements-hub-endpoints-functionality-measurement-triggers.md), calibrations and image acquisition
6. Disconnect with `DELETE /v1/devices/{deviceId}`
7. [Shut down lifecycle services](rhopoint-elements-hub-endpoints-functionality-lifecycle.md)

### Connecting a Device

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

{
  "deviceIdentifier": "12f1d7dd07ac42a088c8f961b39d68ff"
}
```

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

#### Request Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deviceIdentifier` | string | Yes | Identifier returned by `GET /v1/available-devices`. |
| `parameters` | array | No | Optional list of device-class–specific connection parameters as `{ "key": "...", "value": ... }` entries. Most devices require no parameters. |

#### Response

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

```json
{
  "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

```http
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

```http
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

```http
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

```http
DELETE /v1/devices/{deviceId}
```

```bash
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

| Condition | HTTP | Error Code |
| --- | --- | --- |
| Identifier does not match any discovered device | 404 | `E3` |
| Connect failed (hardware error, device busy, …) | 502 | `E8` |
| Requested connected device not found | 404 | `E5` |
| Requested property does not exist on device | 404 | `E4` |

See [Error Handling](rhopoint-elements-hub-error-handling.md) for the response format.