Documentazione dell'infrastruttura Oracle Cloud

Scenario: ricezione di comandi e invio di risposte mediante MQTT

Utilizzare questo scenario per ricevere comandi nel cloud e inviare risposte a un dispositivo utilizzando il protocollo MQTT per interagire con i dispositivi Internet of Things (IoT).

Task

Per completare i passi riportati di seguito, è possibile utilizzare un dominio IoT esistente e un gruppo di domini IoT oppure creare un gruppo di domini IoT e un dominio IoT, quindi completare i passi riportati di seguito.

  1. Creare un'istanza digital twin
  2. Definire il comando in un file JSON
  3. Richiama comando JSON raw
  4. Utilizzare MQTTX per connettersi a un gemello digitale utilizzando un ID esterno
  5. Eseguire la sottoscrizione a un argomento per ricevere i comandi
  6. Monitora lo stato di consegna del comando in APEX
  7. Visualizza la risposta di un comando in MQTTX

Passo 1: creare un'istanza Digital Twin

Uso dell'interfaccia CLI

  1. Quando crei un'istanza digital twin, utilizza un segreto o un certificato in modo che l'istanza digital twin possa eseguire l'autenticazione in modo sicuro. Per completare questo scenario, è necessario creare un segreto o creare un certificato. Oracle consiglia di utilizzare un segreto per ogni istanza digital twin.

  2. Utilizzare il comando oci iot digital-twin-instance create e i parametri richiesti per creare un gemello digitale. L'esempio seguente mostra il comando con i parametri nome visualizzato e ID di autenticazione.

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

    In questa risposta di esempio, osservare il valore della chiave esterna. Utilizzare questo valore di chiave esterna in Passo 3: Utilizzare MQTTX per connettersi utilizzando un ID esterno:

    "external-key": "<unique-id>"
    {
  "data": {
    "auth-id": "<vault-secret-or-certificate-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-05T18:03:15.264Z"
      }
    },
    "description": null,
    "digital-twin-adapter-id": null,
    "digital-twin-model-id": null,
    "digital-twin-model-spec-uri": null,
    "display-name": "HVAC-instance",
    "external-key": "<unique-id>",
    "freeform-tags": {},
    "id": "<iot-digital-twin-instance-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-08-05T18:03:15.870000+00:00",
    "time-updated": "2025-08-05T18:03:15.870000+00:00"
  },
  "etag": "<unique-id>"
}

Passo 2: definire il comando in un file JSON

È possibile definire il comando in un file JSON e utilizzare questo file nel passo successivo.

Il file command.json in questo esempio contiene i comandi seguenti per richiamare il comando ed elaborare la risposta in base alle istruzioni contenute nel file. 

{
  "requestEndpoint": "/endpoints/1234",
  "requestDuration": "PT3M",
  "requestDataFormat": "JSON",
  "requestData": {
    "temp": 33
  },
  "requestDataContentType": "application/json",
  "responseEndpoint": "/endpoints/4321",
  "responseDuration": "PT3M"
}
  • requestEndpoint: il percorso URL /endpoints/1234 in cui verrà inviata la richiesta. In genere si tratta di un endpoint API o di un indirizzo in cui la piattaforma IoT ascolta i comandi.
  • requestDuration: la durata consentita o richiesta per il completamento della richiesta, nel formato di durata ISO 8601. PT3M, pari a 3 minuti.
  • requestDataFormat: specifica il formato data per i dati inviati nella richiesta JSON.
  • requestData: il payload JSON inviato con una coppia di valori chiave per impostare un valore di temperatura sul dispositivo:
    "temp": 33
Per informazioni sulle posizioni dei file e sui tipi di percorso, vedere Uso di un file JSON per l'input complesso.

Passaggio 3: richiamare un comando JSON raw su un dispositivo

È possibile utilizzare l'interfaccia CLI o l'API per richiamare un comando su un dispositivo. L'esempio riportato di seguito utilizza l'interfaccia CLI.

Uso dell'interfaccia CLI

Utilizzare il comando e i parametri oci iot digital-twin-instance invoke-raw-json-command per richiamare un comando JSON raw su un dispositivo.

Sostituire <digital-twin-instance-OCID> con l'OCID dell'istanza digital twin dal Passo 1: creazione di un'istanza Digital Twin. Questo esempio mostra una richiesta di un valore di temperatura dal dispositivo utilizzando il comando raw JSON definito nel file command.json definito nel Passo 2: Definire il comando in un file JSON.

oci iot digital-twin-instance invoke-raw-json-command --digital-twin-instance-id <digital-twin-instance-OCID> --request-endpoint "/endpoints/1234" --from-json --file://command.json
Per ulteriori informazioni sugli altri tipi di comando, vedere Invio di un comando raw da un'istanza Digital Twin.

