Axis VAPIX (PTZ)

Pan/tilt/zoom control and preset recall for Axis network cameras and PTZ video encoders over the VAPIX HTTP API (/axis-cgi/com/ptz.cgi). One Axis PTZ camera or video encoder becomes one GEM device; on a multi-channel encoder, a per-command channel argument selects which channel moves.

This is a PTZ-focused shell of the full Axis VAPIX driver — it exposes only the movement and preset commands and is kept for upgrade safety on sites provisioned before the Axis drivers were merged. For a new install, use the Axis VAPIX driver instead: it does everything this one does plus snapshots, relay/door I/O, privacy masking, audio, and live events, and it is the driver Axis integrations should be built on going forward.

Communication is HTTP or HTTPS to the camera's web port (default 80) using digest authentication.

What this shell covers

• Directional jog — up / down / left / right nudge the camera a fixed step from its current position; zoom_in / zoom_out step the zoom.
• Stop — stop halts any in-progress movement.
• Presets — recall a stored camera preset by number (load_preset) and save the current position to a preset number (save_preset).
• Passthrough — send any raw VAPIX PTZ parameter the named commands don't expose.

What this shell does NOT cover

The command surface here is deliberately limited to movement and presets. For anything else on an Axis unit — JPEG snapshots, relay / door-strike I/O (one zone per output port), privacy masking, audio mute/gain, or the live event feed (motion, I/O, and intercom PIN / card / call-button events) — use the full Axis VAPIX driver, which documents all of it. There is no live video / RTSP streaming in any Axis driver either; wire the camera's stream up separately where GEM consumes video.

Prerequisites

• An Axis PTZ camera or PTZ-capable video encoder channel reachable on the LAN, with PTZ enabled on the target channel. Non-PTZ channels return a 4xx error for PTZ requests.
• A VAPIX account with at least Operator rights for movement and preset recall. Administrator rights are required to save a preset (save_preset) on most firmware.
• Digest authentication available on the account — modern AXIS OS firmware disables Basic auth by default, and this driver authenticates with digest.
• HTTP or HTTPS reachability from the GEM controller to the camera's web port.

Setup

1. Confirm PTZ works in the camera's own web UI first, and note the channel number if this is a multi-channel encoder (single cameras are channel 1).
2. In GEM, open Devices (System → Devices) and click Add Device.
3. Choose the Axis VAPIX (PTZ) driver. GEM shows the matching device fields and a View integration guide link to this page. (For a new deployment, pick Axis VAPIX instead — see above.)
4. Fill in the device attributes below and Save.
5. There is no zone to create for PTZ — the camera channel, not a zone address, is what each command targets. Send a left or right from the Commands page (or a quick test macro) to confirm the camera moves.

Subsystem placement

The driver hints the Security subsystem, so the New Zone editor pre-selects Security if you do create a zone. A stock GEM install also seeds a Cameras subsystem, which is the natural home for a PTZ camera. Either is fine — PTZ commands ignore the zone, so the subsystem only affects grouping.

Device attributes

Attribute	Required	Default	Description
ip	yes	—	LAN IP or hostname of the camera / encoder.
username	yes	—	VAPIX account (Operator rights; Administrator to save presets).
password	yes	—	VAPIX account password. Stored encrypted.
port	no	80	Camera web port.
protocol	no	http	http or https. Switch to https if the camera requires TLS.

Commands

Every command takes an optional channel argument that selects the video channel on a multi-channel encoder — it maps to the VAPIX camera parameter and defaults to 1 when left blank. Single cameras always use 1.

Command	Args	What it does
up	channel	Tilts up a fixed step from the current position.
down	channel	Tilts down a fixed step.
left	channel	Pans left a fixed step.
right	channel	Pans right a fixed step.
zoom_in	channel	Zooms in a fixed step.
zoom_out	channel	Zooms out a fixed step.
stop	channel	Halts any in-progress pan / tilt / zoom motion.
load_preset	preset, channel	Recalls the stored camera preset with the given number.
save_preset	preset, channel	Saves the current position to the given preset number (Administrator only).
passthrough	action, value, channel	Sends a raw VAPIX PTZ parameter — action is the parameter name, value its value. Examples: action = continuouspantiltmove, value = 30,0 for a joystick move; action = gotoserverpresetname, value = Entrance to recall a named preset.

How the jog commands work

up / down / left / right and zoom_in / zoom_out are relative moves — each press nudges the camera a fixed amount from where it is now and then stops (5 units of pan or tilt, 100 units of zoom), rather than running continuously. That makes them ideal for a d-pad or touchpanel button: tap to step, tap again to step again. Because each step self-terminates, you rarely need stop for these — stop is there mainly to halt a continuous move you started with passthrough (for example a continuouspantiltmove).

To move farther per press, or for continuous "hold to move" joystick control, use passthrough with the VAPIX parameter you want, or switch to the full Axis VAPIX driver — its pan / tilt / zoom and continuous_move commands expose absolute positioning, speed, and joystick moves directly.

Presets

load_preset and save_preset work with numbered camera presets (the camera's server-preset slots). Position the camera first — with the jog commands or the camera's own web UI — then save_preset with a number to store it; afterwards load_preset with the same number recalls it. Saving a preset typically requires an Administrator account, so if load_preset works but save_preset fails, that privilege is the usual cause. To recall a preset by name instead of number, use passthrough with action = gotoserverpresetname and value set to the preset name.

Running PTZ from automation

Because PTZ targets the device and a channel rather than a zone, you drive it entirely with commands:

• Commands page — pick the device and a command, set channel if needed, and run it to test. See Commands.
• Macros — a macro can string moves, delays, and preset recalls together (for example "recall preset 1, wait, recall preset 2" for a simple patrol).
• Triggers — an attribute trigger can recall a preset when something else changes, such as jumping the camera to a door preset when a door contact opens.

Troubleshooting

Symptom	Check
Commands return 401 Unauthorized	The VAPIX account lacks Operator rights, or digest auth failed (wrong password, or a Basic-only account on firmware that requires digest). Re-enter the username/password on the device.
save_preset fails but load_preset works	Saving a server preset requires an Administrator account. Use a higher-privileged account, or save presets in the camera's web UI and recall them by number.
Commands hit the wrong channel on a multi-channel encoder	Pass the explicit channel argument — it defaults to 1.
PTZ returns a 4xx on a channel that should move	That channel isn't PTZ-capable. Confirm PTZ is enabled for it in the camera's web UI.
You need snapshots, relays, privacy masks, audio, or live events	Those aren't in this shell — add the camera with the full Axis VAPIX driver, which covers them.

Related documentation

• Axis VAPIX — the full Axis driver this shell is a subset of; use it for new installs and for snapshots, relay I/O, privacy, audio, and live events.
• Devices — adding and configuring the camera device row.
• Subsystems — the Cameras / Security subsystem the device is organized under.
• Commands — running these PTZ commands from the admin UI, macros, and scenes.
• Macros — sequencing moves, delays, and preset recalls (patrol patterns).
• Triggers — recalling presets in response to other events.
• Amcrest PTZ — the equivalent PTZ-only control driver for Amcrest / Dahua-OEM cameras.
• ONVIF — the vendor-neutral camera integration for motion and event ingestion.