v1.0.beta4

v1.0 Beta 4

Pre-release · Compare to v1.0.beta3

---

Release notes

Version 1.0.0 Beta 4 — Audio alarm, firmware visibility, capability detection & config flow

This release adds AudioAlarm-driven controls and a siren, a firmware update (advisory) entity, endpoint-based feature detection with scheduled rescans and config reload when capabilities change, a full config flow refresh (SSL, RTSP, translations, DHCP abort), stronger event → entity routing for multi-channel / NVR setups, and diagnostics export. It builds on Beta 3’s event pipeline and logging discipline.

Status: This integration is still in testing. It has been exercised mainly on DS-2CD2387G3 (ColorVu G3) standalone cameras. NVR and other models are improved in code but not systematically tested—reports with diagnostics and logs are appreciated.

---

What’s new

• Siren entity — New Siren platform when AudioAlarm ISAPI is available: on/off, tones, duration, volume, with retrigger behaviour. Tone labels match the Warning Sound select where possible.
• Audio alarm suite — Select: Audio Type, Warning Sound (options from capabilities + fallbacks, including custom audioID where exposed). Number: Alarm times, Alarm output volume (ISAPI “loudspeaker” — not two-way speaker volume). Button: Trigger alarm (correct /AudioAlarm/{audioID}/test style usage). Logic to align alert vs custom audio class from probed capabilities / tones where applicable.
• Image quality numbers — Brightness, Contrast, Saturation, Sharpness when the image color endpoint probes 200 OK.
• Capability detection v2 — detect_features() uses _test_endpoint_exists() (GET → 200 = supported; 403 = treat as unsupported for controls; 404 = not present) across image, two-way audio, supplement light, IR cut, AudioAlarm, smart triggers, scene change, and I/O from capabilities XML.
• Scheduled capability rescan — First rescan ~15 minutes after startup, then every 6 hours (FEATURE_CAPABILITY_FIRST_SCAN / FEATURE_CAPABILITY_RESCAN_INTERVAL in const.py). If the feature dict changes, the config entry reloads so entities match firmware and permissions.
• Device registry — Serial-first identifiers with IP fallback; manufacturer metadata; NVR / multi-channel improvements including via_device for camera entities where applicable.
• Config flow — Two-step flow, translations/en.json, clearer errors and help text, camera error / HTML extraction, SSL verification toggle, forced RTSP port, improved discovery naming, DHCP abort handled correctly, all code paths return a valid FlowResult.
• Diagnostics — Downloadable diagnostics with detected features and capability-oriented detail; hardened so failures don’t break the integration.
• Docs & tooling (repo) — Added/expanded root docs (entities, endpoints, ISAPI research) and query_camera_capabilities.py for contributors (optional, not a runtime dependency of the integration).

---

Bug fixes

• Event → binary_sensor lookup — Lookup always includes channel_id consistent with binary_sensor.py; fallback keys and logging when no match; channel_id 0 vs 1 fallback for single-channel cameras.
• Binary sensors / notifications — Fixes for ID / channel mismatches; mutex handling for mutually exclusive smart / motion-style events (see const.py mutex / MUTEX_ALTERNATE_ID).
• Duration / ISAPI v2 XML — DurationList / relationEvent parsing hardened for namespaced XML; logging levels adjusted when duration data is missing or non-actionable.
• Scene change — Extra probe via Event/channels/capabilities so scene change is detected on more firmware paths.
• NVR / multi-channel — Fixes for entity creation errors after NVR-oriented updates; safer per-channel behaviour.
• Two-way audio & test tone — Minimal JSON for session open (required fields only); sessionId query parameter per ISAPI; improved 403 / session errors; noise reduction preserved when changing mic/speaker volume; alert audio ID logic corrections.
• Media player — WAV parsing and timing; chunked streaming attempts; removal of unsafe raw ulaw fallback; async_process_play_media_url / internal URL handling for authenticated media; clearer logging.
• Audio alarm test — Uses audioID in the URL where the device requires it.
• Feature detection — Removed “enable everything” style fallbacks in favour of probe-driven flags; safer behaviour when XML or probes partially fail.
• Coordinator / __init__.py — Indentation and missing return issues fixed; detected_features kept in sync for reload logic.
• Update platform — Removed erroneous update __init__.py file; single update.py implementation.
• Config flow — async_step_dhcp, async_step_advanced, and related steps always return; indentation in notifications.py fixed; empty optional RTSP port on reconfigure.
• Diagnostics — IrcutFilter path casing; try/except boundaries so diagnostics never raises into the UI flow.

