Use Link SDK APIs to connect a sub-device to IoT Platform through a gateway - IoT Platform

Informations contextuelles

Pour plus d'informations sur les passerelles et les sous-dispositifs, consultez la rubrique Vue d'ensemble.

La passerelle du sous-dispositif doit maintenir une connexion persistante avec IoT Platform. La méthode de connexion est identique à celle d'un dispositif connecté directement. Pour plus d'informations, consultez la rubrique Vue d'ensemble de la connexion MQTT.

Dans cet exemple, les informations d'authentification d'identité pour le dispositif de passerelle sont les suivantes :

ProductKey	DeviceName	DeviceSecret
a18wP******	LightSwitchGW	uwMTmVAMnGGHaAkqmeDY6cHxxB******

Étape 1 : Initialisation

Ajoutez le fichier d'en-tête.

……
……

#include "aiot_subdev_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_subdev_init pour créer une instance de client subdev et initialiser les paramètres par défaut.

    subdev_handle = aiot_subdev_init();
    if (subdev_handle == NULL) {
        printf("aiot_subdev_init failed\n");
        demo_mqtt_stop(&mqtt_handle);
        return -1;
    }

Étape 2 : Configuration des fonctionnalités

Appelez aiot_subdev_setopt pour configurer les fonctionnalités suivantes.

Associer le handle de la connexion MQTT.
Configurer les rappels de messages pour les fonctionnalités de passerelle et de sous-dispositif.

Associez le handle de la connexion MQTT.

Important

Avant de configurer les paramètres des fonctionnalités de passerelle et de sous-dispositif, assurez-vous d'avoir configuré les informations d'authentification d'identité de la passerelle. Pour plus d'informations, consultez la rubrique Configurer les paramètres de connexion pour MQTT.

Exemple de code :

    aiot_subdev_setopt(subdev_handle, AIOT_SUBDEVOPT_MQTT_HANDLE, mqtt_handle);

Paramètres :

Élément de configuration	Exemple	Description
AIOT_SUBDEVOPT_MQTT_HANDLE	mqtt_handle	Les fonctionnalités de passerelle et de sous-dispositif s'appuient sur la connexion MQTT. Utilisez cet élément de configuration pour associer le handle de connexion MQTT.

Configurez les rappels de messages pour les fonctionnalités de passerelle et de sous-dispositif.

Configurez la fonction de rappel de message.

Exemple de code :

    aiot_subdev_setopt(subdev_handle, AIOT_SUBDEVOPT_RECV_HANDLER, demo_subdev_recv_handler);

Paramètres :

Élément de configuration	Valeur d'exemple	Description
AIOT_SUBDEVOPT_RECV_HANDLER	demo_subdev_recv_handler	Lorsque le dispositif reçoit des messages de passerelle ou de sous-dispositif provenant d'IoT Platform, cette fonction de rappel est déclenchée pour les traiter en conséquence.

Définissez la fonction de rappel de message.

Pour plus d'informations sur le format de données Alink pour les messages, consultez les rubriques Gérer les relations topologiques et État de connexion et de déconnexion des sous-dispositifs.

void demo_subdev_recv_handler(void *handle, const aiot_subdev_recv_t *packet, void *user_data)
{
    switch (packet->type) {
        case AIOT_SUBDEVRECV_TOPO_ADD_REPLY:
        case AIOT_SUBDEVRECV_TOPO_DELETE_REPLY:
        case AIOT_SUBDEVRECV_TOPO_GET_REPLY:
        case AIOT_SUBDEVRECV_BATCH_LOGIN_REPLY:
        case AIOT_SUBDEVRECV_BATCH_LOGOUT_REPLY:
        case AIOT_SUBDEVRECV_SUB_REGISTER_REPLY:
        case AIOT_SUBDEVRECV_PRODUCT_REGISTER_REPLY: {
            printf("msgid        : %d\n", packet->data.generic_reply.msg_id);
            printf("code         : %d\n", packet->data.generic_reply.code);
            printf("product key  : %s\n", packet->data.generic_reply.product_key);
            printf("device name  : %s\n", packet->data.generic_reply.device_name);
            printf("message      : %s\n", (packet->data.generic_reply.message == NULL)?("NULL"):(packet->data.generic_reply.message));
            printf("data         : %s\n", packet->data.generic_reply.data);
        }
        break;
        case AIOT_SUBDEVRECV_TOPO_CHANGE_NOTIFY: {
            printf("msgid        : %d\n", packet->data.generic_notify.msg_id);
            printf("product key  : %s\n", packet->data.generic_notify.product_key);
            printf("device name  : %s\n", packet->data.generic_notify.device_name);
            printf("params       : %s\n", packet->data.generic_notify.params);
        }
        break;
        default: {

        }
    }
}

Étape 3 : Ajout d'une relation topologique

