# Device Scans

> [!note] Tato stránka ještě není přeložena do češtiny a zobrazuje se anglicky.


Device scans discover instruments that are available to the host machine but not yet connected. A scan is an asynchronous, long-running background process — typically backed by a device-class–specific subprocess that polls hardware or the local network. Clients start a scan, poll the list of available devices, and either stop the scan once a device has been found or keep it running for continuous discovery.

### Endpoints Overview

| Method | Endpoint | Description |
| --- | --- | --- |
| POST | `/v1/device-scans` | Start a new scan for a specific device class |
| GET | `/v1/device-scans` | List all active scans |
| GET | `/v1/device-scans/{scanId}` | Get a single scan by identifier |
| GET | `/v1/device-scans/{scanId}/{propertyName}` | Read a single property of a scan |
| DELETE | `/v1/device-scans/{scanId}` | Stop and remove a scan |

> [!note]
> Scans must be started against a known device class. The same device class is used later when connecting (see [Connected Devices](rhopoint-elements-hub-endpoints-functionality-connected-devices.md)). Common values are `aesthetix`, `aesthetix-inline`, `id-inline` and their `-mock` variants (see [Mock Devices](rhopoint-elements-hub-mock-devices.md)).

### Starting a Scan

```http
POST /v1/device-scans
Content-Type: application/json

{
  "deviceClass": "aesthetix-inline"
}
```

```bash
curl -X POST http://localhost:42042/v1/device-scans \
  -H "Content-Type: application/json" \
  -d '{ "deviceClass": "aesthetix-inline" }'
```

#### Request Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deviceClass` | string | Yes | Class of device to scan for (e.g. `aesthetix`, `aesthetix-inline`, `id-inline`) |
| `serialNumberFilter` | string | No | Restrict discovery to devices whose serial number matches the given pattern |
| `ipAddressFilter` | string | No | For network-discovered devices, restrict discovery to a specific IP address or range |

#### What happens internally

Starting a scan spawns the device-class–specific subprocess (for Aesthetix-family devices that is `Aesthetix.exe` / `AesthetixKernel.exe`). The subprocess handles direct communication with the device, including taking measurements and calculating metrics. It is kept alive for as long as the scan or any device connection of that class is active.

### Listing Active Scans

```http
GET /v1/device-scans
```

Example response:

```json
[
  {
    "identifier": "9d8e2f1a-…",
    "scanFilter": {
      "deviceClass": "aesthetix-inline",
      "serialNumberFilter": null,
      "ipAddressFilter": null
    },
    "status": "running",
    "foundDevices": [
      "12f1d7dd07ac42a088c8f961b39d68ff"
    ]
  }
]
```

The `foundDevices` array contains the identifiers of every available device found by this scan so far. To retrieve the full device records, use [the available-devices endpoints](rhopoint-elements-hub-endpoints-functionality-connected-devices.md).

### Polling Discovered Devices

While a scan is running, query `GET /v1/available-devices` to retrieve the discovered devices and their metadata:

```http
GET /v1/available-devices
```

Example response:

```json
[
  {
    "discovered": "2025-11-12T08:15:26.7825826+00:00",
    "identifier": "12f1d7dd07ac42a088c8f961b39d68ff",
    "deviceClass": "aesthetix-inline",
    "serialNumber": "AXI8000027",
    "serialNumbers": [
      "AXI8000027"
    ],
    "hardwareVersion": "…",
    "firmwareVersion": "…",
    "softwareVersion": "…",
    "componentVersions": []
  }
]
```

The `identifier` field is what you pass to `POST /v1/devices` to establish a connection. See [Connected Devices](rhopoint-elements-hub-endpoints-functionality-connected-devices.md) for the follow-up step.

### Stopping a Scan

```http
DELETE /v1/device-scans/{scanId}
```

```bash
curl -X DELETE http://localhost:42042/v1/device-scans/9d8e2f1a-…
```

Stopping a scan tears down the discovery loop. If no connected device of the same class remains, the associated subprocess is shut down as well.

### When to Stop the Scan

- **USB-attached devices (Aesthetix, ID Inline)**: stop the scan once the device has been found and you are about to connect. Keeping the scan running adds no value and consumes a subprocess slot.
- **Network-discovered devices (Aesthetix Inline)**: it is acceptable to keep the scan running while working with the device — discovery is low-cost, and clients may want to detect hot-plugged devices on the same network.

### Best Practices

- Always start a scan **after** calling [`POST /v1/lifecycle/initialize`](rhopoint-elements-hub-endpoints-functionality-lifecycle.md). The hub rejects scan requests if the lifecycle services have not been initialized.
- Treat the scan identifier as opaque; do not parse or rely on its format.
- Poll `GET /v1/available-devices` rather than `GET /v1/device-scans/{scanId}` to read the discovered devices — `available-devices` returns full device records, `device-scans` returns identifiers only.
- Stop scans you no longer need to free the underlying subprocess.
- On shutdown, [`POST /v1/lifecycle/shutdown`](rhopoint-elements-hub-endpoints-functionality-lifecycle.md) stops all scans automatically; explicit `DELETE` is only required when you want to stop a scan mid-session.