Scénario : création de jumeaux numériques pour les périphériques connectés indirectement à l'aide d'une passerelle

Créez des modèles de jumeaux numériques, des adaptateurs, une passerelle, des instances de jumeaux numériques d'appareils directs et indirects afin de pouvoir acheminer la télémétrie et les commandes via une passerelle partagée.

Utilisez ce scénario pour créer une passerelle réutilisable, un périphérique connecté directement et plusieurs périphériques connectés indirectement.

Pour illustrer ce scénario, les exemples modélisent un petit système de chauffage, de ventilation et de climatisation de bâtiment (CVC) comprenant :

Une passerelle nommée Bosch Gateway 1 s'authentifie auprès du domaine IoT et collecte ou achemine des données pour des périphériques tels que des unités HVAC, des chaudières et des déshumidificateurs.
L'instance HVAC directement connectée affiche un périphérique qui envoie sa propre télémétrie.
Les instances de CVC, de chaudière et de déshumidificateur indirectement connectées affichent les périphériques dont la télémétrie et les commandes transitent par la passerelle.

Pour plus de concepts, reportez-vous à la FAQ sur les appareils connectés indirectement.

Consultez le diagramme pour comprendre comment la passerelle, les appareils connectés directement et les appareils connectés indirectement interagissent avec les 3 types d'instances de jumeaux numériques.

Tâches

Créer des modèles de jumeaux numériques.
Créer des adaptateurs de jumeaux numériques.
Créez la passerelle et les instances de dispositif.
Envoyer des données de télémétrie.
Obtenir le contenu de l'instance de jumeau numérique.
Appeler des commandes.

Pour plus d'informations sur le référencement de fichiers à partir de l'interface de ligne de commande, reportez-vous à Utilisation d'un fichier JSON pour les entrées complexes.

Etape 1 : Créer des modèles de jumeaux numériques

Créez un modèle jumeau numérique pour la passerelle et un modèle jumeau numérique pour chaque type d'appareil dans le scénario. Ces appareils émettent des données structurées.

Utilisez les fragments de code ci-dessous pour enregistrer les fichiers suivants : gateway-model.json, hvac-model.json et boiler-model.json.

Utilisez la console lorsque vous voulez télécharger un fichier de modèle enregistré ou coller directement la spécification.

Dans la page de liste Domaines IoT, ouvrez le domaine avec lequel vous voulez travailler. Si vous avez besoin d'aide pour trouver la page de liste des domaines IoT, reportez-vous à Liste des domaines IoT ou à Création d'un domaine IoT.
Sélectionnez l'onglet Modèles de jumeaux numériques, puis sélectionnez Créer.
Saisissez le nom et la description facultative. Evitez de saisir des informations confidentielles.
Sélectionnez Charger la spécification ou Coller la spécification, puis utilisez l'un des exemples de fichier de ce scénario.
Facultatif : ajoutez des balises.
Choisissez Créer.

Utilisez l'un des fichiers suivants lorsque vous chargez ou collez la spécification.

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

Utilisez la commande oci iot digital-twin-model create pour créer chaque modèle de jumeau numérique dans le domaine IoT.

Créer le modèle de passerelle

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

Créer le modèle HVAC

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

Créer le modèle de chaudière

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

Pour cet exemple, enregistrez ces fragments de code dans ces fichiers de modèle, gateway-model.json, hvac-model.json et 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"
    }
  ]
}

Exécutez l'opération CreateDigitalTwinModel pour créer un modèle de jumeau numérique dans le domaine IoT.

Utilisez la même charge utile DTDL que celle indiquée dans les exemples de fichier de modèle de jumeau numérique lorsque vous appelez l'API.

Étape 2 : Créer des adaptateurs jumeaux numériques

Créez un adaptateur pour la passerelle et un adaptateur pour chaque type d'appareil structuré nécessitant un mapping de charge utile.

Utilisez les fragments de code ci-dessous pour enregistrer les fichiers suivants : gateway-envelope.json, gateway-routes.json, hvac-envelope.json, hvac-routes.json, boiler-envelope.json et boiler-routes.json.

Résoudre la cible dans l'enveloppe entrante

