Raspberry Pi 5::Matter Test Harness(1.3) 설치하기

Setup Matter Test Harness(1.3) on Raspberry Pi 5

[필요사항]
- Raspberry Pi 5 (본 글에서는 8GB RAM 모델 사용)
- 유선 이더넷 연결 환경 (LAN 케이블, 공유기 등)
- micro HDMI 케이블 혹은 젠더
- HDMI 지원 모니터
- USB 키보드 (혹은 무선 어댑터 + 무선 키보드 조합)
- Micro SD 카드 (용량은 64GB 이상을 권장, 본 글에서는 32GB 사용)
- Micro SD 카드 리더기 (USB)

1. 개요

Connectivity Standard Alliance(CSA)에서 제공하는 Raspberry Pi(라즈베리파이)용 Matter Test Harness는 공식적으로는 라즈베리파이4에 Ubuntu 22.04 LTS (Jammy Jellyfish)가 설치된 환경(리눅스 커널 5.15버전)만을 지원하고 있다

그런데, 우분투를 배포하는 Canonical은 라즈베리파이 5용으로는 Ubuntu 24.04 LTS (Noble Numbat) 이미지만 배포하고 있는데 기본으로 설치된 리눅스 커널 버전이 6.8이라 별도로 커널 다운그레이드를 하지 않으면 Matter TH 설치가 불가능하다 (** 커널 6.8에는 linux-modules-extra-raspi 패키지가 설치되지 않는다..)

이번 글에서는 간단하게 Matter TH 소스코드의 자동 스크립트를 일부 수정해서 Raspberry Pi 5 + Ubuntu 24.04 LTS + Linux Kernel 6.8 환경에서 Matter TH를 설치하고 구동하는 방법에 대해 알아보도록 한다

※ ConnectedHomeIP에서 라즈베리파이5 공식 지원이 되기 전 야매로 설치하는 방법이니 주의

2. 라즈베리파이 5용 Ubuntu 24.04 Server LTS 운영체제 설치

※ SD카드 OS 이미지 플래시할 때 Windows11 환경에서 진행하였다

2.1. Raspberry Pi Imager 설치

