Exemple - IoT Platform - Centre de documentation Alibaba Cloud

Contexte

Pour plus d'informations sur les ombres de périphérique, consultez la rubrique Présentation.
Le SDK utilise des connexions MQTT. Pour consulter des exemples de code associés, voir la rubrique Connexion MQTT.

sans titre

Étape 1 : Initialisation

Ajoutez les fichiers d'en-tête.
```
...
...

#include "aiot_shadow_api.h"
```

Configurez les dépendances sous-jacentes et la sortie des journaux.

    aiot_sysdep_set_portfile(&g_aiot_sysdep_portfile);
    aiot_state_set_logcb(demo_state_logcb);

Appelez l'opération aiot_shadow_init pour créer un handle shadow

    shadow_handle = aiot_shadow_init();
    if (shadow_handle == NULL) {
        printf("aiot_shadow_init failed\n");
        return -1;
    }

sans titre

Étape 2 : Configuration des fonctionnalités

Appelez l'opération aiot_shadow_setopt pour configurer les éléments suivants.

Associez un handle de connexion MQTT.

Important

Avant de définir les paramètres spécifiques à l'ombre de périphérique,

    aiot_shadow_setopt(shadow_handle, AIOT_SHADOWOPT_MQTT_HANDLE, mqtt_handle);

Paramètre	Exemple	Description
AIOT_SHADOWOPT_MQTT_HANDLE	mqtt_handle	Les requêtes TSL utilisent cette connexion.

Configurez un callback de message

    aiot_shadow_setopt(shadow_handle, AIOT_SHADOWOPT_RECV_HANDLER, (void *)demo_shadow_recv_handler);

Paramètre	Exemple	Description
AIOT_SHADOWOPT_RECV_HANDLER	demo_shadow_recv_handler	Cette fonction est appelée lors de la réception d'un message d'ombre de périphérique.

Étape 3 : Soumission de l'état du périphérique

Le périphérique appelle l'opération aiot_shadow_send pour soumettre le dernier état à l'ombre de périphérique dans IoT Platform.
Lors de la soumission de l'état, tenez compte des points suivants :
- aiot_shadow_msg_t indique le format des données. Ce paramètre est un paramètre d'entrée du callback aiot_shadow_send().
- AIOT_SHADOWMSG_UPDATE indique le type de message.
```
int32_t demo_update_shadow(void *shadow_handle, char *reported_data, int64_t version)
{
    aiot_shadow_msg_t message;

    memset(&message, 0, sizeof(aiot_shadow_msg_t));
    message.type = AIOT_SHADOWMSG_UPDATE;
    message.data.update.reported = reported_data;
    message.data.update.version = version;

    return aiot_shadow_send(shadow_handle, &message);
}
```

Spécifiez le contenu du message.

        res = demo_update_shadow(shadow_handle, "{\"LightSwitch\":1}", 0);
        if (res < 0) {
            printf("demo_delete_shadow_report failed, res = -0x%04x\r\n", -res);
        }

Exemple de message :

Exemple de message Format Alink Description

{
    "LightSwitch": 1
}

{
      "method": "update", 
      "state": {
        "reported": {
          "LightSwitch": 1
        }
      }, 
      "version": 0
    }

Le contenu du message est au format JSON. Le contenu est indiqué par le paramètre state dans les données Alink. Pour plus d'informations, consultez la rubrique Rapport d'état par un périphérique.

Les éléments suivants décrivent le contenu du message dans cet exemple :

Définissez la propriété LightSwitch sur 1.
Définissez le numéro de version sur 0.
Remarque
- Les numéros de version des opérations ultérieures doivent être incrémentés. Sinon, IoT Platform renvoie une erreur.
- Si vous définissez le numéro de version sur -1, IoT Platform efface les données de l'ombre de périphérique et met à jour le numéro de version sur 0.

Après réception du message, IoT Platform met à jour le fichier d'ombre. Ensuite, IoT Platform renvoie une réponse au périphérique.

