Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

문제 해결

샘플 앱

Home API를 사용할 때 문제가 발생하면 추가 디버깅을 위해 로그를 수집할 수 있습니다. 휴대기기에서 로그를 수집하려면 Android 디버그 브리지 (adb)가 필요합니다. Google의 지원이 필요한 경우 Android 기기와 허브 모두에서 로그를 수집하고 관련 정보 및 관련 로그와 함께 Issue Tracker에서 티켓을 엽니다.

Android 로그 수집

adb와 관련된 모든 단계에서 휴대기기가 로컬 머신에 연결되어 있어야 합니다.

adb 설치

아직 설정하지 않았다면 로컬 머신에 Android 디버그 브리지를 설정합니다.

컴퓨터에 'adb'를 설치합니다.
Android 휴대전화에서 개발자 옵션 및 USB 디버깅을 사용 설정합니다.

휴대기기 ID 가져오기

휴대기기의 ID를 가져옵니다.

adb devices

List of devices attached
device-id    device

이 값을 phoneid라는 변수에 저장합니다.
```
phoneid=device-id
```

버전 정보

로그를 수집하기로 결정할 때마다 설정과 관련된 모든 버전 정보를 수집하는 것이 좋습니다. Google과 문제를 공유해야 하는 경우에 필요합니다.

다양한 기기 정보를 변수에 저장합니다.

containerinfo=$(adb -s $phoneid shell dumpsys package com.google.android.gms | grep -m 1 "versionName" || true); ghainfo=$(adb -s $phoneid shell dumpsys package com.google.android.apps.chromecast.app | grep -m 1 "versionName" || true); androidversion=$(adb -s $phoneid shell getprop ro.build.version.release || true); androidapiversion=$(adb -s $phoneid shell getprop ro.build.version.sdk || true); chimeradump=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider || true); homemoduleinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.home" || true); optionalhomemoduleinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.optional_home" || true); threadinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.threadnetwork" || true); enabledfeatures=$(echo "$chimeradump" | grep "Enabled features" | grep -i "home" | sort -u || true)

모든 변수를 _versions.txt 파일에 저장합니다.

펼쳐서 파일에 변수를 저장하는 명령어 표시

전체 블록을 한 번에 복사하여 터미널에 붙여넣을 수 있습니다.

versionfile="_versions.txt"
echo "Saving version info to $versionfile"
echo "Container version: $containerinfo" > $versionfile
echo "Home Module version: $homemoduleinfo" >> $versionfile
echo "Optional Home Module version: $optionalhomemoduleinfo" >> $versionfile
echo "Thread Module version: $threadinfo" >> $versionfile
echo "GHA version: $ghainfo" >> $versionfile
echo "Android version: $androidversion" >> $versionfile
echo "Android API version: $androidapiversion" >> $versionfile
echo "Found enabled features: $enabledfeatures" >> $versionfile

_versions.txt의 콘텐츠를 확인합니다.

cat _versions.txt

펼쳐서 샘플 파일 출력 표시

Container version:     versionName=26.26.34 (190400-945364269)
Home Module version:             com.google.android.gms.home [v262634001]
Optional Home Module version:         com.google.android.gms.optional_home [262634025] ...
Thread Module version:             com.google.android.gms.threadnetwork [v262634001]
GHA version:     versionName=4.22.28.0
Android version: 14
Android API version: 34
Found enabled features:             Enabled features: appsearch_impl, brella_dynamite, dck_management...

이제 문제 해결을 위해 필요에 따라 이 파일을 Google에 제공할 수 있습니다.

상세 디버깅 플래그 사용 설정

Android 기기 로그를 수집하거나 버그 신고를 실행하기 전에 로거 버퍼 크기를 구성하고 Google Home 및 GMS 구성요소에 대한 상세 디버깅 태그를 사용 설정합니다.

# Clear existing device logs and expand logger buffer size
adb -s $phoneid logcat -b all -c
adb -s $phoneid logcat -G 8M

# Enable displaying seconds on the screen
adb -s $phoneid shell settings put secure clock_seconds 1

# Enable GMS Service ID verbose flags
adb -s $phoneid shell setprop log.tag.gms_svc_id:168 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:304 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:305 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:319 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:336 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:360 VERBOSE

# Enable GHP and Matter log tags
adb -s $phoneid shell setprop log.tag.CameraCommissioningPlugin VERBOSE
adb -s $phoneid shell setprop log.tag.HomeSdk VERBOSE
adb -s $phoneid shell setprop log.tag.HomeClient VERBOSE
adb -s $phoneid shell setprop log.tag.InteractionApiChimeraService VERBOSE
adb -s $phoneid shell setprop log.tag.MatterCommissioner VERBOSE
adb -s $phoneid shell setprop log.tag.SampleApp VERBOSE

스크립트로 Android 로그 수집

디버깅 세션 중에 실시간 Android 기기 로그를 캡처하려면 다음 단계를 따르세요.

