Introducción a los dispositivos gemelos

Use el SDK de dispositivo y el SDK de servicio de Azure IoT Hub para desarrollar aplicaciones que controle tareas comunes de dispositivos gemelos. Los dispositivos gemelos son documentos JSON que almacenan información acerca del estado del dispositivo, incluidos metadatos, configuraciones y condiciones. IoT Hub conserva un dispositivo gemelo por cada dispositivo que se conecta a él.

Puede usar dispositivos gemelos para:

• Almacenar metadatos del dispositivo desde el back-end de la solución
• Notificar la información sobre el estado actual, como las funcionalidades y las condiciones disponibles (por ejemplo, el método de conectividad usado) de la aplicación del dispositivo
• Sincronizar el estado de flujos de trabajo de larga duración (como las actualizaciones del firmware y de la configuración) entre la aplicación del dispositivo y la del back-end
• Consultar los metadatos, la configuración o el estado del dispositivo

Para obtener más información sobre los dispositivos gemelos, incluido cuándo usar dispositivos gemelos, consulte Descripción y uso de dispositivos gemelos en IoT Hub.

Nota:

Las características descritas en este artículo solo están disponibles en el nivel estándar de IoT Hub. Para obtener más información sobre los niveles Básico y Estándar o Gratis de IoT Hub, consulte Elección del nivel adecuado de IoT Hub para la solución.

En este artículo se muestra cómo desarrollar dos tipos de aplicaciones:

• Las aplicaciones de dispositivo pueden controlar las solicitudes para actualizar las propiedades deseadas y responder con cambios en las propiedades notificadas.
• Las aplicaciones de servicio pueden actualizar etiquetas de dispositivo gemelo, establecer nuevas propiedades deseadas y consultar dispositivos basados en valores de dispositivo gemelo.

Nota:

Este artículo está diseñado para complementar los ejemplos del SDK de Azure IoT a los que se hace referencia desde este artículo. Puede usar las herramientas del SDK para compilar aplicaciones de dispositivo y back-end.

Requisitos previos

• Una instancia de IoT Hub. Algunas llamadas al SDK requieren la cadena de conexión principal de IoT Hub, así que anótela.

• Un dispositivo registrado. Algunas llamadas al SDK requieren la cadena de conexión principal del dispositivo, así que anótela.

• Obtenga la cadena de conexión del servicio IoT Hub

  En este artículo, se crea un servicio back-end que agrega propiedades deseadas a un dispositivo gemelo y luego consulta el registro de identidades para buscar todos los dispositivos con propiedades notificadas que se han actualizado en consecuencia. El servicio necesita el permiso Conectar al servicio para modificar las propiedades deseadas de un dispositivo gemelo y el permiso Lectura del Registro para consultar el registro de identidades. No hay ninguna directiva de acceso compartido predeterminada que contenga solo estos dos permisos, por lo que tendrá que crearla.

  Para crear una directiva de acceso compartido que conceda los permisos Conexión del servicio y Lectura del Registro, y obtenga una cadena de conexión para esta directiva, siga estos pasos:

  1. En Azure Portal, seleccione Grupos de recursos. Seleccione el grupo de recursos donde se encuentra el centro y, a continuación, seleccione el centro en la lista de recursos.

  2. En el panel de la izquierda del centro, seleccione Directivas de acceso compartido.

  3. En el menú superior situado encima de la lista de directivas, seleccione Agregar una directiva de acceso compartida.

  4. En el panelAgregar una directiva de acceso compartida de la derecha, escriba un nombre descriptivo para la directiva, por ejemplo “serviceAndRegistryRead”. En Permisos, seleccione Lectura del Registro y Conexión del servicio, y después seleccione Agregar.

  5. Seleccione la directiva nueva en la lista de directivas.

  6. Seleccione el icono de copia para Cadena de conexión principal y guarde el valor.

  Para obtener más información sobre las directivas y permisos de acceso compartido de IoT Hub, consulte Control del acceso a IoT Hub con firmas de acceso compartido.

• Si la aplicación usa el protocolo MQTT, asegúrese de que el puerto 8883 esté abierto en el firewall. El protocolo MQTT se comunica a través del puerto 8883. Este puerto puede estar bloqueado en algunos entornos de red corporativos y educativos. Para más información y para saber cómo solucionar este problema, consulte el artículo sobre la conexión a IoT Hub (MQTT).

• Requisitos del SDK de lenguaje:

  • SDK de .NET : requiere Visual Studio.
  • Python SDK - Se recomienda usar la versión de Python 3.7 o posterior. Asegúrese de usar la instalación de 32 bits o 64 bits en función del programa de instalación. Cuando se le solicite durante la instalación, asegúrese de agregar Python a la variable de entorno específica de la plataforma.
  • Java: requiere el Java SE Development Kit. Asegúrese de seleccionar Java 8 en Soporte técnico a largo plazo para obtener descargas de JDK 8.
  • Node.js: requiere Node.js versión 10.0.x o posterior.

Información general

