1. 시작하기 전에
Matter는 최종 사용자에게 원활한 크로스 플랫폼 기기 설정 및 제어 환경을 제공합니다. 이는 내부적으로 서로 함께 작동하는 여러 생태계 구성요소가 있기 때문에 가능한 일입니다. 이러한 시스템 문제 해결은 신규 개발자에게 부담스러울 수 있는 경우가 많으므로 Google에서는 Google Home을 사용하여 Matter 개발자가 보다 쉽게 작업을 수행할 수 있도록 일련의 도구와 기법을 개발했습니다.
이 Codelab에서는 Matter의 세 가지 기본 구성요소를 다룹니다. Google은 휴대전화 및 허브에서 수집한 다음과 같은 각 시스템별로 일련의 문제 해결 분석을 제공합니다.
개발자는 기기 개발 주기 전반에 걸쳐 경험하는 문제를 완화할 수 있어야 합니다. 프로젝트를 시작한 후에는 종합적으로 현장에 있는 기기의 문제 트렌드를 모니터링하고 소프트웨어 업데이트를 통해 문제를 해결해야 합니다. 이 Codelab에서는 이 두 가지 목적에 모두 사용할 수 있는 기법을 다룹니다.
기본 요건
- 작동하는 Matter 프로젝트 및 기기 설정으로 Matter 시작하기 가이드를 완료합니다.
- 워크스테이션에 연결할 수 있는 Android 휴대전화가 있어야 합니다 (ADB 로그의 경우).
학습할 내용
- 스마트 홈용 분석 도구를 사용하여 Matter 문제를 대규모로 모니터링하는 방법
- 오류 로그에 액세스하고 정보를 수집하여 오류를 분류하는 방법
- Matter 문서 및 지원 리소스에 액세스하여 도움을 요청하는 방법
2. Google Home 애널리틱스 보기
성능 모니터링은 Google Home 생태계와의 성공적인 통합을 위해 매우 중요합니다. Google은 Google Cloud Platform에서 스마트 홈 개발자에게 일련의 모니터링 도구를 제공합니다. 이러한 도구를 사용하여 프로젝트 성능을 측정할 수 있습니다.
프로젝트 측정항목에 액세스
- 데이터에 액세스하기 위한 첫 번째 단계는 Google Cloud Console에 로그인하고 작업 > Monitoring > 대시보드로 이동하여 Google Home 대시보드를 확인하는 것입니다.
다른 GCP 제품을 비롯해 프로젝트에 사용할 수 있는 다양한 대시보드가 있습니다. 스마트 홈을 위해 제공되는 대시보드는 Google Home 애널리틱스 접두사로 제공됩니다.
현재 전체 프로젝트를 다루는 일반 대시보드와 특정 통합 (클라우드, 로컬, Matter) 또는 기기 유형 (카메라)을 위한 대시보드가 있습니다. 이 대시보드에는 해당 유형의 통합이 있고 요청을 처리하는 작동 중인 프로젝트가 있는 경우에만 데이터가 포함됩니다.
이러한 대시보드 중 하나를 열면 다음과 같은 일련의 차트가 표시됩니다.
Google Home 대시보드에는 프로젝트와 관련된 이벤트의 세부정보를 보여주는 다양한 차트가 포함되어 있습니다. 각 통합 대시보드에는 프로젝트에서 처리한 총 요청 수를 보여주는 차트, 해당 통합 유형의 성공률을 보여주는 차트, 관련된 기기 유형과 특성을 보여주는 여러 차트가 표시됩니다. 또한 Matter를 사용하면 커미셔닝 성공과 기기의 업데이트 출시를 추적하는 일련의 차트를 이용할 수 있습니다.
Google Home 애널리틱스 대시보드에 표시되는 차트가 포함된 기본 뷰는 스마트 홈 측정항목 데이터를 사용하여 프로젝트를 위해 만든 뷰일 뿐입니다. 측정항목 탐색기를 사용하여 동일한 기본 측정항목으로 나만의 차트를 만들고 맞춤 대시보드에 저장할 수도 있습니다.
오류 로그 액세스
로그 탐색기는 프로젝트에서 생성된 이벤트 로그를 사용하는 도구 모음입니다. Google Cloud 콘솔에서 작업 > 로깅 > 로그 탐색기로 이동하여 액세스할 수 있습니다.
로그 탐색기를 열면 다음과 같은 뷰가 표시됩니다.
탐색기 창에는 로그를 보고, 필터링하고, 쿼리하고, 분석할 수 있는 다양한 도구가 포함되어 있습니다. 기본적으로 이 뷰에는 스마트 홈 외부에서 생성된 로그를 포함하여 프로젝트에 사용할 수 있는 모든 시스템에서 생성된 로그가 표시됩니다. 그렇기 때문에 디버그하려는 이벤트를 필터링하여 이러한 로그를 사용하는 것이 중요합니다. 디버깅 섹션에서 이에 관해 더 자세히 알아보겠습니다.
3. 커미셔닝 문제 디버그
첫 번째로 살펴볼 측정항목 유형은 Matter 커미셔닝 이벤트에 관한 것입니다. 커미셔닝은 사용자가 Matter 기기를 처음 설정하는 데 필요한 일련의 단계를 의미합니다.
기기 커미셔닝 중에 Matter 기기, Google Home 앱, Matter 패브릭 간에 일련의 상호작용이 발생합니다. 다음 이미지는 이러한 이벤트 중 일부를 보여줍니다.
Matter Primer의 수수료 페이지에서 각 단계에 관해 자세히 알아볼 수 있습니다. 이 섹션에서는 커미셔닝 문제를 디버그하는 도구와 기술을 다룹니다.
Google Home 애널리틱스 사용
Google에서는 개발자가 이벤트를 추적하고 오류가 발생할 수 있는 단계를 파악하여 커미셔닝 문제를 조사할 수 있도록 일련의 측정항목을 만들었습니다. 이전 섹션에서 설명한 것처럼 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. 기기 제어 문제 디버그
사용자가 Matter 기기를 설정하고 Google Home 생태계에 제공하면 음성으로 Google 어시스턴트를 사용하거나 (예: "Hey Google, 거실 조명 켜 줘") Home 앱 또는 Google Nest 디스플레이 기기의 UI를 사용하여 명령어를 실행할 수 있습니다.
최종 기기와 Google Hub 간의 제어 사양이 Matter에 의해 조정되므로 기기 제어 측면에서 오류가 줄어들 것으로 예상됩니다. 이와 관계없이 Google에서는 이러한 유형의 문제를 디버그할 수 있도록 측정항목과 로그를 제공합니다.
측정항목 사용
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의 기기 커미셔닝 및 제어 문제를 처리하는 방법을 배웠습니다. 또한 생태계 내에는 고품질 통합을 보장하기 위해 Google 추천 기법을 사용할 수 있는 다른 기능이 있습니다.
OTA 업데이트 추적
Google Home에서 발행한 Matter 기기 무선 업데이트 (OTA)의 출시를 추적하기 위해 Google에서는 현장에 있는 기기의 하드웨어 및 소프트웨어 버전을 보여주는 일련의 측정항목을 제공합니다.
콘솔에서 업데이트를 실행한 후에는 다음 측정항목을 주시하세요.
출시 후 며칠 동안 현장에서 점점 더 많은 기기가 OTA 소프트웨어 출시와 관련된 새 소프트웨어 버전을 받게 됩니다.
6. 지원 요청
Google에서는 Matter 문제를 디버그할 수 있는 도구와 문서를 제공하지만, Matter 생태계가 새로 구축되기 때문에 이러한 리소스에서 다루지 않는 문제가 발생할 수 있습니다. 이러한 경우 YouTube 또는 커뮤니티에 문의하여 지원을 요청할 수 있습니다.
개발자 채널 방문하기
Google 내에서 활발하게 모니터링되는 개발자 채널은 다음과 같습니다.
동일한 팀에서 이러한 각 채널을 주기적으로 모니터링하지만, 어떤 채널을 사용해야 하는지와 관련해 몇 가지 중요한 차이점이 있습니다.
- Stack Overflow: Google 및 스마트 홈 개발자 커뮤니티에 연락하여 구현 관련 질문을 하거나 안내를 받을 수 있습니다. 이 채널은 문제를 해결하거나 특정 기능을 구현하는 방법을 질문하는 데 가장 적합합니다.
- Issue Tracker: Google에서 운영하는 공식 Issue Tracker 시스템으로, 외부 잠재고객이 생태계의 오류를 보고할 수 있습니다. 필요한 경우 파일을 첨부하고 민감한 정보를 공유할 수 있는 웹 도구를 제공합니다. Issue Tracker는 생태계 문제를 신고하거나 기능 요청을 공유하는 데 가장 적합합니다.
- 개발자 포럼: 공식 Google 지원 및 커뮤니티 전문가의 안내를 받으려면 Nest 개발자 포럼을 통해 문의하세요. 이 포럼은 개발을 위한 공식 안내를 구하는 데 가장 적합합니다.
개발자 뉴스레터 구독하기
개발자 채널을 방문하여 궁금한 점을 질문하는 것 외에도 Google에서는 새로운 기능을 소개하고 Google 스마트 홈 생태계의 현황을 소개하는 분기별 뉴스레터도 출시합니다.
가입 양식을 사용하여 개발자 뉴스레터를 받을 수 있습니다.
7. 축하합니다
수고하셨습니다 권장되는 도구와 기법을 사용하여 Matter 통합을 디버그하는 방법을 알아봤습니다. Google Home과 Matter의 통합을 즐겁게 빌드하시길 바랍니다.
다음 단계
다음 실습을 해 보고 추가 리소스를 살펴보세요.