Matter - Test Harness 구축하기 (Raspberry Pi 4)

매터(Matter) 기기 개발 후 제품을 출시하기 위해서는 CSA(Connectivity Standard Alliance)로부터 공인받은 인증업체로부터 인증 절차(Matter Certification)를 거친 후 결과를 CSA에 제출해야 한다 

(여담이지만 국내 CSA 공인 인증 업체 몇군데에 인증 견적을 내보니 기기 한 종류당 1000~2000만원 수준의 예산이 필요하다... 인증이라는 게 당연히 저렴하진 않은게 당연하지만;; IoT 기기 특성상 수백대는 팔아야 인증 비용을 겨우 본전치기할 수준이라니 ㅠ)

 

Matter 기기의 (BLE-WiFi 혹은 Thread network) Commissioning부터 시작해서 디바이스 타입(전구, 센서, 온도조절기 등)별 제어/응답, OTA(Over The Air) 등 다양한 테스트 항목이 존재하는데, CSA 멤버십 페이지에서 어떤 항목들이 검증되는지에 대한 문서를 열람할 수 있다 - 각 테스트 항목들은 Test Case의 앞글자를 따서 TC-xxx-yyy와 같이 라벨링되어 있다

※ 아래 첨부파일은 Matter 관련 필수 성능 테스트 항목에 대한 문서

Matter Test Plans Core Version 1.1.pdf

12.73MB

테스트 케이스 목록 중 일부 발췌

---

CSA에서는 인증업체에 의뢰하기 전 개발 단계에서 직접 테스트해볼 수 있도록 테스트 하네스(Test Harness) 환경을 구축할 수 있는 방법에 대해서도 제시하고 있다 (역시 Zigbee 표준을 개발했던 단체답게 이런 편의기능은 very good!)

 

Matter TH Quick Start Guide v1.1.pdf

4.74MB

 

테스트 하네스를 저렴하게 구축할 수 있게 라즈베리파이(Raspberry Pi)상에서 Matter Test Harness(TH) 환경을 구성할 수 있다고 가이드하고 있다

※ 사실 Wi-Fi와 Bluetooth가 탑재된 플랫폼이라면 뭐든지 상관없이 TH로 활용할 수 있을 것 같다는게 내 판단 (Thread는 어차피 nRF52840같은 USB 동글을 사용하면 되고~) 라즈베리파이처럼 저렴한 SBC로도 구축할 수 있다는데 의의가 있는듯 (TH가 그다지 고사양을 요구하지는 않는다)

 

도커(docker)에서 구동되는 Matter TH 컨테이너가 미리 설치된 Linux(Ubuntu 22.04.1 LTS) 운영체제 이미지를 다운로드받은 뒤, 여분의 라즈베리파이 4에 이미지를 플래싱해서 테스트 하네스를 한 대 만들어보자

(라즈베리파이 하드웨어 공급난도 서서히 해결되어가는 기미가 보인다)

[준비물(하드웨어)]
- 라즈베리파이 4 (RAM 4GB 이상)
- 용량 64GB 이상의 SD카드
- 이더넷 케이블 (중요: 라즈베리파이의 와이파이는 Matter용으로 사용되어야하므로, 유선 네트워크 환경이 필요하다)

1. OS 이미지 다운로드

Test Harness 이미지는 Sharepoint에서 다운로드할 수 있다 (링크)

라즈베리파이용 이미지는 "TH - Final SVE -2" 폴더로 들어가면 된다

SVE_2_Final_Version.img.gz 압축파일 다운로드 (압축 해제 시 이미지 파일 용량은 14.76GB)

Mac OS에서는 다운로드 완료 후 자동으로 압축이 해제되는데, 압축 해제 후 'img'라는 이름의 파일이 생성된다

확장자를 .img 형태로 파일 이름을 바꿔주자 (예시: Matter_TH.img)

[2023.11.26 추가]
쉐어포인트에 접근이 안된다고 하는 댓글이 달려서, 개인 구글드라이브 계정에 이미지 파일을 올려뒀으니 아래 링크에서 바로 다운로드받아도 된다
https://drive.google.com/file/d/1XoA2P3GUHVkE_qC6C05ahsMUZU_3Kfaf/view?usp=sharing

2. 부팅 디스크 생성

라즈베리파이 부팅 디스크 생성용 툴로 유명한 두 개의 툴 (Raspberry Pi Imager 혹은 Balena Etcher) 중 입맛대로 선택해서 설치해준다 (개인적으로는 RPi Imager를 선호하지만, Mac OS에서는 왠지 etcher가 더 잘 돌아가는 이상한 느낌... 이 글에서도 Etcher 기준으로 설명)