상세 디버깅 플래그 사용 설정의 안내에 따라 기존 로그를 지우고 버퍼 사이즈를 확장하고 상세 로깅 태그를 설정합니다.
휴대기기에서 실행 중인 모든 애플리케이션을 닫습니다.
테스트를 시작하기 전에 기존 로그 버퍼 노이즈를 삭제합니다.
```
adb -s $phoneid logcat -c
```
터미널 창에서 로그 수집 프로세스를 시작합니다.
```
adb -s $phoneid logcat | tee android-logs_$(date +%Y%m%d%H%M%S).txt
```
이 터미널 창을 열어 둡니다. 이렇게 하면 프로세스가 실행되는 동안 기기에서 로그가 캡처됩니다.
앱을 실행하고 문제를 재현하는 데 필요한 모든 사용자 인터페이스 작업을 실행합니다.
완료되면 터미널에서 Ctrl+C (Mac의 경우 Cmd+C)를 눌러 logcat 프로세스를 중지합니다.
이 세션의 로그는 android-logs_YYYYMMDDmmss.txt에 저장됩니다. android-logs_YYYYMMDDmmss.txt 및 _versions.txt를 모두 버그 신고에 첨부합니다.

adb bugreport로 Android 로그 수집

시스템 수준 문제, 크래시 덤프 또는 하위 수준 네트워크 및 블루투스 디버깅을 포함하는 자세한 진단 정보를 공유해야 하는 경우 전체 Android 버그 신고를 캡처합니다.

Matter BLE 커미셔닝: BLE와 관련된 Matter 커미셔닝 문제를 신고할 때는 문제를 재현하기 전에 개발자 옵션 (설정 > 개발자 옵션 > 블루투스 HCI 스누프 로그 사용 설정)에서 블루투스 HCI 스누프 로그를 사용 설정하세요.
테스트 전 설정: 테스트를 실행하기 전에 상세 디버깅 플래그 사용 설정의 단계에 따라 기기에서 상세 디버깅 속성을 사용 설정합니다.
버그 신고 캡처: 테스트를 실행하고 문제를 재현한 후 다음 명령어를 실행하여 전체 버그 신고 보관 파일을 생성합니다.
```
adb -s $phoneid bugreport ./android-bugreport_$(date +%Y%m%d%H%M%S).zip
```
고급 디버깅 정보: 생성된 android-bugreport_YYYYMMDDmmss.zip 파일에는 전체 시스템 덤프, 메모리 통계, 배터리 진단, 하위 수준 하위 시스템 trace를 비롯한 포괄적인 시스템 수준 진단 데이터가 포함되어 있어 디버깅을 위한 고급 정보를 제공합니다.

Cast 허브 기기 로그

이 방법을 사용하여 Google Nest Hub의 기기 로그를 볼 수 있습니다. 이 방법은 다음 모델에서 지원됩니다.

Google Home
Google Nest Audio
Google Nest Hub
Google Nest Mini

로컬 로그 검색을 위해 Cast 허브를 사용 설정하려면 다음 단계를 따르세요.

Android 디버그 브리지를 설정합니다.
허브의 IP 주소를 가져옵니다.
- 허브에 화면이 있는 경우:
  1. 화면 상단에서 아래로 스와이프합니다.
  2. 설정 아이콘 을 탭합니다.
  3. 기기 IP 주소 찾기: Nest Hub (2nd gen)에서 기기 정보 > 기술 정보 > IP 주소로 이동합니다.
- 휴대전화의 GHA에서 다음 단계를 따르세요.
  1. 기기를 탭하여 기기 세부정보 페이지를 표시합니다.
  2. 설정 아이콘 을 탭하여 설정 페이지를 표시합니다.
  3. 기기 IP 주소 찾기: 기기 정보 > 기술 정보 > IP 주소로 이동합니다.
기기와 동일한 Wi-Fi 네트워크에 있는 컴퓨터에서 다음을 실행합니다.
```
  adb connect ip-address
  adb logcat
```
다른 사용자에게 로그를 제공하려면 실패한 작업을 수행하고 출력을 텍스트 파일로 파이프합니다.
```
  adb logcat -d > platform-logs.txt
```

자동화

에지 감지

Google Home 생태계의 자동화에는 에지 감지 기능이 있습니다. 이는 기기의 이전 상태를 단순히 반복하는 상태 업데이트와 달리 실제 상태 변경이 있을 때만 시작 조건이 활성화되는지 확인하는 로직입니다.

예를 들어 조명을 켜는 것이 시작 조건인 경우 에지 감지는 조명 기기가 켜짐에서 켜짐 (변경 없음)이 아닌 꺼짐에서 켜짐으로 전환되는 경우에만 시작 조건이 활성화되는지 확인합니다.

자동화가 예상대로 작동하지 않음

에지 감지를 고려한 후에도 자동화가 예상대로 작동하지 않는 경우 다음을 따르세요.

각 기기가 자동화와 별개로 제대로 작동하는지 확인합니다.
자동화의 자동화 그래프를 살펴보고 자동화 DSL과 비교하여 잘못된 가정이 있는지 확인합니다.
자동화 실행 중에 Google Home 앱에서 기기 상태를 관찰합니다.
자동화에서 참조하는 모든 기기가 예상되는 구조에 있는지 확인합니다. 자동화가 종속된 기기를 삭제하면 의도하지 않은 결과가 발생할 수 있습니다. 기기 삭제가 자동화에 미치는 영향을 참고하세요.

