테스트 장비: Orange Pi Zero2
1. 기본 요구사항
Ubuntu 24.04 이상
Python 3.12 이상
2. 필요한 리눅스 패키지 설치
apt install -y python3 python3-dev python3-venv python3-pip bluez libffi-dev libssl-dev libjpeg-dev zlib1g-dev autoconf build-essential libopenjp2-7 libturbojpeg0-dev tzdata ffmpeg liblapack3 liblapack-dev libatlas-base-dev
apt install -y libtiff6
3. 사용자 추가
useradd --system --create-home -c "Home Assistant" -d "/var/homeassistant" homeassistant -G dialout,i2c,gpio
mkdir "/opt/homeassistant"
chown homeassistant:homeassistant /opt/homeassistant
4. 기본 Python과 분리하여 독립적으로 실행할 가상 환경을 설치한다.
sudo -u homeassistant -H -s
cd /opt/homeassistant
python3 -m venv /opt/homeassistant
source /opt/homeassistant/bin/activate
python3 -m pip install wheel
5. Home Assistant를 설치한다.
pip3 install homeassistant==2024.9.9
위의 구문을 실행하면 오류가 발생하면서 설치가능한 버전 목록이 나오는데 2024.9.9 자리에 최신 버전을 명시하여 설치한다.
6. Home Assistant systemd 서비스 기술 파일 작성
exit
vi /usr/lib/systemd/system/hass.service
----------
[Unit]
Description=Home Assistant
After=network-online.target
[Service]
Type=simple
User=homeassistant
Group=homeassistant
WorkingDirectory=/var/homeassistant
ExecStartPre=/bin/sleep 5
ExecStart=/opt/homeassistant/bin/hass -c "/var/homeassistant"
ExecStop=pkill -SIGTERM -f "homeassistant\/bin\/hass"
RestartForceExitStatus=100
[Install]
WantedBy=multi-user.target
----------
systemctl daemon-reload
systemctl enable hass.service
systemctl start hass.service
※최초 실행되는데 10분 정도 소요된다.
7. 웹브라우저에서 아래 형식으로 접속을 확인한다.
http://10.10.10.108:8123
■ SSL 적용
1. configuration.yaml에 설정 추가
아래 설정으로 Reverse Proxy를 허용하고 WebSocket이 활성화 된다.
vi /var/homeassistant/configuration.yaml
----------
# Enable Reverse Proxy
http:
use_x_forwarded_for: true
trusted_proxies:
- 10.10.10.0/24
- 10.10.10.108
- 127.0.0.1
# Enable WebSocket
websocket_api:
----------
2. nginx 설치
apt -y install nginx
systemctl enable nginx.service
3. ngix에 Reverse Proxy 설정파일을 작성
hasu0707.duckdns.org를 외부 HOST명으로 변경하고 원활한 서비스를 위해서는 자체 서명이 정상적인 SSL 인증서를 발급받아 셋팅한다.
vi /etc/nginx/sites-available/reverse_proxy
----------
###########################################################
# /etc/nginx/sites-available/reverse_proxy
#
# Add the following to Home Assistant's configuration.yaml:
###########################################################
#http:
# use_x_forwarded_for: true
# trusted_proxies:
# - 10.10.10.0/24
# - 10.10.10.108
# - 127.0.0.1
#
#websocket_api:
###########################################################
server {
listen [::]:443 ssl default_server http2 ipv6only=off;
server_name 'hasu0707.duckdns.org';
# These shouldn't need to be changed
add_header Strict-Transport-Security "max-age=31536000; includeSubdomains";
ssl_protocols TLSv1.2;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4";
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
proxy_buffering off;
location / {
proxy_pass http://localhost:8123/;
proxy_http_version 1.1;
proxy_redirect http:// https://;
proxy_cache_bypass $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwared-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
}
# self signed certificate
ssl_certificate '/etc/ssl/opizero2/certs/ssl-cert.crt';
ssl_certificate_key '/etc/ssl/opizero2/private/ssl-cert.key';
}
server {
# managed by Certbot
if ($host = 'hasu0707.duckdns.org') {
return 301 https://$host$request_uri;
}
listen 80;
server_name 'hasu0707.duckdns.org';
# managed by Certbot
return 404;
}
----------
ln -s /etc/nginx/sites-available/reverse_proxy /etc/nginx/sites-enabled/reverse_proxy
4. nginx 재시작
systemctl restart nginx.service
■ Zigbee2MQTT 설치
참고: https://docs.jethome.ru/en/controllers/linux/howto/zigbee2mqtt.html
1.MQTT broker mosquitto 패키지 설치
apt install -y mosquitto mosquitto-clients
systemctl enable mosquitto.service
systemctl restart mosquitto.service
systemctl status mosquitto.service
2.mosquitto broker ID/Password 추가 및 암호화
vi /etc/mosquitto/conf.d/account.conf
----------
# 비밀번호 파일경로 설정
password_file /etc/mosquitto/passwd
# 익명 접속 차단
allow_anonymous false
----------
vi /etc/mosquitto/passwd
----------
# username:password
mqttuser:mqTT123@
----------
mosquitto_passwd -U /etc/mosquitto/passwd
systemctl restart mosquitto.service
3.mosquitto broker 테스트
# subscribe
mosquitto_sub -h localhost -t /topic -u mqttuser -P mqTT815@
※subscribe는 listen 모드이다. publish가 보낸 메세지가 표시된다.
# publish (다른 세션에서 실행한다)
mosquitto_pub -h localhost -t /topic -u mqttuser -P mqTT815@ -m "test"
※subscribe 세션에서 test가 뜨면 성공.
4.node.js 최신버전 확인 후 NODE_MAJOR 변수에 major 버전번호 설정
https://nodejs.org/en/download/package-manager/current
export NODE_MAJOR=22
5.20.x 이상의 node.js 및 빌드에 필요한 추가 패키지 설치
apt install -y ca-certificates curl gnupg
mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list
apt -y update
apt install -y nodejs git make g++ gcc
6.Zigbee2MQTT 설치
mkdir -p /opt/zigbee2mqtt
chown -R homeassistant:homeassistant /opt/zigbee2mqtt
git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
cd /opt/zigbee2mqtt
7.npm clean-install을 통해 패키지들을 설치하여 node_modules에 적재
npm ci
8./opt/zigbee2mqtt/data/configuration.yaml 설정
vi /opt/zigbee2mqtt/data/configuration.yaml
----------
# Home Assistant integration (MQTT discovery)
homeassistant: true
# Allow new devices to join
permit_join: false
# MQTT settings
mqtt:
# MQTT base topic for Zigbee2MQTT MQTT messages
base_topic: zigbee2mqtt
# MQTT server URL
server: 'mqtt://localhost'
# Serial settings
serial:
# SONOFF Zigbee 3.0 USB Dongle Plus V2 (EFR32MG21)
port: /dev/ttyUSB0
adapter: ember
rtscts: false
# Optional: advanced settings
advanced:
# Optional: ZigBee channel (Note: changing requires re-pairing of all devices)
channel: 15
# Optional: ZigBee pan ID
pan_id: 0x1a62
# Optional: network encryption key, will improve security (Note: changing requires repairing of all devices)
network_key: [1, 3, 5, 7, 9, 11, 13, 15, 0, 2, 4, 6, 8, 10, 12, 13]
frontend:
# Optional, default 8080
port: 8080
# Optional, default 0.0.0.0
host: 0.0.0.0
----------
9.Zigbee2MQTT 수동 시작 테스트
cd /opt/zigbee2mqtt
npm start
10.Zigbee2MQTT systemd 서비스 기술 파일 작성
vi /usr/lib/systemd/system/zigbee2mqtt.service
----------
[Unit]
Description=zigbee2mqtt
After=network.target
[Service]
User=homeassistant
Group=homeassistant
WorkingDirectory=/opt/zigbee2mqtt
ExecStart=/usr/bin/npm start
StandardOutput=inherit
StandardError=inherit
Restart=always
[Install]
WantedBy=multi-user.target
----------
systemctl daemon-reload
systemctl enable zigbee2mqtt.service
chown -R homeassistant:homeassistant /opt/zigbee2mqtt
systemctl restart zigbee2mqtt.service
11.정상 실행 모니터링
journalctl -u zigbee2mqtt.service -f
12.Home Assistant 통합
•MQTT 사용자 생성 (Home Assistant Supervisor 버전만 해당)
설정 > 구성원 > +구성원 추가하기 > ☑로그인 허용하기 / 이름:mqttuser, 암호:mqTT815@
•MQTT 통합
설정 > 기기 및 서비스 > +통합구성요소 추가하기 > MQTT
브로커: localhost
포트: 1883
사용자이름: mqttuser
암호: mqTT815@
13.MQTT 기기 추가
•MQTT에서 주변 기기 자동 추가
설정 > 기기 및 서비스 > MQTT > n개의 기기 > Zigbee2MQTT Bridge > 제어장치-Permit join:Enable
•IoT 장비 페어링 모드 켜기
14.페어링된 IoT 장비명들의 장비명 및 영역 변경
•설정 > 기기 및 서비스 > MQTT > n개의 기기 > 기기 선택
•우측 최상단 연필모양 아이콘 클릭