중요 가상 기기 빌드

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

1. 소개

Matter는 스마트 기기 개발에 흥미로운 기회를 제공하는 연결 프로토콜입니다. 이 Codelab에서는 사전 구성된 Docker 이미지에 제공된 SDK 및 종속 항목을 사용하여 첫 번째 Matter 기기를 빌드합니다.

Matter에 관해 자세히 알아보려면 Google Home 개발자 센터 또는 Connectivity Standards Alliance 웹사이트를 방문하세요.

학습할 내용

  • Matter 빌드 환경 설정 방법
  • 컴퓨터에서 실행되는 가상 Matter 기기를 빌드하는 방법
  • Google Home으로 가상 Matter 기기를 위임하고 제어하는 방법

필요한 항목

  • Nest Hub (2세대)와 같이 Matter를 지원하는 모든 Google Nest 기기인 허브 허브는 Google 스토어 또는 원하는 소매업체에서 구매할 수 있습니다.
  • X11 윈도잉 시스템을 실행하는 Linux 시스템
  • Docker
  • Linux에 관한 기본 지식

2. 환경 설정

Linux 호스트 머신에서 이전에 구성한 Docker 컨테이너를 사용하겠습니다. 이 컨테이너에는 Matter 가상 기기를 빌드하고 실행하는 데 필요한 모든 종속 항목이 포함되어 있습니다.

하드웨어 확인하기

현재 이 Docker 설치에서는 Windows 및 MacOS 컴퓨터가 지원되지 않습니다. MacOS 또는 Windows에 Matter를 수동으로 설치하고 빌드할 수 있습니다.

또한 이 안내에서는 Linux 시스템에서 X11 윈도잉 시스템을 실행한다고 가정합니다. Linux 시스템에서 Wayland를 실행하는 경우 X.Org도 설치되었는지 확인합니다.

Docker 설정

  1. Docker Engine을 사용하지 않고 Docker Engine을 설치합니다.
  2. Docker Hub에서 Docker 이미지를 가져옵니다. 터미널 창에서 다음을 실행합니다.
    user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    이 작업은 완료하는 데 몇 분 정도 걸릴 수 있습니다.
  3. 실행 중인 Docker 컨테이너를 시작합니다.
    user@host> xhost local:1000
user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

컨테이너를 시작하면 진단 결과가 표시되고 컨테이너 구성이 올바르다는 확인 메시지와 함께 컨테이너 셸 프롬프트가 표시됩니다.

Environment looks good, you are ready to go!
$

Docker 명령어와 여기서 전달한 옵션을 이해해 보겠습니다.

  • xhost local:1000를 사용하면 X Window System이 포트 1000에서 로컬 호스트의 연결을 수신할 수 있으므로 그래픽 사용자 인터페이스를 사용할 수 있습니다.
  • docker run … image은 지정된 이미지를 실행하고 필요한 경우 Docker 레지스트리에서 가져옵니다.
  • --ipc=host를 사용하면 Docker가 프로세스 간 통신 네임스페이스를 호스트 머신과 공유할 수 있습니다.
  • --net=host를 사용하면 Docker가 컨테이너에서 호스트의 네트워크 스택을 사용할 수 있습니다. 호스트의 네트워크 스택은 호스트에서 컨테이너로 mDNS 트래픽을 전달하고 호스트 X11 디스플레이를 공유하는 데 필요합니다.
  • -e DISPLAY는 $DISPLAY를 호스트로 내보내 시스템 그래픽 인터페이스에 대한 액세스를 제공합니다. Matter 클러스터를 수정할 때 ZAP 도구를 실행하는 데 필요합니다.
  • -it는 백그라운드 프로세스 대신 대화형 터미널 (tty)을 사용하여 Docker를 실행합니다.

필요한 경우 두 번째 터미널 세션 인스턴스를 실행할 수 있습니다.

user@host> docker exec -it matter-container /bin/bash
$

Matter Docker 컨테이너 중지 및 시작

