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
Para realizar los siguientes pasos, puede utilizar un dominio IoT y un grupo de dominios IoT existentes o crear un grupo de dominios IoT y un dominio IoT y, a continuación, realizar los siguientes pasos.
- Crear una instancia de gemelo digital
- Definir el comando en un archivo JSON
- Llamar al comando JSON sin formato
- El uso de MQTTX se conecta a un gemelo digital mediante un ID externo
- Suscribirse a un tema para recibir comandos
- Supervisar el estado de entrega del comando en APEX
- Ver la respuesta de un comando en MQTTX
Paso 1: Crear una instancia gemela digital
Uso de la CLI
- 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.
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
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
Paso 4: Utilice MQTTX para conectarse al dispositivo mediante un ID externo
- Descargue y configure MQTTX siguiendo estas instrucciones. Consulte Getting Started with MQTTX. Abra MQTTX.
- Seleccione + Nueva conexión para crear una nueva conexión.
- Introduzca el valor
<unique-id>
de la clave externa como Nombre de usuario. Puede encontrar la clave externa en la respuestaoci iot digital-twin-instance create
, del Paso 1: Creación de una instancia gemela digital anterior:"external-key": "<unique-id>"
- Introduzca la contraseña del dispositivo.
- 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. - Introduzca el puerto, por ejemplo:
8883
- Active el conmutador SSL/TLS.
- Active el conmutador SSL Secure.
- Para el certificado, seleccione la opción Certificado de servidor firmado por CA.
- Al configurar la conexión MQTTX, asegúrese de conectarse mediante un
clean session
y defina la opciónLast-Will-Retain
enfalse
para permitir que se retengan las suscripciones de cliente si el dispositivo se desconecta brevemente. - Defina Último valor de QoS en 1.
- 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.
Para ver una captura de pantalla más grande, haga clic con el botón derecho y abra una nueva pestaña.
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>
.
- En MQTTX, seleccione + Nueva suscripción.
- Introduzca el punto final como tema.
- En el menú desplegable QoS, seleccione 1 Al menos una vez.
- Seleccione Confirm (Confirmar).
- 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.
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.
- 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:Vaya a SQL Workshop y seleccione SQL Commands para consultar los datos IoT.
<domain-short-id-from-device-host>__IOT
- 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>'
- En Resultados, consulte RESPONSE_DATA:
{"test":1}

Paso 7: Ver la respuesta del comando en MQTTX
{
"test": 1
}
Para ver una captura de pantalla más grande, haga clic con el botón derecho y abra una nueva pestaña.