navien_smart_ha

KO | EN

gitlite — search

#php #monitoring #nodejs #pytorch #automation #python #reactjs #golang #swift #kotlin

navien_smart_ha

(★ 9)

경동나비엔 나비엔 스마트 앱 기기를 Home Assistant 에 연동하는 비공식 커스텀 통합

File Explorer

ZIP Download

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

경동나비엔 **나비엔 스마트** 앱에 등록된 기기를 Home Assistant 에 붙입니다.
공식 API 가 아니고, 앱이 쓰는 서버를 그대로 사용합니다.

---

## 무엇이 되나

| 기기 | 지원 |
| --- | --- |
| 숙면매트 — 단계형 | **됩니다.** 실기기(EME-500 싱글·더블) 검증 |
| 숙면매트 — 온도형 | **됩니다.** 실기기(EME-520/521) 검증 — 전원 · 온도 · 좌우 따로 끄기 |
| 숙면매트 — 사계절 | 난방·냉방·**계절 전환** 됩니다. 실기기(EMF520) 확인 |
| 환기청정 (에어원) | **됩니다.** 신형·구형 둘 다. **모델명으로는 못 가립니다** |
| 보일러 | 안 됩니다. 제보는 받습니다 |
| 월패드 · 로비폰 · 상업용 | 범위가 아닙니다 |

