Exemple d'utilisation - IoT Platform - Centre de documentation Alibaba Cloud

Contexte

Pour plus d'informations sur la fonctionnalité de configuration à distance, consultez Vue d'ensemble.
La fonctionnalité de configuration à distance nécessite une connexion MQTT. Pour plus d'informations sur les connexions MQTT, consultez Connexion MQTT.

sans titre

Étape 1 : Initialisation

Ajoutez le fichier d'en-tête.

……
……
#include "aiot_ota_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 aiot_ota_init pour créer une instance OTA.

    ota_handle = aiot_ota_init();
    if (NULL == ota_handle) {
        printf("aiot_ota_init failed\r\n");
        aiot_mqtt_deinit(&mqtt_handle);
        return -2;
    }

Étape 2 : Configuration des fonctionnalités

Appelez aiot_ota_setopt pour configurer les options suivantes.

Associez le handle de connexion MQTT.

Important

Avant de définir les paramètres de configuration à distance,

assurez-vous que les paramètres tels que les identifiants de l'appareil sont configurés. Pour plus d'informations, consultez

Configurer les paramètres de connexion MQTT

.

    aiot_ota_setopt(ota_handle, AIOT_OTAOPT_MQTT_HANDLE, mqtt_handle);

Élément de configuration	Exemple	Description
AIOT_OTAOPT_MQTT_HANDLE	mqtt_handle	Les requêtes de configuration à distance utilisent une connexion MQTT. Cet élément associe le handle de connexion MQTT.

Définissez le callback pour les messages d'instruction de configuration à distance.

    aiot_ota_setopt(ota_handle, AIOT_OTAOPT_RECV_HANDLER, demo_ota_recv_handler);

Élément de configuration	Exemple	Description
AIOT_OTAOPT_MQTT_HANDLE	demo_ota_recv_handler	Appelé lorsque l'appareil reçoit une instruction de configuration à distance depuis IoT Platform.

Étape 3 : Demande active de configuration par l'appareil

Si un appareil est hors ligne lorsque IoT Platform envoie une instruction de configuration à distance, l'appareil peut la demander après sa remise en ligne.

Remarque

Si aucune tâche d'appareil n'est créée dans IoT Platform, l'appel d'API renvoie

receive task get detail reply, task_id:[$next],status:[9]

.

Appelez aiot_mqtt_pub pour envoyer une requête à IoT Platform afin d'obtenir les informations de configuration à distance.

    {
        char *topic_string = "/sys/a18wP******/LightSwitch/thing/config/get";
        char *payload_string = "{\"id\":\"123\",\"params\":{\"configScope\":\"product\",\"getType\":\"file\"}}";

        res = aiot_mqtt_pub(mqtt_handle, topic_string, (uint8_t *)payload_string, strlen(payload_string), 0);
        if (res < STATE_SUCCESS) {
            printf("aiot_mqtt_pub failed: -0x%04X\r\n", -res);
            /* If the connection fails, destroy the MQTT instance and release resources. */
            goto exit;
        }
    }

Paramètre Valeur d'exemple Description

topic_string

/sys/a18wP******5/LightSwitch/thing/config/get

Le topic utilisé pour demander les informations de configuration à distance.

Pour plus d'informations sur les topics, consultez Qu'est-ce qu'un topic ?.

Dans l'exemple de code :

a18wP est le ProductKey de l'appareil.
LightSwitch est le DeviceName de l'appareil.

Pour plus d'informations, consultez Obtenir les identifiants de l'appareil.

payload_string