Les adaptateurs de passerelle peuvent identifier l'instance de jumeau numérique cible lorsque tous les messages de périphérique transférés suivent la même convention de sujet ou de charge utile. La passerelle s'authentifie en tant que telle, le service vérifie que la cible résolue est une instance de jumeau numérique indirectement connectée associée à cette passerelle, puis le service délègue la charge utile à l'adaptateur de l'appareil cible lorsque le mapping structuré est requis.

La passerelle résout target et contentRoot une fois pour l'ensemble du message avant l'exécution des routages. Si target est résolu en clé externe d'appareil indirectement connecté, la charge utile est déléguée à cet appareil. Si target est vide ou NULL, le message est traité comme des données de passerelle.

Utilisez un adaptateur jumeau numérique lorsque la charge utile entrante doit être mappée avec le modèle jumeau numérique cible. Un adaptateur jumeau numérique n'est pas nécessaire lorsque l'appareil envoie des données non structurées, vous pouvez transmettre les données sans modification.

Dans la page de liste Domaines IoT, ouvrez le domaine avec lequel vous voulez travailler.
Sélectionnez l'onglet Adaptateurs de jumeaux numériques, puis Créer.
Saisissez un nom et une description facultative. Evitez de saisir des informations confidentielles.
Sélectionnez le modèle jumeau numérique correspondant à la charge utile que vous mappez.
Activez l'option Indiquer l'enveloppe et les routages entrants, puis chargez ou collez le JSON de l'enveloppe et achemine le JSON pour l'adaptateur.
Facultatif : ajoutez des balises.
Choisissez Créer.

Créez l'adaptateur de passerelle avec ces fichiers de passerelle.

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

Créez les adaptateurs HVAC et de chaudière avec les fichiers de périphérique correspondants.

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

Utilisez la commande oci iot digital-twin-adapter create pour créer chaque adaptateur dans le domaine IoT.

Créer l'adaptateur de passerelle

Cette commande permet de créer un adaptateur de jumeau numérique. Cet exemple montre comment associer le modèle de jumeau numérique à l'aide du DTMI et comment définir l'enveloppe et les routages à l'aide de fichiers .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"
    }
  }
]

Créer l'adaptateur HVAC

Utilisez cette commande pour créer un adaptateur de jumeau numérique. Cet exemple montre comment associer le modèle de jumeau numérique à l'aide du DTMI et comment définir l'enveloppe et les routages à l'aide de fichiers .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"
    }
  }
]

Créer l'adaptateur de chaudière

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

Pour plus d'informations sur le référencement de fichiers à partir de l'interface de ligne de commande, reportez-vous à Utilisation d'un fichier JSON pour les entrées complexes.

Exécutez l'opération CreateDigitalTwinAdapter pour créer un adaptateur de jumeau numérique dans le domaine IoT.

Utilisez les mêmes charges utiles d'enveloppe entrante et d'itinéraires entrants que celles indiquées dans les exemples de fichiers.

Etape 3 : création des instances de passerelle et de périphérique

Créez d'abord la passerelle afin de pouvoir la réutiliser lorsque vous créez les périphériques connectés indirectement.

Options d'ID d'authentification :

Pour tester les instances de jumeau numérique, si vous utilisez l'OCID de clé secrète comme ID d'authentification, utilisez le nom utilisateur de l'appareil comme clé externe et le contenu de clé secrète en texte brut comme mot de passe de l'appareil. Pour obtenir des instructions, lorsque vous créez une clé secrète, reportez-vous à l'étape 7 et pour connaître les clés secrètes déjà créées, reportez-vous à Obtention du contenu d'une clé secrète.
Pour les instances de jumeau numérique de production, utilisez l'OCID de certificat MTLS au lieu d'une clé secrète de coffre en tant qu'ID d'authentification. Lorsque vous utilisez un certificat mTLS, vous devez utiliser le nom commun des détails du certificat en tant que clé externe : --external-key <common-name-from-certificate-details>