Après réception de la réponse par le périphérique, le callback demo_shadow_recv_handler est appelé.

Lors de la définition de la logique du callback, tenez compte des points suivants :

aiot_shadow_recv_t indique le format des données. Ce paramètre est un paramètre d'entrée du callback.
AIOT_SHADOWRECV_GENERIC_REPLY indique le type de message.

Le tableau suivant décrit un exemple de réponse et son format Alink.

Exemple	Format Alink	Description
`{ "status":"success", "version":0 }`	`{ "method": "reply", "payload": { "status": "success", "version": 0 }, "timestamp": 1626317187 }`	La réponse est indiquée par le paramètre payload dans les données Alink. Cet exemple de réponse indique que l'état a été soumis.

Dans cet exemple, le message est affiché.

void demo_shadow_recv_handler(void *handle, const aiot_shadow_recv_t *recv, void *userdata)
{
    printf("demo_shadow_recv_handler, type = %d, productKey = %s, deviceName = %s\r\n",
            recv->type, recv->product_key, recv->device_name);

    switch (recv->type) {

        case AIOT_SHADOWRECV_GENERIC_REPLY: {
            const aiot_shadow_recv_generic_reply_t *generic_reply = &recv->data.generic_reply;

            printf("payload = \"%.*s\", status = %s, timestamp = %ld\r\n",
                   generic_reply->payload_len,
                   generic_reply->payload,
                   generic_reply->status,
                   (unsigned long)generic_reply->timestamp);
        }
……
...
        default:
            break;
    }
}

Étape 4 : Modification de l'état du périphérique à l'aide des propriétés desired

Pour modifier l'état du périphérique, vous pouvez utiliser une application pour envoyer des propriétés desired à l'ombre de périphérique. Vous pouvez également vous connecter à la console IoT Platform et modifier les propriétés desired dans l'ombre de périphérique.

Mettez à jour les propriétés desired dans l'ombre de périphérique. Les méthodes suivantes sont disponibles :
- Développez une application cloud et appelez l'opération API pour envoyer des propriétés desired à l'ombre de périphérique. Pour plus d'informations, consultez la rubrique UpdateDeviceShadow.
- Sur la page Device Details d'IoT Platform, modifiez les propriétés desired dans l'ombre de périphérique. Pour plus d'informations, consultez la rubrique Affichage et mise à jour d'une ombre de périphérique.
IoT Platform met à jour le fichier d'ombre, puis l'envoie au périphérique.

Après réception du fichier d'ombre par le périphérique, le callback demo_shadow_recv_handler est appelé.

Important

Si le périphérique est hors ligne, vous pouvez demander l'ombre de périphérique après sa remise en ligne. Pour plus d'informations, consultez la rubrique

Étape 5 : Demande de l'ombre de périphérique

.

Lors de la définition de la logique du callback, tenez compte des points suivants :

aiot_shadow_recv_t indique le format des données. Ce paramètre est un paramètre d'entrée du callback.
AIOT_SHADOWRECV_CONTROL indique le type de message.

Le tableau suivant décrit un exemple de message et son format Alink.

Exemple Format Alink Description

{
    "state": {
        "desired": {
            "LightSwitch": 0
        }
    },
    "metadata": {
        "desired": {
            "LightSwitch": {
                "timestamp": 1626319658
            }
        }
    }
}

{
      "method": "control", 
      "payload": { 
       "state": {
            "desired": {
                "LightSwitch": 0
            }
        },
        "metadata": {
            "desired": {
                "LightSwitch": {
                    "timestamp": 1626319658 
           }
          }
        }
      }, 
      "version": 2, 
      "timestamp": 1469564576
    }

La réponse est indiquée par le paramètre payload dans les données Alink.

Dans cet exemple, la propriété desired LightSwitch est définie sur 0.

Dans cet exemple, le message est affiché.

