Documentación de Oracle Cloud Infrastructure

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).

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 y para la producción, la instancia de gemelo digital debe utilizar un certificado mTLS para la autenticación.

  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 cómo utilizar el parámetro de ID de autenticación con el parámetro de dominio IoT necesario para asociar el dominio IoT a la instancia de gemelo digital:

    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 y observe la clave externa que es el nombre de usuario del dispositivo que puede utilizar en el siguiente paso:

    "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: Establecer la sesión MQTT con credenciales de broker

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. Introduzca un nombre para la conexión y evite introducir información confidencial.
  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. Si utiliza el secreto de almacén, este debe ser el secreto de texto sin formato o puede utilizar un certificado mTLS.
  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. Consulte Getting an IoT Domain's Details.
  6. Introduzca el puerto, por ejemplo: 8883
    Nota

    Actualmente, MQTT Secure (MQTTS) solo está soportado mediante el puerto 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:
    • clean session: defina la opción clean session en true. Cuando la sesión limpia se define en true, el broker no retiene ninguna información para el cliente y descarta cualquier estado anterior de cualquier sesión persistente. Todos los datos de la sesión se suprimen en cuanto se cierra la conexión de red.
    • 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. Para definir la fiabilidad de la entrega "Al menos una vez" para su notificación de desconexión.
  12. Seleccione Connect (Conectar).

Esta imagen muestra estos ajustes 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.

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

Cuando un sistema externo o un dispositivo IoT publica un mensaje en el tema suscrito, en MQTTX puede ver los mensajes entrantes en ese tema. Si está esperando una respuesta de un comando anterior, asegúrese de que está suscrito al tema de respuesta correcto.

Defina responseEndpoint en el siguiente paso al definir el comando en un archivo JSON. La cadena "responseEndpoint": "/endpoints/4321" representa el tema o la ruta de acceso de punto final donde el dispositivo debe publicar su respuesta. Seleccione cualquier ruta de punto final lógica para las rutas de gemelos digitales. Debe utilizar la misma ruta de acceso tanto en la nube (al enviar el comando) como en el dispositivo (al publicar la respuesta).

  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: your-client-ID
  • Username: ID externo.
  • Password (Contraseña): introduzca la contraseña del dispositivo.
  • Introduzca mqtts:// con el host de dispositivo del dominio IoT y con el número de puerto 8883:

    mqtts://<iot-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 ábralo en una nueva pestaña

.En MQTTX, introduzca el punto como tema y confirme la suscripción.

Paso 4: Definir el comando en un archivo JSON

Puede definir los detalles del comando en un archivo JSON y utilizar este archivo en el siguiente paso para Llamar a un comando JSON sin formato en un dispositivo.

Para este ejemplo, guarde este fragmento en un archivo command.json para que pueda utilizarlo 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.

    Si ya tiene un punto final dedicado a las respuestas, por ejemplo: /endpoints/<external-id>/response utilice esa ruta en responseEndpoint.

    O bien, cree un nuevo endpoint/route para la instancia de gemelo digital en las reglas de enrutamiento de entrada del adaptador de gemelo digital en las que el dispositivo puede publicar. Haga referencia a esa ruta en el archivo command.json. Mantenga la ruta de punto final consistente, cualquier ruta que defina en responseEndpoint se convierte en el tema MQTT al que el cliente debe suscribirse en el paso 3 para que pueda ver la respuesta del comando.

  • requestDuration: duración permitida o solicitada para que se complete la solicitud, en formato de duración ISO 8601. Por ejemplo, PT3M 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 5: 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. 

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 6: Verificar en MQTTX

En MQTTX, observe los datos invocados:
{
    "temp": 33
  }

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.

En esta imagen se muestra cómo verificar en MQTTX.

Escenarios de respuesta de comandos
EscenarioEstado del dispositivoEstado de comando esperadoComentarios
No conectadoNo conectado no suscrito RECHAZADO La entrega del comando falla inmediatamente
Conectado pero no suscritoConectado RECHAZADODispositivo en línea pero no recibe el comando
Suscrito pero no conectado Solo suscritoPENDIENTE → CADUCADOEl comando espera; caduca después del timeout
Suscrito pero no conectado inicialmente y se conecta antes del timeout Inicialmente fuera de línea PENDIENTE → ENVIADAComando recibido
Conectado y suscritoConectado y suscrito ENVIADO Comando recibido
Comando unidireccional (no se esperaba respuesta)Conectado y suscrito TERMINADO La respuesta no se espera y se realiza un seguimiento
Comando bidireccional (no se ha recibido respuesta)Conectado y suscrito NOT_RESPONDEDEl dispositivo no responde dentro del timeout de duración de respuesta
Comando bidireccional (respuesta recibida) Conectado y suscrito TERMINADOEl dispositivo envía los datos dentro del tiempo de espera de respuesta y completa el flujo

Paso 7: 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.