Yerel Evin Hata Ayıklaması

1. Başlamadan önce

Akıllı ev entegrasyonları, Google Asistan'ın kullanıcıların evlerindeki bağlı cihazları kontrol etmesine olanak tanır. Akıllı ev İşlemi derlemek için akıllı ev amaçlarını işleyebilen bir Cloud webhook uç noktası sağlamanız gerekir. Örneğin, bir kullanıcı "Ok Google, ışıkları aç" dediğinde Asistan, cihazın durumunu güncellemek için bu komutu bulut karşılama aracınıza gönderir.

Yerel Ev SDK'sı, akıllı ev amaçlarını doğrudan bir Google Home cihazına yönlendiren yerel bir yol ekleyerek akıllı ev entegrasyonunuzu geliştirir. Bu yöntem, güvenilirliği artırır ve kullanıcıların komutlarının işlenmesinde gecikmeyi azaltır. Cihazları tanımlayan ve herhangi bir Google Home akıllı hoparlörde ya da Google Nest akıllı ekranda komut yürüten TypeScript veya JavaScript ile yerel bir istek karşılama uygulaması yazıp dağıtmanıza olanak tanır. Ardından uygulamanız, komutları yerine getirmek için mevcut standart protokolleri kullanarak yerel ağ üzerinden kullanıcıların mevcut akıllı cihazlarıyla doğrudan iletişim kurar.

72ffb320986092c.png

Akıllı Ev İşlemleri'nde hata ayıklama, Actions'ınızı üretim kalitesiyle geliştirmenin önemli bir adımıdır. Ancak bilgilendirici, kullanımı kolay sorun giderme ve test araçları olmadan hem zorlayıcı hem de zaman alan bir süreçtir. Akıllı ev işlemleri için hata ayıklamayı kolaylaştırmak amacıyla, Actions'daki sorunları tespit edip çözmenize yardımcı olacak Google Cloud Platform (GCP) Metrikler, Logging ve Akıllı ev için Test Paketi kullanılabilir.

Ön koşullar

Neler derleyeceksiniz?

Bu codelab'de, akıllı ev işlemleri için yerel bir sipariş karşılama sistemi oluşturup Asistan'a bağlayacak, ardından akıllı ev ve Google Cloud Platform (GCP) metrikleri ve günlük kaydı için Test paketi aracılığıyla Yerel Ev uygulamasının hatalarını ayıklayacaksınız.

Neler öğreneceksiniz?

  • Üretim sorunlarını tespit edip çözmek için GCP Metrikleri ve Logging'i kullanma.
  • İşlevsel sorunları ve API sorunlarını tanımlamak için Test Paketi'ni kullanma.
  • Yerel Ev uygulamanızı geliştirirken Chrome Geliştirici Araçları'nı kullanma.

Gerekenler

2. Çamaşır makinesi uygulamasını çalıştır

Kaynak kodunu alma

Bu codelab örneğini geliştirme makinenize indirmek için aşağıdaki bağlantıyı tıklayın:

...veya komut satırından GitHub deposunu klonlayabilirsiniz:

$ git clone https://github.com/google-home/smarthome-debug-local.git

Proje hakkında

Başlangıç uygulaması, Akıllı ev İşlemleri için yerel istek karşılamayı etkinleştir codelab'ine benzer alt dizinler ve bulut işlevleri içerir. Ancak app-start yerine burada app-faulty var. İşe yarayan bir yerel ev uygulamasıyla başlayacağız.

Firebase'e bağlanma

Akıllı ev işlemleri için yerel istek karşılamayı etkinleştirme codelab'inde oluşturduğunuz projenin aynısını kullanacağız ancak bu codelab'de indirilen dosyaları dağıtacağız.

app-faulty dizinine gidin, ardından Akıllı ev işlemleri için yerel istek karşılamayı etkinleştir codelab'inde oluşturulan Actions projenizle Firebase CLI'ı ayarlayın:

