Documentação do Oracle Cloud Infrastructure

Cenário: receber comandos e enviar respostas usando MQTTs

Use este cenário para receber comandos na nuvem e enviar respostas a um dispositivo usando o protocolo MQTTs para interagir com seus dispositivos da Internet of Things (IoT).

Tarefas

Para concluir as etapas abaixo, você pode usar um domínio IoT e um grupo de domínios IoT existentes ou criar um grupo de domínios IoT e um domínio IoT e, em seguida, concluir as etapas a seguir.

  1. Criar uma instância de gêmeo digital
  2. Definir o comando em um arquivo JSON
  3. Chamar comando JSON bruto
  4. Usando a conexão MQTTX a um gêmeo digital usando um ID externo
  5. Inscrever-se em um tópico para receber comandos
  6. Monitore o status de entrega do comando no APEX
  7. Exibir a resposta de um comando no MQTTX

Etapa 1: Criar uma Instância Digital Twin

Usando a CLI

  1. Quando você cria uma instância de gêmeo digital, use um segredo ou um certificado para que a instância de gêmeo digital possa ser autenticada com segurança. Você deve criar um segredo ou criar um certificado para concluir este cenário. A Oracle recomenda o uso de um segredo para cada instância de gêmeo digital.

  2. Use o comando oci iot digital-twin-instance create e os parâmetros necessários para criar um gêmeo digital. O exemplo a seguir mostra o comando com os parâmetros de nome para exibição e ID de autenticação:

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

    Neste exemplo de resposta, observe o valor da chave externa. Use este valor de chave externa na Etapa 3: Usar MQTTX para Estabelecer Conexão Usando um ID Externo:

    "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>"
}

Etapa 2: Definir o Comando em um arquivo JSON

Você pode definir o comando em um arquivo JSON e usar esse arquivo na próxima etapa.

O arquivo command.json neste exemplo contém os seguintes comandos para chamar o comando e processar a resposta de acordo com as instruções no arquivo. 

{
  "requestEndpoint": "/endpoints/1234",
  "requestDuration": "PT3M",
  "requestDataFormat": "JSON",
  "requestData": {
    "temp": 33
  },
  "requestDataContentType": "application/json",
  "responseEndpoint": "/endpoints/4321",
  "responseDuration": "PT3M"
}
  • requestEndpoint: O caminho do URL /endpoints/1234 para o qual a solicitação será enviada. Em geral, esse é um ponto final de API ou um endereço no qual a Plataforma IoT faz listening dos comandos.
  • requestDuration: A duração permitida ou solicitada para a solicitação ser concluída, no formato de duração ISO 8601. PT3M que é igual a 3 minutos.
  • requestDataFormat: Especifica o formato de data dos dados enviados na solicitação JSON.
  • requestData: O payload JSON que é enviado com um par de valores de chave para definir um valor de temperatura no dispositivo:
    "temp": 33
Para obter informações, incluindo locais de arquivo e tipos de caminho, consulte Usando um Arquivo JSON para Entrada Complexa.

Etapa 3: Chamar um Comando JSON Bruto em um Dispositivo

Você pode usar a CLI ou a API para chamar um comando em um dispositivo. O exemplo a seguir usa a CLI.

Usando a CLI

Use o comando oci iot digital-twin-instance invoke-raw-json-command e os parâmetros para chamar um comando JSON bruto em um dispositivo.

Substitua o <digital-twin-instance-OCID> pelo OCID da instância do gêmeo digital na Etapa 1: Criar uma Instância do Digital Twin. Este exemplo mostra uma solicitação de um valor de temperatura do dispositivo usando o comando JSON bruto definido no arquivo command.json definido na Etapa 2: Definir o Comando em um arquivo 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 obter mais informações sobre outros tipos de comando, consulte Enviando um Comando Raw de uma Instância Digital Twin.

Etapa 4: Use o MQTTX para se conectar ao dispositivo usando um ID externo

