Documentação do Oracle Cloud Infrastructure

Cenário: Criar Gêmeos Digitais para Dispositivos Conectados Indiretamente Usando um Gateway

Crie modelos de gêmeos digitais, adaptadores, um gateway, instâncias de gêmeos digitais de dispositivos diretos e indiretos para que você possa rotear telemetria e comandos por meio de um gateway compartilhado.

Use este cenário para criar um gateway reutilizável, um dispositivo conectado diretamente e vários dispositivos conectados indiretamente.

Para ilustrar esse cenário, os exemplos modelam um pequeno sistema de aquecimento, ventilação e ar condicionado (HVAC) de edifícios, incluindo:
  • Um gateway denominado Bosch Gateway 1 se autentica no domínio da IoT e coleta ou roteia dados para dispositivos como unidades HVAC, caldeiras e desumidificadores.
  • A instância do HVAC conectada diretamente mostra um dispositivo que envia sua própria telemetria.
  • As instâncias de HVAC, caldeira e desumidificador indiretamente conectados mostram dispositivos cuja telemetria e comandos se movem pelo gateway.

Para obter mais conceitos, consulte Perguntas Frequentes sobre Dispositivos Conectados Indiretamente.

Revise o diagrama para entender como o gateway, dispositivos conectados diretamente e dispositivos conectados indiretamente interagem com os 3 tipos de instâncias de gêmeos digitais.

instâncias duplas digitais

Etapa 1: Criar Modelos Gêmeos Digitais

Crie um modelo de gêmeo digital para o gateway e um modelo de gêmeo digital para cada tipo de dispositivo no cenário. Esses dispositivos emitem dados estruturados.

Use os trechos de código abaixo para salvar estes arquivos: gateway-model.json, hvac-model.json e boiler-model.json.

  • Use a Console quando quiser fazer upload de um arquivo de modelo salvo ou colar a especificação diretamente.

    1. Na página da lista Domínios IoT, abra o domínio com o qual você deseja trabalhar. Se precisar de ajuda para localizar a página de lista de domínios IoT, consulte Listando Domínios IoT ou Criar um novo Domínio IoT.
    2. Selecione a guia Modelos gêmeos digitais e selecione Criar.
    3. Informe um nome e uma descrição opcional. Evite digitar informações confidenciais.
    4. Escolha Fazer upload da especificação ou Colar especificação e, em seguida, use um dos arquivos de exemplo deste cenário.
    5. Opcional: Adicione tags.
    6. Selecione Criar.

    Use um dos arquivos a seguir ao fazer upload ou colar a especificação.

    gateway-model.json
    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:gateway;1",
  "@type": "Interface",
  "displayName": "Gateway",
  "description": "A digital twin model for Gateway",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "cpuUtilization",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "memoryUtilization",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "storageUtilization",
      "schema": "integer"
    },
    {
      "@type": "Property",
      "name": "firmwareVersion",
      "schema": "string"
    }
  ]
}
    hvac-model.json
    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1",
  "@type": "Interface",
  "displayName": "HVAC",
  "description": "A digital twin model for HVAC",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "humidity",
      "schema": "integer"
    }
  ]
}
    boiler-model.json
    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:boiler;1",
  "@type": "Interface",
  "displayName": "Boiler",
  "description": "A digital twin model for Boiler",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "pressure",
      "schema": "integer"
    }
  ]
}

  • Use o comando oci iot digital-twin-model create para criar cada modelo de gêmeo digital no domínio IoT.

    Criar o modelo de gateway

    oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://gateway-model.json

    Criar o modelo HVAC

    oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://hvac-model.json

    Criar o modelo de caldeira

    oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://boiler-model.json

    Para este exemplo, salve esses trechos de código nesses arquivos de modelo, gateway-model.json, hvac-model.json e boiler-model.json.

    gateway-model.json
    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:gateway;1",
  "@type": "Interface",
  "displayName": "Gateway",
  "description": "A digital twin model for Gateway",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "cpuUtilization",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "memoryUtilization",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "storageUtilization",
      "schema": "integer"
    },
    {
      "@type": "Property",
      "name": "firmwareVersion",
      "schema": "string"
    }
  ]
}
    hvac-model.json
    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1",
  "@type": "Interface",
  "displayName": "HVAC",
  "description": "A digital twin model for HVAC",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "humidity",
      "schema": "integer"
    }
  ]
}
    boiler-model.json
    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:boiler;1",
  "@type": "Interface",
  "displayName": "Boiler",
  "description": "A digital twin model for Boiler",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "pressure",
      "schema": "integer"
    }
  ]
}

  • Execute a operação CreateDigitalTwinModel para criar um modelo de gêmeo digital no domínio IoT.

    Use o mesmo payload de DTDL mostrado nos arquivos de modelo de gêmeo digital de exemplo quando chamar a API.

