Scenario: creare gemelli digitali per dispositivi connessi indirettamente utilizzando un gateway

Crea modelli digital twin, adattatori, un gateway, istanze digital twin dirette e indirette dei dispositivi in modo da poter instradare la telemetria e i comandi attraverso un gateway condiviso.

Utilizza questo scenario per creare un gateway riutilizzabile, un dispositivo connesso direttamente e diversi dispositivi connessi indirettamente.

Per illustrare questo scenario, gli esempi modellano un piccolo sistema di riscaldamento, ventilazione e condizionamento degli edifici (HVAC), tra cui:

Un gateway denominato Bosch Gateway 1 esegue l'autenticazione al dominio IoT e raccoglie o instrada i dati per dispositivi quali unità HVAC, caldaie e deumidificatori.
L'istanza HVAC direttamente connessa mostra un dispositivo che invia la propria telemetria.
Le istanze HVAC, caldaia e deumidificatore indirettamente connesse mostrano invece dispositivi la cui telemetria e i cui comandi si spostano attraverso il gateway.

Per ulteriori informazioni, vedere Domande frequenti sui dispositivi connessi in modo diretto.

Esamina il diagramma per capire come il gateway, i dispositivi connessi direttamente e i dispositivi connessi indirettamente interagiscono con i 3 tipi di istanze gemelle digitali.

Task

Crea modelli di gemelli digitali.
Crea adattatori digital twin.
Creare le istanze del gateway e del dispositivo.
Invia dati telemetrici.
Ottieni il contenuto dell'istanza digital twin.
Richiama comandi.

Per ulteriori informazioni su come fare riferimento ai file dell'interfaccia CLI, vedere Uso di un file JSON per input complessi.

Passo 1: Creare modelli Digital Twin

Creare un modello digital twin per il gateway e un modello digital twin per ogni tipo di dispositivo nello scenario. Questi dispositivi emettono dati strutturati.

Utilizzare gli snippet riportati di seguito per salvare questi file: gateway-model.json, hvac-model.json e boiler-model.json.

Utilizzare la console quando si desidera caricare un file modello salvato o incollare direttamente la specifica.

Nella pagina della lista Domini IoT aprire il dominio con cui si desidera lavorare. Per assistenza nella ricerca della pagina di elenco dei domini IoT, vedere Elenca domini IoT o Crea un nuovo dominio IoT.
Selezionare la scheda Modelli gemelli digitali, quindi selezionare Crea.
Immettere il nome e la descrizione facoltativa. Evitare di fornire informazioni riservate.
Scegliere Carica specifica o Incolla specifica, quindi utilizzare uno dei file di esempio di questo scenario.
Facoltativo: aggiungere tag.
Selezionare Crea.

Utilizzare uno dei file seguenti quando si carica o si incolla la specifica.

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-modello.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"
    }
  ]
}

Utilizzare il comando oci iot digital-twin-model create per creare ogni modello gemello digitale nel dominio IoT.

Creare il modello di gateway

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

Creare il modello HVAC

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

Creare il modello di caldaia

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

Per questo esempio, salvare questi snippet nei file modello 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-modello.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"
    }
  ]
}

Eseguire l'operazione CreateDigitalTwinModel per creare un modello gemello digitale nel dominio IoT.

Utilizzare lo stesso payload DTDL mostrato nei file modello digital twin di esempio quando si chiama l'API.

Passo 2: Creare adattatori gemelli digitali

Creare un adattatore per il gateway e un adattatore per ogni tipo di dispositivo strutturato che richiede il mapping del payload.

Utilizzare gli snippet riportati di seguito per salvare questi file: gateway-envelope.json, gateway-routes.json, hvac-envelope.json, hvac-routes.json, boiler-envelope.json e boiler-routes.json.

Risolvere la destinazione nell'envelope in entrata

