View Source Onvif.Device (Onvif v0.5.0)

A Device is an abstraction of a physical piece of hardware.

Setting up a device is done most easily by passing in the results of an Onvif.Discovery.Probe and credentials that can be used to perform ONVIF operations on the physical device.

Summary

Functions

Returns a {:ok, Device.t()} tuple with device struct prepopulated with data required to make an Onvif API request.

Returns a Device.t() struct populated with the bare requirements for making a request to an Onvif enabled device.

Utility function to encode a Device.t() struct into a json string.

Returns a {:ok, Device.t()} if the map can be properly parsed into a struct or {:error, Ecto.Changeset.t()} if not.

Types

t()

@type t() :: %Onvif.Device{
  address: term(),
  auth_type: term(),
  device_service_path: term(),
  firmware_version: term(),
  hardware_id: term(),
  manufacturer: term(),
  media_ver10_service_path: term(),
  media_ver20_service_path: term(),
  model: term(),
  ntp: term(),
  password: term(),
  port: term(),
  recording_ver10_service_path: term(),
  replay_ver10_service_path: term(),
  scopes: term(),
  search_ver10_service_path: term(),
  serial_number: term(),
  services: term(),
  system_date_time: term(),
  time_diff_from_system_secs: term(),
  username: term()
}

Functions

changeset(device, attrs \\ %{})

@spec changeset(t(), map()) :: Ecto.Changeset.t()

init(probe_match, username, password, prefer_https? \\ false, prefer_ipv6? \\ false)

@spec init(Onvif.Discovery.Probe.t(), String.t(), String.t(), boolean(), boolean()) ::
  {:error, any()} | {:ok, t()}

Returns a {:ok, Device.t()} tuple with device struct prepopulated with data required to make an Onvif API request.

probe_match is a valid Probe.t() struct for an Onvif compliant device.

username is an Onvif enabled username. Some manufacturers allow the admin credentials to serve this purpose, but generally you need to enable Onvif for a user in the device's web GUI or create dedicated credentials for Onvif.

password is the password for the username above.

prefer_https? will try requests via a probed https address if present. May run into SSL errors so http is generally preferred.

prefer_ipv6? will try requests via a probed ipv6 address if present.

init will attempt to make requests for the device's system datetime, an authenticated request for device information, and an authenticated request for services to determine what the device's system can provide. As this makes several HTTP/HTTPS requests, there are several points of failure which will return as {:error, reason}.

If init fails a device can be initialized with new/3, providing the address (in form http://ip:port), the username and the password. Then override any other field with a struct update because the init helpers haven't filled in any service paths, scopes, or an auth best guess.

new(address, username, password)

@spec new(String.t(), String.t(), String.t()) :: {:ok, t()}

Returns a Device.t() struct populated with the bare requirements for making a request to an Onvif enabled device.

address is a http address with the form http://ip:port

username is the onvif enabled username

password is the password for the username

As this is an override for the init() function, your mileage may vary here, and some manual struct updates may be required for the onvif requests to succeed. It is recommended to check calls on an authentication required endpoint and swap out auth_type for the one that works.

to_json(schema)

@spec to_json(t()) ::
  {:ok, String.t()}
  | {:error, Ecto.Changeset}
  | {:error, Jason.EncodeError.t() | Exception.t()}

Utility function to encode a Device.t() struct into a json string.

It returns an {:error, Ecto.Changeset.t()} if the struct is not valid.

to_struct(parsed)

@spec to_struct(map()) :: {:ok, t()} | {:error, Ecto.Changeset.t()}

Returns a {:ok, Device.t()} if the map can be properly parsed into a struct or {:error, Ecto.Changeset.t()} if not.