Registra acciones de dispositivos personalizadas

Es posible que tu dispositivo tenga funciones especiales que no están cubiertas por el conjunto actual de rasgos , como el rasgo "parpadear la luz" para un dispositivo que puede hacer parpadear las luces. Puedes definir acciones personalizadas para tu dispositivo que especifiquen los comandos que se envían a él para activar funciones especiales.

Para definir una acción de dispositivo personalizada, necesitas lo siguiente:

  • Un patrón que debe coincidir con la consulta del usuario
  • Una acción de dispositivo personalizada para asociar con una consulta coincidente
  • Texto que se le habla al usuario si el dispositivo admite la acción
  • Un nombre de comando que se envía de vuelta al dispositivo, junto con cualquier parámetro

Para crear la acción personalizada del dispositivo, coloca esta información en un paquete de acciones. Los paquetes de acciones definen el formato de las respuestas de Asistente. A diferencia del SDK de Actions, las acciones personalizadas del dispositivo se entregan de forma local. No especificas un extremo para procesar solicitudes y proporcionar respuestas. Las acciones de dispositivos personalizados no son de naturaleza conversacional.

Crea un paquete de acciones

Con el siguiente ejemplo, crea un archivo (como actions.json) que defina un comando de prueba: que parpadee una luz LED. Copia el archivo del código de muestra que descargaste en un paso anterior:

cd assistant-sdk-python/google-assistant-sdk/googlesamples/assistant/library/
cp ~/assistant-sdk-python/google-assistant-sdk/actions.json .

Ejemplo
{
    "manifest": {
        "displayName": "Blinky light",
        "invocationName": "Blinky light",
        "category": "PRODUCTIVITY"
    },
    "actions": [
        {
            "name": "com.example.actions.BlinkLight",
            "availability": {
                "deviceClasses": [
                    {
                        "assistantSdkDevice": {}
                    }
                ]
            },
            "intent": {
                "name": "com.example.intents.BlinkLight",
                "parameters": [
                    {
                        "name": "number",
                        "type": "SchemaOrg_Number"
                    },
                    {
                        "name": "speed",
                        "type": "Speed"
                    }
                ],
                "trigger": {
                    "queryPatterns": [
                        "blink ($Speed:speed)? $SchemaOrg_Number:number times",
                        "blink $SchemaOrg_Number:number times ($Speed:speed)?"
                    ]
                }
            },
            "fulfillment": {
                "staticFulfillment": {
                    "templatedResponse": {
                        "items": [
                            {
                                "simpleResponse": {
                                    "textToSpeech": "Blinking $number times"
                                }
                            },
                            {
                                "deviceExecution": {
                                    "command": "com.example.commands.BlinkLight",
                                    "params": {
                                        "speed": "$speed",
                                        "number": "$number"
                                    }
                                }
                            }
                        ]
                    }
                }
            }
        }
    ],
    "types": [
        {
            "name": "$Speed",
            "entities": [
                {
                    "key": "SLOWLY",
                    "synonyms": [
                        "slowly",
                        "slow"
                    ]
                },
                {
                    "key": "NORMALLY",
                    "synonyms": [
                        "normally",
                        "regular"
                    ]
                },
                {
                    "key": "QUICKLY",
                    "synonyms": [
                        "quickly",
                        "fast",
                        "quick"
                    ]
                }
            ]
        }
    ]
}

En el ejemplo anterior, se usa la siguiente información para definir la acción personalizada del dispositivo:

  • Un patrón que debe coincidir con la consulta del usuario (intermitir N veces)
  • La acción de dispositivo personalizada que se asociará con una consulta coincidente (com.example.actions.BlinkLight) para fines organizativos
  • Texto que se le devuelva al usuario si el dispositivo admite la acción (parpadeo N veces)
  • Un nombre de comando (com.example.commands.BlinkLight) que se envía de vuelta al dispositivo, junto con cualquier parámetro (un número y, posiblemente, una descripción de la velocidad)

