v1.4.0b1 — Multi-language support (beta)

v1.4.0 beta 1 — Multi-language support

This is a beta. It only shows up in HACS if you turn on "Show beta versions" for this integration. If you don't opt in, nothing changes for you.

Adds Home Assistant translation support for all entity names and dropdown options, with French, Simplified Chinese, and Traditional Chinese translations. Contributed by @baylanger (#10), with PTZ camera testing by @kou147258 (#6). English users should see no visible change.

Also adds names for 25 additional settings found on PTZ cameras (iris, focus, zoom limit, IR light, digital slow shutter, image stabilization, and others).

⚠️ Breaking change: dropdown values are now the camera's raw values

Dropdowns used to report friendly words as their state — Off, White Light, IR, Semi-automatic, 50 Hz. They now report the camera's own internal value — close, colorVuWhiteLight, irLight, SEMIAUTOMATIC, 50hz. The UI still displays the friendly name (that's what the translation files do), but automations and scripts that send or compare dropdown values must use the raw value.

Affected: Supplement Light, BLC Mode, Focus Mode, White Balance, Noise Reduction, Power Line Frequency, and any other dropdown that showed a nicer word than the camera uses. Shutter Speed (1/120 etc.) and Day/Night Mode (day/night/auto) are unaffected.

The Developer Tools → States page shows the raw value for any entity.

How to test

1. In HACS, open Hikvision ISAPI Image Control → ⋮ → Redownload, turn on Show beta versions, and pick v1.4.0b1.
2. Restart Home Assistant.
3. Check that entity names look right, and open the BLC Mode and Iris Mode dropdowns specifically — those use capitalized raw values and are the most likely to show a raw value instead of a friendly one if something's off.
4. Check Settings → System → Logs for a "Translation coverage gaps" warning. It's harmless, but paste it into #6 so the missing names can be added.

Report results on #10 or #6. Once this has been tested on a few more camera models it'll go out as v1.4.0.

v1.3.0 — Basic auth fallback for old cameras

What's changed

• Basic auth fallback for old cameras — Older Hikvision models (e.g. DS-2CD8464F-EI) reject digest authentication entirely and only accept basic auth. When a camera returns a 401 whose WWW-Authenticate challenge doesn't offer Digest, the integration now retries with basic auth and sticks with it for the rest of the session (equivalent to curl --anyauth). A 401 from a camera that does offer Digest is still treated as bad credentials — no basic-auth retry — so the integration won't rack up extra failed logins toward Hikvision's account lockout.
• Docs — Committed the README documentation for the reconfigure flow and permission troubleshooting.

v1.2.1

What's changed

• Sub-endpoint fallback for stubborn cameras — Some Hikvision models (e.g. DS-2CD3367WDP2V2-L) reject all writes to /ISAPI/Image/channels/1 with notSupport, even when sending unmodified XML. When the full endpoint returns notSupport on a single-field change, the integration now automatically retries against the corresponding sub-endpoint (e.g. /Shutter, /SupplementLight). Cameras that already worked continue to use the full endpoint unchanged.
• PUT body debug logging — All four PUT sites now log the outgoing XML at debug level, making it easier to diagnose firmware-specific rejection behavior. Enable with logger.set_level action and custom_components.hikvision_isapi: debug.

Credits

Thanks to @lkwchoi for diagnosing the issue, building the fix, and contributing the PR (#4). Fixes #2.

v1.2.0 — Reconfigure flow

What changed

Adds support for Home Assistant's Reconfigure flow. If you need to change a camera's IP address or credentials, you no longer have to delete the entry and re-add it — just click the three-dot menu on the config entry card in Settings → Devices & Services → Hikvision ISAPI and select Reconfigure.

The form prefills the current host and username so you only need to retype what's actually changing (though the password is always required for verification).

Safety check

After the new credentials validate, the integration compares the MAC address of the camera at the new host against the one stored on the original entry. If they don't match, the reconfigure aborts with a clear error. This prevents an accidental repoint at a different physical camera, which would leave that entry's entities orphaned and state inconsistent.

If you legitimately want to switch an entry to a different camera, delete it and add the new one — that's the right path for that.

Credit

Field-tested against issue #2 as part of walking a user through a permission-scope problem — needed to reconfigure a camera to a different credential set mid-diagnosis.

v1.1.1 — Clearer error when camera user lacks write privileges

What changed

When the Home Assistant user configured in this integration lacks write privileges on a Hikvision camera, the firmware returns HTTP 403 with a variety of unhelpful subStatusCode values (lowPrivilege, notSupport, etc. — depending on firmware). Previously the integration surfaced only the raw code, which was misleading (e.g., "notSupport" made it look like a firmware or capabilities issue when it was actually a permissions issue).

This release adds a clear hint whenever a PUT fails with HTTP 403:

<raw_code> — permission denied. Check that the HA user has write privileges in the camera's web UI (Hikvision is picky about per-user permissions).

The hint shows up in both the user-facing entity error logs (select/number/switch) and the diagnostic warnings. Raw status codes are still used internally for conflict-resolution lookups — no behavior change for that.

How to fix a 403 on your camera

1. Log in to the camera directly at http://<camera-ip>/ with an administrator account.
2. Configuration → System → User Management.
3. Edit the user configured in Home Assistant.
4. Under Remote Permissions, enable Parameters / Configuration.
5. Save — no HA restart needed; new writes will succeed immediately.

Credit

Diagnosed from issue #2 — thanks to @lkwchoi for the detailed logs that made the root cause obvious.

v1.1.0 — Fix blocking SSL call on client init

What changed

Fixes a Home Assistant warning that appeared during integration setup:

Detected blocking call to load_verify_locations inside the event loop

httpx.AsyncClient() triggers SSL certificate loading, which is a synchronous filesystem operation. Creating the client directly on the event loop blocked it briefly. v1.1.0 wraps client instantiation in asyncio.to_thread() so the SSL load happens on a worker thread.

No functional behavior change — just cleaner HA startup logs.

v0.1.0 — Initial release

First public release of the Hikvision ISAPI Image Control integration for Home Assistant.

What's included

• Auto-discovery of camera capabilities from /ISAPI/Image/channels/1/capabilities — every supported setting becomes a native HA entity (switch, number slider, or select dropdown)
• Read-modify-write PUT handling that preserves the exact XML format Hikvision cameras require
• Prerequisite / mutual-exclusivity engine — automatically resolves known conflicts (WDR ↔ HLC, WDR ↔ BLC) by disabling the blocker and retrying
• Tested against multiple Hikvision camera models, including ColorVu, IR, zoom, and panoramic variants

Supported entities (when advertised by the camera)

WDR, BLC, HLC, IR Cut Filter, Exposure, Shutter Speed, Gain, Brightness/Contrast/Saturation, Sharpness, Noise Reduction, Dehaze, White Balance, Image Flip, Supplement Light (ColorVu + IR), and more.

See README.md for details.