Platform Install

스킬 시작 시 다음 정보를 사용자에게 요청한다. $ARGUMENTS로 일부가 전달될 수 있으나 누락된 항목은 반드시 질문한다.

HA_TOKEN은 HA 초기 설정 완료 후에만 발급 가능하므로, 1-6 완료 후 사용자에게 별도 요청한다.

실행 절차

아래 순서대로 Pi에 SSH 접속하여 명령을 실행한다. expect를 사용하여 자동화한다 (sshpass는 비밀번호에 ! 등 특수문자가 포함될 수 있어 동작 안 함). SSH 접속 시 HOST_IP, SSH_USER, SSH_PW를 사용한다.

1-0. unattended-upgrades 비활성화 (필수 최우선)

sudo systemctl stop unattended-upgrades
sudo systemctl disable unattended-upgrades
while sudo fuser /var/lib/dpkg/lock-frontend 2>/dev/null; do sleep 5; done

1-1. Docker 설치

HA와 Matter Server는 Docker 컨테이너로 실행한다. OTBR은 로컬 빌드이므로 Docker 불필요.

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable docker && sudo systemctl start docker
sudo usermod -aG docker $SSH_USER

1-2. apt 소스 noble-updates 추가

Ubuntu 24.04 기본 설치 시 noble-updates가 누락되어 OTBR 빌드 의존성 버전 충돌이 발생한다.

sudo tee -a /etc/apt/sources.list.d/ubuntu.sources << 'EOF'

Types: deb
URIs: http://ports.ubuntu.com/ubuntu-ports/
Suites: noble-updates
Components: main restricted universe multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
EOF

sudo apt update
sudo apt upgrade -y

1-3. OTBR 로컬 빌드 및 설치

빌드에 약 15~20분 소요 (Raspberry Pi 4/5 기준)

# 빌드 의존성
sudo apt install -y git build-essential cmake libdbus-1-dev libsystemd-dev python3-pip bluez

# 소스 클론 및 빌드
cd ~
git clone https://github.com/openthread/ot-br-posix.git
cd ot-br-posix
./script/bootstrap
INFRA_IF_NAME=wlan0 ./script/setup

held broken packages 에러 발생 시 sudo apt upgrade -y 후 재시도

1-4. OTBR REST API 외부 접근 허용

기본값은 127.0.0.1만 바인딩되어 HA에서 보더라우터 재설정 등 일부 기능이 제한된다.

sudo sed -i 's|trel://wlan0"|trel://wlan0 --rest-listen-address 0.0.0.0"|' /etc/default/otbr-agent

변경 후 확인:

cat /etc/default/otbr-agent
# OTBR_AGENT_OPTS="-I wpan0 -B wlan0 spinel+hdlc+uart:///dev/ttyACM0 trel://wlan0 --rest-listen-address 0.0.0.0"

USB 포트가 /dev/ttyACM1인 경우: sudo sed -i 's|/dev/ttyACM0|/dev/ttyACM1|' /etc/default/otbr-agent

1-5. OTBR 서비스 시작 + Thread 네트워크 초기화

sudo systemctl enable otbr-agent
sudo systemctl start otbr-agent

# Thread 네트워크 생성 (채널 15)
sudo ot-ctl dataset init new
sudo ot-ctl dataset channel 15
sudo ot-ctl dataset commit active
sudo ot-ctl ifconfig up
sudo ot-ctl thread start

# 약 10~15초 대기 후 확인
sleep 15
sudo ot-ctl state              # leader
sudo ot-ctl channel             # 15
curl -s http://127.0.0.1:8081/node/state   # "leader"

기존 Thread 데이터셋 복원 시 (TLV 백업 있는 경우):

sudo ot-ctl dataset set active <TLV_HEX>
sudo ot-ctl ifconfig up
sudo ot-ctl thread start
sleep 15
sudo ot-ctl state

1-6. docker-compose.yml 작성 + HA/Matter Server 기동

OTBR은 로컬 systemd 서비스이므로 docker-compose에 포함하지 않는다. matter-server에 --primary-interface wlan0을 반드시 포함한다 (link-local 라우팅 충돌 방지).

mkdir -p /home/$SSH_USER/matterhub-install/config
mkdir -p /home/$SSH_USER/docker/matter-server/data

cat > /home/$SSH_USER/matterhub-install/docker-compose.yml << 'EOF'