Amcrest PTZ Cameras

Pan/tilt/zoom control for Amcrest cameras over the camera's CGI PTZ API (/cgi-bin/ptz.cgi). One camera becomes one GEM device. This driver moves the camera — continuous pan and tilt with an automatic stop, continuous zoom, and preset recall/save — plus a raw passthrough for any PTZ code the named commands don't cover.

Amcrest is Dahua's North-American consumer brand, and the CGI PTZ API is shared, so many rebadged Dahua-OEM PTZ cameras respond to this driver as well.

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

What this driver covers

• Pan / tilt — up / down / left / right continuous moves that automatically stop after a short interval (extendable), plus a manual stop.
• Zoom — continuous zoom_in / zoom_out.
• Presets — recall a stored PTZ preset (load_preset) and store the current position as a preset (save_preset).
• Passthrough — send any raw Amcrest/Dahua PTZ code (Iris, focus, diagonal moves, …) the named commands don't expose.

What this driver does NOT cover

• No live video or RTSP streaming. This driver only moves the camera; wire the camera's RTSP/HTTP stream up separately where GEM consumes camera video.
• No snapshots. There is no still-image command here.
• No motion / event feedback and no status telemetry. The driver sends PTZ commands and reads nothing back, so the camera reports no position, motion, or alarm state to GEM. For live events on an Amcrest/Dahua-OEM camera, add a second device on the same camera using the Dahua (RPC2) driver, or integrate the camera over ONVIF.
• No zones. PTZ commands target the camera's channel argument, not a GEM zone — so you add this as a device only and drive it with commands (see Running PTZ from automation).

Prerequisites

• An Amcrest (or Dahua-OEM) PTZ camera reachable on the LAN whose web interface exposes the CGI PTZ API.
• A camera account with PTZ control privileges. On the camera web UI this lives under Setup → System → Account; a view-only account will move nothing and returns 401 Unauthorized.
• HTTP reachability from the GEM controller to the camera's web port (default 80).

Setup

1. Confirm the camera is reachable from GEM and that PTZ works in the camera's own web UI first.
2. Open Devices (System → Devices) and click Add Device.
3. Choose the Amcrest PTZ driver. GEM shows the matching device fields and a View integration guide link to this page.
4. Fill in the device attributes below and Save. Place the device in whichever subsystem you use to organize cameras — Cameras or Security both work; because this driver has no zones, the subsystem is only for organization.
5. There is no zone to create. Send a left or right command from the Commands page (or a quick test macro) to confirm the camera moves.

Device attributes

Attribute	Required	Default	Description
ip	yes	—	LAN IP or hostname of the camera.
username	yes	—	Camera account with PTZ control privileges.
password	yes	—	Camera account password. Stored encrypted.
port	no	80	Camera web (HTTP) port.

This driver talks HTTP only — it does not use HTTPS for the PTZ API, so leave the camera's HTTP interface enabled on the port above.

Commands

Command	Args	Notes
up / down / left / right	channel, speed	Continuous move that auto-stops after ~300 ms. Add a duration arg (milliseconds) to hold the move longer.
stop	channel, code	Manually stop a move or zoom. code is the motion being stopped — Up/Down/Left/Right for pan-tilt, ZoomTele/ZoomWide for zoom.
zoom_in	channel, factor	Continuous zoom in (tele). Does not auto-stop — see Zoom is continuous.
zoom_out	channel, factor	Continuous zoom out (wide). Does not auto-stop.
load_preset	channel, preset	Move to a stored preset. The picker lists 1–6; higher numbers up to 255 work on cameras that support them.
save_preset	channel, preset	Store the camera's current position as the given preset number.
passthrough	channel, code, arg_1…arg_4	Send a raw PTZ request. Set action to start or stop, code to any Amcrest/Dahua PTZ code (e.g. Iris, FocusFar, FocusNear, LeftUp, RightDown), and the four numeric arguments as the code requires.

Argument reference:

• channel — camera channel. Defaults to 1 if you leave it blank; single cameras use 1, and a multi-sensor / NVR channel uses its channel number.
• speed — pan/tilt speed 1–8 (1 = slow and precise, 8 = fast). Defaults to 3 if blank.
• factor — zoom rate; vendor-specific, typically 1–8.
• duration — optional, milliseconds. Only the pan/tilt commands use it, to override the ~300 ms auto-stop.

How pan and tilt work

A left/right/up/down command tells the camera to start moving, waits ~300 ms, then automatically sends the matching stop. That short pulse is what makes a single button press "nudge" the camera rather than run it to the mechanical limit. To move farther in one command, add a duration arg in milliseconds (for example duration = 1500 for a longer sweep); the driver waits that long before issuing the stop.

If the network drops the follow-up stop, the camera can keep panning. On an unreliable link, raise duration and confirm the camera actually receives the stop, or send an explicit stop (with the matching code) afterward.

Zoom is continuous

Unlike pan and tilt, zoom_in and zoom_out do not auto-stop — they start the zoom and leave it running. To zoom by a controlled amount, follow the zoom command with a stop whose code is ZoomTele (for zoom_in) or ZoomWide (for zoom_out). The simplest way to do this is a two-step macro: the zoom command, a short Delay step (e.g. 500 ms), then the stop. Without a stop the camera zooms to its limit.

Presets

Store presets first: position the camera (using the move commands or the camera's own web UI), then run save_preset with a preset number. Afterward, load_preset with the same number recalls that position. The command picker offers preset numbers 1–6; cameras that support more accept numbers up to 255.

Running PTZ from automation

Because this driver has no zones, you drive it entirely with commands:

• Commands page — pick the device and a command, fill in the args, and run it to test. See Commands.
• Macros — a macro can string moves, delays, and a stop together (the standard pattern for a controlled zoom or a "sweep then return to preset 1" sequence).
• Triggers — an attribute trigger can recall a preset when something else changes (for example, jump a PTZ camera to a door preset when a door contact opens).

Troubleshooting

Symptom	Check
Commands return 401 Unauthorized	The account needs PTZ control rights. Confirm under Setup → System → Account on the camera web UI, and re-enter the username/password on the device.
Camera moves but never stops	The follow-up stop didn't reach the camera. On a lossy link, raise the duration arg and/or send an explicit stop with the matching code.
Zoom runs to the limit	Zoom is continuous — it has no auto-stop. Follow zoom_in/zoom_out with a stop (code ZoomTele/ZoomWide), ideally via a macro with a short delay in between.
Presets do nothing	Save the preset on the camera first with save_preset (or in the camera web UI), then load_preset will recall it. Preset numbers are 1–255 depending on the model.
The camera has no live video or motion in GEM	This driver is control-only. Use GEM's camera streaming for video, and add the Dahua (RPC2) driver or an ONVIF integration as a second device for motion/alarm events.

Related documentation

• 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 a stop (the pattern for controlled zoom).
• Triggers — recalling presets in response to other events.
• Dahua (RPC2) — the event/monitoring integration for the same camera hardware (Amcrest is Dahua's consumer brand); pair it with this driver for motion, alarm, and door-station events.
• Axis VAPIX — the PTZ + I/O integration for Axis cameras, the equivalent on that brand.
• ONVIF — the vendor-neutral camera integration for motion and event ingestion.