docker run 명령어를 실행할 때마다 지정된 이미지로 새 컨테이너를 만듭니다. 이렇게 하면 이전 컨테이너 인스턴스에 저장된 이전 데이터가 손실됩니다. 새로운 설치부터 시작할 수 있으므로 이 방법이 필요할 때가 있습니다. 하지만 세션 간에 작업 및 환경 구성을 저장하고자 하는 경우도 있습니다.

따라서 컨테이너를 만든 후 작업 손실을 방지하기 위해 컨테이너를 중지할 수 있습니다.

user@host> docker stop matter-container

다시 실행할 준비가 되면 컨테이너를 시작하고 터미널 창을 엽니다.

user@host> docker start matter-container
user@host> docker exec -it matter-container /bin/bash

다음을 사용하여 컨테이너에 대한 추가 터미널 세션을 열 수 있습니다.

user@host> docker exec -it matter-container /bin/bash

또는 다음을 사용하여 루트 세션을 시작합니다.

user@host> docker exec -u 0 -it matter-container /bin/bash

초기 법적 사안 설정

터미널이 열리면 이미 Matter의 클론된 저장소 ~/connectedhomeip에 있습니다. 추가 Matter 설정 단계는 필요하지 않습니다.

호스트와 컨테이너 간 파일 공유

컨테이너 머신 내에서 호스트 머신의 파일에 액세스하려면 결합 마운트를 사용하면 됩니다. 호스트에서 쉽게 액세스할 수 있도록 컨테이너 내에서 마운트된 디렉터리에 파일을 쓸 수도 있습니다.

추가 인수 --mount source=$(pwd),target=/workspace,type=bind로 컨테이너를 실행하여 현재 작업 디렉터리를 /workspace의 컨테이너에 마운트합니다.

user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

마운트된 디렉터리에 대한 컨테이너 사용자의 권한은 호스트에서 관리해야 합니다.

컨테이너 사용자의 컨테이너 ID를 컨테이너 내에서 가져옵니다.

$ id
uid=1000(matter) gid=1000(matter) groups=1000(matter)

컨테이너 호스트에서 다른 터미널 세션을 열고 작업 디렉터리를 컨테이너가 마운트한 디렉터리로 설정합니다.

마운트된 디렉터리에 있는 파일의 그룹을 컨테이너 사용자의 그룹으로 재귀적으로 설정합니다.

user@host> sudo chgrp -R 1000 .

디렉터리에서 원하는 권한을 그룹에 부여합니다. 이 예시에서는 컨테이너 사용자의 그룹에 마운트된 디렉터리의 모든 파일에 대한 읽기, 쓰기, 실행 권한을 부여합니다.

user@host> sudo chmod -R g+rwx .

이러한 명령어는 호스트 사용자가 만든 새 파일의 권한에 영향을 주지 않습니다. 필요에 따라 호스트에서 생성된 새 파일의 권한을 업데이트해야 합니다.

컨테이너 사용자의 그룹에 호스트 사용자를 추가하여 컨테이너 사용자가 만든 파일에 대한 권한을 상속받을 수 있습니다.

user@host> currentuser=$(whoami)
user@host> sudo usermod -a -G 1000 $currentuser

3. Google Home 개발자 콘솔

Google Home 개발자 콘솔은 Google Home과의 Matter 통합을 관리하는 웹 애플리케이션입니다.

CSA Matter 인증을 통과한 모든 Matter 기기는 Google Home 생태계에서 작동합니다.

개발자 프로젝트 만들기