**확인한 것은 다섯 대입니다** — `EME-500`(단계형 싱글·더블) · `EMF520`(사계절·온도형) ·
`EME-520/521`(온도형 싱글·퀸).
나머지 모델은 구조가 같아 될 것으로 봅니다. 안 되면
[알려 주시면](#문제가-있거나-제보하실-때) 고칩니다.

**모델별 표를 코드에 넣지 않았습니다.** 서버가 알려주는 제어 방식과 값 범위를 따르므로
목록에 없는 모델도 동작할 가능성이 높습니다. 모르는 값이 오면 추측해 제어하지 않고
건너뛰며 로그에 이유를 남깁니다.

---

## 내 모델이 되나요?

**모델명으로 미리 알기 어렵습니다.** 아래 목록은 참고용이고, 확실한 것은 설치해
보는 것입니다 — 안 되면 이유가 로그에 남습니다. 앱에 Wi-Fi 로 등록돼 있으면 될
가능성이 높습니다.

### 숙면매트

| 계열 | 모델 |
| --- | --- |
| **카본** (Wi-Fi) | EME500 · EME501 · EME520 · EME521 · EME550S · EME551D · EME650D · EME651P · EME652P |
| **온수** (Wi-Fi) | EMW700 · EMW720 · EMW721 · EQM572 · EQM580 · EQM581 · EQM582 · EQM590 · EQM591 · EQM595 |
| **사계절** (Wi-Fi) | EMF440 · EMF450 · EMF500 · EMF501 · EMF510 · EMF520 · EMW750 · EMW751 · EMW753 |
| **온수** (Bluetooth) | EQM530 · EQM550 · EQM551 · EQM552 · EQM553 · EQM555 · EQM560 · EQM561 · EQM562 · EQM565 · EQM570 · EQM571 · EQH20/40DN — **안 됩니다** |

실기기로 확인한 것은 다섯 대입니다.

| 모델 | 확인된 것 |
| --- | --- |
| `EME-500` 싱글·더블 (단계형) | 전원 · 단계 · 좌우 따로 |
| `EMF520` (사계절·온도형) | 냉방 전환 · 냉방 온도 · 좌우 따로 |
| `EME-520/521` 싱글·퀸 (온도형) | 전원 · 온도 · **좌우 따로 끄기** |

**`EME-520` 과 `EME-521` 은 서버가 둘 다 `EME-520` 으로 알려줍니다.** 제보자에
따르면 싱글이 520, 퀸이 521 입니다. 저희는 모델명이 아니라 서버가 주는 제어
방식을 따르므로 둘 다 같게 동작합니다.

나머지는 구조상 될 것으로 봅니다.

### 환기청정 (에어원)

**모델명으로는 판단할 수 없습니다.** 저희도 이름이 아니라 기기가 알려주는
**모델코드**로 신형·구형을 가립니다. 앱 화면에서는 그 값이 안 보입니다.

**신형과 구형 둘 다 됩니다.** 설치하면 통합이 알아서 가리므로 모델명을 따져보지
않으셔도 됩니다.

#### 지금까지 확인된 것

| 모델 | 모델코드 | |
| --- | --- | --- |
| `NRT-530Z3` 룸콘 분리형 | 1901 | **됩니다** — 상태 · 제어 · 희망습도 |
| `NRT-530S3` 올인원 룸콘 | 1900 | **됩니다** — 상태 · 제어 · 공기질(아래 참고) |
| `NRT-20DSW` 구형 | 8 | **됩니다** — 전원 · 모드 6종 · 풍량 6종 · 재시작 복원 |
| `NRT-20DS` 구형 | 7 | **됩니다** — 전원 · 모드 6종 · 풍량 6종 |
| `NRT-20D` 구형 | 4 | **됩니다** — 모드 5종 (**바이패스 없는 모델**) |

**다섯 대 다 동작을 확인했습니다.** 그래도 다섯 대라 규칙을 말할 수는 없습니다.
지금까지는 `NRT-530` 계열이 신형(1900번대), `NRT-20D` 계열이 구형(한 자리)이었습니다.
다만 두 계열만 보고 「번호가 크면 신형」이라고 단정하지 않습니다.

> **바이패스는 기기마다 있고 없습니다.** 연식에 따라 나중에 추가된 기능이라
> 초기형에는 없습니다. 저희는 **있다고 확인된 모델에만** 그 모드를 만듭니다 —
> `NRT-20DS` · `NRT-20DSW` · `NRT-21DS` · `NRT-30` · `NTR-10PW`.
>
> **앱에는 바이패스가 보이는데 HA 에 없다면 알려 주세요.** 바로 넣습니다.

**목록에 없는 모델은 「모른다」입니다.** 안 된다는 뜻이 아닙니다.

> **공기질 값이 몇 시간씩 멈춰 있던 문제는 v0.14.7 에서 고쳤습니다**
> ([#1](https://github.com/ripe-avocado/navien_smart_ha/issues/1) — 해결).
>
> 기기가 실시간 메시지를 보낼 때마다 다음 조회 예약이 뒤로 밀려서, 메시지가 잦은
> 환기청정에서는 조회가 영영 돌지 않았습니다. CO₂ 와 습도가 유독 눈에 띈 이유는
> 그 둘이 제일 빨리 변하기 때문입니다 — 미세먼지·온도는 원래 느리게 움직여서
> 멈춘 티가 안 났습니다.

앱 `기기 추가` 에 나오는 계열은 이렇습니다 — `NRT530` · `NRZ530` · `NRT-30` ·
`NRT-21D` · `NRT-20D` · `NTR-10PW`. **이건 앱이 지원하는 목록이지 저희가 확인한
목록이 아닙니다.** 되든 안 되든 [알려 주시면](#문제가-있거나-제보하실-때) 위 표에
반영합니다.

에어모니터(`NAA` 계열)는 공기질 센서로만 쓰입니다. 올인원 룸콘은 룸콘에 센서가
들어 있어 에어모니터가 없어도 공기질이 나옵니다.

중대형(`NRT530 (2W)`)과 상업용 SCADA(`TAC` 계열)는 범위가 아닙니다.

#### 구형은 기여로 열렸습니다

구형은 명령 보내는 방식이 신형과 전부 다르고 **전원 값이 거꾸로**입니다. 저희에게
구형 기기가 없어 추측으로 열 수 없었습니다.

**구형 기기(`NRT-20DSW`)를 쓰시는 분이 실기기로 확인해 보내주셨습니다** —
[PR #7](https://github.com/ripe-avocado/navien_smart_ha/pull/7). 전원 · 운전 모드
6종 · 풍량 6종 · 재시작 후 상태 복원까지 그분 기기에서 동작을 확인했습니다.

**그 뒤 `NRT-20DS`(모델코드 7) 도 된다는 제보를 받았습니다.** 구형은 이제 두 대에서
확인됐습니다 — 모델코드가 달라도 같은 방식이 통한다는 뜻입니다.

**다만 두 대입니다.** 다른 구형 모델도 같은 방식인지는 여전히 모릅니다. 구형 기기를
쓰시면 [알려 주시면](#문제가-있거나-제보하실-때) 큰 도움이 됩니다 — 통계정보 파일
하나면 됩니다.

---

## 설치

**Home Assistant 2025.2 이상이 필요합니다.**

1. HACS → 사용자 지정 저장소에 이 저장소를 추가
2. `Navien Smart` 설치 후 Home Assistant 재시작
3. 설정 → 기기 및 서비스 → 통합 추가 → `Navien Smart`
4. 나비엔 스마트 앱 아이디와 비밀번호 입력

공간(home)이 여러 개면 고르는 화면이 나옵니다.

---

## 만들어지는 엔티티

**기기에 없는 기능은 엔티티도 안 생깁니다.** 다만 **전원은 매트에 언제나 생깁니다** —
서버가 「전원 제어 없음」이라고 알려주는 모델도 실제로는 됩니다(v0.17.0).

### 숙면매트 엔티티

| 엔티티 | 도메인 |
| --- | --- |
| 전원 | `switch` |
| 난방 온도 (온도형) | `climate` |
| 난방 단계 (단계형) | `select` |
| 계절 — 난방/냉방 (사계절) | `select` |
| 조작음 음량 | `select` — 음소거 · 1 · 2 · 3 단계. **기기 페이지 설정 칸에 있습니다** |
| 조작 잠금 | `switch` |
| 운전상태 · 오류 코드 | `sensor` |
| 고온경고 · 오류 | `binary_sensor` |

좌우 분리 모델은 온도·단계가 **좌/우 두 개**씩 생깁니다.

**사계절 모델은 「계절」 목록으로 난방↔냉방을 바꿉니다.** 실기기(EMF520)로 확인했습니다.
바꾸면 온도 범위가 함께 갈립니다(난방 28~45 · 냉방 20~35, 모델마다 다름).

**냉방에서도 좌우 온도를 따로 잡을 수 있습니다.** EMF520 제보에서 냉방 중
좌 25.0 · 우 25.5 로 서로 다르게 설정된 것을 확인했습니다. 저희는 **누르신 쪽에만
보내고** 기기가 돌려주는 값을 그대로 보여줍니다 — 묶여 도는 모델이라면 양쪽이 같은
값으로 옵니다.

**조작 잠금은 켜고 끌 수 있습니다.** 앱 제어 화면 자물쇠 버튼과 같습니다.
켜면 기기 본체 버튼이 잠깁니다.

단계형에 슬라이더를 쓰지 않은 이유는 `0` 이 숫자가 아니라 **운전 대기** 라서입니다 —
목록으로 고르면 앱과 같은 말을 씁니다.

**마지막 남은 한쪽은 끌 수 없습니다.** 자세한 것은 아래
[좌우 분리 매트의 전원 동작](#좌우-분리-매트의-전원-동작)을 봐 주세요.

### 환기청정 엔티티

| 엔티티 | 도메인 |
| --- | --- |
| 전원 | `switch` |
| 운전모드 · 풍량 | `select` |
| 희망습도 (제습 · 기본풍량) | `number` |
| 운전상태 · 오류 코드 · 필터 잔량 | `sensor` |
| 오류 | `binary_sensor` |
| 공기질 9종 | `sensor` — 에어모니터가 있으면 **별도 기기**에 |

**올인원 룸콘은 에어모니터 없이도 공기질이 나옵니다.** 룸콘에 센서가 들어 있습니다.

운전모드와 풍량 목록은 서버가 알려주는 조합만 씁니다. 습도 범위도 서버 값입니다.

**터보·절전에서는 희망습도가 「자동」이라 조절할 수 없습니다.** 앱도 같습니다 —
그 구간은 기기가 알아서 맞춥니다.

풍량에 「미풍·약풍·강풍」 대신 **「터보·절전」만 보이는 기기가 있습니다.**
전열교환기가 그렇고, 앱에서도 같습니다 — 그 기기에 풍량 단계가 없는 것입니다.

**휘발성유기화합물(TVOC)과 통합공기질은 단위 없이 숫자만 나옵니다.** 나비엔이
단위를 쓰지 않아 확인할 수 없었습니다. 라돈은 `Bq/㎥` 입니다(국내 기준 148 Bq/㎥).
등급(좋음/보통/나쁨)은 각 센서의 `grade` 속성에 있습니다.

---

## 알아두실 것

### 좌우 분리 매트의 전원 동작

**가장 많이 들어오는 질문이라 따로 적습니다.** 좌우 분리 매트는 이렇게 동작합니다.

| 조작 | 결과 |
| --- | --- |
| 한쪽 켜기 (전원 꺼진 상태에서) | 켜집니다. **전원도 같이 켜집니다** |
| 한쪽 끄기 (양쪽 다 켜진 상태에서) | 그쪽만 꺼집니다 |
| **마지막 남은 한쪽 끄기** | **안 꺼집니다.** 「전원을 종료해 주세요」 안내가 뜹니다 |
| 전부 끄기 | **전원 스위치**를 눌러 주세요. 한 번에 꺼집니다 |

**마지막 한쪽이 안 꺼지는 것은 기기의 규칙입니다.** 나비엔 앱에서 같은 조작을
해도 똑같은 안내가 뜹니다. 제품 설명서에도 「좌/우 동시 OFF 설정은 불가하며 해당
동작은 전원 끄기로 가능합니다」라고 적혀 있습니다.

**「그냥 전원까지 꺼주면 안 되나요」** — 두 분이 요청하셨던 것인데, 넣지 않기로
했습니다. 이 매트는 **전원을 켜면 좌우가 모두 켜지는 습성**이 있습니다(실기기
확인). 한쪽만 쓰시다가 저희가 전원을 대신 꺼드리면, 다음에 켤 때 안 쓰던 쪽까지
매번 켜집니다. 앱이 이 동작을 막아둔 이유도 그것으로 보입니다.

켤 때 전원이 같이 켜지는 것은 반대로 저희가 넣은 동작입니다 — 앱은 전원이
꺼지면 온도 버튼을 아예 눌리지 않게 막지만, HA 카드는 항상 눌리기 때문에
누르면 켜지도록 했습니다.

### 기기 조작이 즉시 반영됩니다

리모컨이나 본체로 바꿔도 바로 나타납니다. 기기가 상태를 스스로 올리기 때문입니다.
재시작 후에도 1~2초 안에 채워집니다.

**꺼져 있는 기기는 `사용할 수 없음` 으로 남습니다.** 전원을 켜면 채워집니다.

### 공기질 수치는 5분마다 갱신됩니다

**공기질만 실시간이 아닙니다.** 전원 · 모드 · 풍량은 기기가 스스로 올려주지만,
미세먼지 · CO₂ 같은 수치는 저희가 서버에 물어봐야 합니다.

나비엔 앱도 똑같이 물어봅니다. 다른 건 주기뿐입니다.

| | 나비엔 앱 | 이 통합 |
| --- | --- | --- |
| 주기 | 1분 | **5분** |
| 언제 | 공기질 화면을 **보는 동안만** | 24시간 |
| 하루 요청 수 | 화면 10분 → 10회 | 288회 |

**5분인 이유는 24시간 돌기 때문입니다.** 1분으로 당기면 하루 1,440번이 되는데,
비공식 통합이 나비엔 서버에 그만큼 부담을 주면 막힐 수 있습니다.

**지금 값을 보고 싶으실 땐 언제든 즉시 새로고침됩니다.**

기기 화면의 ⋮ → `새로고침`, 또는 자동화에서 `homeassistant.update_entity` 를
부르시면 기다리지 않고 곧바로 읽어옵니다.

**다만 반복해서 부르시면 5분에 한 번으로 묶입니다.** 10초짜리 자동화를 걸어도
5분마다만 나갑니다. 비공식 통합이라 나비엔 서버에 기본값보다 무거운 부담을
주지 않도록 막아 두었습니다. 한 번씩 누르는 것은 제한이 없습니다.

### 나비엔 앱을 열면 HA 가 잠깐 밀려납니다

**한 계정에 세션이 하나뿐입니다.** 앱을 열면 HA 세션이 끊기고, HA 가 다음 조회 때
자동으로 다시 로그인하면서 이번엔 앱이 로그아웃됩니다.

**쓰는 데 큰 지장은 없습니다** — 통합이 알아서 복구합니다. 다만 앱을 보는 동안
HA 화면이 멈춰 보입니다.

불편하면 **가족 공유**로 계정을 나누시면 됩니다(집주인이 초대 → 그 계정으로 HA 로그인).
다만 계정 생성에 본인인증이 필요해서 혼자 쓰시면 어렵습니다. 필수가 아닙니다.

### 로컬(랜)로는 제어할 수 없습니다

기기가 **열린 포트를 하나도 두지 않습니다**(TCP 전 범위 실측). 앱조차 기기와 직접
통신하지 않고 클라우드를 거칩니다. 그래서 **인터넷이나 나비엔 서버가 끊기면 HA 에서도
제어할 수 없습니다.**

### 그 외

- 블루투스 전용 매트는 폰과 직접 통신해서 **안 됩니다.** 앞으로도 계획이 없습니다
- **고온경고는 경고일 뿐 제한이 아닙니다.** 1~8단계 전부 설정할 수 있습니다
- 비밀번호를 5회 틀리면 나비엔이 재설정을 요구합니다. 통합은 오류만 알립니다

---

## 문제가 있거나 제보하실 때

**`통계정보 다운로드` 한 번이면 됩니다.** 무엇을 붙여야 할지 고민하지 않으셔도 됩니다.

설정 → 기기 및 서비스 → **나비엔 스마트** → ⋮ → `통계정보 다운로드`

기기ID · IP · MAC · SSID · 아이디 · **별칭**이 자동으로 가려집니다. 통신 주소처럼
**값 안에 식별자가 섞여 있는 항목도** 함께 가려집니다.

[이슈 남기기](https://github.com/ripe-avocado/navien_smart_ha/issues/new/choose)

| 양식 | 언제 |
| --- | --- |
| 환기청정 제보 | 에어원을 쓰실 때 — **되든 안 되든**. 값이 비어 있으면 **한 번 조작한 뒤** |
| 사계절 냉방 제보 | 사계절 매트를 **냉방으로 켜고 온도를 바꿔 보신 뒤** |
| 보일러 제보 | 보일러를 쓰실 때 |
| 버그 신고 | 연동됐는데 동작이 이상할 때 |

---

## 시험

```bash
python3 tests/run.py
```

**Home Assistant 를 설치하지 않아도 돌아갑니다.** 파이썬만 있으면 됩니다.
자세한 것은 [`tests/README.md`](tests/README.md) 를 봐 주세요.

---

## 개발자용 CLI

`tools/navien_cli.py` — HA 없이 서버 응답을 직접 확인합니다. 파이썬 표준 라이브러리만
씁니다. **이슈에는 위 통계정보 파일만 붙이시면 되고, CLI 는 안 쓰셔도 됩니다.**

```bash
python3 tools/navien_cli.py login
python3 tools/navien_cli.py devices        # 기기목록 + 기능 메타데이터
python3 tools/navien_cli.py watch          # 실시간 수신 (paho-mqtt 필요)
python3 tools/navien_cli.py airone-modes --device-seq N   # 환기청정 지원 조합
```

`control` · `airone-control` · `airone-status` 는 **실기기에 명령을 보냅니다.**
`--yes` 를 붙이지 않으면 보낼 내용만 출력하고 끝납니다.

---

## 라이선스

MIT. 이 프로젝트는 경동나비엔과 무관하며 앱 동작을 분석해 만든 비공식 통합입니다.
[kyle-seongwoo-jun/homebridge-navien-smart](https://github.com/kyle-seongwoo-jun/homebridge-navien-smart)
의 인증 흐름 분석을 참고했습니다.

navien_smart_ha

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README