Escenario: Crear gemelos digitales para dispositivos conectados indirectamente mediante una puerta de enlace

Cree modelos de gemelos digitales, adaptadores, un gateway, instancias de gemelos digitales de dispositivos directos e indirectos para que pueda enrutar la telemetría y los comandos a través de un gateway compartido.

Utilice este escenario para crear una puerta de enlace reutilizable, un dispositivo conectado directamente y varios dispositivos conectados indirectamente.

Para ilustrar este escenario, los ejemplos modelan un sistema pequeño de calefacción, ventilación y aire acondicionado (HVAC) que incluye:

Una puerta de enlace denominada Bosch Gateway 1 se autentica en el dominio de IoT y recopila o enruta datos para dispositivos como unidades de climatización, calderas y deshumidificadores.
La instancia de HVAC conectada directamente muestra un dispositivo que envía su propia telemetría.
Las instancias de HVAC, caldera y deshumidificador conectadas indirectamente muestran dispositivos cuya telemetría y comandos se mueven por la puerta de enlace en su lugar.

Para obtener más información, consulte Preguntas frecuentes sobre los dispositivos conectados indirectamente.

Revise el diagrama para comprender cómo la puerta de enlace, los dispositivos conectados directamente y los dispositivos conectados indirectamente interactúan con los 3 tipos de instancias de gemelos digitales.

Tareas

Cree modelos gemelos digitales.
Cree adaptadores gemelos digitales.
Cree las instancias de gateway y dispositivo.
Enviar datos de telemetría.
Obtenga el contenido de la instancia de gemelo digital.
Llamar a comandos.

Para obtener más información sobre cómo hacer referencia a archivos desde la CLI, consulte Using a JSON File for Complex Input.

Paso 1: Crear modelos gemelos digitales

Cree un modelo gemelo digital para el gateway y un modelo gemelo digital para cada tipo de dispositivo del escenario. Estos dispositivos emiten datos estructurados.

Utilice los siguientes fragmentos para guardar estos archivos: gateway-model.json, hvac-model.json y boiler-model.json.

Utilice la consola cuando desee cargar un archivo de modelo guardado o pegar la especificación directamente.

En la página de lista Dominios de IoT, abra el dominio con el que desea trabajar. Si necesita ayuda para encontrar la página de lista de dominios de IoT, consulte Listado de dominios de IoT o Creación de un nuevo dominio de IoT.
Seleccione el separador Modelos gemelos digitales y, a continuación, seleccione Crear.
Introduzca un Nombre y una Descripción Opcional. Evite introducir información confidencial.
Seleccione Cargar la especificación o Pegar especificación y, a continuación, utilice uno de los archivos de ejemplo de este escenario.
Opcional: agregue etiquetas.
Seleccione Crear.

Utilice uno de los siguientes archivos al cargar o pegar la especificación.

gateway-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:gateway;1",
  "@type": "Interface",
  "displayName": "Gateway",
  "description": "A digital twin model for Gateway",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "cpuUtilization",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "memoryUtilization",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "storageUtilization",
      "schema": "integer"
    },
    {
      "@type": "Property",
      "name": "firmwareVersion",
      "schema": "string"
    }
  ]
}

hvac-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1",
  "@type": "Interface",
  "displayName": "HVAC",
  "description": "A digital twin model for HVAC",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "humidity",
      "schema": "integer"
    }
  ]
}

boiler-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:boiler;1",
  "@type": "Interface",
  "displayName": "Boiler",
  "description": "A digital twin model for Boiler",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "pressure",
      "schema": "integer"
    }
  ]
}

Utilice el comando oci iot digital-twin-model create para crear cada modelo de gemelo digital en el dominio de IoT.

Crear el modelo de gateway

oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://gateway-model.json

Crear el modelo de HVAC

oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://hvac-model.json

Crear el modelo de caldera

oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://boiler-model.json

Para este ejemplo, guarde estos fragmentos en estos archivos de modelo, gateway-model.json, hvac-model.json y boiler-model.json.

gateway-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:gateway;1",
  "@type": "Interface",
  "displayName": "Gateway",
  "description": "A digital twin model for Gateway",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "cpuUtilization",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "memoryUtilization",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "storageUtilization",
      "schema": "integer"
    },
    {
      "@type": "Property",
      "name": "firmwareVersion",
      "schema": "string"
    }
  ]
}

hvac-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1",
  "@type": "Interface",
  "displayName": "HVAC",
  "description": "A digital twin model for HVAC",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "humidity",
      "schema": "integer"
    }
  ]
}

