Skip to content

README.md

Latest commit

 

History

History
148 lines (121 loc) · 5.32 KB

README.md

File metadata and controls

148 lines (121 loc) · 5.32 KB
Raw

Esee Cloud for Home Assistant

Open your Home Assistant instance and open this repository in HACS

Local-only Home Assistant custom integration for EseeCloud/IP-Pro cameras that use the JUAN/Hi3510 HTTP API and the Bubble media protocol.

This project is an independent community integration and is not affiliated with EseeCloud, IP-Pro, or the camera manufacturer.

Features

  • Bubble video and audio through the installed WebRTC/go2rtc integration
  • Automatic G.711 A-law camera audio configuration for Bubble compatibility
  • Native JPEG snapshots
  • Main and sub-stream camera entities
  • PTZ movement, speed, safe timed pulses, continuous mode, and diagonals
  • Zoom, focus, iris, and auxiliary output commands
  • Home, native horizontal cruise, and emulated vertical scan
  • Set, recall, and clear presets
  • UI config flow and localized English/French strings

The Home Assistant domain is esee_cloud because integration domains cannot contain hyphens. The displayed integration name is Esee Cloud.

The integration exposes the complete PTZ command vocabulary found in the EseeCloud desktop client. Camera models frequently reuse that generic UI even when they do not contain an iris motor or auxiliary relay. In that case the action remains available, but Home Assistant reports the firmware's rejection instead of pretending it succeeded.

Commands

Capability Commands Implementation
Pan/tilt UP, DOWN, LEFT, RIGHT Native local CGI
Diagonals UP_LEFT, UP_RIGHT, DOWN_LEFT, DOWN_RIGHT Alternating safe axis pulses
Stop/home STOP, HOME Native stop; system preset 0 for home
Lens ZOOM_IN, ZOOM_OUT, FOCUS_NEAR, FOCUS_FAR Native local CGI
Iris IRIS_OPEN, IRIS_CLOSE Generic EseeCloud command; hardware-dependent
Auxiliary AUXILIARY_ON, AUXILIARY_OFF Generic EseeCloud command; hardware-dependent
Patrol HORIZONTAL_SCAN, CRUISE, VERTICAL_SCAN Native horizontal auto; emulated vertical sweep
Presets GOTO_PRESET, SET_PRESET, CLEAR_PRESET Native preset CGI, range 0–255

speed is normalized from 0 to 1 and mapped to the firmware range 1–63. duration creates a bounded movement followed by a shielded stop. Set continuous: true only when a separate STOP action is guaranteed.

Installation

HACS custom repository

  1. In HACS, open Integrations.
  2. Add https://github.com/jingle-jew/esee-cloud-home-assistant as a custom repository of type Integration.
  3. Install Esee Cloud and restart Home Assistant.

Manual installation

Copy custom_components/esee_cloud into the custom_components directory of your Home Assistant configuration, then restart Home Assistant.

Add the integration from Settings → Devices & services → Add integration → Esee Cloud. A camera with no password is supported; leave the password field empty.

Example for the camera used during development:

Field Value
Host 10.0.0.81
Port 80
Username admin
Password empty
Channel 0

WebRTC card example

type: custom:webrtc-camera
entity: camera.esee_cloud_camera_flux_principal
ui: true
ptz:
  service: esee_cloud.ptz
  data_left:
    entity_id: camera.esee_cloud_camera_flux_principal
    command: LEFT
    speed: 0.5
    duration: 0.25
  data_right:
    entity_id: camera.esee_cloud_camera_flux_principal
    command: RIGHT
    speed: 0.5
    duration: 0.25
  data_up:
    entity_id: camera.esee_cloud_camera_flux_principal
    command: UP
    speed: 0.5
    duration: 0.25
  data_down:
    entity_id: camera.esee_cloud_camera_flux_principal
    command: DOWN
    speed: 0.5
    duration: 0.25
  data_zoom_in:
    entity_id: camera.esee_cloud_camera_flux_principal
    command: ZOOM_IN
    duration: 0.25
  data_zoom_out:
    entity_id: camera.esee_cloud_camera_flux_principal
    command: ZOOM_OUT
    duration: 0.25

Entity IDs are generated by Home Assistant and may receive a numeric suffix. Always use the actual entity ID shown in Developer tools → States.

Home Assistant action example

action: esee_cloud.ptz
target:
  entity_id: camera.esee_cloud_camera_flux_principal
data:
  command: GOTO_PRESET
  preset: 1

Protocol notes

  • Media uses the Bubble source exposed by the camera and decoded by the WebRTC/go2rtc custom integration.
  • During setup, the integration changes an incompatible camera audio codec such as AAC to G.711 A-law, then verifies that the camera retained the setting. This persistent camera-side change is required because go2rtc's Bubble input receives PCMA/8000 audio.
  • Snapshots use the local NetSDK JPEG endpoint.
  • PTZ and lens operations use authenticated local CGI endpoints.
  • No cloud account or EseeCloud relay is required.
  • The generic EseeCloud desktop UI exposes iris and auxiliary controls on models that may not contain the corresponding hardware. Firmware rejections are surfaced as Home Assistant action errors.

Development status

Version 0.1.3 has been validated with Home Assistant 2026.8.0b6 and one local EseeCloud/IP-Pro camera. Additional camera models and firmware reports are welcome through GitHub issues.