Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Tutorial: Instalación del SDK del dispositivo y ejecución de la aplicación de ejemplo para Device Shadows En esta sección se muestra cómo instalar el software necesario y el SDK de AWS IoT dispositivos para Python y ejecutar la aplicación de `shadow.py` ejemplo para editar el documento Shadow y controlar el estado de la sombra. **En este tutorial, aprenderá a:** + Usa el software instalado y el SDK de AWS IoT dispositivo para Python para ejecutar la aplicación de muestra. + Descubre cómo al introducir un valor con la aplicación de ejemplo, se publica el valor deseado en la consola de AWS IoT . + Revise la aplicación de ejemplo `shadow.py` y descubra cómo utiliza el protocolo MQTT para actualizar el estado de la sombra. **Antes de ejecutar este tutorial:** Debe haber configurado su Cuenta de AWS dispositivo Raspberry Pi y creado AWS IoT algo y una política que otorgue al dispositivo permisos para publicar y suscribirse a los temas reservados de MQTT del servicio Device Shadow. Para obtener más información, consulte [Tutorial: Cómo preparar la Raspberry Pi para ejecutar la aplicación shadow](create-resources-shadow.md). También debes haber instalado Git, Python y el SDK de AWS IoT dispositivos para Python. Este tutorial se basa en los conceptos presentados en el tutorial [Conexión de una Raspberry Pi u otro dispositivo](connecting-to-existing-device.md). Si no ha probado ese tutorial, le recomendamos que siga los pasos descritos en él para instalar los archivos de certificado y el SDK del dispositivo y, a continuación, vuelva a este tutorial para ejecutar la aplicación de ejemplo `shadow.py`. **Topics** + [Paso 1: ejecutar la aplicación de ejemplo shadow.py](#run-sample-application-shadows) + [Paso 2: Revisar la aplicación de ejemplo del SDK de dispositivos shadow.py](#review-shadow-sample-code) + [Paso 3: Solucionar problemas con la aplicación de ejemplo `shadow.py`](#shadow-sample-app-troubleshoot) + [Paso 4: Revisar los resultados y los siguientes pasos](#sample-app-shadow-review) Para completar este tutorial se necesitan aproximadamente 20 minutos. ## Paso 1: ejecutar la aplicación de ejemplo shadow.py Antes de ejecutar la aplicación de ejemplo `shadow.py`, necesitará la siguiente información además de los nombres y la ubicación de los archivos de certificado que instaló. **Valores de los parámetros de la aplicación** | Parámetro | Dónde encontrar el valor | | --- | --- | | your-iot-thing-name | Nombre del elemento AWS IoT que creaste anteriormente en[Paso 2: Cree un recurso cosa y adjunte la política a la cosa](shadow-provision-cloud.md#create-thing-shadow). Para encontrar este valor, en la [consola de AWS IoT](https://console.aws.amazon.com/iot/home), seleccione **Administrar** y, a continuación, seleccione **Cosas**. | | your-iot-endpoint | El *your-iot-endpoint* valor tiene el formato:`endpoint_id-ats.iot.region.amazonaws.com`, por ejemplo,`a3qj468EXAMPLE-ats.iot.us-west-2.amazonaws.com`. Para encontrar este valor: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/iot/latest/developerguide/lightbulb-shadow-application.html) | **Instalar y ejecutar la aplicación de ejemplo** 1. Navegue hasta el directorio de la aplicación de ejemplo. ``` cd ~/aws-iot-device-sdk-python-v2/samples/service-clients ``` 1. En la ventana de la línea de comandos, *your-iot-thing-name* sustituya *your-iot-endpoint* y, como se indica, y ejecute este comando. ``` python3 shadow.py --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint --thing_name your-iot-thing-name ``` 1. Observe que la aplicación de ejemplo: 1. Se conecta al servicio de AWS IoT de tu cuenta. 1. Se suscribe a eventos `Delta` y respuestas `Update` y `Get`. 1. Le pide que introduzca el valor deseado en el terminal. 1. Muestra una salida similar a la siguiente: ``` Connecting to a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com with client ID 'test-0c8ae2ff-cc87-49d2-a82a-ae7ba1d0ca5a'... Connected! Subscribing to Delta events... Subscribing to Update responses... Subscribing to Get responses... Requesting current shadow state... Launching thread to read user input... Finished getting initial shadow state. Shadow contains reported value 'off'. Enter desired value: ``` **nota** Si tiene problemas para ejecutar la aplicación de ejemplo `shadow.py`, revise [Paso 3: Solucionar problemas con la aplicación de ejemplo `shadow.py`](#shadow-sample-app-troubleshoot). Para obtener información adicional que pueda ayudarle a corregir el problema, añada el parámetro `--verbosity debug` a la línea de órdenes para que la aplicación de ejemplo muestre mensajes detallados sobre lo que está haciendo. **Introduzca los valores y observe las actualizaciones en el documento Shadow** Puede introducir valores en el terminal para especificar el valor `desired`, lo que también actualiza el valor `reported`. Supongamos que introduce el color `yellow` en el terminal. El valor `reported` también se actualiza al color `yellow`. A continuación se muestran los mensajes que se muestran en el terminal: ``` Enter desired value: yellow Changed local shadow value to 'yellow'. Updating reported shadow value to 'yellow'... Update request published. Finished updating reported shadow value to 'yellow'. ``` Al publicar esta solicitud de actualización, AWS IoT crea una sombra clásica y predeterminada para el recurso. Puede observar la solicitud de actualización que publicó en `desired` los valores `reported` y de la AWS IoT consola consultando el documento Shadow del recurso de objetos que creó (por ejemplo,`My_light_bulb`). Para ver la actualización en el documento Shadow, siga estos pasos: 1. En la AWS IoT consola, selecciona **Administrar** y, a continuación, selecciona **Cosas**. 1. En la lista de cosas que se muestran, seleccione la cosa que ha creado, elija **Sombras** y, a continuación, **Sombra clásica**. El documento Shadow debería tener un aspecto similar al siguiente y mostrar los valores `reported` y `desired` establecidos en el color `yellow`. Puede ver estos valores en la sección **Estado de sombra** del documento. ``` { "desired": { "welcome": "aws-iot", "color": "yellow" }, "reported": { "welcome": "aws-iot", "color": "yellow" } } ``` También verá una sección de **metadatos** que contiene la información de la marca de tiempo y el número de versión de la solicitud. Puede utilizar la versión del documento de estado para asegurarse de que actualiza la versión más reciente del documento de sombra de un dispositivo. Si envía otra solicitud de actualización, el número de versión aumentará en 1. Cuando se suministra una versión con una solicitud de actualización, el servicio rechaza la solicitud con un código de respuesta de conflicto HTTP 409 si la versión actual del documento de estado no coincide con la versión suministrada. ``` { "metadata": { "desired": { "welcome": { "timestamp": 1620156892 }, "color": { "timestamp": 1620156893 } }, "reported": { "welcome": { "timestamp": 1620156892 }, "color": { "timestamp": 1620156893 } } }, "version": 10 } ``` Para obtener más información sobre el documento alternativo y observar los cambios en la información de estado, continúe con el siguiente tutorial [Tutorial: Interactuar con Device Shadow mediante la aplicación de ejemplo y el cliente de pruebas MQTT](interact-lights-device-shadows.md), tal como se describe en la sección [Paso 4: Revisar los resultados y los siguientes pasos](#sample-app-shadow-review) de este tutorial. Si lo desea, también puede obtener información sobre el código de ejemplo `shadow.py` y cómo utiliza el protocolo MQTT en la siguiente sección. ## Paso 2: Revisar la aplicación de ejemplo del SDK de dispositivos shadow.py En esta sección se revisa la aplicación de ejemplo `shadow.py` del **SDK de dispositivos AWS IoT v2 para Python** utilizada en este tutorial. Aquí veremos cómo se conecta AWS IoT Core mediante los protocolos MQTT y MQTT over WSS. La biblioteca [de tiempo de ejecución AWS común (AWS-CRT)](https://github.com/awslabs/aws-crt-python#aws-crt-python) proporciona compatibilidad con el protocolo de comunicación de bajo nivel y se incluye en el AWS IoT Device SDK v2 para Python. Si bien este tutorial utiliza MQTT y MQTT sobre WSS, AWS IoT es compatible con los dispositivos que publican solicitudes HTTPS. Para ver un ejemplo de un programa de Python que envía un mensaje HTTP desde un dispositivo, consulta el [ejemplo de código HTTPS](http.md#codeexample) con la biblioteca `requests` de Python. Para obtener información sobre cómo tomar una decisión fundamentada sobre qué protocolo utilizar para las comunicaciones de su dispositivo, consulte la [Elección de un protocolo de aplicación para la comunicación entre dispositivos](protocols.md#protocol-selection). **MQTT** Las llamadas de ejemplo `shadow.py` `mtls_from_path` (mostradas aquí) en el [https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py](https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py) para establecer una conexión con AWS IoT Core mediante el protocolo MQTT. `mtls_from_path` utiliza certificados X.509 y TLS v1.2 para autenticar el dispositivo. La biblioteca AWS-CRT gestiona los detalles de nivel inferior de esa conexión. ``` mqtt_connection = mqtt_connection_builder.mtls_from_path( endpoint=args.endpoint, cert_filepath=args.cert, pri_key_filepath=args.key, ca_filepath=args.ca_file, client_bootstrap=client_bootstrap, on_connection_interrupted=on_connection_interrupted, on_connection_resumed=on_connection_resumed, client_id=args.client_id, clean_session=False, keep_alive_secs=6 ) ``` + `endpoint`es el AWS IoT punto final que ha introducido desde la línea de comandos y `client_id` es el ID que identifica de forma exclusiva a este dispositivo en. Región de AWS + `cert_filepath`, `pri_key_filepath` y `ca_filepath` son las rutas a los archivos de certificados y claves privadas del dispositivo y al archivo CA raíz. + `client_bootstrap` es el objeto común en tiempo de ejecución que gestiona las actividades de comunicación del socket, y se instancia antes de la llamada a `mqtt_connection_builder.mtls_from_path`. + `on_connection_interrupted` y `on_connection_resumed` son funciones de devolución de llamada para llamar cuando la conexión del dispositivo se interrumpe y se reanuda. + `clean_session` es si se debe iniciar una nueva sesión persistente o, si ya existe una, reconectarse a una existente. `keep_alive_secs` es el valor de mantenimiento de vida, en segundos, que se debe enviar en la solicitud `CONNECT`. Se enviará automáticamente un ping en este intervalo. El servidor asume que la conexión se pierde si no recibe un ping después de 1,5 veces este valor. La muestra `shadow.py` también llama a `websockets_with_default_aws_signing` en el [https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py](https://github.com/awslabs/aws-crt-python/blob/89207bcf1387177034e02fe29e8e469ca45e39b7/awscrt/awsiot_mqtt_connection_builder.py) para establecer una conexión con AWS IoT Core usando el protocolo MQTT sobre WSS. MQTT sobre WSS también utiliza los mismos parámetros que MQTT y toma estos parámetros adicionales: + `region`es la región de AWS firma utilizada en la autenticación de Signature V4 y `credentials_provider` son las AWS credenciales que se proporcionan para utilizarlas en la autenticación. La Región se pasa desde la línea de comandos, y el objeto `credentials_provider` se instancia justo antes de la llamada a `mqtt_connection_builder.websockets_with_default_aws_signing`. + `websocket_proxy_options` son las opciones de proxy HTTP, si se utiliza un servidor proxy. En la aplicación de ejemplo `shadow.py`, este valor se crea justo antes de la llamada a `mqtt_connection_builder.websockets_with_default_aws_signing`. **Suscribirse a los temas y eventos de Sombra** El ejemplo `shadow.py` intenta establecer una conexión y espera a que esté completamente conectado. Si no está conectado, los comandos se ponen en cola. Una vez conectado, el ejemplo se suscribe a los eventos delta y actualiza y recibe mensajes, y publica los mensajes con un nivel de calidad de servicio (QoS) de 1 (`mqtt.QoS.AT_LEAST_ONCE`). Cuando un dispositivo se suscribe a un mensaje con QoS de nivel 1, el agente de mensajes guarda los mensajes a los que está suscrito el dispositivo hasta que se puedan enviar al dispositivo. El agente de mensajes vuelve a enviar los mensajes hasta que recibe una respuesta `PUBACK` del dispositivo. Para más información sobre el protocolo MQTT, consulte [Revise el protocolo MQTT](sdk-tutorials.md#sdk-tutorials-mqtt-review) y [MQTT](mqtt.md). Para obtener más información sobre cómo se utilizan MQTT, MQTT sobre WSS, las sesiones persistentes y los niveles de QoS que se utilizan en este tutorial, consulte [Consulte la aplicación de ejemplo del SDK de dispositivo pubsub.py](sdk-tutorials.md#sdk-tutorials-explore-sample). ## Paso 3: Solucionar problemas con la aplicación de ejemplo `shadow.py` Cuando ejecute la aplicación de ejemplo `shadow.py`, debería ver algunos mensajes en el terminal y un aviso para introducir un valor `desired`. Si el programa arroja un error, para depurarlo puede empezar por comprobar si ha ejecutado el comando correcto para su sistema. En algunos casos, el mensaje de error puede indicar problemas de conexión y tener un aspecto similar a: `Host name was invalid for dns resolution` o `Connection was closed unexpectedly`. En esos casos, puede comprobar lo siguiente: + **Compruebe la dirección del punto de conexión en el comando** Revise el argumento `endpoint` del comando que introdujo para ejecutar la aplicación de ejemplo, (por ejemplo, `a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com`) y compruebe este valor en la **consola de AWS IoT **. Para comprobar si ha utilizado el valor correcto: 1. En la **consola de AWS IoT **, seleccione **Administrar** y después **Cosas**. 1. Elija la cosa que creó para su aplicación de ejemplo (por ejemplo, **My\$1light\$1bulb**) y luego elija **Interactuar**. Su punto de conexión se muestra en la sección ** HTTPS**. También debería ver un mensaje que dice: `This thing already appears to be connected.` + **Compruebe la activación del certificado** Los certificados autentican el dispositivo con AWS IoT Core. Para comprobar si su certificado está activo: 1. En la **consola de AWS IoT **, seleccione **Administrar** y después **Cosas**. 1. Elija la cosa que creó para su aplicación de ejemplo (por ejemplo, **My\$1light\$1bulb**) y luego elija **Seguridad**. 1. Seleccione el certificado y, a continuación, en la página de detalles del certificado, seleccione **Acciones**. Si en la lista desplegable **Activar** no está disponible y solo puede elegir **Desactivar**, su certificado está activo. Si no es así, seleccione **Activar** y vuelva a ejecutar el programa de muestra. Si el programa sigue sin ejecutarse, compruebe los nombres de los archivos de certificado en la carpeta `certs`. + **Compruebe la política adjunta al recurso de la cosa** Si bien los certificados autentican el dispositivo, AWS IoT las políticas permiten que el dispositivo realice AWS IoT operaciones, como suscribirse o publicar en temas reservados de MQTT. Para comprobar si se adjunta la política correcta: 1. Busque el certificado tal y como se describió anteriormente y, a continuación, elija **Políticas**. 1. Elija la política que se muestra y compruebe si describe las acciones `connect`, `subscribe`, `receive` y `publish` que permiten al dispositivo publicar y suscribirse a los temas reservados de MQTT. Para ver un ejemplo de política, consulte [Paso 1: Crear una AWS IoT política para Device Shadow](shadow-provision-cloud.md#create-policy-shadow). Si ves mensajes de error que indican que tienes problemas para conectarte AWS IoT, es posible que se deba a los permisos que utilizas para la política. Si ese es el caso, le recomendamos que comience con una política que proporcione acceso total a AWS IoT los recursos y, a continuación, vuelva a ejecutar el programa de muestra. Puede editar la política actual o elegir la política actual, seleccionar **Separar** y, a continuación, crear otra política que proporcione acceso completo y adjuntarla a su recurso principal. Más adelante, podrá restringir la política únicamente a las acciones y políticas que necesite para ejecutar el programa. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:*" ], "Resource": "*" } ] } ``` + **Compruebe la instalación de su SDK del dispositivo** Si el programa sigue sin ejecutarse, puede volver a instalar el SDK del dispositivo para asegurarse de que su instalación del SDK es completa y correcta. ## Paso 4: Revisar los resultados y los siguientes pasos **En este tutorial, ha aprendido a:** + Instale el software, las herramientas y el SDK de AWS IoT dispositivo necesarios para Python. + Entender cómo la aplicación de ejemplo, `shadow.py`, utiliza el protocolo MQTT para recuperar y actualizar el estado actual de la sombra. + Ejecute la aplicación de ejemplo para Device Shadows y observe la actualización del documento Shadow en la AWS IoT consola. También aprendió a solucionar cualquier problema y a corregir errores al ejecutar el programa. **Siguientes pasos** Ahora puede ejecutar la aplicación de ejemplo `shadow.py` y usar Device Shadows para controlar el estado. Puede observar las actualizaciones del documento sombra en la consola de AWS IoT y observar los eventos delta a los que responde la aplicación de muestra. Con el cliente de pruebas MQTT, puede suscribirse a los temas paralelos reservados y observar los mensajes que reciben los temas al ejecutar el programa de ejemplo. Para más información sobre cómo ejecutar este tutorial, consulte [Tutorial: Interactuar con Device Shadow mediante la aplicación de ejemplo y el cliente de pruebas MQTT](interact-lights-device-shadows.md).