1. 시작하기 전에
Matter는 최종 사용자에게 원활한 크로스 플랫폼 기기 설정 및 제어 환경을 제공합니다. 이는 주로 여러 생태계 구성요소가 백그라운드에서 서로 함께 작동하기 때문에 가능합니다. 신규 개발자에게는 이와 같은 문제 해결 시스템이 어려울 수 있으므로 Google에서는 Matter 개발자가 Google Home을 사용하는 생활을 더 쉽게 할 수 있도록 일련의 도구와 기술을 개발했습니다.
이 Codelab에서는 Matter의 세 가지 주요 구성요소를 다룹니다. 이러한 각 시스템에 대해 Google은 휴대전화 및 허브에서 수집한 개발자를 위해 일련의 문제 해결 분석을 제공합니다.
개발자는 기기 개발 주기 전반에 걸쳐 발생하는 문제를 완화할 수 있어야 합니다. 프로젝트를 시작하고 나면 현장에서 발생하는 기기 문제 동향을 종합적으로 모니터링하고 소프트웨어 업데이트를 통해 이를 수정해야 합니다. 이 Codelab에서는 이 두 가지 용도로 사용할 수 있는 기법을 다룹니다.
기본 요건
- Matter 프로젝트와 기기 설정을 포함하여 Matter 시작하기 가이드를 완료하세요.
- 워크스테이션에 연결할 수 있는 Android 휴대전화가 있어야 합니다 (ADB 로그의 경우).
학습할 내용
- 스마트 홈용 분석 도구를 사용하여 Matter 문제를 대규모로 모니터링하는 방법
- 오류 로그에 액세스하고 정보를 수집하여 오류를 분류하는 방법
- Matter 문서 및 지원 리소스에 액세스하여 도움을 요청하는 방법
2. Google Home 애널리틱스 보기
Google Home 생태계와 성공적으로 통합하려면 성능을 모니터링하는 것이 매우 중요합니다. Google은 Google Cloud Platform의 스마트 홈 개발자에게 모니터링 도구 모음을 제공합니다. 이러한 도구를 사용하여 프로젝트 성능을 측정할 수 있습니다.
프로젝트 측정항목 액세스
- 데이터에 액세스하려면 먼저 Google Cloud 콘솔에 로그인하고 운영 > 운영 > 모니터링 > 대시보드.
프로젝트에서 사용할 수 있는 여러 가지 대시보드가 있습니다 (다른 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 서비스를 통해 홈 / 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. 축하합니다
축하합니다. Google에서 추천하는 도구와 기술을 사용하여 Matter 통합을 디버그하는 방법을 배웠습니다. Google Home과 Matter 통합을 구축하는 데 도움이 되기를 바랍니다.
다음 단계
다음 연습을 통해 추가 리소스를 살펴보세요.