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. Stabilire la sessione MQTT utilizzando le credenziali del broker
  3. Eseguire la sottoscrizione a un argomento per ricevere i comandi
  4. Definire il comando in un file JSON
  5. Richiama comando JSON raw
  6. Verifica in MQTTX
  7. Monitora lo stato di consegna del comando in APEX

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 e, per la produzione, l'istanza digital twin deve utilizzare un certificato mTLS per l'autenticazione.

  2. Utilizzare il comando oci iot digital-twin-instance create e i parametri richiesti per creare un gemello digitale. L'esempio riportato di seguito mostra il comando su come utilizzare il parametro ID autenticazione con il parametro di dominio IoT richiesto per associare il dominio IoT all'istanza gemella digitale.

    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 chiave esterna, notare la chiave esterna che corrisponde al nome utente del dispositivo che è possibile utilizzare nel passo successivo:

    "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: Stabilire la sessione MQTT utilizzando le credenziali del broker

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. Per creare una nuova connessione, selezionare + Nuova connessione. Immettere un nome per la connessione, evitare di fornire informazioni riservate.
  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. Se si utilizza il segreto del vault, è necessario che questo sia il segreto di testo in chiaro oppure è possibile utilizzare un certificato mTLS.
  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. Vedere Recupero dei dettagli di un dominio IoT.
  6. Immettere la porta, ad esempio: 8883
    Nota

    Al momento, MQTT Secure (MQTTS) è supportato solo utilizzando la porta 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:
    • clean session: impostare l'opzione Clean Session su true. Quando la sessione pulita è impostata su true, il broker non conserva alcuna informazione per il client ed elimina qualsiasi stato precedente da qualsiasi sessione persistente. Tutti i dati di sessione vengono eliminati non appena viene chiusa la connessione di rete.
    • 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. Per definire l'affidabilità della consegna "Almeno una volta" per la notifica di disconnessione.
  12. Selezionare Connetti.

Questa immagine mostra queste 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.

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

Quando un sistema esterno o un dispositivo IoT pubblica un messaggio nell'argomento sottoscritto, in MQTTX vengono visualizzati i messaggi in entrata nell'argomento. Se si è in attesa di una risposta da un comando precedente, assicurarsi di aver eseguito la sottoscrizione all'argomento di risposta corretto.

Definire responseEndpoint nel passo successivo quando si definisce il comando in un file JSON. La stringa "responseEndpoint": "/endpoints/4321" rappresenta l'argomento o il percorso dell'endpoint in cui il dispositivo deve pubblicare la risposta. Scegliere un percorso endpoint logico per i percorsi gemelli digitali. È necessario utilizzare lo stesso percorso sia sul lato cloud (quando si invia il comando) che sul lato dispositivo (quando si pubblica la risposta).

  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: your-client-ID
  • Nome utente: ID esterno.
  • Password: immettere la password del dispositivo.
  • Immettere mqtts:// con l'host del dispositivo del dominio IoT e utilizzando la porta numero 8883:

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

Per visualizzare una schermata più grande, fare clic con il pulsante destro del mouse e aprirla in una nuova scheda

.In MQTTX immettere l'enpoint come argomento e confermare la sottoscrizione.

Passo 4: Definire il comando in un file JSON

È possibile definire i dettagli del comando in un file JSON e utilizzare questo file nel passo successivo per richiamare un comando JSON raw su un dispositivo.

Per questo esempio, salvare questo snippet in un file command.json in modo da poterlo utilizzare 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.

    Se si dispone già di un endpoint dedicato alle risposte, ad esempio: /endpoints/<external-id>/response utilizzare tale percorso in responseEndpoint.

    In alternativa, creare un nuovo endpoint/route per l'istanza digital twin nelle regole di instradamento in entrata dell'adattatore digital twin che il dispositivo può pubblicare. Fare riferimento al percorso nel file command.json. Mantenere coerente il percorso dell'endpoint, qualsiasi percorso definito in responseEndpoint diventa l'argomento MQTT a cui il client deve eseguire la sottoscrizione al passo 3 in modo da poter visualizzare la risposta del comando.

  • requestDuration: la durata consentita o richiesta per il completamento della richiesta, nel formato di durata ISO 8601. Ad esempio, PT3M equivale 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 5: 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. 

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 6: Verifica in MQTTX

In MQTTX, osservare i dati richiamati:
{
    "temp": 33
  }

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

In MQTTX selezionare Connetti.

Questa immagine mostra come verificare in MQTTX.

Scenari risposta comando
ScenarioStato dispositivoStato comando previstocommenti
Non connessoNon connesso non sottoscritto RIFIUTATO Consegna comando non riuscita immediatamente
Connesso ma non sottoscrittoConnesso RIFIUTATODispositivo in linea, ma comando non ricevuto
Iscritto ma non connesso Solo sottoscrittoIN SOSPESO → SCADUTOIl comando attende; scade dopo il timeout
Sottoscritto ma inizialmente non connesso e connesso prima del timeout Inizialmente offline IN ATTESA → INVIATOComando ricevuto
Connesso e sottoscrittoConnesso e sottoscritto INVIATO Comando ricevuto
Comando unidirezionale (nessuna risposta prevista)Connesso e sottoscritto COMPLETATO Risposta non prevista e tracciata
Comando bidirezionale (nessuna risposta ricevuta)Connesso e sottoscritto NOT_RESPONDEDIl dispositivo non risponde entro il timeout della durata della risposta
Comando bidirezionale (risposta ricevuta) Connesso e sottoscritto COMPLETATOIl dispositivo invia i dati entro il tempo di risposta e completa il flusso

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