Tutorial: Provisionar seu edifício e monitorar as condições de funcionamento com a Prévia dos Azure Digital Twins

2020-01-10

Importante

Uma nova versão do serviço dos Gêmeos Digitais do Azure foi lançada. À luz das funcionalidades expandidas do novo serviço, o serviço original dos Gêmeos Digitais do Azure (descrito neste conjunto de documentação) foi desativado.

Para consultar a documentação ativa do serviço Gêmeos Digitais do Azure, visite a Documentação dos Gêmeos Digitais do Azure.

Este tutorial demonstra como usar a Versão Prévia dos Gêmeos Digitais do Azure para monitorar seus espaços para condições de temperatura e nível de conforto desejados. Depois de configurar o seu edifício de exemplo, você poderá provisionar seu prédio e executar funções personalizadas nos dados dos sensores usando as etapas deste tutorial.

Neste tutorial, você aprenderá como:

Defina condições a serem monitoradas.
Crie uma UDF (função definida pelo usuário).
Simular dados do sensor.
Obter resultados de uma função definida pelo usuário.

Pré-requisitos

Este tutorial pressupõe que você concluiu a configuração dos Gêmeos Digitais do Azure. Antes de continuar, verifique se você tem:

Uma conta do Azure.
Uma instância dos Gêmeos Digitais em funcionamento.
Os exemplos de C# dos Gêmeos Digitais foram baixados e extraídos em seu computador de trabalho.
SDK do .NET Core versão 2.1.403 ou posterior em seu computador de desenvolvimento para compilar e executar o exemplo. Execute dotnet --version para verificar se a versão certa está instalada.
Visual Studio Code para explorar o código de exemplo.

Dica

Use um nome de instância exclusivo dos Gêmeos Digitais se você estiver provisionando uma nova instância.

Definir condições para monitorar

Você pode definir um conjunto de condições específicas para monitorar nos dados do dispositivo ou do sensor, chamado correspondentes. Em seguida, você pode definir funções chamadas funções definidas pelo usuário. As funções definidas pelo usuário executam lógica personalizada em dados provenientes de seus espaços e dispositivos, quando ocorrem as condições especificadas pelos correspondentes. Para obter mais informações, leia Processamento de dados e funções definidas pelo usuário.

No projeto de exemplo occupancy-quickstart, abra o arquivo src\actions\provisionSample.yaml no Visual Studio Code. Observe a seção que começa com os comparadores . Cada entrada sob este tipo cria um correspondente com o nome especificado . O correspondente monitorará um sensor do tipo dataTypeValue. Observe como ele se relaciona ao espaço chamado Sala de Foco A1, que tem um nó de dispositivos que contém alguns sensores. Para provisionar um correspondente que acompanhará um desses sensores, verifique se seu dataTypeValue corresponde ao dataTypedo sensor.

Adicione o seguinte comparador abaixo dos comparadores existentes. Verifique se as teclas estão alinhadas e se os espaços não são substituídos por tabulações. Essas linhas também estão presentes como linhas comentadas no arquivo de provisionSample.yaml. Você pode descomentá-los removendo o caractere # na frente de cada linha.

      - name: Matcher Temperature
        dataTypeValue: Temperature

Esse correspondente acompanhará o sensor SAMPLE_SENSOR_TEMPERATURE que você adicionou no primeiro tutorial .

Criar uma função definida pelo usuário

Você pode usar funções definidas pelo usuário para personalizar o processamento dos dados do sensor. Trata-se de códigos JavaScript personalizados que podem ser executados na sua instância do Azure Digital Twins, quando condições específicas, conforme descrito pelos matchers, ocorrem. Você pode criar correspondências e funções definidas pelo usuário para cada sensor que deseja monitorar. Para obter mais informações, leia Processamento de dados e funções definidas pelo usuário.

No arquivo provisionSample.yaml de exemplo, procure uma seção que comece com o tipo userdefinedfunctions. Esta seção provisiona uma função definida pelo usuário com um determinado Nome. Essa UDF atua na lista de comparadores em matcherNames. Observe como você pode fornecer seu próprio arquivo JavaScript para o UDF como o script .

Observe também a seção denominada atribuições de funções. Ele atribui o papel de Administrador de Espaço à função definida pelo usuário. Essa função permite que ela acesse os eventos provenientes de qualquer um dos espaços provisionados.

Configure a UDF para incluir o correspondenter de temperatura adicionando ou descompactando a seguinte linha no nó matcherNames do arquivo provisionSample.yaml:
```
        - Matcher Temperature
```

Abra o arquivo src\actions\userDefinedFunctions\availability.js em seu editor. Esse é o arquivo referenciado no script elemento de provisionSample.yaml. A função definida pelo usuário neste arquivo procura condições quando nenhum movimento é detectado na sala e os níveis de dióxido de carbono estão abaixo de 1.000 ppm.