En este artículo se describe cómo usar el SDK de Azure IoT para .NET para crear código de aplicación de servicio de dispositivo y back-end para dispositivos gemelos.

Creación de una aplicación de dispositivo

Las aplicaciones de dispositivo pueden leer y escribir propiedades notificadas de gemelos y recibir notificaciones de los cambios de propiedad de gemelos deseados establecidos por una aplicación de back-end o IoT Hub.

En esta sección se describe cómo usar el código de aplicación de dispositivo para:

• Recuperar un dispositivo gemelo y examinar las propiedades notificadas
• Actualización de las propiedades notificadas de dispositivos gemelos
• Creación de un controlador de devolución de llamada de actualización de propiedades deseada

Agregar paquete NuGet de dispositivo

Las aplicaciones cliente de dispositivo escritas en C# requieren el paquete NuGet Microsoft.Azure.Devices.Client.

Conectarse a un dispositivo

La clase DeviceClient expone todos los métodos necesarios para interactuar con dispositivos gemelos desde el dispositivo.

Conéctese al dispositivo mediante el método CreateFromConnectionString junto con la cadena de conexión del dispositivo y el protocolo de transporte de conexión.

El parámetro de protocolo de transporte CreateFromConnectionString TransportType admite los siguientes protocolos de transporte:

• Mqtt
• Mqtt_WebSocket_Only
• Mqtt_Tcp_Only
• Amqp
• Amqp_WebSocket_Only
• Amqp_Tcp_Only

El protocolo Http1 no se admite para las actualizaciones de dispositivos gemelos.

Este ejemplo se conecta a un dispositivo mediante el protocolo de transporte Mqtt.

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;

static string DeviceConnectionString = "{IoT hub device connection string}";
static _deviceClient = null;
_deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

Recuperación de un dispositivo gemelo y examen de propiedades

Llame a GetTwinAsync para recuperar las propiedades del dispositivo gemelo actual. Hay muchas propiedades del objeto Gemelo que puede utilizar para acceder a áreas específicas de los JSON Twin incluyendo Properties, Status, Tags, y Version.

En este ejemplo se recuperan las propiedades del dispositivo gemelo y se imprimen los valores del gemelo en formato JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _deviceClient.GetTwinAsync();
Console.WriteLine("\tInitial twin value received:");
Console.WriteLine($"\t{twin.ToJson()}");

Actualización de las propiedades notificadas de dispositivos gemelos

Para actualizar una propiedad notificada de gemelo:

1. Crear un objeto de TwinCollection para la actualización de la propiedad notificada
2. Actualizar una o varias propiedades notificadas dentro del objeto TwinCollection
3. Use UpdateReportedPropertiesAsync para insertar los cambios de propiedad notificados en el servicio IoT Hub

Por ejemplo:

try
{
Console.WriteLine("Sending sample start time as reported property");
TwinCollection reportedProperties = new TwinCollection();
reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

Creación de un controlador de devolución de llamada de actualización de propiedades deseada

Cree un controlador de devolución de llamada de actualización de propiedad deseada que se ejecute cuando se cambia una propiedad deseada en el dispositivo gemelo pasando el nombre del método del controlador de devolución de llamada a SetDesiredPropertyUpdateCallbackAsync.

Por ejemplo, esta llamada configura el sistema para notificar a un método denominadoOnDesiredPropertyChangedAsync cada vez que se cambia una propiedad deseada.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Las propiedades del gemelo se pasan al método de devolución de llamada como TwinCollection y se pueden examinar como estructuras KeyValuePair.

En este ejemplo se reciben las actualizaciones de propiedades deseadas como TwinCollection y, a continuación, recorre e imprime las actualizaciones de la colección KeyValuePair. Después de recorrer en bucle la colección KeyValuePair, el código llama a UpdateReportedPropertiesAsync para actualizar la propiedad notificada DateTimeLastDesiredPropertyChangeReceived para mantener actualizada la última hora actualizada.

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Ejemplo de dispositivo del SDK

El SDK de Azure IoT para .NET proporciona un ejemplo de trabajo de una aplicación de dispositivo que controla las tareas del dispositivo gemelo. Para obtener más información, consulte TwinSample.

Creación de una aplicación back-end

Una aplicación back-end:

• Se conecta a un dispositivo a través de IoT Hub
• Puede leer las propiedades notificadas y deseadas del dispositivo, escribir propiedades deseadas del dispositivo y ejecutar consultas de dispositivo.

La clase RegistryManager expone todos los métodos necesarios para crear una aplicación back-end para interactuar con dispositivos gemelos desde el servicio.

En esta sección se describe cómo crear código de aplicación back-end para:

• Leer y actualizar campos de dispositivos gemelos
• Creación de una consulta de dispositivo gemelo

Agregar paquete NuGet de servicio

Las aplicaciones de servicio back-end requieren el paquete NuGet de Microsoft.Azure.Devices.

Conexión al centro de IoT

Conecte una aplicación back-end a un dispositivo mediante CreateFromConnectionString. Como parámetro, proporcione la cadena de conexión de servicio IoT Hub que creó en la sección de requisitos previos.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{IoT hub service connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Leer y actualizar campos de dispositivos gemelos

Puede recuperar los campos gemelos actuales en un objeto Gemelo mediante una llamada a GetTwinAsync.

La clase Twin incluye propiedades que corresponden a cada sección de un dispositivo gemelo. Use las propiedades de la clase Twin para ver y actualizar campos gemelos del dispositivo. Puede usar las propiedades del objeto Twin para actualizar varios campos gemelos antes de escribir las actualizaciones en el dispositivo mediante UpdateTwinAsync.

Después de realizar actualizaciones de campos gemelos, llame a UpdateTwinAsync para escribir actualizaciones de campo de objeto Twin en un dispositivo. Use la lógica try y catch junto con un controlador de errores para detectar errores de revisión con formato incorrecto de UpdateTwinAsync.

Leer y actualizar etiquetas de dispositivo gemelo

Utilice la propiedad del dispositivo gemelo Etiquetas para leer y escribir la información de las etiquetas del dispositivo.

Actualización de etiquetas mediante un objeto gemelo

En este ejemplo se crea una revisión de etiqueta location , se le asigna al objeto Twin mediante la propiedad Tags y, a continuación, se aplica la revisión mediante UpdateTwinAsync.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the tag patch
var tagspatch =
   @"{
   tags: {
         location: {
            region: 'US',
            plant: 'Redmond43'
         }
   }
}";

// Assign the patch to the Twin object
twin.Tags["location"] = tagspatch;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Actualización de etiquetas mediante una cadena JSON

Puede crear y aplicar una revisión de actualización de información de dispositivos gemelos con formato JSON. IoT Hub analiza y aplica la revisión si tiene el formato correcto.

En este ejemplo se llama a GetTwinAsync para recuperar los campos gemelos actuales en un objeto Twin, crea una revisión con formato JSON tag con información de región y ubicación de la planta y, a continuación, llama a UpdateTwinAsync para aplicar la revisión para actualizar el dispositivo gemelo. Se muestra un mensaje de error si UpdateTwinAsync falla.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the JSON tags patch
var patch =
   @"{
      tags: {
            location: {
               region: 'US',
               plant: 'Redmond43'
            }
      }
   }";
