Hanwha Vision (Wisenet / SUNAPI)

Controls Hanwha Vision (Wisenet, formerly Samsung Techwin) IP cameras, PTZ domes and NVRs over SUNAPI, Hanwha's published CGI integration interface. Provides JPEG snapshots, continuous and absolute PTZ, preset recall, channel enumeration and polled motion state per channel.

Driver name: hanwha_wisenet

Prerequisites

• A device account with Operator privilege or higher. PTZ is a separate permission from viewing — an account that can pull snapshots may still be refused PTZ with a 403.
• The initial password change must be completed. Wisenet firmware forces a password change on first login through the web viewer. Until that is done, SUNAPI answers 401 for every request even when the credentials are correct. This is the single most common setup failure.
• SUNAPI must be enabled. It is on by default across the Wisenet X, P, Q and A series. Hardened sites sometimes disable it under the Open Platform / API settings.
• Network reachability on the HTTP or HTTPS port. Default 80. If the device has "HTTPS (secure connection only)" set in Setup > Network > HTTPS, use scheme: https and port 443.

Setup steps

1. Go to /admin/devices and add a device with driver hanwha_wisenet.
2. Fill in ip, username and password. If the device forces HTTPS, also set scheme to https and port to 443.
3. Run the get_device_info command. A successful response returns the model, firmware version and device type, and confirms both credentials and transport. The driver also writes model, firmware_version and device_type onto the device row at connect.
4. Run get_channels. The driver probes channel indexes upward from 0 and reports which ones answered, along with the video profile each returned. Use this to decide how many zones to create.
5. Create one zone per channel you want to control or watch. Set zone.address to the SUNAPI channel index — see Zone address format below.

Channel numbering is 0-based

SUNAPI channel indexes start at 0, while the Wisenet web viewer and ONVIF both number the same channels starting at 1. Camera 1 in the web UI is zone.address = "0" here. Getting this wrong is silent — commands land on the neighbouring channel.

Attribute reference

Device — required

Attribute	Type	Description
ip	string	LAN IP or hostname of the camera or NVR.
username	string	Device account used for SUNAPI calls.
password	string	Password for that account. Stored encrypted.

Device — optional

Attribute	Type	Default	Description
port	int	80	HTTP/HTTPS port serving SUNAPI.
scheme	string	http	http or https. Self-signed certificates are accepted.
auth_mode	string	digest	digest or basic. Only use basic when the 401 challenge advertises Basic.
max_channels	int	16	Upper bound for get_channels probing. Each probe is one HTTP request.
status_interval	int	5000	Poll period in ms for event status and liveness.
request_timeout	int	10000	Per-request HTTP timeout in ms.

Zone attributes written by the driver

Attribute	Type	Values
state	string	motion / clear
motion	int	1 / 0

Zone address format

zone.address is the 0-based SUNAPI channel index, as a plain integer string.

Device	Addresses
Standalone camera or PTZ dome	0
4-channel NVR	0, 1, 2, 3
16-channel NVR	0 … 15

Run get_channels if you are unsure which indexes are live — an index that is not installed and an index the account lacks rights to both fail the same way.

Commands

Command	Arguments	Notes
snapshot	address	Returns base64-encoded JPEG at the channel's configured resolution.
ptz_pan_tilt	address, pan, tilt	Continuous move, each -100..100. Runs until stopped.
ptz_zoom	address, zoom	Continuous zoom, -100..100. Runs until stopped.
ptz_absolute	address, pan, tilt, zoom	Pan 0-360°, tilt -90..90°, zoom as optical factor.
ptz_stop	address	Stops all motion on the channel.
ptz_preset	address, preset	Recall preset 1-255.
get_status	address	Cached motion state plus the raw event payload.
get_event_status	—	Raw SUNAPI event status for all channels.
get_channels	—	Probe and report responding channel indexes.
get_device_info	—	Model, firmware, device type.
set_alarm_output	output, state	Not implemented — returns an error. See below.

Continuous PTZ does not self-stop

ptz_pan_tilt and ptz_zoom keep the dome moving until ptz_stop is issued. Some models apply their own safety timeout, most do not. Always pair a continuous move with a stop — in a macro, in the UI control, or on button release.

Known limitations

These are deliberate gaps in this driver, not device limitations:

• Alarm output (relay) control is not implemented. set_alarm_output returns not yet implemented. The SUNAPI wire format for relay control could not be verified when this driver was written, and guessing at it risked firing the wrong output on a device wired to a door strike or gate. Use a control_by_web or generic_relay device for dry contacts until this is confirmed against hardware.
• No event streaming. State is polled at status_interval, so motion carries up to one poll interval of latency. There is no push subscription wired.
• PTZ preset recall is unverified on current firmware. SUNAPI revisions have used more than one parameter name for the preset index. The driver sends the documented form. Confirm presets move the dome before wiring them into macros — a firmware that does not recognise the parameter answers 200 without moving.
• Snapshot size is not negotiable. The driver requests the channel snapshot without a size parameter, because not every model accepts one. Change the resolution on the device if the image is too large or small.
• No recording, playback or export control. Live control and state only.

Response format varies by firmware

SUNAPI answers with JSON on newer firmware and newline-delimited key=value text on older Samsung Techwin-era devices. The driver parses both and returns whichever structure the device produced, so the exact shape of get_device_info and get_event_status output differs between devices. Anything reading those responses in a macro should tolerate both.

Motion extraction is written the same way — it matches any key naming a motion event on the requested channel rather than assuming one schema. If a device is detecting motion but the zone never leaves clear, run get_event_status and read the raw payload; the firmware may be using an event name the driver has not seen.

Troubleshooting

Symptom	Check
Every call returns 401	Log into the web viewer with this account and complete the forced password change. SUNAPI rejects accounts still in that state.
401 persists with correct credentials	Set auth_mode to basic. Pre-SUNAPI-2.0 firmware may advertise Basic only.
get_channels finds only channel 0 on an NVR	Raise max_channels, and confirm the account has viewing rights on the other channels — an unprivileged channel is indistinguishable from an absent one.
PTZ returns 403 but snapshots work	PTZ is granted separately from Operator privilege under Setup > User.
Motion never changes	Confirm motion detection is enabled per channel on the device, then inspect get_event_status output.
Works on http, fails on https	Expected on devices whose self-signed certificate regenerates on reboot — the driver tolerates self-signed. If it still fails, confirm which port HTTPS is actually bound to.
Commands land on the wrong camera	Channel indexes are 0-based here and 1-based in the web viewer. Subtract one.

Related

• ONVIF — Hanwha devices also speak ONVIF Profile S/T. Use the onvif driver when you want vendor-neutral discovery and streaming; use this driver when you want Hanwha-specific control and event state.