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

In questa sezione viene illustrato come installare il software richiesto e SDK di dispositivo per Python AWS IoT ed eseguire l’applicazione di esempio shadow.py per modificare il documento Shadow e controllare lo stato di shadow.

Prima di eseguire questo tutorial:

È necessario aver impostato Account AWS, aver configurato il dispositivo Raspberry Pi e aver creato un oggetto AWS IoT e una policy che fornisce 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.

Devi anche aver installato Git, Python e SDK di dispositivo per Python AWS IoT. Questo tutorial si basa sui concetti presentati nel tutorial Connettere un Raspberry Pi o altro dispositivo. 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.

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.

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 si pubblica questa richiesta di aggiornamento, AWS IoT crea una shadow classica predefinita per la risorsa dell’oggetto. È possibile osservare la richiesta di aggiornamento pubblicata nei valori reported e desired nella console AWS IoT guardando il documento Shadow per la risorsa dell’oggetto creata (ad esempio, My_light_bulb). Per visualizzare l'aggiornamento nel documento Shadow:

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 come descritto nella sezione Fase 4: Esamina i risultati e i passaggi successivi 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 a AWS IoT Core utilizzando il protocollo MQTT e MQTT su WSS. La libreria del Runtime comune AWS (AWS-CRT) fornisce il supporto del protocollo di comunicazione di basso livello ed è incluso con SDK di dispositivo v2 per Python AWS IoT.

Mentre questo tutorial utilizza MQTT e MQTT su WSS, AWS IoT supporta i dispositivi che pubblicano richieste HTTPS. Per un esempio di un programma Python che invia un messaggio HTTP da un dispositivo, vedi l’esempio di codice HTTPS 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.

MQTT

L'esempio shadow.py chiama mtls_from_path (mostrato qui) in mqtt_connection_builder 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
)

L’esempio shadow.py chiama anche websockets_with_default_aws_signing in mqtt_connection_builder 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:

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 e MQTT.

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.

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:

Fase 4: Esamina i risultati e i passaggi successivi

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.