Generic ONVIF Cameras

FreeSDN ships an ONVIF protocol shim that lets you onboard cameras from any vendor that implements ONVIF Profile S or Profile T. It is explicitly a protocol shim - it is not listed as a standalone vendor adapter in the maturity table, and it does not carry the same gold-standard contract guarantees as the Hikvision adapter.

Use ONVIF when:

• You have cameras from a brand without a native FreeSDN adapter.
• A vendor adapter exists but a specific camera model works better through ONVIF (common on hybrid NVR channels).
• You are evaluating a camera fleet before committing to a native integration.

ONVIF profile coverage

ONVIF Profile	Supported	Notes
Profile S (streaming)	Yes	RTSP live stream, snapshot, MJPEG
Profile T (advanced streaming)	Partial	H.264/H.265 stream negotiation; metadata streams not ingested
Profile G (recording/storage)	Partial	Recording search (FindRecordings / GetRecordingSearchResults) and track enumeration implemented for NVR device type; on-camera recording creation and deletion are not exposed.
Profile C (access control)	No	Out of scope
Profile Q (onboarding)	No	Manual onboarding only

What the shim exposes

• Live stream - RTSP URL via GetStreamUri, surfaced as RTSP/HLS in the cameras module.
• Snapshot - JPEG via GetSnapshotUri.
• PTZ - ContinuousMove, Stop, preset read/write/go-to (cameras that advertise PTZ service).
• Device info - GetDeviceInformation (manufacturer, model, firmware, serial).
• Capabilities - GetServices (ONVIF 2.0+) or GetCapabilities (ONVIF 1.x fallback) to detect PTZ/imaging/analytics/recording/events services.
• Media profiles - GetProfiles, GetVideoEncoderConfigurations for stream selection.

Events (motion, line-crossing) are ingested via ONVIF PullPoint polling (subscribe_events + pull_events). The adapter probes for PullPoint support during connect and only activates event ingestion on cameras that advertise the Events service.

Adding an ONVIF camera

1. Open Video Surveillance → Cameras and click Add Camera.
2. Select vendor ONVIF (or Generic ONVIF).
3. Enter the camera IP, port (typically 80), and credentials.

Via API:

# Store credentials
curl -X POST https://freesdn.example.com/api/v1/credentials \
  -H "Cookie: freesdn_access=<token>" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "axis-lobby",
    "credential_type": "username_password",
    "username": "root",
    "password": "s3cr3t"
  }'

# Add camera (credentials are passed inline  -  there is no credential_id field)
curl -X POST https://freesdn.example.com/api/v1/cameras/ \
  -H "Cookie: freesdn_access=<token>" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lobby Axis P3245",
    "ip_address": "10.0.1.55",
    "port": 80,
    "vendor": "onvif",
    "username": "root",
    "password": "s3cr3t",
    "site_id": "<site-uuid>"
  }'

ONVIF device discovery (WS-Discovery)

ONVIF devices announce themselves over UDP multicast. FreeSDN’s discovery agent can probe for WS-Discovery announcements on a subnet when configured:

# Trigger an ONVIF WS-Discovery multicast probe (cameras module endpoint)
curl -X POST 'https://freesdn.example.com/api/v1/cameras/discovery/scan?timeout=4' \
  -H "Cookie: freesdn_access=<token>" \
  -H "X-CSRF-Token: <csrf>"

Discovered devices appear in the Inventory tab for manual adoption.

Caution

WS-Discovery uses UDP multicast (port 3702). If the FreeSDN host is not on the same broadcast domain as the cameras, discovery will not find them. Add cameras manually by IP in that case.

Stream URL negotiation

The shim calls GetStreamUri with StreamSetup.Stream='RTP-Unicast' and Transport.Protocol='RTSP' (Media1), or with Protocol='RTSP' alone (Media2 - no stream-type field). The resulting RTSP URL is stored against the camera record and used for live view and recording. If a camera requires a specific media profile, select it on the Camera Detail page under the Stream tab.

PTZ via ONVIF

PTZ commands are available when the camera advertises the ONVIF PTZ service. The shim translates FreeSDN’s normalized PTZ actions (up, down, left, right, zoom_in, zoom_out, stop, preset) to ONVIF ContinuousMove / Stop calls.

Preset operations:

• List presets - GetPresets
• Go to preset - GotoPreset
• Set preset - SetPreset

Tip

Some cameras implement ONVIF PTZ but also expose a richer vendor-specific PTZ API. If fine-grained speed control or patrol configuration is needed, check whether a native adapter exists for your camera model.

Authentication

The shim supports:

• WS-UsernameToken / WSSE (default for SOAP operations - all ONVIF devicemgmt, media, PTZ, and events calls go through onvif-zeep, which sends a WS-Security UsernameToken header on every SOAP request)
• HTTP Digest (used for snapshot URI downloads via httpx; falls back to HTTP Basic if the camera returns 401 to Digest)

If a camera rejects both, check that the ONVIF user account has the right permission level in the camera’s own web UI (typically Administrator or Operator).

Known limitations

• Event ingestion via PullPoint polling - ONVIF events are ingested using subscribe_events() (creates a PullPointSubscription) and pull_events() (calls PullMessages). Motion, line-crossing, and other events are surfaced when the camera advertises the Events service.
• Audio is model-dependent - audio capability (CAMERA_AUDIO) is detected from media-profile inspection (AudioSourceConfiguration / AudioEncoderConfiguration) during connection and advertised when the camera reports it. Two-way audio (CAMERA_TWO_WAY_AUDIO) is declared in the PTZ camera manifest, but end-to-end UI support has not been fully verified; confirm against your specific camera model before relying on it.
• Profile G is partial - recording search (FindRecordings / GetRecordingSearchResults) and track enumeration (get_recording_tracks) are implemented for the NVR device type. Recording creation and deletion are not exposed; use a vendor adapter for full recording management.
• No firmware update - firmware lifecycle is vendor-specific; use the camera’s own management interface.
• Maturity - the ONVIF shim is not listed in the vendor maturity table because it is a protocol layer, not a vendor adapter. It has not been hardened or reviewed to the same depth as the Hikvision adapter. Use it for onboarding and basic operations; validate against your camera models before relying on it in production.

Backend route prefix

ONVIF cameras use the same cameras-module routes as Hikvision (/api/v1/cameras/). The adapter is selected automatically based on vendor: "onvif" on the camera record.