Reference and Troubleshooting#
Configuration reference, internals, capabilities, limitations and troubleshooting for the Milestone XProtect integration.
Configuration reference#
setup.sh generates config/config.yaml from config/base.yaml and the fragments of the
selected VMS and apps. For this integration, the Milestone instance is in
vms_shim/milestone/vap-config.yaml and the Loitering Detection app in
analytics_app_shim/object_detection/vap-config.yaml. Edit the fragments, not
config/config.yaml, and run ./setup.sh --vms milestone --apps ld again.
Environment variables#
Variable |
Default |
Description |
|---|---|---|
|
— |
AI Bridge host address. |
|
|
AI Bridge GraphQL port (debug mode). Use the proxy port in production. |
|
|
Verify AI Bridge’s TLS certificate. Applies only when |
|
empty |
CA certificate path inside the backend container, when |
|
— |
This VAP host’s name or address, as the XProtect host reaches it. Used to build |
|
|
VAP dashboard port. |
|
|
Seconds in the zone before a person counts as loitering. Keep equal to the recipe’s value. |
vendor_options of the Milestone instance#
Key |
Default |
Description |
|---|---|---|
|
|
AI Bridge GraphQL endpoint. |
|
required |
VAP dashboard URL that Management Client shows as the app’s page. It must open from the XProtect host. |
|
all attached systems |
Register with only this XProtect system. |
|
derived |
App id → GUID map, for example |
|
|
Metadata format for |
|
built in |
Category → ONVIF object class, overriding the defaults ( |
|
|
Minimum seconds between analytics events for the same person on the same camera (for captions, per camera). The Milestone fragment sets |
|
|
Shown in Management Client. |
|
bundled |
Hand-written AI Bridge manifest. Used only by the register endpoint when no configured app maps to a topic; startup registration skips registering instead. |
Loitering Detection app settings#
These keys of the object_detection entry in analytics_apps matter for XProtect:
Key |
Description |
|---|---|
|
|
|
DLSPS pipeline for each device. At least one is required. |
|
Detector label → category. The Milestone instance maps the category to an ONVIF class. |
|
Zone sent to the pipeline when a run starts without one, as normalized |
|
Boxes drawn on the video, with a |
|
Threshold sent to the pipeline (on-video text color). |
|
Send loitering rows as analytics events. |
|
MQTT topic suffix of the loitering rows. Must match the recipe’s |
|
MQTT topic prefix. Must match the recipe’s |
How it works#
Connection and camera discovery#
On startup VAP asks AI Bridge for the XProtect systems attached to it
(about { videoManagementSystems { id } }); this is also its reachability check. It then
lists the cameras with cameras { videoStreams { ... } }.
AI Bridge addresses video by device and stream, so VAP camera ids are
milestone:<deviceId>/<streamId>. AI Bridge returns a ready RTSP address and, when
XProtect knows it, the stream’s resolution. A stream without an RTSP address is
reported as offline.
App registration#
VAP registers each app in analytics_apps as its own IVA app, with every attached
XProtect system (or only vms_id). The app’s type sets its topics:
App |
Topics |
Format |
|---|---|---|
|
|
|
|
|
|
An app whose type has no mapping is skipped and logged as
milestone_unmapped_analytics_app_type. VAP never registers video topics: each would
use one XProtect device license per stream.
To register again without restarting, for example after changing a fragment and running
setup.sh again:
curl -k -X POST https://localhost:3443/v1/vms/milestone/register \
-H 'Content-Type: application/json' -d '{}'
milestone in the path is the instance name in vms_shim/milestone/vap-config.yaml. If VMS_PLUGIN_API_KEY
is set, add -H 'X-API-Key: <key>'.
Restart the XProtect Event Server afterwards (see Events and Alarms, Step 4).
App GUIDs#
AI Bridge identifies an app by GUID. VAP derives it from the VMS instance name and the app id, so restarting VAP updates the same app instead of adding a duplicate, and two VAP deployments with different instance names can share one AI Bridge. To adopt an app registered by something else, pin its GUID:
vendor_options:
app_ids:
dls_vision: "11111111-2222-3333-4444-555555555555"
Pipeline and MQTT topic#
When a run starts, VAP:
Looks up the camera’s RTSP restream address.
Scales the zone to the camera’s resolution and sends it as
analytics-properties.zones. Pipelines that declareroi-propertiesalso get the zone’s bounding rectangle as their region of interest, so detection and loitering use the same area.Sends the threshold as
loitering-watermark-properties.loitering-threshold, to pipelines that declare it.Asks the pipeline to publish on
<metadata_topic_prefix>/milestone:<deviceId>~<streamId>. The/of the camera id becomes~, so the topic has a single level after the prefix.
Metadata and events#
For every pipeline frame with detections or configured zones, VAP posts an ONVIF
metadata frame to <app_id>-metadata. With zones configured, that is every frame, so
the zone stays visible on empty scenes. Without zones, frames with no detections are
skipped. For every loitering row, it posts an
analytics event to <app_id>-events; see Events and Alarms.
Limitations#
The VAP page in Management Client is not camera-aware yet. The camera page works when opened directly (
https://<vap-host>:3443/<deviceId>/<deviceId>/<streamId>), but the address Management Client opens does not route to it.No XProtect sign-in on VAP pages. VAP does not validate the operator token that AI Bridge sends when it runs with
enforce-oauth=true. IfVMS_PLUGIN_API_KEYis set, the pages inside Management Client cannot call VAP.No automatic reconnection. If AI Bridge is unreachable when VAP starts, VAP does not retry; restart the backend once AI Bridge is up.
Pipelines are not resumed. If Loitering Detection restarts, start each camera’s pipeline again.
One Milestone instance, named
milestone…. Pipeline results are routed to the VMS instance whosenamestarts withmilestone, the vendor prefix in the camera id. Keep a singlevendor: milestoneinstance and give it a name that starts withmilestone(the default ismilestone).Event Server restart. XProtect may not raise alarms for a newly created analytics event until the Event Server restarts.
Cameras without a resolution. VAP cannot place the zone on a camera for which XProtect reports no resolution, which is common for simulated cameras.
Unticked metadata topic. AI Bridge accepts and drops metadata for a camera whose metadata topic is not ticked, without an error.
Troubleshooting#
VAP and AI Bridge#
Symptom |
Cause and fix |
|---|---|
|
AI Bridge is unreachable, or the GraphQL port is not exposed (production mode uses the proxy). Check |
|
The HTTP request to AI Bridge failed (connection refused, timeout, TLS error). The logged |
|
AI Bridge rejected a query. Read the logged |
|
AI Bridge runs but is not attached to XProtect. |
|
Set |
|
No app in |
|
Registration failed for the XProtect system named in the log. |
No cameras discovered |
The AI Bridge user cannot see the cameras. |
Duplicate apps in Management Client |
The app GUID changed: the VMS instance |
App or topics not in Management Client |
The Processing Server Admin Plugin is not installed, or Management Client was not restarted. |
Pipeline and overlays#
Symptom |
Cause and fix |
|---|---|
|
AI Bridge has no resolution for the camera, so the zone is not sent and the pipeline uses its default zone. Use a camera that reports its resolution. |
No boxes in Smart Client |
Tick |
Boxes for everyone, but no loitering |
People are outside the zone. Move |
Events and alarms#
Symptom |
Cause and fix |
|---|---|
No |
Check |
|
The event topic is missing in AI Bridge. Restart the backend to register again. |
AI Bridge logs |
Restart the XProtect Event Server. Then check that the alarm definition triggers on Loitering Detection / dls_vision-events, includes the camera in its sources, is enabled, and has a time profile that covers now; and that analytics events are enabled with the AI Bridge host allowed. The event name and class do not matter. |
AI Bridge logs |
The camera is not known to XProtect, for example after it was removed. Discover the cameras again and restart the pipeline. |
Too many alarms |
Raise |
Alarm has no outline |
VAP had not seen the person’s box in the 5 seconds before the event ( |