Gli adattatori gateway possono identificare l'istanza digital twin di destinazione quando tutti i messaggi dispositivo inoltrati seguono lo stesso argomento o la stessa convenzione payload. Il gateway esegue l'autenticazione come se stesso, il servizio controlla che la destinazione risolta sia un'istanza gemella digitale connessa in modo indiretto associata a tale gateway, quindi il servizio delega il payload all'adattatore del dispositivo di destinazione quando è necessario il mapping strutturato.

Il gateway risolve target e contentRoot una volta per l'intero messaggio prima dell'esecuzione degli instradamenti. Se target viene risolto in una chiave esterna del dispositivo connessa in modo indiretto, il payload viene delegato a tale dispositivo. Se target è vuoto o nullo, il messaggio viene considerato come dati del gateway.

Utilizzare un adattatore digital twin quando il payload in entrata deve essere mappato al modello digital twin di destinazione. Non è necessario un adattatore digital twin quando il dispositivo invia dati non strutturati, è possibile passare i dati senza modifiche.

Nella pagina della lista Domini IoT aprire il dominio con cui si desidera lavorare.
Selezionare la scheda Adattatori gemelli digitali, quindi selezionare Crea.
Immettere un nome e una descrizione facoltativa. Evitare di fornire informazioni riservate.
Selezionare il modello gemello digitale che corrisponde al payload che si sta mappando.
Attivare Specifica busta e instradamenti in entrata, quindi caricare o incollare il file JSON dell'envelope e instradare il file JSON per l'adattatore.
Facoltativo: aggiungere tag.
Selezionare Crea.

Creare l'adattatore gateway con questi file 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"
    }
  }
]

Creare gli adattatori HVAC e caldaia con i file di dispositivo corrispondenti.

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

Utilizzare il comando oci iot digital-twin-adapter create per creare ogni adattatore nel dominio IoT.

Creare l'adattatore gateway

Utilizzare questo comando per creare un adattatore gemello digitale. Questo esempio mostra come associare il modello digital twin utilizzando DTMI e come definire l'envelope e gli instradamenti utilizzando i file .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"
    }
  }
]

Creare l'adattatore HVAC

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

Creare l'adattatore della caldaia

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

Per ulteriori informazioni su come fare riferimento ai file dell'interfaccia CLI, vedere Uso di un file JSON per input complessi.

Eseguire l'operazione CreateDigitalTwinAdapter per creare un adattatore gemello digitale nel dominio IoT.

Utilizzare gli stessi payload di instradamento in entrata e in entrata visualizzati nei file di esempio.

Passo 3: Creare le istanze del gateway e del dispositivo

Creare prima il gateway in modo da poterlo riutilizzare quando si creano i dispositivi connessi indirettamente.

Opzioni ID autenticazione:

Per il test delle istanze digital twin, se si utilizza l'OCID segreto come ID di autenticazione, utilizzare il nome utente del dispositivo come chiave esterna e il contenuto del segreto di testo normale come password del dispositivo. Per istruzioni, quando si Crea un segreto vedere il Passo 7 e per i segreti già creati, vedere Come ottenere il contenuto di un segreto.
Per le istanze digital twin di produzione, utilizzare l'OCID certificato mTLS anziché un segreto vault come ID di autenticazione. Quando si utilizza un certificato mTLS, è necessario utilizzare il nome comune dei dettagli del certificato come chiave esterna: --external-key <common-name-from-certificate-details>

Utilizzare la console per creare un gateway e associarvi più dispositivi.
Nella console sono disponibili due modi per creare un gateway per il dominio IoT. È possibile creare un gateway dalla scheda Istanza gemella digitale selezionando il tipo di gateway quando si crea un'istanza gemella digitale. In alternativa, è possibile selezionare la scheda Gateway per creare il gateway.
1. Nella pagina della lista Domini IoT aprire il dominio IoT con cui si desidera lavorare.
2. Selezionare la scheda Gateways, quindi selezionare Crea per creare un'istanza del gateway Bosch in modo che sia disponibile per i dispositivi indiretti.
  - Immettere un nome per il gateway e una descrizione.
  - Immettere la chiave esterna gateway1.
  - Selezionare l'adattatore che utilizza gateway-envelope.json e gateway-routes.json creato al Passo 2.
  - Selezionare l'ID autenticazione o incollare l'OCID dell'ID autenticazione, quindi selezionare Crea.
