VISCA over IP PTZ Camera

VISCA is Sony's pan/tilt/zoom camera control protocol, originally a daisy-chain RS-232 standard and now widely implemented over UDP/IP as VISCA over IP on UDP port 52381. One VISCA-IP driver covers most commercial PTZ cameras used in conference rooms, classrooms, courtrooms, lecture halls, churches and broadcast B-roll rigs:

• Sony BRC / SRG / FR-series
• PTZOptics Move / Studio / SE / G2 / G3
• Vaddio RoboSHOT / ConferenceSHOT / OneLINK
• Lumens VC-A / VC-B / VC-TR series
• Marshall CV / CVM PTZ cameras
• BirdDog (VISCA control path)
• Aver CAM5xx / PTC series
• Most other "VISCA-compatible" commercial PTZs

The driver does not handle video — pair it with an RTSP/NDI/HDMI feed from the same camera through the appropriate AV path. It handles power, pan/tilt with speed, zoom, focus (auto and manual), presets, backlight compensation, auto white-balance, the camera's IR-remote receiver, and read-back of power, zoom and PTZ position.

Prerequisites

• The camera supports VISCA over IP in UDP mode. Most PTZOptics, Vaddio, Lumens, Marshall and Sony commercial PTZs do — check the camera menu for the setting (usually under Network or Camera Settings).
• The camera's IP is reachable from the GEM controller on UDP port 52381 (no firewall block).
• IR-remote control is not exclusive: VISCA-IP control works alongside the IR remote on most models, but a few firmwares disable IP control if the IR receiver is on — check the camera menu if commands silently fail.

Setup steps

1. In the camera network menu, assign a static IP / DHCP reservation and enable VISCA over IP in UDP mode.
2. In GEM, go to System → Devices → Add Device and pick the VISCA over IP PTZ Camera driver (visca_ip).
3. Enter the camera's IP. Leave the port on 52381 unless the camera documents otherwise.
4. (Optional) Set default_pan_speed and default_tilt_speed if the defaults (9) move the camera faster/slower than you want.
5. Save. The driver sends a VISCA-IP sequence-reset and immediately reads power state (the same query the get_power command runs) to confirm the camera is reachable. Run get_power again any time to re-check the link.
6. To save framing: pan/tilt/zoom into position, then run preset_save with a preset number. The command picker offers slots 0–15 (the universally safe range); cameras that support more accept higher numbers when typed.

Attribute reference

Required

Attribute	Type	Description
ip	string	LAN IP or hostname of the camera.

Optional

Attribute	Type	Default	Description
port	int	52381	VISCA-IP UDP port.
default_pan_speed	int (1–24)	9	Pan speed when pan_left/pan_right is called without a speed arg.
default_tilt_speed	int (1–23)	9	Tilt speed when tilt_up/tilt_down is called without a speed arg.
status_interval	int (ms)	60000	How often the driver polls power and zoom.
request_timeout	int (ms)	1500	Per-command timeout waiting for completion.

Surfaced by the driver (read-only)

Attribute	Source	Meaning
power_state	status poll / get_power	on / off.
zoom_position	status poll / get_zoom	VISCA zoom position: 0 (full wide) up to roughly 16384 (full tele). The exact top-end varies by model — treat it as a relative indicator.

The status poll (every status_interval, default 60 s) only refreshes power_state and zoom_position. Pan/tilt position is not polled — read it on demand with get_position, which returns {pan_position, tilt_position} as 16-bit signed integers per call (not stored as a device attribute).

Zones

VISCA-IP is device-level — no GEM zones. Power, motion, zoom, focus, and presets all target the camera as a whole. Drive the camera from macros, triggers, scene buttons, or the Commands grid's Test runner — there are no per-zone controls.

Commands

Power

Command	Args	What it does
power_on	—	Wake the camera.
power_off	—	Put the camera in standby.
get_power	—	Read power state; returns on / off. Use it to confirm the camera is reachable.

Pan / tilt

Command	Args	What it does
pan_left	speed (1–24), tilt_speed (1–23)	Start panning left. Keeps moving until you send a stop.
pan_right	speed, tilt_speed	Start panning right.
tilt_up	speed (1–23), pan_speed (1–24)	Start tilting up.
tilt_down	speed, pan_speed	Start tilting down.
pan_tilt_stop	—	Stop any active pan/tilt motion.
stop	—	Alias for pan_tilt_stop.
home	—	Drive pan/tilt to the camera's home position.
reset_ptz	—	Recenter pan/tilt and clear mechanical drift.
get_position	—	Read current pan and tilt; returns pan_position / tilt_position (16-bit signed, per-call only — not stored).

