ONVIF Device Discovery with WS-Discovery

Discover and manage ONVIF cameras and devices on your network automatically using the WS-Discovery protocol. A complete guide for developers and system integrators.

What is ONVIF Device Discovery?

ONVIF Device Discovery enables automatic detection of ONVIF-compliant devices (like IP cameras, NVRs, media servers) on a local network. It uses the WS-Discovery (Web Services Dynamic Discovery) protocol, allowing clients to find devices without knowing their IP addresses beforehand.

This is essential for:

  • Network Setup: Quickly add new cameras to a VMS (Video Management System).
  • System Integration: Automatically detect and configure devices in large installations.
  • Remote Management: Locate devices for maintenance or troubleshooting.

The process is based on multicast messaging over UDP port 3702.

How Device Discovery Works

Discovery happens through two primary mechanisms:

1. Hello Messages (Announcement)

When a device (e.g., a camera) connects to the network, it sends a multicast Hello message to announce its presence.

Key elements in a Hello message:

  • <d:Types>: Must include tds:Device to identify as an ONVIF device.
  • <d:Scopes>: Contains URIs that categorize the device (e.g., model, location, profile).
  • <d:XAddrs>: The device's service endpoint URL(s) (e.g., http://192.168.1.100:80/onvif/device_service).

2. Probe Messages (Search)

A client (e.g., VMS) can actively search for devices by sending a multicast Probe message.

The Probe can include filters like:

  • Types: Search for specific service types (e.g., tds:Device, trt:Media).
  • Scopes: Search within specific categories (e.g., onvif://www.onvif.org/location/country/china).

Devices that match the criteria respond with a ProbeMatch message containing their <d:XAddrs>, <d:Scopes>, and other details.

Note: Devices are discoverable by default. For security, they can be set to "non-discoverable" mode to ignore discovery messages.

Scopes: Organizing Your Devices

Scopes are crucial for filtering and organizing devices. They are URIs with the format onvif://www.onvif.org/<category>/<value>.

Common scope categories:

  • Profile/Streaming: Indicates support for streaming.
  • hardware/ModelNumber: Device model (e.g., hardware/D1-566).
  • location/...: Geographical or physical location (e.g., location/country/china, location/building/headquarter).
  • name/DeviceName: Human-readable device name.

A well-configured scope list allows clients to quickly find devices based on location, model, or function.

Testing Device Discovery

Verify discovery works using these methods:

Using Happytime ONVIF Client

Launch the client and use the "Refresh" function. It should automatically list all ONVIF devices on the network.

Using ONVIF Device Manager (ODM)

Launch ODM and use the "Refresh" function. It should automatically list all ONVIF devices on the network.

Wireshark Analysis

Capture network traffic on UDP port 3702 to see discovery messages in action:

  • Multicast Hello: Sent from device to 239.255.255.250:3702.
  • Multicast Probe: Sent from client to 239.255.255.250:3702.
  • Unicast ProbeMatch: Sent from device to client with discovery details.

Analyze the SOAP XML in the packets to see <d:Types>, <d:Scopes>, and <d:XAddrs>.

Best Practices

  • Use Meaningful Scopes: Configure devices with accurate location, model, and name scopes for easier management.
  • Network Segmentation: Use VLANs to limit discovery traffic to relevant subnets.
  • Security: In high-security environments, consider setting devices to "non-discoverable" mode after initial setup.
  • Firewall Rules: Ensure UDP port 3702 is open on the local network for discovery to work.
  • Testing: Always test discovery in your network environment before deployment.