Tutorial: Aprovisionamiento y supervisión de las condiciones de trabajo con la versión preliminar de Azure Digital Twins

Artículo
01/10/2020

Importante

Se ha publicado una nueva versión del servicio Azure Digital Twins. A la luz de las funcionalidades ampliadas del nuevo servicio, se ha retirado el servicio Azure Digital Twins original (descrito en este conjunto de documentación).

Para ver la documentación del nuevo servicio, visite la documentación activa de Azure Digital Twins.

En este tutorial se muestra cómo usar la versión preliminar de Azure Digital Twins para supervisar las condiciones de temperatura y el nivel de comodidad deseados en los distintos espacios. Una vez que haya configurado el edificio de ejemplo, use los pasos de este tutorial para aprovisionarlo y ejecutar funciones personalizadas en los datos de los sensores.

En este tutorial, aprenderá a:

Definir las condiciones que se van a supervisar
Crear una función definida por el usuario (UDF)
Simular los datos de los sensores
Obtener los resultados de una función definida por el usuario

Requisitos previos

En este tutorial se supone que ha terminado de configurar Azure Digital Twins. Antes de continuar, asegúrese de que:

Una cuenta de Azure.
Hay una instancia de Digital Twins en ejecución.
Los ejemplos en C# de Digital Twins se han descargado y extraído en su equipo de trabajo.
Versión 2.1.403 del SDK de .NET Core, o cualquier versión superior, en la máquina de desarrollo para compilar y ejecutar el ejemplo. Ejecute dotnet --version para comprobar que está instalada la versión correcta.
Tiene Visual Studio Code para explorar el código de ejemplo.

Sugerencia

Use un nombre de instancia de Digital Twins único si está aprovisionando una nueva instancia.

Definición de las condiciones que se van a supervisar

Puede definir un conjunto de condiciones específicas para supervisar en los datos del dispositivo o del sensor, llamado buscador de coincidencias. Luego, puede definir funciones llamadas funciones definidas por el usuario. Las funciones definidas por el usuario ejecutan lógica personalizada en los datos que proceden de los espacios y los dispositivos, cuando se producen las condiciones especificadas por los buscadores de coincidencias. Para más información, lea Procesamiento de datos y funciones definidas por el usuario.

En el proyecto de ejemplo occupancy-quickstart, abra el archivo src\actions\provisionSample.yaml en Visual Studio Code. Observe la sección que comienza con el tipo matchers. Cada entrada con este tipo crea un buscador de coincidencias con el nombre especificado. El buscador de coincidencias supervisará un sensor de tipo dataTypeValue. Observe cómo se relaciona con el espacio denominado Focus Room A1, que tiene un nodo devices, que contiene algunos sensores. Para aprovisionar un buscador de coincidencias que realice el seguimiento de uno de estos sensores, asegúrese de que su valor de dataTypeValue coincida con el valor de dataType del sensor.

Agregue el siguiente buscador de coincidencias debajo de los buscadores de coincidencias existentes. Asegúrese de que las claves estén alineadas y que los espacios no se reemplacen por pestañas. Estas líneas también están presentes en el archivo provisionSample.yaml como líneas con comentarios. Para quitarles la marca de comentario, elimine el carácter # delante de cada línea.

      - name: Matcher Temperature
        dataTypeValue: Temperature

Este buscador de coincidencias realizará el seguimiento del sensor SAMPLE_SENSOR_TEMPERATURE que agregó en el primer tutorial.

Creación de una función definida por el usuario

Puede usar funciones definidas por el usuario para personalizar el procesamiento de los datos de los sensores. Estas funciones son código JavaScript personalizado que se puede ejecutar en la instancia de Azure Digital Twins cuando se producen determinadas condiciones que describen los buscadores de coincidencias. Se pueden crear buscadores de coincidencias y funciones definidas por el usuario para todos los sensores que quiera supervisar. Para más información, lea Procesamiento de datos y funciones definidas por el usuario.

En el archivo provisionSample.yaml de ejemplo, busque una sección que comience por el tipo userdefinedfunctions. En esta sección se proporciona una función definida por el usuario con un nombre determinado. Dicha función actúa sobre la lista de buscadores de coincidencias en matcherNames. Tenga en cuenta que puede especificar su propio archivo de JavaScript para la UDF como script.

