Cómo depurar la casa inteligente

1. Antes de comenzar

Como desarrollador de la Internet de las cosas (IoT), puedes compilar Acciones para casa inteligente que les brinden a los usuarios la capacidad de controlar sus dispositivos mediante controles de tacto en la app de Google Home y comandos por voz con el Asistente de Google.

a4657871181b5ad2.gif

Aprender a usar las herramientas de depuración de Acciones de casa inteligente es un paso importante para desarrollar una integración de calidad de producción con Asistente de Google. Para facilitar la supervisión y depuración, las métricas de Google Cloud Platform (GCP), Logging y el paquete de pruebas para casa inteligente están disponibles para ayudarte a identificar y resolver problemas en tus Acciones.

Requisitos previos

Qué compilarás

En este codelab, implementarás una Acción de casa inteligente con 2 defectos y la conectarás al Asistente. Luego, depurarás los defectos de la acción con el paquete de pruebas para las métricas y Logging de Google Cloud Platform y Google Cloud Platform (GCP).

Qué aprenderás

  • Cómo usar las métricas de GCP y Logging para identificar y resolver problemas de producción
  • Cómo usar el paquete de pruebas para una casa inteligente a fin de identificar problemas funcionales y de API

Requisitos

2. Ejecuta la app defectuosa

Obtén el código fuente

Haz clic en el siguiente vínculo para descargar la muestra de este codelab en tu máquina de desarrollo:

O bien, puedes clonar el repositorio de GitHub desde la línea de comandos.

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

Acerca del proyecto

La app de la lavadora incluye los siguientes subdirectorios:

Cómo conectarse a Firebase

Abre la terminal en tu máquina de desarrollo. Navega al directorio washer-faulty y configura Firebase CLI con tu proyecto de acciones compilado en el codelab Cómo conectar dispositivos de casa inteligente al Asistente de Google:

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

Realiza la implementación en Firebase

Navega a la carpeta functions y, luego, instala todas las dependencias necesarias mediante npm..

$ cd functions
$ npm install

Nota: Si ves el siguiente mensaje, puedes ignorarlo y continuar. La advertencia se debe a algunas dependencias antiguas. Puedes obtener más detalles aquí.

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

Ahora que instalaste las dependencias y configuraste tu proyecto, tienes todo listo para implementar la app de la lavadora defectuosa.

$ firebase deploy

Este es el resultado que deberías ver en la consola:

...

✔ Deploy complete!

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

Actualiza HomeGraph