void demo_shadow_recv_handler(void *handle, const aiot_shadow_recv_t *recv, void *userdata)
{
    printf("demo_shadow_recv_handler, type = %d, productKey = %s, deviceName = %s\r\n",
            recv->type, recv->product_key, recv->device_name);

    switch (recv->type) {
...
...
        case AIOT_SHADOWRECV_CONTROL: {
            const aiot_shadow_recv_control_t *control = &recv->data.control;

            printf("payload = \"%.*s\", version = %ld\r\n",
                   control->payload_len,
                   control->payload,
                   (unsigned long)control->version);
        }
……
...
        default:
            break;
    }
}

Après la mise à jour de l'état local par le périphérique, celui-ci soumet le dernier état à l'ombre de périphérique et traite la réponse.

Pour plus d'informations, consultez la rubrique

Étape 3 : Soumission de l'état du périphérique

.

Le périphérique appelle l'opération aiot_shadow_send pour supprimer les propriétés desired.

Lors de la suppression des propriétés desired, tenez compte des points suivants :

aiot_shadow_msg_t indique le format des données. Ce paramètre est un paramètre d'entrée du callback aiot_shadow_send().
AIOT_SHADOWMSG_CLEAN_DESIRED indique le type de message.
Dans cet exemple, toutes les propriétés desired sont supprimées et le numéro de version est défini sur 1.

int32_t demo_clean_shadow_desired(void *shadow_handle, int64_t version)
{
    aiot_shadow_msg_t message;

    memset(&message, 0, sizeof(aiot_shadow_msg_t));
    message.type = AIOT_SHADOWMSG_CLEAN_DESIRED;
    message.data.clean_desired.version = version;

    return aiot_shadow_send(shadow_handle, &message);
}
……
...
        res = demo_clean_shadow_desired(shadow_handle, 1);
        if (res < 0) {
            printf("demo_clean_shadow_desired failed, res = -0x%04x\r\n", -res);
        }

Après réception de la demande de suppression des propriétés desired par IoT Platform, celle-ci renvoie une réponse. Dans ce cas, le callback demo_shadow_recv_handler est appelé.

Pour plus d'informations, consultez la rubrique

Configuration d'un callback pour traiter les réponses

.

Étape 5 : Demande de l'ombre de périphérique

Le périphérique appelle l'opération aiot_shadow_send pour demander le contenu de l'ombre de périphérique à IoT Platform.

AIOT_SHADOWMSG_GET

indique le type de message.

int32_t demo_get_shadow(void *shadow_handle)
{
    aiot_shadow_msg_t message;

    memset(&message, 0, sizeof(aiot_shadow_msg_t));
    message.type = AIOT_SHADOWMSG_GET;

    return aiot_shadow_send(shadow_handle, &message);
}
……
...
        res = demo_get_shadow(shadow_handle);
        if (res < 0) {
            printf("demo_get_shadow failed, res = -0x%04x\r\n", -res);
        }

Après réception de la demande par IoT Platform, celle-ci renvoie une réponse. Après réception de la réponse par le périphérique, le callback demo_shadow_recv_handler est appelé.

Lors de la définition de la logique du callback, tenez compte des points suivants :

aiot_shadow_recv_t indique le format des données. Ce paramètre est un paramètre d'entrée du callback.
AIOT_SHADOWRECV_GET_REPLY indique le type de message.

Le tableau suivant décrit un exemple de réponse et son format Alink.

Exemple	Format Alink	Description
`{ "status": "success", "state": { "reported": { } }, "metadata": { "reported": { } } }`	`{ "method": "reply", "payload": { "status": "success", "state": { "reported": { } }, "metadata": { "reported": { } } }, "version": 5, "timestamp": 1626320690 }`	La réponse est indiquée par le paramètre payload dans les données Alink. Cet exemple de réponse indique que la demande a abouti. Le paramètre reported ne contient aucune donnée, ce qui signifie qu'aucune propriété n'a été soumise.