Fíjese también en la sección denominada roleassignments. Esta sección asigna el rol Administrador de espacios a la función definida por el usuario y le permite acceder a los eventos que proceden de cualquiera de los espacios aprovisionados.

Configure la UDF para incluir el buscador de coincidencias de temperatura agregando o quitando la marca de comentario de la siguiente línea en el matcherNames nodo del archivo provisionSample.yaml :
```
        - Matcher Temperature
```

Abra el archivo src\actions\userDefinedFunctions\availability.js en el editor. Este es el archivo al que se hace referencia en el elemento script de provisionSample.yaml. La función definida por el usuario en este archivo busca condiciones cuando no se detecta movimiento en la sala, así como cuando los niveles de dióxido de carbono están por debajo de 1000 ppm.

Modifique el archivo de JavaScript para supervisar la temperatura y otras condiciones. Agregue las siguientes líneas de código para buscar condiciones cuando no se detecte movimiento en la sala, los niveles de dióxido de carbono no lleguen a 1000 ppm y la temperatura sea inferior a 78 ºF.

Nota

En esta sección se modifica el archivo src\actions\userDefinedFunctions\availability.js para explicar detalladamente una manera de escribir una función definida por el usuario. Sin embargo, puede elegir usar directamente el archivo src\actions\userDefinedFunctions\availabilityForTutorial.js en su configuración. Dicho archivo contiene todos los cambios necesarios para este tutorial. Si lo usa, asegúrese de utilizar el nombre de archivo correcto para la clave del script en src\actions\provisionSample.yaml.

a. Al principio del archivo, agregue las siguientes líneas para la temperatura debajo del comentario // Add your sensor type here:

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

b. Agregue las líneas siguientes después de la instrucción que define var motionSensor, debajo del comentario // Add your sensor variable here:

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

c. Agregue la línea siguiente después de la instrucción que define var carbonDioxideValue, debajo del comentario // Add your sensor latest value here:

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

d. Quite las siguientes líneas de código de debajo del comentario // 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;
   }

Reemplácelas por estas:

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

e. Quite las siguientes líneas de código de debajo del comentario // 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";

Reemplácelas por estas:

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

f. Quite el siguiente bloque de código if-else después del comentario // 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));
    }

Y sustitúyala por el siguiente bloque 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);
    }

La UDF modificada buscará una condición en la que una sala esté disponible y tenga el dióxido de carbono y la temperatura dentro de unos límites tolerables. Cuando dicha condición se cumpla, generará una notificación con la instrucción parentSpace.Notify(JSON.stringify(alert));. Establece el valor del espacio supervisado, independientemente de si se cumple la condición, con el mensaje correspondiente.

g. Guarde el archivo.

Abra una ventana de comandos y vaya a la carpeta occupancy-quickstart\src. Ejecute el siguiente comando para aprovisionar el grafo de inteligencia espacial y la función definida por el usuario:
```
dotnet run ProvisionSample
```
Importante

Para evitar el acceso no autorizado a Management API de Digital Twins, la aplicación occupancy-quickstart le exige que inicie sesión con las credenciales de su cuenta de Azure. Como las credenciales se guardan durante un breve periodo, es posible que no tenga que iniciar sesión cada vez que lo ejecute. La primera vez que se ejecuta este programa y, luego, cuándo expiran las credenciales guardadas, la aplicación le dirige a una página de inicio de sesión y le proporciona un código específico de la sesión para entrar en la página. Siga las indicaciones para iniciar sesión con su cuenta de Azure.
Después de que se autentica la cuenta, la aplicación empieza a crear un grafo espacial de ejemplo como se ha configurado en provisionSample.yaml. Espere hasta que finalice el aprovisionamiento. Esta operación puede tardar unos minutos. Cuando se haya completado, observe los mensajes de la ventana de comandos y vea cómo se crea el grafo espacial. Observe cómo la aplicación crea una instancia de IoT Hub en el nodo raíz o en Venue.
En la salida de la ventana de comandos, copie el valor de ConnectionString, que aparece en la sección Devices, en el Portapapeles. Necesitará este valor para simular la conexión del dispositivo en la sección siguiente.

Sugerencia