---

Improvements

• Feature detection logging — After each pass, logs count and list of enabled features plus a one-line category summary (image, two-way audio, lights, IR, motion, tamper, intrusion, line, region, scene, AudioAlarm, I/O).
• Notification logging — Noisy info lines moved to debug where appropriate.
• Camera errors — Better extraction when the root element is ResponseStatus or the body is HTML-heavy.
• Switch platform — Availability follows coordinator success when the device is unreachable.
• manifest.json — Version 1.0.1; aiohttp in requirements; platforms lists switch, update, siren explicitly.
• quality_scale.yaml — Updates toward Gold tier expectations.
• README.md — Synced with current entities, HACS slug, requirements, registry defaults, troubleshooting.
• Tests — test_coordinator (and related) updated for new coordinator / rescan behaviour.
• Media player — Inline developer / TODO comments documenting G.711 ulaw expectations and known gaps.
• Entity registry — Speaker media_player: _attr_entity_registry_enabled_default = False for new setups.

---

Technical details

• _test_endpoint_exists(endpoint) — Short-timeout GET; 200 ⇒ True; otherwise False (403/404/timeouts don’t create useless control entities).
• detect_features() — Populates detected_features for all platforms; test_audio_alarm (and the whole audio-alarm cluster) requires GET /ISAPI/Event/triggers/notifications/AudioAlarm?format=json → 200.
• const.py — FEATURE_CAPABILITY_RESCAN_INTERVAL, FEATURE_CAPABILITY_FIRST_SCAN, RTSP_PORT_FORCED, SIREN_RETRIGGER_INTERVAL_SECONDS, per-event mutex, MUTEX_ALTERNATE_ID for IDs such as VMDHumanVehicle.
• FirmwareUpdateCoordinator — aiohttp, merged live + manual firmware JSON, model normalisation and version tuple comparison, UpdateFailed on network/parse errors.
• device_helpers.py — Shared device info / identifier helpers after registry unification.

---

Known issues

• Media player (speaker) — Still not a general-purpose HA speaker: TTS and arbitrary MP3 are unreliable; the code path expects pre-encoded G.711 ulaw style input. Needs deep ISAPI / streaming expertise for a full fix. Contributions welcome. Entity is disabled by default in the entity registry for new installs.
• Testing limited — Primarily DS-2CD2387G3 standalone; other models and NVR layouts need field validation.

---

Note on firmware & audio alarm

The Update entity is advisory only—it does not flash firmware over ISAPI. Siren and other AudioAlarm entities depend on the AudioAlarm notification API probing 200 OK. That is separate from two-way audio (/ISAPI/System/TwoWayAudio/...), which still gates speaker/mic numbers, noise reduction, and the media player.

---

Upgrade notes

• Drop-in from Beta 3: update files or HACS, then restart Home Assistant (or reload the integration).
• Expect new entities: Update, optional Siren, and additional numbers / selects / buttons for audio alarm and image tuning; several remain disabled by default in the entity registry—enable under Settings → Devices & services → Entities if needed.
• aiohttp is declared in manifest.json; Home Assistant should install it with the integration.
• For issues, attach diagnostics, camera model + firmware, HA version, and custom_components.hikvision_isapi: debug logs.

v1.0 Beta 3

Release Notes

Version 1.0.0 Beta 3 - Event Handling Improvements & Bug Fixes

This release focuses on fixing critical event notification issues, preventing notification spam, and improving overall stability.

Status: This integration is still in testing stages, but most/all features are working correctly. The integration has been tested on DS-2CD2387G3 (ColorVu G3) standalone cameras. NVR support has been improved but not tested.

What's New:

• State Change Detection - Smart notification filtering that prevents duplicate events during continuous motion detection. Binary sensors now only update when the actual state changes (OFF→ON or ON→OFF), eliminating notification spam during prolonged motion events. This prevents Home Assistant from being flooded with duplicate events when motion is continuously detected.

