onvif-go/.claude/docs copy/CLI_NETWORK_INTERFACE_USAGE.md

CLI Tools with Network Interface Support

This guide shows how to use the enhanced CLI tools with network interface discovery capabilities.

Overview

Both onvif-cli and onvif-quick now support explicit network interface selection when discovering ONVIF cameras. This is useful when you have multiple network interfaces on your system.

onvif-cli - Full-featured CLI

Building onvif-cli

# From the project root
go build -o onvif-cli ./cmd/onvif-cli

Running onvif-cli

./onvif-cli

Main Menu Features

📋 Main Menu:
  1. Discover Cameras on Network
  2. List Network Interfaces
  3. Connect to Camera
  4. Device Operations
  5. Media Operations
  6. PTZ Operations
  7. Imaging Operations
  0. Exit

Feature 1: List Network Interfaces

Select option 2 to see all available network interfaces:

🌐 Available Network Interfaces
================================
✅ Found 3 interface(s):

📡 lo (⬆️  Up, Multicast: ✓)
   └─ 127.0.0.1
   └─ ::1

📡 eth0 (⬆️  Up, Multicast: ✓)
   └─ 192.168.1.100
   └─ fe80::1

📡 wlan0 (⬆️  Up, Multicast: ✓)
   └─ 192.168.88.50

💡 Use interface name or IP address when discovering cameras
   Example: eth0 or 192.168.1.100

Feature 2: Discover with Interface Selection

Select option 1 for camera discovery:

🔍 Discovering ONVIF cameras...
This may take a few seconds...
Use specific network interface? (y/n) [n]: y

🌐 Available network interfaces:
  1. lo
     └─ 127.0.0.1
     (Up: true, Multicast: No)
  2. eth0
     └─ 192.168.1.100
     (Up: true, Multicast: Yes)
  3. wlan0
     └─ 192.168.88.50
     (Up: true, Multicast: Yes)

Enter interface name or IP address: eth0
🎯 Using interface: eth0

✅ Found 2 camera(s):

📹 Camera #1:
   Endpoint: http://192.168.1.101:8080/onvif/device_service
   Name: Office Camera
   Location: Conference Room A
   Types: [...]
   XAddrs: [...]

Usage Scenarios

Scenario 1: Quick Camera Discovery (Default Interface)

./onvif-cli
# Select: 1 (Discover)
# Answer: n (use default interface)
# Result: Discovers on system default interface

Scenario 2: Discover on Specific Ethernet Interface

./onvif-cli
# Select: 2 (List interfaces)
# See eth0 is available with 192.168.1.100
# Select: 1 (Discover)
# Answer: y (use specific interface)
# Enter: eth0 or 192.168.1.100
# Result: Discovers only on eth0

Scenario 3: Discover on WiFi Interface

./onvif-cli
# Select: 2 (List interfaces)
# See wlan0 is available with 192.168.88.50
# Select: 1 (Discover)
# Answer: y (use specific interface)
# Enter: wlan0
# Result: Discovers only on wlan0

Scenario 4: Connect and Control

./onvif-cli
# Select: 1 (Discover) -> Find camera -> Connect
# Or: Select: 3 (Connect) -> Enter endpoint manually
# Then use options 4-7 for device/media/ptz/imaging control

onvif-quick - Quick Demo Tool

Building onvif-quick

# From the project root
go build -o onvif-quick ./cmd/onvif-quick

Running onvif-quick

./onvif-quick

Main Menu Features

What would you like to do?
1. 🔍 Discover cameras
2. 🌐 List network interfaces
3. 📹 Connect to camera
4. 🎮 PTZ demo
5. 📡 Get stream URLs
0. Exit

Feature 1: List Network Interfaces

Select option 2:

🌐 Network Interfaces
====================
✅ Found 3 interface(s):

📡 lo (Up, Multicast: No)
   └─ 127.0.0.1
   └─ ::1

📡 eth0 (Up, Multicast: Yes)
   └─ 192.168.1.100
   └─ fe80::1

📡 wlan0 (Up, Multicast: Yes)
   └─ 192.168.88.50

Feature 2: Quick Discovery with Interface Selection

Select option 1:

🔍 Discovering cameras on network...
Use specific network interface? (y/n) [n]: y

Available interfaces:
  1. lo (127.0.0.1, ::1)
  2. eth0 (192.168.1.100, fe80::1)
  3. wlan0 (192.168.88.50)