{\"id\":\"123\",\"params\":{\"configScope\":\"product\",\"getType\":\"file\"}}

Le contenu du message de requête.

Le message de requête est au format JSON. Il correspond à la valeur de params dans les données au format Alink. Pour plus d'informations, consultez Un appareil demande activement des informations de configuration.

Après réception de la requête, IoT Platform renvoie les informations de configuration à l'appareil.

Remarque
La taille maximale du contenu de configuration à distance est de 64 Ko.

Vous pouvez activer la configuration à distance et modifier la configuration dans la

console IoT Platform

. Pour plus d'informations, consultez

Modifier un fichier de configuration

.

Appelez aiot_mqtt_recv pour recevoir le message d'instruction de configuration à distance.

Si le pointeur g_dl_handle est nul, le système interroge uniquement les messages MQTT provenant du réseau.
Si le pointeur g_dl_handle n'est pas nul, la fonction aiot_download_recv est appelée.

while (1) {
        aiot_mqtt_process(mqtt_handle);
        res = aiot_mqtt_recv(mqtt_handle);

        if (res == STATE_SYS_DEPEND_NWK_CLOSED) {
            sleep(1);
        }
        if (NULL != g_dl_handle) {
            /* Before the remote configuration is received, change the MQTT message receiving timeout period to 100 ms to reduce the interval between two remote configuration downloads. */
            int32_t ret = aiot_download_recv(g_dl_handle);
            timeout_ms = 100;

            if (STATE_DOWNLOAD_FINISHED == ret) {
                aiot_download_deinit(&g_dl_handle);
                /* After the remote configuration is received, change the MQTT message receiving timeout period back to the default value of 5000 ms. */
                timeout_ms = 5000;
            }
            aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_RECV_TIMEOUT_MS, (void *)&timeout_ms);
        }
    }

Une fois que l'appareil a reçu le message d'instruction de configuration, la fonction de callback demo_ota_recv_handler est déclenchée.
Utilisez les informations suivantes pour rédiger la logique de traitement de la fonction de callback :
- IoT Platform envoie les instructions de configuration à distance à l'appareil via le topic /sys/${ProductKey}/${DeviceName}/thing/config/push.
- Le Link SDK analyse les instructions provenant d'IoT Platform dans une structure de données aiot_ota_recv_t et analyse automatiquement les messages de configuration.
- Le type de message pour la configuration à distance est AIOT_OTARECV_COTA.
- Dans la fonction de callback, vous pouvez initier une requête HTTPS pour télécharger le fichier de configuration à distance. Pour savoir comment rédiger la fonction de callback, consultez Étape 5 : Télécharger le fichier de configuration à distance.

Étape 4 : Réception des informations de configuration à distance envoyées par IoT Platform

Si l'appareil est en ligne, il reçoit immédiatement l'instruction de configuration à distance d'IoT Platform et déclenche la fonction de callback.

Pour plus d'informations, consultez Rédiger la logique de traitement de la fonction de callback.

Étape 5 : Télécharger le fichier de configuration à distance

Important

L'appareil ne télécharge pas automatiquement le fichier de configuration après avoir reçu l'instruction de configuration. Vous devez appeler l'API Link SDK pour démarrer le téléchargement.

Initialisez le programme de téléchargement.

Appelez

aiot_download_init

pour créer un

téléchargement

            uint32_t res = 0;
            uint16_t port = 443;
            uint32_t max_buffer_len = 2048;
            aiot_sysdep_network_cred_t cred;
            void *dl_handle = aiot_download_init();

            if (NULL == dl_handle || NULL == ota_msg->task_desc) {
                return;
            }

            printf("configId: %s, configSize: %u Bytes\r\n", ota_msg->task_desc->version,
                   ota_msg->task_desc->size_total);

            memset(&cred, 0, sizeof(aiot_sysdep_network_cred_t));
            cred.option = AIOT_SYSDEP_NETWORK_CRED_SVRCERT_CA;
            cred.max_tls_fragment = 16384;
            cred.x509_server_cert = ali_ca_cert;
            cred.x509_server_cert_len = strlen(ali_ca_cert);

Configurez les paramètres de téléchargement.

Appelez

aiot_download_setopt