$ cd app-faulty
$ firebase use <project-id>

Firebase'e dağıtma

app-faulty/functions klasörüne gidin ve npm kullanarak gerekli tüm bağımlılıkları yükleyin:

$ cd functions
$ npm install

Not: Aşağıdaki mesajı görüyorsanız bu mesajı yoksayıp devam edebilirsiniz. Uyarı bazı eski bağımlılıklar nedeniyle gelmiştir. Daha ayrıntılı bilgiyi burada bulabilirsiniz.

found 5 high severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

app-faulty/local/ dizinine gidin ve TypeScript derleyicisini indirip uygulamayı derlemek için aşağıdaki komutları çalıştırın:

$ cd ../local
$ npm install
$ npm run build

index.ts (TypeScript) kaynağını derler ve aşağıdaki içerikleri app-faulty/public/local-home/ dizinine yerleştirir:

  • bundle.js: Yerel uygulamayı ve bağımlılıkları içeren derlenmiş JavaScript çıkışı.
  • index.html: Uygulamayı cihaz üzerinde test etmek amacıyla sunmak için kullanılan yerel barındırma sayfası.

Bağımlılıkları yüklediğinize ve projenizi yapılandırdığınıza göre, uygulamayı ilk kez çalıştırmaya hazırsınız.

$ firebase deploy

Aşağıdaki konsol çıkışını görürsünüz:

...

✔ Deploy complete!

Project Console: https://console.firebase.google.com/project/<project-id>/overview
Hosting URL: https://<projectcd -id>.web.app

Bu komut, birkaç Cloud Functions for Firebase ile birlikte bir web uygulamasını dağıtır.

Home Graph'i güncelleme

