Files

T

ProtoTess c384dca68d feat: add network interface selection to WS-Discovery

- Add DiscoverOptions struct with NetworkInterface field
- Add DiscoverWithOptions() function for interface-specific discovery
- Add ListNetworkInterfaces() to enumerate available interfaces
- Add resolveNetworkInterface() helper supporting names and IPs
- Maintain full backward compatibility with existing Discover() function
- Support specifying interface by name (eth0, wlan0) or IP address
- Provide helpful error messages listing available interfaces
- Comprehensive test suite with 6 unit tests + 2 benchmarks
- Add NETWORK_INTERFACE_GUIDE.md with usage examples

This addresses issue where users with multiple active network interfaces
need to explicitly select which interface to use for WS-Discovery multicast,
as auto-detection may select the wrong one.

2025-11-17 17:28:05 +00:00

11 KiB

Raw Permalink Blame History

Network Interface Discovery Guide

This guide explains how to use the network interface selection feature for ONVIF device discovery.

Overview

When you have multiple network interfaces on your system, you may need to specify which interface to use for sending multicast discovery messages to find your cameras. This is especially important when:

You have multiple network cards (Ethernet, WiFi, Virtual Adapters)
Cameras are on a specific network segment
The auto-detected interface doesn't reach your cameras
You want to isolate discovery traffic to a specific network

Features

✅ Specify by Interface Name - Use interface name (e.g., "eth0", "wlan0")
✅ Specify by IP Address - Use any IP assigned to the interface
✅ List Available Interfaces - See all interfaces with their configurations
✅ Backward Compatible - Existing code continues to work unchanged
✅ Helpful Error Messages - Lists available interfaces when one isn't found

Basic Usage

1. List Available Network Interfaces

package main

import (
    "fmt"
    "log"
    "github.com/0x524a/onvif-go/discovery"
)

func main() {
    interfaces, err := discovery.ListNetworkInterfaces()
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("Available Network Interfaces:")
    for _, iface := range interfaces {
        fmt.Printf("  %s - Up: %v, Multicast: %v\n", iface.Name, iface.Up, iface.Multicast)
        for _, addr := range iface.Addresses {
            fmt.Printf("    IP: %s\n", addr)
        }
    }
}

Output Example:

Available Network Interfaces:
  lo - Up: true, Multicast: true
    IP: 127.0.0.1
    IP: ::1
  eth0 - Up: true, Multicast: true
    IP: 192.168.1.100
    IP: 169.254.1.1
  wlan0 - Up: true, Multicast: true
    IP: 192.168.88.50
  docker0 - Up: true, Multicast: true
    IP: 172.17.0.1

2. Discover Cameras on Specific Interface (by name)

package main

import (
    "context"
    "fmt"
    "log"
    "time"
    "github.com/0x524a/onvif-go/discovery"
)

func main() {
    opts := &discovery.DiscoverOptions{
        NetworkInterface: "eth0",  // Discover on Ethernet
    }

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    devices, err := discovery.DiscoverWithOptions(ctx, 5*time.Second, opts)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d devices on eth0:\n", len(devices))
    for _, device := range devices {
        fmt.Printf("  - %s\n", device.GetDeviceEndpoint())
    }
}

3. Discover Cameras Using IP Address

package main

import (
    "context"
    "fmt"
    "log"
    "time"
    "github.com/0x524a/onvif-go/discovery"
)

func main() {
    opts := &discovery.DiscoverOptions{
        NetworkInterface: "192.168.1.100",  // Use interface with this IP
    }

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    devices, err := discovery.DiscoverWithOptions(ctx, 5*time.Second, opts)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d devices:\n", len(devices))
    for _, device := range devices {
        fmt.Printf("  - %s\n", device.GetDeviceEndpoint())
    }
}

4. Backward Compatible - No Changes Required

Existing code continues to work without modification:

package main

import (
    "context"
    "fmt"
    "log"
    "time"
    "github.com/0x524a/onvif-go/discovery"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    // This still works exactly as before
    devices, err := discovery.Discover(ctx, 5*time.Second)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d devices\n", len(devices))
}

API Reference

DiscoverOptions

type DiscoverOptions struct {
    // NetworkInterface specifies the network interface to use for multicast.
    // If empty, the system will choose the default interface.
    // Examples: "eth0", "wlan0", "192.168.1.100"
    NetworkInterface string
}

Functions

`Discover(ctx context.Context, timeout time.Duration) ([]*Device, error)`

Discovers ONVIF devices using the default network interface (backward compatible).

Parameters:

ctx: Context for cancellation and timeout
timeout: How long to listen for responses

Returns:

[]*Device: Discovered devices
error: Any error that occurred

`DiscoverWithOptions(ctx context.Context, timeout time.Duration, opts DiscoverOptions) ([]Device, error)`

Discovers ONVIF devices with custom options including network interface selection.

Parameters:

ctx: Context for cancellation and timeout
timeout: How long to listen for responses
opts: Discovery options (including NetworkInterface)

Returns:

[]*Device: Discovered devices
error: Any error that occurred

`ListNetworkInterfaces() ([]NetworkInterface, error)`

Lists all available network interfaces with their details.

Returns:

[]NetworkInterface: All network interfaces
error: Any error that occurred