Etapa 2: Criar Adaptadores Gêmeos Digitais

Crie um adaptador para o gateway e um adaptador para cada tipo de dispositivo estruturado que precise de mapeamento de payload.

Use os trechos de código abaixo para salvar estes arquivos: gateway-envelope.json, gateway-routes.json, hvac-envelope.json, hvac-routes.json, boiler-envelope.json e boiler-routes.json.

Resolver o destino no envelope de entrada

Os adaptadores de gateway podem identificar a instância de gêmeo digital de destino quando todas as mensagens de dispositivo encaminhadas seguem o mesmo tópico ou convenção de payload. O gateway se autentica como ele mesmo, o serviço verifica se o destino resolvido é uma instância de gêmeo digital indiretamente conectada associada a esse gateway e, em seguida, o serviço delega o payload ao adaptador do dispositivo de destino quando o mapeamento estruturado é necessário.

O gateway resolve target e contentRoot uma vez para toda a mensagem antes da execução das rotas. Se o target for resolvido como uma chave externa de dispositivo conectado indiretamente, o payload será delegado a esse dispositivo. Se target estiver vazio ou for nulo, a mensagem será tratada como dados do gateway.

  • Use um adaptador de gêmeo digital quando o payload de entrada tiver que ser mapeado para o modelo de gêmeo digital de destino. Um adaptador de gêmeo digital não é necessário quando o dispositivo envia dados não estruturados, você pode passar os dados inalterados.

    1. Na página da lista Domínios IoT, abra o domínio com o qual você deseja trabalhar.
    2. Selecione a guia Adaptadores gêmeos digitais e, em seguida, selecione Criar.
    3. Informe um Nome e uma Descrição opcional. Evite digitar informações confidenciais.
    4. Selecione o modelo de gêmeo digital que corresponde ao payload que você está mapeando.
    5. Ative Especificar envelope de entrada e rotas e faça upload ou cole o JSON do envelope e roteie o JSON para o adaptador.
    6. Opcional: Adicione tags.
    7. Selecione Criar.

    Crie o adaptador de gateway com esses arquivos de gateway.

    gateway-envelope.json
    {
  "referenceEndpoint": "/data",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "cpuUtil": 0,
      "memUtil": 0,
      "diskUtil": 0,
      "firmware": "Oracle Linux 9.1"
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time",
    "target": "${if ([\"boilers\", \"hvacs\", \"dehumidifiers\"] | contains([endpoint(1)])) then endpoint(2) else null end}",
    "contentRoot": "$"
  }
}
    gateway-routes.json
    [
  {
    "condition": "*",
    "payloadMapping": {
      "$.cpuUtilization": "$.cpuUtil",
      "$.memoryUtilization": "$.memUtil",
      "$.storageUtilization": "$.diskUtil",
      "$.firmwareVersion": "$.firmware"
    }
  }
]

    Crie os adaptadores HVAC e caldeira com os arquivos de dispositivo correspondentes.

    hvac-envelope.json
    {
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temperature": 0,
      "humidity": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}
    hvac-routes.json
    [
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.humidity": "$.humidity"
    }
  }
]
    boiler-envelope.json
    {
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "timestamp": 1773768299143534,
      "temperature": 0,
      "pressure": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.timestamp"
  }
}
    boiler-routes.json
    [
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.pressure": "$.pressure"
    }
  }
]

  • Use o comando oci iot digital-twin-adapter create para criar cada adaptador no domínio IoT.

    Criar o adaptador de gateway

    Use este comando para criar um adaptador de gêmeo digital. Este exemplo mostra como associar o modelo de gêmeo digital usando o DTMI e como definir o envelope e as rotas usando arquivos .json. 

    oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:gateway;1" \
  --inbound-envelope file://gateway-envelope.json \
  --inbound-routes file://gateway-routes.json
    gateway-envelope.json
    {
  "referenceEndpoint": "/data",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "cpuUtil": 0,
      "memUtil": 0,
      "diskUtil": 0,
      "firmware": "Oracle Linux 9.1"
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time",
    "target": "${if ([\"boilers\", \"hvacs\", \"dehumidifiers\"] | contains([endpoint(1)])) then endpoint(2) else null end}",
    "contentRoot": "$"
  }
}
    gateway-routes.json
    [
  {
    "condition": "*",
    "payloadMapping": {
      "$.cpuUtilization": "$.cpuUtil",
      "$.memoryUtilization": "$.memUtil",
      "$.storageUtilization": "$.diskUtil",
      "$.firmwareVersion": "$.firmware"
    }
  }
]

    Criar o adaptador HVAC

    Use este comando para criar um adaptador de gêmeo digital. Este exemplo mostra como associar o modelo de gêmeo digital usando o DTMI e como definir o envelope e as rotas usando arquivos .json. 

    oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:hvac;1" \
  --inbound-envelope file://hvac-envelope.json \
  --inbound-routes file://hvac-routes.json
    hvac-envelope.json
    {
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temperature": 0,
      "humidity": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}
    hvac-routes.json
    [
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.humidity": "$.humidity"
    }
  }
]

    Criar o adaptador de caldeira

    Use este comando para criar um adaptador de gêmeo digital. Este exemplo mostra como associar o modelo de gêmeo digital usando o DTMI e como definir o envelope e as rotas usando arquivos .json. 

    oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:boiler;1" \
  --inbound-envelope file://boiler-envelope.json \
  --inbound-routes file://boiler-routes.json
    boiler-envelope.json
    {
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "timestamp": 1773768299143534,
      "temperature": 0,
      "pressure": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.timestamp"
  }
}
    boiler-routes.json
    [
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.pressure": "$.pressure"
    }
  }
]

    Para obter mais informações sobre como fazer referência a arquivos da CLI, consulte Usando um Arquivo JSON para Entrada Complexa.

  • Execute a operação CreateDigitalTwinAdapter para criar um adaptador de gêmeo digital no domínio IoT.

    Use o mesmo envelope de entrada e payloads de rotas de entrada mostrados nos arquivos de exemplo.

