Read raw thermal frames

GET /v1/sensors/{key}/frames?from={unix_ms}&to={unix_ms}&limit={count}&compensate=0

key is a current sensor mac or serial discovered with GraphQL.

Parameters

Parameter	Required	Description
`from`	Yes	Inclusive window start, Unix milliseconds.
`to`	Yes	Window end, Unix milliseconds; must be greater than or equal to `from`.
`limit`	No	Sampled frame limit. Default `2000`, maximum `5000`; `0` requests all frames within server bounds.
`hallId`	No	Hall context for hall-specific compensation. It cannot bypass sensor ownership.
`compensate`	No	Set to `0` or `false` to guarantee raw device matrices. Otherwise server-side angle compensation may apply.
`include_raw`	No	With compensation active, set to `1` or `true` to include the original matrix as `raw_data`.

The server selects a fine or coarse archive tier from the requested span. An unarchived window returns 200 with no frames and a non-zero missing count. A storage or decode failure returns 502 instead of silently falling back to a different data source.

Response fields

{
  "key": "00-00-00-00-00-00",
  "kind": "wireless",
  "tier": "fine",
  "from": 1793058000000,
  "to": 1793058300000,
  "count": 1,
  "total": 1,
  "sampled": false,
  "objects": 1,
  "missing": 0,
  "compensated": false,
  "pivot_fallback_frames": 0,
  "frames": [
    {
      "timestamp": 1793058299000,
      "min_c": 21.4,
      "max_c": 31.8,
      "data": [[2945, 2947]]
    }
  ]
}

The short matrix is illustrative. Current Heatic 3 sensors produce 40 rows by 60 columns. With compensate=0, data is the row-major raw uint16 deciKelvin field; convert one value v to Celsius with v / 10 - 273.15. A value of 0 represents a dead pixel.

Without compensate=0, inspect top-level compensated. When it is true, data is angle-corrected; request include_raw=1 to receive the original field as raw_data in the same response.

min_c and max_c are already Celsius. sampled is true when total exceeds count. objects is the number of archive objects read; missing is the number of expected segment objects not found, not the number of missing pixels.