ONVIF

The ONVIF page discovers IP cameras on your network, retrieves their RTSP stream URLs, and lets you map them to GEM camera zones. It also supports PTZ camera control, mapping camera relay outputs and digital inputs to GEM zones.

Scan Configuration

Credentials

The scan supports multiple credential sets to handle networks with cameras from different manufacturers or with different passwords. Each credential set has a Username and Password field.

• Click Add Credentials to add another username/password pair.
• Cameras are tried with each credential set in order until one succeeds.
• Toggle Show passwords to reveal all password fields.
• Credentials are saved to browser local storage between sessions.

tip

Add your most common credentials first. During a CIDR scan, GEM tries each credential set on every reachable camera, so ordering by frequency speeds up discovery.

Scan Settings

Field	Description
Timeout	Scan duration in milliseconds (range: 1000 - 120000, default: 60000).
Target IP / CIDR	Optional. A specific IP address (e.g., 192.168.1.100) or CIDR range (e.g., 192.168.1.0/24). Auto-populated with the GEM server's local network on page load. Leave blank to scan the entire local network.

Running a Scan

1. Add one or more credential sets.
2. Optionally adjust the target IP/CIDR and timeout.
3. Click Scan Network. A progress bar shows scan progress and a count of discovered devices.
4. Click Cancel to stop the scan early.
5. Cameras appear in real-time as they are discovered.

How Scanning Works

For CIDR range scans, GEM uses a two-phase approach:

1. TCP Probe — Fast parallel connection test on common ONVIF ports (80, 2020, 8080, 8000, 8899, 554) to find reachable hosts.
2. ONVIF Connect — For each reachable host, attempts WS-Security authentication with each credential set. If a camera rejects WS-Security (common with Amcrest/Dahua), GEM automatically retries with HTTP Digest authentication.

After scanning, the results summary shows how many cameras were found and whether any hosts rejected all credentials (indicating wrong username/password).

If a host has no ONVIF service but RTSP port 554 is open, GEM reports this and offers manual RTSP URL entry (see Manual RTSP Mapping below).

Discovered Devices

Each discovered device is displayed as a card with the following information:

• Status indicator: Color-coded dot showing the device state (loading, connected, error, or warning).
• Manufacturer and Model: The camera's brand and model name.
• Device type badges: Labels indicating the device's capabilities: Camera, Relay, Input, or combinations like Camera+Relay.
• Mapped status: If the device is already mapped to a GEM zone, the zone name is shown with a green indicator.
• IP Address and Port: The device's network address.
• Serial Number: The device's serial number, if reported.
• RTSP URL: The stream URL retrieved from the camera.

Relay Outputs

If the camera has relay outputs, they are listed below the device information. Each relay shows:

• Relay token, mode, and idle state.
• Whether the relay is already mapped to a GEM zone.
• A Map button to create a zone mapping for that relay (disabled if already mapped).

Digital Inputs

If the camera has digital inputs, they are listed as events-only information (no mapping available for digital inputs).

Device Actions

Each device card has the following action buttons:

Button	Description
Details	Shows the full device information as raw JSON in a modal.
View	Opens a live stream preview using the RtspStreamPlayer component in a modal window.
Test RTSP	Tests the RTSP stream URL connectivity.
Map to Zone / Remap Zone	Opens the camera mapping modal to create or link a GEM zone. If the camera is already mapped to a zone, the button reads Remap Zone and prompts for confirmation before remapping.

Manual RTSP Mapping

When a camera's RTSP port (554) is open but no ONVIF service was found, the device card shows a manual RTSP URL section:

1. URL Template dropdown — Select a manufacturer-specific RTSP path template (TP-Link/TAPO, Hikvision, Dahua/Amcrest, Reolink, etc.) to auto-fill the URL with the camera's IP and your credentials.
2. Manual URL field — Edit the generated URL or enter one manually.
3. Click Set to apply the URL, then use Map to Zone as usual.

tip

If you don't know your camera's RTSP path, the iSpy camera URL database has paths for thousands of models.

Camera Mapping Modal

When you click Map to Zone (or Remap Zone) on a device, a modal appears with two options:

Map to Existing Zone:

• A dropdown of existing camera zones. Select one to set the stream_url attribute on that zone.

Create New Zone:

• Enter a zone name for the new camera zone. A zone is created in the camera subsystem with the stream URL set automatically.

PTZ Attributes

When a camera supports PTZ and was discovered with valid ONVIF credentials, the following attributes are automatically stored on the mapped zone:

Attribute	Description
onvif_host	Camera IP address
onvif_port	ONVIF service port (default: 2020)
onvif_username	ONVIF username
onvif_password	ONVIF password (stored encrypted)
onvif_profile	ONVIF media profile token for PTZ

These attributes enable PTZ control directly from the camera zone viewer without requiring a GEM device driver. PTZ commands (pan, tilt, zoom, presets) are routed through the ONVIF service automatically.

Stream Performance Attributes

The RTSP proxy decodes camera streams to JPEG via ffmpeg. The following zone attributes tune CPU/quality trade-offs:

Attribute	Description
frame_rate	Output frame rate in fps (default: 3). Tile/preview views use a low rate; live/fullscreen views may request higher.
hardware_accelerator	ffmpeg -hwaccel value (e.g. auto, vaapi, qsv, cuvid, none). Defaults to auto. If a configured accelerator is not available on the host, ffmpeg silently falls back to software decode and a warning is logged.

tip

The proxy runs ffmpeg single-threaded with audio stripped, since multiple concurrent decoders compete for the same cores. CPU is best controlled by lowering frame_rate and resolution rather than by skipping frames.

Relay Mapping Modal

When you click Map on a relay output, a modal appears:

1. Select Subsystem: Choose the GEM subsystem for the relay zone (e.g., lighting, security).
2. After selecting a subsystem, choose either:
   • An existing zone from the dropdown, or
   • Enter a new zone name to create one.
3. Click Map to create the relay zone mapping.

Stream Preview

Clicking View on a device opens a modal with a live RTSP stream preview. This uses a temporary onvif_preview zone internally. Close the modal when done previewing.

tip

Use the preview feature to verify that camera credentials and stream URLs are correct before mapping the camera to a permanent zone.

Troubleshooting

No Cameras Discovered

1. Verify cameras are on the same network as the GEM server.
2. Confirm ONVIF is enabled in each camera's settings. Some cameras require creating a separate ONVIF user account.
3. Check that the firewall allows multicast traffic (ONVIF uses WS-Discovery).
4. Verify credentials — if the scan reports "authentication failed", add the correct username/password as a credential set.
5. Increase the timeout if cameras respond slowly.
6. Some cameras (Amcrest, Dahua) use HTTP Digest instead of WS-Security — GEM handles this automatically, but ensure the correct password is provided.
7. If the scan finds an open RTSP port but no ONVIF service, use the manual RTSP URL entry to map the camera.

Stream Not Working

1. Check that RTSP port (typically 554) is accessible.
2. Verify credentials are correct.
3. Confirm the camera's streaming is enabled.

Related Documentation

• Zones — Camera zone configuration
• Devices — Device setup
• Attributes — Zone attribute management