boiler-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:boiler;1",
  "@type": "Interface",
  "displayName": "Boiler",
  "description": "A digital twin model for Boiler",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "pressure",
      "schema": "integer"
    }
  ]
}

Ejecute la operación CreateDigitalTwinModel para crear un modelo gemelo digital en el dominio de IoT.

Utilice la misma carga útil DTDL que se muestra en los archivos de modelo gemelo digital de ejemplo al llamar a la API.

Paso 2: Crear adaptadores gemelos digitales

Cree un adaptador para la puerta de enlace y un adaptador para cada tipo de dispositivo estructurado que necesite asignación de carga útil.

Utilice los siguientes fragmentos para guardar estos archivos: gateway-envelope.json, gateway-routes.json, hvac-envelope.json, hvac-routes.json, boiler-envelope.json y boiler-routes.json.

Resolver el destino en el sobre de entrada

Los adaptadores de gateway pueden identificar la instancia de gemelo digital de destino cuando todos los mensajes de dispositivo reenviados siguen el mismo tema o la misma convención de carga útil. El gateway se autentica como sí mismo, el servicio comprueba que el destino resuelto es una instancia de gemelo digital conectada indirectamente asociada a ese gateway y, a continuación, el servicio delega la carga útil al adaptador del dispositivo de destino cuando se necesita una asignación estructurada.

El gateway resuelve target y contentRoot una vez para todo el mensaje antes de ejecutar las rutas. Si target se resuelve en una clave externa de dispositivo conectada indirectamente, la carga útil se delega a ese dispositivo. Si target está vacío o es nulo, el mensaje se trata como datos de gateway.

Utilice un adaptador de gemelo digital cuando la carga útil entrante se deba asignar al modelo de gemelo digital de destino. No se requiere un adaptador gemelo digital cuando el dispositivo envía datos no estructurados, puede transferir datos sin cambios.

En la página de lista Dominios de IoT, abra el dominio con el que desea trabajar.
Seleccione el separador Adaptadores gemelos digitales y, a continuación, seleccione Crear.
Introduzca un nombre y una descripción opcional. Evite introducir información confidencial.
Seleccione el modelo gemelo digital que coincida con la carga útil que está asignando.
Active Especificar el sobre de entrada y las rutas y, a continuación, cargue o pegue el JSON del sobre y enrute el JSON para el adaptador.
Opcional: agregue etiquetas.
Seleccione Crear.

Cree el adaptador de gateway con estos archivos de gateway.

portal-envelope.json

{
  "referenceEndpoint": "/data",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "cpuUtil": 0,
      "memUtil": 0,
      "diskUtil": 0,
      "firmware": "Oracle Linux 9.1"
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time",
    "target": "${if ([\"boilers\", \"hvacs\", \"dehumidifiers\"] | contains([endpoint(1)])) then endpoint(2) else null end}",
    "contentRoot": "$"
  }
}

gateway-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.cpuUtilization": "$.cpuUtil",
      "$.memoryUtilization": "$.memUtil",
      "$.storageUtilization": "$.diskUtil",
      "$.firmwareVersion": "$.firmware"
    }
  }
]

Cree los adaptadores HVAC y de caldera con los archivos de dispositivo coincidentes.

hvac-envelope.json

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temperature": 0,
      "humidity": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}

hvac-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.humidity": "$.humidity"
    }
  }
]

caldera-envelope.json

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "timestamp": 1773768299143534,
      "temperature": 0,
      "pressure": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.timestamp"
  }
}

boiler-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.pressure": "$.pressure"
    }
  }
]

Utilice el comando oci iot digital-twin-adapter create para crear cada adaptador en el dominio de IoT.

Crear el adaptador de gateway

Utilice este comando para crear un adaptador gemelo digital. En este ejemplo, se muestra cómo asociar el modelo gemelo digital mediante DTMI y cómo definir el sobre y las rutas mediante archivos .json.

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:gateway;1" \
  --inbound-envelope file://gateway-envelope.json \
  --inbound-routes file://gateway-routes.json

portal-envelope.json

{
  "referenceEndpoint": "/data",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "cpuUtil": 0,
      "memUtil": 0,
      "diskUtil": 0,
      "firmware": "Oracle Linux 9.1"
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time",
    "target": "${if ([\"boilers\", \"hvacs\", \"dehumidifiers\"] | contains([endpoint(1)])) then endpoint(2) else null end}",
    "contentRoot": "$"
  }
}