Obtenez les informations d'authentification du sous-dispositif.

Créez un produit et un dispositif pour le sous-dispositif. Lors de la création du produit, définissez le type de nœud sur Gateway Sub-device. Par exemple, créez un produit de sous-dispositif et ajoutez quatre sous-dispositifs.

Nom du produit	ProductKey	DeviceName	DeviceSecret	ProductSecret
LightSwitchSD	a13FN	LightSwitch_SubDev_01	768XBgQwgOakz3K4uhOiLeeh9x	y7GSILD480
		LightSwitch_SubDev_02	iwTZrbjbgNVChfuJkihjE5asek
		LightSwitch_SubDev_03	fdutq35iKMYdcWWBuIINY26hsN
		LightSwitch_SubDev_04	HCKv50YqgwdKhy5cE0Vz4aydmK

Pour plus d'informations, consultez les rubriques Créer un produit et Créer un dispositif.

Définissez la variable g_subdev pour les informations d'authentification du sous-dispositif.
L'exemple de code prédéfinit les informations d'authentification pour quatre sous-dispositifs. Dans un environnement de production, écrivez votre propre code pour récupérer les informations d'authentification du sous-dispositif. Exemples :
- Définissez un protocole entre la passerelle et le sous-dispositif permettant à la passerelle de découvrir le sous-dispositif et d'obtenir son certificat de dispositif. Les fabricants de la passerelle et du sous-dispositif définissent ce protocole.
- Le fabricant de la passerelle peut également fournir une méthode pour préconfigurer les informations de certificat du sous-dispositif sur la passerelle.
```
aiot_subdev_dev_t g_subdev[] = {
    {
        "a13FN******",
        "LightSwitch_SubDev_01",
        "768XBgQwgOakz3K4uhOiLeeh9x******",
        "y7GSILD480******"
    },
    {
        "a13FN******",
        "LightSwitch_SubDev_02",
        "iwTZrbjbgNVChfuJkihjE5asek******",
        "y7GSILD480******"
    },
    {
        "a13FN******",
        "LightSwitch_SubDev_03",
        "fdutq35iKMYdcWWBuIINY26hsN******",
        "y7GSILD480******"
    },
    {
        "a13FN******",
        "LightSwitch_SubDev_04",
        "HCKv50YqgwdKhy5cE0Vz4aydmK******",
        "y7GSILD480******"
    }
};
```

Appelez aiot_subdev_send_topo_add pour envoyer une demande à IoT Platform afin d'ajouter une relation topologique entre le sous-dispositif et le dispositif de passerelle.

    res = aiot_subdev_send_topo_add(subdev_handle, g_subdev, sizeof(g_subdev)/sizeof(aiot_subdev_dev_t));
    if (res < STATE_SUCCESS) {
        printf("aiot_subdev_send_topo_add failed, res: -0x%04X\n", -res);
        aiot_subdev_deinit(&subdev_handle);
        demo_mqtt_stop(&mqtt_handle);
        return -1;
    }

Facultatif : Si le dispositif de passerelle n'agit plus en tant qu'agent pour recevoir les messages d'IoT Platform au nom du sous-dispositif, appelez aiot_subdev_send_topo_delete pour supprimer la relation topologique entre le sous-dispositif et le dispositif de passerelle.

     aiot_subdev_send_topo_delete(subdev_handle, g_subdev, sizeof(g_subdev)/sizeof(aiot_subdev_dev_t));
     if (res < STATE_SUCCESS) {
         printf("aiot_subdev_send_topo_delete failed, res: -0x%04X\n", -res);
         aiot_subdev_deinit(&subdev_handle);
         demo_mqtt_stop(&mqtt_handle);
         return -1;
     }

Étape 4 : Connexion du sous-dispositif

Appelez aiot_subdev_send_batch_login pour envoyer une demande à IoT Platform afin de connecter les sous-dispositifs par lot. Une fois que les sous-dispositifs se sont connectés en utilisant la relation topologique établie, leur statut passe à Online.

    aiot_subdev_send_batch_login(subdev_handle, g_subdev, sizeof(g_subdev)/sizeof(aiot_subdev_dev_t));
    if (res < STATE_SUCCESS) {
        printf("aiot_subdev_send_batch_login failed, res: -0x%04X\n", -res);
        aiot_subdev_deinit(&subdev_handle);
        demo_mqtt_stop(&mqtt_handle);
        return -1;
    }

