# Connecting IKEA ALPSTUGA to Home Assistant via Matter over Thread

## Using Sonoff ZBDongle-E with MultiPAN (Zigbee + Thread on a single dongle)

**Date:** March 2026
**Tested with:** HA OS 16.2, HA Core 2025.10.3, Silicon Labs Multiprotocol Add-on 2.4.5, Matter Server 8.3.0

---

## Prerequisites

- Sonoff ZBDongle-E (EFR32MG21 chip)
- IKEA ALPSTUGA air quality sensor
- Home Assistant with HAOS
- Android or iOS phone with HA Companion App
- Chrome or Edge browser (for firmware flashing)

---

## Step 1: Flash MultiPAN RCP Firmware on ZBDongle-E

The dongle ships with Zigbee-only firmware. You need MultiPAN RCP to run both Zigbee and Thread.

**CRITICAL:** Use the **darkxst web flasher**, NOT the Sonoff flasher. The Sonoff flasher ships GSDK 4.6+ firmware (CPC Protocol v5) which is incompatible with the HA Multiprotocol add-on (CPCd v4.3.1, Protocol v4).

1. Stop any Zigbee integration (ZHA/Z2M) using the dongle
2. Open Chrome/Edge and go to: https://darkxst.github.io/silabs-firmware-builder/
3. Connect the dongle, click **Connect**, select your dongle
4. Select **Change Firmware** → **Multi-PAN (RCP)**
5. Verify the firmware version is **GSDK 4.3.x** (Protocol v4) — if only v5 is available, download `rcp-uart-802154-v4.3.1-zbdonglee-115200.gbl` from the darkxst GitHub repo and use "Upload Custom"
6. Flash the firmware

**If you get Protocol v5 vs v4 mismatch later:** You flashed the wrong firmware version. Re-flash with GSDK 4.3.x.

---

## Step 2: Install Silicon Labs Multiprotocol Add-on

This add-on is deprecated but still functional for small setups.

1. In HA: **Settings → Add-ons → Add-on Store**
2. Search for **Silicon Labs Multiprotocol** (may need to add the repo `https://github.com/home-assistant/addons` manually)
3. Install the add-on (v2.4.5)
4. Go to **Configuration** and set:
   - **Device:** select your ZBDongle-E serial path
   - **Baudrate:** `115200`
   - **Hardware flow control:** `disabled` (false)
   - **Enable OpenThread Border Router:** `true`
   - **OTBR firewall:** `false` (avoids potential commissioning issues)
   - **Automatic firmware flash:** `false`
5. Under **Show disabled ports**, enable port **8081** (map to any free port like 8443 if 8081 is taken) — this exposes the OTBR web UI
6. Save and start the add-on

**Expected log output:**
```
Connected to Secondary
Secondary Protocol v4
Secondary CPC v4.3.1
Daemon startup was successful. Waiting for client connections
otbr-agent: Role detached -> leader
BackboneAgent: Backbone Router becomes Primary!
```

---

## Step 3: Align Zigbee and Thread Channels

With MultiPAN on a single radio, **both protocols MUST use the same channel**. If ZHA is on channel 25 and Thread defaults to channel 15, neither will work.

**Check ZHA channel:**
Settings → Devices & Services → ZHA → Network settings → note the channel number.

**Change Thread channel to match ZHA:**

1. Open the OTBR web UI in your browser: `http://<HA-IP>:<exposed-port>/` (e.g., `http://192.168.0.107:8443`)
2. If Thread is already running, disable it first via SSH or REST API:
   ```bash
   curl -X POST http://<HA-IP>:<port>/node/disable
   ```
3. In the OTBR web UI, click **Form**
4. Set **Channel** to match your ZHA channel (e.g., 25)
5. Set a **Network Name** (e.g., `ha-thread-imre`)
6. Leave **Network Key**, **Extended PAN ID**, **PAN ID** blank for auto-generated secure values, OR set custom values (avoid defaults like `1234`)
7. Click **Form**

