viamrtsp

README

viamrtsp module

This module implements the "rdk:component:camera" API for real-time streaming protocol (RTSP) enabled cameras. Four models are provided:

• viam:viamrtsp:rtsp - Codec agnostic. Will auto detect the codec of the rtsp_address.
• viam:viamrtsp:rtsp-h264 - Only supports the H264 codec.
• viam:viamrtsp:rtsp-h265 - Only supports the H265 codec.
• viam:viamrtsp:rtsp-mjpeg - Only supports the M-JPEG codec.
• viam:viamrtsp:rtsp-mpeg4 - Only supports the MPEG4 codec. This module also implements the "rdk:service:discovery" API, to surface rtsp cameras based on their communication protocol. The following models are implemented:
• viam:viamrtsp:onvif - discovers cameras using the onvif interface.

Configure your viamrtsp camera

Navigate to the CONFIGURE tab of your machine in the Viam app. Add the camera component to your machine, searching for viamrtsp and selecting your desired model.

Copy and paste the following attributes template into the resulting component's attribute panel:

{
   "rtp_passthrough": true,
   "rtsp_address": "rtsp://foo:bar@192.168.10.10:554/stream"
}

Edit the attributes as applicable.

Attributes

The following attributes are available for all models of viamrtsp cameras:

Name	Type	Inclusion	Description
rtsp_address	string	Required	The RTSP address where the camera streams.
rtp_passthrough	bool	Optional	RTP passthrough mode (which improves video streaming efficiency) is supported with the H264 codec. It will be on by default. Set to false to disable H264 RTP passthrough. Default: true

Example configuration

{
  "components": [
    {
      "name": "your-rtsp-cam",
      "namespace": "rdk",
      "type": "camera",
      "model": "viam:viamrtsp:rtsp",
      "attributes": {
        "rtp_passthrough": true,
        "rtsp_address": "rtsp://foo:bar@192.168.10.10:554/stream"
      }
    }
  ],
  "modules": [
    {
      "type": "registry",
      "name": "viam_viamrtsp",
      "module_id": "viam:viamrtsp",
      "version": "latest"
    }
  ]
}

[!NOTE] The above is a raw JSON configuration for an rtsp model. To use another provided model, change the "model" string.

Configure the viamrtsp:onvif discovery service

This model is used to locate rtsp cameras on a network that utilize the onvif interface and surface their configuration.

Attributes

The following attributes are available for all models of viamrtsp discovery services:

Name	Type	Inclusion	Description
credentials	string	Optional	set the username and password for any amount of credentials.

Example configuration

{
   "credentials": [
    {
      "user": "<USERNAME1>",
      "pass": "<PASSWORD1>"
    },
    {
      "user": "<USERNAME2>",
      "pass": "<PASSWORD2>"
    },
   ]
}

Next steps

Use the DiscoverResources API by adding a viam:viamrtsp:onvif discovery model to retrieve a list of cameras discovered by the service and their configuration. Some cameras will output multiple channels, so review the rtsp_address of the cameras to determine which camera streams you wish to add.

Common RTSP discovery pitfalls

DHCP

IP camera does not support DHCP, and does not have an assigned IP after connecting to your LAN. In this case, you'll have to assign the camera's IP manually. This can be done through your router's web-based management interface. To find the IP address of your router's management interface, you can use the following command on Darwin systems:

netstat -nr | grep default

And the following command on Linux systems:

ip route | grep default

This will display the IP address of your default gateway, which is usually the IP address of your router. You can then access the router's management interface by typing this IP address in a web browser. Some router interfaces also allow you to find a camera using its MAC address or the specific Ethernet port it's connected to, and manually assign an IP address from there.

ONVIF adherence

Discovery relies on the IP camera adhering to the ONVIF Profile S standard, which includes methods such as getting device metadata, media profiles, and stream URIs. It will not work with non-existent or incompatible ONVIF camera integrations that do not meet this profile level.

ONVIF authentication

For some IP cameras, ONVIF authentication may be flaky or broken. A workaround is to disable the camera's ONVIF authentication temporarily to discover the RTSP address, then (optionally) re-enable the setting.

UPnP Host Discovery

If in your rtsp_address your hostname is UPNP_DISCOVER then we will try to find a UPnP host that matches. You can filter the results by fillong out the query field in the configuration. See viamupnp.DeviceQuery for supported filters.

Build for local development

The binary is statically linked with FFmpeg v6.1, eliminating the need to install FFmpeg separately on target machines.

We support building this module using the Makefile for the following host/target combinations:

