Why Simulate ONVIF Events?

Event-driven behavior is a core requirement of modern video surveillance systems. VMS platforms rely on ONVIF events to trigger recording, send push notifications, activate alarms, and initiate PTZ presets. Testing this without a real camera that generates motion or alarm events is difficult because:

• Motion events are unpredictable: You cannot guarantee a person will walk past a camera at the exact moment you are testing event recording linkage.
• Hardware I/O is cumbersome: Testing digital input events (door contacts, PIR sensors) requires wiring physical sensors to a test controller.
• Alarm scenarios are hard to reproduce: Tamper, fault, and other alarm conditions may require physically manipulating hardware.

Happytime ONVIF Server solves this by simulating events entirely in software. You can trigger motion detection events, digital input state changes, tamper alarms, and any custom event type — on demand and repeatably — directly from the configuration or via the ONVIF event creation interface.

Understanding the ONVIF Event Model

The ONVIF Core Specification defines a publish-subscribe event system. Understanding this model is essential before configuring event simulation.

Key Concepts

Event Lifecycle

1. Client discovers the device's event service endpoint (via GetCapabilities).
2. Client creates a subscription by calling CreatePullPointSubscription with a filter specifying desired event topics and an initial termination time.
3. Device accepts the subscription and returns a subscription reference with a pull-point address.
4. Client polls for events by calling PullMessages on the pull-point address, with a timeout value.
5. Device responds with any queued events. If no events occurred, the request blocks until the timeout or until an event arrives.
6. Client renews the subscription before it expires by calling Renew.
7. Client cancels the subscription when done by calling Unsubscribe.

ONVIF Event Topics Supported by ONVIF Server

Happytime ONVIF Server can simulate the following standard ONVIF event topics. Each topic corresponds to a real-world scenario that a VMS platform would typically respond to.

Step 1: Enable Event Simulation in the Configuration

The ONVIF Server configuration file (onvif.cfg) includes an <event> block that controls event simulation behavior.

Default Event Configuration

<event>
    <renew_interval>60</renew_interval>
    <simulate_enable>1</simulate_enable>
</event>

Event configuration parameters:

Step 2: Complete Configuration with Event Support

Below is a minimal onvif.cfg with the event block properly configured alongside other essential settings. Place this in the same directory as the ONVIF Server executable.

<?xml version="1.0" encoding="utf-8"?>
<config>
    <server_ip>192.168.1.200</server_ip>
    <http_enable>1</http_enable>
    <http_port>8000</http_port>
    <https_enable>0</https_enable>
    <http_max_users>16</http_max_users>
    <ipv6_enable>1</ipv6_enable>
    <wan_ip></wan_ip>
    <need_auth>1</need_auth>
    <log_enable>1</log_enable>
    <log_level>1</log_level>
    <log_path></log_path>
    <log_mode>loop</log_mode>
    <log_max_size></log_max_size>
    <log_max_index></log_max_index>

    <information>
        <Manufacturer>Happytimesoft</Manufacturer>
        <Model>IPCamera</Model>
        <FirmwareVersion>2.4</FirmwareVersion>
        <SerialNumber>123456</SerialNumber>
        <HardwareId>1.0</HardwareId>
    </information>
    <user>
        <username>admin</username>
        <password>admin</password>
        <userlevel>Administrator</userlevel>
    </user>

    <profile>
        <video_source>
            <width>1280</width>
            <height>720</height>
        </video_source>
        <video_encoder>
            <width>1280</width>
            <height>720</height>
            <encoding>H264</encoding>
        </video_encoder>
    </profile>

    <scope>onvif://www.onvif.org/name/IP-Camera</scope>

    <!-- Event simulation configuration -->
    <event>
        <renew_interval>60</renew_interval>
        <simulate_enable>1</simulate_enable>
    </event>
</config>

Step 3: Launch the ONVIF Server and Verify Event Service