gateway-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.cpuUtilization": "$.cpuUtil",
      "$.memoryUtilization": "$.memUtil",
      "$.storageUtilization": "$.diskUtil",
      "$.firmwareVersion": "$.firmware"
    }
  }
]

Crear el adaptador de HVAC

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:hvac;1" \
  --inbound-envelope file://hvac-envelope.json \
  --inbound-routes file://hvac-routes.json

hvac-envelope.json

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temperature": 0,
      "humidity": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}

hvac-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.humidity": "$.humidity"
    }
  }
]

Crear el adaptador de caldera

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:boiler;1" \
  --inbound-envelope file://boiler-envelope.json \
  --inbound-routes file://boiler-routes.json

caldera-envelope.json

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "timestamp": 1773768299143534,
      "temperature": 0,
      "pressure": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.timestamp"
  }
}

boiler-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.pressure": "$.pressure"
    }
  }
]

Para obtener más información sobre cómo hacer referencia a archivos desde la CLI, consulte Using a JSON File for Complex Input.

Ejecute la operación CreateDigitalTwinAdapter para crear un adaptador gemelo digital en el dominio de IoT.

Utilice las mismas cargas útiles de rutas de entrada y sobre de entrada que se muestran en los archivos de ejemplo.

Paso 3: Creación de las instancias de gateway y dispositivo

Cree primero la puerta de enlace para que pueda reutilizarla cuando cree los dispositivos conectados indirectamente.

Opciones de ID de autenticación:

Para probar instancias de gemelos digitales, si utiliza el OCID secreto como ID de autenticación, utilice el nombre de usuario del dispositivo como clave externa y el contenido del secreto de texto sin formato como contraseña del dispositivo. Para obtener instrucciones, al Crear un secreto, consulte el paso 7 y, para conocer los secretos que ya se han creado, consulte Obtención del contenido de un secreto.
Para las instancias de gemelos digitales de producción, utilice el OCID del certificado mTLS en lugar de un secreto de almacén como ID de autenticación. Al utilizar un certificado mTLS, debe utilizar el nombre común de los detalles del certificado como clave externa: --external-key <common-name-from-certificate-details>

Utilice la consola para crear un gateway y asociarle varios dispositivos.
En la consola, hay dos formas de crear un gateway para el dominio de IoT. Puede crear un gateway desde el separador Instancia de gemelo digital seleccionando el tipo de gateway al crear una instancia de gemelo digital. O bien, puede seleccionar el separador Gateway para crear el gateway.
1. En la página de lista Dominios de IoT, abra el dominio de IoT con el que desea trabajar.
2. Seleccione el separador Gateways y, a continuación, seleccione Crear para crear una instancia de gateway de transferencia para que esté disponible para dispositivos indirectos.
  - Introduzca un nombre para el gateway y una descripción.
  - Introduzca la clave externa gateway1.
  - Seleccione el adaptador que utiliza gateway-envelope.json y gateway-routes.json creados en el Step 2.
  - Seleccione el ID de autenticación o pegue el OCID del ID de autenticación y, a continuación, seleccione Crear.
3. En la página Dominio de IoT, seleccione el separador Instancias gemelas digitales, seleccione Crear y, a continuación, seleccione conectadas directamente o conectadas indirectamente como tipo para crear las instancias gemelas digitales para estos dispositivos, utilizando el modelo y los adaptadores creados en el Paso 1 y el Paso 2 para:
  - instancia de HVAC de LG conectada directamente con la clave externa hvac1.
  - instancia de HVAC conectada indirectamente con la clave externa hvac2
  - instancia de caldera conectada indirectamente con la clave externa boiler1.
  - instancia de deshumidificador conectada indirectamente con la clave externa dehumidifier1. El deshumidificador no utiliza un adaptador gemelo digital o un modelo gemelo digital, ya que envía telemetría cruda no estructurada que no necesita una asignación de carga útil estructurada. También puede recibir comandos raw a través del gateway.
  Nota
  
  Si no introduce una clave externa, se generará.