Web uygulamasını görüntülemek için tarayıcınızda (https://<project-id>.web.app) Barındırma URL'sini açın. Web kullanıcı arayüzünde, Senkronizasyon İste seçeneği aracılığıyla HomeGraph'i arızalı yıkama uygulamasındaki en son cihaz meta verileriyle güncellemek için Yenileae8d3b25777a5e30.png düğmesini tıklayın:

fa3c47f293cfe0b7.png

Google Home uygulamasını aç ve çamaşır makinesinin yeni adının "Hatalı Çamaşır Makinesi" olduğunu doğrula. Cihazı, Nest cihazı bulunan bir odaya atamayı unutmayın.

2a082ee11d47ad1a.png

3. Akıllı çamaşır makinesini çalıştır

Akıllı ev işlemleri için yerel istek karşılamayı etkinleştir codelab'ini çalıştırdıysanız sanal akıllı çamaşır makinesini daha önce başlatmış olmanız gerekir. Durdurulduysa sanal cihazı yeniden başlatmayı unutmayın.

Cihazı başlatma

virtual-device/ dizinine gidin ve yapılandırma parametrelerini bağımsız değişken olarak ileterek cihaz komut dosyasını çalıştırın:

$ cd ../../virtual-device
$ npm install
$ npm start -- \
  --deviceId=deviceid123 --projectId=<project-id> \
  --discoveryPortOut=3311 --discoveryPacket=HelloLocalHomeSDK

Cihaz komut dosyasının beklenen parametrelerle çalıştığını doğrulayın:

(...): UDP Server listening on 3311
(...): Device listening on port 3388
(...): Report State successful

4. Yerel Ev Uygulamasını test edin

Google Home cihazına sesli komutlarla cihazınıza aşağıdakiler gibi komutlar gönderin:

"Ok Google, çamaşır makinemi aç."

"Ok Google, çamaşır makinemi çalıştır."

"Ok Google, yerel reklamları zorla."

"Ok Google, çamaşır makinemi durdur."

"Yerel zorla" komutunun ardından çamaşır makinesini kontrol etmeye çalıştığınızda Google Asistan'ın "Maalesef Arızalı Çamaşır Makinesi şu anda kullanılamıyor" şeklinde yanıt verdiğini görürsünüz.

Bu durum, cihaza yerel bir yoldan erişilemediği anlamına gelir. Cihaza yerel bir yoldan erişilemediğinde bulut yolunu kullanmaya başlayacağımız için "Ok Google, zorla yerel" komutu yayınlanmadan önce çalıştı. Ancak "yerel zorla" komutunun ardından bulut yoluna geri dönme seçeneği devre dışı bırakılır.

Sorunun ne olduğunu öğrenmek için sahip olduğumuz araçlardan yararlanalım: Google Cloud Platform (GCP) Metrikler, Günlük Kaydı ve Chrome Geliştirici Araçları.

5. Local Home uygulamasında hata ayıklayın

Aşağıdaki bölümde, cihaza yerel yol üzerinden neden erişilemediğini öğrenmek için Google tarafından sağlanan araçları kullanacaksınız. Google Home cihazına bağlanmak, konsol günlüklerini görüntülemek ve Yerel Ev uygulamasının hatalarını ayıklamak için Google Chrome Geliştirici Araçları'nı kullanabilirsiniz. Ayrıca kullanıcılarınızın Yerel Ev uygulamanızda en sık karşılaştığı hatalardan haberdar olmak için Cloud Logging'e özel günlükler de gönderebilirsiniz.

Chrome Geliştirici Araçları'nı bağlama

Hata ayıklayıcıyı yerel sipariş karşılama uygulamanıza bağlamak için şu adımları uygulayın:

  1. Google Home cihazınızı, Actions console projesine erişim izni olan bir kullanıcıya bağladığınızdan emin olun.
  2. Google Home cihazınızı yeniden başlatın. Bu işlem, hem HTML'nizin URL'sini hem de Actions konsoluna yerleştirdiğiniz tarama yapılandırmasını almasını sağlar.
  3. Geliştirme makinenizde Chrome'u başlatın.
  4. Yeni bir Chrome sekmesi açın ve denetleyiciyi başlatmak için adres alanına chrome://inspect yazın.

Sayfada cihazların bir listesini göreceksiniz. Ayrıca Google Home cihazınızın adının altında uygulama URL'niz görünecektir.

567f97789a7d8846.png

İnceleyiciyi başlatma

Chrome Geliştirici Araçları'nı başlatmak için uygulama URL'nizin altında Denetle'yi tıklayın. Console (Konsol) sekmesini seçin ve TypeScript uygulamanız tarafından yazdırılan IDENTIFY intent'inin içeriğini görebildiğinizi doğrulayın.

774c460c59f9f84a.png

Bu çıkış, IDENTIFY işleyicinin başarıyla tetiklendiği ancak IdentifyResponse içinde döndürülen verificationId değerinin HomeGraph'inizdeki hiçbir cihazla eşleşmediği anlamına gelir. Nedenini öğrenmek için birkaç özel günlük ekleyelim.

Özel günlükler ekleyin

Yerel Ev SDK'sı tarafından yazdırılmış bir DEVICE_VERIFICATION_FAILED hatası olsa da bu hata, sorunun asıl nedenini bulmaya yardımcı olmaz. Tarama verilerini doğru şekilde okuyup işlediğimizden emin olmak için birkaç özel günlük ekleyelim. Sözü bir hata ile reddedersek hata mesajının aslında Cloud Logging'e de gönderileceğini unutmayın.

local/index.ts

identifyHandler(request: IntentFlow.IdentifyRequest):
    Promise<IntentFlow.IdentifyResponse> {
  console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));

  const scanData = request.inputs[0].payload.device.udpScanData;
  if (!scanData) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_request', 'Invalid scan data');
    return Promise.reject(err);
  }

  // In this codelab, the scan data contains only local device id.
  // Is there something wrong here?
  const localDeviceId = Buffer.from(scanData.data);
  console.log(`IDENTIFY handler: received local device id
      ${localDeviceId}`);

  // Add custom logs
  if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_device', 'Invalid device id from scan data ' +
        localDeviceId);
    return Promise.reject(err);
  }

  const response: IntentFlow.IdentifyResponse = {
    intent: Intents.IDENTIFY,
    requestId: request.requestId,
    payload: {
      device: {
        id: 'washer',
        verificationId: localDeviceId.toString(),
      }
    }
  };
  console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));

  return Promise.resolve(response);
}

