Career Journal

Node.js CLI Tool for Controlling PTZ Cameras via the ONVIF Protocol

Node.js CLI Tool for Controlling PTZ Cameras via the ONVIF Protocol

Gedion Daniel's photo
Gedion Daniel
·

4 min read

Controlling Pan-Tilt-Zoom (PTZ) cameras efficiently is crucial for effective surveillance and monitoring systems. The node-onvif-ptz-cli tool offers a robust command-line interface to control PTZ cameras using the ONVIF protocol, a widely adopted standard for ensuring compatibility across IP-based security products. This article explores how to use the node-onvif-ptz-cli tool to streamline camera management tasks. The tool is open-source and available on GitHub.

Overview of the node-onvif-ptz-cli Tool

The node-onvif-ptz-cli is a Node.js-based command-line tool that allows users to control PTZ cameras via the ONVIF protocol. It provides a range of commands for moving cameras, managing presets, and adjusting camera settings directly from the terminal. With support for both Node.js and Docker, the tool is versatile and can be easily integrated into various systems.

Key Features

  • Platform Compatibility: The tool is cross-platform and can run on Windows, macOS, Linux, and even Raspberry Pi devices.

  • Comprehensive Commands: It offers a wide array of commands to control camera movement and manage presets.

  • Environment Variable Support: Users can set environment variables to store credentials and URLs, reducing the need for repetitive input.

  • Docker Support: The tool is available as a Docker image, making deployment and execution straightforward across different environments.

Installation and Setup

Installing via NPM

To get started with the node-onvif-ptz-cli tool, you'll need Node.js 18.x or higher installed on your system. Follow these steps to install the tool using npm:

  1. Install Node.js: Download and install Node.js 18.x or higher from the official Node.js website.

  2. Install the CLI Tool: Open a terminal and run the following command to install the tool globally:

     npm i -g onvif-ptz-cli

  3. Verify Installation: Run the following command to check that the tool is installed correctly:

     onvif-ptz --help

    This command will display the tool's documentation and available commands.

Running via Docker

The node-onvif-ptz-cli tool is also available as a Docker image, which can be useful for environments where Docker is preferred or required. Follow these steps to run the tool using Docker:

  1. Pull the Docker Image: Use the following command to pull the Docker image:

     sudo docker pull marklagendijk/onvif-ptz-cli

  2. Run the Docker Container: Execute the following command to run a specific command within the Docker container:

     sudo docker run \
 --name onvif-ptz \
 --rm \
 marklagendijk/onvif-ptz-cli goto-preset \
 --baseUrl=http://192.168.0.123 \
 -u=admin \
 -p=admin \
 --preset=1

    Replace the baseUrl, username, password, and preset values with those specific to your camera.

CLI Documentation

The node-onvif-ptz-cli tool provides several commands to control PTZ cameras. Below is a detailed overview of the available commands and their options:

Common Options

  • --help: Show help information for the command.

  • --version: Display the tool's version number.

  • --baseUrl: The base URL of the camera (required).

  • --path: The ONVIF path of the camera (default: /onvif/device_service).

  • --username, -u: The username for accessing the camera (required).

  • --password, -p: The password for accessing the camera (required).

Commands

goto-preset

Move the camera to a specific preset.

onvif-ptz goto-preset \
--baseUrl=http://192.168.0.123 \
-u=admin \
-p=admin \
--preset=1
  • --preset: The preset number to load (required).

goto-home

Move the camera to the home position.

onvif-ptz goto-home \
--baseUrl=http://192.168.0.123 \
-u=admin \
-p=admin

move

Move the camera relative to its current position.

onvif-ptz move \
--baseUrl=http://192.168.0.123:8080 \
-u=admin \
-p=admin \
-x=0.01 \
-y=0.02 \
-z=0.03

  • -x: Movement on the x-axis. Range: -1 (left) to 1 (right). Optionally add :NUMBER for speed.

  • -y: Movement on the y-axis. Range: -1 (down) to 1 (up). Optionally add :NUMBER for speed.

  • -z: Movement on the z-axis (zoom). Range: -1 (zoom out) to 1 (zoom in). Optionally add :NUMBER for speed.

get-presets

List all available camera presets.

onvif-ptz get-presets \
--baseUrl=http://192.168.0.123 \
-u=admin \
-p=admin

set-preset

Store the current camera position and settings in a preset.

onvif-ptz set-preset \
--baseUrl=http://192.168.0.123 \
-u=admin \
-p=admin \
--preset=1 \
--name=Overview

  • --preset: The token of the preset, usually a number (required).

  • --name: The name of the preset (required).

Environment Variables

The node-onvif-ptz-cli tool allows users to set environment variables for convenience, particularly useful for specifying the camera's URL and credentials:

  • ONVIF_BASE_URL: The base URL of the camera.

  • ONVIF_USERNAME: The username for accessing the camera.

  • ONVIF_PASSWORD: The password for accessing the camera.

These variables reduce the need to repeatedly input credentials and URLs for each command, streamlining the user experience.

Conclusion

The node-onvif-ptz-cli tool provides a powerful and flexible solution for controlling PTZ cameras via the ONVIF protocol. Whether you are managing a single camera or an extensive surveillance network, this tool offers the functionality needed to automate and simplify camera control tasks. Its compatibility with various platforms and support for Docker makes it an excellent choice for both developers and system administrators looking to integrate PTZ camera control into their workflows. You can access the tool and contribute to its development on GitHub.

ptzNode.jsnpmcliJavaScriptonvif