Host	Target	Supported
Linux/Arm64	Linux/Arm64	✅
Linux/Arm64	Android/Arm64	❌
Linux/Amd64	Linux/Amd64	✅
Linux/Amd64	Android/Arm64	✅
Darwin/Arm64	Darwin/Arm64	✅
Darwin/Arm64	Android/Arm64	✅
Darwin/Amd64	Darwin/Amd64	❌
Darwin/Amd64	Android/Arm64	❌

• Build for Linux targets:
  • Install canon: go install github.com/viamrobotics/canon@latest
  • Startup canon dev container.
    • Linux/Arm64: canon -profile viam-rtsp-antique -arch arm64
    • Linux/Amd64: canon -profile viam-rtsp-antique -arch amd64
  • Build binary: make
• Build for MacOS target:
  • Build binary: make
• Build for Android target:
  • Cross-compile from Linux/Amd64 or Darwin/Arm64 host.
  • To build from Linux/Amd64 host:
    • Startup canon: canon -profile viam-rtsp-antique -arch amd64
    • Build binary: TARGET_OS=android TARGET_ARCH=arm64 make
  • To build from Darwin/Arm64 host:
    • Build binary: TARGET_OS=android TARGET_ARCH=arm64 make
• Binary will be in bin/<OS>-<CPU>/viamrtsp
• Clean up build artifacts: make clean
• Clean up all files not tracked in git: make clean-all

Notes

• Non fatal LibAV errors are suppressed unless the module is run in debug mode.
• Heavily cribbed from gortsplib examples:
  • H264 stream to JPEG
  • H265 stream to JPEG

Documentation

Overview

Package viamrtsp implements RTSP camera support in a Viam module

Index

• Constants
• Variables
• func H2645StartCode() []byte
• func NewRTSPCamera(ctx context.Context, _ resource.Dependencies, conf resource.Config, ...) (camera.Camera, error)
• func SetLibAVLogLevelFatal()
• type Config
  • func (conf *Config) Validate(path string) ([]string, error)

Constants

const (

	// Unknown indicates an error when no available video codecs could be identified
	Unknown videoCodec = iota
	// Agnostic indicates that a discrete video codec has yet to be identified
	Agnostic
	// H264 indicates the h264 video codec
	H264
	// H265 indicates the h265 video codec
	H265
	// MJPEG indicates the mjpeg video codec
	MJPEG
	// MPEG4 indicates the mpeg4 video codec
	MPEG4
)

Variables

var (
	// Family is the namespace family for the viamrtsp module.
	Family = resource.ModelNamespace("viam").WithFamily("viamrtsp")
	// ModelAgnostic selects the best available codec.
	ModelAgnostic = Family.WithModel("rtsp")
	// ModelH264 uses the h264 codec.
	ModelH264 = Family.WithModel("rtsp-h264")
	// ModelH265 uses the h265 codec.
	ModelH265 = Family.WithModel("rtsp-h265")
	// ModelMJPEG uses the mjpeg codec.
	ModelMJPEG = Family.WithModel("rtsp-mjpeg")
	// ModelMPEG4 uses the mpeg4 codec.
	ModelMPEG4 = Family.WithModel("rtsp-mpeg4")
	// Models is a slice containing the above available models.
	Models = []resource.Model{ModelAgnostic, ModelH264, ModelH265, ModelMJPEG, ModelMPEG4}
	// ErrH264PassthroughNotEnabled is an error indicating H264 passthrough is not enabled.
	ErrH264PassthroughNotEnabled = errors.New("H264 passthrough is not enabled")
)

Functions

func H2645StartCode

func H2645StartCode() []byte

H2645StartCode is the start code byte sequence for H264/H265 NALs.

func NewRTSPCamera

func NewRTSPCamera(ctx context.Context, _ resource.Dependencies, conf resource.Config, logger logging.Logger) (camera.Camera, error)

NewRTSPCamera creates a new rtsp camera from the config, that has to have a viamrtsp.Config.

func SetLibAVLogLevelFatal

func SetLibAVLogLevelFatal()

SetLibAVLogLevelFatal sets libav errors to fatal log level to cut down on log spam

Types

type Config

type Config struct {
	Address        string               `json:"rtsp_address"`
	RTPPassthrough *bool                `json:"rtp_passthrough"`
	Query          viamupnp.DeviceQuery `json:"query"`
}

Config are the config attributes for an RTSP camera model.

func (*Config) Validate

func (conf *Config) Validate(path string) ([]string, error)

Validate checks to see if the attributes of the model are valid.