Modifique o arquivo JavaScript para monitorar a temperatura e outras condições. Adicione as seguintes linhas de código para procurar condições quando nenhum movimento é detectado na sala, os níveis de dióxido de carbono estão abaixo de 1.000 ppm, e a temperatura está abaixo de 78 graus Fahrenheit.

Observação

Esta seção modifica o arquivo src\actions\userDefinedFunctions\availability.js para que você possa aprender em detalhes uma maneira de escrever uma função definida pelo usuário. No entanto, você pode optar por usar diretamente o arquivo src\actions\userDefinedFunctions\availabilityForTutorial.js em sua configuração. Este arquivo tem todas as alterações necessárias para este tutorial. Se você usar esse arquivo, certifique-se de usar o nome correto do arquivo para a chave do script em src\actions\provisionSample.yaml.

um. Na parte superior do arquivo, adicione as seguintes linhas para a temperatura abaixo do comentário // Add your sensor type here:

    var temperatureType = "Temperature";
    var temperatureThreshold = 78;

b. Adicione as seguintes linhas após a instrução que define var motionSensor, abaixo do comentário // Add your sensor variable here:

   var temperatureSensor = otherSensors.find(function(element) {
       return element.DataType === temperatureType;
   });

c. Adicione a seguinte linha após a instrução que define var carbonDioxideValue, abaixo do comentário // Add your sensor latest value here:

    var temperatureValue = getFloatValue(temperatureSensor.Value().Value);

d. Remova as seguintes linhas de código abaixo do comentário // Modify this line to monitor your sensor value:

   if(carbonDioxideValue === null || motionValue === null) {
       sendNotification(telemetry.SensorId, "Sensor", "Error: Carbon dioxide or motion are null, returning");
       return;
   }

Substitua-as pelas seguintes linhas:

    if(carbonDioxideValue === null || motionValue === null || temperatureValue === null){
        sendNotification(telemetry.SensorId, "Sensor", "Error: Carbon dioxide, motion, or temperature are null, returning");
        return;
    }

e. Remova as seguintes linhas de código abaixo do comentário // Modify these lines as per your sensor:

    var availableFresh = "Room is available and air is fresh";
    var noAvailableOrFresh = "Room is not available or air quality is poor";

Substitua-as pelas seguintes linhas:

    var alert = "Room with fresh air and comfortable temperature is available.";
    var noAlert = "Either room is occupied, or working conditions are not right.";

f. Remova o seguinte bloco de código if-else após o comentário // Modify this code block for your sensor:

    // If carbonDioxide less than threshold and no presence in the room => log, notify and set parent space computed value
    if(carbonDioxideValue < carbonDioxideThreshold && !presence) {
        log(`${availableFresh}. Carbon Dioxide: ${carbonDioxideValue}. Presence: ${presence}.`);
        setSpaceValue(parentSpace.Id, spaceAvailFresh, availableFresh);
    }
    else {
        log(`${noAvailableOrFresh}. Carbon Dioxide: ${carbonDioxideValue}. Presence: ${presence}.`);
        setSpaceValue(parentSpace.Id, spaceAvailFresh, noAvailableOrFresh);

        // Set up custom notification for poor air quality
        parentSpace.Notify(JSON.stringify(noAvailableOrFresh));
    }

E substitua-o pelo seguinte bloco if-else:

    // If sensor values are within range and room is available
    if(carbonDioxideValue < carbonDioxideThreshold && temperatureValue < temperatureThreshold && !presence) {
        log(`${alert}. Carbon Dioxide: ${carbonDioxideValue}. Temperature: ${temperatureValue}. Presence: ${presence}.`);

        // log, notify and set parent space computed value
        setSpaceValue(parentSpace.Id, spaceAvailFresh, alert);

        // Set up notification for this alert
        parentSpace.Notify(JSON.stringify(alert));
    }
    else {
        log(`${noAlert}. Carbon Dioxide: ${carbonDioxideValue}. Temperature: ${temperatureValue}. Presence: ${presence}.`);

        // log, notify and set parent space computed value
        setSpaceValue(parentSpace.Id, spaceAvailFresh, noAlert);
    }

A UDF modificada procurará uma condição em que um cômodo esteja disponível e onde o dióxido de carbono e a temperatura estejam dentro dos limites toleráveis. Ele gerará uma notificação com a instrução parentSpace.Notify(JSON.stringify(alert)); quando essa condição for atendida. Ele definirá o valor do espaço monitorado, independentemente de a condição ser atendida, com a mensagem correspondente.

g. Salve o arquivo.

Abra uma janela de comando e vá para a pasta occupancy-quickstart\src. Execute o seguinte comando para provisionar o grafo de inteligência espacial e a função definida pelo usuário:
```
dotnet run ProvisionSample
```
Importante

