1. 시작하기 전에
Matter는 최종 사용자에게 원활한 크로스 플랫폼 기기 설정 및 제어 환경을 제공합니다. 이는 주로 백그라운드에서 서로 연동되는 여러 생태계 구성요소 덕분입니다. 이러한 시스템의 문제 해결은 신규 개발자에게 부담스러울 수 있으므로 Google Home을 사용하는 Matter 개발자의 삶을 더 쉽게 만들어 주는 일련의 도구와 기술을 개발했습니다.
이 Codelab에서는 Matter의 세 가지 주요 구성요소를 다룹니다. Google은 이러한 각 시스템에 대해 휴대전화와 허브에서 수집된 개발자용 문제 해결 분석을 제공합니다.
개발자는 기기 개발 주기 전반에 걸쳐 발생하는 문제를 완화할 수 있어야 합니다. 프로젝트를 출시한 후에는 필드에 있는 기기의 문제 동향을 집계 방식으로 모니터링하고 소프트웨어 업데이트를 통해 문제를 수정해야 합니다. 이 Codelab에서는 이러한 두 가지 목적에 사용할 수 있는 기법을 다룹니다.
기본 요건
- 작동하는 Matter 프로젝트와 기기 설정으로 Matter 시작하기 가이드 완료
- 워크스테이션에 연결할 수 있는 Android 휴대전화가 있어야 합니다 (ADB 로그용).
학습할 내용
- 스마트 홈용 분석 도구를 사용하여 대규모로 Matter 문제를 모니터링하는 방법
- 오류 로그에 액세스하고 정보를 수집하여 오류를 분류하는 방법
- Matter 문서 및 지원 리소스에 액세스하여 도움을 받는 방법
2. Google Home 분석 보기
성능 모니터링은 Google Home 생태계와의 성공적인 통합에 매우 중요합니다. Google에서는 Google Cloud Platform에서 스마트 홈 개발자에게 모니터링 도구 세트를 제공합니다. 이러한 도구를 사용하여 프로젝트의 성능을 측정할 수 있습니다.
프로젝트 측정항목 액세스
- 데이터에 액세스하는 첫 번째 단계는 Google Cloud 콘솔에 로그인하고 작업 > 모니터링 > 대시보드로 이동하여 Google Home 대시보드를 확인하는 것입니다.
프로젝트에서 사용할 수 있는 대시보드 (다른 GCP 제품 포함)가 여러 개 있습니다. 스마트 홈에 제공되는 대시보드에는 Google Home 분석이라는 접두사가 붙습니다.
현재 전체 프로젝트를 다루는 일반 대시보드와 특정 통합 (클라우드, 로컬, Matter) 또는 기기 유형 (카메라)을 위한 대시보드가 있습니다. 이러한 대시보드에는 요청을 처리하는 작동 가능한 프로젝트와 함께 해당 유형의 통합이 있는 경우에만 데이터가 포함됩니다.
이러한 대시보드 중 하나를 열면 다음과 같은 일련의 차트가 표시됩니다.
Google Home 대시보드에는 프로젝트와 연결된 이벤트의 세부정보를 보여주는 다양한 차트가 포함되어 있습니다. 각 통합 대시보드에는 프로젝트에서 처리한 총 요청 수를 보여주는 차트, 해당 통합 유형의 성공률을 보여주는 차트, 관련 기기 유형과 특성을 보여주는 여러 차트가 표시됩니다. 또한 Matter를 사용하면 커미셔닝 성공 여부와 기기의 업데이트 출시를 추적하는 차트 세트가 제공됩니다.
Google Home 애널리틱스 대시보드에 표시되는 차트가 포함된 기본 뷰는 스마트 홈 측정항목 데이터를 사용하여 프로젝트를 위해 Google에서 만든 뷰일 뿐입니다. 측정항목 탐색기를 사용하여 동일한 기본 측정항목으로 자체 차트를 만들어 커스텀 대시보드에 저장할 수도 있습니다.
액세스 오류 로그
로그 탐색기는 프로젝트에서 생성된 이벤트 로그를 사용하는 도구 모음입니다. 작업 > 로깅 > 로그 탐색기로 이동하면 Google Cloud 콘솔에서 액세스할 수 있습니다.
로그 탐색기를 열면 다음과 같은 뷰가 표시됩니다.
탐색기 창에는 로그를 보고, 필터링하고, 쿼리하고, 분석하는 다양한 도구가 포함되어 있습니다. 기본적으로 이 뷰에는 스마트 홈 외부에서 생성된 로그를 비롯하여 프로젝트에서 사용할 수 있는 모든 시스템에서 생성된 로그가 표시됩니다. 따라서 디버그하려는 이벤트를 필터링하여 이러한 로그를 사용하는 것이 중요합니다. 이에 대해서는 디버깅 섹션에서 자세히 다루겠습니다.
3. 커미셔닝 문제 디버그
첫 번째 측정항목 유형은 Matter 커미셔닝 이벤트에 관한 것입니다. 커미셔닝은 사용자가 Matter 기기를 처음 설정하는 데 필요한 단계 집합을 의미합니다.
기기 커미셔닝 중에 Matter 기기, Google Home 앱, Matter 패브릭 간에 일련의 상호작용이 발생합니다. 다음 이미지는 이러한 이벤트 중 일부를 보여줍니다.
각 단계에 대한 자세한 내용은 Matter 기본 사항의 커미셔닝 페이지를 참고하세요. 이 섹션에서는 커미셔닝 문제를 디버그하는 도구와 기법을 다룹니다.
Google Home 분석 사용
이벤트를 추적하고 오류가 발생할 수 있는 단계를 파악하여 커미셔닝 문제를 조사할 수 있는 측정항목 세트가 마련되어 있습니다. 이전 섹션에서 설명한 대로 Matter 통합 대시보드에서 확인할 수 있습니다.
이 대시보드의 차트는 기기 프로비저닝에 관한 데이터를 제공합니다.
기기 수 차트에는 특정 날짜에 사용자가 시도한 커미셔닝 횟수가 표시됩니다. 성공률은 Google 측에서 이러한 이벤트의 인식된 성공률을 보여줍니다. 각 커미셔닝 시도는 연결된 상태가 있는 이벤트 세트를 생성합니다. 이러한 상태에서 오류가 발생하면 오류 분류 차트에도 표시됩니다.
커미셔닝 상태:
- COMMISSIONING_STARTED
- ONBOARDING_PAYLOAD_GENERATED
- LOCAL_DISCOVERY_SUCCESSFUL
- PASE_CONNECTION_SUCCESSFUL
- NOC_ADDED_SUCCESSFULLY
- COMMISSIONING_COMPLETE
이러한 이벤트의 자세한 버전을 보려면 작업 > 로깅 > 로그 탐색기로 이동하세요. 커미셔닝 오류를 필터링하려면 쿼리 필드에서 'clientUpdateLog'와 'severity>=ERROR'를 함께 검색하면 됩니다.
Matter의 커미셔닝 오류 로그는 다음과 같습니다.
{
"insertId": "1a32ry0f6xpzzn",
"jsonPayload": {
"clientUpdateLog": {
"MatterUpdate": {
"reportedProductId": 55,
"sessionId": "1584879052892229997",
"reportedVendorId": 4800,
"commissioningState": "GENERIC_COMMISSIONING_ERROR",
"status": "GENERIC_ERROR"
}
}
},
"resource": {
"type": "assistant_action_project",
"labels": {
"project_id": "<project-id>"
}
},
"timestamp": "2023-03-01T07:09:55.216425297Z",
"severity": "ERROR",
"logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
"receiveTimestamp": "2023-03-01T07:09:55.216425297Z"
}
커미셔닝 상태와 상태 코드 외에도 오류 로그에는 포착된 오류의 타임스탬프와 오류를 일으킨 제품을 식별할 수 있는 Matter 제품 ID가 포함됩니다. 동일한 커미셔닝 시도에서 생성된 로그 집합은 sessionId를 공유합니다.
Google Home 분석의 측정항목을 사용하면 문제가 발생할 수 있는 단계를 파악할 수 있습니다. 기기 커미셔닝 오류의 근본 원인을 찾으려면 커미셔닝 프로세스에 사용된 모바일 기기에서 생성된 로그를 사용하여 추가 디버깅을 해야 할 수도 있습니다. 이러한 경우에는 Android 디버그 브리지가 필요합니다.
Android 디버그 브리지 (ADB) 사용
커미셔닝 문제를 해결하는 또 다른 방법은 Android 디버그 브리지 (ADB) 명령줄 도구를 사용하는 것입니다. 커미셔닝은 주로 모바일 기기와 Matter 기기 간에 처리되므로 ADB 도구를 사용하여 커미셔닝 전반에 걸쳐 Google Home 앱에서 생성된 로그에 액세스할 수 있습니다.
플랫폼 도구 설치
ADB는 Android SDK 플랫폼 도구의 일부로 제공되며, Android 스튜디오 또는 sdkmanager 명령줄 도구를 통해 설치할 수 있습니다.
시스템에 플랫폼 도구를 설치한 후 다음 명령어를 사용하여 터미널에서 버전 번호를 확인하여 ADB를 확인합니다.
$ adb -- version
그러면 설치된 ADB 유틸리티의 버전 번호가 오류 없이 표시됩니다.
USB 디버깅 사용 설정
다음은 Android 기기에서 USB 디버깅을 사용 설정하는 것입니다.
먼저 단계에 따라 기기에서 개발자 옵션을 사용 설정한 다음 USB 디버깅을 사용 설정합니다.
이렇게 하면 ADB가 현재 기기에서 실행 중인 앱에서 생성된 로그에 액세스할 수 있습니다.
기기 ID 가져오기
- 다음 명령어를 사용하여 ADB 서버를 실행합니다.
$ adb start-server
- ADB 서버를 실행하는 컴퓨터에 휴대전화를 연결합니다.
USB 디버깅에 관한 경고 메시지가 휴대전화에 표시되어 컴퓨터에서 휴대전화의 정보에 액세스하도록 허용할지 묻는 메시지가 표시될 수 있습니다.
- 이 경고 메시지가 표시되면 허용을 클릭합니다.
- 터미널에서 기기 목록 명령어를 실행하여 다음 명령어를 사용하여 컴퓨터가 ADB를 통해 휴대전화에 액세스할 수 있는지 확인합니다.
$ adb devices
이렇게 하면 다음과 비슷한 응답이 표시됩니다.
List of devices attached <phone-id> device
<phone-id>는 기기를 고유하게 식별하는 영숫자 문자열입니다.
- 다음 단계에서 사용할
<phone-id>값을 기억해둡니다.
시스템 정보 수집
다음으로 기기에 설치된 앱과 시스템의 버전 정보를 확인합니다.
- Android OS 버전을 확인하려면 다음 단계를 따르세요.
$ adb -s <phone-id> shell getprop ro.build.version.release
- Google Home 앱 버전을 확인하려면 다음 단계를 따르세요.
$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName
- Google Play 서비스 버전을 확인하려면 다음 단계를 따르세요.
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
- Play 서비스를 통해 Home / Matter 제어 모듈이 있는지 확인하려면 다음 단계를 따르세요.
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"
이러한 반환 값이 Google 생태계에서 지원되는지 확인하세요. 커미셔닝 실패에 관한 지원을 요청할 때는 항상 지원 티켓에 시스템 정보를 포함하세요.
오류 로그 수집
그런 다음 로그 수집 프로세스를 시작하고 커미셔닝 단계를 거쳐 디버그하려는 오류 이벤트를 생성합니다.
<phone-id>와 컴퓨터에 로그가 저장될<file-name>(예:debug_file.txt)에 복사합니다.
$ adb -s <phone-id> logcat > <file-name>
그러면 로깅 프로세스가 즉시 시작됩니다. 제공된 이름의 파일이 아직 없으면 파일이 생성되고 각 이벤트 후 휴대전화의 로그가 파일에 추가됩니다.
Matter 기기로 커미셔닝 단계를 진행합니다.
- 디버그하려는 오류에 도달하면 실행 중인 터미널 창에서
Control+C를 눌러 로깅을 중지합니다.
이제 로그가 <file-name> 로깅 파일에 저장됩니다. 이 프로세스는 기기에서 추적되는 모든 실행 중인 프로세스의 로그를 기록하므로 이 파일에는 많은 로그가 있습니다. 따라서 필요한 항목을 검색하여 이러한 로그를 항상 활용해야 합니다.
오류 로그 분석
커미셔닝 프로세스는 GHA 내의 MatterCommissioner라는 하위 시스템을 통해 처리됩니다.
- 커미셔닝 오류 분석 시 사용되는 기본 전략에 따라 다음 명령어를 사용하여 MatterCommissioner 하위 시스템에서 생성된 오류를 찾습니다.
$ grep "MatterCommissioner" <file-name>
이렇게 하면 커미셔닝 프로세스의 이벤트가 포함된 출력이 생성됩니다.
- Matter 기기에서 스레드를 사용하는 경우 다음 명령어를 통해 스레드 하위 시스템에서 생성된 오류를 확인할 수도 있습니다.
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>
ADB 디버깅 프로세스에서 생성된 로그 파일을 분석할 때는 특정 패턴도 찾아보세요. 많은 커미셔닝 오류에는 오류 메시지에 'commissioning failure' 문자열이 포함됩니다.
- 다음 명령어를 사용하여 커미셔닝 실패 메시지를 검색합니다.
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"
4. 기기 제어 문제 디버그
사용자가 Google Home 생태계에 Matter 기기를 설정하고 커미셔닝하면 Google 어시스턴트를 사용하여 음성으로 명령을 내리거나('Hey Google, 거실 조명을 켜 줘' 등) Home 앱 또는 Google Nest 디스플레이 기기의 UI를 사용하여 명령을 내릴 수 있습니다.
엔드 기기와 Google 허브 간의 제어 사양은 Matter에 의해 중재되므로 기기 제어 측면에서 오류가 줄어들 것으로 예상됩니다. 어떤 경우든 이러한 유형의 문제를 디버깅할 수 있도록 측정항목과 로그가 제공됩니다.
측정항목 사용
Matter 통합 대시보드에는 기기 제어와 관련된 여러 측정항목이 표시됩니다. 현장에서 기기의 성능을 평가하는 데 중요한 세 가지 차트가 있습니다.
제어 문제가 발생하면 일반적으로 성공률이 감소하고 오류 분류 차트가 증가합니다. 오류 분류 차트에는 기기 제어 시도가 실패한 이유에 관해 Google Nest Hub에서 포착한 오류가 표시됩니다.
로그 사용
각 Matter 기기 제어 문제도 시스템에 오류 로그를 생성합니다. 이러한 오류는 로그 탐색기에서 'executionLog'를 검색하여 필터링할 수 있습니다.
Matter 기기 제어 오류 로그는 다음과 같이 표시됩니다.
{
"insertId": "1a32ry0f6xpzzn",
"jsonPayload": {
"executionLog": {
"executionResults": [
{
"executionType": "MATTER",
"latencyMsec": "6000",
"actionResults": [
{
"action": {
"actionType": "ONOFF_OFF",
"trait": "TRAIT_ON_OFF"
},
"status": {
"externalDebugString": "No message was received before the deadline.",
"statusType": "RESPONSE_TIMEOUT",
"fallbackToCloud": false,
"isSuccess": false
},
"device": {
"deviceType": "OUTLET"
}
}
],
"requestId": "1487232799486580805"
}
]
},
"locale": "en-US"
},
"resource": {
"type": "assistant_action_project",
"labels": {
"project_id": "<project-id>"
}
},
"timestamp": "2023-03-01T15:47:27.311673018Z",
"severity": "ERROR",
"logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
"receiveTimestamp": "2023-03-01T15:47:27.311673018Z"
}
각 오류 로그에는 타임스탬프, 기기 유형, 특성, statusType의 제어 요청과 관련된 오류가 포함됩니다. 많은 제어 오류에는 오류의 내용을 설명하는 짧은 오류 메시지인 externalDebugString도 포함됩니다.
5. 기타 기능 디버그
지금까지 Matter의 기기 커미셔닝 및 제어 문제를 처리하는 방법을 알아봤습니다. 생태계 내에서 사용할 수 있는 다른 기능이나 양질의 통합을 보장하기 위한 권장 기법도 있습니다.
OTA 업데이트 추적
Google Home에서 발행한 Matter 기기의 무선 (OTA) 업데이트 출시를 추적하기 위해 현장에 있는 기기의 하드웨어 및 소프트웨어 버전을 보여주는 측정항목 세트가 제공됩니다.
콘솔에서 업데이트를 실행한 후에는 다음 측정항목을 주시하세요.
출시 후 며칠 동안 현장의 기기가 OTA 소프트웨어 출시와 연결된 새 소프트웨어 버전을 점점 더 많이 가져오는 것을 확인할 수 있습니다.
6. 지원 요청
Google에서는 Matter 문제를 디버그할 수 있는 도구와 문서를 제공하지만 Matter 생태계는 새롭기 때문에 이러한 리소스에서 다루지 않는 문제가 있을 수 있습니다. 이러한 경우 언제든지 Google 또는 커뮤니티에 문의하여 지원을 받으실 수 있습니다.
개발자 채널 방문
Google 내에서 적극적으로 모니터링되는 개발자 채널은 다음과 같습니다.
이러한 채널은 모두 동일한 팀에서 주기적으로 모니터링하지만, 각 채널을 사용해야 하는 시기에는 몇 가지 중요한 차이점이 있습니다.
- Stack Overflow: 구현 관련 질문이 있거나 안내가 필요한 경우 Google 및 스마트 홈 개발자 커뮤니티에 문의하세요. 이 채널은 문제 해결 방법이나 특정 기능 구현 방법을 문의하는 데 가장 적합합니다.
- Issue Tracker: 외부 사용자가 생태계의 오류를 신고할 수 있는 공식 Google 운영 문제 추적 시스템입니다. 필요한 경우 파일을 첨부하고 민감한 정보를 공유할 수 있는 웹 도구를 제공합니다. Issue Tracker는 생태계 문제를 신고하거나 기능 요청을 공유하는 데 가장 적합합니다.
- 개발자 포럼: 공식 Google 지원팀 및 커뮤니티 전문가의 안내를 받으려면 Nest 개발자 포럼을 통해 문의하세요. 이 포럼은 \ 개발에 관한 공식 가이드를 얻는 데 가장 적합합니다.
개발자 뉴스레터 신청
질문이 있는 경우 개발자 채널을 방문하는 것 외에도 새로운 기능을 강조하고 Google 스마트 홈 생태계의 상태에 관한 소식을 제공하는 분기별 뉴스레터를 발행합니다.
가입 양식을 사용하여 개발자 뉴스레터를 받아보실 수 있습니다.
7. 축하합니다
축하합니다. Google에서 권장하는 도구와 기법을 사용하여 Matter 통합을 디버그하는 방법을 배웠습니다. Google Home으로 Matter 통합을 빌드하는 데 즐거운 시간을 보내시기 바랍니다.
다음 단계
다음 연습을 해 보고 추가 리소스를 살펴보세요.