Etapa 3: Criar as Instâncias do Gateway e do Dispositivo

Crie o gateway primeiro para que você possa reutilizá-lo quando criar os dispositivos conectados indiretamente.

Opções de ID de autenticação:

  • Para testar instâncias de gêmeos digitais, se você usar o OCID do segredo como o ID de autenticação, use o nome de usuário do dispositivo como a chave externa e o conteúdo do segredo de texto sem formatação como a senha do dispositivo. Para obter instruções, quando você Criar um Segredo, consulte a Etapa 7 e, para saber quais segredos já foram criados, consulte Obtendo o Conteúdo de um Segredo.

  • Para instâncias de gêmeos digitais de produção, use o OCID do certificado mTLS em vez de um segredo de vault como o ID de autenticação. Ao usar um certificado mTLS, você precisará usar o nome comum dos detalhes do certificado como a chave externa: --external-key <common-name-from-certificate-details>

  • Use a Console para criar um gateway e associar vários dispositivos a ele.

    Na Console, há duas maneiras de criar um gateway para o domínio IoT. Você pode criar um gateway na guia Instância de gêmeo digital, selecionando o tipo de gateway ao criar uma instância de gêmeo digital. Ou você pode selecionar a guia Gateway para criar o gateway.

    1. Na página de lista Domínios IoT, abra o domínio IoT com o qual você deseja trabalhar.
    2. Selecione a guia Gateways e, em seguida, selecione Criar para criar uma Instância do Gateway Bosch para que ela esteja disponível para dispositivos indiretos.
      • Informe um Nome para o gateway e uma Descrição.
      • Informe o gateway1 da chave externa.
      • Selecione o adaptador que usa o gateway-envelope.json e o gateway-routes.json criados na Etapa 2.
      • Selecione o ID de autenticação ou cole o OCID do ID de autenticação e selecione Criar.
    3. Na página Domínio IoT, selecione a guia Instâncias gêmeas digitais, selecione Criar e, em seguida, selecione diretamente conectado ou indiretamente conectado como o tipo para criar as instâncias gêmeas digitais para esses dispositivos, usando o modelo e os adaptadores criados na Etapa 1 e na Etapa 2 para:
      • conectou diretamente a instância LG HVAC com a chave externa hvac1.
      • instância HVAC conectada indiretamente com a chave externa hvac2
      • instância de caldeira conectada indiretamente com a chave externa boiler1.
      • indiretamente conectado à instância do desumidificador com a chave externa dehumidifier1. O desumidificador não usa um adaptador de gêmeo digital ou modelo de gêmeo digital, pois envia telemetria bruta não estruturada que não precisa de mapeamento de carga útil estruturada. Ele também pode receber comandos de rastreamento por meio do gateway.
      Observação

      Se você não informar uma chave externa, ela será gerada.
    4. Para a instância conectada diretamente e o gateway, selecione um ID de autenticação.
    5. Para uma instância conectada indiretamente, selecione um ou mais gateways existentes em vez de adicionar credenciais de autenticação de dispositivo. Selecione mais de um gateway quando um dispositivo sem fio puder percorrer entre gateways.
    6. Opcional: Adicione tags.
    7. Revise o resumo da instância do gêmeo digital e selecione Criar.
    Depois de criar as instâncias de gêmeos digitais, use a página Detalhes do gateway para exibir quais dispositivos dependem e estão associados ao gateway.
    • Localize os Detalhes do gateway na página de domínio do IoT, selecionando a guia Gateway para exibir a lista de gateway, selecione um gateway para ir até a página de detalhes do Gateway.
    • Na guia Instância de gêmeo digital, você pode pesquisar por tipo para exibir os diferentes tipos de instância de gêmeo digital de um domínio IoT.
    • Exiba os dispositivos conectados direta e indiretamente na página de detalhes da instância gêmea digital.

    Para obter uma lista completa de definições, consulte Criando uma Instância Digital Twin, Listando Instâncias Digital Twin e Obtendo Detalhes da Instância de um Digital Twin.

  • Use o comando oci iot digital-twin-instance create para criar o gateway e as instâncias de dispositivo conectadas diretamente e indiretamente.

    Criar a instância HVAC conectada diretamente

    Use este comando para criar uma instância de gêmeo digital associada a um domínio IoT específico e que esteja diretamente conectada, usando uma chave externa hvac1.

    oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type DIRECT \
  --display-name "LG HVAC 1" \
  --auth-id <certificate-or-secret-OCID> \
  --digital-twin-adapter-id <hvac-adapter-OCID> \
  --external-key hvac1

    Criar a instância do gateway

    Use este comando para criar uma instância de gêmeo digital associada a um domínio IoT específico, use o parâmetro --connectivity-type necessário com o valor GATEWAY para criar uma instância de gêmeo digital que seja um gateway. A chave externa é gateway1.

    oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type GATEWAY \
  --display-name "Bosch Gateway 1" \
  --auth-id <certificate-or-secret-OCID> \
  --digital-twin-adapter-id <gateway-adapter-OCID> \
  --external-key gateway1

    Criar a instância HVAC conectada indiretamente

    Use este comando e o parâmetro necessário --connectivity-type INDIRECT para criar um gêmeo digital que seja um dispositivo conectado indiretamente. Este cenário mostra uma associação de gateway por dispositivo. Quando sua implantação suportar roaming, associe o dispositivo conectado indiretamente a mais de um gateway para que ele possa se mover entre eles sem alterar a instância do gêmeo digital.
    Observação

    Quando você cria um dispositivo conectado indiretamente usando o parâmetro --gateways necessário, ele é um tipo complexo e deve usar um array JSON. Por exemplo: --gateways '["<gateway-instance-OCID>"]' ou para roaming, use --gateways '["<gateway-instance-1-OCID>","<gateway-instance-2-OCID>"]'. Como alternativa, você pode usar um arquivo .json.
    oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name "LG HVAC 2" \
  --gateways '["<gateway-instance-OCID>"]' \
  --digital-twin-adapter-id <hvac-adapter-OCID> \
  --external-key hvac2

    Criar a instância de caldeira conectada indiretamente

    Use este comando e o parâmetro necessário --connectivity-type INDIRECT para criar um gêmeo digital que seja um dispositivo conectado indiretamente.

    oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name "GE Boiler 1" \
  --gateways '["<gateway-instance-OCID>"]' \
  --digital-twin-adapter-id <boiler-adapter-OCID> \
  --external-key boiler1

    Criar a instância do desumidificador conectado indiretamente

    Use este comando e o parâmetro necessário --connectivity-type INDIRECT para criar um gêmeo digital que seja um dispositivo conectado indiretamente.

    oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name Danby Dehumidifier 1 \
  --gateways '["<gateway-instance-OCID>"]' \
  --external-key dehumidifier1

  • Execute a operação CreateDigitalTwinInstance para criar uma instância de gateway, uma instância conectada diretamente e uma instância conectada indiretamente.

    Ao criar uma instância conectada indiretamente, certifique-se de que a solicitação inclua a associação do gateway.