// Apply the patch to update the device twin tags
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Visualización y actualización de las propiedades deseadas del gemelo

Use la propiedad del objeto gemelo TwinProperties.Desired para leer y escribir información de propiedad deseada del dispositivo. Actualice las propiedades del gemelo Desired mediante una revisión con formato JSON.

Este ejemplo llama a GetTwinAsync para recuperar los campos gemelos actuales del dispositivo en un objeto Twin, actualiza la propiedad deseada del gemelo speed, y luego llama a UpdateTwinAsync para aplicar el objeto Twin para actualizar el gemelo del dispositivo.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

twin.Properties.Desired["speed"] = "type: '5G'";
await registryManager.UpdateTwinAsync(twin.DeviceId, twin, twin.ETag);

Otros métodos de actualización de gemelos

También puede aplicar actualizaciones de gemelos mediante estos métodos del SDK:

• Llame a ReplaceTwinAsync para reemplazar todo el dispositivo gemelo.
• Llame a UpdateTwins2Async para actualizar una lista de gemelos creados anteriormente en el sistema.

Creación de una consulta de dispositivo gemelo

En esta sección se muestran dos consultas de dispositivo gemelo. Las consultas de dispositivos gemelos son consultas similares a SQL que devuelven un conjunto de resultados de dispositivos gemelos.

Para crear una consulta de dispositivo gemelo, llame a CreateQuery para enviar una consulta SQL de gemelos y obtener una interfaz IQuery. Opcionalmente, puede llamar a CreateQuery con un segundo parámetro para especificar un número máximo de elementos por página.

A continuación, llame al método GetNextAsTwinAsync o GetNextAsJsonAsync tantas veces como sea necesario para recuperar todos los resultados del gemelo.

• GetNextAsTwinAsync para recuperar el siguiente resultado paginado como objetos Gemelo.
• GetNextAsJsonAsync para recuperar el siguiente resultado paginado como cadenas JSON.

La interfaz IQuery incluye una propiedad HasMoreResults booleana que se puede utilizar para comprobar si hay más resultados gemelos que recuperar.

En esta consulta de ejemplo solo se seleccionan los dispositivos gemelos de los dispositivos ubicados en la planta de Redmond43.

var query = registryManager.CreateQuery(
"SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
var twinsInRedmond43 = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43: {0}", 
string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

Esta consulta de ejemplo refina la primera consulta para seleccionar solo los dispositivos que también están conectados a través de una red de telefonía móvil.

query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));

Ejemplo del servicio SDK

El SDK de Azure IoT para .NET proporciona un ejemplo de trabajo de una aplicación de servicio que controla las tareas del dispositivo gemelo. Para obtener más información, consulte Ejemplo del Administrador de registros.

Información general

En este artículo se describe cómo usar la SDK de Azure IoT para Java para crear código de aplicación de servicio de dispositivo y back-end para dispositivos gemelos.