Utilisez la console pour créer une passerelle et lui associer plusieurs périphériques.
Dans la console, il existe deux façons de créer une passerelle pour le domaine IoT. Vous pouvez créer une passerelle à partir de l'onglet Instance de jumeau numérique, en sélectionnant le type de passerelle lorsque vous créez une instance de jumeau numérique. Vous pouvez également sélectionner l'onglet Passerelle pour créer la passerelle.
1. Sur la page de liste Domaines IoT, ouvrez le domaine IoT avec lequel vous voulez travailler.
2. Sélectionnez l'onglet Passerelles, puis Créer pour créer une instance de passerelle Bosch afin qu'elle soit disponible pour les dispositifs indirects.
  - Entrez le nom de la passerelle et la description.
  - Entrez la clé externe gateway1.
  - Sélectionnez l'adaptateur qui utilise les éléments gateway-envelope.json et gateway-routes.json créés à l'Step 2.
  - Sélectionnez l'ID d'authentification ou collez l'OCID de l'ID d'authentification, puis sélectionnez Créer.
3. Sur la page Domaine IoT, sélectionnez l'onglet Instances de jumeaux numériques, sélectionnez Créer, puis sélectionnez directement connecté ou indirectement connecté en tant que type pour créer les instances de jumeaux numériques pour ces périphériques, à l'aide du modèle et des adaptateurs créés à l'étape 1 et à l'étape 2 pour :
  - connexion directe à l'instance LG HVAC avec la clé externe hvac1.
  - instance HVAC connectée indirectement avec la clé externe hvac2
  - instance de chaudière connectée indirectement avec la clé externe boiler1.
  - instance de déshumidificateur connectée indirectement avec la clé externe dehumidifier1. Le déshumidificateur n'utilise pas d'adaptateur jumeau numérique ou de modèle jumeau numérique car il envoie une télémétrie brute non structurée qui n'a pas besoin d'une cartographie de charge utile structurée. Il peut également recevoir des commandes brutes via la passerelle.
  Remarque
  
  Si vous n'entrez pas de clé externe, celle-ci est générée.
4. Pour l'instance de passerelle directement connectée et l'instance de passerelle, sélectionnez un ID d'authentification.
5. Pour une instance connectée indirectement, sélectionnez des passerelles existantes au lieu d'ajouter des informations d'identification d'authentification d'appareil. Sélectionnez plusieurs passerelles lorsqu'un périphérique sans fil peut circuler entre les passerelles.
6. Facultatif : ajoutez des balises.
7. Vérifiez le récapitulatif des instances de jumeau numérique, puis sélectionnez Créer.
Une fois les instances de jumeau numérique créées, utilisez la page Détails de la passerelle pour visualiser les périphériques dépendants de la passerelle et qui lui sont associés.
- Recherchez les détails de passerelle sur la page du domaine IoT. Pour afficher la liste des passerelles, sélectionnez l'onglet Passerelle, puis une passerelle pour accéder à la page de détails de la passerelle.
- Dans l'onglet Instance de jumeau numérique, vous pouvez effectuer une recherche par type pour visualiser les différents types d'instance de jumeau numérique d'un domaine IoT.
- Affichez les périphériques connectés directement et indirectement à partir de la page Détails de l'instance de jumeau numérique.
Pour obtenir la liste complète des paramètres, reportez-vous à Création d'une instance de jumeau numérique, à Liste des instances de jumeau numérique et à Obtention des détails d'une instance de jumeau numérique.
Utilisez la commande oci iot digital-twin-instance create pour créer la passerelle et les instances de périphérique directement connectées et indirectement connectées.

Créer l'instance HVAC directement connectée
Utilisez cette commande pour créer une instance de jumeau numérique associée à un domaine IoT spécifique et directement connectée, à l'aide d'une clé externe 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
```
Créer l'instance de passerelle
Utilisez cette commande pour créer une instance de jumeau numérique associée à un domaine IoT spécifique. Utilisez le paramètre --connectivity-type requis avec la valeur GATEWAY pour créer une instance de jumeau numérique qui est une passerelle. La clé externe est 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
```
Créer l'instance HVAC connectée indirectement
Utilisez cette commande et le paramètre requis --connectivity-type INDIRECT pour créer un jumeau numérique qui est un périphérique connecté indirectement. Ce scénario présente une association de passerelle par périphérique. Lorsque votre déploiement prend en charge l'itinérance, associez l'appareil connecté indirectement à plusieurs passerelles afin qu'il puisse se déplacer entre elles sans modifier l'instance de jumeau numérique.
Remarque