pour configurer les paramètres de la tâche de téléchargement.

            /* Set the download method to TLS download. */
            if ((STATE_SUCCESS != aiot_download_setopt(dl_handle, AIOT_DLOPT_NETWORK_CRED, (void *)(&cred))) ||
                /* Set the server port for the download. */
                (STATE_SUCCESS != aiot_download_setopt(dl_handle, AIOT_DLOPT_NETWORK_PORT, (void *)(&port))) ||
                /* Set the information about the download task. This information is obtained from the task_desc member of the ota_msg input parameter. It includes the download URL, and the size and version number of the remote configuration. */
                (STATE_SUCCESS != aiot_download_setopt(dl_handle, AIOT_DLOPT_TASK_DESC, (void *)(ota_msg->task_desc))) ||
                /* Set the callback function that the SDK calls when the downloaded content arrives. */
                (STATE_SUCCESS != aiot_download_setopt(dl_handle, AIOT_DLOPT_RECV_HANDLER, (void *)(demo_download_recv_handler))) ||
                /* Set the maximum buffer length for a single download. The user is notified each time the buffer is full. */
                (STATE_SUCCESS != aiot_download_setopt(dl_handle, AIOT_DLOPT_BODY_BUFFER_MAX_LEN, (void *)(&max_buffer_len))) ||
                /* Send an HTTP GET request to the HTTP server. */
                (STATE_SUCCESS != aiot_download_send_request(dl_handle))) {
                if (res != STATE_SUCCESS) {
                    aiot_download_deinit(&dl_handle);
                    break;
                }
            }

Après l'envoi d'une requête de téléchargement, l'appareil reçoit un message d'accusé de réception, ce qui déclenche la fonction de callback demo_download_recv_handler pour traiter le téléchargement.

Utilisez les informations suivantes pour rédiger la logique de traitement de la fonction de callback :

La structure de données du message de téléchargement est aiot_download_recv_t. Il s'agit d'un paramètre d'entrée de la fonction de callback.
Le packet->type du message de téléchargement est AIOT_DLRECV_HTTPBODY.
L'exemple de code se contente d'afficher les données. Vous devez télécharger le fichier de configuration vers un emplacement spécifique.

void demo_download_recv_handler(void *handle, const aiot_download_recv_t *packet, void *userdata)
{
    /* Currently, only the case where packet->type is AIOT_DLRECV_HTTPBODY is supported. */
    if (!packet || AIOT_DLRECV_HTTPBODY != packet->type) {
        return;
    }
    int32_t percent = packet->data.percent;
    uint8_t *src_buffer = packet->data.buffer;
    uint32_t src_buffer_len = packet->data.len;

    /* If percent is a negative number, a packet reception exception or a digest verification error occurred. */
    if (percent < 0) {
        /* A packet reception exception or a digest verification error occurred. */
        printf("exception happend, percent is %d\r\n", percent);
        return;
    }
……
……
}

Appelez aiot_download_report_progress pour signaler la progression du téléchargement.

void demo_download_recv_handler(void *handle, const aiot_download_recv_t *packet, void *userdata)
{
    /* Currently, only the case where packet->type is AIOT_DLRECV_HTTPBODY is supported. */
    if (!packet || AIOT_DLRECV_HTTPBODY != packet->type) {
        return;
……
……
    aiot_download_report_progress(handle, percent);
    printf("config len is %d, config content is %.*s\r\n", src_buffer_len, src_buffer_len, (char *)src_buffer);
}

Une fois le téléchargement terminé, appelez aiot_download_deinit pour définir le handle g_dl_handle sur null.

while (1) {
        aiot_mqtt_process(mqtt_handle);
        res = aiot_mqtt_recv(mqtt_handle);

        if (res == STATE_SYS_DEPEND_NWK_CLOSED) {
            sleep(1);
        }
        if (NULL != g_dl_handle) {
            /* Before the remote configuration is received, change the MQTT message receiving timeout period to 100 ms to reduce the interval between two remote configuration downloads. */
            int32_t ret = aiot_download_recv(g_dl_handle);
            timeout_ms = 100;

            if (STATE_DOWNLOAD_FINISHED == ret) {
                aiot_download_deinit(&g_dl_handle);
                /* After the remote configuration is received, change the MQTT message receiving timeout period back to the default value of 5000 ms. */
                timeout_ms = 5000;
            }
            aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_RECV_TIMEOUT_MS, (void *)&timeout_ms);
        }
    }

Étape 6 : Quitter le programme

Appelez aiot_ota_deinit pour détruire l'instance OTA.

    aiot_ota_deinit(&ota_handle);

Étapes suivantes

./output/cota-basic-demo.

Pour plus d'informations, consultez Compiler et exécuter.
journaux opérationnels.