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

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 usar um segredo para cada instância de gêmeo digital e, para produção, a instância de gêmeo digital deve usar um certificado mTLS para autenticação.

  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 como usar o parâmetro ID de autenticação com o parâmetro de domínio IoT necessário para associar o domínio IoT à instância do gêmeo digital:

    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 e observe a chave externa que é o nome de usuário do dispositivo que você pode usar na próxima etapa:

    "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: Estabelecer a sessão MQTT usando credenciais do broker

Use qualquer cliente MQTT. Este exemplo usa o 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 Mais de Nova Conexão para criar uma nova conexão. Insira um nome para a conexão, evitando inserir informações confidenciais.
  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. Se você usar o segredo do vault, esse deverá ser o segredo de texto sem formatação ou poderá usar um certificado mTLS.
  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. Consulte Obtendo Detalhes de um Domínio IoT.
  6. Informe a porta. Por exemplo: 8883
    Observação

    Atualmente, o MQTT Secure (MQTTS) só é suportado usando a porta 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 conectar usando:
    • clean session: Defina a opção de limpeza de sessão como true. Quando a sessão limpa é definida como verdadeira, o broker não retém nenhuma informação para o cliente e descarta qualquer estado anterior de qualquer sessão persistente. Todos os dados da sessão são excluídos assim que a conexão de rede é fechada.
    • Defina a opção Last-Will-Retain como false para permitir que as assinaturas do cliente sejam mantidas se o dispositivo for desconectado brevemente.
  11. Defina o Último QoS como 1. Definir a confiabilidade da entrega "Pelo menos uma vez" para sua notificação de desconexão.
  12. Selecione Conexão.

Esta imagem mostra essas 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.

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

Quando um sistema externo ou um dispositivo IoT publica uma mensagem no tópico inscrito, no MQTTX, você exibe as mensagens de entrada nesse tópico. Se você estiver aguardando uma resposta de um comando anterior, certifique-se de estar inscrito no tópico de resposta correto.

Defina o responseEndpoint na próxima etapa quando definir o comando em um arquivo JSON. A string "responseEndpoint": "/endpoints/4321" representa o caminho do tópico ou do ponto final em que o dispositivo deve publicar sua resposta. Escolha qualquer caminho de ponto final lógico para suas rotas de gêmeos digitais. Use o mesmo caminho no lado da nuvem (ao enviar o comando) e no lado do dispositivo (ao publicar a resposta).

  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 do domínio IoT e usando o número de porta 8883:

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

Para ver uma captura 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 4: Definir o Comando em um arquivo JSON

Você pode definir os detalhes do comando em um arquivo JSON e usar esse arquivo na próxima etapa para Chamar um Comando JSON Bruto em um Dispositivo.

Para este exemplo, salve este trecho de código em um arquivo command.json para que você possa usá-lo 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.

    Se você já tiver um ponto final dedicado a respostas, por exemplo: /endpoints/<external-id>/response use esse caminho em responseEndpoint.

    Ou crie um novo endpoint/route para a instância do gêmeo digital nas regras de roteamento de entrada do adaptador do gêmeo digital para as quais o dispositivo pode publicar. Faça referência a esse caminho no arquivo command.json. Mantenha o caminho do ponto final consistente. Qualquer caminho definido em responseEndpoint se tornará o tópico MQTT que seu cliente deverá se inscrever na Etapa 3 para que você possa ver a resposta do comando.

  • requestDuration: A duração permitida ou solicitada para a solicitação ser concluída, no formato de duração ISO 8601. Por exemplo, PT3M é 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 5: 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. 

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

No MQTTX, observe os dados chamados:
{
    "temp": 33
  }

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.

Esta imagem mostra como verificar no MQTTX.

Cenários de Resposta do Comando
CenárioEstado do DispositivoEstado de Comando EsperadoComentários
Não ConectadoNão conectado inscrito RECUSADO A entrega do comando falha imediatamente
Conectado mas não inscritoConectado RECUSADODispositivo on-line, mas não recebe comando
Inscrito, mas não conectado Inscrito somentePENDENTE → EXPIRADOO comando aguarda; expira após o timeout
Inscrito, mas não conectado inicialmente e é conectado antes do timeout Inicialmente off-line PENDENTE → ENVIADOComando Recebido
Conectado e inscritoConectado e inscrito Enviado Comando Recebido
Comando Unidirecional (Nenhuma resposta esperada)Conectado e inscrito CONCLUÍDO A resposta não é esperada e rastreada
Comando bidirecional (Nenhuma resposta recebida)Conectado e inscrito NOT_RESPONDEDO dispositivo não responde dentro do tempo limite de duração da resposta
Comando bidirecional (resposta recebida) Conectado e inscrito CONCLUÍDOO dispositivo envia dados dentro do tempo limite de resposta e conclui o fluxo

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