Home Assistant add-on 개발 일지

Developing Note: Home Assistant add-on

Home Assistant (홈어시스턴트, HA) 애드온을 수많은 삽질을 양념삼아 개발하고 있다 

그냥 도커 이미지로 뿌리면 될 줄 알았는데, HA랑 연동해서 사용하려면 이것저것 해줘야 할 게 꽤 있더라는...

애드온 개발 관련 지침은 HA의 공식 개발자 문서를 참고해서 거의 그대로 따라하고 있다

https://developers.home-assistant.io/docs/add-ons

Developing an add-on | Home Assistant Developer Docs

 

그동안 HA 애드온을 개발하겠다고 호언장담(?)해왔는데, 말만 해놓고 놀고 있는게 아니냐는 의심을 받을까봐 제발에 저려 끼적끼적 올려보는 개발 이력 정리 포스팅 ^^;;

※ 아직 어플리케이션 설정이 불가능한 애드온이라 실제로는 사용할 수 없음! 

1. 애드온 컨셉 

수시간의 빌드 및 실행 테스트 삽질을 하면서 설계한 (스스로 생각하기에는 꽤나 합리적인) 애드온 컨셉은 다음과 같다

HA addon design concept

 

• 도커 컨테이너 이미지는 단순히 홈네트워크 어플리케이션 소스코드(python)를 클론해온 뒤 실행하는 역할만을 수행
  (실행 시 git pull로 코드 최신화 작업 수행)
• 빌드된 도커 이미지는 Docker Hub 저장소에 푸시하고, HA 애드온 설치 시 도커 허브에서 이미지를 다운로드받을 수 있도록 구현
  (라즈베리파이같은 SBC에서는 도커 빌드 과정이 너무 오래 걸림)
• 도커 이미지 빌드는 ubuntu가 설치된 고성능 랩탑에서 수행
• 어플리케이션의 설정(config.xml)은 애드온의 인그레스(ingress) 포트 혹은 애드온 파라미터를 통해 바꿀 수 있도록 구현

2. HA 애드온을 위한 깃허브 리포지터리 생성 및 커밋

일단 지금까지 개발한 이력을 깃허브 HA 애드온 리포지터리에 커밋해봤다

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

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

├── homenet-hillstate
│   ├── apparmor.txt
│   ├── build.yaml
│   ├── CHANGELOG.md
│   ├── config.yaml
│   ├── Dockerfile
│   ├── DOCS.md
│   ├── icon.png
│   ├── logo.png
│   ├── README.md
│   ├── run.sh
├── LICENSE
├── README.md
├── repository.yaml

2.1. Dockerfile

ARG BUILD_FROM
FROM $BUILD_FROM
LABEL maintainer="YOGYUI lee2002w@gmail.com"

# install required packages
RUN apk add --update --no-cache \
    bash curl nano vim wget git openrc \
    gcc openssl-dev libffi-dev musl-dev linux-headers cargo pkgconfig \
    python3 python3-dev py3-pip

# clone repository from GitHub
RUN mkdir -p /repos/yogyui
RUN git clone https://github.com/YOGYUI/HomeNetwork.git /repos/yogyui/HomeNetwork
WORKDIR /repos/yogyui/HomeNetwork/Hillstate-Gwanggyosan

# create & activate python virtual environment, install python requirements
RUN /bin/bash -c "source ./bootstrap.sh"
RUN python3 clean.py

# expose default web server port (todo: dynamic expose?)
EXPOSE 7929

COPY run.sh /
CMD ["/bin/bash", "-c", "source /run.sh"]

위에서 언급한대로, 도커 이미지에는 깃허브 리포지터리로부터 소스코드를 클론해온 뒤 필요한 파이썬 패키지들을 설치한 뒤, 컨테이터 실행 시 run.sh 스크립트를 호출하게 간단하게 만들었다

소스코드는 이미지 내부 /repos/yogyui/HomeNetwork 경로에 클론하도록 설정했다 (애드온 사용자 입장에서는 코드가 어디 존재하는지 알 필요가 전혀 없긴 하다)

2.2. config.yaml

name: HomeNetwork for Hillstate
version: "1.0.0"
slug: yogyui_homenet_hillstate
description: RS-485 based HomeNetwork for Hillstate (Hyundai HT)
arch:
  - armhf
  - armv7
  - aarch64
  - amd64
  - i386
image: yogyui/ha-addon-{arch}-homenet-hillstate
init: false
startup: application
url: https://github.com/YOGYUI/homeassistant-addons/tree/main/homenet-hillstate
ingress: true
ingress_port: 7929
ingress_stream: true
ports:
  7929/tcp: 7929
ports_description:
  7929/tcp: Web service server port
privileged:
  - SYS_ADMIN
full_access: true
apparmor: false
panel_icon: mdi:home-automation
panel_title: YOGYUI-HILLSTATE
panel_admin: false
map:
  - share:rw

애드온 설정을 위한 config.xml은 일단 되는대로 필수적이라고 생각하는 기능들만 넣어뒀다

USB to RS485 컨버터를 직접 액세스해야되는 경우가 있을 것 같아 full_access를 활성화하고 priviliged에 관리자 권한을 설정했는데, 이렇게 하는게 맞는건지는 의문...

3. run.sh

repo_path=/repos/yogyui/HomeNetwork

echo "try to update repository"
git pull

source ${repo_path}/Hillstate-Gwanggyosan/activate.sh
python3 ${repo_path}/Hillstate-Gwanggyosan/app.py

