Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Tutorial: Installare l'SDK di dispositivo ed eseguire l’applicazione di esempio per Device Shadows Questa sezione mostra come installare il software richiesto e AWS IoT Device SDK for Python ed eseguire `shadow.py` l'applicazione di esempio per modificare il documento Shadow e controllare lo stato dell'ombra. **In questo tutorial, apprenderai come:** + Usa il software installato e AWS IoT Device SDK for Python per eseguire l'app di esempio. + Scoprire come l'immissione di un valore utilizzando l'app di esempio pubblichi il valore desiderato nella console AWS IoT . + Esaminare l’applicazione di esempio `shadow.py` e come utilizzare il protocollo MQTT per aggiornare lo stato di shadow. **Prima di eseguire questo tutorial:** È necessario aver configurato Account AWS, configurato il dispositivo Raspberry Pi e creato una AWS IoT cosa e una politica che consentano al dispositivo le autorizzazioni per pubblicare e sottoscrivere gli argomenti riservati MQTT del servizio Device Shadow. Per ulteriori informazioni, consulta [Tutorial: Preparazione del Raspberry Pi per eseguire l'applicazione shadow](create-resources-shadow.md). Devi aver installato anche Git, Python e AWS IoT Device SDK for Python. Questo tutorial si basa sui concetti presentati nel tutorial [Connettere un Raspberry Pi o altro dispositivo](connecting-to-existing-device.md). Se non hai provato questo tutorial, ti consigliamo di seguire i passaggi descritti in tale tutorial per installare i file dei certificati e SDK di dispositivo e quindi tornare a questo tutorial per eseguire l’applicazione di esempio `shadow.py`. **Topics** + [Fase 1: eseguire l'app di esempio shadow.py](#run-sample-application-shadows) + [Fase 2: Revisione dell'app di esempio shadow.py dell'SDK di dispositivo](#review-shadow-sample-code) + [Fase 3: Risolvi i problemi con l’app di esempio `shadow.py`](#shadow-sample-app-troubleshoot) + [Fase 4: Esamina i risultati e i passaggi successivi](#sample-app-shadow-review) Questo tutorial dura circa 20 minuti. ## Fase 1: eseguire l'app di esempio shadow.py Prima di eseguire il comando l’app di esempio `shadow.py`, oltre ai nomi e alla posizione dei file di certificato installati, sono necessarie le seguenti informazioni. **Valori dei parametri dell'applicazione** | Parametro | Dove trovare il valore | | --- | --- | | your-iot-thing-name | Nome della AWS IoT cosa che hai creato in precedenza in. [Fase 2: creare una risorsa dell’oggetto e connettere la policy all’oggetto](shadow-provision-cloud.md#create-thing-shadow) Per trovare questo valore, nella [console AWS IoT](https://console.aws.amazon.com/iot/home), scegli **Manage (Gestione)**, quindi scegli **Things (Oggetti)**. | | your-iot-endpoint | Il *your-iot-endpoint* valore ha un formato di:`endpoint_id-ats.iot.region.amazonaws.com`, ad esempio,`a3qj468EXAMPLE-ats.iot.us-west-2.amazonaws.com`. Per trovare questo valore: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/iot/latest/developerguide/lightbulb-shadow-application.html) | **Installazione ed esecuzione dell'applicazione di esempio** 1. Passare alla directory dell’applicazione di esempio. ``` cd ~/aws-iot-device-sdk-python-v2/samples/service-clients ``` 1. Nella finestra della riga di comando, sostituisci *your-iot-endpoint* e *your-iot-thing-name* come indicato ed esegui questo 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. Osserva che l'applicazione di esempio: 1. Si connette al servizio AWS IoT per il tuo account. 1. Effettui la sottoscrizione ad eventi `Delta` e alle risposte `Update` e `Get`. 1. Richieda di inserire un valore desiderato nel terminale. 1. L'output sia simile a quello riportato di seguito: ``` 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** In caso di problemi nell'esecuzione dell’app di esempio `shadow.py`, consulta [Fase 3: Risolvi i problemi con l’app di esempio `shadow.py`](#shadow-sample-app-troubleshoot). Per ottenere ulteriori informazioni che potrebbero essere utili per risolvere il problema, aggiungi il parametro `--verbosity debug` alla riga di comando in modo che l'app di esempio visualizzi messaggi dettagliati su ciò che sta facendo. **Inserisci i valori e osserva gli aggiornamenti nel documento Shadow** È possibile inserire i valori nel terminale per specificare il valore `desired`, che aggiorna anche il valore `reported`. Supponiamo di inserire il colore `yellow` nel terminale. Il valore `reported` viene aggiornato anche al colore `yellow`. Di seguito sono riportati i messaggi visualizzati nel terminale: ``` 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'. ``` Quando pubblichi questa richiesta di aggiornamento, AWS IoT crea un'ombra classica predefinita per la risorsa thing. È possibile osservare la richiesta di aggiornamento pubblicata su `reported` e i `desired` valori nella AWS IoT console esaminando il documento Shadow relativo alla risorsa oggetto che è stata creata (ad esempio,`My_light_bulb`). Per visualizzare l'aggiornamento nel documento Shadow: 1. Nella AWS IoT console, scegli **Gestisci**, quindi scegli **Cose**. 1. Nell'elenco di oggetti visualizzati, seleziona l'oggetto che hai creato, scegli **Shadows**, quindi scegli **Classic Shadow (Shadow classico)**. Il documento Shadow dovrebbe essere simile a quanto riportato di seguito, mostrando i valori `reported` e `desired` impostati sul colore `yellow`. Questi valori vengono visualizzati nello **Stato shadow** del documento. ``` { "desired": { "welcome": "aws-iot", "color": "yellow" }, "reported": { "welcome": "aws-iot", "color": "yellow" } } ``` Viene inoltre visualizzato una sezione **Metadata (Metadati)** che contiene le informazioni sul timestamp e il numero di versione della richiesta. Puoi usare la versione del documento sullo stato per assicurarti di aggiornare la versione più recente di una copia shadow di un dispositivo. Se invii un'altra richiesta di aggiornamento, il numero di versione aumenta di 1. Quando fornisci una versione con una richiesta di aggiornamento, il servizio rifiuta la richiesta con un codice di risposta di conflitto HTTP 409 se la versione corrente del documento sullo stato non corrisponde alla versione fornita. ``` { "metadata": { "desired": { "welcome": { "timestamp": 1620156892 }, "color": { "timestamp": 1620156893 } }, "reported": { "welcome": { "timestamp": 1620156892 }, "color": { "timestamp": 1620156893 } } }, "version": 10 } ``` Per saperne di più sul documento Shadow e osservare le modifiche alle informazioni sullo stato, procedi con il tutorial successivo [Tutorial: Interagisci con Device Shadow utilizzando l’app di esempio e il client di test MQTT](interact-lights-device-shadows.md) come descritto nella sezione [Fase 4: Esamina i risultati e i passaggi successivi](#sample-app-shadow-review) di questo tutorial. Eventualmente, si può anche sapere di più sul codice di esempio `shadow.py` e su come utilizza il protocollo MQTT nella sezione seguente. ## Fase 2: Revisione dell'app di esempio shadow.py dell'SDK di dispositivo Questa sezione esamina l’app di esempio `shadow.py` dal **SDK di dispositivo v2 AWS IoT per Python**, usata in questo tutorial. Qui esamineremo come si connette AWS IoT Core utilizzando il protocollo MQTT e MQTT su WSS. La libreria [AWS Common Runtime (AWS-CRT)](https://github.com/awslabs/aws-crt-python#aws-crt-python) fornisce il supporto del protocollo di comunicazione di basso livello ed è inclusa in AWS IoT Device SDK v2 for Python. Sebbene questo tutorial utilizzi MQTT e MQTT su WSS, supporta i dispositivi che pubblicano richieste HTTPS. AWS IoT Per un esempio di un programma Python che invia un messaggio HTTP da un dispositivo, vedi l’[esempio di codice HTTPS](http.md#codeexample) utilizzando la libreria di Python `requests`. Per informazioni su come prendere una decisione informata sul protocollo da utilizzare per le comunicazioni del dispositivo, consulta [Scelta di un protocollo applicativo per la comunicazione del dispositivo](protocols.md#protocol-selection). **MQTT** L'esempio `shadow.py` chiama `mtls_from_path` (mostrato qui) in [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) per stabilire una connessione con AWS IoT Core utilizzando il protocollo MQTT. `mtls_from_path` utilizza i certificati X.509 e TLS v1.2 per autenticare il dispositivo. La libreria AWS-CRT gestisce i dettagli di livello inferiore di quella connessione. ``` 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`è l' AWS IoT endpoint che hai passato dalla riga di comando ed `client_id` è l'ID che identifica in modo univoco questo dispositivo in. Regione AWS + `cert_filepath`, `pri_key_filepath` e `ca_filepath` sono i percorsi del certificato e dei file di chiave privata del dispositivo e del file root CA. + `client_bootstrap` è l'oggetto runtime comune che gestisce le attività di comunicazione socket e viene istanziato prima della chiamata a `mqtt_connection_builder.mtls_from_path`. + `on_connection_interrupted` e `on_connection_resumed` sono le funzioni di callback da chiamare quando la connessione del dispositivo viene interrotta e ripresa. + `clean_session` consente di avviare una nuova sessione persistente o, se è presente, di riconnettersi a una esistente. `keep_alive_secs` è il valore keep alive, in secondi, per inviare la richiesta `CONNECT`. Un ping verrà inviato automaticamente a questo intervallo. Se il server non riceve un ping dopo 1,5 volte questo valore, presuppone che la connessione sia stata persa. L’esempio `shadow.py` chiama anche `websockets_with_default_aws_signing` in [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) per stabilire una connessione con AWS IoT Core utilizzando il protocollo MQTT su WSS. MQTT su WSS utilizza anche gli stessi parametri di MQTT e prende questi parametri aggiuntivi: + `region`è la regione di AWS firma utilizzata dall'autenticazione Signature V4 e `credentials_provider` sono AWS le credenziali fornite da utilizzare per l'autenticazione. La regione viene passata dalla riga di comando, e l’oggetto `credentials_provider` viene istanziato appena prima della chiamata a `mqtt_connection_builder.websockets_with_default_aws_signing`. + `websocket_proxy_options` sono le opzioni proxy HTTP, se si utilizza un host proxy. Nell’app di esempio `shadow.py`, questo valore viene istanziato appena prima della chiamata a `mqtt_connection_builder.websockets_with_default_aws_signing`. **Iscrizione agli argomenti e agli eventi Shadow** L’esempio `shadow.py` cerca di stabilire una connessione e attende di essere completamente connesso. Se non è connesso, i comandi vengono messi in coda. Una volta connesso, l'esempio sottoscrive gli eventi delta e aggiorna e riceve i messaggi e pubblica i messaggi con un livello Quality of Service (QoS) pari a 1 (`mqtt.QoS.AT_LEAST_ONCE`). Quando un dispositivo sottoscrive un messaggio con QoS livello 1, il broker di messaggi salva i messaggi a cui il dispositivo è sottoscritto fino a quando non possono essere inviati al dispositivo. Il broker di messaggi restituisce i messaggi fino a quando non riceve una risposta `PUBACK` dal dispositivo. Per ulteriori informazioni sul protocollo MQTT, consulta [Esamina il protocollo MQTT](sdk-tutorials.md#sdk-tutorials-mqtt-review) e [MQTT](mqtt.md). Per ulteriori informazioni su MQTT, MQTT su WSS, sessioni persistenti e i livelli QoS utilizzati in questa esercitazione, consulta [Revisione dell'app di esempio pubsub.py SDK per dispositivi](sdk-tutorials.md#sdk-tutorials-explore-sample). ## Fase 3: Risolvi i problemi con l’app di esempio `shadow.py` Quando si esegue l’app di esempio `shadow.py`, dovresti vedere alcuni messaggi visualizzati nel terminale e un prompt per inserire un valore `desired`. Se il programma genera un errore, per eseguire il debug dell'errore, puoi iniziare controllando se hai eseguito il comando corretto per il tuo sistema. In alcuni casi, il messaggio di errore potrebbe indicare problemi di connessione e avere un aspetto simile a: `Host name was invalid for dns resolution` o `Connection was closed unexpectedly`. In questi casi, ecco alcune operazioni disponibili: + **Controlla l'indirizzo dell'endpoint nel comando** Esaminare il parametro `endpoint` nel comando inserito per eseguire l'app di esempio (ad esempio `a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com`) e controllare questo valore nella **console AWS IoT **. Per verificare se hai utilizzato il valore corretto: 1. Nella **console AWS IoT **, scegli **Manage (Gestione)** e poi **Things (Oggetti)**. 1. Scegli l’oggetto che hai creato per l'app di esempio (ad esempio, **my\$1light\$1lampadina**) e quindi scegli **Interact (Interagisci)**. L'endpoint viene visualizzato nella sezione ** HTTPS** della pagina dei dettagli degli oggetti. Dovresti visualizzare anche un messaggio in cui viene indicato: `This thing already appears to be connected.` + **Verifica l'attivazione del certificato** I certificati autenticano il dispositivo con. AWS IoT Core Per verificare se il certificato è attivo: 1. Nella **console AWS IoT **, scegli **Manage (Gestione)** e poi **Things (Oggetti)**. 1. Scegli l’oggetto che hai creato per l'app di esempio (ad esempio, **my\$1light\$1lampadina**) e quindi scegli **Security (Sicurezza)**. 1. Seleziona il certificato e quindi, dalla pagina dei dettagli del certificato, scegli Seleziona il certificato e quindi, dalla pagina dei dettagli del certificato, scegli **Actions (Operazioni)**. Se nell'elenco a discesa **Activate (Attiva)** non è disponibile e puoi solo scegliere **Deactivate (Disattiva)**, il certificato è attivo. In caso contrario, scegli **Activate (Attiva)** ed esegui di nuovo il programma di esempio. Se il programma continua a non essere eseguito, controlla i nomi dei file del certificato nel folder `certs`. + **Controlla la policy associata alla risorsa dell’oggetto** Mentre i certificati autenticano il dispositivo, AWS IoT le policy consentono al dispositivo di eseguire AWS IoT operazioni, come la sottoscrizione o la pubblicazione di argomenti riservati MQTT. Per verificare se la policy corretta è allegata: 1. Individua il certificato come descritto in precedenza, quindi scegli **Policies (Policy)**. 1. Scegli la policy visualizzata e verifica se descrive le operazioni `connect`, `subscribe`, `receive` e `publish` che consentono al dispositivo l’autorizzazione di pubblicare e sottoscrivere gli argomenti riservati MQTT. Consulta [Fase 1: Creare una AWS IoT policy per il Device Shadow](shadow-provision-cloud.md#create-policy-shadow) per una policy di esempio. Se visualizzi messaggi di errore che indicano problemi di connessione AWS IoT, ciò potrebbe essere dovuto alle autorizzazioni che stai utilizzando per la politica. In tal caso, ti consigliamo di iniziare con una politica che fornisca l'accesso completo alle AWS IoT risorse e quindi di eseguire nuovamente il programma di esempio. È possibile modificare la policy corrente oppure scegliere la policy corrente. Scegli **Detach (Distacca)** e quindi crea un altra policy che fornisca accesso completo e collegala alla risorsa dell’oggetto. In seguito è possibile limitare la policy solo alle operazioni e alle policy necessarie per eseguire il programma. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:*" ], "Resource": "*" } ] } ``` + **Verifica dell'installazione di SDK di dispositivo** Se il programma non viene ancora eseguito, è possibile reinstallare SDK di dispositivo per assicurarsi che l'installazione dell'SDK sia completa e corretta. ## Fase 4: Esamina i risultati e i passaggi successivi **In questo tutorial, hai appreso come:** + Installa il software, gli strumenti e il AWS IoT Device SDK for Python necessari. + Capire come l'applicazione di esempio ,`shadow.py`, che utilizza il protocollo MQTT per recuperare e aggiornare lo stato corrente di shadow. + Esegui l'app di esempio per Device Shadows e osserva l'aggiornamento del documento Shadow nella console. AWS IoT Hai anche imparato a risolvere eventuali problemi e correggere gli errori durante l'esecuzione del programma. **Fasi successive** A questo punto è possibile eseguire il l’applicazione di esempio `shadow.py` e utilizzare Device Shadows per controllare lo stato. È possibile osservare gli aggiornamenti del documento Shadow nella console AWS IoT e gli eventi delta a cui risponde l'app di esempio. Utilizzando il client di test MQTT, è possibile iscriversi agli argomenti shadow riservati e osservare i messaggi ricevuti dagli argomenti durante l'esecuzione del programma di esempio. Per ulteriori informazioni su come eseguire questo tutorial, consulta [Tutorial: Interagisci con Device Shadow utilizzando l’app di esempio e il client di test MQTT](interact-lights-device-shadows.md).