Facultatif : Pour mettre un sous-dispositif hors ligne, appelez aiot_subdev_send_batch_logout pour envoyer une demande à IoT Platform. Après réception de la demande par IoT Platform, le sous-dispositif est mis hors ligne et son statut passe à Offline.
Important
Lorsque cette API est appelée, IoT Platform met à jour le statut du sous-dispositif sur hors ligne, ce qui empêche la passerelle de recevoir les messages destinés au sous-dispositif.
```
     aiot_subdev_send_batch_logout(subdev_handle, g_subdev, sizeof(g_subdev)/sizeof(aiot_subdev_dev_t));
     if (res < STATE_SUCCESS) {
         printf("aiot_subdev_send_batch_logout failed, res: -0x%04X\n", -res);
         aiot_subdev_deinit(&subdev_handle);
         demo_mqtt_stop(&mqtt_handle);
         return -1;
     }
```

Une fois qu'un sous-dispositif se connecte ou se déconnecte, IoT Platform traite les messages en fonction du statut du sous-dispositif :

Si le sous-dispositif est hors ligne, les messages QoS=0 envoyés par IoT Platform au sous-dispositif sont immédiatement rejetés.
Si le sous-dispositif est en ligne, IoT Platform envoie les messages destinés au sous-dispositif à la passerelle correspondante, qui les transfère ensuite au sous-dispositif.

Étape 5 : Abonnement à un topic pour le sous-dispositif

Une fois qu'un sous-dispositif est connecté à IoT Platform via une passerelle, appelez aiot_mqtt_sub pour vous abonner au topic du sous-dispositif et recevoir ses messages.

Important

Lors de l'abonnement à un topic, faites la distinction entre le ProductKey et le DeviceName du sous-dispositif et de la passerelle. Assurez-vous de vous abonner au bon topic de dispositif.

Exemple de code :

    {
        char *sub_topic = "/a13FN******/LightSwitch_SubDev_01/user/get";

        res = aiot_mqtt_sub(mqtt_handle, sub_topic, NULL, 1, NULL);
        if (res < 0) {
            printf("aiot_mqtt_sub failed, res: -0x%04X\n", -res);
            return -1;
        }
    }

Paramètres :

Paramètre

Exemple

Description

sub_topic

/a13FN/LightSwitch_SubDev_01/user/get

Un topic auquel vous disposez d'autorisations d'abonnement. Dans ce topic :

a13FN est le ProductKey du sous-dispositif.
LightSwitch_SubDev_01 est le DeviceName du sous-dispositif.

Cet exemple utilise un topic personnalisé par défaut pour que le sous-dispositif reçoive des messages d'IoT Platform.

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

Étape 6 : Publication d'un message depuis le sous-dispositif

Appelez aiot_mqtt_pub pour publier un message sur un topic spécifique au sous-dispositif.

Exemple de code :

     {
        char *pub_topic = "/a13FN******/LightSwitch_SubDev_01/user/update";
        char *pub_payload = "{\"id\":\"1\",\"version\":\"1.0\",\"params\":{\"LightSwitch\":0}}";

        res = aiot_mqtt_pub(mqtt_handle, pub_topic, (uint8_t *)pub_payload, (uint32_t)strlen(pub_payload), 0);
        if (res < 0) {
            printf("aiot_mqtt_sub failed, res: -0x%04X\n", -res);
            return -1;
        }
    }

Paramètres :

Paramètre

Exemple

Description

pub_topic

/a13FN/LightSwitch_SubDev_01/user/update

Un topic auquel vous disposez d'autorisations de publication. Dans ce topic :

a13FN est le ProductKey du sous-dispositif.
LightSwitch_SubDev_01 est le DeviceName du sous-dispositif.

Cet exemple utilise un topic personnalisé par défaut pour le sous-dispositif. Le dispositif utilise ce topic pour publier des messages sur IoT Platform.

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

pub_payload

{\"id\":\"1\",\"version\":\"1.0\",\"params\":{\"LightSwitch\":0}}

Le contenu du message signalé à IoT Platform.

Étant donné que la catégorie de topic pour l'exemple de message est personnalisée, le format de données peut également être personnalisé.

Pour plus d'informations sur les formats de données, consultez la rubrique Formats de données.

Étape 7 : Déconnexion de la passerelle

Remarque

MQTT est généralement utilisé pour les dispositifs nécessitant une connexion persistante. Par conséquent, le programme n'atteint généralement pas ce point.

Dans le programme d'exemple, le thread principal est responsable de la configuration des paramètres et de l'établissement de la connexion. Une fois la connexion établie, le thread principal peut entrer en hibernation.

Vous pouvez appeler aiot_mqtt_disconnect pour envoyer un message de déconnexion à IoT Platform et vous déconnecter du réseau.

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

Étape 8 : Quitter le programme

Appelez aiot_subdev_deinit pour détruire l'instance de client subdev et libérer les ressources associées.

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

Étapes suivantes

Après avoir configuré le fichier d'exemple, compilez-le pour générer le fichier exécutable ./output/subdev-basic-demo.

Pour plus d'informations, consultez la rubrique Compiler et exécuter.

Pour plus d'informations sur les résultats, consultez la rubrique Journaux d'exploitation.