핵심으로 넣은 기능이 run.sh 호출 시 git pull로 소스코드를 최신화하는 것이다

이렇게 해두면 정말 특별한 경우가 아닌 이상 애드온을 업데이트할 이유가 전혀 없지않을까...하는게 내 생각 ㅋㅋ

(소스코드를 도커 이미지 빌드 시 하드 카피해 넣는게 아니라 깃허브 저장소에서 클론해오고, 실행 혹은 애드온 재시작 시 항상 최신버전으로 업데이트 가능)

3. 애드온 도커 이미지 생성 및 푸시

5종류의 CPU 아키텍쳐에 대한 멀티플랫폼 이미지를 지원하기 위해 도커 허브에 5개의 저장소를 따로 만들었다...

• yogyui/ha-addon-armv7-homenet-hillstate
• yogyui/ha-addon-armhf-homenet-hillstate
• yogyui/ha-addon-aarch64-homenet-hillstate
• yogyui/ha-addon-i386-homenet-hillstate
• yogyui/ha-addon-amd64-homenet-hillstate

도커 허브 저장소 하나에 멀티플랫폼 이미지를 전부 넣으면 좋을텐데.. 아직 그렇게 빌드하는 방법을 못찾았다 ㅠ

(buildx의 docker container 드라이버로 빌드하는 방법을 연구중이다.. 이것땜에 사실 애드온 개발하는 시간이 상당히 지체되고 있다;;)

이미지를 빌드해서 도커 허브 저장소에 푸시하는 것 까지는 HA 공식 가이드대로 명령어 한줄로 가능!

docker run \
  --rm \
  --privileged \
  --name hassio-builder \
  -v ~/.docker:/root/.docker \
  -v ${addon_path}:/data \
  homeassistant/amd64-builder \
  --all \
  -t /data

4. HA 애드온 연동 테스트

일단 지금까지 만든 애드온 이미지를 HAOS에 설치하고 실행해보자

4.1. 애드온 스토어 저장소 추가

메뉴: HA 홈페이지 - 설정 - 애드온 - 애드온 스토어 - 저장소

 

저장소에 나의 HA 애드온 깃허브를 입력하고 '추가하기' 버튼을 클릭하면 'YOGYUI'라는 항목이 추가된다

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

 

이제 애드온 목록에 'YOGYUI' 항목 아래 'HomeNetwork for Hillstate' 애드온 항목이 추가된 것을 볼 수 있다

애드온 아이콘에 양심없이 힐스테이트 로고 붙여놓은 꼬락서니 보라지... (변경 예정 ㅋㅋ)

4.2. 애드온 설치

'설치하기' 버튼을 눌러 설치를 하면 supervisor 로그에 애드온 디렉터리 생성 및 도커 이미지 다운로드가 진행되고 있다고 기록된다 (테스트는 HAOS가 설치된 라즈베리파이4에서 진행했기에, aarch64 아키텍쳐용으로 빌드된 이미지를 도커 허브로부터 다운로드받는다)

이미지 용량이 416MB나 되기 때문에 다운로드 및 설치에 시간이 다소 소요된다...

설치완료까지 대략 3분 30초 정도 소요되는듯?

※ 이게 다 ThinQ 연동때문에 crypto같은 파이썬 패키지를 설치해야되기 때문 ^^;; 지금 너무나 편하게 연동해서 잘 쓰고 있기 때문에 다른 사람들을 위해 ThinQ 연동을 내 소스코드에서 제외할 생각은 없다 ㅋㅋ

 

설치가 완료되면 애드온 화면이 다음과 같이 변경된다 (무려 보안등급은 최하위인 1등급... apparmor도 비활성화해놨기 때문에 사실상 스팸메일 수준의 애드온 ㅋㅋㅋ)

4.3. 애드온 실행

'시작하기' 버튼을 클릭해 실행하고 '사이드바에 표시하기' 옵션을 활성화해보자

 

앱 로그를 보면 어플리케이션이 제대로 실행되고 있는 것을 알 수 있다

 

사이드바를 보면 'YOGYUI-HILLSTATE' 메뉴가 추가된 것을 알 수 있다

 

사이드바 메뉴를 클릭해보면 초창기에 구현해둔 Flask 웹페이지가 Ingree로 라우팅되는 것을 알 수 있다

(아직 웹 프론트엔드 작업은 한창 진행 중)

4. TODO

이제 애드온 릴리즈를 위한 사전준비(?)는 대략 마무리되었다

앞으로 남은 일은...

• 어플리케이션 설정파일(config.xml) 수정이 가능한 웹 프론트엔드 개발
   MQTT Broker, Device Discovery 등 앱 구동을 위해 설정해야 할 것들이 많다
• Ingress 사용 시 Flask 라우팅 설정 방법 연구 및 적용
  Ingress에서는 내가 쉽게 사용했던 Flask 라우터가 전혀 먹히질 않기 때문에, 손봐야될 게 많아보인다...
• 애드온 아이콘 교체 
  힐스테이트 이미지를 쓰는건 너무 양심없어 보이기도 하고, 법적인 문제가 있을 것 같기도 하고...
• DOCS.md, README.md 등 문서 작업

---

나름 바쁘게 사는 사람인지라... 없는 시간 쪼개가며 조금씩 개발해나가는 중이니만큼 애드온 출시를 기대하시는 분이 계시다면 조금만 더 인내해주시길 바랍니다 ^^