**If you get a 409 error via REST API:** The Thread network is still active. Disable it first, then set the channel, then re-enable.

---

## Step 4: Set Up ZHA (Zigbee)

1. Go to **Settings → Devices & Services → Add Integration → Zigbee Home Automation (ZHA)**
2. When asked for Serial Device Path, choose **Enter Manually**
3. Select **EZSP** as radio type
4. Enter: `socket://core-silabs-multiprotocol:9999`
5. Re-pair your Zigbee devices

---

## Step 5: Set Up Thread and Matter Integrations

1. **Thread integration:** Settings → Devices & Services → Add Integration → Thread (should auto-discover)
2. **OTBR integration:** Should auto-discover. If not, add manually with URL: `http://core-silabs-multiprotocol:8081`
3. Verify Thread integration shows the correct channel (matching ZHA) and no channel mismatch warning
4. **Matter Server add-on:** Settings → Add-ons → Install Matter Server → Start
5. **Matter integration:** Settings → Devices & Services → Add Integration → Matter → accept default `ws://core-matter-server:5580/ws`

---

## Step 6: Sync Thread Credentials to Phone (CRITICAL)

**This is the step most people miss and it causes commissioning to fail.**

On your phone, open the HA Companion app:

- **Android:** Settings → Companion App → Troubleshooting → **Sync Thread credentials**
- **iOS:** Settings → Companion App → Thread → verify credentials are present

The regular "Send credentials" button in the Thread integration often fails — use the Troubleshooting path instead.

---

## Step 7: Pair the ALPSTUGA

1. **Factory reset the ALPSTUGA:** Press and hold the system button for **10 seconds** until the red LED stops blinking. It will restart and enter pairing mode for 15 minutes (white LED pulses slowly).
2. On your phone, make sure **Bluetooth is ON** and you're connected to your **home WiFi** (same network as HA)
3. Keep the phone, ALPSTUGA, and the dongle **within a few meters** of each other
4. In the HA Companion app: **Settings → Devices & Services → Matter → Add Device**
5. Scan the **Matter QR code** (on the bottom of the ALPSTUGA or the packaging leaflet)
6. Wait — it can take 3-5 minutes. Don't cancel prematurely.
7. Success: white LED on ALPSTUGA blinks twice

**If it fails:** Factory reset the ALPSTUGA again and retry. Multiple attempts are normal — this is a known issue with IKEA Matter-over-Thread devices.

---

## Post-Setup

### Clock Sync
The ALPSTUGA clock won't sync automatically from HA. Install **Matter Time Sync** from HACS to set up automated clock syncing.

### Expected Entities
- CO2 (ppm)
- PM2.5 (µg/m³)
- Temperature
- Humidity
- Display on/off switch (shows as "outlet" — known cosmetic bug)

### Known Issues
- Device may go unavailable after ~30 minutes of idle (IKEA firmware issue, awaiting update)
- Clock resets on power cycle (no internal battery)
- Display switch shows as "outlet" instead of "switch"

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `Secondary Protocol v5 doesn't match CPCd Protocol v4` | Flash older MultiPAN firmware (GSDK 4.3.x) via darkxst flasher |
| `Failed to connect, secondary seems unresponsive` | Check baudrate (115200), disable hardware flow control, verify MultiPAN firmware is flashed |
| Channel mismatch warning | Align Thread and ZHA to the same channel via OTBR web UI |
| "Commission new Thread device" greyed out | Restart Matter Server add-on; verify Thread integration has credentials |
| Phone can't commission device | Sync Thread credentials via Companion App → Troubleshooting |
| ALPSTUGA won't pair | Factory reset (hold 10s), retry multiple times, stay close to border router |
| OTBR REST API returns 409 | Disable Thread node first, then modify dataset, then re-enable |
| `ipset` errors in OTBR logs | Set `otbr_firewall` to false in Multiprotocol add-on config |