3. Nella pagina Dominio IoT selezionare la scheda Istanze gemelli digitali, selezionare Crea, quindi selezionare Connesso direttamente o indirettamente come tipo per creare le istanze gemelli digitali per questi dispositivi, utilizzando il modello e gli adattatori creati nel Passo 1 e nel Passo 2 per:
  - istanza HVAC LG direttamente connessa con la chiave esterna hvac1.
  - istanza HVAC connessa indirettamente con la chiave esterna hvac2
  - istanza caldaia connessa in modo indiretto con la chiave esterna boiler1.
  - istanza del deumidificatore connessa in modo indiretto con la chiave esterna deumidificatore1. Il deumidificatore non utilizza un adattatore digital twin o un modello digital twin poiché invia una telemetria raw non strutturata che non richiede una mappatura strutturata del payload. Può inoltre ricevere comandi raw tramite il gateway.
  Nota
  
  Se non si immette una chiave esterna, verrà generata.
4. Per l'istanza connessa direttamente e il gateway, selezionare un ID di autenticazione.
5. Per un'istanza connessa in modo indiretto, selezionare uno o più gateway esistenti invece di aggiungere credenziali di autenticazione dispositivo. Selezionare più gateway quando un dispositivo wireless può spostarsi tra i gateway.
6. Facoltativo: aggiungere tag.
7. Rivedere il riepilogo delle istanze dei gemelli digitali, quindi selezionare Crea.
Dopo aver creato le istanze digital twin, utilizzare la pagina Dettagli gateway per visualizzare i dispositivi da cui dipendono e sono associati al gateway.
- Trovare i dettagli del gateway nella pagina del dominio IoT, selezionando la scheda Gateway per visualizzare la lista dei gateway, selezionare un gateway per andare alla pagina dei dettagli del gateway.
- Nella scheda Istanza gemello digitale è possibile eseguire la ricerca per tipo per visualizzare i diversi tipi di istanza gemello digitale per un dominio IoT.
- Visualizzare i dispositivi connessi in modo diretto e indiretto dalla pagina Dettagli istanza gemella digitale.
Per un elenco completo delle impostazioni, vedere Creazione di un'istanza Digital Twin, Elenco delle istanze Digital Twin e Recupero dei dettagli di un'istanza Digital Twin.
Utilizzare il comando oci iot digital-twin-instance create per creare il gateway e le istanze di dispositivo connesse direttamente e indirettamente.

Crea l'istanza HVAC direttamente connessa
Utilizzare questo comando per creare un'istanza digital twin associata a un dominio IoT specifico e connessa direttamente, utilizzando una chiave esterna 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
```
Creare l'istanza del gateway
Utilizzare questo comando per creare un'istanza di gemello digitale associata a un dominio IoT specifico. Utilizzare il parametro --connectivity-type richiesto con il valore GATEWAY per creare un'istanza di gemello digitale che è un gateway. La chiave esterna è 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
```
Crea l'istanza HVAC connessa indirettamente
Utilizzare questo comando e il parametro richiesto --connectivity-type INDIRECT per creare un digital twin che è un dispositivo connesso indirettamente. Questo scenario mostra un'associazione gateway per dispositivo. Quando la tua distribuzione supporta il roaming, associa il dispositivo connesso indirettamente a più gateway in modo che possa spostarsi tra di loro senza modificare l'istanza gemella digitale.
Nota

