Escenario: recepción de comandos y envío de respuestas mediante MQTT

Utilice este escenario para recibir comandos en la nube y enviar respuestas a un dispositivo mediante el protocolo MQTTs para interactuar con los dispositivos de Internet of Things (IoT).

Tareas

Paso 1: Crear una instancia gemela digital

Uso de la CLI

  1. Cuando cree una instancia de gemelo digital, utilice un secreto o un certificado para que la instancia de gemelo digital se pueda autenticar de forma segura. Debe crear un secreto o crear un certificado para completar este escenario. Oracle recomienda utilizar un secreto para cada instancia de gemelo digital.
  2. Utilice el comando oci iot digital-twin-instance create y los parámetros necesarios para crear un gemelo digital. En el siguiente ejemplo, se muestra el comando con los parámetros de nombre mostrado e ID de autenticación:

    oci iot digital-twin-instance create --auth-id <vault-secret-or-client-certificate-id> --iot-domain-id <iot-domain-OCID>

    En esta respuesta de ejemplo, observe el valor de clave externa. Utilice este valor de clave externa en el Step 3: Use MQTTX to Connect Using an External ID:

    "external-key": "<unique-id>"
    {
      "data": {
        "auth-id": "<vault-secret-or-certificate-OCID>",
        "defined-tags": {
          "Oracle-Tags": {
            "CreatedBy": "default/user@oracle.com",
            "CreatedOn": "2025-08-05T18:03:15.264Z"
          }
        },
        "description": null,
        "digital-twin-adapter-id": null,
        "digital-twin-model-id": null,
        "digital-twin-model-spec-uri": null,
        "display-name": "HVAC-instance",
        "external-key": "<unique-id>",
        "freeform-tags": {},
        "id": "<iot-digital-twin-instance-OCID>",
        "iot-domain-id": "<iot-domain-OCID>",
        "lifecycle-state": "ACTIVE",
        "system-tags": {},
        "time-created": "2025-08-05T18:03:15.870000+00:00",
        "time-updated": "2025-08-05T18:03:15.870000+00:00"
      },
      "etag": "<unique-id>"
    }

Paso 2: Definir el comando en un archivo JSON

Puede definir el comando en un archivo JSON y utilizar este archivo en el siguiente paso.

El archivo command.json de este ejemplo contiene los siguientes comandos para llamar al comando y procesar la respuesta según las instrucciones del archivo.

{
  "requestEndpoint": "/endpoints/1234",
  "requestDuration": "PT3M",
  "requestDataFormat": "JSON",
  "requestData": {
    "temp": 33
  },
  "requestDataContentType": "application/json",
  "responseEndpoint": "/endpoints/4321",
  "responseDuration": "PT3M"
}
  • requestEndpoint: ruta de acceso de URL /endpoints/1234 a la que se enviará la solicitud. Normalmente, se trata de un punto final de API o una dirección en la que la plataforma IoT recibe comandos.
  • requestDuration: duración permitida o solicitada para que se complete la solicitud, en formato de duración ISO 8601. PT3M, que equivale a 3 minutos.
  • requestDataFormat: especifica el formato de fecha para los datos enviados en la solicitud de JSON.
  • requestData: carga útil de JSON que se envía con un par de valores de clave para definir un valor de temperatura en el dispositivo:
    "temp": 33
Para obtener información sobre las ubicaciones de los archivos y los tipos de ruta, consulte Uso de un archivo JSON para una entrada compleja.

Paso 3: Llamada a un comando JSON raw en un dispositivo

Puede usar la CLI o la API para invocar un comando en un dispositivo; en el siguiente ejemplo, se usa la CLI.

Uso de la CLI

Utilice el comando oci iot digital-twin-instance invoke-raw-json-command y los parámetros para llamar a un comando JSON sin formato en un dispositivo.

Sustituya <digital-twin-instance-OCID> por el OCID de la instancia de gemelo digital del Paso 1: Creación de una instancia de gemelo digital. En este ejemplo, se muestra una solicitud para un valor de temperatura del dispositivo mediante el comando JSON sin formato definido en el archivo command.json definido en el Paso 2: Definir el comando en un archivo JSON.

oci iot digital-twin-instance invoke-raw-json-command --digital-twin-instance-id <digital-twin-instance-OCID> --request-endpoint "/endpoints/1234" --from-json --file://command.json
Para obtener más información sobre otros tipos de comandos, consulte Envío de un comando raw desde una instancia gemela digital.

