Home Assistant integration (HACS)

Yunkan now ships an official Home Assistant custom integration. It is a thin client that talks to your Yunkan server over its regular API and maps it onto native Home Assistant entities, a media browser and services — all recording, detection and account logic stays on the server.

Opens this repository in your Home Assistant's HACS as a custom repository.

What you get

• Cameras with native WebRTC (low-latency, HLS fallback) and JPEG snapshots — picture-glance cards, area dashboards, HomeKit export and camera.snapshot.
• Detection sensors per camera — person, vehicle, animal, package, face, fall, baby-cry and motion — carrying the recognised name / licence plate.
• Object-count sensors plus recognised face / plate sensors.
• Switches — AI detection, recording, per-feature detection toggles, PTZ auto-tracking — plus server-wide detection switches on the hub.
• Device-page controls — refresh-snapshot and PTZ direction buttons, a PTZ preset dropdown and a voice-broadcast field.
• Device triggers and actions for automations, plus a ready-made notification blueprint.
• Media browser for recordings, events and snapshots, proxied through Home Assistant's own authentication.

Requirements

• Home Assistant 2024.11 or newer (for native WebRTC cameras).
• A reachable Yunkan server — use its main entry address (the nginx entry, usually port 23406).
• A Yunkan account. An admin account is required for PTZ, the detection switches and voice broadcast; viewing works with any account.

Install via HACS

1. 1

   Open in HACS

   Click the Open in HACS button above (or, in HACS, open the three-dot menu → Custom repositories and add the repository URL with category *Integration*).

2. 2

   Install and restart

   Search for Yunkan in HACS, install it, then restart Home Assistant.

3. 3

   Add the integration

   Go to Settings → Devices & Services → Add Integration → Yunkan and enter your server URL. Home Assistant then opens Yunkan's sign-in page: sign in the way you normally do, then click Authorize. The next section covers this in detail.

How it connects: one click to authorize in Yunkan

The current integration does not ask you for a password. When you add it you only enter the Yunkan server address; Home Assistant then opens Yunkan's own sign-in page, you sign in the way you normally do (password, code, passkey or single sign-on — any of them), and click "Authorize". Yunkan hands Home Assistant a token of its own, and your password never leaves your side.

• Accounts with two-step verification on connect fine — the signing-in part happens on Yunkan's own page, and that is where the code goes.
• You can disconnect at any time — the token is listed under Settings → API Tokens, with Home Assistant in its name. Delete it and the integration loses access immediately. To restore it, run through the authorization again in Home Assistant.
• Older Yunkan servers have no authorization page — the integration falls back to asking for a username and password, exactly as before. That route cannot connect to an account with two-step verification on, so update the server first.

Free tier vs Pro

Cameras, snapshots, events, sensors, the media browser and PTZ work on any Yunkan server. AI detection and voice broadcast are Pro features; on a free-tier server those actions surface an upgrade notice instead of failing silently.