onvif Go Library

Using the library follows a four-step workflow:

1. Connecting to the device: Initialize a device object using onvif.NewDevice with the appropriate network address and port.
2. Authentication: If the device requires it, provide credentials during initialization or use the Authenticate method.
3. Defining Data Types: Create a request structure corresponding to the ONVIF service method you wish to call. Each service has its own package (e.g., device, ptz) containing these structures.
4. Carrying out the method: Execute the request by passing the defined structure to the CallMethod function of the device object.

Each service has a dedicated package named after the service (capitalized). Data types for specific functions are defined as structures within these packages.

Common data types shared across multiple services (like User) are located in the onvif package.

Examples:

• Device Service: device.GetCapabilities or device.CreateUsers.
• PTZ Service: ptz.GetServiceCapabilities.
• Shared Types: onvif.User.

// Example: Defining GetCapabilities for the Device service
capabilities := device.GetCapabilities{Category: "All"}

// Example: Defining GetServiceCapabilities for the PTZ service
ptzCapabilities := ptz.GetServiceCapabilities{}

// Example: Using a shared type from the onvif package in a service request
createUsers := device.CreateUsers{User: onvif.User{Username: "admin", Password: "qwerty", UserLevel: "User"}}

To install the library, use the go get command to fetch the module from GitHub.

go get github.com/use-go/onvif

The DeviceType type represents the different categories of ONVIF-compliant hardware. You can use these constants when performing discovery.

• NVD: NetworkVideoDisplay
• NVS: NetworkVideoStorage
• NVA: NetworkVideoAnalytics
• NVT: NetworkVideoTransmitter

type DeviceType int

const (
	NVD DeviceType = iota // NetworkVideoDisplay
	NVS                  // NetworkVideoStorage
	NVA                  // NetworkVideoAnalytics
	NVT                  // NetworkVideoTransmitter
)

Once you have defined the request structure for a specific service method, use the CallMethod function on your device instance to execute the command and receive a response.

// 1. Define the request
createUsers := device.CreateUsers{User: onvif.User{Username: "admin", Password: "qwerty", UserLevel: "User"}}

// 2. Initialize device
device := onvif.NewDevice(onvif.DeviceParams{Xaddr: "192.168.13.42:1234", Username: "username", Password: password})

// 3. Authenticate
device.Authenticate("username", "password")

// 4. Call the method
resp, err := device.CallMethod(createUsers)

Use onvif.NewDevice with onvif.DeviceParams. The Xaddr field should contain the IP address and port (e.g., 192.168.13.42:1234). Note that the ONVIF port is often 80, but you should verify this via the device's web interface.

dev, err := onvif.NewDevice(onvif.DeviceParams{Xaddr: "192.168.13.42:1234"})

To handle services requiring authentication, you can provide credentials directly in onvif.DeviceParams during initialization, or call the Authenticate method on the device object.

// Via DeviceParams
device := onvif.NewDevice(onvif.DeviceParams{Xaddr: "192.168.13.42:1234", Username: "username", Password: password})

// Via Authenticate method
device.Authenticate("username", "password")

The library implements the following ONVIF services:

• Device
• Media
• PTZ
• Imaging
• Event
• Discovery
• Auth
• Soap

Once a Device is initialized, you can query its metadata and service locations:

• GetDeviceInfo(): Returns a DeviceInfo struct containing Manufacturer, Model, FirmwareVersion, SerialNumber, and HardwareId.
• GetServices(): Returns a map[string]string of all discovered service endpoints (e.g., "media": "http://.../media_service").
• GetEndpoint(name string): Returns the specific URL for a service by name (e.g., device.GetEndpoint("media")).
• GetDeviceParams(): Returns the original DeviceParams used to connect.

The CallMethod function is the primary way to interact with an ONVIF device. It takes a method struct (representing a SOAP request) and automatically determines the correct service endpoint based on the package name of the method struct.

If Username and Password are provided in the DeviceParams, CallMethod will automatically include WS-Security authentication in the SOAP header.

Note: The method struct's package name is used to route the request to the appropriate service (e.g., a struct in the media package will be routed to the Media service endpoint).

// Assuming 'method' is a struct defined in a package like 'media'
resp, err := device.CallMethod(method)
if err != nil {
	// Handle error
}
defer resp.Body.Close()

Use GetAvailableDevicesAtSpecificEthernetInterface to perform a WS-Discovery probe on a specific network interface. This function searches for devices of type NVT (Network Video Transmitter).

It returns a slice of Device objects representing the discovered devices.

devices, err := onvif.GetAvailableDevicesAtSpecificEthernetInterface("eth0")
if err != nil {
	// Handle discovery error
}

for _, dev := range devices {
	fmt.Printf("Found device at: %s\n", dev.GetDeviceParams().Xaddr)
}

Use NewDevice to create a new Device instance. This function automatically attempts to discover the device's capabilities and available service endpoints. You must provide a DeviceParams struct containing the device's network address (Xaddr).

If the device is unreachable or does not support ONVIF services, NewDevice will return an error.

params := onvif.DeviceParams{
	Xaddr:    "192.168.1.100",
	Username: "admin",
	Password: "password",
}

device, err := onvif.NewDevice(params)
if err != nil {
	// Handle error (e.g., device unreachable)
}