Etapa 4: Enviar Dados de Telemetria

Estes exemplos mostram três caminhos de dados. Um dispositivo conectado diretamente, como hvac1, se autentica com sua própria chave externa e envia dados para sua própria instância de gêmeo digital. O gateway, gateway1, também se autentica com sua própria chave externa quando envia sua própria CPU, memória, armazenamento e telemetria de firmware.

Os dispositivos conectados indiretamente não se autenticam no domínio IoT; o gateway se autentica como gateway1 e o caminho do ponto final, como hvacs/hvac2, boilers/boiler1 ou dehumidifiers/dehumidifier1, identifica o dispositivo de destino por trás do gateway.

    1. Instale e configure o MQTTX.

    2. Use o <digital-twin-instance-external-key> como nome de usuário do dispositivo. Se precisar localizar a chave externa da instância digital, você poderá Obtendo Detalhes da Instância de um Gêmeo Digital.
    3. Conecte-se ao <domain-short-id>.device.iot.<region>.oci.oraclecloud.com na porta 8883, ative o SSL/TLS e use uma sessão limpa.

    Enviar telemetria da instância HVAC conectada diretamente:

    mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'data' \
  -m '{
    "temperature": 70,
    "humidity": 60
  }' \
  -u hvac1 \
  -P '<secret-contents>'

    Enviar telemetria da instância do gateway:

    mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'data' \
  -m '{
    "cpuUtil": 30,
    "memUtil": 25,
    "diskUtil": 20,
    "firmware": "Oracle Linux 9.1"
  }' \
  -u gateway1 \
  -P '<secret-contents>'

    Enviar telemetria para a instância HVAC conectada indiretamente por meio do gateway:

    mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'hvacs/hvac2' \
  -m '{
    "temperature": 75,
    "humidity": 65
  }' \
  -u gateway1 \
  -P '<secret-contents>'

    Enviar telemetria para a instância de caldeira conectada indiretamente por meio do gateway:

    mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'boilers/boiler1' \
  -m '{
    "temperature": 80,
    "pressure": 90
  }' \
  -u gateway1 \
  -P '<secret-contents>'

    Enviar telemetria para a instância de desumidificador conectada indiretamente por meio do gateway:

    mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'dehumidifiers/dehumidifier1' \
  -m 'humidity=50,fanSpeed=medium' \
  -u gateway1 \
  -P '<secret-contents>'

  • Use curl para enviar telemetria por HTTPS. Esses exemplos usam autenticação básica HTTP com a chave externa da instância do gêmeo digital e o conteúdo do segredo de texto sem formatação.

    1. Use a chave externa da instância do gêmeo digital como nome de usuário. Por exemplo, para a telemetria conectada diretamente, use a chave externa da instância, como hvac1.
    2. Use o conteúdo do segredo de texto sem formatação como a senha.
    3. Envie a solicitação para https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/<endpoint-path>.
    4. Para dispositivos conectados indiretamente, faça a autenticação como instância do gateway e use o caminho do ponto final para identificar o dispositivo de destino, como hvacs/hvac2 ou boilers/boiler1.

    Enviar telemetria da instância HVAC conectada diretamente:

    curl -i -u "hvac1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/data" \
  -d '{
    "temperature": 70,
    "humidity": 60
  }'

    Enviar telemetria da instância do gateway:

    curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/data" \
  -d '{
  "cpuUtil": 30,
  "memUtil": 25,
  "diskUtil": 20,
  "firmware": "Oracle Linux 9.1"
}'

    Enviar telemetria para a instância HVAC conectada indiretamente por meio do gateway:

    curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/hvacs/hvac2" \
  -d '{
    "temperature": 75,
    "humidity": 65
  }'

    Enviar telemetria para a instância de caldeira conectada indiretamente por meio do gateway:

    curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/boilers/boiler1" \
  -d '{
    "temperature": 80,
    "pressure": 90
  }'

    Enviar telemetria para a instância de desumidificador conectada indiretamente por meio do gateway:

    curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: text/plain" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/dehumidifiers/dehumidifier1" \
  -d 'humidity=50,fanSpeed=medium'