Passo 4: Utilizzare MQTTX per connettersi al dispositivo utilizzando un ID esterno

Utilizzare qualsiasi client MQTT, questo esempio utilizza MQTTX con le seguenti impostazioni.
  1. Il download e la configurazione di MQTTX seguono queste istruzioni, vedere Guida introduttiva a MQTTX. Apri MQTTX.
  2. Selezionare + Nuova connessione per creare una nuova connessione.
  3. Immettere il valore <unique-id> della chiave esterna come nome utente. È possibile trovare la chiave esterna nella risposta oci iot digital-twin-instance create, dal Passo 1 precedente: creazione di un'istanza Digital Twin:
    "external-key": "<unique-id>"
  4. Immettere la password del dispositivo.
  5. Immettere l'host. Selezionare il protocollo mqtts:// dall'elenco a discesa host e immettere l'host del dispositivo: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com dal dominio IoT.
  6. Immettere la porta, ad esempio: 8883
  7. Attivare l'opzione di attivazione/disattivazione SSL/TLS.
  8. Attivare l'opzione SSL Secure.
  9. Per il certificato, selezionare l'opzione Certificato server con firma CA.
  10. Quando si configura la connessione MQTTX, assicurarsi di connettersi utilizzando un clean session e impostare l'opzione Last-Will-Retain su false per consentire la conservazione delle sottoscrizioni client se il dispositivo si disconnette brevemente.
  11. Impostare Ultima esecuzione QoS su 1.
  12. Selezionare Connetti.

Questa immagine mostra le impostazioni in MQTTX, fare clic con il pulsante destro del mouse e aprire in una nuova scheda per visualizzare uno screenshot più grande.

Nelle impostazioni MQTTX per richiamare un comando.

Per visualizzare uno screenshot più grande, fare clic con il pulsante destro del mouse e aprirlo in una nuova scheda.

In MQTTX selezionare Connetti.

Passo 5: Esegui sottoscrizione a un argomento per ricevere risposte in MQTTX

Quando il sistema esterno o il dispositivo IoT pubblica un messaggio nell'argomento sottoscritto, i messaggi in entrata vengono visualizzati in MQTTX in tale argomento. Se si è in attesa di una risposta da un comando precedente, assicurarsi di aver eseguito la sottoscrizione all'argomento di risposta corretto impostato in modo dinamico nella risposta dell'istanza gemella digitale come valore <external-id>.

  1. In MQTTX, selezionare + Nuova sottoscrizione.
  2. Immettere l'endpoint come argomento.
  3. Nel menu a discesa QoS selezionare 1 Almeno una volta.
  4. Selezionare Conferma.
Utilizzare le impostazioni di connessione riportate di seguito per ricevere i messaggi pubblicati in un endpoint di dispositivo per l'istanza gemello digitale con un ID esterno specifico.
  • ID client: oracle-test-user-42
  • Nome utente: ID esterno.
  • Password: immettere la password del dispositivo.
  • Immettere mqtts:// con host dispositivo e numero porta:

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

Per visualizzare uno screenshot più grande, fare clic con il pulsante destro del mouse e aprirlo in una nuova scheda.In MQTTX immettere l'enpoint come argomento e confermare la sottoscrizione.

Passo 6: monitorare lo stato di consegna del comando in APEX

Per visualizzare i dati IoT in APEX, è necessario configurare l'accesso ai dati. Una volta completata la configurazione, è possibile utilizzare APEX per utilizzare i dati IoT.

  1. In APEX, eseguire il login all'area di lavoro del dominio IoT specifico utilizzando quanto segue come nome area di lavoro e nome utente database. Osservare i due caratteri di sottolineatura nel nome dello schema di database:
    <domain-short-id-from-device-host>__IOT
    Andare a SQL Workshop e selezionare SQL Commands per eseguire una query sui dati IoT.
  2. Immettere il comando seguente, sostituire <digital-twin-instance-OCID> con l'OCID del gemello digitale e selezionare Esegui per eseguire una query sui dati del comando raw: 
    select * from raw_command_data
where digital_twin_instance_id='<digital-twin-instance-OCID>'
  3. In Risultati, visualizzare RESPONSE_DATA:
    {"test":1}
Per visualizzare uno screenshot più grande, fare clic con il pulsante destro del mouse e aprirlo in una nuova scheda.Visualizzare i dati di risposta del dispositivo in APEX.

Passo 7: Visualizza la risposta del comando in MQTTX

In MQTTX, selezionare Connetti per visualizzare la risposta:
{
    "test": 1
  }

Per visualizzare uno screenshot più grande, fare clic con il pulsante destro del mouse e aprirlo in una nuova scheda.

In MQTTX visualizzare i dati di risposta del comando.