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à.
# AWS IoT Applicazione demo Device Shadow
**Importante**
Questa demo è ospitata nel repository Amazon-FreeRTOS che è obsoleto. Ti consigliamo di [iniziare da qui quando crei un nuovo progetto](freertos-getting-started-modular.md). Se hai già un progetto FreeRTOS esistente basato sull'ormai obsoleto repository Amazon-FreerTOS, consulta il. [Guida alla migrazione del repository Github di Amazon-FreeRTOS](github-repo-migration.md)
## Introduzione
Questa demo mostra come utilizzare la libreria AWS IoT Device Shadow per connettersi al [servizio AWS Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html). Utilizza la [libreria CoreMQTT](coremqtt.md) per stabilire una connessione MQTT con TLS (Mutual Authentication) al broker AWS IoT MQTT e il parser della libreria CoreJSON per analizzare i documenti shadow ricevuti dal servizio Shadow. AWS La demo mostra le operazioni shadow di base, come aggiornare un documento shadow e come eliminare un documento shadow. La demo mostra anche come registrare una funzione di callback con la libreria CoreMQTT per gestire messaggi come l'shadow `/update` e i `/update/delta` messaggi inviati dal servizio Device Shadow AWS IoT .
Questa demo è intesa come esercizio di apprendimento solo perché la richiesta di aggiornamento del documento ombra (stato) e la risposta all'aggiornamento vengono eseguite dalla stessa applicazione. In uno scenario di produzione realistico, un'applicazione esterna richiederebbe un aggiornamento dello stato del dispositivo in remoto, anche se il dispositivo non è attualmente connesso. Il dispositivo riconoscerà la richiesta di aggiornamento quando sarà connesso.
**Nota**
Per configurare ed eseguire le demo di FreerTOS, segui i passaggi indicati. [Inizia con FreerTOS](freertos-getting-started.md)
## Funzionalità
La demo crea una singola attività applicativa che ripercorre una serie di esempi che mostrano shadow `/update` e `/update/delta` callback per simulare la commutazione dello stato di un dispositivo remoto. Invia un aggiornamento shadow con il nuovo `desired` stato e attende che il dispositivo cambi lo `reported` stato in risposta al nuovo stato. `desired` Inoltre, viene utilizzato un `/update` callback shadow per stampare i cambiamenti degli stati ombra. Questa demo utilizza anche una connessione MQTT sicura al broker AWS IoT MQTT e presuppone che esista uno `powerOn` stato nell'ombra del dispositivo.
La demo esegue le seguenti operazioni:
1. Stabilire una connessione MQTT utilizzando le funzioni di supporto in. `shadow_demo_helpers.c`
1. Assemblate stringhe di argomenti MQTT per le operazioni di shadow del dispositivo, utilizzando le macro definite dalla libreria Device Shadow AWS IoT .
1. Pubblicate sull'argomento MQTT utilizzato per eliminare l'ombra di un dispositivo per eliminare qualsiasi ombra del dispositivo esistente.
1. Abbonatevi agli argomenti MQTT per `/update/delta` `/update/accepted` e `/update/rejected` utilizzo delle funzioni di supporto in. `shadow_demo_helpers.c`
1. Pubblica lo stato desiderato di `powerOn` utilizzo delle funzioni di supporto in. `shadow_demo_helpers.c` Ciò provocherà l'invio di un `/update/delta` messaggio al dispositivo.
1. Gestisci i messaggi MQTT in `prvEventCallback` arrivo e determina se il messaggio è correlato all'ombra del dispositivo utilizzando una funzione definita dalla libreria AWS IoT Device Shadow ()`Shadow_MatchTopic`. Se il messaggio è un `/update/delta` messaggio shadow del dispositivo, la funzione demo principale pubblicherà un secondo messaggio a cui aggiornare lo stato segnalato. `powerOn` Se viene ricevuto un `/update/accepted` messaggio, verificate che sia lo `clientToken` stesso pubblicato in precedenza nel messaggio di aggiornamento. Ciò segnerà la fine della demo.
La demo può essere trovata nel file `{{freertos}}/demos/device_shadow_for_aws/shadow_demo_main.c` o su [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c).
La schermata seguente mostra l'output previsto quando la demo ha esito positivo.
## Connect al broker AWS IoT MQTT
Per connetterci al broker AWS IoT MQTT, utilizziamo lo stesso metodo `MQTT_Connect()` di. [Demo di autenticazione reciproca CoreMQTT](mqtt-demo-ma.md)
## Eliminare il documento ombra
Per eliminare il documento shadow, chiamate `xPublishToTopic` con un messaggio vuoto, utilizzando le macro definite dalla libreria AWS IoT Device Shadow. Viene utilizzato `MQTT_Publish` per pubblicare sull'`/delete`argomento. La seguente sezione di codice mostra come ciò avviene nella funzione`prvShadowDemoTask`.
```
/* First of all, try to delete any Shadow document in the cloud. */
returnStatus = PublishToTopic( SHADOW_TOPIC_STRING_DELETE( THING_NAME ),
SHADOW_TOPIC_LENGTH_DELETE( THING_NAME_LENGTH ),
pcUpdateDocument,
0U );
```
## Iscriviti agli argomenti ombra
Iscriviti agli argomenti Device Shadow per ricevere notifiche dal AWS IoT broker sulle modifiche dello shadow. Gli argomenti Device Shadow sono assemblati da macro definite nella libreria Device Shadow. La seguente sezione di codice mostra come ciò avviene nella `prvShadowDemoTask` funzione.
```
/* Then try to subscribe shadow topics. */
if( returnStatus == EXIT_SUCCESS )
{
returnStatus = SubscribeToTopic(
SHADOW_TOPIC_STRING_UPDATE_DELTA( THING_NAME ),
SHADOW_TOPIC_LENGTH_UPDATE_DELTA( THING_NAME_LENGTH ) );
}
if( returnStatus == EXIT_SUCCESS )
{
returnStatus = SubscribeToTopic(
SHADOW_TOPIC_STRING_UPDATE_ACCEPTED( THING_NAME ),
SHADOW_TOPIC_LENGTH_UPDATE_ACCEPTED( THING_NAME_LENGTH ) );
}
if( returnStatus == EXIT_SUCCESS )
{
returnStatus = SubscribeToTopic(
SHADOW_TOPIC_STRING_UPDATE_REJECTED( THING_NAME ),
SHADOW_TOPIC_LENGTH_UPDATE_REJECTED( THING_NAME_LENGTH ) );
}
```
## Invia aggiornamenti Shadow
Per inviare un aggiornamento shadow, la demo chiama `xPublishToTopic` con un messaggio in formato JSON, utilizzando macro definite dalla libreria Device Shadow. Viene utilizzato `MQTT_Publish` per pubblicare sull'`/delete`argomento. La seguente sezione di codice mostra come ciò avviene nella `prvShadowDemoTask` funzione.
```
#define SHADOW_REPORTED_JSON \
"{" \
"\"state\":{" \
"\"reported\":{" \
"\"powerOn\":%01d" \
"}" \
"}," \
"\"clientToken\":\"%06lu\"" \
"}"
snprintf( pcUpdateDocument,
SHADOW_REPORTED_JSON_LENGTH + 1,
SHADOW_REPORTED_JSON,
( int ) ulCurrentPowerOnState,
( long unsigned ) ulClientToken );
xPublishToTopic( SHADOW_TOPIC_STRING_UPDATE( THING_NAME ),
SHADOW_TOPIC_LENGTH_UPDATE( THING_NAME_LENGTH ),
pcUpdateDocument,
( SHADOW_DESIRED_JSON_LENGTH + 1 ) );
```
## Gestisci i messaggi shadow delta e i messaggi shadow update
La funzione di callback utente, che è stata registrata nella [libreria client CoreMQTT](https://www.freertos.org/iot-device-shadow/device-shadow-demo.html#handle-shadow-messages) utilizzando la `MQTT_Init` funzione, ci avviserà di un evento di pacchetto in arrivo. Vedi la funzione di callback attiva. [ prvEventCallback](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c#L671-L753) GitHub
La funzione di callback conferma che il pacchetto in entrata è di tipo `MQTT_PACKET_TYPE_PUBLISH` e utilizza l'API Device Shadow Library `Shadow_MatchTopic` per confermare che il messaggio in arrivo è un messaggio shadow.
Se il messaggio in arrivo è un messaggio ombra di tipo`ShadowMessageTypeUpdateDelta`, chiamiamo [ prvUpdateDeltaHandler](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c#L464-L580) per gestire questo messaggio. Il gestore `prvUpdateDeltaHandler` utilizza la libreria CoreJSON per analizzare il messaggio per ottenere il valore delta per `powerOn` lo stato e lo confronta con lo stato corrente del dispositivo gestito localmente. Se questi sono diversi, lo stato del dispositivo locale viene aggiornato in modo da riflettere il nuovo valore `powerOn` dello stato del documento ombra.
Se il messaggio in arrivo è un messaggio shadow con tipo`ShadowMessageTypeUpdateAccepted`, chiamiamo [ prvUpdateAcceptedHandler](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c#L584-L667) per gestire questo messaggio. Il gestore `prvUpdateAcceptedHandler` analizza il messaggio utilizzando la libreria CoreJSON per ottenere il contenuto del messaggio. `clientToken` Questa funzione di gestione verifica che il token client del messaggio JSON corrisponda al token client utilizzato dall'applicazione. Se non corrisponde, la funzione registra un messaggio di avviso.