먼저 Google Home 개발자 콘솔로 이동합니다. 먼저 Google Home 개발자 콘솔로 이동합니다.

  1. '프로젝트 관리' 화면에서 프로젝트 만들기를 클릭합니다.
    Google Home 개발자 센터
  2. '시작하기' 화면에서 프로젝트 만들기를 클릭합니다.

  1. 고유한 프로젝트 이름을 입력한 다음 새 프로젝트 만들기를 클릭합니다. 새 프로젝트 만들기 대화상자
  2. + Matter 통합을 클릭하면 '법적 사안 리소스' 화면으로 이동하여 Matter 개발 문서를 보고 일부 도구에 대해 알아볼 수 있습니다.
  3. 계속할 준비가 되면 '법적 사안 체크리스트' 화면을 표시하는 다음: 개발을 클릭합니다.
  4. 다음: 설정을 클릭합니다.
  5. '설정' 화면에서 제품 이름을 입력합니다.
  6. 기기 유형 선택을 클릭하고 드롭다운 메뉴 (이 경우 Light)에서 기기 유형을 선택합니다.
  7. 공급업체 ID (VID)에서 VID 테스트를 선택하고 VID 테스트 드롭다운 메뉴에서 0xFFFF1을 선택합니다. 제품 ID (PID)에 0x8000을 입력하고 저장 및 계속을 클릭한 후 다음 페이지에서 저장을 클릭합니다.
    프로젝트 설정
  8. 이제 Matter 통합 아래에 Matter 기기 한 개가 표시됩니다. Matter 통합
  9. 허브가 최신 Matter 통합 프로젝트 구성을 수신하도록 재부팅합니다. 나중에 VID 또는 PID를 변경해야 하는 경우 프로젝트를 저장한 후 재부팅해야 변경사항이 적용됩니다.

4. 기기 빌드

Matter의 모든 예는 GitHub 저장소의 examples 폴더에 있습니다. 여러 샘플이 있지만 이 Codelab에서는 Chef에 중점을 둡니다.

Chef는 다음 두 가지 모두에 해당합니다.

  • examples/shell 앱에서도 찾을 수 있는 터미널 기능, 래핑 기능을 제공하는 샘플 앱입니다.
  • Matter 지원 기기를 개발하는 데 필요한 여러 일반적인 작업을 캡슐화하기 위해 규칙에 대한 구성 원칙을 따르는 스크립트입니다.

Chef 예시 폴더로 이동하여 첫 번째 Matter 빌드를 만듭니다.

$ cd examples/chef
$ ./chef.py -zbr -d rootnode_dimmablelight_bCwGYSDpoe -t linux

Chef는 chef.py -h를 실행하여 볼 수 있는 몇 가지 옵션이 있습니다. 여기서 사용하는 옵션은 다음과 같습니다.

  • -d: 사용할 기기 유형을 정의합니다. 여기서는 켜기/끄기 및 레벨 컨트롤이 있는 조명 앱을 만듭니다.
  • -z: ZAP 도구를 호출하여 기기 유형을 구현하는 소스 파일을 생성합니다. 즉, 사용자가 선택한 조명에 따라 ZAP가 광원 (데이터 모델) 및 다른 기기와 상호작용하는 방식 (상호작용 모델)을 정의하는 빌드에 통합할 코드를 자동으로 생성합니다.
  • -b: 빌드.
  • -r: [선택사항] 가상 머티리얼 기기에서 RPC 서버를 사용 설정하여 다른 구성요소 (예: GUI)가 기기와 통신하여 데이터 모델 속성을 설정하고 검색할 수 있도록 합니다.
  • -t linux: 타겟 플랫폼입니다. 지원 플랫폼은 linux, nrfconnect, esp32입니다. ./chef.py -h를 실행하여 사용 가능한 모든 명령어와 지원되는 타겟 플랫폼을 확인할 수 있습니다. linux는 가상 Matter 기기에 사용됩니다.

기기 실행

Matter는 TCP/UDP 포트 5540을 사용하므로 컴퓨터에서 방화벽을 실행하는 경우 종료하거나 포트 5540에서 수신 TCP/UDP 연결을 허용합니다.

다음을 사용하여 컨테이너에서 가상 기기를 실행합니다.

$ ./linux/out/rootnode_dimmablelight_bCwGYSDpoe
   [1648589956496] [14264:16538181] CHIP: [DL] _Init]