Quando si crea un dispositivo connesso indirettamente utilizzando il parametro --gateways richiesto, si tratta di un tipo complesso e deve utilizzare un array JSON. Ad esempio: --gateways '["<gateway-instance-OCID>"]' o per il roaming utilizzare --gateways '["<gateway-instance-1-OCID>","<gateway-instance-2-OCID>"]'. In alternativa, è possibile usare un file .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
```
Crea istanza caldaia connessa in modo indiretto
Utilizzare questo comando e il parametro richiesto --connectivity-type INDIRECT per creare un digital twin che è un dispositivo connesso indirettamente.
```
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
```
Crea istanza del deumidificatore connesso indirettamente
Utilizzare questo comando e il parametro richiesto --connectivity-type INDIRECT per creare un digital twin che è un dispositivo connesso indirettamente.
```
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
```
Eseguire l'operazione CreateDigitalTwinInstance per creare un'istanza del gateway, un'istanza connessa direttamente e un'istanza connessa indirettamente.

Quando si crea un'istanza connessa in modo indiretto, assicurarsi che la richiesta includa l'associazione del gateway.

Passo 4: Invia dati telemetria

Questi esempi mostrano tre percorsi dati. Un dispositivo connesso direttamente, ad esempio hvac1, esegue l'autenticazione con una propria chiave esterna e invia i dati alla propria istanza digital twin. Il gateway, gateway1, esegue anche l'autenticazione con una propria chiave esterna quando invia la propria telemetria CPU, memoria, storage e firmware.

I dispositivi connessi indirettamente non eseguono l'autenticazione al dominio IoT; il gateway esegue l'autenticazione come gateway1 e il percorso dell'endpoint, ad esempio hvacs/hvac2, boilers/boiler1 o dehumidifiers/dehumidifier1, identifica il dispositivo di destinazione dietro il gateway.

Installa e configura MQTTX.
Utilizzare <digital-twin-instance-external-key> come nome utente del dispositivo. Se devi trovare la chiave esterna dell'istanza digitale, puoi ottenere i dettagli dell'istanza di un gemello digitale.
Connettersi a <domain-short-id>.device.iot.<region>.oci.oraclecloud.com sulla porta 8883, abilitare SSL/TLS e utilizzare una sessione di pulizia.

Invia telemetria dall'istanza HVAC direttamente connessa:

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>'

Invia telemetria dall'istanza del 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>'

Invia telemetria per l'istanza HVAC connessa indirettamente tramite il 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>'

Invia telemetria per l'istanza della caldaia connessa indirettamente tramite il 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>'

Invia telemetria per l'istanza del deumidificatore connessa indirettamente tramite il 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>'

Utilizzare curl per inviare la telemetria tramite HTTPS. Questi esempi utilizzano l'autenticazione di base HTTP con la chiave esterna dell'istanza gemella digitale e il contenuto del segreto di testo normale.

Utilizzare la chiave esterna dell'istanza gemella digitale come nome utente. Ad esempio, per la telemetria connessa direttamente, utilizzare la chiave esterna dell'istanza, ad esempio hvac1.
Utilizzare il contenuto del segreto di testo normale come password.
Inviare la richiesta a https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/<endpoint-path>.
Per i dispositivi connessi in modo indiretto, eseguire l'autenticazione come istanza del gateway e utilizzare il percorso endpoint per identificare il dispositivo di destinazione, ad esempio hvacs/hvac2 o boilers/boiler1.

Invia telemetria dall'istanza HVAC direttamente connessa:

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

Invia telemetria dall'istanza del 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"
}'

Invia telemetria per l'istanza HVAC connessa indirettamente tramite il 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
  }'

Invia telemetria per l'istanza della caldaia connessa indirettamente tramite il 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
  }'

Invia telemetria per l'istanza del deumidificatore connessa indirettamente tramite il 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'

Passo 5 opzionale: ottenere il contenuto dell'istanza di un gemello digitale

Per confermare l'acquisizione dei dati dell'istanza del gemello digitale, utilizzare la console, l'interfaccia CLI o l'API per visualizzare il contenuto dell'istanza del gemello digitale, ovvero i dati snapshot più recenti.

Per un'istanza di data digital twin non strutturata, in genere non dispone di un modello digital twin associato, pertanto non è possibile utilizzare il contenuto di acquisizione per un'istanza digital twin per visualizzarne i dati.

1. Nella pagina di elenco Domini, selezionare il dominio da utilizzare. Se è necessaria assistenza per trovare la pagina di elenco dei domini IoT o un dominio IoT, vedere Elenco dei domini IoT.
2. Selezionare la scheda Istanze gemelle digitali.
3. Selezionare il nome dell'istanza gemella digitale. Viene visualizzata la pagina dei dettagli.
4. Selezionare la scheda Dati per visualizzare i dati snapshot più recenti per questa istanza. Per ulteriori informazioni, vedere Informazioni di riferimento sullo schema del database del dominio IoT.

Utilizzare il comando oci iot digital-twin-instance get-content e il parametro necessario per ottenere il contenuto dell'istanza di un gemello digitale:

Verificare l'istanza HVAC direttamente connessa:

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

Verificare l'istanza del gateway:

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

Verificare l'istanza HVAC connessa indirettamente:

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

Verificare l'istanza della caldaia connessa in modo indiretto:

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

Eseguire l'operazione GetDigitalTwinInstanceContent per ottenere il contenuto da un'istanza digital twin.

Passo 6: richiamare i comandi

Per i dispositivi connessi in modo indiretto, utilizza un criterio di consegna at-least-once e prevedi nuovi tentativi o consegne duplicate.

Quando è richiesta una risposta, configurare un endpoint di risposta in modo che il gateway possa pubblicare la risposta per conto del dispositivo di destinazione.

Utilizzare la console quando si desidera inviare un comando raw dalla pagina dei dettagli dell'istanza gemella digitale.
1. Aprire il dominio IoT e selezionare la scheda Istanze gemelle digitali.
2. Selezionare l'istanza che si desidera controllare.
3. Nel menu Azioni selezionare Invia comando raw.
4. Immettere l'endpoint della richiesta, la durata della richiesta e il payload del comando.
5. Facoltativo: configurare un endpoint di risposta e la durata della risposta, quindi selezionare Invia comando raw. Utilizzare i valori di questi file: gateway-command.json, boiler-command.json
gateway-command.json
{ "force": true }
boiler-command.json
{ "hardReset": false }
Utilizzare il comando oci iot digital-twin-instance invoke-raw-json-command per richiamare le azioni di esempio in questo scenario. Per ulteriori informazioni, vedere Invio di un comando raw da un'istanza Digital Twin.

Riavviare l'istanza del 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}'
```
Reimposta istanza caldaia connessa in modo indiretto
Specificare --request-endpoint, in questo esempio boilers/boiler1/actions/reset.
Specificare --response-endpoint, in questo esempio boilers/boiler1/actions/response.
Se si prevede una risposta, è necessario includere il parametro --response-duration. In caso contrario, il comando passa allo stato COMPLETED senza ricevere la risposta. Di conseguenza, la risposta del comando non viene acquisita nella tabella del database 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
```
Pubblica la risposta della caldaia
Utilizzare l'endpoint di risposta per pubblicare la risposta della caldaia a questo endpoint: boilers/boiler1/actions/response in questo esempio gateway1 è la chiave esterna e il nome utente del 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>'
```
Spegnere la ventola del deumidificatore collegata indirettamente
Utilizzare questo comando per richiamare un comando JSON raw sul dispositivo che spegne la ventola sul deumidificatore.
```
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}'
```
Eseguire l'operazione InvokeRawCommand per richiamare un comando raw su un dispositivo.

