Home Assistant custom integration for Plejd — the Swedish Bluetooth-mesh lighting and relay system.
Status: Working. The BLE protocol (GATT, AES-128 crypto, mesh commands) and cloud login are fully decoded, and the core — lights, switches, scenes, buttons, motion/illuminance, and on-device scheduling (a scheduled scene was confirmed firing on real hardware) — is validated end-to-end against real hardware. Covers, climate, and the device-config entities are decoded from the app but not yet hardware-validated. Reverse-engineered entirely from our own analysis of the Plejd Android app + BLE capture; not affiliated with Plejd.
If you find this integration useful, you can buy me a coffee ☕
Plejd devices form a local Bluetooth mesh (no per-device IP API). This integration:
- Logs in to the Plejd cloud to fetch your site's crypto key, device list (BLE addresses, output addresses, device types), and whether the site has a Plejd Gateway (GWY-01). The gateway path also obtains short-lived access tokens from the cloud as needed.
- Controls the mesh over whichever transport fits, validated end-to-end on real hardware:
- Local Bluetooth — connects to one mesh device, which relays commands and state to the rest; payloads are AES-128 encrypted with the site key. Fully local, no internet. State arrives as LastChanged mesh broadcasts.
- Remote gateway — if your site has a GWY-01, commands and state are relayed through Plejd's cloud WebSocket, so control keeps working even when Home Assistant is out of Bluetooth range. State arrives as
mesh.outpushes.
It prefers the gateway when one exists and falls back to Bluetooth automatically. Both paths are push-based (no polling). iot_class is local_push.
- Home Assistant 2024.6 or newer with the Bluetooth integration available (a built-in adapter or an ESPHome Bluetooth proxy).
- A Plejd account (email + password) and at least one Plejd device.
Or manually:
- In HACS, go to Integrations → ⋮ → Custom repositories.
- Add
https://github.com/8408323/ha-plejdas an Integration. - Search for Plejd and click Download.
- Restart Home Assistant.
- Copy
custom_components/plejd/to your HAconfig/custom_components/directory. - Restart Home Assistant.
- Go to Settings → Devices & Services → Add Integration (a Plejd device in Bluetooth range is also auto-discovered).
- Search for Plejd.
- Sign in with your Plejd account; if you have more than one site, pick one. Your site's devices and crypto key are fetched once. On a site without a gateway, control then happens locally over Bluetooth with no internet needed; on a site with a GWY-01 it defaults to the remote gateway (cloud), falling back to local Bluetooth when the gateway is unreachable.
Devices, scenes, buttons and sensors appear automatically. Per-device tuning and schedules are added as entities (see below).
Go to Settings → Devices & Services → Plejd → Configure → Add a device. This wizard lives on the integration entry itself, not on any specific device (not the gateway, not a light) — so it works the same whether your site has a GWY-01 or not.
- Power up the new device; it broadcasts as unprovisioned over Bluetooth.
- Pick it from the list (address, model, signal strength).
- Give it a name (and optionally a new room). It's commissioned directly from Home Assistant — DH key exchange, mesh access address, node index — no need to open the Plejd app at all.
Prefer scripting it? The same logic is exposed as the plejd.add_device and
plejd.scan_new_devices services (Developer Tools → Actions), which the wizard
calls under the hood.
Entities are created automatically from your site:
- Lights ✅ — on/off + brightness for dimmers and LED drivers (DIM-01/02, LED-10/75, …)
- Switches / relays ✅ — CTR-01, REL-01/02, OUT-01/02
- Scenes ✅ — trigger Plejd scenes
- Buttons ✅ — wall switches / remotes (WPH-01, WRT-01) fire HA events (press / release) for automations
- Motion & illuminance ✅ — WMS-01 reports occupancy (
binary_sensor) and ambient light (sensor) - Covers — JAL-01 / MTR-01 blinds and shades (decoded; not hardware-validated)
- Climate — TRM-01 thermostats: target temperature + Plejd presets (decoded; not hardware-validated)
Per-output device settings (config entities):
- Minimum / maximum brightness —
numberentities that set a dimmer's range - Dimming curve — linear / logarithmic / anti-logarithmic (
select) - Phase dimming — leading / trailing edge, on phase-cut dimmers (
select)
On-device scheduling — Plejd devices can run weekly time→scene events from their own clock, so they keep firing even when Home Assistant is offline:
- A Sync clock button (and automatic sync on connect + daily) keeps device clocks correct.
- Add weekly schedules (day + time → scene) under the integration's Configure
dialog; each becomes a
switchyou can enable/disable. Prefer HA automations? Just don't add any — the choice is yours.
Astro (sunrise/sunset) schedules and firmware OTA are intentionally out of scope — Home Assistant's
sun-based automations cover the former, and OTA would require Plejd's proprietary firmware images.
The Plejd site crypto key is the master secret for your mesh. This integration keeps it in the Home Assistant config entry and never logs or transmits it. When filing issues, redact the crypto key, your account email, BLE addresses, and any capture artifacts. See SECURITY.md.
The integration is pure Python with no Home Assistant import needed to run the test suite:
uv sync --dev
uv run pytest tests/ -v --cov=custom_components/plejd --cov-fail-under=100
uv run ruff check custom_components/ tests/ tools/How the protocol was reverse-engineered (BLE GATT, crypto, mesh commands, cloud) is documented in docs/reverse_engineering.md. Contributions welcome — see CONTRIBUTING.md.
Not affiliated with or endorsed by Plejd. "Plejd" is a trademark of its owner. All protocol knowledge was obtained from our own analysis of the Plejd Android app. Use at your own risk. Licensed under MIT.