Ayrıca, doğru sürümü kullanıp kullanmadığımızı tanımlayabilmemiz için yerel ana ekran uygulaması sürümünü de değiştirin.

local/index.ts

const localHomeSdk = new App('1.0.1');

Özel günlükleri ekledikten sonra uygulamayı tekrar derlemeniz ve Firebase'e yeniden dağıtmanız gerekir.

$ cd ../app-faulty/local
$ npm run build
$ firebase deploy --only hosting

Şimdi, güncellenen yerel ana ekran uygulamasını yükleyebilmesi için Google Home cihazınızı yeniden başlatın. Chrome Geliştirici Araçları'ndaki Console günlüklerine bakarak Google Home cihazının beklenen sürümü kullanıp kullanmadığını görebilirsiniz.

ecc56508ebcf9ab.png

Cloud Logging'e erişme

Hatalarınızı bulmak için Cloud Logging'i nasıl kullanacağınıza göz atalım. Projenizde Cloud Logging'e erişmek için:

  1. Cloud Platform konsolunda Projeler sayfasına gidin.
  2. Akıllı ev projenizi seçin.
  3. İşlemler bölümünde, Günlük Kaydı > Günlük Gezgini'ni seçin.

Günlük kaydı verilerine erişim, Actions projenizin kullanıcıları için Identity and Access Management (IAM) üzerinden yönetilir. Günlük kaydı verilerinin rol ve izinleri hakkında daha fazla bilgi için Cloud Logging erişim denetimi başlıklı makaleyi inceleyin.

Gelişmiş filtreleri kullanma

Yerel cihaz tanımlanamadığı için yerel yol çalışmadığından IDENTIFY amacında hatalar oluştuğunu biliyoruz. Ancak, sorunun tam olarak ne olduğunu bilmek istediğimiz için önce IDENTIFY işleyicide oluşan hataları filtreleyelim.

Sorgu önizlemesi kutusunu genişletin. kutu, Sorgu oluşturucu kutusuna dönüşür. Sorgu oluşturucu kutusuna jsonPayload.intent="IDENTIFY" yazın ve Sorgu çalıştır düğmesini tıklayın.

4c0b9d2828ee2447.png

Bunun sonucunda IDENTIFY işleyiciye gönderilen tüm hata günlüklerini alırsınız. Ardından, son hatayı genişletin. Sözü reddederken ayarladığınız errorCode ve debugString değerlerini IDENTIFY işleyicisinde bulabilirsiniz.

71f2f156c6887496.png

debugString üzerinden yerel cihaz kimliğinin beklenen biçimde olmadığı anlaşılıyor. Yerel Ev uygulaması, yerel cihaz kimliğini deviceid ile başlayıp 3 basamaklı bir dize şeklinde almayı bekler. Ancak buradaki yerel cihaz kimliği onaltılık bir dizedir.

Hatayı düzeltme

Tarama verilerinden yerel cihaz kimliğini ayrıştırdığımız kaynak koda döndüğümüzde, dizeyi bayta dönüştürürken kodlamayı sağlamadığımızı fark ederiz. Tarama verileri onaltılık dize olarak alındığından Buffer.from() çağrılırken karakter kodlaması olarak hex iletin.

local/index.ts