Etapa Opcional 5: Obter o Conteúdo da Instância de um Gêmeo Digital

Para confirmar se os dados da instância do gêmeo digital são capturados, use a Console, a CLI ou a API para exibir o conteúdo da instância do gêmeo digital. Esses são os dados de snapshot mais recentes.

Para uma instância de gêmeo digital de dados não estruturados, ela geralmente não tem um modelo de gêmeo digital associado, portanto, você não pode usar o conteúdo obtido para uma instância de gêmeo digital para exibir seus dados.

    1. Na página de lista Domínios, selecione o domínio com o qual você deseja trabalhar. Se precisar de ajuda para localizar a página de lista de domínios IoT ou um domínio IoT, consulte Listando Domínios IoT.
    2. Selecione a guia Instâncias gêmeas digitais.
    3. Selecione o nome da instância gêmea digital. A página de detalhes será aberta.
    4. Selecione a guia Dados para exibir os dados de snapshot mais recentes dessa instância. Para obter mais informações, consulte Referência de Esquema do Banco de Dados do Domínio IoT.

  • Use o comando oci iot digital-twin-instance get-content e o parâmetro necessário para obter o conteúdo da instância de um gêmeo digital:

    Verifique a instância HVAC conectada diretamente:

    oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <lg-hvac-1-OCID>

    Verifique a instância do gateway:

    oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <bosch-gateway-1-OCID>

    Verifique a instância HVAC conectada indiretamente:

    oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <lg-hvac-2-OCID>

    Verifique a instância de caldeira conectada indiretamente:

    oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <ge-boiler-1-OCID>

  • Execute a operação GetDigitalTwinInstanceContent para obter conteúdo de uma instância de gêmeo digital.