Creación de una aplicación de dispositivo

Las aplicaciones de dispositivo pueden leer y escribir propiedades notificadas de gemelos y recibir notificaciones de los cambios de propiedad de gemelos deseados establecidos por una aplicación de back-end o IoT Hub.

En esta sección se describe cómo crear código de aplicación de dispositivo para:

• Recuperación y visualización de un dispositivo gemelo
• Actualización de las propiedades notificadas de dispositivos gemelos
• Suscripción a los cambios de propiedad deseados

La clase DeviceClient expone todos los métodos necesarios para interactuar con dispositivos gemelos desde el dispositivo.

Instrucciones de importación de dispositivos

Use las siguientes instrucciones de importación de dispositivos para acceder al SDK de Azure IoT para Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;

Conexión del dispositivo

Cómo conectarlo a un dispositivo:

1. Use IotHubClientProtocol para elegir un protocolo de transporte. Por ejemplo:

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

2. Use el constructor DeviceClient para agregar la cadena de conexión principal y el protocolo del dispositivo.

   String connString = "{IoT hub device connection string}";
   DeviceClient client = new DeviceClient(connString, protocol);
   

3. Use abrir para conectar el dispositivo a IoT Hub. Si el cliente ya está abierto, el método no hace nada.

   client.open(true);
   

Recuperación y visualización de un dispositivo gemelo

Después de abrir la conexión de cliente, llame a getTwin para recuperar las propiedades del gemelo actual en un objeto Twin.

Por ejemplo:

private static Twin twin;
System.out.println("Getting current twin");
twin = client.getTwin();
System.out.println("Received current twin:");
System.out.println(twin);

Actualización de las propiedades notificadas del dispositivo gemelo

Después de recuperar el gemelo actual, puede empezar a realizar actualizaciones de propiedades notificadas. También puede realizar actualizaciones de propiedades notificadas sin obtener el gemelo actual siempre que tenga la versión de propiedades notificadas correcta. Si envía propiedades notificadas y recibe un error de "error de condición previa", la versión de las propiedades notificadas no está actualizada. En ese caso, vuelva a llamar a getTwin la versión más reciente.

Para actualizar las propiedades notificadas:

1. Llame a getReportedProperties para capturar las propiedades notificadas del gemelo en un objeto TwinCollection.

2. Use put para actualizar una propiedad notificada dentro del objeto TwinCollection. Llame a put para cada actualización de propiedad notificada.

3. Use updateReportedProperties para aplicar el grupo de propiedades notificadas que se actualizaron mediante el método put.

Por ejemplo:

TwinCollection reportedProperties = twin.getReportedProperties();

int newTemperature = new Random().nextInt(80);
reportedProperties.put("HomeTemp(F)", newTemperature);
System.out.println("Updating reported property \"HomeTemp(F)\" to value " + newTemperature);

ReportedPropertiesUpdateResponse response = client.updateReportedProperties(reportedProperties);
System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTemperature);

Suscripción a los cambios de propiedad deseados

Llame a subscribeToDesiredProperties para suscribirse a los cambios de propiedad deseados. Este cliente recibe una devolución de llamada con un objeto Twin cada vez que se actualiza una propiedad deseada. Esa devolución de llamada contiene las propiedades deseadas completas establecidas o solo la propiedad deseada actualizada en función de cómo se cambió la propiedad deseada.

En este ejemplo se suscribe a los cambios de propiedad deseados. Los cambios de propiedad deseados se pasan a un controlador denominado DesiredPropertiesUpdatedHandler.

client.subscribeToDesiredProperties(new DesiredPropertiesUpdatedHandler(), null);

En este ejemplo, el controlador de devolución de llamada de cambio de propiedad deseada DesiredPropertiesUpdatedHandler llama a getDesiredProperties para recuperar los cambios de propiedad y, a continuación, imprime las propiedades gemelas actualizadas.

  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
  {
      @Override
      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
      {
          if (twin == null)
          {
              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
              return;
          }

          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
          System.out.println("Received desired property update. Current twin:");
          System.out.println(twin);
      }
  }

Ejemplo de dispositivo del SDK

El SDK de Azure IoT para Java incluye un ejemplo de trabajo para probar los conceptos de la aplicación de dispositivo descritos en este artículo. Para obtener más información, consulte Ejemplo de dispositivo gemelo.

Creación de una aplicación back-end

En esta sección se describe cómo crear una aplicación back-end que:

• Actualiza las etiquetas de dispositivo gemelo
• Consulta dispositivos mediante filtros en las etiquetas y propiedades

La clase ServiceClient DeviceTwin contiene métodos que los servicios pueden utilizar para acceder a los dispositivos gemelos.

Instrucciones de importación de servicio

Use las siguientes instrucciones de importación de servicio para acceder al SDK de Azure IoT para Java.

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

Conéctese al cliente del servicio del centro de IoT

Para conectarse a IoT Hub para ver y actualizar la información del dispositivo gemelo:

