Home Assistant add-on 베타버전 릴리즈

Developing Home Assistant add-on: Release beta version

홈어시스턴트(Home Assistant, HA) 애드온을 겨우겨우 쓸만하게 만들었다 ^^;;

https://github.com/YOGYUI/homeassistant-addons

GitHub - YOGYUI/homeassistant-addons: My Home Assistant Addon(s)

힐스테이트 광교산용 RS-485 파이썬 코드를  HA에서 자동 실행하는 방법 중 가장 HA스러운(?) 솔루션이랄까.. 

 

이미 개발되어 있는 파이썬 어플리케이션을 HA 베이스 도커(docker) 컨테이너에 임베딩하는게 전부인데, 어플리케이션 설정(기존의 config.xml)을 어떻게 하면 더 쉽게 수정할 수 있을까 요리조리 짱구를 굴리다보니 개발 일정이 많이 늘어져버렸다 ㅎㅎ... 딱히 데드라인을 정해놓고 개발하고 있던게 아니기도 하고 ^^;;

 

Ingress를 제대로 활용하려면 nginx도 적절하게 설정해줘야되는데, 어차피 웹 프론트엔드 개발 자체에 의욕이 없기 때문에 애드온의 options로 앱 구동에 필요한 파라미터들을 설정할 수 있게 해줬다 ㅎㅎ

- 파이썬 앱 정상 구동 여부만 확인 완료
- 애드온을 별도로 홍보하진 않을 계획 (블로그 방문자 중 관심있는 유저만 설치해 사용 후 문제 발생시 이슈 처리)

 

마크다운 문서로 애드온 사용법은 간략하게 기재해뒀는데, 블로그에도 사용 방법을 간단하게 포스팅하도록 한다

※ HA Core 2024.2.2, Supervisor 2024.03.0, OS 11.5 버전에서 설치 및 구동 테스트했으며, 다른 버전에서는 구동하지 않을 가능성이 존재함

1. 애드온 설치

Home Assistant 웹페이지 - 설정 - 애드온 클릭

 

화면 우측 하단 애드온 스토어 클릭

 

화면 우측 상단 팝업 메뉴 - 저장소 클릭

 

저장소 주소에 다음 URL 입력 후 추가하기 버튼 클릭

https://github.com/YOGYUI/homeassistant-addons

 

YOGYUI 저장소가 추가된 것을 확인 후 닫기 클릭

 

애드온 스토어에서 YOGYUI 항목 검색 후 HomeNetwork for Hillstate 항목 클릭

※ 결국 애드온 이름은 안바꿨다 -_-;;

 

설치하기 클릭

※ 400MB 가량의 도커 이미지를 다운로드받은 뒤 설치하기 때문에 5~10분 정도 기다려야 한다 (HA가 구동중인 환경에 따라 시간은 상이함) 

 

설치가 완료되면 아래와 같이 애드온을 실행할 준비가 완료된다

※ 성급하게 시작하지 말자 (애드온 설정을 해줘야 하며, 아래 글을 계속 읽으면 된다)

※ AppArmor와 Ingress를 활성화해 가장 높은 보안 등급인 8등급(가장 안전하고 가장 낮은 위험)을 달성했다! 릴리즈하기에 무리없다랄까?

2. 애드온 설정

애드온을 본격적으로 시작하기 전에 MQTT 브로커랑 RS-485 컨버터 등 이것저것 미리 설정해둬야 할 게 있으니 꼼꼼하게 설정해주자 > 설정은 애드온의 구성 탭에서 진행

2.1. MQTT 브로커 설정

 

애드온이 설치된 HA에 Mosquitto MQTT 브로커 애드온을 설치해 사용할 계획이라면 호스트(host)는 core-mosquitto로 그대로 두고 아이디(username)와 비밀번호(password)만 변경해주자 (만약 포트번호를 바꿨다면 port도 적절하게 수정) 

※ 동일 호스트라고 하여 127.0.0.1을 입력하면 동작하지 않는다

mosquitto broker의 호스트명은 'core-mosquitto'

 

만약 다른 환경에서 구동중인 브로커를 사용하고자 할 경우 IP주소를 입력해주면 된다

paho-mqtt의 SSL 보안 접속 기능은 아직 구현하지 않은 상태
만약 유저의 요청이 있다면 추가 개발할 계획

2.2. RS-485 컨버터 설정

USB-to-RS485 컨버터를 사용할 지 혹은 EW-11 같은 WiFi-to-RS485 컨버터를 사용할 지 여부에 따라 설정 방법이 조금 다르다

