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

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](https://github.com/marklagendijk/node-onvif-ptz-cli).

## 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](https://nodejs.org/).
    
2. **Install the CLI Tool**: Open a terminal and run the following command to install the tool globally:
    
    ```bash
    npm i -g onvif-ptz-cli
    ```
    
3. **Verify Installation**: Run the following command to check that the tool is installed correctly:
    
    ```bash
    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:
    
    ```bash
    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:
    
    ```bash
    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.

```bash
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.

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

#### `move`

Move the camera relative to its current position.

```bash
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.

```bash
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.

```bash
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](https://github.com/marklagendijk/node-onvif-ptz-cli).