Measurement Triggers

Measurement triggers are the primary way to obtain data from a connected instrument. A trigger executes a device-class–specific measurement procedure and returns a measurement container — by default a binary RAE file (see RAE File Format) — containing all metric values, metadata and any attached device images.

Endpoints Overview

Listing Available Triggers

GET /v1/devices/{deviceId}/measurement-triggers

curl http://localhost:42042/v1/devices/12f1d7dd07ac42a088c8f961b39d68ff/measurement-triggers

The response describes which triggers the connected device supports and which parameters they accept. Example shape:

[
  {
    "identifier": "measure",
    "title": "Measure",
    "category": "measure",
    "parameters": [
      {
        "key": "metricGroupKeys",
        "type": "EnumArray",
        "description": "Specify the metric group keys measured."
      },
      {
        "key": "imageFormat",
        "type": "String",
        "description": "Image encoding for images in the RAE container. Allowed values: 'image/png' (default), 'image/jpeg', 'image/x-raw'."
      }
    ]
  }
]

Use the listing endpoint to discover the parameter keys that are valid for the specific device class and firmware combination — they may evolve between releases.

Executing a Measurement

POST /v1/devices/{deviceId}/measurement-triggers
Content-Type: application/json

{
  "measurementKey": "measure",
  "containerFormat": "raeBinary",
  "parameters": [
    { "key": "metricGroupKeys", "value": ["sparkle", "scratchLinear"] },
    { "key": "imageFormat",     "value": "image/png" }
  ]
}

curl -X POST http://localhost:42042/v1/devices/12f1d7dd07ac42a088c8f961b39d68ff/measurement-triggers \
  -H "Content-Type: application/json" \
  -d '{
    "measurementKey": "measure",
    "containerFormat": "raeBinary",
    "parameters": [
      { "key": "metricGroupKeys", "value": ["sparkle", "scratchLinear"] }
    ]
  }' \
  --output measurement.rae

Request Body

Container Formats

The container always contains the full measurement tree: scalar metrics, hierarchical groups, attached images, and metadata. The choice between raeBinary and raeJson affects encoding only, not content.

Image Encoding

Device images embedded in the container are PNG-encoded by default. The optional imageFormat operation parameter on Aesthetix devices selects an alternative encoding:

See Measurement Image Formats for the binary layout of image/x-raw, parsing examples, and per-image notes (some images are cropped server-side before PNG/JPEG encoding; the raw payload is uncropped).

Aesthetix Metric Groups

For Aesthetix-family devices the metricGroupKeys parameter selects which metric groups participate in the measurement. Typical values include sparkle, scratchLinear, scratchRadial, gloss, haze, cell, waviness, crossCut, shadeImages. See Aesthetix — Available Measurements for the full list. Pass an empty array or omit the parameter to use the device's default selection.

Decoding the Container Client-Side

If you receive a binary RAE container and want to decode it without parsing the format yourself, the hub also exposes:

POST /v1/measurements/decode
Content-Type: multipart/form-data

Upload a .rae file as form data and receive the parsed measurement components as JSON. Useful for testing and one-off decoding from environments where embedding a RAE parser is impractical.

Best Practices

• Call the GET endpoint once after connecting and cache the trigger metadata for the lifetime of the connection — the parameter list does not change while the device is connected.
• Validate parameters against the metadata returned by GET to avoid runtime parameter errors.
• For Aesthetix devices, restrict metricGroupKeys to the metrics you actually need. Each group adds processing time on the device side; an unrestricted measurement is several seconds slower than a single-group measurement.
• Prefer raeBinary for any data that is going to be stored — the size difference compared to raeJson is significant for measurements that contain images.

Error Cases

See Error Handling for the response format.