Flash from file 선택 후 이미지 파일(앞서 이름 변경한 파일) 선택

SD카드 삽입 및 선택 후 Flash! 버튼 클릭 (대략 30분 정도 소요되니 여유롭게 게임 한판 때리고 오면 된다)

3. 라즈베리파이 부팅

default 계정은 다음과 같이 설정되어 있다

(어차피 로컬 환경에서 Matter TH용으로만 사용할 것이라면 굳이 auth 변경은 안해도 될 듯? 보안이 신경쓰인다면 바꿔주자)

• username: ubuntu
• password: raspberrypi

디스크 내부 내용을 보면 상당히 단촐한 것을 알 수 있다

이미지 플래시 완료 후 SD카드를 라즈베리파이에 삽입한 뒤 부팅 (제대로 되는지 확인하기 위해 모니터를 연결해봤다)

ubuntu-desktop 패키지가 설치되지 않은 이미지라 tty1 모드로 부팅되기 때문에 콘솔로만 제어할 수 있다 (아마도 이미지 용량 때문이었으리라...)

어차피 Matter TH는 HTTP 웹으로 모든 작업이 이루어지기 때문에, 라즈베리파이가 정상적으로 구동되는 것만 확인하면 모니터도 연결할 필요없이 그냥 이더넷 연결해둔 채로 구석에 박아두면 된다 (ifconfig로 ip주소만 확인해두자)

※ 테스트 시 도커 로그를 확인해야 하는 경우가 종종 있는데, SSH로 해결하면 된다

 

만약 ubuntu-desktop을 설치해 라즈베리파이를 범용 리눅스 PC로 사용하고자 하면 apt로 설치해줘야 한다

그런데, 최초로 apt 패키지를 설치하려 하면 dpkg lock이 걸려있다는 메시지가 뜨며 설치가 되지 않는 것을 알 수 있다

E: Could not get lock /var/lib/dpkg/lock-frontend. It is held by process xxxx (unattended-upgr)
N: Be aware that removing the lock file is not a solution and may break your system.
E: Unable to acquire the dpkg frontend lock (/var/lib/dpkg/lock-frontend), is another process using it?

의도되지 않은 패키지 업그레이드를 막는 용도로 lock을 걸어두는데, 괜히 lock 파일을 지웠다가 나중에 후회하지 말고 잠시 프로세스를 종료하도록 하자 (위 로그에서 xxxx가 lock 파일을 점유하고 있는 process id)

$ sudo kill -9 xxxx

※ 라즈베리파이를 단순히 Matter TH로만 사용하지 않고 범용적으로 사용하고자 할 경우에만 설치

$ sudo apt-get install ubuntu-desktop

4. Matter TH 구동 확인

라즈베리파이와 동일한 로컬 네트워크 상의 다른 기기(랩탑 or 데스크톱)의 웹브라우저에서 라즈베리파이의 IP 주소로 HTTP 접속하면 다음과 같은 화면이 보이게 된다

- 라즈베리파이 부팅 시 도커 컨테이너가 자동으로 시작된다

맥북 Safari로 접속한 모습

만약 웹페이지 접속에 실패한다면 ssh를 통해 컨테이너를 시작해줘야 한다

$ ./chip-certification-tool/scripts/start.sh

4.1. Matter TH 구동 코드 간략 분석

start.sh 스크립트는 다음과 같이 작성되어 있다 (docker-compose를 호출하는 것을 알 수 있다)

#! /usr/bin/env sh
ROOT_DIR=$(realpath $(dirname "$0")/..)

## SET BACKEND PATH ENV
KEY="BACKEND_FILEPATH_ON_HOST"
VALUE=$(readlink -f $ROOT_DIR/backend)
export $KEY=$VALUE

cd $ROOT_DIR

# Exit in case of error
set -e

# Ensure .env exists
./scripts/install-default-env.sh

# Record Backend SHA to a file
sh ./scripts/record-backend-sha-version.sh


INSTALL_DEV=false \
docker-compose \
-f docker-compose.yml -f docker-compose.override.yml \
config > docker-stack.yml

docker-compose -f docker-stack.yml up -d

docker-compose.yml, docker-compose.override.yml 파일 내부를 보면 어떤 도커 이미지들이 실행되는지 알 수 있다

 

