From 91ee173a9d39409e2d9cb0814c43dde000f6aba7 Mon Sep 17 00:00:00 2001 From: Mike Haldas <51054652+mikehaldas@users.noreply.github.com> Date: Fri, 16 Oct 2026 11:07:19 -0400 Subject: [PATCH] Docs: correct the LPR event payload, keepalive, and firmware differences Align the IPC, NVR, v2.1, and httpPostV2 pages, the LPR application page, and the ipc-v1x examples with posts observed on LPR-IP4 firmware 5.3.1: real V1 plate layout, approach/away direction, count-attribute scales, configurable keepalive interval, and a firmware differences table. --- .../events/httppostv2-data-types.md | 6 +- docs/api-reference/events/ipc-event-format.md | 193 +++++++++++++++--- .../events/ipc-http-post-format-v21.md | 6 + docs/api-reference/events/nvr-event-format.md | 17 +- .../license-plate-recognition-camera-api.mdx | 106 ++++++---- examples/README.md | 9 +- examples/ipc-v1x/keepalive-older-firmware.xml | 15 ++ examples/ipc-v1x/keepalive.xml | 32 +-- examples/ipc-v1x/lpr.xml | 161 ++++++++++----- 9 files changed, 413 insertions(+), 132 deletions(-) create mode 100644 examples/ipc-v1x/keepalive-older-firmware.xml diff --git a/docs/api-reference/events/httppostv2-data-types.md b/docs/api-reference/events/httppostv2-data-types.md index 19a436e..0216961 100644 --- a/docs/api-reference/events/httppostv2-data-types.md +++ b/docs/api-reference/events/httppostv2-data-types.md @@ -41,9 +41,13 @@ IPC IP-AX8D, March 29, 2026, all five data types subscribed: 13:59:08.546 traject stops -- person leaves zone 13:59:19.056 alarmStatus -- perimeterAlarm=false (659 bytes) -14:00:49+ keepalives -- empty body posts every ~90 seconds +14:00:49+ keepalives -- empty body posts about every 90 seconds ``` +:::note Keepalive interval and body +The keepalive interval is configurable in the camera's HTTP POST settings (`keepaliveTimeval`, 30-120 seconds; see [Webhook Configuration](/docs/api-reference/alarm/http-post-webhook-config)). The ~90 seconds above reflects that camera's setting, not a fixed value. The empty keepalive body was seen on this IP-AX8D. Other models and firmware send a body: LPR-IP4 firmware 5.3.1 sends a `config` 1.7 document with `messageType` `keepalive`. Older firmware uses a `` root. See [IPC Format: Keepalive](./ipc-event-format.md#keepalive). +::: + **Total: 104 traject posts, 4 smartData+image posts, 2 alarmStatus posts, 3 keepalives** **Key observations:** diff --git a/docs/api-reference/events/ipc-event-format.md b/docs/api-reference/events/ipc-event-format.md index abc8a7f..ee881cd 100644 --- a/docs/api-reference/events/ipc-event-format.md +++ b/docs/api-reference/events/ipc-event-format.md @@ -12,21 +12,46 @@ IP cameras send alarm data directly to your HTTP server using config version `1. The IPC sends three types of messages: keepalive heartbeats, alarm status changes, and full alarm data with detection details and images. +Several details depend on camera firmware. See [Firmware Differences](#firmware-differences) before you hard-code a field name or value. + ## Keepalive -Periodic heartbeat. Uses a `` root element (not ``). +Periodic heartbeat. **The interval is configurable** in the camera's HTTP POST settings (`keepaliveTimeval`, 30-120 seconds; see [Webhook Configuration](/docs/api-reference/alarm/http-post-webhook-config)). Base any "connection lost" timeout on the value you configured, not on a fixed number. For example, an LPR-IP4 on firmware 5.3.1 with the setting at 90 seconds sent a keepalive every 90 seconds over one persistent connection. 90 seconds is an example setting, not a fixed value. + +The body depends on firmware, so accept every form below. + +### Firmware 5.3.1 + +Observed on LPR-IP4 firmware 5.3.1. A `` document (version `1.7`) with `messageType` `keepalive` and a `deviceInfo` block. There is no XML declaration. + +```xml + +keepalive + + + + + + +``` + +### Older firmware + +Older firmware uses a `` root element (not ``) and includes the serial number. ```xml Device Name 1 - - 192.168.1.192 - 58:5B:69:40:F4:0D + + 192.0.2.100 + 00:00:00:00:00:00 ``` +Some cameras send keepalive posts with an empty body (see the [httpPostV2 Data Types](./httppostv2-data-types.md) timeline). + ## Alarm Status (alarmStatusInfo) Sent when an alarm state changes. Small post (~660 bytes), no images. @@ -48,6 +73,8 @@ Sent when an alarm state changes. Small post (~660 bytes), no images. ``` +`dataTime` follows the camera's date and time display format. The sample above uses `YYYY-MM-DD HH:MM:SS`. LPR-IP4 firmware 5.3.1 sent `MM-DD-YYYY hh:mm:ss AM/PM` (for example `09-21-2026 02:15:30 PM`). Parse both, or use `currentTime` on alarm data posts. License plate alarms use `vehiceAlarm` (firmware spelling). + **Key behavior:** - `true` arrives shortly after first detection - `false` arrives after `alarmHoldTime` expires -- NOT when the person leaves @@ -128,7 +155,7 @@ When both source and target images are subscribed, the post includes a ` PEA - FEATURE_RESULT + FEATURE_RESULT 1563528106584193 @@ -184,7 +211,9 @@ When both source and target images are subscribed, the post includes a `` of ``. The first item contains the overview image, the second contains the plate number, authorization status, and plate crop image. +A plate read arrives as one `FEATURE_RESULT` post. There is no `sourceDataInfo` block. `listInfo` has two items: -| Field | Description | -|-------|-------------| -| `plateNumber` | Detected plate text | -| `vehicleListType` | Plate database status (see table below) | -| `PlateConfidence` | Detection confidence score | -| `plateColor` | Plate color | -| `vehicleDirect` | Vehicle direction (`approach` or `leave`) | -| `targetImageData/targetBase64Data` | Base64 JPEG plate crop image | +- **Item 0** is the overview image (`image` 0, empty `plateNumber`, `width`/`height` 0, empty `targetType`). +- **Item 1** is the plate read and the plate crop (`image` 1, `targetType` `car`). + +Shape observed on LPR-IP4 firmware 5.3.1 (HTTP POST V1 layout). Device identity, the timestamp, image data, and vehicle attribute values are placeholders. `IB36NL` is a test plate. The full file is [examples/ipc-v1x/lpr.xml](https://github.com/mikehaldas/IP-Camera-API/blob/main/examples/ipc-v1x/lpr.xml). + +```xml + + + +VEHICE +FEATURE_RESULT +1785000000123456 + + + +1 +1 + + + 0 + + + + 0 + + 0 + 0 + 770384 + + + + + 1 + 1 + + 6 + approach + whiteList + 176 + 100 + 2688 + 1776 + 75592072 + 82142072 + 75592635 + 82142635 + + + + + + + + + + white + saloon car + Toyota + Toyota_Camry + + + 1242 + 586446 + + + 0 + car + 176 + 100 + 19520 + + + + + +``` + +#### LPR Fields + +"Confirmed on" names the firmware where the field was seen in a captured post. + +| Field | Description | Confirmed on | +|-------|-------------|--------------| +| `smartType` | `VEHICE` or `VEHICLE`, depending on firmware | 5.1.1, 5.3.1 | +| `currentTime` | Event time from the camera clock, Unix microseconds (16 digits). Check the camera clock before comparing it with arrival time. | 5.3.1 | +| `plateCount` | Number of plates in the post | 5.3.1 | +| `listInfo/item[0]/targetImageData` | Overview JPEG (base64). About 760 KB of base64 text in an LPR-IP4 post. | 5.1.1, 5.3.1 | +| `plateNumber` | Plate text (CDATA). Empty on item 0. | 5.1.1, 5.3.1 | +| `plateCharCount` | Number of characters in the plate text | 5.3.1 | +| `vehicleDirect` | `approach` or `away`. Earlier versions of this page listed `leave`, which has not been seen in a captured post. Treat `leave` like `away` if it appears. | 5.1.1 (`approach`), 5.3.1 (both) | +| `vehicleListType` | Plate list the plate matched (table below). Not sent at all on 5.1.x. | 5.3.1 | +| `PlateConfidence` | Value is in the `count` attribute, on a 0-10000 scale (`count="9900"` = 99%). The element has no text. | 5.3.1 | +| `plateColor` | Numeric code in the `count` attribute (for example `count="3"`), not a color name. The code-to-color mapping is not documented. | 5.3.1 | +| `plateColorRate`, `plateStyle`, `vehiceColor`, `plateAngleH`, `plateAngleV` | Numeric values in the `count` attribute. Meaning not documented. | 5.3.1 | +| `leftTop`, `rightTop`, `leftBottom`, `rightBottom` | Plate corner points, normalized 0-10000. There is no `rect` on IPC plate posts. | 5.3.1 | +| `PlateWidth`, `PlateHeight` | Plate crop size in pixels | 5.3.1 | +| `SourceImageWidth`, `SourceImageHeight` | Full-frame size in pixels | 5.3.1 | +| `province` | Plate region text. Empty in U.S. reads. | 5.3.1 | +| `carAttr/color`, `carAttr/type`, `carAttr/brand`, `carAttr/model` | Vehicle color, type (for example `saloon car`), brand, and model (`Brand_Model` form) | 5.3.1 | +| `carRect` | Vehicle box: `x`, `y`, `width`, `height`. `y` was an empty element. Units not confirmed. | 5.3.1 | +| `listInfo/item[1]/targetImageData` | Plate crop JPEG (base64), `targetType` `car`. About 19 KB of base64 text. | 5.1.1, 5.3.1 | + +The post carries no plate group number. Map list names yourself. **Plate database status (`vehicleListType`):** -| Value | Meaning | -|-------|---------| -| `whiteList` | Plate is on the allow list (within valid date range) | -| `blackList` | Plate is on the block list (within valid date range) | -| `temporaryList` | Plate is on the temporary list (within valid date range) | -| *(field absent)* | Plate is not in the database, or any plate with an expired date range | +| Value | Meaning | Confirmed on | +|-------|---------|--------------| +| `whiteList` | Plate is on the allow list | 5.3.1 | +| `blackList` | Plate is on the block list | 5.3.1 | +| `temporaryList` | Plate is on the temporary list | Not yet confirmed in a captured post | +| *(field absent)* | Plate is on no list. On 5.1.x the field is always absent, even for listed plates. | 5.1.1, 5.3.1 | + +Not yet confirmed: plates whose valid date range has expired (allow, block, or temporary) are expected to have `vehicleListType` omitted, so the camera checks date ranges for every list type. Test this on your firmware before you rely on it. + +#### Image data + +Decode the actual base64 text, and don't size buffers from `targetBase64Length`. On LPR-IP4 firmware 5.3.1 the declared length didn't match the text: the overview declared 770,384 characters and carried about 760,500, and the plate crop declared 19,520 and carried 19,270. + +## Firmware Differences + +Observed on LPR-IP4 cameras. Behaviour on other models may differ. + +| Behaviour | 5.1.1.0 (build 52592) | 5.1.1.0 (build 66800) | 5.3.1 | +|-----------|-----------------------|-----------------------|-------| +| Public API version (`GetDeviceInfo`) | 1.7 | 1.7 | 2.1.0 | +| Plate post layout | V1, config `1.7` | V1, config `1.7` | V1, config `1.7` (also when a V2 row is saved; see [IPC Format (v2.1)](./ipc-http-post-format-v21.md)) | +| `smartType` | `VEHICE` | `VEHICLE` | `VEHICE` | +| `vehicleListType` | Never sent | Never sent | Sent for listed plates (`whiteList`, `blackList`); absent for unlisted plates | +| `vehicleDirect` | `approach` seen on 5.1.1 (build not recorded) | `approach` seen on 5.1.1 (build not recorded) | `approach` and `away` seen | +| `carAttr` vehicle attributes | Not confirmed | Not confirmed | Sent | +| Keepalive body | Not confirmed | Not confirmed | `config` 1.7 + `messageType` `keepalive` + `deviceInfo` | +| `type` attribute names | Not confirmed | Not confirmed | `openAlarmObj`, `subscribeRelationV1` | -The camera validates date ranges internally for **all** list types — not just temporary plates. Any plate with an expired end date (allow, block, or temporary) will have `vehicleListType` omitted entirely. +Accept both `VEHICE` and `VEHICLE`. The spelling doesn't follow firmware age: 5.3.1 is newer than build 66800 and still sends `VEHICE`. :::tip Application Guides For step-by-step setup of IPC webhook events, see [Webhook Event Notification API](/docs/applications/webhook-event-notification-api). For traject-based real-time tracking from IPC, see [Real-Time Object Tracking](/docs/applications/real-time-object-tracking-api). For LPR plate database management, see [LPR Configuration](/docs/api-reference/smart-detection/license-plate-recognition-config). diff --git a/docs/api-reference/events/ipc-http-post-format-v21.md b/docs/api-reference/events/ipc-http-post-format-v21.md index 85c2576..6c24070 100644 --- a/docs/api-reference/events/ipc-http-post-format-v21.md +++ b/docs/api-reference/events/ipc-http-post-format-v21.md @@ -11,3 +11,9 @@ sidebar_position: 9 Verification of direct camera posts on v2.1 firmware is in progress. Until this section is complete, log the raw post body and check for `messageType`, the `smartType` spelling, and where the plate list result appears. Cameras on v2.1 firmware report `httpPostVersion` `2.1.0`. On a v2.1 LPR camera running 5.3.1 firmware, the HTTP POST V2 event list in the web interface is `ALL`, `MOTION`, `SENSOR`, `AVD`, and `VEHICLE`, and the data-type element is named `subDataType`. See [httpPostV2 Data Types](./httppostv2-data-types.md) and [Webhook Configuration](/docs/api-reference/alarm/http-post-webhook-config). + +## V2 rows and the V1 sender + +On LPR-IP4 firmware 5.3.1, saving a V2 (`httpPostV2`) row in the web interface also turned on the legacy V1 `httpPost` sender, aimed at the same host, port, and path. The page has no separate V1 switch. In testing with a V2 row saved for `VEHICLE`, every post received used the V1 layout: config version `1.7`, no `messageType` on plate posts, and `smartType` `VEHICE`. No V2-format posts were received. Plate posts from this firmware therefore follow the [IPC Event Format (v1.x)](./ipc-event-format.md#lpr-event-vehice--vehicle), including `vehicleListType` for listed plates. + +No V2.1-format post body has been captured yet, so this page does not document one. diff --git a/docs/api-reference/events/nvr-event-format.md b/docs/api-reference/events/nvr-event-format.md index a7b0632..f6180eb 100644 --- a/docs/api-reference/events/nvr-event-format.md +++ b/docs/api-reference/events/nvr-event-format.md @@ -8,7 +8,7 @@ sidebar_position: 4 # NVR Event Format (v2.0) -NVRs send alarm data using config version `2.0.0` with `Content-Type: application/soap+xml; charset=utf-8` and `Connection: close`. The NVR sends three message types identified by a `` field (IPC posts do not have this field). +NVRs send alarm data using config version `2.0.0` with `Content-Type: application/soap+xml; charset=utf-8` and `Connection: close`. The NVR sends three message types identified by a `` field. IPC alarm posts do not have this field, but IPC keepalives on firmware 5.3.1 do (see [IPC Format](./ipc-event-format.md#keepalive)). > Tested: NVR v2.0 (firmware 1.4.13), February-March 2026 @@ -19,19 +19,19 @@ NVRs send alarm data using config version `2.0.0` with `Content-Type: applicatio | **Config version** | `1.0` or `1.7` | `2.0.0` | | **Content-Type** | `application/xml; charset=utf-8` | `application/soap+xml; charset=utf-8` | | **Connection** | `keep-alive` | `close` | -| **messageType field** | Not present | `keepalive`, `alarmStatus`, `alarmData` | +| **messageType field** | Not present on alarm posts. Present (`keepalive`) on keepalives from firmware 5.3.1 | `keepalive`, `alarmStatus`, `alarmData` | | **deviceInfo block** | Varies | Always present with `deviceName`, `ip`, `mac`, `channelId` | | **smartType values** | Codes: `PEA`, `VFD`, `VEHICE`, `VSD` | Spelled out: `regionIntrusion`, `lineCrossing`, `videoFaceDetect`, `videoMetadata`, `vehicle` | | **Timestamp** | `dataTime` string or `currentTime` (10-16 digits) | `currentTime` Unix **microseconds** (16 digits) | | **Event data** | `perimeter/perInfo` or `listInfo/item` | `eventInfo/item` with `eventId`, `targetId`, `boundary`, `pointGroup`, `rect` | | **Image data** | `sourceDataInfo` + `listInfo/targetImageData` | `sourceDataInfo` + `targetListInfo/targetImageData` | -| **targetType** | Numeric: 1=person, 2=car, 4=bike | String: `person`, `car`, `motor` | +| **targetType** | Numeric (1=person, 2=car, 4=bike) in older samples. String (`car`) on LPR-IP4 firmware 5.3.1 plate posts | String: `person`, `car`, `motor` | | **POST line** | `POST /API HTTP/1.1` (path only) | `POST http://192.168.0.56:5002/API HTTP/1.1` (full URL) | | **Type annotations** | Present (`type="uint32"`) | Not present | ## Keepalive -Heartbeat sent approximately every 10 seconds. +Periodic heartbeat. The interval is most likely set by the heartbeat or keepalive setting in the NVR's HTTP POST or alarm server configuration, so don't assume a fixed number. The NVR interval has not been measured. An earlier version of this page said "approximately every 10 seconds"; that figure is unconfirmed. Base any "connection lost" timeout on the interval you configured. ```xml @@ -356,7 +356,11 @@ Full-frame object detection. NVR equivalent of IPC `VSD`. ### vehicle (LPR) -License plate recognition. NVR equivalent of IPC `VEHICE`. Uses a completely different XML structure -- `licensePlateListInfo` instead of `eventInfo` + `targetListInfo`. +License plate recognition. NVR equivalent of IPC `VEHICE` / `VEHICLE`. Uses a completely different XML structure -- `licensePlateListInfo` instead of `eventInfo` + `targetListInfo`. + +:::caution Not yet re-verified +This section has not been confirmed against a current captured NVR plate post. Treat the field names, the 20-digit `currentTime`, and whether `licensePlateMatchInfo/groupName` appears as unconfirmed. Log the raw post body from your NVR before you rely on them. +::: ```xml @@ -422,9 +426,10 @@ License plate recognition. NVR equivalent of IPC `VEHICE`. Uses a completely dif | `carAttribute/brand` | Vehicle brand | `GMC` | | `carAttribute/model` | Vehicle model | `GMC_SAVANA` | | `targetImageData` | Cropped plate image (128x64 JPEG) | base64 | +| `licensePlateMatchInfo/groupName` | Plate database group name when the plate matches a group. Not in the sample above, and not yet confirmed in a captured post. | `Whitelist` | **Notable observations:** -- Vehicle attribute recognition identifies type, color, brand, and model -- far richer than IPC v1.x format +- Vehicle attribute recognition identifies type, color, brand, and model. IPC posts on LPR-IP4 firmware 5.3.1 carry the same kind of data in `carAttr` (see [IPC Format](./ipc-event-format.md#lpr-event-vehice--vehicle)) - `currentTime` anomaly: the 20-digit timestamp appears to be a firmware bug - `sourceDataInfo` has zero dimensions but the post is ~628 KB - No `alarmStatus` observed for this detection type diff --git a/docs/applications/license-plate-recognition-camera-api.mdx b/docs/applications/license-plate-recognition-camera-api.mdx index 867fc32..9040d4d 100644 --- a/docs/applications/license-plate-recognition-camera-api.mdx +++ b/docs/applications/license-plate-recognition-camera-api.mdx @@ -16,7 +16,7 @@ import TabItem from '@theme/TabItem'; # License Plate Recognition Camera API (LPR/ALPR) -Viewtron AI security cameras include built-in license plate recognition (LPR/ALPR) that runs entirely on the camera hardware — no cloud service, external software, or third-party LPR engine required. When a vehicle passes through the camera's detection zone, the camera reads the license plate and sends an HTTP POST webhook to your server with the plate number, a cropped plate image, and (on NVR v2.0) detailed vehicle attributes including type, color, brand, and model. +Viewtron AI security cameras include built-in license plate recognition (LPR/ALPR) that runs entirely on the camera hardware — no cloud service, external software, or third-party LPR engine required. When a vehicle passes through the camera's detection zone, the camera reads the license plate and sends an HTTP POST webhook to your server with the plate number, a cropped plate image, an overview image, and, depending on firmware, vehicle attributes including type, color, brand, and model. LPR-IP4 firmware 5.3.1 sends vehicle attributes in the camera's own post (`carAttr`), and the NVR v2.0 format carries them as `carAttribute`. The API also supports managing an on-camera plate database with whitelist and blacklist entries, enabling automated gate access control without any middleware. Plates can be added with date ranges and owner information. The camera includes a Wiegand output for direct integration with gate controllers and access control panels. All Viewtron IP cameras and NVRs are NDAA compliant. @@ -42,23 +42,27 @@ The API also supports managing an on-camera plate database with whitelist and bl ## Event Data -Each LPR webhook POST contains: +Each LPR webhook POST contains the fields below. Field names differ between a camera posting directly (IPC v1.x) and an NVR (v2.0), and some fields depend on firmware. See [Firmware Differences](/docs/api-reference/events/ipc-event-format#firmware-differences). | Field | Description | |-------|-------------| -| `smartType` | `VEHICE` (IPC) or `vehicle` (NVR) | +| `smartType` | IPC: `VEHICE` or `VEHICLE`, depending on firmware. NVR: `vehicle` | | `plateNumber` / `licensePlateNumber` | Detected plate text (e.g., `JP116D`) | -| `vehicleListType` | IPC: `whiteList`, `blackList`, `temporaryList`, or absent if not in database | -| `licensePlateMatchInfo/groupName` | NVR: user-defined group name (e.g., "Whitelist", "Residents"), or absent if not in database | -| `licensePlateAttribute/color` | Plate color (NVR v2.0) | -| `carAttribute/carType` | Vehicle type: `sedan`, `suv`, `mpv`, `truck`, etc. (NVR v2.0) | -| `carAttribute/color` | Vehicle color (NVR v2.0) | -| `carAttribute/brand` | Vehicle brand: `GMC`, `Ford`, `Toyota`, etc. (NVR v2.0) | -| `carAttribute/model` | Vehicle model: `GMC_SAVANA`, etc. (NVR v2.0) | -| `rect` | Plate bounding box coordinates (x1, y1, x2, y2) | +| `vehicleDirect` | IPC: `approach` or `away` | +| `PlateConfidence` | IPC: confidence in the `count` attribute, 0-10000 (`count="9900"` = 99%) | +| `vehicleListType` | IPC: `whiteList` or `blackList` on firmware 5.3.1, absent if the plate is on no list. Never sent on firmware 5.1.x. `temporaryList` is documented but not yet confirmed in a captured post. | +| `licensePlateMatchInfo/groupName` | NVR: user-defined group name (e.g., "Whitelist", "Residents"), or absent if not in database. Not yet confirmed in a captured post. | +| `plateColor` / `licensePlateAttribute/color` | Plate color. IPC: a numeric code in the `count` attribute. NVR: a color name | +| `carAttr/type` / `carAttribute/carType` | Vehicle type: `saloon car` (IPC 5.3.1), or `sedan`, `suv`, `mpv`, `truck`, etc. (NVR) | +| `carAttr/color` / `carAttribute/color` | Vehicle color | +| `carAttr/brand` / `carAttribute/brand` | Vehicle brand: `GMC`, `Ford`, `Toyota`, etc. | +| `carAttr/model` / `carAttribute/model` | Vehicle model: `GMC_SAVANA`, etc. | +| `rect` / corner points | NVR: plate bounding box (x1, y1, x2, y2). IPC: `leftTop`, `rightTop`, `leftBottom`, `rightBottom`, normalized 0-10000 | | `targetBase64Data` | Cropped plate JPEG image (base64 encoded, ~10-20 KB) | -| `sourceBase64Data` | Full-frame overview JPEG image (base64 encoded, ~400-500 KB) | -| `currentTime` | Detection timestamp | +| Overview image | Full-frame JPEG, base64 encoded. IPC: `listInfo` item 0 `targetBase64Data` (about 760 KB of base64 text in an LPR-IP4 firmware 5.3.1 post; there is no `sourceDataInfo`). NVR: `sourceBase64Data` | +| `currentTime` | Detection timestamp, Unix microseconds from the device clock | + +Decode the base64 text itself. The declared `targetBase64Length` did not match the actual text on LPR-IP4 firmware 5.3.1. ## Parsing LPR Events @@ -148,6 +152,10 @@ See the [Node.js SDK reference](/docs/category/nodejs-sdk-reference) for all eve The NVR v2.0 format uses `licensePlateListInfo` with detailed vehicle attributes and `licensePlateMatchInfo` for plate database group matching: +:::caution Not yet re-verified +This NVR sample has not been confirmed against a current captured post. In particular, whether `licensePlateMatchInfo/groupName` appears, and its exact name, is unconfirmed. Log the raw post body from your NVR before you rely on these fields. +::: + ```xml @@ -198,38 +206,60 @@ See the [NVR Event Format](/docs/api-reference/events/nvr-event-format) referenc -The IPC v1.x format uses `listInfo` with the plate number and whitelist/blacklist status: +The IPC v1.x format puts everything in `listInfo`. There is no `sourceDataInfo` block. Item 0 is the overview image. Item 1 holds the plate number, direction, list status, confidence, vehicle attributes, and the plate crop. This shape was observed on LPR-IP4 firmware 5.3.1. Placeholder device values; `IB36NL` is a test plate: ```xml - + - VEHICE - 1732045234584193 - - 418200 - ... (base64 JPEG overview) ... - - - - - 52480 - ... (base64 JPEG overview crop) ... - - - - - whiteList - - 8640 - ... (base64 JPEG plate crop) ... - - - +VEHICE +FEATURE_RESULT +1785000000123456 +1 + + + 0 + + + + 0 + 0 + 770384 + + + + + 1 + + approach + whiteList + 75592072 + 82142072 + 75592635 + 82142635 + + + + white + saloon car + Toyota + Toyota_Camry + + + car + 176 + 100 + 19520 + + + + ``` +This sample is trimmed. The full post is in [examples/ipc-v1x/lpr.xml](https://github.com/mikehaldas/IP-Camera-API/blob/main/examples/ipc-v1x/lpr.xml). + :::note -The IPC smartType uses `VEHICE` (note the typo in the firmware — not `VEHICLE`). The NVR uses `vehicle`. +The IPC `smartType` spelling depends on firmware: `VEHICE` (the firmware's own spelling) on 5.1.1.0 build 52592 and on 5.3.1, and `VEHICLE` on 5.1.1.0 build 66800. Accept both. The NVR uses `vehicle`. On firmware 5.1.x, `vehicleListType` is never sent, even for plates on the camera's list. ::: See the [IPC Event Format](/docs/api-reference/events/ipc-event-format) reference for the complete v1.x XML structure. diff --git a/examples/README.md b/examples/README.md index 3eca08e..7113834 100644 --- a/examples/README.md +++ b/examples/README.md @@ -26,14 +26,15 @@ Posts sent directly by a Viewtron IP camera (not through an NVR). | File | smartType | Description | |------|-----------|-------------| -| [lpr.xml](ipc-v1x/lpr.xml) | `VEHICE` | License plate detected with whitelist/blacklist | +| [lpr.xml](ipc-v1x/lpr.xml) | `VEHICE` / `VEHICLE` | License plate read with direction, list status (`whiteList`/`blackList` on firmware 5.3.1), confidence, vehicle attributes, overview and plate crop (shape observed on LPR-IP4 firmware 5.3.1) | | [face-detection.xml](ipc-v1x/face-detection.xml) | `VFD` | Face detected | | [perimeter-intrusion.xml](ipc-v1x/perimeter-intrusion.xml) | `PEA` | Person/vehicle enters an intrusion zone | | [line-crossing.xml](ipc-v1x/line-crossing.xml) | `PEA` | Person/vehicle crosses a tripwire line | | [zone-entry.xml](ipc-v1x/zone-entry.xml) | `AOIENTRY` | Object enters a defined zone | | [zone-exit.xml](ipc-v1x/zone-exit.xml) | `AOILEAVE` | Object exits a defined zone | | [video-metadata.xml](ipc-v1x/video-metadata.xml) | `VSD` | Continuous full-frame object detection | -| [keepalive.xml](ipc-v1x/keepalive.xml) | — | Periodic heartbeat | +| [keepalive.xml](ipc-v1x/keepalive.xml) | — | Periodic heartbeat, firmware 5.3.1 format (`config` 1.7 + `messageType` `keepalive`). Interval is set in the camera's HTTP POST settings | +| [keepalive-older-firmware.xml](ipc-v1x/keepalive-older-firmware.xml) | — | Periodic heartbeat, older-firmware format (`` root) | | [alarm-status.xml](ipc-v1x/alarm-status.xml) | — | Alarm start/stop notification | ## Key Differences Between Formats @@ -41,10 +42,10 @@ Posts sent directly by a Viewtron IP camera (not through an NVR). | Feature | IPC v1.x | NVR v2.0 | |---------|----------|----------| | Config version | `1.0` or `1.7` | `2.0.0` | -| messageType field | Not present | `keepalive`, `alarmStatus`, `alarmData` | +| messageType field | Not present on alarm posts; `keepalive` on firmware 5.3.1 keepalives | `keepalive`, `alarmStatus`, `alarmData` | | smartType naming | Codes: `PEA`, `VFD`, `VEHICE` | Descriptive: `regionIntrusion`, `videoFaceDetect`, `vehicle` | | Timestamps | Unix seconds/ms or formatted date | Unix **microseconds** (16 digits, divide by 1,000,000) | -| Target type | Numeric: `1`=person, `2`=car, `4`=bike | String: `person`, `car` | +| Target type | Numeric: `1`=person, `2`=car, `4`=bike (string `car` on LPR-IP4 firmware 5.3.1 plate posts) | String: `person`, `car` | | Device info fields | `ipAddress`, `macAddress` | `ip`, `mac`, `channelId` | | Event data | `perimeter/perInfo`, `tripwire/tripInfo`, `listInfo` | `eventInfo`, `targetListInfo`, `licensePlateListInfo`, `faceListInfo` | | Type annotations | Present (`type="uint32"`) | Not present | diff --git a/examples/ipc-v1x/keepalive-older-firmware.xml b/examples/ipc-v1x/keepalive-older-firmware.xml new file mode 100644 index 0000000..98e6835 --- /dev/null +++ b/examples/ipc-v1x/keepalive-older-firmware.xml @@ -0,0 +1,15 @@ + + + + Device Name + 1 + + 192.0.2.100 + 00:00:00:00:00:00 + diff --git a/examples/ipc-v1x/keepalive.xml b/examples/ipc-v1x/keepalive.xml index 35252d0..6496bdd 100644 --- a/examples/ipc-v1x/keepalive.xml +++ b/examples/ipc-v1x/keepalive.xml @@ -1,12 +1,20 @@ - - - - Device Name - 1 - - 192.168.1.192 - 58:5b:69:5a:84:bb - + + +keepalive + + + + + + diff --git a/examples/ipc-v1x/lpr.xml b/examples/ipc-v1x/lpr.xml index 60e1d78..8c6b8ee 100644 --- a/examples/ipc-v1x/lpr.xml +++ b/examples/ipc-v1x/lpr.xml @@ -1,53 +1,120 @@ - + + targetBase64Length is the length the camera declares. It did not match + the actual base64 text on 5.3.1, so decode the text itself. --> - VEHICE - FEATURE_RESULT - 1732045234584193 - - VEHICE,VFD_MATCH,PEA,VFD,VSD,AOIENTRY,AOILEAVE,PASSLINECOUNT,TRAFFIC - 1,2,4 - - - - - 0 - 2 - 1920 - 1080 - 161438 - - - - - - whiteList - - 0 - 2 - 150 - 50 - 3200 - - - - - - 0 - 1920 - 1080 - 161438 - - +MOTIONSENSORPEAAVDOSCVFDVFD_MATCHVEHICEAOIENTRYAOILEAVEPASSLINECOUNTTRAFFICFIRETEMPERATUREVSDPVDLOITERASDSMDCROWDGATHERINGALARMFEATURE_RESULTSMART_NONESMART_STARTSMART_STOPSMART_PROCEDUREpersoncarmotor +VEHICE +FEATURE_RESULT +1785000000123456 + + + +1 +1 + + + 0 + 0 + + 0 + 0 + 0 + 2688 + 1776 + 00 + 00 + 00 + 00 + + + + + + + + + 0 + + 0 + 0 + 770384 + + + + + 1 + 1 + + 6 + approach + whiteList + 176 + 100 + 2688 + 1776 + 75592072 + 82142072 + 75592635 + 82142635 + + + + + + + + + + white + saloon car + Toyota + Toyota_Camry + + + 1242 + + 586 + 446 + + + 0 + car + 176 + 100 + 19520 + + + +