identifyHandler(request: IntentFlow.IdentifyRequest):
    Promise<IntentFlow.IdentifyResponse> {
  console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));

  const scanData = request.inputs[0].payload.device.udpScanData;
  if (!scanData) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_request', 'Invalid scan data');
    return Promise.reject(err);
  }

  // In this codelab, the scan data contains only local device id.
  const localDeviceId = Buffer.from(scanData.data, 'hex');
  console.log(`IDENTIFY handler: received local device id
      ${localDeviceId}`);

  if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
    const err = new IntentFlow.HandlerError(request.requestId,
      'invalid_device', 'Invalid device id from scan data ' +
      localDeviceId);
    return Promise.reject(err);
  }

  const response: IntentFlow.IdentifyResponse = {
    intent: Intents.IDENTIFY,
    requestId: request.requestId,
    payload: {
      device: {
        id: 'washer',
        verificationId: localDeviceId.toString(),
      }
    }
  };
  console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));

  return Promise.resolve(response);
}

Ayrıca, doğru sürümü kullanıp kullanmadığımızı tanımlayabilmemiz için yerel ana ekran uygulaması sürümünü de değiştirin.

local/index.ts

const localHomeSdk = new App('1.0.2');

Hatayı düzelttikten sonra uygulamayı derleyin ve Firebase'e yeniden dağıtın. app-faulty/local içinde şu komutu çalıştırın:

$ npm run build
$ firebase deploy --only hosting

Düzeltmenizi test etme

Dağıtımdan sonra, güncellenmiş yerel ana ekran uygulamasını yükleyebilmesi için Google Home cihazınızı yeniden başlatın. Yerel ana ekran uygulaması sürümünün 1.0.2 olduğundan ve bu sefer Chrome Geliştirici Araçları Konsolu'nda hata görmediğinizden emin olun.

c8456f7b5f77f894.png

Artık cihazınıza komut göndermeyi tekrar deneyebilirsiniz.

"Ok Google, yerel reklamları zorla."

"Ok Google, çamaşır makinemi durdur."

"Ok Google, çamaşır makinemi aç."

...

"Ok Google, varsayılanı zorla."

6. Akıllı Ev için Test Paketini Çalıştır

Google Home uygulamasındaki dokunma kontrollerini kullanarak veya sesli komutlarla cihazınızı doğruladıktan sonra, kullanım alanlarını İşleminizle ilişkili cihaz türlerine ve özelliklere göre doğrulamak için otomatik Akıllı ev için Test Paketi'nden yararlanabilirsiniz. Test Paketi, İşleminizdeki sorunları tespit etmek için bir dizi test yürütür ve etkinlik günlüklerini derinlemesine incelemeden önce hata ayıklama işleminizi hızlandırmak amacıyla başarısız test durumlarıyla ilgili bilgilendirici mesajlar gösterir.

Akıllı ev için Test Paketi'ni çalıştırın