Para definir el patrón de consulta, ten en cuenta lo siguiente:

  • Puedes usar tipos definidos por schema.org en el patrón de consulta.
  • El array types [...] define la lista de tipos personalizados (por ejemplo, $Speed).
  • Puedes usar tipos personalizados en el patrón de consulta. El usuario puede decir cualquiera de los sinónimos de tu tipo personalizado para que coincida con el patrón de consulta.
  • Cuando un sinónimo coincide, el tipo de instancia (speed) mostraría la clave normalizada (SLOWLY). Puede haber varias entidades en el caso, por ejemplo, que haya diferentes luces que admitan diferentes velocidades de parpadeo.
  • Algunas partes del patrón de solicitud de TTS pueden ser opcionales. Por ejemplo, usa ($Speed:speed)? en el patrón de consulta para que esta parte sea opcional.
  • $type.raw (por ejemplo, $speed.raw) en el TTS de respuesta se reemplaza por las palabras que el usuario realmente dijo.

Para obtener descripciones de muchos de estos campos, consulta la documentación de ActionPackage.

Implementa el paquete de acciones

Después de compilar tu acción personalizada del dispositivo en un paquete de acciones, puedes hacer que Asistente pueda acceder a ese paquete.

Si bien puedes realizar los pasos de esta sección en tu dispositivo, tal vez sea más fácil hacerlo en tu sistema de desarrollo. Los siguientes comandos no requieren un entorno virtual para ejecutarse.

  1. Descarga la herramienta de línea de comandos de gactions.

  2. Quita las credenciales existentes del mismo directorio que la herramienta de gactions.

    rm creds.data
  3. Guarda tu paquete de acciones en Google con la CLI de gactions. Reemplaza project_id por el ID de tu proyecto en la Consola de Actions.

    ./gactions update --action_package actions.json --project project_id
  4. La primera vez que ejecutes este comando, obtendrás una URL y se te pedirá que accedas. Copia la URL y pégala en un navegador (esto se puede hacer en cualquier sistema). En la página, se te pedirá que accedas a tu Cuenta de Google. Accede a la Cuenta de Google con la que se creó el proyecto en un paso anterior de.

  5. Después de aprobar la solicitud de permiso de la API, aparecerá un código en tu navegador, como "4/XXXX". Copia y pega este código en la terminal:

    Enter the authorization code:

    Si la autorización se realizó correctamente, verás una respuesta similar a la siguiente:

    Your app for the Assistant for project my-devices-project was successfully
    updated with your actions.
    
  6. Implementa tu paquete de acciones en modo de prueba mediante la CLI de gactions. Debes haber guardado tu paquete de acciones en Google al menos una vez antes de ejecutar este comando. El modo de prueba habilita el paquete de acciones solo en tu cuenta de usuario.

    ./gactions test --action_package actions.json --project project_id

    Actualmente, no puedes probar el proyecto con el simulador de Actions.

  7. Para actualizar el paquete de acciones, usa el comando gactions update.

  8. (Opcional) Puedes crear paquetes de acciones localizadas para admitir muchos idiomas y configuraciones regionales diferentes al mismo tiempo en un solo proyecto.

Modifica la muestra

Sigue los pasos de esta sección en el dispositivo.

nano hotword.py

Agrega un controlador para tu acción personalizada. Puedes usar el siguiente controlador si quieres utilizar el paquete de acciones de muestra anterior.

import time # Add this to the imports near the top of the file

...

if event.type == EventType.ON_DEVICE_ACTION:
    for command, params in event.actions:
        print('Do command', command, 'with params', str(params))

        # Add the following lines after the existing line above:

        if command == "com.example.commands.BlinkLight":
            number = int( params['number'] )
            for i in range(int(number)):
                print('Device is blinking.')
                # GPIO.output(25, 1)
                time.sleep(1)
                # GPIO.output(25, 0)
                time.sleep(1)

Ejecutar la muestra

Ejecuta el código fuente modificado.

python hotword.py --device-model-id my-model

Intenta con una consulta. Para el ejemplo anterior, prueba lo siguiente:

Hey Google, parpadea 5 veces.

Ten en cuenta que la consulta debe coincidir con el patrón de consulta del paquete de acciones.