Para impedir o acesso não autorizado à API de Gerenciamento dos Gêmeos Digitais, o aplicativo de início rápido de ocupação requer que você entre com suas credenciais de conta do Azure. Ele salva suas credenciais por um breve período, então você pode não precisar fazer login toda vez que executá-lo. A primeira vez que este programa é executado e, quando suas credenciais salvas expirarem, o aplicativo direciona você para uma página de login e fornece um código específico da sessão para inserir nessa página. Siga os prompts para entrar com sua conta do Azure.
Depois que sua conta for autenticada, o aplicativo começará a criar um grafo espacial de exemplo, conforme configurado em provisionSample.yaml. Aguarde até que o provisionamento seja concluído. Levará alguns minutos. Depois disso, observe as mensagens na janela de comando e observe como o grafo espacial é criado. Observe como o aplicativo cria um hub IoT no nó raiz ou no Venue.
Na janela de comando, copie o valor de ConnectionString da saída, na seção Devices, para a área de transferência. Você precisará desse valor para simular a conexão do dispositivo na próxima seção.

Dica

Se você receber uma mensagem de erro semelhante a "A operação de E/S foi anulada devido a uma saída de thread ou uma solicitação de aplicativo" no meio do provisionamento, tente executar o comando novamente. Isso pode acontecer se o cliente HTTP sofrer um tempo de espera devido a um problema de rede.

Simular dados do sensor

Nesta seção, você usará o projeto chamado device-connectivity no exemplo. Você simulará dados do sensor para detectar movimento, temperatura e dióxido de carbono. Esse projeto gera valores aleatórios para os sensores e os envia para o hub IoT usando a cadeia de conexão do dispositivo.

Em uma janela de comando separada, vá para o exemplo dos Gêmeos Digitais do Azure e, em seguida, para a pasta de conectividade do dispositivo .
Execute este comando para garantir que as dependências do projeto estejam corretas:
```
dotnet restore
```
Abra o arquivo appsettings.json em seu editor e edite os seguintes valores:

a. DeviceConnectionString: atribua o valor de ConnectionString na janela de saída da seção anterior. Copie essa cadeia de caracteres completamente, entre aspas, para que o simulador possa se conectar corretamente com o Hub IoT.

b. HardwareId dentro da matriz de sensores: Porque você está simulando eventos provisionados na sua instância de Azure Digital Twins, a ID de hardware e os nomes dos sensores nesse arquivo devem corresponder ao nó sensors do arquivo provisionSample.yaml.

Adicione uma nova entrada para o sensor de temperatura. O nó Sensores no appsettings.json deve ser semelhante ao seguinte:
```
"Sensors": [{
  "DataType": "Motion",
  "HardwareId": "SAMPLE_SENSOR_MOTION"
},{
  "DataType": "CarbonDioxide",
  "HardwareId": "SAMPLE_SENSOR_CARBONDIOXIDE"
},{
  "DataType": "Temperature",
  "HardwareId": "SAMPLE_SENSOR_TEMPERATURE"
}]
```
Execute este comando para começar a simular eventos do dispositivo para temperatura, movimento e dióxido de carbono:
```
dotnet run
```
Observação

Como o exemplo de simulação não se comunica diretamente com sua instância dos Gêmeos Digitais, ele não exige que você se autentique.

Obter resultados da função definida pelo usuário

A função definida pelo usuário é executada sempre que sua instância recebe dados de dispositivo e sensor. Esta seção consulta sua instância dos Gêmeos Digitais do Azure para obter os resultados da função definida pelo usuário. Você será notificado quase em tempo real, quando uma sala estiver disponível, que o ar está fresco e a temperatura está certa.

Abra a janela de comando usada para provisionar o exemplo ou uma nova janela de comando e vá para a pasta occupancy-quickstart\src do exemplo novamente.
Execute o seguinte comando e entre quando solicitado:
```
dotnet run GetAvailableAndFreshSpaces
```

A janela de saída mostra como a função definida pelo usuário é executada e intercepta eventos da simulação do dispositivo.

saída

Se a condição monitorada for atendida, a função definida pelo usuário definirá o valor do espaço com a mensagem relevante, como vimos anteriormente . A função GetAvailableAndFreshSpaces imprime a mensagem no console.

Limpar os recursos

Se você quiser parar de explorar os Gêmeos Digitais do Azure neste momento, fique à vontade para excluir os recursos criados neste tutorial:

No menu à esquerda do portal do Azure, selecione Todos os recursos, selecione o grupo de recursos dos Gêmeos Digitais e depois selecione Excluir.

Dica

Se você tiver problemas para excluir sua instância dos Gêmeos Digitais, uma atualização de serviço foi implementada com a correção. Por favor, tente excluir sua instância novamente.
Se necessário, exclua os aplicativos de exemplo em seu computador de trabalho.

Próximas etapas

Agora que você provisionou seus espaços e criou uma estrutura para disparar notificações personalizadas, acesse qualquer um dos seguintes tutoriais:

Tutorial: Receber notificações de seus espaços dos Gêmeos Digitais do Azure usando Logic Apps

Tutorial: Visualizar e analisar eventos de seus espaços dos Gêmeos Digitais do Azure usando o Time Series Insights

Compartilhar via