실행중인 컨테이너들을 리스트업해보자

$ docker container ls

오호라... 기본적으로 4개의 컨테이너가 구동되고 있다

각 컨테이너별로 어떤 SW 프레임워크가 사용되었는지 간략하게 알아보자

4.1.1. Web Backend

웹호스팅 백엔드(backend) 소스코드 경로: ~/chip-certification-tool/backend

대부분 python 코드로 작성되어 있으며, 메인 프레임워크는 uvicorn + FastAPI 조합으로 백엔드 API가 구현되어있다 (사실 웹쪽은 Flask나 Django만 써봐서... ㅋㅋ 코딩 스타일은 큰 차이는 없네?)

백엔드는 컨테이너에서 8888번 TCP 포트를 점유하고 있다

~/chip-certification-tool/backend/app/main.py 스크립트 중 일부

4.1.2. Web Frontend

웹호스팅 프론트엔드(frontend) 소스코드 경로: ~/chip-certification-tool/frontend

프론트엔드는 대부분 타입스크립트(typescript)로 작성되어 있으며, 프레임워크는 Angular를 사용하고 있다

(프론트엔드 프레임워크도 리액트랑 뷰만 써봤는뎈ㅋㅋㅋ 내 개발역량과는 너무 거리가 먼 소스코드다...)

프론트엔드는 컨테이너에서 4200번 TCP 포트를 사용한다

~/chip-certification-tool/frontend/src/main.ts

4.1.3. Database

데이터베이스(DB)는 PostgreSQL을 통해 구축되었다 (하... 난 MySQL이랑 MongoDB만 주로 쓰는데 ㅋㅋㅋ)

데이터베이스는 Matter 테스트 프로젝트 및 테스트 결과물을 로컬에 저장하는데 사용되는 걸로 판단된다 

DB는 컨테이너에서 5432번 TCP 포트를 사용한다

~/chip-certification-tool/docker-compose.yaml

4.1.4. Reverse Proxy

웹호스팅 시 리버스 프록시를 구성하기 위해 Traefik을 사용하고 있다 (난 Nginx만 쓰고 있지... ...)

웹브라우저로 HTTP(80) 접속 요청을 프론트엔드 컨테이너로 연결시켜 준다

Traefik 문서 대강 읽어보니 도커 환경에서 리버스 프록시 구성하는 방법이 Nginx보다 조금 더 간결해보인다~

사용하는 TCP 포트는 80번과 8090번 (8090요청을 8080으로 프록시)

~/chip-certification-tool/docker-compose.yaml

~/chip-certification-tool/docker-compose.override.yaml

4.2. 정리

• Matter TH는 Ubuntu 22.04 (커널 5.15) 리눅스 OS에서 구동되도록 제공된다
• 구동에 필요한 docker container들이 내장되어 있으며 부팅시 자동으로 시작된다
• Matter TH는 HTTP 웹으로 모든 기능이 제공된다
• 웹 프론트엔드는 typescript로 작성되었으며 프레임워크는 Angular
• 웹 백엔드는 uvicorn + FastAPI 조합으로 API가 구현되었다
• 데이터베이스는 PostgreSQL
• 리버스 프록시를 위해 Traefik 사용

진짜 내가 그동안 써왔던 프레임워크들이랑 단 1개도 겹치는게 없다 ㅋㅋㅋ

내가 그만큼 Old해진건가 싶어서 약간 서글퍼진다 (사실 마음만 먹으면 혹은 개발 요청이 있으면 배우고 코드 짜는건 크게 어렵진 않겠지만...)

5. Matter Certification Test 데모

괜시리 포스팅이 짧을 것 같아 쓸데없이 코드를 좀 살펴봤다 ~.,~

TH 자체만으로는 크게 다룰 내용이 없어서... 그만큼 깔끔하게 필요한 기능들로만 잘 구성되어 있다

Matter 인증 테스트(certification test) 시 사용되는 테스트 케이스 중 일부를 내가 만든 기기에 적용해보자

5.1. 프로젝트 생성 및 설정

'Create New Project' 클릭

Project Config는 json 형태로 Wi-Fi, Thread 네트워크 설정 및 테스트하고자 하는 디바이스(DUT)의 commissioning 정보를 입력할 수 있다

예를 들기 위해 지난번에 예제로 개발한 Color Control 클러스터를 TH에 연동시켜보자

[PROJ] Matter::ColorControl 클러스터 개발 예제 (ESP32)