자동화가 실행되지 않아야 할 때 실행됨

자동화가 실행되지 않아야 할 때 실행되는 경우 시작 조건 기준을 검토하세요. 상태 변경이 한 번만 캡처되고 자동화를 한 번만 트리거하도록 하려면 추가 로직을 추가해야 할 수 있습니다.

자동화가 컴파일되지 않음

앱에 다양한 노드 유형에 해당하는 각 클래스와 참조하는 특성을 비롯하여 필요한 모든 가져오기가 포함되어 있는지 확인합니다.

자동화 생성 유효성 검사 실패

자동화 생성이 검증을 통과하지 못하면 경고 또는 오류 메시지가 문제에 관한 정보를 제공합니다. 자세한 내용은 ValidationIssueType 참조를 확인하세요.

목록 함수에서 예외 발생

Automation API List 함수를 호출할 때 API 기능이 누락되어 읽기 핸들러에서 예외가 발생할 수 있습니다. 이 문제를 완화하려면 영향을 받는 자동화를 삭제하세요.

방법은 다음과 같습니다.

adb이 설치되어 있는지 확인합니다. adb 설치를 참고하세요.

다음을 호출하여 Android 로그에서 자동화 ID를 가져옵니다.

adb logcat -s GhpNative

예시 로그:

adb logcat -s GhpNative level:debug | grep -A 10 -B 10 AutomationManagerTrait\.ListResponse

INTERACTION RESPONSE -> SendCommandsResponse:
1 {
1: "automation@global"
3 {
  1: "home.internal.traits.automation.AutomationManagerTrait.ListResponse"
  2:
  5 {
    1: "type.googleapis.com/home.internal.traits.automation.AutomationManagerTrait.ListResponse"
    1 {
        1: "1111-2222-3333-44444-55555" // Automation ID to delete
        2: "structure@2222-3333-4444-5555-6666"
...

여러 자동화 ID를 삭제해야 하는 경우 터미널 페이저를 사용하여 출력을 제어할 수 있습니다.

adb logcat -s GhpNative level:debug | less

자동화 ID를 사용하여 자동화를 삭제합니다.

structure.deleteAutomation(new object : HasId(id = "1111-2222-3333-44444-55555"))

특성이 등록 취소되면 Discovery API에서 경고를 로깅함

Discovery API가 Trait not found에 대한 경고를 로깅하는 경우 이는 API가 탐색 후보에 특성을 사용하려고 하지만 초기화 중에 특성이 등록되지 않았기 때문에 성공하지 못함을 의미합니다. 예를 들면 다음과 같습니다.

09-03 17:45:20.578 10646 10646 W AutomationSdk: trait_id: "home.matter.6006.clusters.fc43" and Exception occurred com.google.home.HomeException: 18: Trait not found: home.matter.6006.clusters.fc43
09-03 17:45:20.578 10646 10646 W AutomationSdk: While converting candidate: # com.google.home.platform.traits.AutomationCandidateNode@76f0b582

특성 식별자는 home.matter.6006.clusters.fc43이며, 이는 RelativeHumidityControl에 해당합니다. ID에서 특성 이름을 확인하려면 특성 색인을 참고하세요.

이 예시에서는 앱 초기화 중에 RelativeHumidityControl를 등록해야 합니다. 특성 등록을 참고하여 레지스트리에 특성을 추가합니다.

OAuth

기존 OAuth 클라이언트가 있는 경우

게시된 앱에 인증된 OAuth 클라이언트가 이미 있는 경우 기존 OAuth 클라이언트를 사용하여 Home API를 테스트할 수 있습니다.

Home API를 테스트하고 사용하기 위해 Google Home Developer Console 등록은 필요하지 않습니다. 하지만 다른 통합에서 확인된 OAuth 클라이언트가 있더라도 앱을 게시하려면 승인된 Developer Console 등록이 필요합니다.

다음 고려사항이 적용됩니다.

기존 OAuth 클라이언트를 사용하는 경우 사용자 제한은 100명입니다. 테스트 사용자 추가에 대한 자세한 내용은OAuth 동의 화면을 설정합니다. OAuth 인증과 별개로, Home API에서 부과하는 제한에 따라 애플리케이션에 권한을 부여할 수 있는 사용자는 100명으로 제한됩니다. 이 제한은 Developer Console 등록이 완료되면 해제됩니다.
Developer Console 등록 은 Home API로 앱을 업데이트하기 위해 OAuth를 통해 기기 유형 권한 부여를 제한할 준비가 되면 승인을 위해 전송해야 합니다.

중요: Google Home Developer Console은 아직 등록할 수 없습니다.

아직 OAuth 인증이 대기 중인 Google Cloud 앱의 경우 인증이 완료될 때까지 사용자가 OAuth 흐름을 완료할 수 없습니다. 권한을 부여하려고 하면 다음 오류가 발생합니다.

Access blocked: <Project Name> has not completed the Google verification process.