1. Cree un objeto DeviceTwinClientOptions. Establezca las opciones necesarias para la aplicación. Estas opciones se pasan al objeto DeviceTwin.
2. Use un constructor DeviceTwin para crear la conexión con el IoT Hub. El objeto DeviceTwin controla la comunicación con el IoT Hub. Como parámetros, proporcione la cadena de conexión del servicio IoT Hub que creó en la sección Requisitos previos y el objeto DeviceTwinClientOptions.
3. El objeto DeviceTwinDevice representa el dispositivo gemelo con sus propiedades y etiquetas.

Por ejemplo:

public static final String iotHubConnectionString = "{IoT hub service connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwinClientOptions twinOptions = new DeviceTwinClientOptions();
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString,twinOptions);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

Actualizar campos gemelos de dispositivo

Para actualizar los campos del dispositivo gemelo:

1. Use getTwin para recuperar los campos gemelos del dispositivo actual

   En este ejemplo se recuperan e imprimen los campos del dispositivo gemelo:

   // Get the device twin from IoT Hub
   System.out.println("Device twin before update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

2. Use un objeto HashSet para add un grupo de pares de etiquetas gemelas

3. Use setTags para agregar un grupo de pares de etiquetas de un objeto tags a un objeto DeviceTwinDevice

4. Use updateTwin para actualizar el gemelo en IoT Hub

   En este ejemplo se actualizan las etiquetas de dispositivo gemelo de región y planta para un dispositivo gemelo:

   // Update device twin tags if they are different
   // from the existing values
   String currentTags = device.tagsToString();
   if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {
   
   // Create the tags and attach them to the DeviceTwinDevice object
   Set<Pair> tags = new HashSet<Pair>();
   tags.add(new Pair("region", region));
   tags.add(new Pair("plant", plant));
   device.setTags(tags);
   
   // Update the device twin in IoT Hub
   System.out.println("Updating device twin");
   twinClient.updateTwin(device);
   }
   
   // Retrieve and display the device twin with the tag values from IoT Hub
   System.out.println("Device twin after update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

Creación de una consulta de dispositivo gemelo

En esta sección se muestran dos consultas de dispositivo gemelo. Las consultas de dispositivos gemelos son consultas similares a SQL que devuelven un conjunto de resultados de dispositivos gemelos.

La clase Query contiene métodos que se pueden usar para crear consultas de estilo SQL en IoT Hub para gemelos, trabajos, trabajos de dispositivo o datos sin procesar.

Para crear una consulta de dispositivo:

1. Use createSqlQuery para compilar la consulta SQL de gemelos

2. Use queryTwin para ejecutar la consulta

3. Use hasNextDeviceTwin para comprobar si hay otro dispositivo gemelo en el conjunto de resultados

4. Use getNextDeviceTwin para recuperar el siguiente dispositivo gemelo del conjunto de resultados

Las consultas de ejemplo siguientes devuelven un máximo de 100 dispositivos.

En esta consulta de ejemplo solo se seleccionan los dispositivos gemelos de los dispositivos ubicados en la planta de Redmond43.

// Query the device twins in IoT Hub
System.out.println("Devices in Redmond:");

// Construct the query
SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);

// Run the query, returning a maximum of 100 devices
Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Esta consulta de ejemplo refina la primera consulta para seleccionar solo los dispositivos que también están conectados a través de una red de telefonía móvil.

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Ejemplo del servicio SDK

El SDK de Azure IoT para Java proporciona un ejemplo de trabajo de una aplicación de servicio que controla las tareas del dispositivo gemelo. Para obtener más información, consulte Ejemplo de dispositivo gemelo.

Información general

En este artículo se describe cómo usar la SDK de Azure IoT para Python para crear código de aplicación de servicio de dispositivo y back-end para dispositivos gemelos.

Creación de una aplicación de dispositivo

Las aplicaciones de dispositivo pueden leer y escribir propiedades notificadas de gemelos y recibir notificaciones de los cambios de propiedad de gemelos deseados establecidos por una aplicación de back-end o IoT Hub.

La clase IoTHubDeviceClient contiene métodos que se pueden usar para trabajar con dispositivos gemelos.

En esta sección se describe cómo crear código de aplicación de dispositivo que:

• Recupera un dispositivo gemelo y examina las propiedades notificadas
• Revisa las propiedades de dispositivos gemelos notificados

Conectarse a un dispositivo

En esta sección se muestra cómo conectar una aplicación a un dispositivo mediante una clave principal de dispositivo que incluye una clave de acceso compartido.

Para conectar una aplicación a un dispositivo:

1. Llame a create_from_connection_string para agregar la cadena de conexión del dispositivo.
2. Llame a conectar para conectar el cliente del dispositivo a una instancia de Azure IoT Hub

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{IOT hub device connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

# connect the application to the device
await device_client.connect()

Recuperar un dispositivo gemelo y examinar las propiedades notificadas

Puede recuperar y examinar la información del dispositivo gemelo, incluidas las etiquetas y las propiedades. La información del dispositivo gemelo recuperada coincide con los datos con formato JSON del dispositivo gemelo que puede ver para un dispositivo en Azure Portal.

Llame a get_twin para obtener el dispositivo gemelo del servicio Azure IoT Hub. La información del gemelo se coloca en una variable que se puede imprimir o examinar.

En este ejemplo se recupera el dispositivo gemelo y se usa el comando print para ver el dispositivo gemelo en formato JSON.

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

Revisa las propiedades de dispositivos gemelos notificados

Puede aplicar una revisión para actualizar las propiedades notificadas del dispositivo en formato JSON.

Para aplicar una revisión para actualizar las propiedades notificadas:

1. Asigne una revisión JSON de propiedad notificada a una variable.
2. Llame a patch_twin_reported_properties para aplicar la revisión JSON a las propiedades notificadas. Se trata de una llamada sincrónica, lo que significa que esta función no devuelve hasta que se envía la revisión al servicio y se confirma.

Si patch_twin_reported_properties devuelve un error, esta función genera el error correspondiente.

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

También puede llamar a estos métodos para actualizar dispositivos gemelos:

• Llame a replace_twin para reemplazar las etiquetas de dispositivo gemelo y las propiedades deseadas.
• Llame a update_twin para actualizar las etiquetas de dispositivo gemelo y las propiedades deseadas.

Controlador de revisiones de propiedades deseadas entrantes

Llame a on_twin_desired_properties_patch_received para crear una función de controlador o corrutina a la que se llama cuando se recibe una revisión de propiedades deseadas de gemelo. El controlador toma un argumento, que es la revisión gemela en forma de un objeto de diccionario JSON.

En este ejemplo se configura un controlador de revisiones de propiedades deseado denominado twin_patch_handler.

Por ejemplo:

try:
    # Set handlers on the client
    device_client.on_twin_desired_properties_patch_received = twin_patch_handler
except:
    # Clean up in the event of failure
    client.shutdown()

El twin_patch_handler recibe e imprime las actualizaciones de propiedades deseadas de JSON.

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

Ejemplos de dispositivos del SDK

El SDK de Azure IoT para Python incluye los ejemplos siguientes:

• get_twin: conéctese a un dispositivo y recupere información de gemelos.
• update_twin_reported_properties: actualice las propiedades notificadas del gemelo.
• receive_twin_desired_properties: reciba y actualice las propiedades deseadas.

Creación de una aplicación back-end

Una aplicación back-end se conecta a un dispositivo a través de IoT Hub y puede leer las propiedades notificadas y deseadas del dispositivo, escribir propiedades deseadas del dispositivo y ejecutar consultas de dispositivo.

En esta sección se describe cómo crear una aplicación back-end para:

• Actualizar etiquetas gemelas y propiedades deseadas
• Consultar dispositivos mediante filtros en las etiquetas y propiedades

La clase IoTHubRegistryManager expone todos los métodos necesarios para crear una aplicación back-end para interactuar con dispositivos gemelos desde el servicio.

Conexión al centro de IoT

Conéctese a IoT Hub mediante from_connection_string. Como parámetro, proporcione la cadena de conexión de servicio IoT Hub que creó en la sección de requisitos previos.

Por ejemplo:

import sys
from time import sleep
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

Actualizar etiquetas gemelas y propiedades deseadas

Puede actualizar las etiquetas de dispositivo gemelo y las propiedades deseadas de una aplicación back-end al mismo tiempo mediante update_twin.

1. Llame a get_twin para obtener la versión actual del dispositivo gemelo.
2. Use la clase Gemelo para agregar etiquetas y propiedades en formato JSON.
3. Llame a update_twin para aplicar la revisión al dispositivo gemelo. También puede usar replace_twin para reemplazar las propiedades y etiquetas deseadas de un dispositivo gemelo.

En este ejemplo se actualiza la información de etiqueta region y plant y se establece una propiedad deseada power_level en 1.

new_tags = {
        'location' : {
            'region' : 'US',
            'plant' : 'Redmond43'
        }
    }

DEVICE_ID = "[Device Id]"
twin = iothub_registry_manager.get_twin(DEVICE_ID)
twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

Creación de una consulta de dispositivo gemelo

Puede consultar la información del dispositivo gemelo mediante consultas de dispositivos gemelos. Las consultas de dispositivos gemelos son consultas similares a SQL que devuelven un conjunto de resultados de dispositivos gemelos.

Para usar una consulta de dispositivo gemelo:

1. Use un objeto QuerySpecification para definir una solicitud de consulta similar a SQL.

2. Use query_iot_hub para consultar IoTHub y recuperar información de dispositivos gemelos mediante la especificación de consulta similar a SQL.

En este ejemplo se ejecutan dos consultas. La primera selecciona solo los dispositivos gemelos de los dispositivos que se encuentran en la plantaRedmond43 y la segunda mejora la consulta para seleccionar solo los dispositivos que están también conectados a través de la red de telefonía móvil. Los resultados se imprimen después de cada consulta.

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

Ejemplo del servicio SDK

El SDK de Azure IoT para Python proporciona un ejemplo de trabajo de una aplicación de servicio que controla las tareas del dispositivo gemelo. Para obtener más información, consulte ejemplo de consulta del Administrador de registros.

Información general

En este artículo se describe cómo usar el SDK de Azure IoT para .Node.js para crear código de aplicación de servicio de dispositivo y back-end para dispositivos gemelos.

Creación de una aplicación de dispositivo

Las aplicaciones de dispositivo pueden leer y escribir propiedades notificadas de gemelos y recibir notificaciones de los cambios de propiedad de gemelos deseados establecidos por una aplicación de back-end o IoT Hub.

En esta sección se describe cómo usar el paquete de azure-iot-device en el SDK de Azure IoT para Node.js para crear una aplicación de dispositivo para:

• Recuperar un dispositivo gemelo y examinar las propiedades notificadas
• Actualizar las propiedades notificadas de dispositivos gemelos
• Recibir aviso de los cambios de propiedad deseados

Instalación de paquetes de SDK

Ejecute este comando para instalar el SDK de dispositivo de azure-iot-device en la máquina de desarrollo:

npm install azure-iot-device --save

El paquete azure-iot-device contiene objetos que interactúan con dispositivos IoT. La clase Gemelo incluye objetos específicos de gemelos. Esta sección describe el código de clase Client que se utiliza para leer y escribir datos gemelos del dispositivo.

Selección de un protocolo de transporte

EClientl objeto admite estos protocolos:

• Amqp
• Http: al usar Http, la instancia de Client comprueba si hay mensajes de IoT Hub con poca frecuencia (cada 25 minutos como mínimo).
• Mqtt
• MqttWs
• AmqpWs

Instale los protocolos de transporte necesarios en la máquina de desarrollo.

Por ejemplo, este comando instala el protocolo Mqtt:

npm install azure-iot-device-mqtt --save

Para más información sobre las diferencias entre la compatibilidad con MQTT, AMQP y HTTPS, consulte Guía de comunicación de nube a dispositivo y Elección de un protocolo de comunicación.

Creación de un módulo de cliente

Cree un módulo Client mediante el paquete instalado.

Por ejemplo:

const Client = require('azure-iot-device').Client;

Creación de un módulo de protocolo

Cree un módulo Protocol mediante un paquete de transporte instalado.

En este ejemplo se asigna el protocolo MQTT:

const Protocol = require('azure-iot-device-mqtt').Mqtt;

Adición de la cadena de conexión del dispositivo y el protocolo de transporte

Llame a fromConnectionString para proporcionar parámetros de conexión de dispositivo:

• connStr: una cadena de conexión que encapsula los permisos "device connect" para una instancia de IoT Hub. La cadena de conexión contiene el nombre de host, la identidad del dispositivo y la clave de acceso compartido en este formato: "HostName=<iothub_host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key>".
• transportCtor: el protocolo de transporte.

En este ejemplo se usa el protocolo de transporte Mqtt:

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Mqtt;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Apertura de la conexión a IoT Hub

Use el método open para abrir una conexión entre un dispositivo IoT e IoT Hub. Use .catch(err) para detectar un error y ejecutar código de controlador.

Por ejemplo:

client.open()  //open the connection
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

Recuperar un dispositivo gemelo y examinar las propiedades notificadas

Llame a getTwin para recuperar la información actual del dispositivo gemelo en un objeto Gemelo.

Por ejemplo:

client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

Actualización de las propiedades notificadas de dispositivos gemelos

Use actualizar para actualizar las propiedades notificadas del dispositivo. Incluya una revisión con formato JSON como el primer parámetro y el método de devolución de llamada de estado de ejecución de la función como segundo parámetro para el método.

En este ejemplo, se almacena una revisión de dispositivo gemelo con formato JSON en la variable patch. La revisión contiene un dispositivo gemelo connectivity valor de actualización de cellular. El controlador de revisiones y errores se pasan al método update. Si se produce un error, se muestra un mensaje de error de consola.

var patch = {
    connectivity: {
        type: 'cellular'
    }
}
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Recibir aviso de los cambios de propiedad deseados

Cree un agente de escucha de eventos de actualización de propiedades deseada que se ejecute cuando se cambie una propiedad deseada en el dispositivo pasando el nombre del método del controlador de devolución de llamada a twin.on.

El agente de escucha de eventos de propiedad deseada puede adoptar una de las formas siguientes:

• Recepción de todas las revisiones con un único controlador de eventos
• Recepción de un evento si algo cambia en una agrupación de propiedades
• Recepción de un evento para un único cambio de propiedad

Recepción de todas las revisiones con un único controlador de eventos

Puede crear un agente de escucha para recibir cualquier cambio de propiedad deseado.

Este código de ejemplo genera las propiedades que se reciben del servicio.

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

Recepción de un evento si algo cambia en una agrupación de propiedades

Puede crear un agente de escucha para recibir un evento si algo en una agrupación de propiedades cambia.

Por ejemplo:

1. Las propiedades minTemperature y maxTemperature se encuentran en una agrupación de propiedades denominada properties.desired.climate changes.

2. Una aplicación de servicio back-end aplica esta revisión para actualizar las propiedades deseadas minTemperature y maxTemperature:

   const twinPatch1 = {
   properties: {
      desired: {
       climate: { minTemperature: 68, maxTemperature: 76, },
       },
     },
    };
   

3. Este código configura un agente de escucha de eventos de cambio de propiedades deseado que se desencadena para los cambios dentro de la agrupación de propiedades de properties.desired.climate. Si hay un cambio de propiedad deseado en este grupo, los mensajes de cambio de temperatura mínimo y máximo que se muestran en la consola:

   twin.on('properties.desired.climate', function (delta) {
       if (delta.minTemperature || delta.maxTemperature) {
           console.log('updating desired temp:');
           console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
           console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
       }
   });
   

Recepción de un evento para un único cambio de propiedad

Puede configurar un agente de escucha para un único cambio de propiedad. En este ejemplo, el código de este evento solo se ejecuta si el valor booleano fanOn forma parte de la revisión. El código genera el nuevo estado deseado fanOn cada vez que el servicio lo actualiza.

1. Una aplicación back-end aplica esta revisión de propiedad deseada:

    const twinPatch2 = {
     properties: {
       desired: {
         climate: {
           hvac: {
             systemControl: { fanOn: true, },
           },
         },
       },
     },
   };
   

2. El agente de escucha solo se desencadena cuando cambia la propiedad fanOn:

    twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
        console.log('setting fan state to ' + fanOn);
     });
   