4. Para la instancia de gateway y conectada directamente, seleccione un ID de autenticación.
5. Para una instancia conectada indirectamente, seleccione una o más puertas de enlace existentes en lugar de agregar credenciales de autenticación de dispositivo. Seleccione más de una puerta de enlace cuando un dispositivo inalámbrico pueda vagar entre puertas de enlace.
6. Opcional: agregue etiquetas.
7. Revise el resumen de la instancia de gemelo digital y, a continuación, seleccione Crear.
Después de crear las instancias de gemelos digitales, utilice la página Detalles de gateway para ver de qué dispositivos dependen y están asociados al gateway.
- Busque los detalles de gateway en la página de dominio de IoT. Para ello, seleccione el separador Gateway para ver la lista de gateway y seleccione un gateway para ir a la página de detalles de gateway.
- En el separador Instancia de gemelo digital, puede buscar por tipo para ver los diferentes tipos de instancia de gemelo digital para un dominio de IoT.
- Vea los dispositivos conectados directa e indirectamente desde la página Detalles de instancia de gemelo digital .
Para obtener una lista completa de la configuración, consulte Creación de una instancia de gemelo digital, Listado de instancias de gemelo digital y Obtención de detalles de una instancia de gemelo digital.
Utilice el comando oci iot digital-twin-instance create para crear el gateway y las instancias de dispositivo conectadas directa e indirectamente.

Crear la instancia de HVAC conectada directamente
Utilice este comando para crear una instancia de gemelo digital que esté asociada a un dominio de IoT específico y que esté conectada directamente mediante una clave externa hvac1.
```
oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type DIRECT \
  --display-name "LG HVAC 1" \
  --auth-id <certificate-or-secret-OCID> \
  --digital-twin-adapter-id <hvac-adapter-OCID> \
  --external-key hvac1
```
Crear la instancia de gateway
Utilice este comando para crear una instancia de gemelo digital que esté asociada a un dominio de IoT específico. Utilice el parámetro --connectivity-type necesario con el valor GATEWAY para crear una instancia de gemelo digital que sea un gateway. La clave externa es gateway1.
```
oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type GATEWAY \
  --display-name "Bosch Gateway 1" \
  --auth-id <certificate-or-secret-OCID> \
  --digital-twin-adapter-id <gateway-adapter-OCID> \
  --external-key gateway1
```
Crear la instancia de HVAC conectada indirectamente
Utilice este comando y el parámetro necesario --connectivity-type INDIRECT para crear un gemelo digital que sea un dispositivo conectado indirectamente. Este escenario muestra una asociación de puerta de enlace por dispositivo. Cuando el despliegue soporta la itinerancia, asocie el dispositivo conectado indirectamente a más de un gateway para que pueda moverse entre ellos sin cambiar la instancia de gemelo digital.
Nota

Al crear un dispositivo conectado indirectamente mediante el parámetro --gateways necesario, es un tipo complejo y debe utilizar una matriz de JSON. Por ejemplo: --gateways '["<gateway-instance-OCID>"]' o para itinerancia, utilice --gateways '["<gateway-instance-1-OCID>","<gateway-instance-2-OCID>"]'. También puede utilizar un archivo .json.
```
oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name "LG HVAC 2" \
  --gateways '["<gateway-instance-OCID>"]' \
  --digital-twin-adapter-id <hvac-adapter-OCID> \
  --external-key hvac2
```
Crear la instancia de caldera conectada indirectamente
Utilice este comando y el parámetro necesario --connectivity-type INDIRECT para crear un gemelo digital que sea un dispositivo conectado indirectamente.
```
oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name "GE Boiler 1" \
  --gateways '["<gateway-instance-OCID>"]' \
  --digital-twin-adapter-id <boiler-adapter-OCID> \
  --external-key boiler1
```
Crear la instancia de deshumidificador conectada indirectamente
Utilice este comando y el parámetro necesario --connectivity-type INDIRECT para crear un gemelo digital que sea un dispositivo conectado indirectamente.
```
oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name Danby Dehumidifier 1 \
  --gateways '["<gateway-instance-OCID>"]' \
  --external-key dehumidifier1
```
Ejecute la operación CreateDigitalTwinInstance para crear una instancia de gateway, una instancia conectada directamente y una instancia conectada indirectamente.

Al crear una instancia conectada indirectamente, asegúrese de que la solicitud incluya la asociación de gateway.

Paso 4: Enviar datos de telemetría

Estos ejemplos muestran tres rutas de datos. Un dispositivo conectado directamente, como hvac1, se autentica con su propia clave externa y envía datos a su propia instancia de gemelo digital. La puerta de enlace, gateway1, también se autentica con su propia clave externa cuando envía su propia CPU, memoria, almacenamiento y telemetría de firmware.