Akıllı ev İşleminizi Test Suite'e göre test etmek için şu talimatları uygulayın:

  1. Web tarayıcınızda Akıllı ev için Test Paketi'ni açın.
  2. Sağ üst köşedeki düğmeyi kullanarak Google'da oturum açın. Bu, Test Paketi'nin komutları doğrudan Google Asistan'a göndermesine olanak tanır.
  3. Proje Kimliği alanına akıllı ev işleminizin proje kimliğini girin. Ardından, ilerlemek için SONRAKİ'yi tıklayın.
  4. Test Ayarları adımındaki Cihazlar ve Traisler bölümünde Arızalı Çamaşır Makinesi'ni görmeniz gerekir.
  5. Örnek yıkama uygulamasında çamaşır makinesi eklemek / çıkarmak / yeniden adlandırmak için kullanıcı arayüzü olmadığından Test İsteği Senkronizasyonu seçeneğini devre dışı bırakın. Üretim sisteminde, kullanıcı cihaz eklediğinde / kaldırdığında / yeniden adlandırdığında Senkronizasyon İste'yi tetiklemeniz gerekir.
  6. Hem yerel hem de bulut yollarını test edeceğimiz için Local Home SDK (Yerel Ev SDK'sı) seçeneğini etkin bırakın.
  7. Testi çalıştırmaya başlamak için SONRAKİ'yi tıklayın.

67433d9190fa770e.png

Testler tamamlandığında yerel yoldaki Duraklatma/Devam Ettirme testlerinin başarısız olduğunu ve bulut yolundaki Duraklatma/Devam Ettirme testleri geçemediğini görürsünüz.

d1ebd5cfae2a2a47.png

Hata mesajını analiz et

Başarısız test durumlarındaki hata mesajlarını daha yakından inceleyin. Size söz konusu testin beklenen ve gerçek durumunun ne olduğunu söyler. Buradaki örnekte, "Çamaşır Makinesini Duraklat" işlemi için beklenen durum isPaused: true iken gerçek durumda isPaused: false değerini elde ettik. Benzer şekilde, "Çamaşır Makinesini Duraklat" için beklenen durum isPaused: true iken gerçek durumda isPaused: false.

6bfd3acef9c16b84.png

Hata mesajlarından, yerel yolda isPaused durumunu ters çevirdiğimiz anlaşılıyor.

Hatayı tespit etme ve düzeltme

Local Home uygulamasının, yürütme komutunu cihaza gönderdiği kaynak kodunu bulalım. getDataCommand(), cihaza gönderilen yürütme komutunda payload'yi ayarlamak için executeHandler() tarafından çağrılan işlevdir.

local/index.ts

getDataForCommand(command: string, params: IWasherParams): unknown {
    switch (command) {
        case 'action.devices.commands.OnOff':
            return {
                on: params.on ? true : false
            };
        case 'action.devices.commands.StartStop':
            return {
                isRunning: params.start ? true : false
            };
        case 'action.devices.commands.PauseUnpause':
            return {
                // Is there something wrong here?
                isPaused: params.pause ? false : true
            };
        default:
            console.error('Unknown command', command);
            return {};
    }
}

Gerçekten de isPause özelliğini ters duruma ayarlıyoruz. params.pause true olduğunda true, aksi takdirde false olarak ayarlanmalıdır. Gelin bu sorunu çözelim.

local/index.ts

getDataForCommand(command: string, params: IWasherParams): unknown {
    switch (command) {
        case 'action.devices.commands.OnOff':
            return {
                on: params.on ? true : false
            };
        case 'action.devices.commands.StartStop':
            return {
                isRunning: params.start ? true : false
            };
        case 'action.devices.commands.PauseUnpause':
            return {
                isPaused: params.pause ? true : false
            };
        default:
            console.error('Unknown command', command);
            return {};
    }
}

Doğru sürümü kullanıp kullanmadığımızı belirleyebilmemiz için yerel ana ekran uygulaması sürümünü değiştirin.

local/index.ts

const localHomeSdk = new App('1.0.3');

Uygulamayı tekrar derlemeyi ve Firebase'e yeniden dağıtmayı unutmayın. app-faulty/local içinde şu komutu çalıştırın:

$ npm run build
$ firebase deploy --only hosting

Şimdi, güncellenmiş yerel ana ekran uygulamasını yükleyebilmesi için Google Home cihazınızı yeniden başlatın. Yerel ana ekran uygulaması sürümünün 1.0.3 olduğundan emin olun.

Düzeltmenizi test etme

Şimdi, akıllı ev için test paketini aynı yapılandırmalarla yeniden çalıştırdığınızda tüm test durumlarının geçtiğini göreceksiniz.

b7fc8c5d3c727d8d.png

7. Tebrikler

764dbc83b95782a.png

Tebrikler! Akıllı ev ve Cloud Logging için Test Paketi aracılığıyla Yerel Ev uygulamasında sorun gidermeyi başarıyla öğrendiniz.

Daha Fazla Bilgi

Şunları da deneyebilirsiniz:

Ayrıca, İşleminizi kullanıcılara yayınlamak için sertifikasyon süreci de dahil olmak üzere bir İşlemi test etme ve incelemeye gönderme hakkında daha fazla bilgi edinebilirsiniz.