screen.quality

Screen colour & brightness quality

Reports how far a screen's brightness and colour have drifted from its calibrated baseline. Sent from Harvester readings, at most once per screen per windowSeconds, and averaged over that window. Each channel is scored as value / reference * 100, so 100 is exactly on the baseline. On an uncalibrated screen, references are null and status is UNKNOWN.

No event means no data, not a healthy screen. Vojo sends the value, the reference and the score; you decide what counts as bad.

Delivery headers

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-Vojo-Signature: t=1761037200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Example payload

{
  "eventType": "screen.quality",
  "attemptId": "att_7Hq2",
  "eventId": "evt_screen_quality_01",
  "screenId": "scr_123",
  "screenName": "Platform 2 north",
  "basis": "drift-from-calibration",
  "calibratedAt": "1759312800",
  "windowSeconds": 3600,
  "windowEndAt": "1761037200",
  "thresholdPct": 10,
  "brightness": {
    "value": 1180,
    "reference": 1200,
    "score": 98,
    "status": "GOOD"
  },
  "colour": {
    "red": {
      "value": 412,
      "reference": 420,
      "score": 98,
      "status": "GOOD"
    },
    "green": {
      "value": 515,
      "reference": 500,
      "score": 103,
      "status": "GOOD"
    },
    "blue": {
      "value": 240,
      "reference": 300,
      "score": 80,
      "status": "BAD"
    },
    "status": "BAD"
  }
}

Payload

eventTypestringRequired
Always screen.quality
eventIdstringRequired
Stable per-event id, constant across retries (injected at delivery). Dedupe on this.
screenIdstringRequired
screenNamestringRequired
basisstringRequired
Always drift-from-calibration
windowSecondsintegerRequired
The throttle/averaging window this payload covers.
windowEndAtstringRequired
Epoch (seconds) of the latest reading in this window. Use for staleness — absence of events means no data, not "healthy".
thresholdPctnumber or nullRequired
GOOD/BAD band half-width around 100 (your organisation's quality threshold, default 10 = +/-10%). Symmetric, so both over-bright and too-dim are BAD. Same value for brightness and every colour channel. null when no alerting config.
brightnessobjectRequired
The white / clear channel.
Show 4 fields
- valuenumber or nullRequired
  The measured reading (averaged over the window).
- referencenumber or nullRequired
  The calibration baseline this channel was scored against. Null when uncalibrated.
- scorenumber or nullRequired
  round(value / reference * 100). Null when not computable.
- statusstringRequired
  GOOD within +/- the org quality threshold of 100; UNKNOWN when not assessable.
  One of GOOD, BAD, UNKNOWN
colourobjectRequired
Show 4 fields
- redobjectRequired
  One scored channel. score = round(value / reference * 100); 100 = on the calibrated baseline.
  Show 4 fields
  - valuenumber or nullRequired
    The measured reading (averaged over the window).
  - referencenumber or nullRequired
    The calibration baseline this channel was scored against. Null when uncalibrated.
  - scorenumber or nullRequired
    round(value / reference * 100). Null when not computable.
  - statusstringRequired
    GOOD within +/- the org quality threshold of 100; UNKNOWN when not assessable.
    One of GOOD, BAD, UNKNOWN
- greenobjectRequired
  One scored channel. score = round(value / reference * 100); 100 = on the calibrated baseline.
  Show 4 fields
  - valuenumber or nullRequired
    The measured reading (averaged over the window).
  - referencenumber or nullRequired
    The calibration baseline this channel was scored against. Null when uncalibrated.
  - scorenumber or nullRequired
    round(value / reference * 100). Null when not computable.
  - statusstringRequired
    GOOD within +/- the org quality threshold of 100; UNKNOWN when not assessable.
    One of GOOD, BAD, UNKNOWN
- blueobjectRequired
  One scored channel. score = round(value / reference * 100); 100 = on the calibrated baseline.
  Show 4 fields
  - valuenumber or nullRequired
    The measured reading (averaged over the window).
  - referencenumber or nullRequired
    The calibration baseline this channel was scored against. Null when uncalibrated.
  - scorenumber or nullRequired
    round(value / reference * 100). Null when not computable.
  - statusstringRequired
    GOOD within +/- the org quality threshold of 100; UNKNOWN when not assessable.
    One of GOOD, BAD, UNKNOWN
- statusstringRequired
  Worst of the three channels.
  One of GOOD, BAD, UNKNOWN
attemptIdstring
Per-attempt id; CHANGES on each retry. Do not dedupe on this.
calibratedAtstring or null
Epoch (seconds) the active calibration baseline was taken; null when uncalibrated.

Handling this event

Verify the signature, reply with a 2xx within 20 seconds, then process the event in the background. Retries reuse the same event id, so deduplicate on it.