Ejemplos de SDK de dispositivos

El SDK de Azure IoT para Node.js contiene dos ejemplos de dispositivos gemelos:

• Dispositivo gemelo de ejemplo simple

• Dispositivo gemelo de ejemplo simple con SAS

Creación de una aplicación back-end

Una aplicación back-end se conecta a un dispositivo a través de IoT Hub y puede leer las propiedades notificadas y deseadas del dispositivo, escribir propiedades deseadas del dispositivo y ejecutar consultas de dispositivo.

En esta sección se describe cómo crear una aplicación back-end que:

• Recupera y actualiza un dispositivo gemelo.
• Crea una consulta de dispositivo gemelo

Instalación de paquetes de SDK de servicio

Ejecute este comando para instalar azure-iothub en la máquina de desarrollo:

npm install azure-iothub --save

La clase Registro expone todos los métodos necesarios para interactuar con dispositivos gemelos desde una aplicación back-end.

Conexión al centro de IoT

Use fromConnectionString para conectarse a IoT Hub. Como parámetro, proporcione la cadena de conexión de servicio IoT Hub que creó en la sección de requisitos previos.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Iot Hub service connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

Recuperación y actualización de un dispositivo gemelo

Puede crear una revisión que contenga actualizaciones de etiquetas y propiedades deseadas para un dispositivo gemelo.