Utilizzare un endpoint di risposta quando il comando deve restituire una conferma a livello di applicazione.

Scegli il tipo di connettività giusto per la tua istanza Digital Twin

Come decidere quale tipo di connettività utilizzare per un'istanza gemella digitale:

Connesso direttamente

Usa quando: Il dispositivo si connette al dominio IoT da solo.
Parametro obbligatorio: ID autenticazione, per il test utilizzare un secret e per la produzione utilizzare il certificato mTLS.
Obbligatorio per i dati strutturati: Un adattatore gemello digitale corrispondente al modello gemello digitale può essere fornito o derivato dall'adattatore e il modello deve contenere almeno una telemetria, una proprietà o un comando.
Per dati non strutturati: Non utilizzare un adattatore digital twin o un modello digital twin.
Input facoltativo: Chiave esterna, se non si fornisce un elemento esterno, il servizio ne genera uno. Utilizzare per il nome utente del dispositivo.
Non usare: Associazione del gateway a un dispositivo connesso direttamente.

Gateway

Usa quando: Un dispositivo inoltra dati e comandi per sé stesso e per altri dispositivi.
Parametri obbligatori: ID autenticazione e adattatore gateway. Le istanze del gateway non supportano la telemetria non strutturata, pertanto l'adattatore è obbligatorio.
Modello del gemello digitale: Il modello digital twin del gateway può essere associato o dedotto dall'adattatore digital twin e il modello deve contenere almeno una telemetria, una proprietà o un comando. È possibile creare un'istanza digital twin con un adattatore senza specificare il modello. Un modello viene associato tramite l'adattatore.; Per i dati non strutturati, in genere non si utilizza un adattatore o un modello.
Input facoltativo: Chiave esterna, se non ne viene fornita una, il servizio ne genera una.
Consigliato: Prima di modificarla o eliminarla, rivedere la pagina dettagli del gateway per vedere quanti dispositivi dipendono dal gateway.
Non: Associare un'istanza di gateway a un'altra istanza di gateway.