{
  "config": {
    "network": {
      "wifi": {
        "ssid": "와이파이 SSID",
        "password": "와이파이 패스워드"
      }
    },
    "dut_config": {
      "discriminator": "3841",
      "setup_code": "20222023",
      "pairing_mode": "ble-wifi",
      "chip_tool_timeout": null
    },
    "test_parameters": null
  },
  "pics": {
    "clusters": {}
  }
}

페어링 모드를 ble-wifi로 해주면 된다 (만약 OTBR을 사용한다면 USB 동글에 대한 정보를 정확히 입력해줘야 한다

5.2. PICS XML 파일 업로드

디바이스에 구현한 클러스터 종류별로 테스트 케이스가 정리된 PICS(Protocol Implementation Conformance Statement) 파일을 준비해야 한다

(Matter specification에 명시된 테스트 케이스를 하나하나 모두 개발자가 정리하기엔 테스트케이스가 너무 많다...)

PICS는 XML 포맷 파일인데, CSA 멤버십 가입자만 CSA-IoT 웹페이지를 통해 접근할 수 있다 (왜 굳이 PICS 파일들의 접근성이 폐쇄적인지는 잘 이해가 되지 않는 부분 ㅎㅎ...)

Documents - Matter Technical Resources - Matter Specification and Test Plans 경로

XML_Version Master-V13.zip

2023년 6월 기준, Version 13이 최신 버전이다 (2022년 9월 28일 업데이트 - 한동안 업데이트가 없다..)

zip 파일을 받아서 해제해보면 거의 모든 종류의 클러스터들에 대한 개별 PICS 파일이 존재하는 것을 알 수 있다

XML_Version Master-V13 압축 해제 결과

On-Off Cluster Test Plan.xml 파일을 열어보자

On-Off Cluster Test Plan.xml 파일 중 일부 발췌

OO.S, OO.C 등 자세한 테스트 케이스들에 대한 내용은 Matter Test Plan Specification 문서에서 찾아볼 수 있다

 

PICS는 Matter TH 프로젝트 세팅창에서 편하게 업로드할 수 있다

- Upload PICS 버튼 클릭 후 디바이스에 구현된 클러스터에 해당하는 PICS XML 파일 선택

5.3. 테스트 생성 및 테스트 항목 선택

좌측 사이드바에서 'Test' 아이콘 선택 후 새로 추가한 프로젝트 선택

'Create New Test Run' 선택

테스트 케이스 선택 (간단하게 예만 들기 위해 TC-ACL-1.1, TC-ACL-2.1 케이스 두 개만 선택)

실제 제품 테스트 시에는 Test Plan 문서를 보면서 Mandatory 항목은 모두 통과되는지 체크해야된다 (인증업체에서 테스트하는 항목은 모두 사전에 통과하는지 여부를 반드시 확인)

5.4. 테스트

'Start' 버튼 클릭해서 테스트 시작!

좌측에는 테스트 중인 항목 및 테스트 결과 (Pass 시 녹색 체크, Fail 시 적색 X)가 좌측에 리스트로 표시되며, 우측에는 Matter TH에서 구동중인 chip-tool의 로그를 기록하게 된다 (굳이 ssh로 docker 로그를 찍어보지 않더라도 디버깅이 가능하다)

5.5. 테스트 리포트

테스트 성공/실패 후 테스트 항목의 메뉴에서 'Show Report' 항목을 선택하면 출력 가능한 형태의 리포트를 볼 수 있다

인증업체에서도 이런 포맷의 테스트 리포트를 CSA에 제출하는 것으로 인증 절차를 밟는 것으로 추측된다

 

이 외에도 Matter TH 웹 UI는 몇몇 기능들이 더 있는데, 직관적으로 잘 만들어둬서 굳이 더 설명할 필요는 없을 것 같다

6. Matter Test 약어 설명

Matter TH를 사용하다보면 로그에 약어들이 기록되는데 뭘 뜻하는지 몰라서 찾아야되는 경우가 있어서 이 글에 정리해본다

Acronym / Abbreviation	Description
PICS	Protocol Implementation Conformance Statement(s)
PIXIT	Protocol Implementation eXtra Information for Testing
DUT	Device under Test
PAKE	Password Authenticated Key Exchange
PASE	Passcode Authenticated Session Establishment
PBKDF	Password-Based Key Derivation Function
MIC	Message integrity check
CASE	Certificate Authenticated Session Establishment
TLV	Tag Lenght Value
TH	Test Harness
CSR	Certificate Signing Request