Enter interface name or IP: eth0
✅ Found 1 camera(s):
  1. Office Camera (http://192.168.1.101:8080/onvif/device_service)

Quick Demo Workflows

Workflow 1: List Interfaces → Discover → Check Streams

./onvif-quick
# Select: 2 (List interfaces)
# See which interfaces are available
# Select: 1 (Discover)
# Choose eth0
# Specify credentials when found
# Select: 5 (Get stream URLs) to see RTSP streams

Workflow 2: PTZ Demo on Specific Interface

./onvif-quick
# Select: 1 (Discover) on eth0
# Find PTZ-capable camera
# Select: 4 (PTZ demo)
# Test pan/tilt/zoom movements

Common Workflows

Workflow A: Multi-Network Environment

You have a system with both Ethernet (192.168.1.0/24) and WiFi (192.168.88.0/24):

./onvif-cli

# Step 1: List interfaces
1 (Discover)
n (default)
# No results?

# Step 2: Try Ethernet explicitly
1 (Discover)
y (specific interface)
eth0
# Found cameras on ethernet!

# Step 3: Try WiFi
1 (Discover)
y (specific interface)
wlan0
# Found different cameras on WiFi!

Workflow B: Docker Container with Multiple Networks

Container has management (172.17.0.x) and camera (172.20.0.x) networks:

./onvif-quick

# Step 1: See available networks
2 (List interfaces)
# Output shows two networks with different IPs

# Step 2: Discover on camera network
1 (Discover)
y (specific interface)
172.20.0.10  # Use the camera network IP
# Discovers cameras on the camera network

Workflow C: Network Troubleshooting

Discovery not working as expected?

./onvif-cli

# Step 1: Check all interfaces
2 (List interfaces)
# Look for:
# - Interfaces marked "Up: true"
# - Multicast support: Yes
# - Expected IP addresses

# Step 2: Try discovery on each interface
1 (Discover)
y (use specific interface)
# Try each interface name one by one
# See which one finds cameras

# Result: Identifies which network has your cameras

Tips & Best Practices

1. Check Interface Status First

Always start with option 2 to see:

• Interface names (eth0, wlan0, docker0, etc.)
• IP addresses assigned
• Whether multicast is supported
• Whether the interface is up/down

# Quick check
./onvif-cli
2 (List interfaces)

2. Use Interface Names When Possible

Interface names are more reliable than IP addresses:

Good:  eth0, wlan0
Less good: 192.168.1.100 (may change)

3. Check Multicast Support

Ensure the interface supports multicast (required for WS-Discovery):

Look for: "Multicast: Yes" or "Multicast: ✓"

4. Isolate Discovery to One Network

If you have many interfaces, disable the ones you don't need:

./onvif-cli
1 (Discover)
y (specify eth0)
# Only discovers on eth0, ignores other interfaces

5. Scripting and Automation

For automation, you can pipe input:

# Non-interactive discovery on eth0
(echo 1; echo y; echo eth0; sleep 2; echo 0) | ./onvif-cli

# Or with timeout
timeout 30 bash -c '(echo 1; echo y; echo eth0) | ./onvif-cli'

Troubleshooting

Problem: "Use specific network interface?" appears on every discovery

Solution: This is the normal behavior in onvif-cli. To skip it, answer n to use the system default interface.

Problem: Interface listed but discovery fails

Possible causes:

1. Interface doesn't support multicast (check "Multicast: Yes")
2. Cameras aren't on that network segment
3. Firewall blocking UDP 3702

Solution:

./onvif-cli
2 (List interfaces)
# Check Multicast: Yes
# Check interface is "Up: true"
1 (Discover)
y (use specific interface)
# Try the confirmed interface

Problem: "network interface not found" error

Solution:

1. Use 2 (List interfaces) to see exact interface names
2. Copy the exact name from the list
3. Try again with correct interface name

# Wrong:  eth-0 or ethnet0
# Right:  eth0 (from list)

Problem: No cameras found on any interface

Possible causes:

1. Cameras on different subnet
2. Firewall blocking discovery
3. ONVIF not enabled on cameras

Solution:

# Try each interface individually
./onvif-cli
2 (List interfaces)
# For each interface that shows "Multicast: Yes" and "Up: true"
1 (Discover)
y (use that interface)
# Check if cameras found

Integration with Other Tools

Using Discovered Camera with VLC

./onvif-cli
1 (Discover)
y (eth0)
# Get stream URL from discovered camera
2 (Get stream URIs)
# Copy RTSP URL
# Paste into VLC: File → Open Network Stream

Scripting Camera Discovery

#!/bin/bash
# discover_cameras.sh

# List all interfaces with multicast support
./onvif-cli << EOF
2
q
EOF | grep "Multicast: ✓" | grep -o "📡 [^ ]*" | cut -d' ' -f2 | while read iface; do
    echo "Discovering on $iface..."
    # Could add automated discovery here
done

Related Documentation

• NETWORK_INTERFACE_GUIDE.md - Detailed discovery API guide
• QUICKSTART.md - Quick start guide
• examples/discovery/ - Discovery code examples
• ONVIF Specification - Official ONVIF specs

Command Reference

onvif-cli Commands

Option	Feature	Purpose
1	Discover Cameras	Find ONVIF cameras (with interface selection)
2	List Interfaces	See all network interfaces
3	Connect to Camera	Manual endpoint connection
4	Device Operations	Info, capabilities, datetime, reboot
5	Media Operations	Profiles, streams, snapshots, video settings
6	PTZ Operations	Pan/tilt/zoom control and presets
7	Imaging Operations	Brightness, contrast, saturation, etc.
0	Exit	Quit the application

onvif-quick Commands

Option	Feature	Purpose
1	Discover Cameras	Find ONVIF cameras (quick, with interface selection)
2	List Interfaces	See all network interfaces
3	Connect to Camera	Quick connection and info
4	PTZ Demo	Quick PTZ movement demonstration
5	Get Stream URLs	Display all stream and snapshot URLs
0	Exit	Quit the application

Version History

• Current: Network interface selection support added
• Previous: Basic discovery and camera control