Connesso indirettamente

Usa quando: Un altro dispositivo, in genere un gateway, invia dati di telemetria e riceve i comandi per conto del dispositivo.
Obbligatorio: Una o più associazioni gateway sono obbligatorie. Utilizzare più gateway quando un dispositivo wireless può spostarsi tra i gateway. Confermare con un amministratore se questo funziona nell'ambiente in uso.
Per i dati strutturati: Per i dati strutturati è necessario un adattatore digital twin. Il modello digital twin corrispondente può essere fornito o dedotto dall'adattatore, specificando il DTMI o l'OCID del modello digital twin, il modello deve contenere almeno una telemetria, una proprietà o un comando.
Per dati non strutturati: Per i dati non strutturati non utilizzare un adattatore digital twin o un modello digital twin. Impossibile ottenere il contenuto per i dati non strutturati poiché non contiene un modello gemello digitale.
Input facoltativo: Chiave esterna, se non si fornisce una chiave esterna, il servizio ne genera una.
ID autenticazione: Non utilizzare un ID di autenticazione per un'istanza digital twin connessa indirettamente.

Non connesso

Usa quando: Test di un'istanza digital twin che non autentica, invia o riceve i dati del dispositivo in modo da poter testare le relazioni digital twin per testare la configurazione IoT senza la complessità dei dati o dell'autenticazione.
Obbligatorio: Per i dati strutturati, è necessario un modello gemello digitale e non deve contenere telemetria, proprietà o comandi.
Facoltativo: Relazioni gemelle digitali per i test. Per ulteriori informazioni, vedere Relazioni gemelli digitali.
Non usare: ID autenticazione, chiave esterna, adattatore digital twin, associazione gateway o dati dispositivo su istanze digital twin non connesse.

Domande più frequenti

Queste domande frequenti descrivono le storie degli utenti del gateway descritte in questo scenario.

Posso configurare un'istanza digital twin per essere connessa indirettamente in modo che un altro dispositivo invii dati per suo conto?

Sì Creare l'istanza digital twin per il dispositivo con tipo di connettività INDIRECT e associarla a una o più istanze digital twin gateway invece di fornire al dispositivo il proprio ID di autenticazione.

Come posso sapere quali dispositivi sono connessi attraverso un gateway specifico e capire l'impatto della perdita di tale gateway?

