Como reiniciar remotamente o Azure Sphere com os métodos diretos do Azure IoT

10 minutos

Nesta unidade, você aprenderá a reiniciar remotamente um Azure Sphere do Azure IoT Central.

Entender os comandos do IoT Central

O Azure IoT Central usa comandos para invocar uma ação em um dispositivo. Frequentemente, os comandos são usados para o controle interativo de dispositivos, como ligar um ventilador, acender uma luz ou, no caso desta unidade, reiniciar o Azure Sphere.

O IoT Central é baseado no Hub IoT do Azure e envia comandos a um dispositivo usando métodos diretos do Hub IoT. Os métodos diretos do Hub IoT representam uma interação de solicitação e resposta com um dispositivo semelhante a uma chamada HTTP, no sentido em que são bem-sucedidas ou falham imediatamente (após um tempo limite especificado pelo usuário). Essa abordagem é útil para cenários em que o curso de ação imediata é diferente dependendo se o dispositivo foi capaz de responder.

Observação

Há vários motivos pelos quais você pode precisar reiniciar remotamente um Azure Sphere. Certificados de dispositivo, atualizações do SO e atualizações de aplicativos são concluídos em um ciclo de 24 horas ou após a reinicialização do dispositivo. Você pode ter um motivo operacional pelo qual precisa reiniciar o dispositivo para forçar uma atualização.

Reinicialização remota de um Azure Sphere

Na guia de comandos do dispositivo do IoT Central, você pode invocar o comando para reiniciar o dispositivo. Você precisa definir o número de segundos que o dispositivo aguardará antes de reiniciar. O Azure IoT Central solicita que o Hub IoT do Azure envie uma mensagem de método direto com uma carga opcional para o dispositivo. O dispositivo responde com um código de status e, opcionalmente, uma mensagem indicando se o comando foi bem-sucedido ou falhou. O IoT Central pode exibir o histórico de comandos que foram invocados no Azure Sphere.

The illustration shows a device twin configuration pattern.

Etapas para reiniciar um Azure Sphere no IoT Central

As etapas a seguir descrevem como um comando do Azure IoT Central usa os métodos diretos do Hub IoT do Azure para o controle de transferências de nuvem para dispositivo.

Na guia de comandos do dispositivo do Azure IoT Central, você invoca o comando Reiniciar Dispositivo. O IoT Central solicita que o Hub IoT envie uma mensagem de método direto para o dispositivo.
No Azure Sphere, a função RestartDeviceHandler é chamada.
Em seguida, o dispositivo envia uma mensagem ReportedRestartUTC de dispositivo gêmeo para o Azure IoT para registrar a hora em que o dispositivo foi reiniciado.
O método direto responde com um código de status HTTP e uma mensagem de resposta.
Em seguida, o Azure Sphere é reiniciado.
O Azure IoT Central consulta e exibe a propriedade ReportedRestartUTC do dispositivo.

Introdução às associações de método direto

Lembre-se de que os comandos do Azure IoT Central são implementados usando os métodos diretos do Hub IoT do Azure. Uma associação de método direto mapeia o nome de um método direto com uma função de manipulador que será chamada para implementar a ação.

O exemplo a seguir declara uma associação de método direto para reiniciar o Azure Sphere. Essa declaração mapeia o comando RestartDevice do Azure IoT Central com uma função de manipulador chamada RestartDeviceHandler.

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

Reinicialização remota do Azure Sphere

A seguir está a implementação da função de manipulador RestartDeviceHandler. A função de manipulador é chamada quando o dispositivo recebe uma mensagem de método direto chamada RestartDevice do Hub IoT do Azure.

/// <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;
    }
}

Capacidade PowerControls do Azure Sphere

A função RestartDeviceHandler configura um temporizador de uso único que invoca a função DelayRestartDeviceTimerHandler após o período de reinicialização especificado, medido em segundos. Na função DelayRestartDeviceTimerHandler, é feita uma chamada à API PowerManagement_ForceSystemReboot. A API PowerManagement_ForceSystemReboot requer que a capacidade PowerControls seja declarada no arquivo app_manifest.json.

"PowerControls": [
    "ForceReboot"
]

Como os métodos diretos são mapeados para os manipuladores

Todas as associações de método direto declaradas precisam ser adicionadas por referência à matriz directMethodBindingSet. Quando uma mensagem de método direto é recebida pelo dispositivo do Hub IoT do Azure, é verificado um nome de methodName correspondente na matriz directMethodBindingSet. Quando uma correspondência é encontrada, a função de manipulador correspondente é chamada.

LP_DIRECT_METHOD_BINDING* directMethodBindingSet[] = { &dm_restartDevice };

Abrir o conjunto de associação de método direto

O conjunto de associação de método direto é inicializado na função InitPeripheralsAndHandlers em main.c.

lp_directMethodSetOpen(directMethodBindingSet, NELEMS(directMethodBindingSet));

Fechar o conjunto de associação de método direto

O conjuntos de associação é fechado na função ClosePeripheralsAndHandlers em main.c.

lp_directMethodSetClose();

Comandos do Azure IoT Central

Os comandos do IoT Central são definidos na interface do modelo de dispositivo. Neste exemplo, o tipo de esquema do comando RestartDevice é Inteiro. A carga do método direto é um inteiro que define o número de segundos antes de reiniciar o dispositivo. O nome do comando deve corresponder à declaração ae associação de método direto RestartDevice no Azure Sphere.

The illustration shows a device template interface.

Continuar