Si recibe un mensaje de error que dice algo como que la operación de E/S se anuló debido a una salida de subproceso o una solicitud de aplicación en medio del aprovisionamiento, pruebe a volver a ejecutar el comando. Esto puede ocurrir si el cliente HTTP ha agotado el tiempo de espera debido a algún problema en la red.

Simulación de los datos de los sensores

En esta sección, usará el proyecto denominado device-connectivity en el ejemplo. Simulará los datos de los sensores para la detección de movimiento, temperatura y dióxido de carbono. Este proyecto genera valores aleatorios para los sensores y los envía a la instancia de IoT Hub mediante la cadena de conexión del dispositivo.

En otra ventana de comandos, vaya al ejemplo de Azure Digital Twins y, después, a la carpeta device-connectivity.
Ejecute este comando para asegurarse de que las dependencias del proyecto son correctas:
```
dotnet restore
```
Abra el archivo appSettings.json en el editor y edite los valores siguientes:

a. DeviceConnectionString: asigne el valor de ConnectionString en la ventana de salida de la sección anterior. Copie esta cadena completamente, entre comillas, para que el simulador se conecte correctamente con la instancia de IoT Hub.

b. HardwareId dentro de la matriz Sensors : dado que está simulando eventos de sensores aprovisionados en la instancia de Azure Digital Twins, el identificador de hardware y los nombres de los sensores de este archivo deben coincidir con el sensors nodo del archivo provisionSample.yaml .

Agregue una nueva entrada para el sensor de temperatura. El nodo Sensors de appsettings.json debe ser similar al siguiente:
```
"Sensors": [{
  "DataType": "Motion",
  "HardwareId": "SAMPLE_SENSOR_MOTION"
},{
  "DataType": "CarbonDioxide",
  "HardwareId": "SAMPLE_SENSOR_CARBONDIOXIDE"
},{
  "DataType": "Temperature",
  "HardwareId": "SAMPLE_SENSOR_TEMPERATURE"
}]
```
Ejecute este comando para iniciar la simulación de eventos de temperatura, movimiento y dióxido de carbono del de dispositivo:
```
dotnet run
```
Nota

Como el ejemplo de simulación no se comunica directamente con la instancia de Digital Twin, no requiere autenticación.

Obtención de los resultados de la función definida por el usuario

La función definida por el usuario se ejecuta cada vez que una instancia recibe datos del dispositivo y de los sensores. En esta sección se consulta su instancia de Azure Digital Twins para obtener los resultados de la función definida por el usuario. Se le notificará casi en tiempo real cuando una sala está disponible, el aire sea puro y la temperatura, la adecuada.

Abra la ventana de comandos que usó para aprovisionar el ejemplo, o una nueva, y vaya otra vez a la carpeta occupancy-quickstart\src del ejemplo.
Ejecute el comando siguiente e inicie sesión cuando se le solicite:
```
dotnet run GetAvailableAndFreshSpaces
```

La ventana de salida muestra cómo se ejecuta la función definida por el usuario e intercepta los eventos de la simulación de dispositivos.

Si se cumple la condición supervisada, la función definida por el usuario establece el valor del espacio con el mensaje pertinente, como se ha visto anteriormente. La función GetAvailableAndFreshSpaces imprime el mensaje en la consola.

Limpieza de recursos

Si quiere dejar de explorar Azure Digital Twins en este punto, elimine los recursos creados en este tutorial:

En el menú izquierdo de Azure Portal, seleccione Todos los recursos, seleccione el grupo de recurso de Digital Twins y haga clic en Eliminar.

Sugerencia

Si tiene problemas al eliminar una instancia de Digital Twins, se ha incorporado una actualización del servicio con la corrección. Vuelva a intentar eliminar la instancia.
Si es necesario, elimine las aplicaciones de ejemplo en la máquina de trabajo.

Pasos siguientes

Ahora que ha aprovisionado los espacios y ha creado una plataforma para desencadenar notificaciones personalizadas, puede continuar con cualquiera de los siguientes tutoriales:

Tutorial: Recepción de notificaciones de los espacios de Azure Digital Twins mediante Logic Apps

Tutorial: Visualización y análisis de eventos de los espacios de Azure Digital Twins mediante Time Series Insights