VISCA drives pan and tilt in a single packet, so each direction command carries both a primary and a cross-axis speed: pan_left / pan_right accept an optional tilt_speed, and tilt_up / tilt_down accept an optional pan_speed. Omit them and the device defaults (default_pan_speed / default_tilt_speed) are used.

Zoom and focus

Command	Args	What it does
zoom_in	speed (0–7, default 4)	Variable-speed zoom toward tele. Keeps zooming until stopped.
zoom_out	speed (0–7, default 4)	Variable-speed zoom toward wide.
zoom_stop	—	Stop any active zoom.
get_zoom	—	Read the current zoom position.
focus_auto	—	Enable auto-focus.
focus_manual	—	Switch to manual focus.
focus_near	—	Drive manual focus nearer (open-ended; focus_stop to halt).
focus_far	—	Drive manual focus farther.
focus_stop	—	Stop active focus motion.

Preset control

Command	Args	What it does
preset_save	preset	Store the current PTZ position in a preset slot.
preset_recall	preset	Move to a stored preset.
preset_delete	preset	Clear a preset slot.

The preset picker offers slots 0–15 in the command UI, but the driver accepts numbers up to 127 when you type a higher value on a camera that supports it — see Presets below for real-world ranges.

Image and IR remote

Command	Args	What it does
backlight_on	—	Backlight compensation on.
backlight_off	—	Backlight compensation off.
wb_auto	—	White balance to auto.
ir_on	—	Enable the camera's IR-remote receiver.
ir_off	—	Disable the IR-remote receiver — needed on cameras that lock out IP control while the IR receiver is active.

Pan / tilt / zoom semantics

VISCA pan/tilt commands are open-ended: pan_left (or any direction) starts the motor and it keeps moving until you send stop. This matches how AV control surfaces and joystick consoles drive PTZ cameras and is intentional. The driver does not auto-stop on a timeout — your macro, joystick, or UI must send stop.

zoom_in / zoom_out are also open-ended; use zoom_stop to halt.

Pan speeds are 1–24, tilt speeds are 1–23 per the VISCA spec. Zoom variable speed is 0–7 (0 slowest, 7 fastest; defaults to 4 when no speed is given).

Presets

preset_save / preset_recall / preset_delete take a preset arg in the range 0–127 per the VISCA spec, but real-world camera support is narrower:

• All cameras: 0–9.
• Most commercial PTZs (PTZOptics, Vaddio, Sony): 0–127.
• A few older Lumens / Marshall: 0–15.

If preset_recall returns an error for a high number, drop to a lower preset.

Known limitations / not yet supported

• Read-back of currently-selected preset (CAM_MemoryInq) is not exposed.
• Image-control inquiries (iris, gain, shutter, exposure) are not exposed. This is camera-specific anyway — many cameras override the standard VISCA exposure layout.
• VISCA-IP TCP mode is not supported. Configure the camera for UDP mode.
• VISCA daisy-chain addressing (cameras 2–7) is not supported — the driver always targets address 0x81. Most over-IP installs are one camera per IP.
• Class 2 VISCA extensions like CAM_Color, CAM_ColorEnhancement, and CAM_AutoTracking are not exposed.

Troubleshooting

Symptom	Likely cause
Every command times out	Camera is set to TCP-mode VISCA-IP, not UDP. Switch the camera to UDP mode.
Commands succeed but the camera does not move	Camera is in IR-only or local-only mode. Re-check the camera menu; on some PTZs ir_off is required before IP commands take effect.
preset_recall returns command not executable	Preset number exceeds what the camera supports. Drop to 0–9 and re-test.
pan_left works but pan_right does not respond	An earlier command left the camera moving. Send stop first.
Status sometimes lags by a few seconds	UDP packet was lost. The next status poll catches up. To reduce drift, lower status_interval.
Zoom inquiry returns a value but the slider is wrong scale	Camera's zoom range is not exactly 0–16384. Use zoom_position as a relative indicator; absolute scale varies by model.

Related documentation

• Devices — add and configure the camera.
• Commands — the command grid and Test runner for the PTZ, zoom, focus and preset commands above.
• Device Health — connection status and reachability for the camera device.
• Subsystems — the subsystem the camera device belongs to.