라즈베리파이용 우분투 이미지는 Raspberry Pi Imager 프로그램을 통해 손쉽게 다운로드받은 뒤 SD카드에 플래시할 수 있다 (링크: https://www.raspberrypi.com/software/)

 

※ 2024년 5월 10일 기준 최신 버전은 v1.8.5

2.2. SD카드 포맷

Windows 11의 '디스크 관리' 유틸리티로 SD카드를 단일 파티션으로 할당한 뒤 포맷을 진행해준다 (FAT32 FS 설정)

 

2.3. Ubuntu 24.04 이미지 다운로드 및 설치

Raspberry Pi Imager로 라즈베리파이용 우분투 이미지(iso파일)를 자동으로 다운로드받은 뒤 설치를 진행할 수 있다

2.3.1. 장치 선택

 

'Raspberry Pi 5' 선택

2.3.2. 운영체제 선택

 

'Other general-purpose OS' 선택

 

'Ubuntu' 선택

 

'Ubuntu Server 24.04 LTS (64-bit)' 선택

※ Matter TH 외 다른 용도로 라즈베리파이를 사용하고자 한다면 ubuntu-desktop 패키지만 apt로 설치해주면 된다

2.3.3. 저장소 선택

앞서 2.2에서 포맷해둔 Micro SD카드 볼륨 선택

2.3.4. 설치 진행

'다음' 클릭

 

OS 커스터마이징 설정 적용은 하지 않는 것을 권장 ('아니요' 클릭)

 

'예' 클릭을 하면 우분투 OS 이미지를 네트워크에서 다운로드받은 뒤 SD카드에 자동으로 설치가 진행된다

 

5~10분 정도 기다리면 설치가 완료된다

 

SD카드 리더기에서 카드를 제거한 뒤 라즈베리파이 5 보드에 삽입한 뒤 전원을 켜 부팅해주면 된다

3. Ubuntu 환경설정

최초 환경 설정 시 모니터와 키보드가 필요하며, SSH 설정 후에는 전원과 유선 이더넷만 연결해둔 채 원격으로 작업하면 된다

※ 유선 이더넷 네트워크 접속이 반드시 필요하므로, 공유기 설정을 확인해준다 (네트워크 전문가가 아닌 이상에야 별다른 설정 없이 공유기에 연결하면 외부 네트워크에 액세스할 수 있다)

 

최초로 부팅 시 SSH 서버가 다음과 같이 설정되는 것을 확인할 수 있다 (cloud-init)

 

엔터키를 누르면 계정을 통한 로그인 화면으로 넘어간다

3.1. 로그인 및 비밀번호 변경

Raspberry Pi Imager로 우분투 설치 시 설정되는 초기 계정 정보는 다음과 같다 (cloud-init 정보로 확인 가능)

- 계정명: ubuntu

- 패스워드: ubuntu

패스워드 입력 후 패스워드를 변경하라는 문구가 나오니 적절히 바꿔주면 된다

 

이제 ubuntu server 24.04가 라즈베리파이 5에 설치가 완료됐다!

라즈베리파이 보드에 알맞게 설계된 Linux 6.8.0-1004-raspi aarch64 커널이 설치된 것을 확인할 수 있다

3.2. IP 주소 확인

터미널에서 다음 명령어를 입력해 IP주소를 확인해준다

$ ip addr

 

eth0 유선 이더넷 어댑터의 inet으로 IPv4 주소를 확인할 수 있다

(2.1 과정에서 보듯이 우분투 서버 최초 부팅 시 콘솔에서도 확인할 수 있다)

※ 공유기에서 라즈베리파이의 IP주소를 확인할 수 있다면 3.1~3.2 과정을 스킵하고 바로 3.3을 진행하면 된다

3.3. SSH 접속 설정

$ sudo apt update
$ sudo apt upgrade -y
$ sudo apt install -y openssh-server

※ openssh-server는 ubuntu server 설치 시 자동으로 설치된다

※ Matter TH 구동 시 SSH를 통한 원격 접속이 반드시 필요한 기능은 아니므로 이 단계는 스킵해도 된다 (TH 설치 후 Web UI로 접근할 수 있게 된다)

 

라즈베리파이의 ssh 서버로 접속하고자 하는 클라이언트의 공개키(id_isa.pub)를 복사해 라즈베리파이의 ~/.ssh 경로의 authorized_keys 파일에 입력 후 저장해준다 (USB 플래시 메모리를 통한 파일 복사-붙여넣기가 제일 간단한 방법)

※ ssh-keygen을 통한 공개키 생성 과정은 본 글에서는 생략 (자세한 건 구글링)

 

이 글에서는 라즈베리파이에 접속하고자 하는 맥OS의 공개키를 USB 메모리에 복사한 뒤 라즈베리파이에서 작업하는 과정에 대한 예시만 다루도록 한다 (더 스마트한 방법도 있으니 구글링해보도록 하자)

3.3.1. 클라이언트에서 USB 메모리에 공개키 복사

$ cp ~/.ssh/id_pub.rsa /Volumes/${USB_Drive_Volume}

3.3.2. 라즈베리파이에서 USB 메모리 마운트 후 공개키 붙여넣기

$ sudo mkdir ~/media/usb
$ sudo mount -t vfat /dev/sda1 /media/usb
$ cat ~/media/usb/id_rsa.pub >> ~/.ssh/authorized_keys

3.3.3. 클라이언트에서 SSH 접속 확인

$ ssh ubuntu@{라즈베리파이 IP주소}

※ 공유기 포트포워딩 등 숙련자용 네트워크 설정 방법은 본 글에서는 생략한다

4. Matter Test Harness 설치

4.1. Matter TH 소스코드 클론 (깃허브)

Matter TH의 깃허브 소스코드 경로는

https://github.com/project-chip/certification-tool.git

 

공식 가이드를 보면 Matter 1.3 인증을 위한 Test Harness 버전 2.1부터는 Matter TH가 설치된 우분투 OS 이미지를 제공하는게 아니라, 사용자가 직접 소스코드를 빌드해 사용하도록 변경되었다 (오히려 이게 더 설치가 편하고 빠르다...)

https://github.com/project-chip/certification-tool/blob/main/docs/Matter_TH_User_Guide/Matter_TH_User_Guide.adoc

certification-tool/docs/Matter_TH_User_Guide/Matter_TH_User_Guide.adoc at main · project-chip/certification-tool

 

이 글에서는 클론 경로로 ~/matter 디렉터리로 설정했는데, 본인 입맛에 맞게 바꿔도 무방하다

$ mkdir ~/matter
$ cd ~/matter
$ git clone https://github.com/project-chip/certification-tool.git

 

클론 완료 후 서브모듈도 모두 체크아웃해준다

$ cd ~/matter/certification-tool
$ git submodule update --init --recursive

4.2. 필수 패키지 설치

certification-tool 소스코드의 아래 두 스크립트 파일(sh)을 보면 Matter TH 설치 시 필요한 패키지 종류를 확인할 수 있다

• certification-tool/scripts/pi-setup/install-pi-dependencies.sh
• certification-tool/scripts/ubuntu/1-install-dependencies.sh

패키지 의존 버전을 고정해둬서 커널 6.8 기반 우분투 24.04에서 설치 시 오류가 발생하는게 대부분인데, 우선 의존성 문제가 발생하는 패키지들을 수동으로 설치해주자

$ sudo apt update
$ sudo apt install -y\
    pi-bluetooth\
    g++\
    generate-ninja\
    libavahi-client-dev\
    libcairo2-dev\
    libdbus-1-dev\
    libgirepository1.0-dev\
    libglib2.0-dev\
    libreadline-dev\
    net-tools\
    ninja-build\
    npm\
    pkg-config\
    python3-pip\
    python3-venv\
    software-properties-common\
    toilet

4.3. 패키지 설치 스크립트 수정

4.2에서 언급한 두 개의 설치 스크립트 파일을 다음과 같이 수정해준다

(의존성 '='으로 표시된 것을 '>='으로 바꿔준 게 대부분이며, linux-modules-extra-raspi 패키지는 없어도 TH가 무리없이 설치되고 구동되는 것을 확인)

4.3.1. /scripts/pi-setup/install-pi-dependencies.sh

#! /usr/bin/env bash

 #
 # Copyright (c) 2023 Project CHIP Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
 # http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
set -e

# Silence user prompts about reboot and service restart required (script will prompt user to reboot in the end)
sudo sed -i "s/#\$nrconf{kernelhints} = -1;/\$nrconf{kernelhints} = -1;/g" /etc/needrestart/needrestart.conf
sudo sed -i "s/#\$nrconf{restart} = 'i';/\$nrconf{restart} = 'a';/" /etc/needrestart/needrestart.conf

# Upgrade OS
sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
sudo DEBIAN_FRONTEND=noninteractive apt-get upgrade -y

# TODO Comment on what dependency is required for:
packagelist=(
    #"linux-modules-extra-raspi (>=5.15.0.1046.44)"
    "pi-bluetooth (>=0.1.18ubuntu4)"
)

SAVEIFS=$IFS
IFS=$(echo -en "\r")
for package in ${packagelist[@]}; do
  echo "# Instaling package: ${package[@]}"
  sudo DEBIAN_FRONTEND=noninteractive sudo apt satisfy ${package[@]} -y --allow-downgrades
done
IFS=$SAVEIFS

4.3.2. /scripts/ubuntu/1-install-dependencies.sh

#! /usr/bin/env bash

 #
 # Copyright (c) 2023 Project CHIP Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
 # http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
set -e

# Install Docker Package Repo
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor --yes -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Silence user prompts about reboot and service restart required (script will prompt user to reboot in the end)
sudo sed -i "s/#\$nrconf{kernelhints} = -1;/\$nrconf{kernelhints} = -1;/g" /etc/needrestart/needrestart.conf
sudo sed -i "s/#\$nrconf{restart} = 'i';/\$nrconf{restart} = 'a';/" /etc/needrestart/needrestart.conf

sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
sudo DEBIAN_FRONTEND=noninteractive apt-get upgrade -y

# TODO Comment on what dependency is required for:
packagelist=(
    "apt-transport-https (>=2.4.11)"
    "avahi-utils (>=0.8-5ubuntu5.2)"                 # Matter uses Avahi
    "ca-certificates (>=20230311ubuntu0.22.04.1)"
    "docker-ce (>=5:24.0.7-1~ubuntu.22.04~jammy)"    # Test Harness uses Docker
    "figlet (=2.2.5-3)"
    "g++ (>=4:11.2.0-1ubuntu1)"
    "gcc (>=4:11.2.0-1ubuntu1)"
    "generate-ninja (>=0.0~git20220118.0725d78-1)"
    "libavahi-client-dev (>=0.8-5ubuntu5.2)"
    "libcairo2-dev (>=1.16.0-5ubuntu2)"
    "libdbus-1-dev (>=1.12.20-2ubuntu4.1)"
    "libgirepository1.0-dev (>=1.72.0-1)"
    "libglib2.0-dev (>=2.72.4-0ubuntu2.2)"
    "libreadline-dev (>=8.1.2-1)"
    "libssl-dev (>=3.0.2-0ubuntu1.14)"               # Apparently with each update, previous versions of the library are removed
    "net-tools (>=1.60+git20181103.0eebece-1ubuntu5)"
    "ninja-build (>=1.10.1-1)"
    "npm (>=8.5.1~ds-1)"
    "pkg-config (>=0.29.2-1ubuntu3)"
    "python3-pip (>=22.0.2+dfsg-1ubuntu0.4)"          # Test Harness CLI uses Python              
    "python3-venv (>=3.10.6-1~22.04)"                 # Test Harness CLI uses Python
    "software-properties-common (>=0.99.22.9)"
    "toilet (>=0.3-1.4)"
    "unzip (>=6.0-26ubuntu3.1)"
)

SAVEIFS=$IFS
IFS=$(echo -en "\r")
for package in ${packagelist[@]}; do
  echo "# Instaling package: ${package[@]}"
  sudo DEBIAN_FRONTEND=noninteractive sudo apt satisfy ${package[@]} -y --allow-downgrades
done
IFS=$SAVEIFS 

# Install Peotry, needed for Test Harness CLI
curl -sSL https://install.python-poetry.org | python3 -

4.4. 빌드 및 구동

이제 자동 설치 스크립트를 터미널에서 호출하면 설치가 진행된다

$ cd ~/matter/certification-tool/scripts/pi-setup
$ ./auto-install.sh

 

설치가 완료된 뒤 재부팅한 뒤 Matter TH 시작 스크립트를 호출해주면 Matter TH가 구동된다

$ ~/matter/certification-tool/scripts/
$ ./start.sh

Matter TH 구동 화면

Matter TH 웹페이지 접속 화면

5. 결론

라즈베리파이 5를 위한 Ubuntu 22.04가 공식적으로 지원되었다면 이렇게까지 삽질을 할 필요가 없는데, 24.04 버전이 출시되면서 최신 하드웨어인 라즈베리파이 5에는 24.04 버전만 지원되면서 생긴 문제를 해결하는 방법에 대해 알아봤다

일단 최신 패키지를 통해서도 빌드가 잘 되고 구동도 잘 되는걸 봐서 다행이긴 한데, 아무래도 야매로 하는 방법이다보니 추천하진 않는다 ㅎㅎ

아마 조만간 CSA에서도 커널 6.8 기반의 Ubuntu 24.04 LTS 버전을 위한 공식 가이드를 제공할 것으로 생각되는데, 그 전에 급하게 TH를 구축해야할 일이 있다면... 그냥 라즈베리파이 4 + ubuntu 22.04 조합을 추천한다 ㅎㅎ