Skip to content

Event Handling

The device service can retrieve events one of the following ways:

  • PullPoint - "Pull" using the CreatePullPointSubscription and PullMessage operations
  • BaseNotification - "Push" using Notify, Subscribe and Renew operations from WSBaseNotification

The specification can refer to ONVIF specification and oasis-open specification

Define the Device Resources for Event Handling

Define a CameraEvent Resource for Device Service to Publish the Event

Before receiving the event data from the camera, we must define a device resource for the event. 

- name: "CameraEvent"
 isHidden: true
 description: "This resource is used to send the async event reading to north bound"
 attributes:
   service: "EdgeX"
   getFunction: "CameraEvent"
 properties:
   valueType: "Object"
   readWrite: "R"

Define Device Resource for PullPoint

  • Define a SubscribeCameraEvent resource with PullPoint subscribeType for creating the subscription 

    - name: "SubscribeCameraEvent"
 isHidden: false
 description: "Create a subscription to subscribe the event from the camera"
 attributes:
   service: "EdgeX"
   setFunction: "SubscribeCameraEvent"
   # PullPoint | BaseNotification
   subscribeType: "PullPoint"
   defaultSubscriptionPolicy: ""
   defaultInitialTerminationTime: "PT1H"
   defaultAutoRenew: true
   defaultTopicFilter: "tns1:RuleEngine/TamperDetector"
   defaultMessageContentFilter: "boolean(//tt:SimpleItem[@Name=”IsTamper”])"
   defaultMessageTimeout: "PT5S"
   defaultMessageLimit: 10
 properties:
   valueType: "Object"
   readWrite: "W"

  • Define a UnsubscribeCameraEvent resource for unsubscribing 

    - name: "UnsubscribeCameraEvent"
 isHidden: false
 description: "Unsubscribe all event from the camera"
 attributes:
   service: "EdgeX"
   setFunction: "UnsubscribeCameraEvent"
 properties:
   valueType: "Object"
   readWrite: "W"

Define Device Resource for BaseNotification

  • Define a SubscribeCameraEvent resource with BaseNotification subscribeType 

    - name: "SubscribeCameraEvent"
 isHidden: false
 description: "Create a subscription to subscribe the event ..."
 attributes:
   service: "EdgeX"
   setFunction: "SubscribeCameraEvent"
   # PullPoint | BaseNotification
   subscribeType: "BaseNotification"
   defaultSubscriptionPolicy: ""
   defaultInitialTerminationTime: "PT1H"
   defaultAutoRenew: true
   defaultTopicFilter: "..."
   defaultMessageContentFilter: "..."
 properties:
   valueType: "Object"
   readWrite: "W"

  • Override the AppCustom config BaseNotificationURL to indicate the device service network location 

    export HOST_IP=$(ifconfig eth0 | grep "inet " | awk '{ print $2 }')

    # docker-compose.yml
device-onvif-camera:
  environment:
    # BaseNotificationURL indicates the device service network location, the user must replace the host to match their machine
    APPCUSTOM_BASENOTIFICATIONURL: http://${HOST_IP}:59984

Device service will generate the following path for pushing event from Camera to device service:

  • {BaseNotificationURL}/api/v2/resource/{DeviceName}/{ResourceName}
  • {BaseNotificationURL}/api/v2/resource/Camera1/CameraEvent

After this, the device service can be accessed by the external camera from the other subnetwork.

Define Device Resource for Unsubscribing the Event

  - name: "UnsubscribeCameraEvent"
    isHidden: true
    description: "Unsubscribe all subscription from the camera"
    attributes:
      service: "EdgeX"
      setFunction: "UnsubscribeCameraEvent"
    properties:
      valueType: "Object"
      readWrite: "W"

Find the Supported Event Topics

Find out what notifications a camera supports and what information they contain:

curl --request GET 'http://localhost:59882/api/v2/device/name/Camera003/GetEventProperties'

Create a Pull Point

You can create a pull point with the following command: 

curl --request PUT 'http://localhost:59882/api/v2/device/name/Camera003/PullPointSubscription' \
--header 'Content-Type: application/json' \
--data-raw '{
    "PullPointSubscription": {
        "MessageContentFilter": "boolean(//tt:SimpleItem[@Name=\"Rule\"])",
        "InitialTerminationTime": "PT120S",
        "MessageTimeout": "PT20S"
    }
}'

Note

  • The device service uses a loop to pull message, and the subscription auto-renew by camera
  • The device service create a new pull point when the pull point expired
  • You can unsubscribe from the subscription and the device service will stop the loop to pull the message and execute unsubscribe Onvif function.

Create a BaseNotification

When creating subscriptions, the InitialTerminationTime is required and should be greater than ten seconds: 

curl --request PUT 'http://localhost:59882/api/v2/device/name/Camera003/BaseNotificationSubscription' \
--header 'Content-Type: application/json' \
--data-raw '{
    "BaseNotificationSubscription": {
        "TopicFilter": "tns1:RuleEngine/TamperDetector/Tamper",
        "InitialTerminationTime": "PT180S"
    }
}'

Note

  • Device service send Renew request every ten second before termination time
  • User can unsubscribe the subscription, then the device service stop to renew the subscription

Unsubscribe From All Subscriptions

You can unsubscribe from all camera subscriptions (PullPoint and BaseNotification) with the following command: 

curl --request PUT 'http://localhsot:59882/api/v2/device/name/Camera003/UnsubscribeCameraEvent' \
--header 'Content-Type: application/json' \
--data-raw '{
    "UnsubscribeCameraEvent": {
    }
}'