1. Save the onvif.cfg file in the ONVIF Server working directory.
2. Launch the ONVIF Server executable.
3. Check the logs to confirm that the event service has started. Look for log entries indicating the event module is initialized and that simulation is enabled.
4. Verify the event service endpoint: Use an ONVIF client to call GetCapabilities. The response should include an Events section with the XAddr of the event service (typically http://192.168.1.200:8000/onvif/Events).
5. Check available event topics: The client can call GetEventProperties on the event service to retrieve the list of supported event topics. Verify that topics like VideoSource/MotionAlarm and Device/Trigger/DigitalInput are present.

Step 4: Subscribe to Events (Client-Side)

With the ONVIF Server running and event simulation enabled, the next step is to create an event subscription from your ONVIF client. Below is the pull-point subscription workflow.

Create a Pull-Point Subscription

Send a CreatePullPointSubscription request to the event service. You can optionally include a Filter to subscribe to specific event topics. If no filter is specified, all events are delivered.

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope">
    <s:Header>
        <!-- WS-Security UsernameToken (if need_auth=1) -->
    </s:Header>
    <s:Body>
        <CreatePullPointSubscription xmlns="http://www.onvif.org/ver10/events/wsdl">
            <Filter>
                <!-- Subscribe to all topics (empty filter = receive everything) -->
            </Filter>
            <InitialTerminationTime>PT300S</InitialTerminationTime>
        </CreatePullPointSubscription>
    </s:Body>
</s:Envelope>

Key parameters in the subscription request:

• Filter: The event topic filter. Use an empty filter to receive all event types. To filter for motion detection only, specify the topic tns1:VideoSource/MotionAlarm.
• InitialTerminationTime: The subscription lifetime in ISO 8601 duration format. PT300S means 300 seconds (5 minutes). The client must renew before this time elapses. This value should be greater than <renew_interval> (60 seconds default).

The device responds with a SubscriptionReference containing the pull-point address. The client then uses this address to poll for events.

Poll for Events (PullMessages)

Send a PullMessages request to the pull-point address returned in the subscription response:

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope">
    <s:Body>
        <PullMessages xmlns="http://www.onvif.org/ver10/events/wsdl">
            <Timeout>PT10S</Timeout>
            <MessageLimit>10</MessageLimit>
        </PullMessages>
    </s:Body>
</s:Envelope>

PullMessages parameters:

• Timeout: How long the server should hold the request open if no events are available. PT10S = 10 seconds. Use longer timeouts (e.g., PT60S) for long-polling to reduce network overhead.
• MessageLimit: Maximum number of events to return in a single response. Useful for high-frequency event scenarios to avoid large response payloads.

Step 5: Testing Event Scenarios

With the subscription established and the ONVIF Server running with <simulate_enable>1</simulate_enable>, the device will periodically generate simulated events. Below are the key test scenarios to validate your VMS platform's event handling.

Test 1: Motion Detection Event Subscription

1. Create a pull-point subscription with a filter for tns1:VideoSource/MotionAlarm.
2. Call PullMessages with a timeout (e.g., PT30S).
3. Expected result: The server returns a MotionAlarm event notification. The event should include:
   • Topic: tns1:VideoSource/MotionAlarm
   • Source: A reference to the video source that generated the event.
   • Data: A boolean Motion property set to true (motion started) or false (motion stopped).
   • Timestamp: The UTC time when the event was generated.
4. Verify that your VMS platform correctly handles this event: triggers recording, highlights the camera, or fires the configured action rule.

Test 2: Digital Input State Change

1. Subscribe to tns1:Device/Trigger/DigitalInput events.
2. Poll for events.
3. Expected result: The server generates a DigitalInput event with a LogicalState property indicating whether the input is true (active, e.g., door open) or false (inactive, e.g., door closed).
4. Verify that your VMS correctly links this event to associated actions (recording trigger, alarm, relay output).

Test 3: Tamper Alarm

1. Subscribe to tns1:Device/HardwareFailure/Tamper events.
2. Poll for events.
3. Expected result: The server generates a Tamper event. The VMS should treat this as a high-priority security alarm.
4. Verify that the VMS generates the appropriate alarm UI indication, logs the incident, and triggers any configured alarm outputs.

Test 4: Multi-Event Subscription (All Topics)

1. Create a subscription without a topic filter (receive all events).
2. Poll for events over a longer period (e.g., 2 minutes).
3. Expected result: The server delivers a mix of event types: MotionAlarm, DigitalInput changes, and Tamper events.
4. Verify that your VMS correctly dispatches each event type to its respective handler and does not confuse or drop events.

Test 5: Subscription Renewal

1. Create a subscription with InitialTerminationTime set to PT120S (2 minutes).
2. Wait 90 seconds, then call Renew to extend the subscription.
3. Expected result: The subscription remains active. The server continues delivering events to the pull-point.
4. Wait without renewing until the termination time passes, then try PullMessages.
5. Expected result: The server returns a fault indicating the subscription has expired.

Test 6: Unsubscribe

1. Create a subscription and poll for a few events.
2. Call Unsubscribe on the subscription manager.
3. Attempt to call PullMessages again on the old pull-point address.
4. Expected result: The server returns a fault indicating the pull-point no longer exists.

Step 6: Event Notification for NVR Recording Trigger Testing

One of the most common and critical test scenarios is validating that an NVR starts recording when a motion detection event is received. Below is a step-by-step validation workflow:

1. Configure the ONVIF Server with event simulation enabled (<simulate_enable>1</simulate_enable>).
2. On your NVR/VMS: Add the ONVIF Server as a device and create a recording linkage rule: when this camera's motion detection event fires, start recording.
3. Create a pull-point subscription from the NVR to the ONVIF Server's event service for the MotionAlarm topic.
4. Verify recording starts: When PullMessages returns a MotionAlarm event, check that the NVR begins recording this camera's stream within a configurable pre-event buffer window.
5. Verify recording stops: When the subsequent MotionAlarm event has Motion = false, verify that the NVR stops recording after the post-event buffer period.
6. Verify recording timeline: Search the NVR recording timeline. Confirm that event-triggered recordings appear with timestamps matching the motion events.

Troubleshooting

Best Practices

• Use Pull-Point Notification: Pull-point is the recommended ONVIF notification method. It is simpler to implement on the client side, works through firewalls and NAT without additional configuration, and gives the client full control over polling frequency.
• Set Appropriate Timeout Values: Use PullMessages timeout values between PT10S and PT60S. Too short causes excessive polling overhead; too long risks the subscription expiring before the client can renew.
• Always Renew Subscriptions: Implement a subscription renewal thread or timer in your client that calls Renew at intervals less than half the InitialTerminationTime. This provides a safety margin against network delays.
• Filter Events at Subscription Time: If your client only needs specific event types (e.g., only motion detection), use a topic filter in CreatePullPointSubscription. This reduces network traffic and client-side processing compared to receiving all events and filtering locally.
• Test Under Load: Simulate multiple concurrent subscribers pulling events simultaneously. This validates that your VMS event handling scales and does not drop events under load.
• Acknowledge Events Properly: After processing events from PullMessages, the client should not re-fetch the same messages. The ONVIF pull-point model assumes that each PullMessages call consumes the returned events and advances the cursor.
• Handle Empty Responses Gracefully: A PullMessages response may return zero events if the timeout elapsed without any events occurring. The client should treat this as normal and immediately re-poll, rather than logging a warning or disconnecting.
• Use Realistic Event Timing: When the device simulates events (with <simulate_enable>1</simulate_enable>), events are generated at intervals. For integration testing, allow sufficient time for the event to be produced, delivered via pull-point, and processed by your client's event handler.