Tutorial: Interagisci con Device Shadow utilizzando l’app di esempio e il client di test MQTT - AWS IoT Core
Fase 1: Aggiornare i valori desiderati e segnalati utilizzando l’app di esempio shadow.pyFase 2: Visualizzare i messaggi dall’app di esempio shadow.py nel client di test MQTTFase 3: Risoluzione degli errori con le interazioni Device ShadowFase 4: Esamina i risultati e i passaggi successivi

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: Interagisci con Device Shadow utilizzando l’app di esempio e il client di test MQTT

Per interagire con l’applicazione di esempio shadow.py, inserisci un valore nel terminale per il valore desired. Ad esempio, è possibile specificare i colori che assomigliano al semaforo e AWS IoT risponde alla richiesta e aggiorna i valori segnalati.

In questo tutorial, imparerai come:

  • Utilizzare l'app di esempio shadow.py per specificare gli stati desiderati e aggiornare lo stato corrente di shadow.

  • Modificare il documento Shadow per osservare gli eventi delta e come l'app di esempio shadow.py risponde ad essi.

  • Utilizzare il client di test MQTT per effettuare la sottoscrizione ad argomenti shadow e osservare gli aggiornamenti quando si esegue il programma di esempio.

Prima di eseguire questo tutorial, è necessario:

Configurare le impostazioni di Account AWS, configurare il dispositivo Raspberry Pi e creare un oggetto e una policy AWS IoT. È inoltre necessario aver installato il software richiesto, SDK per dispositivo, i file di certificato ed eseguire il programma di esempio nel terminale. Per ulteriori informazioni, consulta i tutorial precedenti Tutorial: Preparazione del Raspberry Pi per eseguire l'applicazione shadow e Fase 1: eseguire l'app di esempio shadow.py. Se non lo hai già fatto, devi completare questi tutorial.

Questo tutorial dura circa 45 minuti.

Fase 1: Aggiornare i valori desiderati e segnalati utilizzando l’app di esempio shadow.py

Nel tutorial precedente Fase 1: eseguire l'app di esempio shadow.py, è stato appreso come osservare un messaggio pubblicato nel documento Shadow nella console AWS IoT quando si inserisce un valore desiderato come descritto nella sezione Tutorial: Installare l'SDK di dispositivo ed eseguire l’applicazione di esempio per Device Shadows.

Nell'esempio precedente, abbiamo impostato il colore desiderato su yellow. Dopo aver inserito ogni valore, il terminale richiede di immettere un altro valore desired. Se si inserisce di nuovo lo stesso valore (yellow), l'app lo riconosce e ti chiede di inserire un nuovo valore desired.

Enter desired value:
yellow
Local value is already 'yellow'.
Enter desired value:

Ora, supponiamo di inserire il colore green. AWS IoT risponde alla richiesta e aggiorna il valore reported a green. Questo è il modo in cui si verifica l'aggiornamento quando lo stato desired è diverso dal reported, causando un delta.

In che modo l’app di esempio shadow.py simula le interazioni Device Shadow:

  1. Inserisci un valore desired (ad esempio yellow) nel terminale per pubblicare lo stato desiderato.

  2. Dato che lo stato desired è diverso dallo stato reported (ad esempio il colore green), si verifica un delta e l'app sottoscritta al delta riceve questo messaggio.

  3. L'app risponde al messaggio e aggiorna il suo stato al valore desired, yellow.

  4. L'app pubblica quindi un messaggio di aggiornamento con il nuovo valore dello stato del dispositivo, yellow.

Di seguito vengono illustrati i messaggi visualizzati nel terminale che mostrano come viene pubblicata la richiesta di aggiornamento.

Enter desired value:
green
Changed local shadow value to 'green'.
Updating reported shadow value to 'green'...
Update request published.
Finished updating reported shadow value to 'green'.

Nella console AWS IoT, il documento Shadow riflette il valore aggiornato su green per entrambi i campi reported e desired e il numero di versione viene incrementato di 1. Ad esempio, se il numero della versione precedente è stato visualizzato come 10, il numero della versione corrente verrà visualizzato come 11.

Nota

L'eliminazione di una shadow non reimposta il numero di versione su 0. Si vedrà che la versione shadow viene incrementata di 1 quando si pubblica una richiesta di aggiornamento o si crea un'altra shadow con lo stesso nome.

Modifica del documento Shadow per osservare gli eventi delta