Abre la URL de Hosting en tu navegador (https://<project-id>.firebaseapp.com) para ver la aplicación web. En la IU web, haz clic en el botón Actualizar ae8d3b25777a5e30.png para actualizar HomeGraph mediante Request Sync con los metadatos más recientes del dispositivo de la app de la lavadora con errores:

6f2b1344179977cf.png

Abre la app de Google Home y verifica que puedas ver el dispositivo de la lavadora con el nombre Faulty Washer.

e357de6a7faff925.png

3. Prueba la Acción

Después de implementar tu proyecto, prueba que tu Acción controla la lavadora.

Prueba la lavadora

Comprueba el cambio de valor cuando pruebes cualquiera de los siguientes comandos por voz en el teléfono:

"Hey Google, enciende la lavadora".

“Hey Google, inicia mi lavadora”.

"Hey Google, pausa la lavadora".

"Hey Google, reanuda la lavadora".

"Hey Google, detén la lavadora".

Observarás que Asistente responde por voz que algo anda mal cuando pausas o reanudas la lavadora:

"Lo siento, no pude establecer conexión con <nombre visible del proyecto>".

Para depurar este problema, primero necesitas más información sobre el error para limitarlo e identificar la causa raíz.

Panel de estadísticas de Smarthome

Un buen lugar para inspeccionar los errores es el panel de Smarthome Analytics, que agrega gráficos de métricas de uso y salud para la entrega de tu nube:

  • Las métricas de Uso reflejan la tendencia de uso de tu Acción de casa inteligente, incluida la cantidad de usuarios activos por día y el recuento total de solicitudes de tu entrega.
  • Las métricas de Estado te ayudan a supervisar los casos de anomalías en tu Acción de casa inteligente, ya que abarcan la latencia de las solicitudes, el porcentaje de éxito y el desglose de errores.

Si quieres acotar la causa del error, sigue los pasos que se indican a continuación para acceder al panel del proyecto.

  1. En la Consola de Actions, ve a la página Proyectos.
  2. Selecciona tu proyecto de casa inteligente.
  3. Selecciona la pestaña Analytics y haz clic en Ir a Google Cloud Platform.

b1735bbe11a7aff8.png

  1. Esto te llevará a una lista de paneles para tu proyecto en Google Cloud. Selecciona el panel Google Home Analytics - Cloud Integration.

5edd3751323176dd.png

  1. Desplázate hacia abajo hasta el gráfico Cloud Fulfillment Errors - Status Breakdown para ver los códigos de error del intervalo de tiempo destacado.

c468743c20a11c15.png

El código de error PARTNER_RESPONSE_MISSING_DEVICE brinda una sugerencia para la causa raíz. A continuación, recupera registros de eventos basados en el código de error para obtener más detalles.

Accede a los registros de eventos

Para obtener más detalles sobre el error, accede a los registros de eventos de tus Acciones de casa inteligente a través de Cloud Logging.

Abre el Menú de navegación en Google Cloud Platform y, en Operaciones, selecciona Logging > Explorador de registros para acceder a los registros de eventos de tu proyecto. También puedes buscar Explorador de registros en el cuadro de búsqueda.

En la sección Consulta, ingresa la consulta PARTNER_RESPONSE_MISSING_DEVICE y haz clic en Ejecutar consulta. Los registros que coinciden con la consulta se muestran en la sección Resultados de la consulta.

747cca0f1249a5a.png

El registro de errores muestra un evento de casa inteligente con detalles del error que indican lo siguiente:

  • La acción que realizó el usuario es "reanudando la lavadora" (actionType: "STARTSTOP_UNPAUSE"), que corresponde al comando por voz que falló recientemente.
  • El mensaje de depuración asociado es "JSON response does not include device."

En función del mensaje de depuración, debes verificar por qué la app de la lavadora no incluye el dispositivo correcto en la respuesta de EXECUTE.

Identifica la causa raíz del error

En functions/index.js, busca el controlador EXECUTE (en el array onExecute) que muestra el estado de cada comando y el nuevo estado del dispositivo. La inserción de los IDs de dispositivo en una respuesta EXECUTE depende de que se resuelva la función updateDevice:

index.js

app.onExecute(async (body) => {
 ...

 for (const command of intent.payload.commands) {
   for (const device of command.devices) {
     for (const execution of command.execution) {
       executePromises.push(
           updateDevice(execution, device.id)
               .then((data) => {
                 result.ids.push(device.id);
                 Object.assign(result.states, data);
               })
               .catch((e) =>
                 functions.logger.error('EXECUTE',
                     device.id, e.message)));
     }
   }
 }

Además, comprueba cómo la función updateDevice controla las funciones de pausa y reanudación en la lavadora y comprobarás que la cadena que coincide con el comando de pausa/reanudación es incorrecta:

index.js

const updateDevice = async (execution, deviceId) => {
 const {params, command} = execution;
 let state; let ref;
 switch (command) {
   ...
   case 'action.devices.commands.PauseUnpausePause':
     state = {isPaused: params.pause};
     if (params.pause) state.isRunning = false;
     ref = firebaseRef.child(deviceId).child('StartStop');
     break;
 }

 return ref.update(state)
     .then(() => state);
};

Corrige el error

Ahora que identificaste la causa raíz del error, puedes corregir la cadena del comando de pausa / reanudación:

index.js

const updateDevice = async (execution, deviceId) => {
 const {params, command} = execution;
 let state; let ref;
 switch (command) {
   ...
   case 'action.devices.commands.PauseUnpause':
     state = {isPaused: params.pause};
     if (params.pause) state.isRunning = false;
     ref = firebaseRef.child(deviceId).child('StartStop');
     break;
 }

 return ref.update(state)
     .then(() => state);
};

Prueba la corrección

Implementa el código actualizado usando Firebase CLI:

firebase deploy --only functions

Vuelve a ejecutar los siguientes comandos por voz. En este momento, Asistente responderá correctamente cuando pauses o reanudes la lavadora.

"Hey Google, pausa la lavadora".

=>

“Por supuesto, pausando la lavadora”.

"Hey Google, reanuda la lavadora".

=>

"Entendido. Reanudando la lavadora".

También puedes hacer preguntas para verificar el estado actual de la lavadora.

"Hey Google, ¿la lavadora está encendida?".

"Hey Google, ¿la lavadora está funcionando?".

"Hey Google, ¿en qué ciclo está la lavadora?".

4. Prueba tu acción con el paquete de pruebas

Además de realizar pruebas manuales, puedes usar el paquete de pruebas para casa inteligente automatizado para validar casos de uso en función de los tipos y las características de dispositivos asociados con tu Acción. El paquete de pruebas ejecuta una serie de pruebas para detectar problemas en tu Acción y muestra mensajes informativos sobre casos de prueba con errores para acelerar la depuración antes de sumergirte en los registros de eventos.

Ejecuta el paquete de pruebas para la casa inteligente

Sigue estas instrucciones para probar la Acción por paquete de pruebas de tu casa inteligente:

  1. En el navegador web, abre el paquete de pruebas para la casa inteligente.
  2. Accede a Google con el botón de la esquina superior derecha. Esto permite que el paquete de pruebas envíe los comandos directamente a Asistente de Google.
  3. En el campo ID del proyecto, ingresa el ID del proyecto de tu Acción de casa inteligente. Y, luego, haz clic en SIGUIENTE para continuar.
  4. En el paso Test Settings, verás que el paquete de pruebas enumera el tipo de dispositivo y las características de la lavadora.

78ed6a1ebdb581bf.png

  1. Inhabilita la opción Test Request Sync, ya que la app de la lavadora de muestra no tiene una IU para agregar, quitar o cambiar el nombre de la lavadora. En un sistema de producción, debes activar la opción Solicitar sincronización cada vez que el usuario agregue dispositivos, los quite o les cambie el nombre.
  2. Haz clic en SIGUIENTE para comenzar a ejecutar la prueba.

Cuando el paquete de pruebas termine de ejecutarse, consulta los resultados de los casos de prueba. Verás dos casos de prueba fallidos capturados con el mensaje de error correspondiente:

5838d10631c98ed2.png

Para depurar tu Acción de casa inteligente en busca de la falla, deberás identificar la causa raíz del error analizando el mensaje de error.

Analizar mensaje de error

Para ayudar a los desarrolladores a identificar la causa raíz, el paquete de pruebas muestra mensajes de error para cada caso de prueba fallido que indican el motivo.

En el primer caso de prueba fallido que aparece más arriba,

99e4e5d06965a8a7.png

su mensaje de error indica que el paquete de pruebas espera "isPause": true en los estados informados de tu Acción de casa inteligente, pero los estados reales solo incluyen "isPause": false.

Además, el mensaje de error del segundo caso de prueba con errores indica que los estados en la respuesta de QUERY de tu Acción de casa inteligente incluyen "isPause": true, que difiere de "isPause": false en los estados informados de tu Acción de casa inteligente:

fdb5124102e3a37.png

Según ambos mensajes de error, debes verificar si los informes de acción muestran el estado isPaused con el valor correcto.

Identifica la causa raíz del error

Abre functions/index.js, que contiene la función reportstate que publica cambios de estado en Home Graph mediante Report State. Revisa la carga útil del estado del informe y verás que falta el estado isPaused, que es exactamente lo que el paquete de pruebas verificó en los casos de prueba con errores.

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      ...

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
             [context.params.deviceId]: {
                online: true,
                on: snapshot.OnOff.on,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };

      const res = await homegraph.devices.reportStateAndNotification({
        requestBody,
      });
      ...
    });

Corrige el error

Ahora que identificaste la causa raíz del error, revisa functions/index.js. Para ello, agrega el estado isPaused a la carga útil del estado del informe:

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      ...

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
             [context.params.deviceId]: {
                online: true,
                on: snapshot.OnOff.on,
                isPaused: snapshot.StartStop.isPaused,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };
      ...
    });

Prueba la corrección

Implementa el código actualizado usando Firebase CLI:

$ firebase deploy --only functions

Vuelve a ejecutar el paquete de pruebas para una casa inteligente y verás que todos los casos de prueba se aprobaron.

148837f85d377dd6.png

5. Felicitaciones

17d485868a6771bc.png

¡Felicitaciones! Aprendiste a solucionar problemas relacionados con las acciones de la casa inteligente mediante el paquete de pruebas para las métricas y los registros de GCP inteligentes.

Más información

A partir de este Codelab, prueba los siguientes ejercicios y explora recursos adicionales:

También puedes obtener más información sobre cómo probar una Acción y enviarla a revisión, incluido el proceso de certificación para publicar tu Acción para los usuarios.