Introducción a la identidad de módulo y a los módulos gemelos de IoT Hub (Node.js)

Artículo
08/30/2023

Las identidades de módulo y los módulos gemelos son similares a la identidad de dispositivo y el dispositivo gemelo de Azure IoT Hub, pero ofrecen granularidad más fina. Aunque la identidad del dispositivo y los dispositivos gemelos de Azure IoT Hub permiten que la aplicación back-end configure un dispositivo y proporcionan visibilidad para las condiciones del dispositivo, la identidad de módulo y los módulos gemelos proporcionan estas funcionalidades para los componentes individuales del dispositivo. En los dispositivos compatibles con varios componentes, como los dispositivos con sistema operativo o con firmware, permite una configuración y unas condiciones aisladas para cada componente.

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.

Al final de este artículo, tendrá dos aplicaciones de Node.js:

CreateIdentities: crea una identidad de dispositivo, una de módulo y las claves de seguridad asociadas para conectar el dispositivo y los clientes del módulo.
UpdateModuleTwinReportedProperties: envía las propiedades notificadas por el módulo gemelo actualizadas a IoT Hub.

Nota

Para más información sobre las herramientas de SDK disponibles para compilar aplicaciones de dispositivo y back-end, consulte SDK de Azure IoT.

Requisitos previos

Una instancia de IoT Hub. Cree uno con la CLI o el Azure Portal.
Node.js versión 10.0.x o posteriores. En Preparación del entorno de desarrollo se describe cómo instalar Node.js para este artículo ya sea en Windows o en Linux.

Autenticación de módulos

Puede utilizar claves simétricas o certificados X.509 para autenticar las identidades de los módulos. Para la autenticación de certificados X.509, el certificado del módulo debe tener su nombre común (CN) formateado como CN=<deviceid>/<moduleid>. Por ejemplo:

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

Obtención de la cadena de conexión de IoT Hub

En este artículo, va a crear un servicio back-end que agregará un dispositivo en el registro de identidades y, a continuación, agregará un módulo a ese dispositivo. El servicio requiere el permiso de escribir en el Registro. De forma predeterminada, todas las instancias de IoT Hub se crean con una directiva de acceso compartido denominada registryReadWrite que concede este permiso.

Para obtener la cadena de conexión de IoT Hub para la directiva registryReadWrite, siga estos pasos:

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.
En el panel de la izquierda del centro, seleccione Directivas de acceso compartido.
En la lista de directivas, seleccione la directiva registryReadWrite.
Copie la Cadena de conexión principal y guarde el valor.

Para obtener más información sobre las directivas de acceso compartido y los permisos de IoT Hub, consulte Permisos y control del acceso.

Crear una identidad del dispositivo y una identidad de módulo en IoT Hub

En esta sección se crea una aplicación de Node.js que crea una identidad de dispositivo y otra de módulo en el registro de identidades de la instancia de IoT Hub. No se puede conectar un dispositivo o un módulo a IoT Hub a menos que tenga una entrada en el registro de identidades. Para más información, consulte Descripción del registro de identidades de un centro de IoT. Cuando se ejecuta esta aplicación de consola, genera una clave y un identificador únicos para el dispositivo y el módulo. El identificador y la clave distinguen mayúsculas de minúsculas. El dispositivo y el módulo usan estos valores para identificarse al enviar mensajes del dispositivo a la nube a IoT Hub.

Cree un directorio para almacenar el código.
Dentro de ese directorio, ejecute primero npm init -y para crear un archivo package.json vacío con los valores predeterminados. Este es el archivo de proyecto para su código.
Ejecute npm install -S azure-iothub@modules-preview para instalar el SDK del servicio dentro del subdirectorio node_modules.

Nota

El nombre de subdirectorio node_modules utiliza la palabra module para indicar "una biblioteca de nodos". En este caso, el término no tiene nada que ver con los módulos de IoT Hub.

Cree el siguiente archivo .js en su directorio. Llámelo add.js. Copie y pegue la cadena de conexión del centro y el nombre del centro.

var Registry = require('azure-iothub').Registry;
var uuid = require('uuid');
// Copy/paste your connection string and hub name here
var serviceConnectionString = '<hub connection string from portal>';
var hubName = '<hub name>.azure-devices.net';
// Create an instance of the IoTHub registry
var registry = Registry.fromConnectionString(serviceConnectionString);
// Insert your device ID and moduleId here.
var deviceId = 'myFirstDevice';
var moduleId = 'myFirstModule';
// Create your device as a SAS authentication device
var primaryKey = new Buffer(uuid.v4()).toString('base64');
var secondaryKey = new Buffer(uuid.v4()).toString('base64');
var deviceDescription = {
  deviceId: deviceId,
  status: 'enabled',
  authentication: {
    type: 'sas',
    symmetricKey: {
      primaryKey: primaryKey,
      secondaryKey: secondaryKey
    }
  }
};