Lorsque vous créez un appareil connecté indirectement à l'aide du paramètre --gateways requis, il s'agit d'un type complexe qui doit utiliser un tableau JSON. Par exemple : --gateways '["<gateway-instance-OCID>"]' ou pour l'itinérance, utilisez --gateways '["<gateway-instance-1-OCID>","<gateway-instance-2-OCID>"]'. Vous pouvez également utiliser un fichier .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
```
Créer l'instance de chaudière connectée indirectement
Utilisez cette commande et le paramètre requis --connectivity-type INDIRECT pour créer un jumeau numérique qui est un périphérique connecté indirectement.
```
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
```
Créer l'instance de déshumidificateur connectée indirectement
Utilisez cette commande et le paramètre requis --connectivity-type INDIRECT pour créer un jumeau numérique qui est un périphérique connecté indirectement.
```
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
```
Exécutez l'opération CreateDigitalTwinInstance pour créer une instance de passerelle, une instance connectée directement et une instance connectée indirectement.

Lorsque vous créez une instance connectée indirectement, assurez-vous que la demande inclut l'association de passerelle.

Etape 4 : Envoyer les données de télémétrie

Ces exemples montrent trois chemins de données. Un appareil directement connecté, tel que hvac1, s'authentifie avec sa propre clé externe et envoie des données à sa propre instance de jumeau numérique. La passerelle, gateway1, s'authentifie également avec sa propre clé externe lorsqu'elle envoie sa propre télémétrie de CPU, de mémoire, de stockage et de microprogramme.

Les périphériques connectés indirectement ne s'authentifient pas auprès du domaine IoT ; la passerelle s'authentifie en tant que gateway1 et le chemin d'adresse, tel que hvacs/hvac2, boilers/boiler1 ou dehumidifiers/dehumidifier1, identifie le périphérique cible derrière la passerelle.

Installez et configurez MQTTX.
Utilisez <digital-twin-instance-external-key> comme nom utilisateur de périphérique. Si vous devez rechercher la clé externe de l'instance numérique, vous pouvez obtenir les détails de l'instance d'un jumeau numérique.
Connectez-vous à <domain-short-id>.device.iot.<region>.oci.oraclecloud.com sur le port 8883, activez SSL/TLS et utilisez une session propre.

Envoyer une télémétrie à partir de l'instance HVAC directement connectée :

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

Envoyer la télémétrie à partir de l'instance de passerelle :

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

Envoyer une télémétrie pour l'instance HVAC connectée indirectement via la passerelle :

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

Envoyer une télémétrie pour l'instance de chaudière connectée indirectement via la passerelle :

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

Envoyer une télémétrie pour l'instance de déshumidificateur connectée indirectement via la passerelle :

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

Utilisez curl pour envoyer la télémétrie via HTTPS. Ces exemples utilisent l'authentification de base HTTP avec la clé externe de l'instance de jumeau numérique et le contenu de la clé secrète en texte brut.
1. Utilisez la clé externe de l'instance de jumeau numérique comme nom utilisateur. Par exemple, pour la télémétrie directement connectée, utilisez la clé externe de l'instance, telle que hvac1.
2. Utilisez le contenu de clé secrète en texte brut comme mot de passe.
3. Envoyez la demande à https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/<endpoint-path>.
4. Pour les périphériques connectés indirectement, authentifiez-vous en tant qu'instance de passerelle et utilisez le chemin d'adresse pour identifier le périphérique cible, tel que hvacs/hvac2 ou boilers/boiler1.
Envoyer une télémétrie à partir de l'instance HVAC directement connectée :
```
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
  }'
```
Envoyer la télémétrie à partir de l'instance de passerelle :
```
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"
}'
```
Envoyer une télémétrie pour l'instance HVAC connectée indirectement via la passerelle :
```
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
  }'
```
Envoyer une télémétrie pour l'instance de chaudière connectée indirectement via la passerelle :
```
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
  }'
