ONVIF Generic Events
Custom ONVIF Events
Introduction
You can create custom rules based on ONVIF camera-generated events inside Macula Console Events & Actions. To do so, you need:
ONVIF compatible camera connected via ONVIF driver to the Macula,
Understanding of the camera events,
Basic knowledge of the ONVIF standard XML responses generated by your cameras.
Although ONVIF is a set of rules that standardizes video monitoring hardware and software - the range of available options is extensive, and different cameras may have very different capabilities. In the context of this manual, we will focus on integrating this wide range of varying camera capabilities into the Macula and fully utilize your camera potential.
The scheme below represents the cameras sending Event data to the Macula server.
This event data is sent via RTSP and HTTP in XML format and adheres to the ONVIF-defined standard. Both streams may represent the same or different events, and you must invest your attention to get out the most from your setup.
User Defined Events
To begin with the ONVIF-based custom event creation, you must add a camera via the Generic ONVIF driver. You can find how to add your devices in a corresponding part of this manual.
After adding a device, find the Channels inside Macula Console -> Configuration sub-section.
Find the corresponding channel and open it in a pop-up window by double-clicking on its name or selecting it and pressing the Edit button on the top of the channel list subsection.
Find the User defined events in the pop-up window at the bottom of the right subsection.
You will see the empty subsection with three buttons on the top. +New drop-down button, grayed-out Edit button, and Notification messages button. You can create a New generic event by clicking the +New or Notification Messages buttons. Both options will bring the new Messages pop-up window with the list of received notification messages in XML format. Received data represented in a table-like form with columns:
Time - Received notification server timestamp (MM/DD/YYYY HH:MM:SS)
Source:
Notification service - data stream received via HTTP
MetaStream - data stream received via RTSP
Message - Received data in XML format. The Message column is updated in real-time as the data is received.
Matches - if you have already created a generic event filter, you will see an indication for the events with exact matches for that existing filter.
Locate the event you want to use as the prototype for the filter, click on it, and then click on the +New button on the bottom-left part of the pop-up window. You may find the same event inside both - Notification service and MetaStream data. For such cases, our recommendation is to use MetaStream. This stream is sent together with the video stream, so it is easier to notice any instability the third-party factors may cause.
This will bring the Generic event pop-up window.
You will see the following fields inside the Details tab:
Type - Event type (in this case - GenericEvent), non-editable.
Message source - Notification service/MetaStream, non-editable
Title - the only field that the user should fill in. The display name of the created event. Editable.
Id - Event identifier. The field will be completed automatically after the event is saved. You can identify the event inside log files by this ID.
Enable checkbox - enable event processing. Uncheck it to stop processing the event.
The only field you should fill inside the Details subsection is the Title field - add a meaningful name that will allow you to recognize this event inside the Events & Actions Configurator.
VCA event mapping
The next step is to map data. Inside the Item subsection, locate the Mapping; this will bring the Mapping options. You will see three subsections:
Notifications message - the most-right subsection of the Mapping section. Provide a detailed view of the selected message.
Items - represents the mapped portions of the Notification message. You may create multiple items - only exact matches will be processed (similar to the && conditional operation).
Condition - the left subsection of the Mapping section. This subsection allows adjustments to the Items created in the Items subsection. You will find the following interface elements:
Name field - You can edit this to make the Items subsection more readable. Provide a meaningful name for the Condition Item.
Select node button - which will bring a pop-up screen with the notification message. Use it if you want to change the part of the message your item is based on.
Evaluate button - Evaluate if the created Item matches the current condition. Use it if you manually adjusted XPath or Text fields to avoid errors. Values: "true" - if the Item condition matches the Notification message; "false" - if XPath value or Text does not have an exact match.
XPath input field - represents the path to the Item conditional value in the context of the Notification message tree; may contain variables.
Text input field - represents the value that must match to meet the event's trigger condition.
Regular Expression checkbox - mark it if REGEX is used for conditioning.
Case sensitive checkbox - by default, condition matching is registry case-independent. Mark this checkbox only if you need registry case-dependent conditioning.
Save/Apply changes button - Save changes before switching to the next Item or confirming event with the OK button at the bottom-right corner of the Mappings subsection.
Cancel button - Cancel current changes made to the selected Item.
Blurry mainstream Custom VCA Event scenario
At first glance, Generic events may seem complicated, but they provide an unprecedented level of elasticity if needed or allow the creation of simple event triggers from otherwise incompatible devices. The example below will create a generic event based on the ONVIF camera's mainstream blurriness.
Ensure the camera is connected via the ONVIF driver and the Camera analytics is up and running.
Go to Configuration -> Channels -> 'Your Channel' and double-click on it.
At the bottom of the right section, find User defined events, select it, then on the top of the right subsection, click the +New button -> New generic event.
Locate relevant event. In the example case, this will be an event sent via Metastream containing information on the image quality. Click on the +New button at the Messages window's bottom-left side.
In the provided example the event is named "HikiEntrance_tooBlurry." Click on the Mapping. You will see already created Item based on the event topic.
For Example, the camera has both mainstream and substream, and the mainstream is found under the Message/Source/VideoSource_1. To evaluate only mainstream, you need to create one more Item.
At the Notification Message subsection, locate Message/Source and click on the node; then, in the Items subsection (the one in the middle), click the +New condition button. You can change the Item name to something more meaningful, like in the provided example, "MainStream," and confirm the adjustment with the Create button..
Now, the system knows "where to look." All that's left is to tell the system what it must look for. Create one more Item from the Message/Data node. In the provided example, you need to evaluate if the image is blurry, so you are looking for the value - "true." Select the Data node, Click the +New condition button, rename the Item as "TooBlurry," and confirm it with the Create button.
Confirm Generic Event with the OK button, then confirm it again with the Apply button under the User defined events subsection.
From now on, you are ready to build Actions based on the blurriness of the camera mainstream. To do so:
Go to the Macula Console -> Events & Actions -> Events
At the top-left part of the Events subsection, find the +New event button and click it.
Find the VCA event (Stands for Video Camera Analytics) from the pop-up window and confirm with the OK button.
Add the Event Title, which will be displayed inside the configurator. Name it "blurry entrance cam."
Click the Change button on the right side from the Source field and select the camera you used to create that generic event.
To bring a custom event to its full potential, you must add the VCA rule. Click the Change button and find your generic event name in the pop-up window. It will likely be at the bottom of the list. Confirm your selection with the OK button, then click the Apply and the OK buttons to save your event.
Go to the Rules subsection and open the configurator. The goal is to log this event to the server, generate an alert, and pop up the channel inside the Macula Monitor.
That's it. All the Actions are now available for your event. This way, very complicated scenarios might be created, starting with basic notifications for the simple analytics event and up to very specific conditioning for the VCA value for the particular case.
Import/export custom events
Once the event is mapped, it is possible to export it. To do so, go to:
Configuration -> Channels -> Your channel -> User defined events
Select your Event and click the Export button at the top of the window.
To import event, go to:
Configuration -> Channels -> Your channel -> User defined events
Select your Event and click the Import button at the top of the window.
find saved json file and confirm it with the Ok button.
Although it is possible to import any custom event to any ONVIF compatible camera, it will be working only with the cameras that sends exactly the same notification messages.
Last updated