Los dispositivos conectados de forma indirecta no se autentican en el dominio de IoT; el gateway se autentica como gateway1 y la ruta de punto final, como hvacs/hvac2, boilers/boiler1 o dehumidifiers/dehumidifier1, identifica el dispositivo de destino detrás del gateway.

Instalar y configurar MQTTX.
Utilice <digital-twin-instance-external-key> como nombre de usuario del dispositivo. Si necesita buscar la clave externa de instancia digital, puede obtener detalles de instancia de un gemelo digital.
Conéctese a <domain-short-id>.device.iot.<region>.oci.oraclecloud.com en el puerto 8883, active SSL/TLS y utilice una sesión limpia.

Enviar telemetría desde la instancia de HVAC conectada directamente:

mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'data' \
  -m '{
    "temperature": 70,
    "humidity": 60
  }' \
  -u hvac1 \
  -P '<secret-contents>'

Enviar telemetría desde la instancia de gateway:

mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'data' \
  -m '{
    "cpuUtil": 30,
    "memUtil": 25,
    "diskUtil": 20,
    "firmware": "Oracle Linux 9.1"
  }' \
  -u gateway1 \
  -P '<secret-contents>'

Enviar telemetría para la instancia de HVAC conectada indirectamente a través del gateway:

mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'hvacs/hvac2' \
  -m '{
    "temperature": 75,
    "humidity": 65
  }' \
  -u gateway1 \
  -P '<secret-contents>'

Enviar telemetría para la instancia de caldera conectada indirectamente a través del gateway:

mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'boilers/boiler1' \
  -m '{
    "temperature": 80,
    "pressure": 90
  }' \
  -u gateway1 \
  -P '<secret-contents>'

Envíe la telemetría para la instancia de deshumidificador conectada indirectamente a través del gateway:

mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'dehumidifiers/dehumidifier1' \
  -m 'humidity=50,fanSpeed=medium' \
  -u gateway1 \
  -P '<secret-contents>'

Utilice curl para enviar telemetría a través de HTTPS. Estos ejemplos utilizan la autenticación básica HTTP con la clave externa de la instancia de gemelo digital y el contenido del secreto de texto sin formato.
1. Utilice la clave externa de la instancia de gemelo digital como nombre de usuario. Por ejemplo, para la telemetría conectada directamente, utilice la clave externa de la instancia, como hvac1.
2. Utilice el contenido del secreto de texto sin formato como contraseña.
3. Envíe la solicitud a https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/<endpoint-path>.
4. Para los dispositivos conectados indirectamente, autentique como instancia de gateway y utilice la ruta de punto final para identificar el dispositivo de destino, como hvacs/hvac2 o boilers/boiler1.
Enviar telemetría desde la instancia de HVAC conectada directamente:
```
curl -i -u "hvac1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/data" \
  -d '{
    "temperature": 70,
    "humidity": 60
  }'
```
Enviar telemetría desde la instancia de gateway:
```
curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/data" \
  -d '{
  "cpuUtil": 30,
  "memUtil": 25,
  "diskUtil": 20,
  "firmware": "Oracle Linux 9.1"
}'
```
Enviar telemetría para la instancia de HVAC conectada indirectamente a través del gateway:
```
curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/hvacs/hvac2" \
  -d '{
    "temperature": 75,
    "humidity": 65
  }'
```
Enviar telemetría para la instancia de caldera conectada indirectamente a través del gateway:
```
curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/boilers/boiler1" \
  -d '{
    "temperature": 80,
    "pressure": 90
  }'
```
Envíe la telemetría para la instancia de deshumidificador conectada indirectamente a través del gateway:
```
curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: text/plain" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/dehumidifiers/dehumidifier1" \
  -d 'humidity=50,fanSpeed=medium'
```

Paso opcional 5: Obtener contenido de instancia de gemelo digital

Para confirmar que los datos de la instancia de gemelo digital se capturan, utilice la consola, la CLI o la API para ver el contenido de la instancia del gemelo digital, que son los datos de instantánea más recientes.

Para una instancia de gemelo digital de datos no estructurados, normalmente no tiene un modelo de gemelo digital asociado, por lo que no puede utilizar la obtención de contenido para una instancia de gemelo digital para ver sus datos.

1. En la página de lista Dominios, seleccione el dominio con el que desea trabajar. Si necesita ayuda para encontrar la página de lista de dominios de IoT o un dominio de IoT, consulte Listado de dominios de IoT.
2. Seleccione el separador Instancias gemelas digitales.
3. Seleccione el nombre de instancia de gemelo digital y se abrirá la página de detalles.
4. Seleccione el separador Datos para ver los datos de instantánea más recientes para esta instancia. Para obtener más información, consulte Referencia de esquema de base de datos de dominio de IoT.