Use qualquer cliente MQTT, este exemplo usa MQTTX com as seguintes configurações.
  1. Faça download e configure o MQTTX, siga estas instruções. Consulte Conceitos Básicos do MQTTX. Abra o MQTTX.
  2. Selecione + Nova Conexão para criar uma nova conexão.
  3. Informe o valor <unique-id> da chave externa como o Nome do Usuário. Você pode encontrar a chave externa na resposta oci iot digital-twin-instance create, na Etapa 1: Criar uma Instância Digital Twin anterior:
    "external-key": "<unique-id>"
  4. Insira a senha do dispositivo.
  5. Informe o Host. Selecione o protocolo mqtts:// na lista drop-down host e informe o host do dispositivo: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com no domínio IoT.
  6. Informe a porta. Por exemplo: 8883
  7. Ative a opção SSL/TLS.
  8. Ative a opção SSL Secure.
  9. Para o Certificado, selecione a opção Certificado do servidor assinado pela CA.
  10. Ao configurar a conexão MQTTX, certifique-se de estabelecer conexão usando um clean session e defina a opção Last-Will-Retain como false para permitir que as assinaturas do cliente sejam retidas se o dispositivo for desconectado brevemente.
  11. Defina o Último QoS como 1.
  12. Selecione Conexão.

Esta imagem mostra as configurações no MQTTX, clique com o botão direito do mouse e abra em uma nova guia para ver uma captura de tela maior.

Nas definições de MQTTX para chamar um comando.

Para ver uma captura de tela maior, clique com o botão direito do mouse e abra em uma nova aba.

Em MQTTX selecione conectar.

Etapa 5: Inscrever-se em um Tópico para Receber Respostas no MQTTX

Quando o sistema externo ou o dispositivo IoT publica uma mensagem no tópico inscrito, você exibe as mensagens de entrada no MQTTX nesse tópico. Se você estiver aguardando uma resposta de um comando anterior, certifique-se de estar inscrito no tópico de resposta correto que é definido dinamicamente na resposta da instância do gêmeo digital como o valor <external-id>.

  1. No MQTTX, selecione + Nova Assinatura.
  2. Informe o ponto final como o Tópico.
  3. No menu suspenso QoS, selecione 1 Pelo menos uma vez.
  4. Selecione Confirmar.
Use as seguintes definições de conexão para receber quaisquer mensagens publicadas em um ponto final de dispositivo para a instância de gêmeo digital com um ID externo específico:
  • ID do Cliente: your-client-ID
  • Username: ID Externo.
  • Senha: Informe a senha do dispositivo.
  • Digite mqtts:// com o host do dispositivo e o número da porta:

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

Para ver uma captura de tela maior, clique com o botão direito do mouse e abra em uma nova aba.No MQTTX, insira o ponto como o tópico e confirme a assinatura.

Etapa 6: Monitorar o Status de Entrega do Comando no APEX

Para exibir seus dados IoT no APEX, é necessário configurar o acesso aos seus dados. Após a conclusão dessa configuração, você poderá usar o APEX para trabalhar com seus dados IoT.

  1. No APEX, faça log-in no Espaço de Trabalho do domínio IoT específico usando o seguinte como nome do espaço de trabalho e nome do usuário do banco de dados. Observe os dois sublinhados no nome do esquema do banco de dados:
    <domain-short-id-from-device-host>__IOT
    Vá para SQL Workshop e selecione SQL Commands para consultar os dados IoT.
  2. Digite o seguinte comando, substitua <digital-twin-instance-OCID> pelo OCID do gêmeo digital e selecione Executar para consultar os dados do comando bruto: 
    select * from raw_command_data
where digital_twin_instance_id='<digital-twin-instance-OCID>'
  3. Em Resultados, exiba o RESPONSE_DATA:
    {"test":1}
Para ver uma captura de tela maior, clique com o botão direito do mouse e abra em uma nova aba.Exiba os dados de resposta do dispositivo no APEX.

Etapa 7: Exibir a Resposta do Comando no MQTTX

No MQTTX, selecione conectar para exibir a resposta:
{
    "test": 1
  }

Para ver uma captura de tela maior, clique com o botão direito do mouse e abra em uma nova aba.

Em MQTTX, visualize os dados de resposta do comando.