...
[1648562026.946882][433632:433632] CHIP:SVR: SetupQRCode: [MT:Y3.13Y2N00KA0648G00]
[1648562026.946893][433632:433632] CHIP:SVR: Copy/paste the below URL in a browser to see the QR Code:
[1648562026.946901][433632:433632] CHIP:SVR: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AY3.13Y2N00KA0648G00
[1648562026.946915][433632:433632] CHIP:SVR: Manual pairing code: [34970112332]

기기를 계속 실행합니다. 이제 기기를 Google Home에 의뢰할 수 있도록 Google Home 앱에 주목하겠습니다.

기기 중지

CTRL+C를 사용하여 프로그램을 종료할 수 있습니다. 앱이 종료되지 않으면 CTRL+\도 사용해야 할 수 있습니다.

가상 기기의 사용자 인증 정보는 /tmp/ 디렉터리에 chip 프리픽스로 시작하는 파일에 저장됩니다.

처음부터 전체 의뢰를 반복하려면 다음 명령어를 실행하여 파일을 삭제해야 합니다.

$ rm /tmp/chip*

5. 가상 기기 컨트롤러

Virtual Device Controller는 가상 Matter 기기의 상태를 제어하고 표시할 수 있는 그래픽 사용자 인터페이스를 제공하는 독립형 앱입니다. RPC 클라이언트를 사용하여 개발 환경에 연결된 Matter 기기와 통신합니다.

가상 기기 컨트롤러

가상 기기 컨트롤러는 가상 기기를 시각적으로 표시합니다.

가상 기기 컨트롤러 그래픽 사용자 인터페이스 (GUI)를 통해 가상 기기와 상호작용할 수 있습니다. GUI의 변경사항은 기본 데이터 모델에 영향을 미칩니다. 현재 가상 기기 컨트롤러는 조명 밝기 조절 기기 유형을 지원합니다.

가상 기기 컨트롤러 설치

가상 기기 컨트롤러는 Ubuntu LTS 20.04 Docker 컨테이너에 사전 설치되어 제공됩니다.

가상 기기 컨트롤러 실행

두 번째 터미널 세션 인스턴스를 만듭니다.

user@host> docker exec -it matter-container /bin/bash
$

가상 기기와 통신하는 데 사용할 네트워크 소켓을 제공하여 가상 기기 컨트롤러를 시작합니다.

  $ cd ~/matter-virtual-device-gui/
  $ electron main.js --s=localhost:33000 --no-sandbox

인수를 제공하지 않고 컨트롤러를 시작하면 localhost 포트 33000을 사용하는 네트워크 소켓 옵션이 기본적으로 설정됩니다. 컨트롤러가 가상 기기에 연결되면 기기 상태를 보여주는 화면이 표시됩니다.

가상 기기 그래픽 사용자 인터페이스

가상 컨트롤러 앱에서 변경할 때 앱이 기기의 RPC 서버에 요청을 전송하고 초당 한 번 RPC 서버를 폴링하여 상태를 가져옵니다.

가상 기기 컨트롤러 앱을 사용하여 기기 수수료 흐름의 일부로 QR 코드를 가져올 수도 있습니다. 기기 이미지 옆에 있는 QR 코드 아이콘을 클릭하여 이 기기의 QR 코드를 표시합니다.

QR 코드

이 QR 코드를 사용하여 기기를 위임할 수 있습니다.

6. 기기 수수료 입찰

참고: 이 단계는 Google Home 개발자 콘솔에서 이미 프로젝트를 설정한 경우에만 성공합니다.

Nest Hub

기기를 Matter 패브릭에 의뢰하려면 허브가 필요합니다. 이는 Nest Hub (2세대)와 같이 Matter를 지원하고 스레드 지원 기기의 경계 라우터 역할을 하며 스마트 홈 인텐트를 라우팅하는 로컬 처리 경로로 기능하는 Google Nest 기기입니다.