• ActiveState Support - Integration now properly handles activeState field in event notifications. When cameras send activeState="inactive", the integration immediately clears the binary sensor instead of waiting for a timeout. This provides more responsive event clearing that matches camera behavior.

• Dynamic Icons for Binary Sensors - Binary sensors now display state-based icons that change based on their on/off state. Video Loss sensors show ethernet cable icons, Tamper Detection shows alarm light icons, providing better visual feedback in Home Assistant.

• Improved Device Identification - Integration now uses camera serial number as the primary device identifier instead of IP address, improving device tracking and preventing issues when camera IPs change. Falls back to IP address if serial number is not available.

• NVR Support Improvements - Improved handling of NVR devices with proper via_device relationships for camera entities. Camera entities on NVRs should now correctly link to the NVR device, improving device organization in Home Assistant. Note: NVR support has been improved but not tested as only standalone cameras are available for testing.

Bug Fixes:

• Fixed "Unsupported event duration" Errors - Properly handles Hikvision ISAPI v2.0 duration events by extracting the actual event type from DurationList/Duration/relationEvent structure. These errors (which occurred 244+ times) are now logged at debug level instead of error level to reduce log noise. The integration now uses multiple fallback methods to find event types, supporting different camera firmware versions.

• Fixed Detection Enabled State Crashes - Added proper checks for empty enabled text elements to prevent crashes when parsing detection settings for all event types (Motion, Tamper, Intrusion/Field Detection, Line Crossing, Scene Change, Region Entrance, Region Exiting). Previously, the integration would crash if the XML had an <enabled> tag but no text content.

• Fixed Channel ID Fallback for Single Cameras - Added fallback mechanism for event notifications. Some cameras send notifications with channel_id=0, but entities are created with channel_id=1. The integration now automatically tries channel_id=1 as a fallback when lookup fails with channel_id=0, ensuring events work correctly on single cameras.

• Fixed Scene Change Detection Parsing - Improved XML parsing with multiple fallback methods for namespace handling, fixing issues where scene change events weren't being detected on some cameras.

• Fixed Entity Availability - Better handling of connection errors and entity availability checks. Entities now properly report unavailable state when the camera is unreachable.

• Fixed Event/Triggers Endpoint URL - Corrected URL construction for Event/triggers endpoint to properly include /ISAPI/Event path.

• Fixed Alarm I/O Switch Icons - Updated alarm input/output switch icons from generic eye icons to proper video input icons (mdi:video-input-hdmi) for better visual identification.

• Reduced Log Noise - Connection errors during camera restarts are now logged at debug level instead of error level. Duration event parsing failures that are expected (when relationEvent is missing) are also logged at debug level.

Improvements:

• Enhanced Event Parsing - Multiple fallback methods (6 different approaches) for finding event types in XML, supporting different camera firmware versions and namespace variations. This makes the integration more compatible with various Hikvision camera models.

• Better Error Handling - More robust XML parsing with comprehensive fallback mechanisms for both namespaced and non-namespaced XML structures. The integration now handles edge cases where cameras send non-standard XML formats.

• Documentation Updates - README now accurately reflects all available entities, features, and their default status. Added complete entity listings including all detection switches, alarm I/O, brightness controls, and binary sensors. Added quality_scale.yaml for tracking integration quality tier compliance.

• Event Structure Updates - Updated AlertInfo model to include active_state field. Updated event documentation to match actual implementation (added io_port_id field, removed incorrect device field).

• Supported Events Tracking - Added new get_supported_events() API method that fetches and tracks supported events from the camera's Event/triggers API, with graceful fallback if the API is unavailable. This improves logging and helps identify which events are available on each camera.

• Alarm I/O Error Handling - Improved error handling for alarm input/output operations. Connection errors during camera restarts are now logged at debug level instead of error level, reducing log noise.

• Media Player Developer Documentation - Added extensive developer comments to media player implementation explaining what's broken, what was attempted, and what needs to be fixed. This will help future contributors understand the current state and challenges.

• Test Tone Improvements - Removed base64 encoding from test tone function and improved audio streaming with chunked transfer to avoid timeouts. Test tone now uses a 3-second consistent tone (1000 Hz ramping to 2500 Hz).

• Switch Availability Checks - Added proper availability checks to all switch entities to prevent errors when camera is unreachable.

Technical Details:

