Rhopoint Instruments Manual
MD Wyświetl jako Markdown
Ta strona nie została jeszcze przetłumaczona i jest wyświetlana w języku angielskim.

API Overview

The Elements Hub REST API provides comprehensive access to device discovery, connection, measurement acquisition, calibration, image streaming, and self-administration. This page is the top-level map — every section links to the detailed reference for the matching endpoints.

For an interactive way to explore and try the API see the Swagger UI Guide. For strongly typed client libraries see Client Code Generation.

API Version

Current version: 1.0

All endpoints are versioned and follow the pattern: /v1/{resource}. The default base URL is http://localhost:42042 — see Network Binding for how to change it.

Workflow at a Glance

Almost every integration follows the same sequence. See Endpoints — Functionality for the prose walkthrough and step-by-step links:

  1. Initialize lifecycle services
  2. Start a device scan
  3. Connect to a discovered device
  4. Calibrate (where required)
  5. Trigger measurements and / or consume image streams
  6. Disconnect
  7. Shut down lifecycle services

Endpoint Reference

Area Reference Endpoints
Service lifecycle Lifecycle POST /v1/lifecycle/initialize, POST /v1/lifecycle/shutdown
Device discovery Device Scans POST/GET/DELETE /v1/device-scans, GET /v1/available-devices
Device connection Connected Devices POST/GET/DELETE /v1/devices, property lookup
Measurements Measurement Triggers GET/POST /v1/devices/{deviceId}/measurement-triggers, POST /v1/measurements/decode
Calibration Calibrations GET/POST /v1/devices/{deviceId}/calibrations, GET /calibrations/status
Live imaging Image Streams POST/DELETE /v1/devices/{deviceId}/image-streams/{sourceKey}, start/configure/snapshot/stream
Host diagnostics System GET /v1/system/version, GET /v1/system/checks, POST /v1/system/errors/raise-exception
Self-update App Updates GET /v1/app-updates/info, POST /v1/app-updates/action

Cross-Cutting Topics

  • Error Handling — uniform ErrorInfo response format and the id.rhopointservice.com/E<n> reference URLs.
  • Security Notice — current authentication and transport posture; important to read before exposing the hub on a network.
  • Measurement Image Formats — encoding of device images inside measurement containers (PNG / JPEG / raw).
  • RAE File Format — binary layout of the measurement container produced by Measurement Triggers.
  • Mock Devices — running the API without physical hardware for development and CI.

Core Concepts

Devices

  • Available Devices — devices discovered by a running scan that can be connected. See Polling Discovered Devices.
  • Connected Devices — devices currently connected and ready for operations. See Connected Devices.
  • Device Class — identifies the model behind a device record (e.g. aesthetix, aesthetix-inline, id-inline, plus -mock variants). The class drives which calibrations, measurements and image sources are available — see Aesthetix for one example.

Scans

  • Device Scans — background processes that discover available devices on the network or attached via USB. See Device Scans.
  • One scan covers exactly one device class. To search for multiple classes in parallel, start multiple scans.

Measurements & Operations

  • Measurement Triggers — commands that initiate data acquisition from connected devices. See Measurement Triggers.
  • Calibrations — operations that re-reference the device's measurement chain against known standards. See Calibrations.
  • Commands — device-class–specific actions, discoverable via GET /v1/devices/{deviceId}/commands.
  • Container Formats — output containers for measurements, currently raeBinary (default) and raeJson. See Container Formats and RAE File Format.

HTTP Methods Used

Method Usage
GET Retrieve information (devices, scans, status, snapshots).
POST Create resources or initiate operations (connect devices, start scans, trigger measurements, run calibrations).
DELETE Remove resources (disconnect devices, stop scans, stop image streams).

Content Types

Request

  • application/json — used by every endpoint that accepts a body, except POST /v1/measurements/decode.
  • multipart/form-data — only by POST /v1/measurements/decode (file upload for RAE decoding, see Decoding the Container Client-Side).

Response

Content type Endpoint(s)
application/json Standard API responses, including ErrorInfo payloads — see Error Handling.
application/vnd.rhopoint.rae+binary POST /v1/devices/{deviceId}/measurement-triggers with containerFormat: raeBinary — see RAE File Format.
image/png / image/jpeg / image/bmp Snapshots and single-image endpoints — see Snapshot — Single Frame.
image/x-raw Raw device images embedded in a measurement container — see Measurement Image Formats.
text/event-stream Live image streams — see Consuming the Stream (SSE).
text/plain GET /v1/logs.

Response Patterns

Successful responses use the shape documented on each endpoint's reference page. There is no uniform "envelope" wrapping every response — for example, GET /v1/devices returns a JSON array of device records, GET /v1/system/version returns an object, and a successful measurement returns the raw RAE container as a binary body.

Error responses always follow a single schema, regardless of which endpoint produced them. See Error Handling for the full ErrorInfo format, the errorCode/errorUrl contract, and recommended client patterns.

Authentication

None. Any caller that can reach the listening socket can call every endpoint. Read Security Notice before binding the hub to anything other than localhost.

Rate Limiting

Currently, no rate limiting is implemented, but clients should:

  • Avoid excessive polling of `GET /v1/available-devices` or status endpoints — once a second is typically sufficient.
  • Allow adequate time between measurement triggers — many measurements take several seconds on the device side.
  • Reuse a single connection over many measurements rather than connect/disconnect cycles; see Connected Devices — Best Practices.

Asynchronous Operations

A few operations follow a start-then-poll pattern rather than blocking on the response:

  • Device scanning — POST starts the scan, GET /v1/available-devices polls for results, DELETE stops.
  • Application download — POST .../action "download" stages the update, GET .../info reports updateDownloaded.
  • Image streams — POST .../start enables the stream, GET .../stream opens an SSE subscription, DELETE tears down.

Connect / disconnect, measurements and calibrations are synchronous: the POST does not return until the operation has finished on the device. Make sure the HTTP client timeout is long enough — at least 30 s is a safe baseline for measurements and calibrations.