Utilice el comando oci iot digital-twin-instance get-content y el parámetro necesario para obtener el contenido de la instancia de un gemelo digital:

Verifique la instancia de HVAC conectada directamente:

oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <lg-hvac-1-OCID>

Verifique la instancia de gateway:

oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <bosch-gateway-1-OCID>

Verifique la instancia de HVAC conectada indirectamente:

oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <lg-hvac-2-OCID>

Verifique la instancia de caldera conectada indirectamente:

oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <ge-boiler-1-OCID>

Ejecute la operación GetDigitalTwinInstanceContent para obtener contenido de una instancia de gemelo digital.

Paso 6: Llamar a comandos

Para dispositivos conectados indirectamente, utilice una política de entrega at-least-once y espere reintentos o entrega duplicada.

Cuando se necesite una respuesta, configure un punto final de respuesta para que el gateway pueda publicar la respuesta en nombre del dispositivo de destino.

Utilice la consola cuando desee enviar un comando raw desde la página de detalles de la instancia de gemelo digital.
1. Abra el dominio de IoT y seleccione el separador Instancias gemelas digitales.
2. Seleccione la instancia que desea controlar.
3. En el menú Acciones, seleccione Enviar comando raw.
4. Introduzca el punto final de la solicitud, la duración de la solicitud y la carga útil del comando.
5. Opcional: configure un punto final de respuesta y una duración de respuesta y, a continuación, seleccione Enviar comando raw. Utilice los valores de estos archivos: gateway-command.json, boiler-command.json
gateway-command.json
{ "force": true }
boiler-command.json
{ "hardReset": false }
Utilice el comando oci iot digital-twin-instance invoke-raw-json-command para llamar a las acciones de ejemplo en este escenario. Para obtener más información, consulte Envío de un comando raw desde una instancia de gemelo digital.

Reiniciar la instancia de gateway
```
oci iot digital-twin-instance invoke-raw-json-command \
  --digital-twin-instance-id <bosch-gateway-1-OCID> \
  --request-endpoint "actions/reboot" \
  --request-data '{"force": true}'
```
Restablecer la instancia de caldera conectada indirectamente
Especifique --request-endpoint, en este ejemplo que es boilers/boiler1/actions/reset.
Especifique --response-endpoint, en este ejemplo que es boilers/boiler1/actions/response.
Si espera una respuesta, debe incluir el parámetro --response-duration. Si no es así, el comando pasa al estado COMPLETED sin recibir la respuesta. Como resultado, la respuesta del comando no se captura en la tabla de base de datos RAW_COMMAND_DATA.
```
oci iot digital-twin-instance invoke-raw-json-command \
  --digital-twin-instance-id <ge-boiler-1-OCID> \
  --request-endpoint "boilers/boiler1/actions/reset" \
  --request-data '{"hardReset": false}' \
  --response-endpoint "boilers/boiler1/actions/response" \
  --response-duration PT10M
```
Publicar la respuesta de la caldera
Utilice el punto final de respuesta para publicar la respuesta de la caldera a este punto final: boilers/boiler1/actions/response en este ejemplo, gateway1 es la clave externa y el nombre de usuario del dispositivo.
```
mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t "boilers/boiler1/actions/response" \
  -m '{
    "status": "OK"
  }' \
  -u gateway1 \
  -P '<secret-contents>'
```
Apague el ventilador del deshumidificador conectado indirectamente
Utilice este comando para invocar un comando JSON sin formato en el dispositivo que cierra el ventilador en el deshumidificador.
```
oci iot digital-twin-instance invoke-raw-json-command \
  --digital-twin-instance-id <danby-dehumidifier-1-OCID> \
  --request-endpoint "dehumidifiers/dehumidifier1/actions/fanOff" \
  --request-data '{"fanOff": true}'
```
Ejecute la operación InvokeRawCommand para invocar un comando raw en un dispositivo.

Utilice un punto final de respuesta cuando el comando devuelva una confirmación de nivel de aplicación.

Elija el tipo de conectividad adecuado para su instancia de gemelo digital

Cómo decidir qué tipo de conectividad utilizar para una instancia de gemelo digital:

Conexión directa

