PTZ Axis
Map gamepad or joystick analog input to continuous ONVIF PTZ camera movement. The camera moves proportionally to stick deflection, with dead-zone filtering and per-axis inversion for smooth manual control. Keeps moving while the stick is held and stops automatically when the stick returns to neutral.
Smooth PTZ control from a gamepad
PTZ Axis binds a physical gamepad or joystick to continuous ONVIF pan, tilt, and zoom. Unlike the discrete PTZ action that fires fixed-speed commands, this action continuously reads analog stick position and sends proportional speed commands â giving the operator the feel of direct physical control over the camera.
The action is designed for high-frequency controller input. Each axis event from the gamepad is processed and mapped to an ONVIF speed command, filtered by a configurable dead zone to prevent drift from a controller at rest. A watchdog timer sends a stop command if controller events stop arriving.
Bind a gamepad to a PTZ camera
Set up the Gamepad State Controller
Add and start a Gamepad State Controller for the physical controller. Confirm the controller is detected and that axis events are visible in the event log.
Identify axis indexes
Move each physical stick/trigger and observe which axis index changes in the controller events. Note which index controls left/right (X), up/down (Y), and zoom. This depends on the controller model and driver.
Create PTZ Axis action
Click + next to PTZ Axis under the Actions sub-menu. Choose the target camera from Device and enter the Gamepad identifier matching your controller.
Map axes
Set X axis index, Y axis index, and Zoom axis index to match the physical controller layout identified in step 2.
Calibrate dead zone
Start with Stop threshold at 0.1. If the camera slowly drifts when the stick is at rest, increase the threshold. If fine slow movements are not registering, decrease it.
Invert axes if needed
Enable Reverse X, Reverse Y, or Reverse Zoom if the physical movement direction feels inverted. Test with the live camera to confirm the correct orientation.
Configuration parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
Restart on failure |
Yes | Restart behavior after an error:
|
10 sec |
Title |
Yes | Descriptive label for this action instance. Helps identify which camera and controller are bound, for example PTZ Axis â Entrance Camera. |
â |
Device |
Yes | The PTZ-capable ONVIF camera to control. Avoid running multiple PTZ Axis actions for the same camera simultaneously â competing axis streams can cause unstable, unpredictable camera movement. Select the target ONVIF Camera. | â |
Gamepad |
Yes | Identifier of the physical controller whose axis events should drive PTZ. Events from other controllers are ignored. Useful when multiple controllers are connected to one workstation or when different operators control different cameras. | â |
Stop threshold |
Yes | Dead zone around the neutral stick position. Axis values within this range are treated as zero â no PTZ command is sent. Range: -1 to 1. Increase when the camera drifts at rest; decrease for very fine slow movement control on a stable joystick. |
0.1 |
X axis index |
Yes | Gamepad axis index that controls horizontal camera pan. Range: 0â128. Identify the correct index by moving the physical stick and observing which axis index changes in the controller event stream. | 0 |
Y axis index |
Yes | Gamepad axis index that controls vertical camera tilt. Range: 0â128. Use a different index from X axis index. On most gamepads, the left stick uses indexes 0 (X) and 1 (Y). | 1 |
Zoom axis index |
Yes | Gamepad axis index that controls optical zoom speed. Range: 0â128. Can map to a trigger, slider, secondary stick axis, or any other analog axis. Set to an unused or neutral axis to disable gamepad zoom control. | 2 |
Reverse X |
Optional | Invert the pan direction. Enable when pushing the stick right moves the camera left (or vice versa). Eliminates the need to swap hardware connections or configure the driver. | false |
Reverse Y |
Optional | Invert the tilt direction. Enable when pushing the stick up moves the camera down (or vice versa). Common on cameras and controllers that use different up/down conventions. | false |
Reverse zoom |
Optional | Invert the zoom direction. Enable when pulling the zoom trigger zooms the camera out instead of in, or when the trigger reports inverted values. | false |
Stop timeout |
Yes | Watchdog timeout in milliseconds. Every matching gamepad axis event extends the movement window. If controller events stop arriving for this duration, the action sends a PTZ stop command. Keep short for responsive control. Range: 100â1000 ms. | 300 |
Recommended profiles
Standard joystick PTZ
Map pan and tilt to the main stick (indexes 0 and 1), zoom to a trigger or secondary stick. Keep Stop threshold at 0.1 and use the default Stop timeout for responsive manual control.
Precise indoor tracking
Lower Stop threshold to 0.05â0.08 on a stable joystick. Use reversals only after checking the real movement direction on the camera. Useful for following people or objects at short range in a corridor or room.
Outdoor or long-range camera
Raise Stop threshold to 0.15â0.25 to prevent slow drift from a worn controller. Small unintended movements are much more visible at high zoom levels outdoors.
Zoom-only control
Set X axis index and Y axis index to unused or neutral axes. Map Zoom axis index to the preferred trigger or slider. Use when camera direction is controlled by presets but the operator still needs manual zoom adjustment.
Noisy or worn controller
Increase Stop threshold and keep Stop timeout short. This filters axis noise at rest and ensures the camera stops quickly if the controller disconnects or events stop flowing.