DKN Cloud NA — Home Assistant Integration

Control your Daikin mini-split air conditioners through Home Assistant using the DKN Cloud NA cloud service.

This integration is a port of the homebridge-dkncloudna plugin by @plecong, adapted for Home Assistant.

---

Supported Hardware

Any Daikin mini-split system connected to the DKN Cloud NA WiFi adapter (North America). The adapter must be set up and working in the official DKN Cloud NA mobile app before using this integration.

---

Prerequisites

• A working DKN Cloud NA account
• Your Daikin unit(s) already set up and visible in the DKN Cloud NA app
• Home Assistant 2024.1 or later

---

Installation

This integration is installed manually — it is not published to HACS.

1. Download or clone this repository
2. Copy the custom_components/dkncloudna/ directory into your Home Assistant config/custom_components/ directory, so that you end up with config/custom_components/dkncloudna/manifest.json
3. Restart Home Assistant

To upgrade, replace the dkncloudna directory with the newer copy and restart again.

---

Configuration

1. Go to Settings → Devices & Services → Add Integration
2. Search for DKN Cloud NA
3. Enter your DKN Cloud NA email and password
4. Optionally adjust the scan interval (default: 60 seconds)
5. Optionally enable Show tokens after login to view your access and refresh tokens

All discovered devices are added automatically.

---

Entities

Each device exposes the following entities:

Entity	Type	Description
AC unit	climate	On/off, mode (auto/cool/heat/dry/fan), target temperature, fan speed, swing
Room temperature	sensor	Current room temperature (°C)
Exterior temperature	sensor	Outdoor temperature (°C) — disabled by default
Wi-Fi signal	sensor	RSSI in dBm — diagnostic
Error code	sensor	Active error code — diagnostic
Connected	binary_sensor	Whether the device is online — diagnostic
Machine ready	binary_sensor	Whether the device is ready to receive commands — diagnostic

---

How It Works

• Authentication. The integration exchanges your DKN Cloud NA credentials for access + refresh tokens on first setup, then uses the refresh token to keep the session alive. Refreshed tokens are persisted to the config entry so they survive restarts.
• Device discovery and polling. All installations and their devices are fetched from the REST API on a configurable interval (default 60 seconds). The poll establishes the device list and acts as a heartbeat against the cloud.
• Live updates via Socket.IO. While the integration is running, it maintains a Socket.IO connection to dkncloudna.com and applies device-data events to entity state in near real-time — no waiting for the next poll cycle.
• Control via Socket.IO. Mode, target temperature, fan speed, and swing commands are sent as Socket.IO machine events. Local changes are reflected optimistically in Home Assistant and reconciled when the cloud echoes the new state back.
• Temperature units. Home Assistant always presents temperatures in Celsius. Devices reporting in Fahrenheit are transparently converted in both directions — values you set in HA are sent to the device in its native units.

Known Limitations

• Reauthentication is required if your refresh token expires (e.g. you change your DKN Cloud NA password). Home Assistant will surface a "Reconfigure" prompt when this happens.
• Multi-zone systems are exposed as one climate entity per indoor unit; there is no aggregate "installation" entity.

---

Development

CI runs on Gitea Actions (.gitea/workflows/ci.yml). To reproduce it locally:

pip install ruff==0.16.8       # version is pinned in CI
ruff check .
ruff format --check .
python3 scripts/validate_integration.py

scripts/validate_integration.py checks that every JSON file parses, that manifest.json has the keys Home Assistant requires of a custom integration, and that each file in translations/ has the same key structure as strings.json.

smoke-test/run.sh exercises the client against a real DKN Cloud NA account. It needs a .env with DKN_CLOUD_NA_EMAIL and DKN_CLOUD_NA_PASSWORD (see .env.example) and is run by hand, not in CI.

---

Credits

• Original Homebridge plugin: homebridge-dkncloudna by @plecong
• EU counterpart inspiration: DKNCloud-HASS by @eXPerience83