Utilizar cuando: El dispositivo se conecta al dominio de IoT por sí solo.
Parámetro necesario: ID de autenticación, para la prueba, utilice un secret y para la producción, utilice el certificado mTLS.
Necesario para datos estructurados: Se puede proporcionar o inferir un adaptador gemelo digital que coincida con el modelo gemelo digital del adaptador, y el modelo debe contener al menos una telemetría, una propiedad o un comando.
Para datos no estructurados: No utilice un adaptador digital doble o un modelo digital doble.
Entrada opcional: La clave externa, si no proporciona una externa, el servicio genera una. Se utiliza para el nombre de usuario del dispositivo.
No Usar: Asociación de puerta de enlace con un dispositivo conectado directamente.

Gateway

Utilizar cuando: Un dispositivo reenvía datos y comandos para sí mismo y para otros dispositivos.
Parámetros necesarios: ID de autenticación y un adaptador de gateway. Las instancias de gateway no soportan la telemetría no estructurada, por lo que el adaptador es necesario.
Modelo de gemelos digitales: El modelo de gemelo digital de la puerta de enlace se puede asociar o inferir del adaptador de gemelo digital, y el modelo debe contener al menos una telemetría, propiedad o comando. Puede crear una instancia de gemelo digital con un adaptador sin especificar el modelo; un modelo se asocia a través del adaptador.; Para los datos no estructurados, normalmente no se utiliza un adaptador ni un modelo.
Entrada opcional: La clave externa, si no proporciona una, el servicio genera una.
Recomendado: Antes de cambiarla o suprimirla, revise la página gateway details (Detalles de gateway) para ver cuántos dispositivos dependen de la puerta de enlace.
No: Asocie una instancia de gateway a otra instancia de gateway.

Conectado indirectamente

Utilizar cuando: Otro dispositivo, normalmente una puerta de enlace, envía datos de telemetría y recibe comandos en nombre del dispositivo.
Necesario: Se necesitan una o más asociaciones de gateway. Utilice más de una puerta de enlace cuando un dispositivo inalámbrico pueda moverse entre puertas de enlace. Confirme con un administrador si esto funciona en su entorno.
Para datos estructurados: Para los datos estructurados se requiere un adaptador gemelo digital. El modelo de gemelo digital correspondiente se puede proporcionar o inferir del adaptador, especificando el DTMI o el OCID del modelo de gemelo digital, el modelo debe contener al menos una telemetría, propiedad o comando.
Para datos no estructurados: Para los datos no estructurados, no utilice un adaptador gemelo digital ni un modelo gemelo digital. No se puede obtener contenido para datos no estructurados, ya que no contiene un modelo gemelo digital.
Entrada opcional: Clave externa. Si no proporciona una clave externa, el servicio genera una.
Identificador de Autenticación: No utilice un ID de autenticación para una instancia de gemelo digital conectada indirectamente.

No conectado

Utilizar cuando: Prueba de una instancia de gemelo digital que no autentica, envía ni recibe datos del dispositivo para que pueda probar las relaciones de gemelo digital y probar la configuración de IoT sin la complejidad de los datos ni la autenticación.
Necesario: Para los datos estructurados, se requiere un modelo gemelo digital y no debe contener telemetría, propiedades o comandos.
Opcional: Relaciones gemelas digitales para pruebas. Para obtener más información, consulte Relaciones digitales con gemelos.
No Usar: ID de autenticación, clave externa, adaptador de gemelos digitales, asociación de gateway o datos de dispositivo en instancias de gemelos digitales que no están conectadas.

Preguntas más frecuentes

En esta sección de preguntas frecuentes se describen las historias de usuarios de gateway descritas en este escenario.

¿Puedo configurar una instancia de gemelo digital para que esté conectada indirectamente de modo que otro dispositivo envíe datos en su nombre?

Sí. Cree la instancia de gemelo digital para el dispositivo con el tipo de conectividad INDIRECT y asóciela a una o más instancias de gemelo digital de gateway en lugar de proporcionar al dispositivo su propio ID de autenticación.

¿Cómo puedo saber qué dispositivos están conectados a través de una puerta de enlace específica y comprender el impacto de perder esa puerta de enlace?

Utilice la página de detalles de la puerta de enlace para revisar el recuento de dispositivos asociados y la lista de instancias de gemelos digitales dependientes. Esto le ofrece la vista más rápida del radio de influencia de la puerta de enlace antes de las operaciones de mantenimiento, migración o supresión.