```
Envoyer une télémétrie pour l'instance de déshumidificateur connectée indirectement via la passerelle :
```
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'
```

Etape facultative 5 : Obtenir le contenu de l'instance d'un jumeau numérique

Pour vérifier que les données de l'instance de jumeau numérique sont capturées, utilisez la console, l'interface de ligne de commande ou l'API pour visualiser le contenu de l'instance du jumeau numérique, c'est-à-dire les dernières données d'instantané.

Pour une instance de jumeau numérique de données non structurée, elle n'a généralement pas de modèle de jumeau numérique associé. Vous ne pouvez donc pas utiliser l'option Obtenir le contenu d'une instance de jumeau numérique pour visualiser ses données.

1. Sur la page de liste Domaines, sélectionnez le domaine avec lequel vous souhaitez travailler. Si vous avez besoin d'aide pour trouver la page de liste des domaines IoT ou un domaine IoT, reportez-vous à Liste des domaines IoT.
2. Sélectionnez l'onglet Instances de jumeaux numériques.
3. Sélectionnez le nom d'instance de jumeau numérique. La page de détails s'ouvre.
4. Sélectionnez l'onglet Données pour afficher les dernières données de cliché pour cette instance. Pour plus d'informations, reportez-vous à Référence de schéma de base de données de domaine IoT.

Utilisez la commande oci iot digital-twin-instance get-content et le paramètre requis pour obtenir le contenu de l'instance d'un jumeau numérique :

Vérifiez l'instance HVAC directement connectée :

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

Vérifiez l'instance de passerelle :

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

Vérifiez l'instance HVAC connectée indirectement :

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

Vérifiez l'instance de chaudière connectée indirectement :

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

Exécutez l'opération GetDigitalTwinInstanceContent pour obtenir le contenu d'une instance de jumeau numérique.

Etape 6 : Appeler des commandes

Pour les périphériques connectés indirectement, utilisez une stratégie de distribution at-least-once et attendez-vous à des nouvelles tentatives ou à une livraison en double.

Lorsqu'une réponse est requise, configurez une adresse de réponse afin que la passerelle puisse publier la réponse au nom du périphérique cible.

Utilisez la console lorsque vous voulez envoyer une commande brute à partir de la page de détails de l'instance de jumeau numérique.
1. Ouvrez le domaine IoT et sélectionnez l'onglet Instances de jumeaux numériques.
2. Sélectionnez l'instance que vous voulez contrôler.
3. Dans le menu Actions, sélectionnez Envoyer la commande brute.
4. Entrez l'adresse de demande, la durée de la demande et la charge utile de la commande.
5. Facultatif : configurez une adresse de réponse et une durée de réponse, puis sélectionnez Envoyer la commande brute. Utilisez les valeurs des fichiers suivants : gateway-command.json, boiler-command.json
gateway-command.json
{ "force": true }
boiler-command.json
{ "hardReset": false }
Utilisez la commande oci iot digital-twin-instance invoke-raw-json-command pour appeler les exemples d'actions dans ce scénario. Pour plus d'informations, reportez-vous à Envoi d'une commande brute à partir d'une instance de jumeau numérique.

Redémarrer l'instance de passerelle
```
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}'
```
Réinitialiser l'instance de chaudière connectée indirectement
Indiquez --request-endpoint, dans cet exemple qui est boilers/boiler1/actions/reset.
Indiquez --response-endpoint, dans cet exemple qui est boilers/boiler1/actions/response.
Si vous attendez une réponse, vous devez inclure le paramètre --response-duration. Dans le cas contraire, la commande passe à l'état COMPLETED sans recevoir la réponse. Par conséquent, la réponse de la commande n'est pas capturée dans la table de base de données 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
```
Publier la réponse de la chaudière
Utilisez l'adresse de réponse pour publier la réponse de la chaudière vers cette adresse : boilers/boiler1/actions/response dans cet exemple, gateway1 est la clé externe et le nom utilisateur de l'appareil.
```
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>'
```
Désactivez le ventilateur de déshumidificateur connecté indirectement
Utilisez cette commande pour appeler une commande JSON brute sur le périphérique qui arrête le ventilateur sur le déshumidificateur.
```
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}'
```
Exécutez l'opération InvokeRawCommand pour appeler une commande brute sur un périphérique.

Utilisez une adresse de réponse lorsque la commande doit renvoyer un accusé de réception au niveau de l'application.

Choisir le bon type de connectivité pour votre instance de jumeau numérique

Comment choisir le type de connectivité à utiliser pour une instance de jumeau numérique :

Connecté directement

