Précédent

Suivant

Redémarrage à distance d’un appareil Azure Sphere avec une méthode directe Azure IoT Hub

Effectué

Dans cette unité, vous allez découvrir comment redémarrer un appareil Azure Sphere à distance dans Azure IoT Explorer.

Fonctionnement des commandes de méthode directe IoT Hub

Azure IoT Hub utilise des commandes de méthode directe pour appeler une action sur un appareil. Les commandes sont souvent utilisées pour le contrôle interactif des appareils, comme allumer un ventilateur ou une lampe ou, dans le cas de cette unité, redémarrer l’appareil Azure Sphere.

Les méthodes directes IoT Hub représentent une interaction demande-réponse avec un appareil similaire à un appel HTTP en ce qu’elles réussissent ou échouent immédiatement (après un délai d’attente spécifié par l’utilisateur). Cette approche est utile pour les scénarios où le plan d’action immédiate est différent selon que l’appareil a été en mesure ou non de répondre.

Notes

Plusieurs raisons peuvent vous amener à redémarrer un appareil Azure Sphere à distance. Les certificats d’appareil, les mises à jour du système d’exploitation et les mises à jour d’une application sont traités sur un cycle de 24 heures ou après le redémarrage de l’appareil. Une raison opérationnelle peut vous amener à redémarrer l’appareil pour forcer une mise à jour.

Redémarrage à distance d’un appareil Azure Sphere

Dans IoT Explorer, vous pouvez appeler une commande de méthode directe pour redémarrer l’appareil. Vous devez définir le nombre de secondes que l’appareil doit attendre avant le redémarrage. Azure IoT Hub envoie à l’appareil un message de méthode directe avec une charge utile facultative. L’appareil répond avec un code d’état et un message facultatif indiquant si la commande a réussi ou échoué.

Procédure de redémarrage d’un appareil Azure Sphere IoT Explorer

La procédure suivante montre comment sont utilisées les méthodes directes Azure IoT Explorer et Azure IoT Hub pour le contrôle cloud-à-appareil.

1. Dans Azure IoT Explorer, vous pouvez appeler la commande de méthode directe IoT Hub Redémarrer l’appareil.
2. Azure IoT Hub envoie alors le message de commande de méthode directe à l’appareil.
3. Sur l’appareil Azure Sphere, la fonction RestartDeviceHandler est appelée.
4. L’appareil envoie ensuite un message ReportedRestartUTC de jumeau d’appareil à Azure IoT pour enregistrer l’heure à laquelle l’appareil a été redémarré.
5. La méthode directe répond avec un code d’état HTTP et un message de réponse.
6. L’appareil Azure Sphere est ensuite redémarré.
7. Azure IoT Explorer interroge et affiche la propriété ReportedRestartUTC de l’appareil.

Prise en main des liaisons de méthode directe

Une liaison de méthode directe fait correspondre un nom de commande de méthode directe IoT Hub à une fonction de gestionnaire qui sera appelée pour implémenter l’action.

L’exemple suivant déclare une liaison de méthode directe pour redémarrer l’appareil Azure Sphere. Cette déclaration fait correspondre la commande de méthode directe RestartDevice Azure IoT Hub à une fonction de gestionnaire nommée RestartDeviceHandler.

static LP_DIRECT_METHOD_BINDING dm_restartDevice = {
    .methodName = "RestartDevice",
    .handler = RestartDeviceHandler };

Redémarrage à distance de l’appareil Azure Sphere

Voici l’implémentation de la fonction de gestionnaire RestartDeviceHandler. La fonction de gestionnaire est appelée quand l’appareil reçoit un message de méthode directe nommé RestartDevice provenant d’Azure IoT Hub.

/// <summary>
/// Start Device Power Restart Direct Method 'ResetMethod' integer seconds eg 5
/// </summary>
static LP_DIRECT_METHOD_RESPONSE_CODE RestartDeviceHandler(JSON_Value* json, LP_DIRECT_METHOD_BINDING* directMethodBinding, char** responseMsg)
{
    const size_t responseLen = 60; // Allocate and initialize a response message buffer. The calling function is responsible for the freeing memory
    static struct timespec period;

    *responseMsg = (char*)malloc(responseLen);
    memset(*responseMsg, 0, responseLen);

    if (json_value_get_type(json) != JSONNumber) { return LP_METHOD_FAILED; }

    int seconds = (int)json_value_get_number(json);

    // leave enough time for the device twin dt_reportedRestartUtc to update before restarting the device
    if (seconds > 2 && seconds < 10)
    {
        // Report Device Restart UTC
        lp_deviceTwinReportState(&dt_reportedRestartUtc, lp_getCurrentUtc(msgBuffer, sizeof(msgBuffer))); // LP_TYPE_STRING

        // Create Direct Method Response
        snprintf(*responseMsg, responseLen, "%s called. Restart in %d seconds", directMethodBinding->methodName, seconds);

        // Set One Shot LP_TIMER
        period = (struct timespec){ .tv_sec = seconds, .tv_nsec = 0 };
        lp_timerOneShotSet(&restartDeviceOneShotTimer, &period);

        return LP_METHOD_SUCCEEDED;
    }
    else
    {
        snprintf(*responseMsg, responseLen, "%s called. Restart Failed. Seconds out of range: %d", directMethodBinding->methodName, seconds);
        return LP_METHOD_FAILED;
    }
}

Fonctionnalité PowerControls d’Azure Sphere

La fonction RestartDeviceHandler configure un minuteur ponctuel qui appelle la fonction DelayRestartDeviceTimerHandler après la période de redémarrage spécifiée, mesurée en secondes. Dans la fonction DelayRestartDeviceTimerHandler, un appel est effectué à l’API PowerManagement_ForceSystemReboot. L’API PowerManagement_ForceSystemReboot nécessite que la fonctionnalité PowerControls soit déclarée dans le fichier app_manifest.json.

"PowerControls": [
    "ForceReboot"
]

Comment les méthodes directes sont mappées aux gestionnaires

Toutes les liaisons de méthode directe déclarées doivent être ajoutées par référence au tableau directMethodBindingSet. Quand l’appareil reçoit un message de méthode directe en provenance d’Azure IoT Hub, un nom methodName correspondant dans le tableau directMethodBindingSet est recherché dans le message. Si une correspondance est trouvée, la fonction de gestionnaire correspondante est appelée.

LP_DIRECT_METHOD_BINDING* directMethodBindingSet[] = { &dm_restartDevice };

Ouverture de l’ensemble de liaisons de méthode directe

L’ensemble de liaisons de méthode directe est initialisé dans la fonction InitPeripheralsAndHandlers de main.c.

lp_directMethodSetOpen(directMethodBindingSet, NELEMS(directMethodBindingSet));

Fermeture de l’ensemble de liaisons de méthode directe

L’ensemble de liaisons de méthode directe est fermé dans la fonction ClosePeripheralsAndHandlers de main.c.

lp_directMethodSetClose();

Continuer