Etapa 6: Chamar Comandos

Para dispositivos conectados indiretamente, use uma política de entrega at-least-once e espere novas tentativas ou entrega duplicada.

Quando uma resposta for necessária, configure um ponto final de resposta para que o gateway possa publicar a resposta em nome do dispositivo de destino.

  • Use a Console quando quiser enviar um comando bruto da página de detalhes da instância do gêmeo digital.

    1. Abra o domínio IoT e selecione a guia Instâncias gêmeas digitais.
    2. Selecione a instância que você deseja controlar.
    3. No menu Ações, selecione Enviar comando bruto.
    4. Informe o ponto final da solicitação, a duração da solicitação e o payload do comando.
    5. Opcional: Configure um ponto final de resposta e a duração da resposta e selecione Enviar comando bruto. Use os valores destes arquivos: gateway-command.json, boiler-command.json
    gateway-command.json
    {
  "force": true
}
    boiler-command.json
    {
  "hardReset": false
}

  • Use o comando oci iot digital-twin-instance invoke-raw-json-command para chamar as ações de exemplo neste cenário. Para obter mais informações, consulte Enviando um Comando Bruto de uma Instância Digital Twin.

    Reinicialize a instância do gateway

    oci iot digital-twin-instance invoke-raw-json-command \
  --digital-twin-instance-id <bosch-gateway-1-OCID> \
  --request-endpoint "actions/reboot" \
  --request-data '{"force": true}'

    Redefinir a instância de caldeira conectada indiretamente

    Especifique o --request-endpoint, neste exemplo que é boilers/boiler1/actions/reset.

    Especifique o --response-endpoint, neste exemplo que é boilers/boiler1/actions/response.

    Se você esperar uma resposta, inclua o parâmetro --response-duration. Caso contrário, o comando fará a transição para um estado COMPLETED sem receber a resposta. Como resultado, a resposta do comando não é capturada na tabela de banco de dados RAW_COMMAND_DATA.

    oci iot digital-twin-instance invoke-raw-json-command \
  --digital-twin-instance-id <ge-boiler-1-OCID> \
  --request-endpoint "boilers/boiler1/actions/reset" \
  --request-data '{"hardReset": false}' \
  --response-endpoint "boilers/boiler1/actions/response" \
  --response-duration PT10M

    Publicar a resposta da caldeira

    Use o ponto final de resposta para publicar a resposta da caldeira para este ponto final: boilers/boiler1/actions/response neste exemplo gateway1 é a chave externa e o nome do usuário do dispositivo.

    mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t "boilers/boiler1/actions/response" \
  -m '{
    "status": "OK"
  }' \
  -u gateway1 \
  -P '<secret-contents>'

    Desligue o ventilador de desumidificador indiretamente conectado

    Use este comando para chamar um comando JSON bruto no dispositivo que desliga o ventilador no desumidificador. 

    oci iot digital-twin-instance invoke-raw-json-command \
  --digital-twin-instance-id <danby-dehumidifier-1-OCID> \
  --request-endpoint "dehumidifiers/dehumidifier1/actions/fanOff" \
  --request-data '{"fanOff": true}'

  • Execute a operação InvokeRawCommand para chamar um comando bruto em um dispositivo.

    Use um ponto final de resposta quando o comando deve retornar uma confirmação no nível do aplicativo.