Dans cet exemple, le message est affiché.

void demo_shadow_recv_handler(void *handle, const aiot_shadow_recv_t *recv, void *userdata)
{
    printf("demo_shadow_recv_handler, type = %d, productKey = %s, deviceName = %s\r\n",
            recv->type, recv->product_key, recv->device_name);

    switch (recv->type) {
...
...
        case AIOT_SHADOWRECV_GET_REPLY: {
            const aiot_shadow_recv_get_reply_t *get_reply = &recv->data.get_reply;

            printf("payload = \"%.*s\", version = %ld\r\n",
                   get_reply->payload_len,
                   get_reply->payload,
                   (unsigned long)get_reply->version);
        }
        default:
            break;
    }
}

Étape 6 : Suppression des propriétés dans l'ombre de périphérique

Le périphérique appelle l'opération aiot_shadow_send pour supprimer des propriétés spécifiées dans l'ombre de périphérique.

Lors de l'envoi d'une demande, tenez compte des points suivants :

aiot_shadow_msg_t indique le format des données. Ce paramètre est un paramètre d'entrée du callback aiot_shadow_send().
AIOT_SHADOWMSG_DELETE_REPORTED indique le type de message.

int32_t demo_delete_shadow_report(void *shadow_handle, char *reported, int64_t version)
{
    aiot_shadow_msg_t message;

    memset(&message, 0, sizeof(aiot_shadow_msg_t));
    message.type = AIOT_SHADOWMSG_DELETE_REPORTED;
    message.data.delete_reporte.reported = reported;
    message.data.delete_reporte.version = version;

    return aiot_shadow_send(shadow_handle, &message);
}

Spécifiez les propriétés à supprimer.

        res = demo_delete_shadow_report(shadow_handle, "{\"LightSwitch\":\"null\"}", 2);
        if (res < 0) {
            printf("demo_delete_shadow_report failed, res = -0x%04x\r\n", -res);
        }

Exemple de message :

Exemple Format Alink Description

"{\"LightSwitch\":\"null\"}", 2

{
      "method": "delete", 
      "state": {
        "reported": {
          "LightSwitch": "null", 
        }
      }, 
      "version": 2
    }

Le contenu du message est au format JSON. Le contenu est indiqué par le paramètre state dans les données Alink. Pour plus d'informations, consultez la rubrique Suppression des propriétés d'ombre par un périphérique.

Les éléments suivants décrivent le contenu du message dans cet exemple :

Définissez la propriété LightSwitch sur null. Cette valeur indique que toutes les données de l'ombre de périphérique sont effacées.
Définissez le numéro de version sur 2.

Après réception de la demande par IoT Platform, celle-ci renvoie une réponse. Après réception de la réponse par le périphérique, le callback demo_shadow_recv_handler est appelé.

Pour plus d'informations, consultez la rubrique

Configuration d'un callback pour traiter les réponses

.

Étape 7 : Arrêt du programme

Appelez l'opération aiot_shadow_deinit pour détruire le handle shadow

    res = aiot_shadow_deinit(&shadow_handle);
    if (res < STATE_SUCCESS) {
        printf("aiot_shadow_deinit failed: -0x%04X\n", -res);
        return -1;
    }

Étapes suivantes

Dans cet exemple, le fichier exécutable ./demos/shadow-basic-demo est généré.

Pour plus d'informations, consultez la rubrique Compilation et exécution.
Important
- Lors de la configuration du fichier d'exemple de code, supprimez les symboles de commentaire (/* et */) de part et d'autre du code et modifiez les numéros de version en fonction des scénarios réels.
- Lors de la modification des numéros de version, tenez compte des points suivants :
  - Les numéros de version des opérations ultérieures doivent être incrémentés. Sinon, IoT Platform renvoie une erreur.
  - Si vous définissez le numéro de version sur -1, IoT Platform efface les données de l'ombre de périphérique et met à jour le numéro de version sur 0.
Journaux d'exécution.