Paso 4: Utilice MQTTX para conectarse al dispositivo mediante un ID externo

Utilice cualquier cliente MQTT, en este ejemplo se utiliza MQTTX con la siguiente configuración.
  1. Descargue y configure MQTTX siguiendo estas instrucciones. Consulte Getting Started with MQTTX. Abra MQTTX.
  2. Seleccione + Nueva conexión para crear una nueva conexión.
  3. Introduzca el valor <unique-id> de la clave externa como Nombre de usuario. Puede encontrar la clave externa en la respuesta oci iot digital-twin-instance create, del Paso 1: Creación de una instancia gemela digital anterior:
    "external-key": "<unique-id>"
  4. Introduzca la contraseña del dispositivo.
  5. Introduzca el Host. Seleccione el protocolo mqtts:// en la lista desplegable de hosts e introduzca el host del dispositivo: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com en el dominio IoT.
  6. Introduzca el puerto, por ejemplo: 8883
  7. Active el conmutador SSL/TLS.
  8. Active el conmutador SSL Secure.
  9. Para el certificado, seleccione la opción Certificado de servidor firmado por CA.
  10. Al configurar la conexión MQTTX, asegúrese de conectarse mediante un clean session y defina la opción Last-Will-Retain en false para permitir que se retengan las suscripciones de cliente si el dispositivo se desconecta brevemente.
  11. Defina Último valor de QoS en 1.
  12. Seleccione Connect (Conectar).

Esta imagen muestra la configuración en MQTTX, haga clic con el botón derecho y abra en una nueva pestaña para ver una captura de pantalla más grande.

En la configuración de MQTTX para llamar a un comando.

Para ver una captura de pantalla más grande, haga clic con el botón derecho y abra una nueva pestaña.

En MQTTX, seleccione Conectar.

Paso 5: Suscribirse a un tema para recibir respuestas en MQTTX

Cuando el sistema externo o el dispositivo IoT publica un mensaje en el tema suscrito, puede ver los mensajes entrantes en MQTTX en ese tema. Si está esperando una respuesta de un comando anterior, asegúrese de que está suscrito al tema de respuesta correcto que se define dinámicamente en la respuesta de dos instancias digitales como valor <external-id>.

  1. En MQTTX, seleccione + Nueva suscripción.
  2. Introduzca el punto final como tema.
  3. En el menú desplegable QoS, seleccione 1 Al menos una vez.
  4. Seleccione Confirm (Confirmar).
Utilice los siguientes valores de conexión para recibir los mensajes publicados en un punto final de dispositivo para la instancia de gemelo digital con un ID externo específico:
  • ID de cliente: oracle-test-user-42
  • Username: ID externo.
  • Contraseña: introduzca la contraseña del dispositivo.
  • Introduzca mqtts:// con el host y el número de puerto del dispositivo:

    mqtts://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com:8883

Para ver una captura de pantalla más grande, haga clic con el botón derecho y abra una nueva pestaña.En MQTTX, introduzca el punto como tema y confirme la suscripción.

Paso 6: Supervisión del estado de entrega del comando en APEX

Para ver los datos de IoT en APEX, es necesario configurar el acceso a los datos. Una vez finalizada esa configuración, puede utilizar APEX para trabajar con los datos de IoT.

  1. En APEX, conéctese al espacio de trabajo del dominio IoT específico mediante lo siguiente como nombre de espacio de trabajo y nombre de usuario de base de datos. Observe los dos caracteres de subrayado en el nombre del esquema de base de datos:
    <domain-short-id-from-device-host>__IOT 
    Vaya a SQL Workshop y seleccione SQL Commands para consultar los datos IoT.
  2. Introduzca el siguiente comando, sustituya <digital-twin-instance-OCID> por el OCID de gemelo digital y seleccione Run para consultar los datos del comando raw:
    select * from raw_command_data
    where digital_twin_instance_id='<digital-twin-instance-OCID>'
  3. En Resultados, consulte RESPONSE_DATA:
    {"test":1}
Para ver una captura de pantalla más grande, haga clic con el botón derecho y abra una nueva pestaña.Vea los datos de respuesta del dispositivo en APEX.

Paso 7: Ver la respuesta del comando en MQTTX

En MQTTX, seleccione Conectar para ver la respuesta:
{
    "test": 1
  }

Para ver una captura de pantalla más grande, haga clic con el botón derecho y abra una nueva pestaña.

En MQTTX, visualice los datos de respuesta del comando.