Utiliser quand: Le périphérique se connecte au domaine IoT seul.
Paramètre requis: L'ID d'authentification, pour le test, utilise un secret et pour la production, un certificat mTLS.
Requis pour les données structurées: Un adaptateur jumeau numérique correspondant au modèle jumeau numérique peut être fourni ou déduit de l'adaptateur, et le modèle doit contenir au moins une télémétrie, une propriété ou une commande.
Pour les données non structurées: N'utilisez pas d'adaptateur jumeau numérique ou de modèle jumeau numérique.
Entrée facultative: Clé externe, si vous ne fournissez pas de clé externe, le service en génère une. Utilisez ce nom d'utilisateur pour le périphérique.
Ne pas utiliser: Association de passerelle à un périphérique directement connecté.

Passerelle

Utiliser quand: Un périphérique transmet des données et des commandes pour lui-même et pour d'autres périphériques.
Paramètres requis: ID d'authentification et adaptateur de passerelle. Les instances Gateway ne prennent pas en charge la télémétrie non structurée. L'adaptateur est donc requis.
Modèle de jumeaux numérique: Le modèle de jumeau numérique de la passerelle peut être associé ou déduit de l'adaptateur de jumeau numérique, et le modèle doit contenir au moins une télémétrie, une propriété ou une commande. Vous pouvez créer une instance de jumeau numérique avec un adaptateur sans spécifier le modèle. Un modèle est associé via l'adaptateur.; Pour les données non structurées, vous n'utilisez généralement ni adaptateur ni modèle.
Entrée facultative: Clé externe, si vous n'en fournissez pas, le service en génère une.
Recommandé: Avant de la modifier ou de la supprimer, consultez la page Détails de la passerelle pour connaître le nombre de périphériques qui dépendent de la passerelle.
Ne pas: Associez une instance Gateway à une autre instance Gateway.

Connecté indirectement

Utiliser quand: Un autre périphérique, généralement une passerelle, envoie des données de télémétrie et reçoit des commandes au nom du périphérique.
Requis: Une ou plusieurs associations de passerelle sont requises. Utilisez plusieurs passerelles lorsqu'un périphérique sans fil peut errer entre les passerelles. Confirmez avec un administrateur si cela fonctionne dans votre environnement.
Pour les données structurées: Pour les données structurées, un adaptateur jumeau numérique est requis. Le modèle de jumeau numérique correspondent peut être fourni ou déduit de l'adaptateur, en spécifiant le DTMI ou l'OCID du modèle de jumeau numérique, le modèle doit contenir au moins une télémétrie, une propriété ou une commande.
Pour les données non structurées: Pour les données non structurées, n'utilisez pas d'adaptateur de jumeau numérique ou de modèle de jumeau numérique. Vous ne pouvez pas obtenir de contenu pour les données non structurées car elles ne contiennent pas de modèle jumeau numérique.
Entrée facultative: Clé externe, si vous ne fournissez pas de clé externe, le service en génère une.
ID d'authentification: N'utilisez pas d'ID d'authentification pour une instance de jumeau numérique connectée indirectement.

Non connecté

Utiliser quand: Test d'une instance de jumeau numérique qui n'authentifie, n'envoie ou ne reçoit pas de données d'appareil afin que vous puissiez tester les relations de jumeau numérique pour tester votre configuration IoT sans la complexité des données ou de l'authentification.
Requis: Pour les données structurées, un modèle de jumeau numérique est requis et ne doit pas contenir de télémétrie, de propriétés ou de commandes.
Facultatif: Relations de jumeaux numériques pour les tests. Pour plus d'informations, reportez-vous à Relations numériques avec les jumeaux.
Ne pas utiliser: ID d'authentification, clé externe, adaptateur de jumeau numérique, association de passerelle ou données d'appareil sur les instances de jumeau numérique non connectées.

FAQ

Cette FAQ décrit les scénarios utilisateur de passerelle décrits dans ce scénario.

Puis-je configurer une instance de jumeau numérique pour qu'elle soit connectée indirectement afin qu'un autre appareil envoie des données en son nom ?

Oui. Créez l'instance de jumeau numérique pour l'appareil avec le type de connectivité INDIRECT et associez-la à des instances de jumeau numérique de passerelle au lieu de lui attribuer son propre ID d'authentification.

Comment savoir quels appareils sont connectés via une passerelle spécifique et comprendre l'impact de la perte de cette passerelle ?

