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 콘솔에 로그인하고 작업 > 모니터링 > 대시보드로 이동하여 Google Home 대시보드를 확인합니다.
프로젝트에서 사용할 수 있는 대시보드에는 여러 가지가 있습니다(다른 GCP 제품 포함). 스마트 홈용으로 제공되는 대시보드에는 Google Home 애널리틱스라는 접두사가 붙습니다.
현재 전체 프로젝트를 포괄하는 일반 대시보드는 물론 특정 통합 (클라우드, 로컬, Matter) 또는 기기 유형 (카메라)을 위한 대시보드가 마련되어 있습니다. 이 대시보드는 요청을 처리하는 정상적으로 작동하는 프로젝트와 해당 유형의 통합이 있는 경우에만 데이터를 포함합니다.
이러한 대시보드 중 하나를 열면 다음과 같은 일련의 차트가 표시됩니다.
Google Home 대시보드에는 프로젝트와 연결된 이벤트의 세부정보를 보여주는 다양한 차트가 포함되어 있습니다. 각 통합 대시보드에는 프로젝트에서 처리한 총 요청 수를 보여주는 차트, 해당 통합 유형의 성공률을 보여주는 차트, 관련 기기 유형 및 트레잇을 보여주는 여러 차트가 표시됩니다. 또한 Matter를 사용하면 커미셔닝 성공 여부와 기기의 업데이트 출시를 추적하는 차트 세트를 사용할 수 있습니다.
Google Home 분석 대시보드에 표시되는 차트가 포함된 기본 보기는 스마트 홈 측정항목 데이터를 사용하여 프로젝트에 대해 만든 보기일 뿐입니다. 측정항목 탐색기를 사용하여 동일한 기본 측정항목에서 자체 차트를 만들고 커스텀 대시보드에 저장할 수도 있습니다.
액세스 오류 로그
로그 탐색기는 프로젝트에서 생성된 이벤트 로그를 사용하는 도구 모음입니다. Google Cloud 콘솔에서 작업 > 로깅 > 로그 탐색기로 이동하여 액세스할 수 있습니다.
로그 탐색기를 열면 다음과 같은 뷰가 표시됩니다.
탐색기 창에는 로그를 보고, 필터링하고, 쿼리하고, 분석할 수 있는 다양한 도구가 있습니다. 기본적으로 이 뷰에는 스마트 홈 외부에서 생성된 로그를 비롯하여 프로젝트에서 사용할 수 있는 모든 시스템에서 생성된 로그가 표시됩니다. 따라서 디버그하려는 이벤트를 필터링하여 이러한 로그를 사용하는 것이 중요합니다. 디버깅 섹션에서 자세히 설명하겠습니다.
3. 커미셔닝 문제 디버그
먼저 살펴볼 측정항목 유형은 Matter 커미셔닝 이벤트에 관한 것입니다. 커미셔닝은 사용자가 Matter 기기를 처음 설정하는 데 필요한 일련의 단계를 말합니다.
기기 커미셔닝 중에 Matter 기기, Google Home 앱, Matter 패브릭 간에 일련의 상호작용이 발생합니다. 다음 이미지는 이러한 이벤트 중 일부를 보여줍니다.
이러한 각 단계에 관한 자세한 내용은 Matter Primer의 커미션 페이지에서 확인할 수 있습니다. 이 섹션에서는 커미셔닝 문제를 디버그하는 도구와 기법을 설명합니다.
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 디버깅에 관한 경고 메시지가 휴대전화에 표시될 수 있습니다.
- 이 경고 메시지가 표시되면 허용을 클릭합니다.
- 터미널에서 list devices 명령어를 실행하여 컴퓨터가 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 서비스를 통해 홈 / 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 생태계는 새롭기 때문에 이러한 리소스에서 다루지 않는 문제가 있을 수 있습니다. 이 경우 언제든지 YouTube 또는 커뮤니티에 연락하여 지원을 요청할 수 있습니다.
개발자 채널 방문하기
Google에서는 다음과 같은 세 가지 개발자 채널을 적극적으로 모니터링합니다.
이러한 각 채널은 동일한 팀에서 주기적으로 모니터링하지만 어떤 채널을 사용해야 하는지에 관해서는 몇 가지 중요한 차이점이 있습니다.
- Stack Overflow: 구현 관련 질문이나 안내를 받기 위해 Google 및 스마트 홈 개발자 커뮤니티에 문의할 수 있습니다. 이 채널은 문제 해결 방법이나 특정 기능 구현 방법을 문의하는 데 가장 적합합니다.
- Issue Tracker: 외부 사용자가 생태계의 오류를 신고할 수 있는 Google에서 운영하는 공식 Issue Tracker 시스템입니다. 필요한 경우 파일을 첨부하고 민감한 정보를 공유할 수 있는 웹 도구를 제공합니다. 생태계 문제를 보고하거나 기능 요청을 공유하려면 Issue Tracker를 사용하는 것이 가장 좋습니다.
- 개발자 포럼: Nest 개발자 포럼을 통해 공식 Google 지원팀 및 커뮤니티 전문가의 안내를 받을 수 있습니다. 이 포럼은 \ 개발에 관한 공식 안내를 받는 데 가장 적합합니다.
개발자 뉴스레터 구독하기
질문이 있는 경우 개발자 채널을 방문하는 것 외에도 새로운 기능을 소개하고 Google 스마트 홈 생태계의 상태에 관한 뉴스를 제공하는 분기별 뉴스레터를 발행합니다.
가입 양식을 사용하여 개발자 뉴스레터를 받을 수 있습니다.
7. 축하합니다
축하합니다. 권장 도구와 기법을 사용하여 Matter 통합을 디버그하는 방법을 알아봤습니다. Google Home과 Matter 통합을 빌드하는 데 도움이 되기를 바랍니다.
다음 단계
다음 연습을 해 보고 추가 리소스를 살펴보세요.