[공통사항]

• name: 컨버터 이름, 앱 로그에 찍히는 이름으로 아무렇게나 구별되게만 지으면 된다 (컨버터 여러개 쓸 경우 구분하기 위한 용도)
• index: 0 이상의 숫자로, 컨버터를 여러 개 쓸 경우 반드시 1씩 증가하게 값을 지정해야 한다 (0부터 시작)
  아래에 나오는 파서 매핑 시 필요한 값이다
• enable: 컨버터를 어플리케이션이 사용할 지 여부로, 디버깅 등 특별한 경우가 아니라면 true로 설정
• hwtype: 0은 USB 컨버터 (시리얼 통신), 1은 WiFi 컨버터 (TCP 소켓 통신)
  USB-to-RS485 컨버터는 0으로 설정하고, EW-11은 1로 설정하면 된다 (EW-11 외 다른 컨버터도 지원)
• packettype: 0은 일반 포트용, 1은 주방 비디오폰 용

[hwtype=0 일 경우]

• serial: HA가 설치된 PC가 인식하는 컨버터의 시리얼 포트명을 기입 (예: /dev/ttyUSB0)
• baudrate: 보레이트, 현대통신은 보통 9600을 사용하면 되는데, 주방 비디오폰의 경우 3840을 사용해야 하니 주의
• databit: 5, 6, 7, 8 중 하나로, 8을 사용하면 된다
• parity: "N", "O", "P" (None, Odd, Even) 중 하나로, 현대통신은 "N"을 사용하면 된다
• stopbits: 1, 1.5, 2 중 하나로, 1을 사용하면 된다
• socketaddr, socketport는 사용되지 않으나 값은 반드시 기입해야 한다 (각각 문자열 및 숫자)

[hwtype=1 일 경우]

• socketaddr: EW-11의 IP주소를 입력한다 (예: 192.168.0.100)
• sockerport: EW-11의 TCP 포트를 입력한다 (EW-11의 디폴트값은 8899)
• serial, baudrate, databit, parity, stopbits는 사용되지 않으나 값은 반드시 기입해야 한다

EW-11의 경우 TCP 소켓 통신만 지원한다 (UDP 등 다른 프로토콜에 대해서는 유저의 요구사항이 있을 때 구현 예정)

 

[컨버터를 여러개 쓸 경우]

여러 개의 컨버터를 써야 하는 홈네트워크 환경도 있는데, 이를 지원한다

※ 나는 EW-11 2개를 월패드에 연결하고, USB 컨버터를 주방 서브폰에 연결해 총 3개를 사용중

아래 예시와 같이 하이픈(-)으로 설정을 한개 더 추가해주면 된다

- name: port1
  index: 0
  enable: true
  hwtype: 0
  packettype: 0
  serial: /dev/ttyUSB0
  baudrate: 9600
  databit: 8
  parity: "N"
  stopbits: 1
  socketaddr: 127.0.0.1
  socketport: 8899
- name: port2
  index: 1
  enable: true
  hwtype: 1
  packettype: 0
  serial: /dev/ttyUSB0
  baudrate: 9600
  databit: 8
  parity: "N"
  stopbits: 1
  socketaddr: 192.168.0.10
  socketport: 8899

index 0 컨버터는 /dev/ttyUSB0 시리얼 컨버터를 사용, index 1 컨버터는 192.168.0.10 IP 주소를 할당받은 EW-11을 사용

2.3. RS-485 패킷 파서 매핑 설정

각각의 디바이스가 위에서 설정한 컨버터 중 어떤 컨버터에서 패킷이 송수신되는지를 매핑해줘야 한다

만약 컨버터를 하나만 쓴다면 모두 0으로 설정하면 된다

※ 각 컨버터별로 담당하는 디바이스 종류에 대해 미리 알고 있어야 수월하게 설정할 수 있다

※ 값은 위에서 설정한 컨버터의 index 값을 매핑하면 된다

light: 0
outlet: 0
gasvalve: 1
thermostat: 1
ventilator: 1
elevator: 1
subphone: 2
batchoffsw: 1
hems: 2

우리집(힐스테이트 광교산)에서는 위와 같이 설정해야된다.. ㅎㅎ

2.4. 디바이스 자동 탐지 기능 설정

내 파이썬 어플리케이션이 자랑하는(?) 핵심 기능 중 하나인 디바이스 자동 탐색

activate를 true로 설정 후 애드온을 재시작하면 timeout 시간(단위=초)동안 디바이스를 자동으로 탐지하고 해당 디바이스들을 config.xml에 추가한 뒤 어플리케이션을 재시작하여 곧바로 제어가 가능하다