Utilisez la page de détails de passerelle pour vérifier le nombre d'appareils associés et la liste des instances de jumeaux numériques dépendantes. Vous obtenez ainsi la vue la plus rapide du rayon d'impact de la passerelle avant les opérations de maintenance, de migration ou de suppression.

Comment savoir combien de mes instances de jumeau numérique sont directement connectées, indirectement connectées ou passerelles ?

Sur la page de liste de l'instance de jumeau numérique ou de la passerelle, vous pouvez trouver la liste des passerelles.

Vérifiez le type de connectivité de chaque jumeau numérique et utilisez une passerelle de niveau domaine et des vues de topologie pour obtenir des informations sur votre environnement. Ce scénario présente un périphérique direct, une passerelle et plusieurs périphériques indirects afin que vous puissiez comparer les trois modèles.

Comment configurer un adaptateur pour ma passerelle afin que la télémétrie entrante soit acheminée vers le périphérique cible approprié ?

Utilisez un adaptateur jumeau numérique pour la passerelle qui inclut un mapping target dans l'enveloppe. Reportez-vous à Etape 2 : création d'adaptateurs jumeaux numériques.

Quand placer target dans les routages entrants plutôt que dans l'enveloppe entrante ?

Non Placez target dans l'enveloppe entrante.

Que se passe-t-il si target est vide ou NULL ?

Le message est traité comme des données de passerelle au lieu d'être délégué à un périphérique connecté indirectement.

Un adaptateur de passerelle peut-il gérer à la fois la télémétrie de passerelle et la télémétrie d'appareil connecté indirectement ?

Oui. C'est l'objectif principal du routage de passerelle. Les messages de périphérique transférés vont vers une cible résolue, tandis que les données de cible vide ou sans correspondance restent avec la passerelle.

Puis-je réutiliser une passerelle entre des appareils connectés directement et indirectement sans dupliquer mes définitions ?

Oui. Traitez la passerelle comme une ressource réutilisable, créez les adaptateurs correspondants une fois, puis associez la passerelle à chaque périphérique connecté indirectement qui doit utiliser cette condition de routage d'adaptateur.

Puis-je envoyer des télémesures non structurées à partir d'appareils connectés indirectement ?

Oui. Si vous n'avez pas besoin d'un mapping de charge utile structurée pour le périphérique cible, vous pouvez envoyer la charge utile brute via la passerelle et ignorer l'adaptateur propre au périphérique.

Puis-je appeler des commandes non structurées sur des appareils connectés indirectement et sur la passerelle elle-même ?

Oui. Utilisez des adresses de commande brutes pour les deux modèles. Ajoutez une adresse de réponse à la commande non structurée lorsque vous avez besoin que la passerelle publie un accusé de réception de niveau application pour le périphérique cible.

--request-endpoint, par exemple boilers/boiler1/actions/reset

--response-endpoint, par exemple boilers/boiler1/actions/response

Puis-je associer un appareil à plusieurs passerelles afin qu'il puisse errer ?

Oui. Un dispositif connecté indirectement peut être associé à une ou plusieurs passerelles. Cela permet à un appareil sans fil de conserver la même instance de jumeau numérique lorsqu'il se déplace entre les passerelles disponibles.

Dans la CLI, vous pouvez configurer l'itinérance multi-passerelle à l'aide d'une baie pour l'association de passerelle du modèle de jumeau numérique.

Utilisez l'option --gateways avec un tableau JSON d'OCID d'instance de jumeau numérique de passerelle :

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

Si vous préférez éviter les problèmes de citation de shell, placez la liste des passerelles dans un fichier d'entrée roaming-device.json et utilisez --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"
}

Avant de dépendre de l'itinérance multi-passerelles en production, vérifiez le comportement dans votre environnement de test et validez le modèle de transfert utilisé par vos passerelles.

Dépannage

La commande reste à l'état ACCEPTED

Dans Etape 6 : appels de commandes, si vous n'incluez pas le paramètre --request-data, la commande reste à l'état ACCEPTED et génère une erreur : Invalid Command Invocation id [unique-id]: [Previous command invocation is not finished yet]

Etapes suivantes

Supprimez les ressources utilisées pour créer ce scénario :

Documentation Oracle Cloud Infrastructure