Skip to main content

MQTT

EverNVR can publish what it sees to an MQTT broker: object detections, alerts, each camera's connection, activity, object counts and tamper state, and the recorder's own health. Building management, access control and automation systems that speak MQTT can subscribe to it. MQTT is off until an administrator turns it on.

The recorder only publishes. It subscribes to nothing, so nothing sent to the broker can move a camera, change a setting, or reach the recorder.

Connect a broker​

An administrator opens Settings → MQTT:

FieldNotes
Broker URLmqtt://, mqtts://, ws:// or wss://, with a port if it is not the default
User name, passwordOptional. The password is stored in the credential vault and never displayed again
Topic prefixDefault evernvr. Every topic below starts with it
Client IDOptional. Left empty, one is made from the recorder's identity
CA certificatemqtts:// and wss:// only. Paste a PEM certificate when the broker uses a private CA

Check Publish to MQTT and save. The status line shows Connected, or the reason the connection failed, and the recorder keeps retrying every five seconds. Send test message publishes to <prefix>/test.

mqtt:// and ws:// are unencrypted. Use mqtts:// or wss:// when the broker is not on the same trusted network.

MQTT is a licensed feature. Where the recorder's license does not include it, checking Publish to MQTT and Send test message are refused. A broker already connected stays connected, and its settings can still be changed.

warning

Anyone who can subscribe to <prefix>/# on the broker sees every camera's detections, whatever their EverNVR account is allowed to see. Use the broker's access control to restrict who can read the prefix.

Topics​

<camera> is the camera's name in lower case, with spaces and punctuation replaced by _ (for example, Front Door becomes front_door). If two cameras have the same name, the camera ID is added to the end. When a camera is renamed or removed, the recorder clears what it retained under the old name.

Retained topics hold current state. The broker keeps the last value, so a subscriber that connects later gets the current state right away. The other topics carry one-time events and are not retained.

TopicRetainedPayload
<prefix>/availabilityyesonline, or offline when the recorder stops or loses the broker (MQTT last will)
<prefix>/eventsnoOne detection, JSON (below)
<prefix>/cameras/<camera>/eventsnoThe same, for one camera
<prefix>/cameras/<camera>/stateyes{"state":"online","reason":null}
<prefix>/cameras/<camera>/activeyesON while a person or a moving vehicle is in view, else OFF
<prefix>/cameras/<camera>/objects/<label>yesHow many confirmed objects of that label are in view now, such as 2. person and car always exist; other labels appear when first seen
<prefix>/cameras/<camera>/tamperyes{"active":true,"kind":"blinded","since":1790000000000}
<prefix>/cameras/<camera>/snapshotyesThe latest detection picture as JPEG bytes, when Snapshot of each detection is on
<prefix>/cameras/<camera>/camera_eventsnoThe camera's own ONVIF events, when they are switched on for that camera: {"kind","phase","topic","at"}
<prefix>/cameras/<camera>/camera_events/<kind>yesON or OFF for a camera event that begins and ends, such as motion
<prefix>/alertsnoAn action rule that fired: {"alertId","ruleId","rule","eventId","camera","triggerType","state","at"}
<prefix>/alarmsnoA recorder alarm (storage, health, camera connection, delivery, rule outcomes), the same entries as the Alarms page, without request logs
<prefix>/healthyes{"state":"healthy","issues":[{"key","severity","message"}]}
<prefix>/detectoryes{"ready","running","backend","fallback","fallbackReason","recovering","lastError"}
<prefix>/systemyesRecorder name, version, camera counts and recording storage use, updated every minute

A detection payload:

{
  "kind": "entered",
  "id": 4127,
  "camera": { "id": 3, "name": "Front Door", "slug": "front_door" },
  "label": "person",
  "confidence": 0.91,
  "startedAt": 1790000000000,
  "endedAt": null,
  "dwellMs": 0,
  "scope": "zone",
  "zone": "Porch",
  "zones": ["Porch"],
  "identity": { "state": "known", "name": "Alex", "score": 0.82, "method": "face" },
  "face": "known",
  "plate": null,
  "hasSnapshot": true
}

identity.method is appearance, face or plate. face and plate are filled where face and plate recognition is on: face is known, unsure, unknown or unusable, and plate is {"text","state","confidence"}.

kind is entered, resumed, dwell, left, settled or identity (the recorder decided who it was). The same visit sends several messages as it changes; id links them, and /events?event=<id> opens it on the recorder. Times are milliseconds since the epoch. A vehicle is settled a few seconds after it stops; a person or animal keeps sending dwell while standing still and is settled only after five minutes without movement.

Events and alerts are sent only while the broker is connected. They are not queued while the broker is unreachable: History has every event, and retained state is republished as soon as the connection returns.

Snapshots​

Snapshot of each detection publishes the event's picture, the same image as on the Events page, with privacy masks already applied. It is replaced when the recorder cuts a sharper still from the recording a few seconds later.