• Duration events (ISAPI v2.0) are now properly parsed by checking DurationList/Duration/relationEvent when eventType is "duration" or empty
• State change detection prevents redundant Home Assistant events and entity updates during continuous motion
• ActiveState handling allows immediate sensor clearing when cameras send inactive notifications
• Multiple XML parsing fallback methods ensure compatibility with different camera firmware versions

Known Issues:

• Media Player (Speaker) - Still not working. The media player implementation is too complex for AI-assisted development and will likely need an experienced developer familiar with Hikvision ISAPI two-way audio, G.711 codec streaming, and real-time audio session management to properly implement. Extensive developer comments have been added to the code explaining what was attempted and what needs to be fixed. Contributions welcome!

• Testing Limited - Only tested on DS-2CD2387G3 (ColorVu G3) standalone cameras. Other models and NVR setups have not been tested.

Note on Smart Events:

All smart event types (Motion, Intrusion, Line Crossing, Region Entrance/Exiting, Scene Change, Video Tampering, Alarm Input) should now work correctly with proper camera configuration. The integration properly handles all event types including duration events (ISAPI v2.0). If events aren't working, ensure they are enabled and configured on the camera with notification linkage actions set up.

Upgrade Notes:

• No breaking changes - this is a drop-in upgrade
• Duration event errors in logs should be significantly reduced (now at debug level)
• Notification spam during continuous motion should be eliminated
• If you were experiencing "Unsupported event duration" errors, these should now be resolved
• Single cameras that send notifications with channel_id=0 should now work correctly with the fallback mechanism

---

v1.0 Beta 2

Release Notes

Version 1.0.0 Beta 2 - Major Improvements & Bug Fixes

This release includes significant improvements to event notifications, multiple camera stream support, and various bug fixes.

What's New:

• Multiple Camera Streams - Support for Main Stream, Sub-stream, Third Stream, and Transcoded Stream. Each stream type gets its own camera entity, with Main Stream enabled by default and others disabled (can be enabled in entity registry).

• Notification Host Sensors - New diagnostic sensors showing notification host configuration:

  • Notification Host (IP address)
  • Notification Host Path
  • Notification Host Port
  • Notification Host Protocol

• Event Notifications Working - Motion detection notifications are now working! Other event types (Intrusion, Line Crossing, etc.) should work if properly configured on the camera.

• Improved Error Handling - Better XML parsing with multiple fallback methods, improved error messages, and detailed logging for debugging.

• Bug Fixes:

  • Fixed notification host being reset to "/" on integration unload
  • Fixed Security endpoint URL construction (RTSP port detection)
  • Fixed stream detection for cameras
  • Fixed fallback camera entity stream support error
  • Improved entity lookup and unique_id matching

Improvements:

• Enhanced logging throughout the integration for easier debugging
• Better handling of cameras that don't support all stream types
• Notification host configuration now uses /api/hikvision to match other integrations
• More robust XML parsing with multiple detection methods

Known Issues:

• Binary sensors for events other than Motion may not work if not properly configured on camera
• Media Player (Speaker) still not working
• Only tested on DS-2CD2387G3 (ColorVu G3)

Upgrade Notes:

• If you had the integration configured before, you may need to re-enable additional camera stream entities in the entity registry
• Notification host path changed from /api/hikvision_isapi to /api/hikvision to avoid conflicts

---

v1.0.0 (Beta 1)

Release Notes

Version 1.0.0 beta 1 - Initial Release

This is the first version of the integration. It's still in early development stages, but provides comprehensive control over Hikvision IP cameras via ISAPI.

What's included:

• Real-time event detection - Motion, Intrusion, Line Crossing, Region Entrance/Exiting, Scene Change, Video Loss, and Video Tampering events via webhook notifications
• Video/Image controls - Day/Night switch, supplement light modes, brightness controls, LED duration
• Motion detection settings - Sensitivity, target type, trigger times
• Audio controls - Speaker/microphone volume, noise reduction
• System monitoring - CPU, memory, uptime, reboot count, streaming status
• Camera controls - Snapshot, remote restart

This integration was created to provide more control options than existing Hikvision integrations, with a focus on real-time event detection and comprehensive camera settings management.

Note: This is early development software. Expect bugs and limitations. Only tested on DS-2CD2387G3 (ColorVu G3).

---