L'app di esempio shadow.py è anche sottoscritta agli eventi delta e risponde quando c'è una modifica a un valore desired. Ad esempio, è possibile modificare il valore desired per il colore red. A tale scopo, nella console AWS IoT, modifica il documento Shadow facendo clic su Edit (Modifica) e quindi imposta il valore desired a red nel JSON, mantenendo il valore reported a green. Prima di salvare le modifiche, tieni aperto il terminale sul Raspberry Pi mentre vedrai i messaggi visualizzati nel terminale quando si verifica la modifica.

{
"desired": {
  "welcome": "aws-iot",
  "color": "red"
},
"reported": {
  "welcome": "aws-iot",
  "color": "green"
}
}

Dopo aver salvato il nuovo valore, l’app di esempio shadow.py risponde a questa modifica e visualizza i messaggi nel terminale che indicano il delta. Si dovrebbero quindi vedere i seguenti messaggi visualizzati sotto il prompt per l'immissione del valore desired.

Enter desired value:
Received shadow delta event.
Delta reports that desired value is 'red'. Changing local value...
Changed local shadow value to 'red'.
Updating reported shadow value to 'red'...
Finished updating reported shadow value to 'red'.
Enter desired value:
Update request published.
Finished updating reported shadow value to 'red'.

Fase 2: Visualizzare i messaggi dall’app di esempio shadow.py nel client di test MQTT

Puoi utilizzare il client di test MQTT nella console AWS IoT per monitorare i messaggi MQTT che vengono passati in Account AWS. Utilizzando gli argomenti MQTT riservati utilizzati dal servizio Device Shadow, è possibile osservare i messaggi ricevuti dagli argomenti durante l'esecuzione dell'applicazione di esempio.

Se il client di test MQTT non è ancora stato utilizzato, è possibile consultare Visualizza MQTT i messaggi con il AWS IoT MQTT client. In questo modo si impara come utilizzare il client di test MQTT nella console AWS IoT per visualizzare i messaggi MQTT durante il passaggio attraverso il broker di messaggi.

  1. Apertura del client di test MQTT

    Apri il client di test MQTT nella console AWS IoT in una nuova finestra in modo da poter osservare i messaggi ricevuti dagli argomenti MQTT senza perdere la configurazione del client di test MQTT. Il client di test MQTT non conserva sottoscrizioni o registri di messaggi se si lascia andare a un'altra pagina della console. Per questa sezione del tutorial, è possibile avere il documento Shadow dell’oggetto AWS IoT e il client di test MQTT aperti in finestre separate per osservare più facilmente l'interazione con Device Shadows.

  2. Iscrizione agli argomenti Shadow riservati MQTT

    È possibile utilizzare il client di test MQTT per inserire i nomi degli argomenti riservati MQTT di Device Shadow e sottoscriverli per ricevere gli aggiornamenti durante l'esecuzione dell’app di esempio shadow.py. Per effettuare la sottoscrizione agli argomenti:

    1. Nel client di test MQTT nella console AWS IoT, scegli Subscribe to a topic (Sottoscrizione a un argomento).

    2. Nel Topic filter (Filtro di argomenti), inserisci: $aws/things/thingname/shadow/update/ #. Qui, thingname è il nome della risorsa dell’oggetto creata in precedenza (ad esempio, My_light_bulb).

    3. Mantieni i valori predefiniti per le impostazioni di configurazione aggiuntive, quindi scegli Subscribe (Effettua sottoscrizione).

    Utilizzando il carattere jolly # nella sottoscrizione dell'argomento, è possibile sottoscrivere più argomenti MQTT contemporaneamente e osservare tutti i messaggi che vengono scambiati tra il dispositivo e il suo Shadow in un'unica finestra. Per ulteriori informazioni sui caratteri jolly e sul loro utilizzo, consulta MQTTargomenti.

  3. Esegui il programma di esempio shadow.py e osserva i messaggi

    Nella finestra della riga di comando di Raspberry Pi, se hai disconnesso il programma, esegui di nuovo l'app di esempio e guarda i messaggi nel client di test MQTT nella console AWS IoT.

    1. Esegui il seguente comando per riavviare il programma di esempio. Sostituisci il nome del tuo oggetto IoT e il tuo endpoint IoT con i nomi dell’oggetto AWS IoT che hai creato in precedenza (ad esempio, My_light_bulb) e l'endpoint per interagire con il dispositivo. 

      cd ~/aws-iot-device-sdk-python-v2/samples
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

      L’app di esempio shadow.py viene eseguita e recupera lo stato shadow corrente. Se hai eliminato lo shadow o cancellato gli stati correnti, il programma imposta il valore corrente su off e richiede di inserire un valore desired.

      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 document lacks 'color' property. Setting defaults...
