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에 로그인한 후 작업 > 모니터링 > 대시보드로 이동하여 Google Home 대시보드를 확인해야 합니다.
프로젝트에 다른 대시보드( )를 포함하여 다양한 대시보드를 사용할 수 있습니다. 스마트 홈에 제공되는 대시보드에는 Google Home 애널리틱스 프리픽스가 붙습니다.
현재 전체 프로젝트를 다루는 일반 대시보드와 특정 통합 (클라우드, 로컬, Matter) 또는 기기 유형 (카메라)을 위한 대시보드가 있습니다. 이 대시보드는 요청을 처리하는 정상적으로 작동하는 프로젝트와 함께 해당 유형을 통합한 경우에만 데이터를 포함합니다.
이러한 대시보드 중 하나를 열면 다음과 같은 일련의 차트가 표시됩니다.
Google Home 대시보드에는 프로젝트와 관련된 이벤트의 세부정보를 보여주는 다양한 차트가 포함되어 있습니다. 각 통합 대시보드에서는 프로젝트에서 처리한 총 요청 수를 보여주는 차트, 해당 통합 유형의 성공률을 보여주는 차트, 관련 기기 유형 및 특성을 보여주는 여러 차트가 표시됩니다. 또한 Matter에는 커미셔닝 성공과 기기의 업데이트 출시를 추적하는 차트가 있습니다.
Google Home 애널리틱스 대시보드에 표시되는 차트가 표시되는 기본 보기는 스마트 홈 측정항목 데이터를 사용하여 프로젝트를 위해 만든 보기일 뿐입니다. 측정항목 탐색기를 사용하여 동일한 기본 측정항목에서 자체 차트를 만들고 커스텀 대시보드에 저장할 수도 있습니다.
오류 로그 액세스
로그 탐색기는 프로젝트에서 생성된 이벤트 로그로 사용할 수 있는 도구의 모음입니다. Google Cloud Console에서 작업 > 로깅 > 로그 탐색기로 이동하여 액세스할 수 있습니다.
로그 탐색기를 열면 다음과 같은 뷰가 표시됩니다.
탐색기 창에는 로그를 보고 필터링하고 쿼리하고 분석하는 다양한 도구가 포함되어 있습니다. 기본적으로 이 뷰에는 스마트 홈 외부에서 생성된 로그를 포함하여 프로젝트에 사용할 수 있는 모든 시스템에서 생성된 로그가 표시됩니다. 그렇기 때문에 디버그하려는 이벤트를 필터링하여 이러한 로그를 사용하는 것이 중요합니다. 이에 대해서는 디버깅 섹션에서 자세히 설명하겠습니다.
3. 수수료 문제 디버그
살펴볼 첫 번째 측정항목 유형은 Matter 수수료 이벤트입니다. 수수료는 사용자가 Matter 기기를 처음 설정하는 데 필요한 단계를 의미합니다.
기기 의뢰 중에는 Matter 기기, Google Home 앱, Matter 패브릭 간에 상호작용이 발생합니다. 다음 이미지는 이러한 이벤트 중 일부를 보여줍니다.
각 단계에 대한 자세한 내용은 Matter Primer의 커미션 페이지에서 확인할 수 있습니다. 이 섹션에서는 수수료 문제를 디버깅하는 도구와 기법을 다룹니다.
Google Home 애널리틱스 사용
이벤트를 추적하고 오류가 발생할 수 있는 단계를 이해하여 수수료 문제를 조사할 수 있도록 일련의 측정항목을 만들었습니다. 이전 섹션에서 다룬 Matter 통합 대시보드에서 찾을 수 있습니다.
이 대시보드의 차트는 기기 수수료에 대한 데이터를 제공합니다.
기기 수 차트에는 특정 날짜에 사용자가 위탁한 시도 횟수가 표시됩니다. 성공률은 Google 측에서 발생한 이러한 이벤트의 성공률을 나타냅니다. 각 수수료 시도는 연결된 상태로 이벤트 집합을 생성합니다. 이러한 상태에서 오류가 발생하면 오류 분석 차트에도 반영됩니다.
위탁 사유:
- 수수료 시작
- 온보딩_결제_생성됨
- LOCAL_DISCOVERY_SUCCESSFUL
- 성공_연결_완료
- NOC_ADDED_SUCCESSFULLY회
- 수수료_완료
이러한 이벤트의 자세한 버전을 보려면 작업 > 로깅 > 로그 탐색기로 이동하세요. 수수료 오류를 필터링하려면 쿼리 필드에서 '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 스튜디오 또는 sdkmanager 명령줄 도구를 통해 설치할 수 있는 Android SDK 플랫폼 도구의 일부로 제공됩니다.
시스템에 플랫폼 도구를 설치했으면 터미널에서 다음 명령어로 버전 번호를 확인하여 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 서비스를 통해 집 / 법적 사안 제어 모듈이 있는지 확인하려면 다음 단계를 따르세요.
$ 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에 의해 중재되므로 기기 제어 측에서 오류가 더 적게 발생할 것으로 예상됩니다. 이러한 유형의 문제를 디버그할 수 있는 측정항목과 로그도 제공됩니다.
측정항목 사용하기
Matter 통합 대시보드에는 기기 제어와 관련된 몇 가지 측정항목이 표시됩니다. 현장에서 기기의 성능을 평가하는 데 중요한 차트 3개가 있습니다.
통제 문제를 겪는 동안 일반적으로 성공률은 하락하고 오류 분석 차트는 상승합니다. 오류 분석 차트에는 기기 제어 시도가 실패한 이유와 관련하여 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 기기의 무선 업데이트 출시 버전을 추적하기 위해 현장의 기기에 대한 하드웨어 및 소프트웨어 버전을 보여주는 측정항목 모음을 제공합니다.
Console에서 업데이트를 실행한 후 다음 측정항목을 주의 깊게 살펴보세요.
출시 후 며칠 내에 현장에서 점점 더 많은 기기가 OTA 소프트웨어 릴리스와 관련된 새로운 소프트웨어 버전을 얻게 될 것입니다.
6. 지원 요청
Google은 Matter 문제를 디버깅하는 도구와 문서를 제공하지만 Matter 생태계가 새로운 것이기 때문에 이러한 리소스에서는 다루지 않는 문제가 있습니다. 이러한 경우 언제든지 YouTube 또는 커뮤니티에 연락하여 지원을 요청할 수 있습니다.
개발자 채널 방문하기
Google 내부에서 활발하게 모니터링 중인 개발자 채널은 3가지입니다.
이러한 채널은 모두 동일한 팀에서 주기적으로 모니터링되지만 어떤 채널을 사용해야 하는지에 대해서는 몇 가지 주요 차이점이 있습니다.
- Stack Overflow: 구현 질문이 있거나 안내가 필요한 경우 스마트 홈 개발자 커뮤니티에 Google에 문의할 수 있습니다. 이 채널은 문제를 해결하거나 특정 기능을 구현하는 방법에 가장 적합합니다.
- Issue Tracker: Google에서 실행하는 공식 Issue Tracker 시스템으로, 외부 잠재고객이 생태계의 오류를 보고할 수 있습니다. 필요한 경우 파일을 첨부하고 민감한 정보를 공유할 수 있는 웹 도구를 제공합니다. Issue Tracker를 사용하는 것이 생태계 문제 신고 또는 기능 요청 공유에 가장 적합합니다.
- 개발자 포럼: Google 공식 지원 및 커뮤니티 전문가에게 조언을 구하려면 Nest 개발자 포럼을 통해 문의하세요. 이 포럼은 개발에 관한 공식 안내를 확인하는 데 가장 적합합니다.
개발자 뉴스레터 구독하기
질문을 받기 위해 개발자 채널을 방문하는 것 외에도 분기별 뉴스레터를 통해 새로운 기능을 소개하고 Google 스마트 홈 생태계 현황에 관한 뉴스를 제공합니다.
가입 양식을 사용하여 개발자 뉴스레터를 받을 수 있습니다.
7. 축하합니다
축하합니다. Google에서 권장하는 도구와 기법을 사용하여 Matter 통합을 디버깅하는 방법을 배웠습니다. Google Home과의 Matter 통합을 빌드해 보시기 바랍니다.
다음 단계
다음 실습을 통해 추가 리소스를 살펴보세요.