Para actualizar un dispositivo gemelo:

1. Llame a getTwin para recuperar el objeto de dispositivo gemelo.

• Formatee una revisión que contenga la actualización del dispositivo gemelo. La revisión tiene el formato JSON tal como se describe en la clase Gemelo. Una revisión del servicio back-end puede contener actualizaciones de propiedades deseadas y etiquetas. Para obtener más información sobre el formato de revisión, consulte Formato de etiquetas y propiedades.

1. Llame a actualizar para actualizar el dispositivo gemelo con la revisión.

En este ejemplo, el dispositivo gemelo se recupera para myDeviceId y, a continuación, se aplica una revisión a los gemelos que contienen location actualización de etiquetas de region: 'US', plant: 'Redmond43'.

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Creación de una consulta de dispositivo gemelo

Puede crear consultas de dispositivo similares a SQL para recopilar información de dispositivos gemelos.

Use createQuery para crear una consulta que se pueda ejecutar en una instancia de IoT Hub para buscar información sobre dispositivos o trabajos.

createQuery incluye dos parámetros:

• sqlQuery: la consulta escrita como una cadena SQL.
• pageSize: número deseado de resultados por página (opcional. valor predeterminado: 1000, máximo: 10000).

Si se especifica el parámetro pageSize , el objeto de consulta contiene una propiedad booleana hasMoreResults que puede comprobar y usar el método nextAsTwin para obtener la página de resultados del gemelo siguiente tantas veces como sea necesario para recuperar todos los resultados. Un método llamado next está disponible para los resultados que no son dispositivos gemelos, por ejemplo, los resultados de consultas de agregación.

En esta consulta de ejemplo solo se seleccionan los dispositivos gemelos de los dispositivos ubicados en la planta Redmond43.

var queryTwins = function() {
var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});

Esta consulta de ejemplo refina la primera consulta para seleccionar solo los dispositivos que también están conectados a través de una red de telefonía móvil.

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});
};

Ejemplo del SDK de servicio

El SDK de Azure IoT para Node.js proporciona un ejemplo de trabajo de una aplicación de servicio que controla las tareas del dispositivo gemelo. Para obtener más información, consulte servicio back-end de dispositivos gemelos: este proyecto se usa para enviar actualizaciones de revisiones de dispositivos gemelos para un dispositivo específico.