Changed local shadow value to 'off'.
Updating reported shadow value to 'off'...
Update request published.
Finished updating reported shadow value to 'off'...
Enter desired value:

      D'altra parte, se il programma era in esecuzione e lo hai riavviato, vedrai il valore di colore più recente riportato nel terminale. Nel client di test MQTT, verrà visualizzato un aggiornamento degli argomenti $aws/things/thingName/shadow/get e $aws/things/thingName./shadow/get/accepted.

      Supponiamo che l'ultimo colore riportato sia green. Di seguito viene mostrato il contenuto del $aws/things/thingName./shadow/get/accepted file JSON.

      {
"state": {
  "desired": {
    "welcome": "aws-iot",
    "color": "green"
  },
  "reported": {
    "welcome": "aws-iot",
    "color": "green"
  }
},
"metadata": {
  "desired": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620161643
    }
  },
  "reported": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620161643
    }
  }
},
"version": 10,
"timestamp": 1620173908
}

    2. Inserisci un valore desired nel terminale, come yellow. L’app di esempio shadow.py risponde e visualizza i seguenti messaggi nel terminale che mostrano la modifica nel valore reported a yellow.

      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'.

      In MQTT test client (Client MQTT di test) nella console AWS IoT, in Subscriptions (Sottoscrizioni), viene visualizzato che i seguenti argomenti hanno ricevuto un messaggio:

      • $aws/things/thingName/shadow/update: mostra che i valori desired e updated cambiano al colore yellow.

      • $aws/things/thingname/shadow/update/accepted: mostra i valori correnti degli stati desired e reported e i relativi metadati e informazioni sulla versione.

      • $aws/things/thingname/shadow/update/documents: mostra i valori precedenti e correnti degli stati desired e reported e i relativi metadati e informazioni sulla versione.

      Siccome il documento $aws/things/thingname/shadow/update/documents contiene anche informazioni contenute negli altri due argomenti, possiamo esaminarlo per vedere le informazioni sullo stato. Lo stato precedente mostra il valore riportato impostato su green, i metadati e le informazioni sulla versione e lo stato corrente che mostra il valore riportato aggiornato a yellow.

      {
"previous": {
  "state": {
    "desired": {
      "welcome": "aws-iot",
      "color": "green"
    },
    "reported": {
      "welcome": "aws-iot",
      "color": "green"
    }
  },
  "metadata": {
    "desired": {
      "welcome": {
        "timestamp": 1617297888
      },
      "color": {
        "timestamp": 1617297898
      }
    },
    "reported": {
      "welcome": {
        "timestamp": 1617297888
      },
      "color": {
        "timestamp": 1617297898
      }
    }
  },
  "version": 10
},
"current": {
  "state": {
    "desired": {
      "welcome": "aws-iot",
      "color": "yellow"
    },
    "reported": {
      "welcome": "aws-iot",
      "color": "yellow"
    }
  },
  "metadata": {
    "desired": {
      "welcome": {
        "timestamp": 1617297888
      },
      "color": {
        "timestamp": 1617297904
      }
    },
    "reported": {
      "welcome": {
        "timestamp": 1617297888
      },
      "color": {
        "timestamp": 1617297904
      }
    }
  },
  "version": 11
},
"timestamp": 1617297904
}

    3. Ora, se si inserisce un altro valore desired, vengono visualizzate ulteriori modifiche ai valori reported e agli aggiornamenti dei messaggi ricevuti da questi argomenti. Anche il numero di versione aumenta di 1. Ad esempio, se si inserisce il valore green, lo stato precedente riporta il valore yellow e lo stato corrente riporta il valore green.

  4. Modifica del documento Shadow per osservare gli eventi delta

    Per osservare le modifiche apportate all'argomento delta, modifica il documento Shadow nella console AWS IoT. Ad esempio, è possibile modificare il valore desired per il colore red. A tale scopo, nella console AWS IoT, scegli Edit (Modifica) e quindi imposta il valore desired sul rosso nel JSON, mantenendo il valore reported impostato su green. Prima di salvare la modifica, tieni il terminale aperto poiché vedrai il messaggio delta riportato nel terminale.

    {
"desired": {
  "welcome": "aws-iot",
  "color": "red"
},
"reported": {
  "welcome": "aws-iot",
  "color": "green"
}
}

    L’app di esempio shadow.py risponde a questa modifica e visualizza i messaggi nel terminale che indica il delta. Nel client di test MQTT, gli argomenti update avranno ricevuto un messaggio che mostra le modifiche apportate ai valori desired e reported.

    Si vede anche che l'argomento $aws/things/thingname/shadow/update/delta ha ricevuto un messaggio. Per visualizzare il messaggio, scegli questo argomento, elencato in Subscriptions (Sottoscrizioni).

    {
"version": 13,
"timestamp": 1617318480,
"state": {
  "color": "red"
},
"metadata": {
  "color": {
    "timestamp": 1617318480
  }
}
}

