homeassistant-dkncloudna/docs/plans/2026-03-29-hacs-plugin-design.md

DKN Cloud NA — Home Assistant Integration: Design

Date: 2026-03-29 Status: Approved Scope: Scaffolding only — no live Daikin API calls yet

---

Background

This integration ports the homebridge-dkncloudna plugin to Home Assistant as a HACS custom integration. It targets Daikin mini-split AC systems connected via the DKN Cloud NA WiFi adapter.

The EU counterpart DKNCloud-HASS (airzone) provided reference patterns for coordinator structure, config flow hygiene, and optimistic overlays. We diverge where the NA API differs or where simpler approaches suffice.

---

Source References

• Homebridge plugin (NA): /Users/slavoie2/src/github.com/plecong/homebridge-dkncloudna
• EU HA reference: /Users/slavoie2/src/github.com/eXPerience83/DKNCloud-HASS
• Target repo: https://github.com/lavoiesl/homeassistant-dkncloudna

---

Architecture

Config Entry
  data:    { username }
  options: { user_token, refresh_token, scan_interval, expose_pii }
      ↓
DknCoordinator  (DataUpdateCoordinator, default 60s)
      ↓
DknCloudNaClient  (login, token refresh, fetch_installations)
      ↓
Platforms: climate · sensor · binary_sensor

Key decisions:

• Cloud polling only — no Socket.IO. Simpler, more maintainable, idiomatic for HA cloud integrations.
• 60s default poll interval — reasonable for an AC unit; configurable 30–300s.
• Password never persisted — cleared after login; only tokens stored in entry.options.
• Optimistic overlays — 2.5s TTL bridges write→poll latency, borrowed from EU reference.
• Per-device async locks — serializes concurrent writes per device.

---

DKN Cloud NA API (from homebridge plugin)

Base URL: https://dkncloudna.com/api/v1

Endpoint	Method	Purpose
/auth/login/dknUsa	POST	Login (email + password → token + refreshToken)
/users/isLoggedIn/dknUsa	GET	Validate token
/auth/refreshToken/{refreshToken}/dknUsa	GET	Refresh expired token
/installations/dknUsa	GET	Fetch all installations + devices

Auth: Bearer token. User-Agent spoofs iPhone iOS 15.5 (required by the API).

Device control: Socket.IO create-machine-event — deferred to implementation phase.

---

File Structure

custom_components/dkncloudna/
├── __init__.py          # async_setup_entry, async_unload_entry
├── manifest.json        # domain, codeowners, version, iot_class
├── const.py             # DOMAIN, BASE_URL, API paths, timing constants
├── api.py               # DknCloudNaClient (stub)
├── coordinator.py       # DknCoordinator (stub data)
├── config_flow.py       # user → token_display → options / reauth
├── entity.py            # DknEntity base class (CoordinatorEntity)
├── climate.py           # DknClimateEntity stub
├── sensor.py            # DknSensorEntity stubs
├── binary_sensor.py     # DknBinarySensorEntity stubs
├── strings.json         # mirrors en.json
└── translations/
    └── en.json          # config flow + entity strings

hacs.json
README.md
.github/workflows/validate.yml

---

Config Flow

Steps

1. user — email, password, scan_interval (30–300s, default 60)
2. token_display — shows access_token + refresh_token read-only (skipped if expose_pii=False)
3. Options flow — scan_interval, expose_pii toggle
4. Reauth — re-presents user step; clears password after new token obtained

Data storage

• entry.data: { username }
• entry.options: { user_token, refresh_token, scan_interval, expose_pii }
• Password: never stored, cleared immediately after token exchange

---

Entities Per Device

Climate (1 per device)

• HVAC modes: OFF, COOL, HEAT, AUTO, DRY, FAN_ONLY
• Features: TARGET_TEMPERATURE, FAN_MODE, SWING_MODE, TURN_ON, TURN_OFF
• Dynamic: TARGET_TEMPERATURE hidden in DRY / FAN_ONLY / OFF modes
• Unique ID: dkncloudna_{mac}

Sensors (per device)

Entity	Key	Unit	Category	Default
Room temperature	work_temp	°C	—	enabled
Exterior temperature	ext_temp	°C	—	disabled
WiFi signal	stat_rssi	dBm	diagnostic	enabled
Error code	error_ascii1/2	—	diagnostic	enabled

Binary sensors (per device)

Entity	Key	Category
Connected	isConnected	diagnostic
Machine ready	machineready	diagnostic

---

Patterns from EU Reference (Adopted)

Pattern	Source	Notes
Optimistic overlay (2.5s TTL)	EU ref	Bridges write→poll latency
Per-device asyncio.Lock	EU ref	Serializes concurrent writes
Password cleared post-login	EU ref	Security hygiene
Reauth on 401	EU ref	Standard HA pattern
Dynamic supported_features	EU ref	Mode-aware feature set
Backoff + jitter retry	EU ref + homebridge	Robust API resilience

Patterns Omitted

Pattern	Reason
persistent_notification	Legacy — use HA issue API in future
Switch entity (power proxy)	Redundant with climate turn_on/off
Number entities (sleep/unoccupied)	NA API has no such concepts
40+ sensor dump	Only expose meaningful entities

---

README Sections

1. What it is + supported devices
2. Prerequisites (DKN Cloud NA account)
3. Installation via HACS
4. Configuration walkthrough (config flow steps)
5. Entities reference table
6. Known limitations & roadmap
7. Credits (homebridge plugin by @plecong, EU reference by @eXPerience83)

---

Validation CI

Two jobs in .github/workflows/validate.yml:

• hassfest — validates manifest against HA schema
• hacs — validates HACS requirements (with ignore: brands until icon added)