※ 아직 discovery 완료 후 activate 설정을 false로 바꾸는 기능을 구현하지 않았다... 만약 activate가 true인 채로 애드온이 재시작되면 불필요하게 디바이스를 중복으로 탐색하게 되니 activate를 false로 바꾼 후 애드온을 다시 재시작해줘야 한다... (1.0.5 버전에 해결할 예정)

 

prefix는 HA mosquitto mqtt broker의 discovery 검색 접두사 설정값을 참고하여 설정해주면 된다 (아무 설정도 안했다면 그냥 homeassistant로 그대로 두면 되며, 기기 검색 활성화는 반드시 켜져있어야 HA의 구성요소도 자동으로 추가된다)

2.5. 기타 설정

• thermo_len_per_dev: 현대통신 월패드 새로운 난방 패킷 유형 발견 및 코드 적용(깃허브) 참고

아직 베타버전인 만큼, 애드온 설정은 앞으로 추가/삭제 등이 빈번하게 일어날 수 있다
변경 사항은 애드온의 변경 이력 및 관련 문서 탭을 참고하도록 하자

---

설정을 모두 마쳤다면 저장하기를 클릭

3. 애드온 실행

애드온 정보 탭 - 시작하기 클릭

 

애드온 로그 탭에서 어플리케이션 구동 로그를 확인할 수 있다

 

디바이스 탐색 기능을 활성화했다면, 디바이스가 감지되고 추가되는 것을 로그로 확인할 수 있다

 

※ 다시 한번 언급하지만, 1.0.4 베타버전에서는 device discovery 후 activate를 false로 만든 뒤 애드온을 다시 시작

 

MQTT 구성요소도 제대로 추가된 것을 확인
※ 통합구성요소 MQTT에 추가된다

 

3.1. 구성요소 편집

구성요소들을 대시보드에 입맛에 맞게 추가해주면 된다

TIP: 전등/콘센트/난방/에어컨 구성요소의 이름은 ROOM1, ROOM2 등 공간 이름으로 시작하므로 ROOM 키워드로 구성요소를 검색하면 된다

가스밸브는 GASVALVE, 엘리베이터는 ELEVATOR, 환기(전열교환기)는 VENTILATOR, 일괄소등스위치는 BATCHOFFSWITCH로 이름이 고정되어 있다 (만약 해당 기기가 여러개 존재하는 경우 추가 개발 예정)

 

대시보드 구성 예시

 

구성요소의 표시되는 이름(display name)은 구성요소 편집으로 수정할 수 있다 (설정 - 기기 및 서비스 - 구성요소 탭) > 아이콘, 영역도 편집할 수 있

 

업데이트 후 대시보드에서 이름이 제대로 변경된 것을 확인할 수 있다

TIP: 해당 이름으로 구글 어시스턴트의 음성 명령을 수행할 수 있다 (ex: "거실 천장 전등 1번 켜줘")

 

4. 유지보수

config.xml 수정이 필요하다면 Visual Studio Code Server 애드온으로 루트 경로의 /addon_configs 디렉터리에 xxxxxxx_yogyui_homenet_hillstate 내에 app_config.xml 파일을 수정하면 된다 (해당 경로가 도커 컨테이너 내부에 /config 경로 volume으로 마운트된다)

※ 개발자인 나를 제외하고는 건드릴 일이 있겠냐싶긴 하다만 ~.,~ 개발 이력으로 남기기 위해 기록해둔다 

5. ETC

Home Assistant Developer 가이드에 따라, HAOS가 구동될 수 있는 5종류의 CPU 아키텍쳐에 대해 애드온이 멀티플랫폼 지원을 할 수 있다

지원되는 아키텍쳐는 armv7, armhf, aarch64, amd64, i386 총 5개이며, 애드온 설치 시 자동으로 이미지를 선택해 다운로드 및 설치를 진행하므로 유저 입장에서는 신경쓸 필요가 없는 항목~

6. TODO

버그 및 개선 사항은 블로그 댓글 및 방명록, 이메일(lee2002w@gmail.com), 깃허브 이슈 등 어떤 채널을 통해서든지 제시 부탁드립니다 (주의: 대응은 느릴 수 있음)

 

몇몇 분들이 HA 애드온 출시를 희망하셨는데, 기대에 살포시 부응했다는데 의미가 있는 지난 2주였다 ㅎㅎ

그다지 원하진 않지만, 입소문이라도 탄다면 앞으로 할 일이 더 많아지겠지? ㅠ