Utilizzare la pagina dei dettagli del gateway per esaminare il conteggio dei dispositivi associati e la lista delle istanze digital twin dipendenti. Ciò ti offre la visione più rapida del raggio di esplosione del gateway prima delle operazioni di manutenzione, migrazione o eliminazione.

Come faccio a sapere quante delle mie istanze digital twin sono collegate direttamente, indirettamente o gateway?

Nella pagina di elenco dell'istanza gemella digitale o nella pagina di elenco Gateway è possibile trovare la lista dei gateway.

Esamina il tipo di connettività dell'istanza gemella digitale per ogni gemello digitale e utilizza un gateway a livello di dominio e viste della topologia per ottenere insight sul tuo ambiente. Questo scenario mostra un dispositivo diretto, un gateway e diversi dispositivi indiretti in modo da poter confrontare i tre modelli.

Come si configura un adattatore per il gateway in modo che la telemetria in entrata venga instradata al dispositivo di destinazione corretto?

Utilizzare un adattatore gemello digitale per il gateway che include un mapping target nell'envelope. Vedere Passo 2: Creazione di adattatori gemelli digitali.

Quando inserire target nei percorsi in entrata anziché nell'envelope in entrata?

N. Inserire target nell'envelope in entrata.

Cosa succede se target è vuoto o nullo?

Il messaggio viene considerato come dati gateway invece di essere delegato a un dispositivo connesso indirettamente.

Un adattatore gateway può gestire sia la telemetria del gateway che la telemetria del dispositivo connessa indirettamente?

Sì Questo è lo scopo principale del gateway routing. I messaggi del dispositivo inoltrati vanno a una destinazione risolta, mentre i dati senza corrispondenza o con destinazione vuota rimangono con il gateway.

Posso riutilizzare un gateway tra dispositivi connessi direttamente e indirettamente senza duplicare le mie definizioni?

Sì Considera il gateway come un asset riutilizzabile, crea gli adattatori corrispondenti una volta e associa il gateway a ogni dispositivo connesso indirettamente che dovrebbe utilizzare tale condizione di instradamento dell'adattatore.

Posso inviare la telemetria non strutturata da dispositivi connessi indirettamente?

Sì Se non è necessario mappare il payload strutturato per il dispositivo di destinazione, è possibile inviare il payload raw tramite il gateway e saltare l'adattatore specifico del dispositivo.

Posso richiamare comandi non strutturati su dispositivi connessi indirettamente e sul gateway stesso?

Sì Utilizzare gli endpoint dei comandi raw per entrambi i pattern. Aggiungere un endpoint di risposta al comando non strutturato quando è necessario che il gateway pubblichi una conferma a livello di applicazione per il dispositivo di destinazione.

--request-endpoint, ad esempio boilers/boiler1/actions/reset

--response-endpoint, ad esempio boilers/boiler1/actions/response

Posso associare un dispositivo a più gateway in modo che possa vagare?

Sì Un dispositivo connesso indirettamente può essere associato a uno o più gateway. Ciò consente a un dispositivo wireless di mantenere la stessa istanza digital twin mentre si sposta tra i gateway disponibili.

Nell'interfaccia CLI, è possibile configurare il roaming multi-gateway utilizzando un array per l'associazione del gateway del modello digital twin.

Utilizzare l'opzione --gateways con un array JSON di OCID istanza digital twin 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 si preferisce evitare problemi di citazione della shell, inserire la lista dei gateway in un file di input roaming-device.json e utilizzare --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"
}

Prima di dipendere dal roaming multi-gateway in produzione, confermare il comportamento nell'ambiente di test e convalidare il pattern di trasferimento utilizzato dai gateway.

Risoluzione dei problemi

Il comando rimane in stato ACCEPTED

In Passo 6: Richiama comandi, se non si include il parametro --request-data, il comando rimane nello stato ACCEPTED e genera un errore: Invalid Command Invocation id [unique-id]: [Previous command invocation is not finished yet]

Passi successivi

Eliminare le risorse utilizzate per creare questo scenario:

Documentazione dell'infrastruttura Oracle Cloud