Escolha o Tipo de Conectividade Certo para sua Instância Digital Twin

Como decidir qual tipo de conectividade usar para uma instância de gêmeo digital:

Conectado Diretamente

Usar quando
O dispositivo se conecta ao domínio IoT por conta própria.
Parâmetro obrigatório
ID de Autenticação. Para teste, use um segredo e para produção use certificado mTLS.
Obrigatório para dados estruturados
Um adaptador de gêmeo digital correspondente ao modelo de gêmeo digital pode ser fornecido ou inferido do adaptador, e o modelo deve conter pelo menos uma telemetria, propriedade ou comando.
Para dados não estruturados
Não use um adaptador de gêmeo digital ou modelo de gêmeo digital.
Entrada opcional
Chave externa, se você não fornecer uma externa, o serviço gerará uma. Use o nome de usuário do dispositivo.
Não usar
Associação de gateway com um dispositivo conectado diretamente.

Gateway

Usar quando
Um dispositivo encaminha dados e comandos para si e para outros dispositivos.
Parâmetros obrigatórios
ID de autenticação e um adaptador de gateway. As instâncias do gateway não suportam telemetria não estruturada; portanto, o adaptador é necessário.
Modelo Gêmeo Digital
O modelo de gêmeo digital do gateway pode ser associado ou inferido do adaptador de gêmeo digital, e o modelo deve conter pelo menos uma telemetria, propriedade ou comando. Você pode criar uma instância de gêmeo digital com um adaptador sem especificar o modelo. Um modelo é associado por meio do adaptador.
Para dados não estruturados, geralmente você não usa um adaptador ou um modelo.
Entrada opcional
Chave externa, se você não fornecer uma, o serviço gerará uma.
Recomendado
Antes de alterá-lo ou excluí-lo, revise a página gateway details para ver quantos dispositivos dependem do gateway.
Não
Associar uma instância de gateway a outra instância de gateway.

Conectado Indiretamente

Usar quando
Outro dispositivo, geralmente um gateway, envia dados de telemetria e recebe comandos em nome do dispositivo.
Obrigatório
Uma ou mais associações de gateway são obrigatórias. Use mais de um gateway quando um dispositivo sem fio puder percorrer entre gateways. Confirme com um administrador se isso funciona no seu ambiente.
Para dados estruturados
Para dados estruturados, é necessário um adaptador de gêmeo digital. O modelo de gêmeo digital correspondente pode ser fornecido ou inferido do adaptador, especificando o DTMI ou o OCID do modelo de gêmeo digital, o modelo deve conter pelo menos uma telemetria, propriedade ou comando.
Para dados não estruturados
Para dados não estruturados, não use um adaptador de gêmeo digital ou um modelo de gêmeo digital. Não é possível obter conteúdo para dados não estruturados, pois eles não contêm um modelo de gêmeo digital.
Entrada opcional
Chave externa, se você não fornecer uma chave externa, o serviço gerará uma.
ID de Autenticação
Não use um ID de autenticação para uma instância digital twin conectada indiretamente.

Não Conectado

Usar quando
Testando uma instância de gêmeo digital que não autentica, envia ou recebe dados do dispositivo para que você possa testar relacionamentos de gêmeos digitais para testar sua configuração IoT sem a complexidade dos dados ou autenticação.
Obrigatório
Para dados estruturados, é necessário um modelo de gêmeo digital e não deve conter telemetria, propriedades ou comandos.
Opcional
Relações de gêmeos digitais para teste. Para obter mais informações, consulte Relacionamentos Gêmeos Digitais.
Não usar
ID de autenticação, chave externa, adaptador de gêmeo digital, associação de gateway ou dados de dispositivo em instâncias de gêmeo digital que não estão conectadas.

Perguntas Frequentes

Esta FAQ descreve as histórias de usuário do gateway descritas neste cenário.