// First, create a device identity
registry.create(deviceDescription, function(err) {
  if (err) {
    console.log('Error creating device identity: ' + err);
    process.exit(1);
  }
  console.log('device connection string = "HostName=' + hubName + ';DeviceId=' + deviceId + ';SharedAccessKey=' + primaryKey + '"');

  // Then add a module to that device
  registry.addModule({ deviceId: deviceId, moduleId: moduleId }, function(err) {
    if (err) {
      console.log('Error creating module identity: ' + err);
      process.exit(1);
    }

    // Finally, retrieve the module details from the hub so we can construct the connection string
    registry.getModule(deviceId, moduleId, function(err, foundModule) {
      if (err) {
        console.log('Error getting module back from hub: ' + err);
        process.exit(1);
      }
      console.log('module connection string = "HostName=' + hubName + ';DeviceId=' + foundModule.deviceId + ';ModuleId='+foundModule.moduleId+';SharedAccessKey=' + foundModule.authentication.symmetricKey.primaryKey + '"');
      process.exit(0);
    });
  });
});

Esta aplicación crea una identidad del dispositivo con el identificador myFirstDevice y una de módulo con el identificador myFirstModule en el dispositivo myFirstDevice. (Si el identificador de módulo ya existe en el Registro de identidad, el código simplemente recupera la información existente del módulo). A continuación, la aplicación muestra la clave principal de esa identidad. Esta clave se usará en la aplicación de módulo simulado para conectarse a IoT Hub.

Ejecútelo con el comando node add.js. Se le ofrecerá una cadena de conexión para la identidad del dispositivo y otra para la identidad del módulo.

Nota

El registro de identidades de IoT Hub solo almacena identidades de dispositivos y módulos para permitir el acceso seguro a IoT Hub. El registro de identidades almacena los identificadores y las claves de dispositivo para usarlas como credenciales de seguridad. El registro de identidades también almacena una marca de habilitado o deshabilitado de cada dispositivo que se puede usar para deshabilitar el acceso a dicho dispositivo. Si la aplicación necesita almacenar otros metadatos específicos del dispositivo, debe usar un almacén específico de la aplicación. No hay marcas de habilitado/deshabilitado para las identidades de módulo. Para obtener más información, vea Descripción del registro de identidades de un centro de IoT en la Guía del desarrollador de IoT Hub.

Actualización del módulo gemelo con el SDK de dispositivo Node.js

En esta sección se crea una aplicación de Node.js en el dispositivo simulado que actualiza las propiedades notificadas del módulo gemelo.

Obtenga la cadena de conexión del módulo. Inicie sesión en Azure Portal. Vaya al IoT Hub y seleccione Dispositivos IoT. Busque myFirstDevice, ábralo y verá que myFirstModule se creó correctamente. Copie la cadena de conexión del módulo, la necesitará en el paso siguiente.
De forma similar a la sección anterior, cree un directorio para el código de dispositivo y use NPM para inicializarlo e instalar el SDK del dispositivo (npm install -S azure-iot-device-amqp@modules-preview).

Nota

El comando npm install puede resultar lento. Sea paciente, porque extrae una gran cantidad de código del repositorio de paquetes.

Nota

Si ve un error "npm ERR! registry error parsing json" (Error de npm: error del registro al analizar json), puede ignorarlo sin problema. Si ve un error "npm ERR! registry error parsing json" (Error de npm: error del registro al analizar json), puede ignorarlo sin problema.

Cree un archivo llamado twin.js. Copie y pegue la cadena de identidad del módulo.

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-amqp').Amqp;
// Copy/paste your module connection string here.
var connectionString = '<insert module connection string here>';
// Create a client using the Amqp protocol.
var client = Client.fromConnectionString(connectionString, Protocol);
client.on('error', function (err) {
  console.error(err.message);
});
// connect to the hub
client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
  console.log('client opened');
// Create device Twin
  client.getTwin(function(err, twin) {
    if (err) {
      console.error('error getting twin: ' + err);
      process.exit(1);
    }
    // Output the current properties
    console.log('twin contents:');
    console.log(twin.properties);
    // Add a handler for desired property changes
    twin.on('properties.desired', function(delta) {
        console.log('new desired properties received:');
        console.log(JSON.stringify(delta));
    });
    // create a patch to send to the hub
    var patch = {
      updateTime: new Date().toString(),
      firmwareVersion:'1.2.1',
      weather:{
        temperature: 72,
        humidity: 17
      }
    };
    // send the patch
    twin.properties.reported.update(patch, function(err) {
      if (err) throw err;
      console.log('twin state reported');
    });
  });
});

Ahora, ejecútelo con el comando node twin.js.

F:\temp\module_twin>node twin.js

A continuación, verá:

client opened
twin contents:
{ reported: { update: [Function: update], '$version': 1 },
  desired: { '$version': 1 } }
new desired properties received:
{"$version":1}
twin state reported

Pasos siguientes

Para continuar la introducción a IoT Hub y explorar otros escenarios de IoT, consulte:

Introducción a la identidad de módulo y a los módulos gemelos de IoT Hub (Node.js)

Requisitos previos

Autenticación de módulos

Obtención de la cadena de conexión de IoT Hub

Crear una identidad del dispositivo y una identidad de módulo en IoT Hub

Actualización del módulo gemelo con el SDK de dispositivo Node.js

Pasos siguientes

Recursos adicionales