¿Cómo puedo saber cuántas de mis instancias de gemelos digitales están conectadas directamente, conectadas indirectamente o gateways?

En la página de lista de la instancia de gemelo digital o en la página de lista Gateway, puede encontrar la lista de gateways.

Revise el tipo de conectividad de cada gemelo digital y utilice un gateway de nivel de dominio y vistas de topología para obtener información sobre su entorno. En este escenario, se muestra un dispositivo directo, una puerta de enlace y varios dispositivos indirectos para que pueda comparar los tres patrones.

¿Cómo puedo configurar un adaptador para mi puerta de enlace para que la telemetría entrante se enrute al dispositivo de destino correcto?

Utilice un adaptador gemelo digital para la puerta de enlace que incluya una asignación target en el sobre. Consulte Paso 2: Creación de adaptadores gemelos digitales.

¿Cuándo debo poner target en las rutas de entrada en lugar de en el sobre de entrada?

Nº Coloque target en el sobre de entrada.

¿Qué sucede si target está vacío o es nulo?

El mensaje se trata como datos de puerta de enlace en lugar de delegarse a un dispositivo conectado indirectamente.

¿Puede un adaptador de puerta de enlace manejar tanto la telemetría de puerta de enlace como la telemetría de dispositivo conectada indirectamente?

Sí. Esta es la finalidad principal del enrutamiento de gateway. Los mensajes de dispositivo reenviados van a un destino resuelto, mientras que los datos de destino no coincidentes o vacíos permanecen con la puerta de enlace.

¿Puedo reutilizar un gateway en dispositivos conectados directa e indirectamente sin duplicar mis definiciones?

Sí. Tratar el gateway como un activo reutilizable, crear los adaptadores coincidentes una vez y, a continuación, asociar el gateway a cada dispositivo conectado indirectamente que deba utilizar esa condición de ruta del adaptador.

¿Puedo enviar telemetría no estructurada desde dispositivos conectados indirectamente?

Sí. Si no necesita una asignación de carga útil estructurada para el dispositivo de destino, puede enviar la carga útil raw a través de la puerta de enlace y omitir el adaptador específico del dispositivo.

¿Puedo invocar comandos no estructurados en dispositivos conectados indirectamente y en el propio gateway?

Sí. Utilice puntos finales de comandos raw para ambos patrones. Agregue un punto final de respuesta al comando no estructurado cuando necesite que el gateway publique una confirmación de nivel de aplicación para el dispositivo de destino.

--request-endpoint, por ejemplo boilers/boiler1/actions/reset

--response-endpoint, por ejemplo boilers/boiler1/actions/response

¿Puedo asociar un dispositivo a varias puertas de enlace para que pueda vagar?

Sí. Un dispositivo conectado indirectamente se puede asociar a una o más puertas de enlace. Esto permite que un dispositivo inalámbrico mantenga la misma instancia de gemelo digital mientras se mueve entre las puertas de enlace disponibles.

En la CLI, puede configurar la itinerancia de varias puertas de enlace mediante una matriz para la asociación de puerta de enlace del modelo gemelo digital.

Utilice la opción --gateways con una matriz JSON de OCID de instancia de gemelo digital de gateway:

oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name "Roaming Wireless Device 1" \
  --gateways '["<gateway-instance-1-OCID>","<gateway-instance-2-OCID>"]' \
  --external-key roaming-device1

Si prefiere evitar problemas de comillas de shell, coloque la lista de gateway en un archivo de entrada roaming-device.json y utilice --from-json:

oci iot digital-twin-instance create \
  --from-json file://roaming-device.json

roaming-device.json

{
  "iotDomainId": "<iot-domain-OCID>",
  "connectivityType": "INDIRECT",
  "displayName": "Roaming Wireless Device 1",
  "gateways": [
    "<gateway-instance-1-OCID>",
    "<gateway-instance-2-OCID>"
  ],
  "externalKey": "roaming-device1"
}

Antes de depender de la itinerancia de varios gateways en producción, confirme el comportamiento en el entorno de prueba y valide el patrón de transferencia que utilizan los gateways.

Solución de problemas

El comando permanece en estado ACCEPTED

En el Step 6: Invoke Commands, si no incluye el parámetro --request-data, el comando permanece en el estado ACCEPTED y genera un error: Invalid Command Invocation id [unique-id]: [Previous command invocation is not finished yet]

Siguientes Pasos

Suprima los recursos utilizados para crear este escenario:

Documentación de Oracle Cloud Infrastructure