Posso configurar uma instância de gêmeo digital para ser conectada indiretamente para que outro dispositivo envie dados em seu nome?
Sim. Crie a instância do gêmeo digital para o dispositivo com o tipo de conectividade INDIRECT e associe-a a uma ou mais instâncias do gêmeo digital de gateway em vez de fornecer ao dispositivo seu próprio ID de autenticação.
Como posso saber quais dispositivos estão conectados por meio de um gateway específico e entender o impacto da perda desse gateway?
Use a página de detalhes do gateway para revisar a contagem de dispositivos associados e a lista de instâncias de gêmeos digitais dependentes. Isso dá a você a visão mais rápida do raio de explosão do gateway antes das operações de manutenção, migração ou exclusão.
Como sei quantas das minhas instâncias de gêmeos digitais estão conectadas diretamente, indiretamente ou gateways?
Na página de lista da instância Digital Twin ou na página de lista Gateway, você pode encontrar a lista de gateways.
Revise o tipo de conectividade de instância de gêmeo digital para cada gêmeo digital e use um gateway de nível de domínio e views de topologia para obter insights sobre seu ambiente. Este cenário mostra um dispositivo direto, um gateway e vários dispositivos indiretos para que você possa comparar os três padrões.
Como posso configurar um adaptador para meu gateway para que a telemetria de entrada seja roteada para o dispositivo de destino correto?
Use um adaptador de gêmeo digital para o gateway que inclua um mapeamento target no envelope. Consulte Etapa 2: Criar Adaptadores Gêmeos Digitais.
Quando devo colocar target nas rotas de entrada em vez de no envelope de entrada?
Não. Coloque target no envelope de entrada.
O que acontece se target estiver vazio ou for nulo?
A mensagem é tratada como dados de gateway em vez de ser delegada a um dispositivo indiretamente conectado.
Um adaptador de gateway pode lidar com telemetria de gateway e telemetria de dispositivo indiretamente conectado?
Sim. Esse é o principal objetivo do roteamento de gateway. As mensagens do dispositivo encaminhadas vão para um destino resolvido, enquanto os dados de destino sem correspondência ou vazios permanecem com o gateway.
Posso reutilizar um gateway em dispositivos conectados diretamente e indiretamente conectados sem duplicar minhas definições?
Sim. Trate o gateway como um ativo reutilizável, crie os adaptadores correspondentes uma vez e, em seguida, associe o gateway a cada dispositivo conectado indiretamente que deve usar essa condição de rota do adaptador.
Posso enviar telemetria não estruturada de dispositivos conectados indiretamente?
Sim. Se você não precisar de mapeamento de payload estruturado para o dispositivo de destino, poderá enviar o payload bruto por meio do gateway e ignorar o adaptador específico do dispositivo.
Posso invocar comandos não estruturados em dispositivos conectados indiretamente e no próprio gateway?
Sim. Use pontos finais de comando brutos para ambos os padrões. Adicione um ponto final de resposta ao comando não estruturado quando precisar que o gateway publique uma confirmação no nível do aplicativo para o dispositivo de destino.
--request-endpoint, por exemplo, boilers/boiler1/actions/reset
--response-endpoint, por exemplo, boilers/boiler1/actions/response
Posso associar um dispositivo a vários gateways para que ele possa percorrer?
Sim. Um dispositivo conectado indiretamente pode ser associado a um ou mais gateways. Isso permite que um dispositivo sem fio mantenha a mesma instância de gêmeo digital enquanto ele se move entre os gateways disponíveis.
Na CLI, você pode configurar o roaming de vários gateway usando um array para a associação de gateway do modelo de gêmeo digital.
Use a opção --gateways com um array JSON de OCIDs de instância de gêmeo digital de gateway:
oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name "Roaming Wireless Device 1" \
  --gateways '["<gateway-instance-1-OCID>","<gateway-instance-2-OCID>"]' \
  --external-key roaming-device1
Se você preferir evitar problemas de cotação do shell, coloque a lista de gateway em um arquivo de entrada roaming-device.json e use --from-json:
oci iot digital-twin-instance create \
  --from-json file://roaming-device.json
roaming-device.json
{
  "iotDomainId": "<iot-domain-OCID>",
  "connectivityType": "INDIRECT",
  "displayName": "Roaming Wireless Device 1",
  "gateways": [
    "<gateway-instance-1-OCID>",
    "<gateway-instance-2-OCID>"
  ],
  "externalKey": "roaming-device1"
}
Antes de depender do roaming de vários gateway na produção, confirme o comportamento em seu ambiente de teste e valide o padrão de entrega que seus gateways usam.

Diagnóstico e Solução de Problemas

O comando permanece no estado ACCEPTED

Na Etapa 6: Chamar Comandos, se você não incluir o parâmetro --request-data, o comando permanecerá no estado ACCEPTED e resultará em um erro: Invalid Command Invocation id [unique-id]: [Previous command invocation is not finished yet]