Custom integration for Home Assistant to control IP cameras that use the Hi3510 CGI protocol (/cgi-bin/hi3510/param.cgi).

This protocol is used by hundreds of camera models based on HiSilicon (now HiStar) SoCs. Despite the "Hi3510" name, the protocol is shared across multiple chip generations including Hi3510, Hi3518A, Hi3518C, Hi3518EV100, Hi3518EV200/201, Hi3516CV100/200/300, Hi3516EV200/300, and others. These cameras are manufactured by dozens of Chinese OEMs and sold worldwide under many brand names.

The integration communicates entirely over the local network (no cloud dependency) using HTTP Basic Auth and RTSP.

Your camera is likely compatible if:

1. It uses the CamHi, HiP2P, Ctronics, or HiSilicon app for mobile access
2. Its web UI looks like this (accessible at http://<ip>/web/admin.html):

3. The URL http://<ip>/cgi-bin/hi3510/param.cgi?cmd=getserverinfo returns data in the format var key="value";
4. The HTTP 401 response contains WWW-Authenticate: Basic realm="hi3510" or similar

The following brands are known to sell cameras using the Hi3510 CGI protocol. Not every model from these brands uses this protocol — newer or higher-end models may use different firmware.

Note: Many unbranded or white-label cameras sold on Amazon, AliExpress, Banggood, and similar marketplaces also use this protocol. If the camera's mobile app is CamHi, HiP2P, or similar, it very likely uses the Hi3510 CGI protocol.

These cameras use various HiSilicon chips, all sharing the same CGI protocol:

These specific model codes have been tested with this integration:

The firmware supports auto-detection of these image sensors via I2C:

• Live video stream via RTSP (rtsp://<host>:<rtsp_port>/11)
• JPEG snapshots from /tmpfs/auto.jpg
• Configurable RTSP port (default: 554)

The config flow includes automatic network scanning:

1. Choose "Scan network" or "Manual entry"
2. The scan probes all IPs on local subnets for Hi3510 cameras (port 80)
3. Cameras are identified by their CGI response format or HTTP 401 realm
4. Already-configured cameras are filtered out
5. Scan results are cached across flow instances — no rescanning when adding multiple cameras
6. A "Rescan network" option is available to refresh the list

OSD position selects include anti-overlap validation.

All image parameters are sent together to prevent firmware from resetting unspecified values.

Two services are available for automations and scripts:

Move the camera in a direction or control zoom/focus/iris.

service: hi3510.ptz_move
data:
  entry_id: "01KKXYNQ..."
  action: left       # left, right, up, down, home, stop, leftup, leftdown, rightup, rightdown, hscan, vscan, zoomin, zoomout, focusin, focusout, irisin, irisout
  speed: 1           # 0–4, default 1

Go to or save a PTZ preset position.

# Go to preset 3
service: hi3510.ptz_preset
data:
  entry_id: "01KKXYNQ..."
  action: go
  number: 3

# Save current position as preset 5
service: hi3510.ptz_preset
data:
  entry_id: "01KKXYNQ..."
  action: save
  number: 5

Download diagnostic data from any camera device page (⋮ → Download diagnostics). The JSON includes coordinator data, camera info, and options — with passwords and usernames redacted.

1. Settings → Devices & Services → Add Integration → Hi3510 IP Camera
2. Choose Scan network (automatic) or Manual entry
3. Enter credentials (username, password, RTSP port)
4. The integration validates the connection and identifies the camera by MAC address

Configure integration options without removing the camera:

• Connection: update host, port, credentials, RTSP port
• Cache retention: set how many days to keep cached recordings (default: 7)
• Allowed networks: restrict cache browser access to specific IP ranges (default: private networks)
• Polling interval: how often to poll camera parameters, 10–300 seconds (default: 30)
• Motion detection interval: how often to check for motion events, 1–60 seconds (default: 3)

Browse and play back SD card recordings directly from Home Assistant. Two interfaces are available:

The SD Browser is a full-featured recording manager accessible at /api/hi3510/sd. It provides:

• Camera hub: grid of all cameras, click to enter per-camera view
• Sidebar with months: lists all months that have recordings on SD or in cache, with badge counts (💾 cached, 🔗 merged)
• Interactive calendar: click a month to see a calendar; days with recordings are highlighted with file counts
• File list with filters: view all files for a day, filter by type (alarm 🔴 / recording 📹 / merged 🔗 / cached 💾)
• Click-to-play: click any file to play it inline. If not yet cached, it downloads from SD, converts HXVS→MP4, and plays automatically

• Merge recordings: select multiple files (checkbox + range select) and merge them into a single continuous video
• Merge tracking: files used in a merge are marked with "✓ unito" badge; merged videos appear at the top with time range labels
• Cache management: "Svuota cache" button to clear all cached files for a camera
• Cache size display: hub shows cache size in MB per camera and total cache size
• Global cache purge: "Svuota tutta la cache" button on the hub to clear all cameras at once
• Live counters: shows cached/total files, merged count, and used-in-merge count per day

type: iframe
url: /api/hi3510/sd
aspect_ratio: 100%

To show only cameras in a specific HA area (recommended — survives reinstallation):

type: iframe
url: /api/hi3510/sd?area=rieti
aspect_ratio: 100%

To filter by host substring (e.g., all cameras on a specific hostname or IP range):

type: iframe
url: /api/hi3510/sd?host=192.168.1
aspect_ratio: 100%

To show only specific cameras by entry ID:

type: iframe
url: /api/hi3510/sd?entries=<entry_id_1>,<entry_id_2>
aspect_ratio: 100%

Filters can be combined: ?area=rieti&host=spare.dynu.com

1. Open the SD Browser tab in your dashboard
2. Click on a camera from the hub grid
3. Select a month from the sidebar → the calendar shows days with recordings
4. Click a day → the file list loads with all recordings
5. Click a file → it downloads from SD, converts to MP4, and plays inline
6. To create a compilation: check multiple files → click "🔗 Unisci" → a merged video is created
7. Use filters to quickly find alarm events or already-cached files

The original cache browser at /api/hi3510/cache is still available but offers fewer features (no merge, no single-file download, no filters). The SD Browser supersedes it for all use cases.

Both interfaces support:

• Direct URL: navigate to http://<your-ha>:8123/api/hi3510/sd from any browser on your local network
• Dashboard embed: add an iframe card (see examples above)
• Media browser: open the HA media browser panel and select Hi3510 IP Camera to browse recordings per camera
• Supports H.264 recordings (HXVS container format) with audio (G.711 a-law → AAC). H.265 (HXVT) files are parsed but not playable in the browser
• Recordings are downloaded from the camera, remuxed to MP4 via ffmpeg, and cached locally
• Cache auto-cleanup based on configurable retention period
• Filterable by HA area (?area=), host substring (?host=), or entry IDs (?entries=)
• IP-based access control (no auth token required from allowed networks)

You can create a full NVR experience by combining a live camera card with the SD browser in a tabbed dashboard. Here's an example using advanced-camera-card and go2rtc:

# Tab 1: Live View (requires advanced-camera-card + go2rtc)
views:
  - title: Live
    path: live
    icon: mdi:cctv
    type: panel
    cards:
      - type: custom:advanced-camera-card
        cameras:
          - title: Front Door
            id: front_door
            live_provider: webrtc-card
            webrtc_card:
              url: front_door_sd
              mode: webrtc
            dependencies:
              cameras:
                - front_door_hd
          - title: Front Door HD
            id: front_door_hd
            live_provider: webrtc-card
            webrtc_card:
              url: front_door_hd
              mode: webrtc
            capabilities:
              disable_except:
                - substream
          - title: Backyard
            id: backyard
            live_provider: webrtc-card
            webrtc_card:
              url: backyard_sd
              mode: webrtc
            dependencies:
              cameras:
                - backyard_hd
          - title: Backyard HD
            id: backyard_hd
            live_provider: webrtc-card
            webrtc_card:
              url: backyard_hd
              mode: webrtc
            capabilities:
              disable_except:
                - substream
        live:
          display:
            mode: grid
            grid_columns: 2
          auto_play:
            - selected
            - visible
          auto_mute:
            - unselected
            - hidden
          auto_unmute:
            - selected
          lazy_load: true
          draggable: false
          controls:
            builtin: false
            next_previous:
              style: none
            thumbnails:
              mode: none
            timeline:
              mode: none
        menu:
          style: hover-card
          buttons:
            substreams:
              enabled: true
              icon: mdi:high-definition
            fullscreen:
              enabled: true
              alignment: opposing
            mute:
              enabled: true
              priority: 35
            microphone:
              enabled: true
              priority: 34
              type: toggle
        status_bar:
          style: overlay
          position: bottom
          height: 28
          items:
            title:
              enabled: true
            engine:
              enabled: false
            resolution:
              enabled: false
            technology:
              enabled: false
        dimensions:
          aspect_ratio_mode: unconstrained
          height: calc(100vh - 56px)

  # Tab 2: SD Browser (recording management)
  - title: SD Browser
    path: sd-browser
    icon: mdi:sd
    type: panel
    cards:
      - type: iframe
        url: /api/hi3510/sd
        aspect_ratio: 100%

This gives you a two-tab dashboard: the first tab shows a live grid of all cameras with SD/HD substream switching and audio controls, the second tab embeds the SD browser for full recording management with calendar navigation, download, merge, and playback.

When using advanced-camera-card with webrtc-card provider and go2rtc streams that include audio:

• Audio plays automatically when you select a camera (thanks to auto_unmute: [selected])
• The mute button in the menu bar toggles audio on/off for the selected camera
• The microphone button enables two-way audio (requires go2rtc with backchannel support)
• Make sure auto_mute does NOT include microphone — only unselected and hidden

# Audio configuration summary
live:
  auto_mute:
    - unselected    # mute when camera is not selected
    - hidden        # mute when camera is hidden
  auto_unmute:
    - selected      # unmute when camera is selected
menu:
  buttons:
    mute:
      enabled: true       # toggle audio on/off
    microphone:
      enabled: true       # two-way audio (hold or toggle)
      type: toggle        # toggle mode instead of push-to-talk

The integration registers as a Home Assistant media source, making SD card recordings browsable from the HA media browser panel.

• Main coordinator: configurable, default 30s (image, OSD, infrared, ONVIF, recording, audio, SD info)
• Motion coordinator: configurable, default 3s (SD card alarm file browsing)
• Both intervals adjustable in the options flow per camera

• OSD Region 0 protection: writing -name on region 0 is blocked — it corrupts OSD on some firmware and can brick the camera
• Image parameter preservation: all values sent together on any change
• OSD anti-overlap: prevents both overlays in the same corner
• Graceful degradation: 3 consecutive failures → camera marked unavailable

1. Open HACS → Integrations
2. Search "Hi3510" and install
3. Restart Home Assistant

Copy custom_components/hi3510/ to your HA config/custom_components/ directory and restart.

• OSD timestamp text (region 0) is read-only — writing corrupts OSD on some firmware
• Some older firmware (V9.x) lacks setimageattr, flip/mirror, or presets
• OSD position: 2 options on older firmware, 4 on newer
• HTTP Basic Auth with no encryption
• Motion detection requires an SD card
• PTZ presets must be saved via the camera's web UI or the hi3510.ptz_preset service

• English
• Italian

• Config flow scan fix: network scan no longer shows "Unknown error occurred" — any exception during scan now silently falls back to manual entry form (fixes issue #1)
• Scan fallback: uses socket as fallback if homeassistant.components.network is unavailable
• hxvs_parser: fixed O(n²) HXVF frame scan (pos += 4 → pos += 16 + psize) — parsing is now linear and dramatically faster on large recordings
• hxvs_parser: guard against infinite loop in MPEG-TS packet stuffing
• ffmpeg: subprocess is now killed on timeout instead of being left as a zombie process
• SD merge: asyncio.Lock per camera prevents concurrent merge operations from corrupting cache files — returns 409 if a merge is already in progress
• config_flow: _scan_cache moved from class-level to hass.data — fixes race condition between concurrent config flows
• config_flow: uses async_get_clientsession instead of creating a raw aiohttp.ClientSession
• Startup guard: raises ConfigEntryNotReady if unique_id is None (camera MAC not available) — prevents entity ID collisions with multiple cameras
• Reboot button: Hi3510ConnectionError is now caught and treated as success (camera drops the TCP connection during reboot — was incorrectly reported as an error)
• Switch / Number / Text: SET operations now raise HomeAssistantError on API failure instead of propagating unhandled exceptions
• Coordinator: unexpected errors now logged at WARNING instead of DEBUG
• CacheFileView: entry_id ownership is checked before file existence (prevents cross-camera file probing)

• Network scan fix: removed incorrect exclusion of 172.x.x.x subnets from discovery scan — cameras on these networks are now found correctly
• Scan count fix: the "Found X camera(s)" message no longer counts the "Rescan" option
• Auth-required labels: cameras behind authentication (401) now show a 🔒 icon and "(auth required)" label in the scan results for clarity
• README images: fixed broken images in HACS repository page (relative paths replaced with absolute GitHub raw URLs)

• SD Browser cache stats: the hub now shows cache size in MB per camera and total cache size across all cameras
• Per-camera purge button: "🗑 Svuota" button on each camera card to clear its cache without entering the browser
• Global cache purge: "🗑 Svuota tutta la cache" button on the hub to clear all cached files at once
• New endpoint: DELETE /api/hi3510/sd/clear_all — clears the entire cache for all cameras
• HACS Default: integration is now in the HACS default repository (no custom repo needed)
• README: updated installation instructions, badge, and icon URL

• Advanced SD Browser playback: sticky video player with seek bar, speed control (0.5x–8x), mute, screenshot
• 24h interactive timeline: zoom (mouse wheel), pan (drag), scrollbar, needle cursor, click-to-play
• Prefetch: next 2 files downloaded in background for seamless continuous playback
• Auto-next: continuous playback across files (downloads automatically if not cached)
• Error recovery: auto-skip to next file on video errors
• Go-to-time: jump to nearest file for a given HH:MM:SS
• Download clip: select time range for auto-download or merge
• Multi-camera synchronized playback: select 2+ cameras, choose a time, parallel download and synced play with per-camera audio toggle and speed sync
• H.265 (HXVT) support: H.265 recordings now playable via ffmpeg transcode to H.264 — works in SD Browser, legacy views, merge, and media browser
• Sidebar layout: month list + compact calendar on left, player + timeline on right
• File list toggle: hidden by default, toggle for merge operations

• PTZ control entities: 7 button entities per camera (Left, Right, Up, Down, Home, Zoom In, Zoom Out) — visible on the device page and usable in dashboards and automations
• PTZ preset select: select entity (1–16) to go to a saved preset position directly from the device page
• PTZ services: hi3510.ptz_move and hi3510.ptz_preset services for automations and scripts, with full direction/zoom/focus/iris control and preset go/save
• HA diagnostics: download diagnostic data from any camera device page (⋮ → Download diagnostics) — includes coordinator data, camera info, and options with sensitive data redacted
• Configurable polling: polling interval (10–300s) and motion detection interval (1–60s) now adjustable per camera in the options flow
• OSD text validation: max 32 characters enforced on the OSD text entity
• Camera as CoordinatorEntity: camera entity now properly extends CoordinatorEntity for correct availability tracking (unavailable after 3 consecutive failures)
• Motion midnight fix: motion detection preserves active state across midnight instead of falsely resetting
• ffmpeg debug logging: full ffmpeg stderr output logged at debug level when SD recording conversion fails (was truncated)
• Code refactor: shared view utilities extracted to view_utils.py (DRY cleanup of views.py and sd_browser.py)

• Audio in SD recordings: SD card recordings now include audio. The HXVS parser extracts G.711 a-law audio frames from the proprietary container, and ffmpeg transcodes them to AAC during the HXVS→MP4 conversion. Both single-file downloads and multi-file merges produce MP4 files with synchronized audio+video
• Audio format: G.711 a-law, 8kHz mono, 160 bytes/frame (20ms) — transcoded to AAC 64kbps for browser compatibility
• Backward compatible: recordings from cameras without audio (or with audio disabled) continue to work as before — the parser gracefully handles files with no HXAF frames

• SD Browser area filter: the hub view now supports ?area=<area_name> to filter cameras by Home Assistant area — dashboard URLs survive integration reinstallation (no more hardcoded entry IDs)
• SD Browser host filter: added ?host=<substring> filter to show only cameras whose host contains the given string
• Hub title: shows the area name in the page title when filtering by area (e.g., "SD Browser — Rieti")
• Filter preservation: all filters (area, host, entries) are preserved in back-links when navigating to per-camera views

• Version alignment: fixed manifest.json version to match GitHub release tag (was stuck at 1.4.1)

• Minimum HA version: added homeassistant requirement (2024.2.0) in hacs.json — prevents installation on incompatible versions (Python 3.12 type alias syntax required)

• SD Browser: new full-featured recording manager at /api/hi3510/sd with:
  • Camera hub grid with per-camera entry
  • Month sidebar with cache/merge badge counts
  • Interactive calendar with per-day file counts
  • File list with filters (alarm / recording / merged / cached)
  • Click-to-download-and-play: click any SD file to download, convert HXVS→MP4, and play inline
  • Multi-file merge: select files and merge into a single continuous video
  • Merge tracking: "✓ unito" badges on source files, merged videos with time range labels
  • Cache management: clear all cached files per camera
  • Live counters per day (cached, merged, used-in-merge)
• New diagnostic sensors: IP address, firmware version, model code, last boot time
• OSD position fix: position now correctly derived from place + x coordinate (was using only place, which mapped incorrectly on some firmware)
• Entity categories: infrared mode and OSD position selects now categorized as EntityCategory.CONFIG
• Entity categories: reboot button, image parameters, audio volumes, OSD text now have proper entity categories

• SD card recording playback: download, remux (H.264 → MP4), cache, and play back recordings from the camera's SD card directly in Home Assistant
• Cache browser UI: web-based interface with camera grid, calendar month navigation, per-day video list, and inline video player with full seek support
• Media source integration: SD recordings browsable from HA's built-in media browser
• Options flow: single-step configuration for cache retention days and allowed network ranges
• IP-based access control: cache browser accessible without auth token from configured private networks (supports ZeroTier/VPN)
• HTTP Range support: video files served with Range request support for proper seek/scrub in the browser player
• HXVS container parser: extract H.264 elementary streams from Hi3510 proprietary SD card format. H.265 (HXVT) is parsed but not playable in browsers
• SD diagnostic sensors: free space, total space, and SD card status entities
• API extensions: list_sd_files, download_sd_file, get_sd_info methods

• Initial HACS release
• Camera entity with RTSP stream and JPEG snapshot
• Switch, select, number, text, button, binary sensor entities
• Network discovery in config flow
• OSD overlay management with anti-overlap validation
• Motion detection via SD card alarm file monitoring

MIT

_{🤖 This integration was entirely developed with the assistance of artificial intelligence (Kiro AI IDE).}