의뢰를 시작하기 전에 다음 사항을 확인하세요.

  • 허브가 Google Home Console에 로그인할 때 사용한 Google 계정과 페어링되어 있습니다.
  • 허브가 Virtual Matter 기기를 실행하는 데 사용하는 컴퓨터와 동일한 Wi-Fi 네트워크에 연결되어 있어야 합니다.
  • 허브가 Google Home 앱에서 사용 중인 구조에 있습니다. Google Home 그래프의 '집'은 집을 나타냅니다.

QR 코드 받기

의뢰 절차에서는 QR 코드를 통해 제공되는 Matter의 온보딩 정보가 필요합니다. 가상 기기 컨트롤러에서 가상 기기의 QR 코드를 얻을 수 있습니다.

수수료 작업 수행

  1. Google Home 앱을 엽니다.
  2. 왼쪽 상단의 +를 탭합니다.
  3. 기기 설정을 탭합니다.
  4. 새 기기를 탭합니다.
  5. 집을 선택하고 다음을 탭합니다.
  6. Google Home 앱에서 기기를 검색합니다. '법적 사안 기기를 찾았습니다...'라는 메시지가 표시되면 '예'를 탭합니다. 그렇지 않으면 다른 기기 설정을 탭한 다음 기기 목록에서 Matter 기기를 선택합니다.
  7. 카메라로 기기의 QR 코드 또는 웹사이트에서 생성한 QR 코드를 가리킵니다.
  8. Google Home 앱 흐름에 표시된 대로 페어링 절차를 계속 진행합니다.

이러한 단계를 완료하면 Matter 가상 기기가 성공적으로 의뢰되고 Google Home 앱에 새로운 아이콘으로 표시됩니다.

Google Home 앱의 페어링된 전구

문제 해결

'연결 문제' 또는 'Google에 연락할 수 없음' 오류 메시지와 함께 의뢰가 실패함

  • Google Home 콘솔에서 올바른 VID/PID 조합으로 프로젝트를 만들었는지, 동일한 VID/PID 조합을 사용하는 다른 프로젝트가 없는지 확인합니다.

오랜 기간 '기기를 검색'한 후 실행이 실패함

7. 기기 제어

Matter 지원 기기가 의뢰되어 Google Home 앱에 전구 모양으로 표시되면 다음과 같이 다양한 방법으로 기기 제어를 테스트할 수 있습니다.

  • Google 어시스턴트를 사용합니다.
  • Google Home 앱 사용
  • 가상 기기 GUI 사용

Google 어시스턴트

휴대전화 또는 허브에서 Google 어시스턴트를 사용하여 "Hey Google, 조명 전환"과 같은 음성 명령으로 기기 상태를 전환할 수 있습니다.

더 많은 명령어 예를 보려면 Google Home 앱에 추가된 스마트 홈 기기 제어하기의 음성 명령으로 스마트 홈 기기 제어하기 섹션을 참고하세요.

Google Home 앱

Google Home 앱에 표시된 전구 아이콘 옆에 있는 사용 및 사용 중지 라벨을 탭해도 됩니다.

자세한 내용은 Google Home 앱에 추가된 스마트 홈 기기 제어하기의 Google Home 앱으로 기기 제어 섹션을 참고하세요.

가상 기기 GUI

가상 기기 GUI와 상호작용하여 기기 상태를 변경할 수 있습니다. 가상 기기 컨트롤러, 휴대전화의 Google Home 앱 또는 허브를 통해 가상 기기를 제어하는지와 상관없이 이러한 모든 인터페이스는 가상 기기의 현재 상태를 반영합니다.

8. 수고하셨습니다.

첫 번째 Matter 기기를 만들었습니다. 좋습니다.

이 Codelab을 통해 학습한 내용은 다음과 같습니다.

  • 사전 패키징된 Docker 이미지를 사용하여 Matter 개발 환경을 설치합니다.
  • Matter 가상 기기를 빌드하고 실행합니다.
  • Google Home에서 가상 기기를 수수료로 관리하고 제어하세요.

Matter에 관한 자세한 내용은 다음 자료를 참고하세요.