Fase 3: Risoluzione degli errori con le interazioni Device Shadow

Quando esegui l'app di esempio Shadow, potresti riscontrare problemi con l'osservazione delle interazioni con il servizio Device Shadow.

Se il programma viene eseguito correttamente e richiede di inserire un valore desired, si dovrebbe essere in grado di osservare le interazioni Device Shadow utilizzando il documento Shadow e il client di test MQTT come descritto in precedenza. Tuttavia, se non riesci a visualizzare le interazioni, ecco alcune cose da controllare:

  • Controlla il nome dell’oggetto e la shadow nella console AWS IoT

    Se i messaggi non vengono visualizzati nel documento Shadow, controlla il comando e assicurati che corrisponda al nome dell’oggetto nella console AWS IoT. Puoi anche verificare se hai una shadow classica scegliendo la tua risorsa dell’oggetto e quindi scegliendo Shadows. Questo tutorial si concentra principalmente sulle interazioni con la shadow classica.

    È inoltre possibile confermare che il dispositivo utilizzato è connesso a Internet. Nella console AWS IoT, scegli l'oggetto che hai creato in precedenza, quindi scegli Interact (Interagisci). Nella pagina dei dettagli dell’oggetto, dovresti visualizzare un messaggio con scritto: This thing already appears to be connected.

  • Controlla gli argomenti riservati MQTT che hai sottoscritto

    Se i messaggi non vengono visualizzati nel client di test MQTT, verifica se gli argomenti sottoscritti sono formattati correttamente. Gli argomenti MQTT Device Shadow hanno il formato $aws/things/thingname/shadow/ a cui potrebbe seguire update, get o delete in base alle operazioni che desideri eseguire sulla copia shadow. In questo tutorial si utilizza l'argomento $aws/things/thingName/shadow/ # quindi assicurati di averlo inserito correttamente quando ti iscrivi all'argomento nella sezione Topic filter (Filtro di argomento) del client di test.

    Quando inserisci il nome dell'argomento, assicurati che thingName è lo stesso del nome dell’oggetto AWS IoT che hai creato in precedenza. È inoltre possibile sottoscrivere altri argomenti MQTT per verificare se un aggiornamento è stato eseguito correttamente. Ad esempio, puoi iscriverti all'argomento $aws/things/thingname/shadow/update/rejected per ricevere un messaggio ogni volta che una richiesta di aggiornamento non è riuscita, in modo da poter eseguire il debug dei problemi di connessione. Per ulteriori informazioni sugli argomenti riservati, consulta Argomenti copie shadow e MQTTArgomenti Device Shadow.

Fase 4: Esamina i risultati e i passaggi successivi

In questo tutorial, hai appreso come:

  • Utilizzare l'app di esempio shadow.py per specificare gli stati desiderati e aggiornare lo stato corrente di shadow.

  • Modificare il documento Shadow per osservare gli eventi delta e come l'app di esempio shadow.py risponde ad essi.

  • Utilizzare il client di test MQTT per effettuare la sottoscrizione ad argomenti shadow e osservare gli aggiornamenti quando si esegue il programma di esempio.

Fasi successive

Puoi iscriverti ad altri argomenti riservati MQTT per osservare gli aggiornamenti dell'applicazione shadow. Ad esempio, se ti iscrivi solo all'argomento $aws/things/thingname/shadow/update/accepted, verranno visualizzate solo le informazioni sullo stato corrente quando un aggiornamento viene eseguito correttamente.

È inoltre possibile sottoscrivere altri argomenti shadow per eseguire il debug dei problemi o per ottenere ulteriori informazioni sulle interazioni Device Shadow e anche eseguire il debug di eventuali problemi con le interazioni Device Shadow. Per ulteriori informazioni, consulta Argomenti copie shadow e MQTTArgomenti Device Shadow.

È inoltre possibile scegliere di estendere l'applicazione utilizzando tali shadow o hardware aggiuntivi collegati al Raspberry Pi per i LED e osservare le modifiche al loro stato utilizzando i messaggi inviati dal terminale.

Per ulteriori informazioni sul servizio Device Shadow e sull'utilizzo del servizio in dispositivi, app e servizi, consulta AWS IoT Servizio Device Shadow, Utilizzo delle copie shadow nei dispositivi e Utilizzo delle copie shadow in app e servizi.