Questa sezione spiega in che modo i dispositivi possono utilizzare il bridge MQTT per comunicare con Cloud IoT Core. Per informazioni generali su HTTP e MQTT, vedi Protocolli.
Per informazioni complete su ciascun metodo descritto in questa sezione, consulta la documentazione dell'API. Vedi anche gli esempi relativi a MQTT.
Per pubblicare tramite il bridge MQTT:
Installa un client MQTT sul tuo dispositivo.
Scarica un certificato server MQTT sul dispositivo.
Configura il client MQTT per autenticare il dispositivo in Cloud IoT Core.
Avvia un handshake TLS su
mqtt.googleapis.com
o su un dominio di assistenza a lungo termine.Pubblica eventi di telemetria o imposta lo stato del dispositivo.
Server MQTT
Cloud IoT Core supporta il protocollo MQTT eseguendo un intermediario gestito che rimane in ascolto sulla porta mqtt.googleapis.com:8883
. La porta 8883 è la porta TCP standard prenotata con IANA per le connessioni MQTT sicure. Le connessioni a questa porta devono utilizzare il trasferimento TLS, che è supportato dai client open source come Eclipse Paho.
Se la porta 8883 è bloccata dal firewall, puoi anche utilizzare la porta 443: mqtt.googleapis.com:443
.
Qualità del servizio (QoS)
La specifica MQTT descrive tre livelli di qualità del servizio (QoS):
- QoS 0, pubblicazione al massimo una volta
- QoS 1, pubblicato almeno una volta
- QoS 2, pubblicato esattamente una volta
Cloud IoT Core non supporta QoS 2. La pubblicazione di messaggi QoS 2 chiude la connessione. L'abbonamento a un argomento predefinito con QoS 2 esegue il downgrade del livello QoS a QoS 1.
Le funzioni QoS 0 e 1 funzionano come segue in Cloud IoT Core:
- Un messaggio
PUBLISH
con QoS 1 verrà confermato dal messaggioPUBACK
dopo che è stato inviato correttamente a Cloud Pub/Sub. PUBLISH
messaggi con QoS 0 non richiedono rispostePUBACK
e potrebbero essere eliminati se c'è un jitter lungo il percorso di recapito del messaggio (ad esempio, se Cloud Pub/Sub è temporaneamente non disponibile).- Il bridge MQTT di Cloud IoT Core mantiene un piccolo buffer di messaggi non recapitati per poterli riprovare. Se il buffer si esaurisce, il messaggio con QoS 1 potrebbe essere ignorato e un messaggio
PUBACK
non verrà inviato al client. Il client è tenuto a inviare nuovamente il messaggio.
Per le configurazioni di dispositivi, i livelli di QoS sono i seguenti:
- Quando QoS è 0, una determinata versione di configurazione verrà pubblicata sul dispositivo solo una volta. Se il dispositivo non riceve la configurazione, deve iscriversi nuovamente. Una QoS pari a 0 è quindi utile quando una configurazione viene aggiornata di frequente (nell'ordine di secondi o minuti) e non è necessaria che il dispositivo riceva ogni aggiornamento.
- Se il valore QoS è 1, verrà eseguito nuovamente l'ultimo aggiornamento della configurazione finché il dispositivo non lo confermerà con un PUBACK. Se viene eseguito il push di una configurazione più recente prima che quella precedente venga confermata, la precedente non verrà caricata nuovamente, ma la nuova verrà pubblicata (e ripubblicata). Questo livello è la modalità più sicura per le configurazioni dei dispositivi: garantisce che alla fine il dispositivo riceverà la configurazione più recente.
Download dei certificati server MQTT in corso...
Per utilizzare il trasporto TLS, i dispositivi devono verificare i certificati server di Cloud IoT Core per assicurarsi di comunicare con Cloud IoT Core anziché un furto d'identità. I seguenti pacchetti di certificati supportano la verifica:
Il pacchetto di certificazione CA radice di Google completo (128 kB) per
mqtt.googleapis.com
.- Questo pacchetto stabilisce la catena di fiducia per la comunicazione con i prodotti e i servizi Google, incluso Cloud IoT Core.
- I dispositivi con il pacchetto di certificazione CA completo possono comunicare direttamente con il server MQTT.
- Questo pacchetto viene aggiornato regolarmente.
Set minimo di CA radice di Google (< 1 KB) per
mqtt.2030.ltsapis.goog
. Il set di CA radice minimo include un certificato principale e un backup.- Questo set è per i dispositivi con vincoli di memoria, come i microcontroller, e stabilisce la catena di attendibilità per comunicare solo con Cloud IoT Core.
- I dispositivi con un insieme di CA radice minimo comunicano con Cloud IoT Core tramite domini di assistenza a lungo termine.
- Questo insieme viene corretto fino al 2030 (i certificati principale e di backup non cambieranno). Per maggiore sicurezza, i Servizi Google Trust possono passare dal certificato principale a quello di backup in qualsiasi momento e senza preavviso.
Dopo aver scaricato i certificati CA radice di Google sul tuo dispositivo, puoi configurare un client MQTT per l'autenticazione del dispositivo, connetterti al server MQTT e comunicare tramite il bridge MQTT.
Configurazione dei client MQTT
I client MQTT autenticano i dispositivi connettendosi al bridge MQTT. Per configurare un client MQTT per autenticare un dispositivo:
- Imposta l'ID client MQTT sul percorso completo del dispositivo:
projects/PROJECT_ID/locations/REGION/registries/REGISTRY_ID/devices/DEVICE_ID
- Associare il client MQTT ai certificati server MQTT.
- Imposta il nome host MQTT su
mqtt.googleapis.com
o su un dominio di assistenza a lungo termine (se hai utilizzato il set di CA radice minimo). - Specifica un nome utente. Il bridge MQTT ignora il campo del nome utente, ma alcune librerie client MQTT non inviano il campo della password a meno che non venga specificato il campo del nome utente. Per ottenere risultati ottimali, fornisci un nome utente arbitrario come
unused
oignored
. - Imposta la password. Il campo della password deve contenere il codice JWT.
L'esempio seguente mostra come configurare il client MQTT per autenticare un dispositivo:
C++
Di seguito sono riportati i passaggi per configurare l'ID client e autenticare un dispositivo:Java
Node.js
Python
Questo esempio utilizza la libreria client delle API di Google per Python.Utilizzo di un dominio MQTT a lungo termine
I domini di assistenza a lungo termine (LTS) consentono di utilizzare una configurazione TLS per un periodo di tempo prolungato. Puoi configurare un client MQTT una volta, configurare il client MQTT per pubblicare i messaggi tramite un dominio LTS e comunicare continuamente sul bridge MQTT durante il periodo di tempo supportato.
Attualmente, il dominio LTS attivo è mqtt.2030.ltsapis.goog
. Questo dominio LTS è supportato fino al 2030.
Per utilizzare il dominio LTS:
Configura un client MQTT per pubblicare i messaggi tramite un dominio LTS.
- Configura il client MQTT per autenticare il dispositivo in Cloud IoT Core.
- Quando configuri il dispositivo, associa i certificati principali e di backup del set di CA radice minimo al client MQTT.
Avvia un handshake TLS sulla porta
mqtt.2030.ltsapis.goog
8883 o 443. Utilizza almeno le seguenti funzionalità TLS.- TLS 1.2
- P-256 con SHA-256 come chiave del certificato e algoritmo hash
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 tramite P-256 e punti non compressi per il pacchetto di crittografia
- Indicazione del nome del server (SNI)
- DNS su TCP o UDP
Per ulteriori informazioni sulla protezione del traffico MQTT, inclusi i messaggi inviati a domini LTS, vedi Consigli per la sicurezza dei dispositivi.
Pubblicazione di eventi di telemetria
Una volta che il dispositivo è stato configurato con un client MQTT e si è connesso al bridge MQTT, può pubblicare un evento di telemetria inviando un messaggio PUBLISH
a un argomento MQTT nel seguente formato:
/devices/DEVICE_ID/events
L'ID dispositivo è l'ID stringa del dispositivo specificato nell'ID client MQTT. L'ID dispositivo è sensibile alle maiuscole.
I messaggi pubblicati in questo argomento MQTT vengono inoltrati all'argomento di telemetria predefinito del registro corrispondente. L'argomento di telemetria predefinito è l'argomento Cloud Pub/Sub specificato nel campo eventNotificationConfigs[i].pubsubTopicName
nella risorsa del Registro di sistema.
Se non esiste un argomento Pub/Sub predefinito, i dati di telemetria pubblicati andranno persi.
Per pubblicare messaggi in altri argomenti Cloud Pub/Sub, consulta Pubblicazione di eventi di telemetria in altri argomenti Cloud Pub/Sub.
Il campo dei dati dei messaggi inoltrati contiene una copia del messaggio pubblicato dal dispositivo e i seguenti attributi di messaggio vengono aggiunti a ogni messaggio nell'argomento Cloud Pub/Sub:
Attributo | Descrizione |
---|---|
deviceId |
L'identificatore di stringa definito dall'utente per il dispositivo, ad esempio thing1 . L'ID dispositivo deve essere univoco all'interno del registry. |
deviceNumId |
L'ID numerico del dispositivo generato dal server. Quando crei un dispositivo, Cloud IoT Core genera automaticamente l'ID numerico del dispositivo, che è univoco a livello globale e non modificabile. |
deviceRegistryLocation |
La regione del registry del dispositivo Google Cloud Platform, ad esempio us-central1 . |
deviceRegistryId |
L'identificatore di stringa definito dall'utente per il registro di dispositivi, ad esempio registry1 . |
projectId |
L'ID stringa del progetto cloud proprietario del registro e del dispositivo. |
subFolder |
La sottocartella può essere utilizzata come categoria di evento o classificazione. Per i client MQTT, la sottocartella è l'argomento secondario dopo DEVICE_ID/events , che viene copiato direttamente. Ad esempio, se il client pubblica nell'argomento MQTT /devices/DEVICE_ID/events/alerts , la sottocartella è la stringa alerts . |
L'esempio seguente mostra come inviare messaggi PUBLISH
tramite la connessione MQTT:
C++
Questo esempio utilizza la libreria client delle API di Google per Python.Java
Node.js
Python
Questo esempio utilizza la libreria client delle API di Google per Python.Pubblicazione di eventi di telemetria in argomenti aggiuntivi di Cloud Pub/Sub
I dispositivi possono pubblicare dati in altri argomenti Cloud Pub/Sub. Per impostazione predefinita, i messaggi MQTT pubblicati in /devices/DEVICE_ID/events
vengono inoltrati all'argomento di telemetria predefinito del Registro di sistema corrispondente. Nell'argomento MQTT puoi specificare una sottocartella per inoltrare i dati ad altri argomenti Cloud Pub/Sub.
La sottocartella è l'argomento secondario dopo /devices/DEVICE_ID/events
.
I messaggi pubblicati in una sottocartella vengono inoltrati all'argomento Cloud Pub/Sub con lo stesso nome. Il registro corrispondente deve essere configurato con l'argomento Cloud Pub/Sub; in caso contrario, i messaggi vengono inoltrati all'argomento Cloud Pub/Sub predefinito.
I messaggi vengono inoltrati all'argomento Cloud Pub/Sub predefinito anziché all'argomento Cloud Pub/Sub aggiuntivo nei seguenti casi:
- Nessuna sottocartella specificata nell'argomento MQTT
- Nell'argomento MQTT è stata specificata una sottocartella, ma non è presente un argomento Pub/Sub corrispondente nel registro dispositivi
Ad esempio, se il dispositivo pubblica nell'argomento MQTT /devices/DEVICE_ID/events/alerts
, la sottocartella è la stringa alerts
. I messaggi vengono inoltrati all'argomento Cloud Pub/Sub aggiuntivo se i campi eventNotificationConfigs[i].subfolderMatches
e eventNotificationConfigs[i].pubsubTopicName
sono entrambi impostati su alerts
. In caso contrario, i messaggi vengono inoltrati all'argomento predefinito Cloud Pub/Sub.
Impostazione stato dispositivo
I dispositivi connessi possono segnalare lo stato del dispositivo inviando un messaggio PUBLISH
al seguente argomento MQTT:
/devices/DEVICE_ID/state
Per classificare e recuperare i messaggi di stato, configura il Registro di sistema con un argomento di stato del dispositivo. L'argomento dello stato del dispositivo è l'argomento Cloud Pub/Sub specificato nel campo StateNotificationConfig.pubsubTopicName
. Se il registry è configurato con un argomento dello stato del dispositivo, questi messaggi vengono inoltrati all'argomento Cloud Pub/Sub corrispondente.
Per maggiori dettagli sul recupero dei messaggi di stato, vedi Recupero dello stato del dispositivo.
Limitazione del traffico MQTT
Cloud IoT Core limita i progetti che generano un carico eccessivo. Quando i dispositivi tentano di nuovo di eseguire operazioni non riuscite senza attendere, possono attivare limiti che interessano tutti i dispositivi dello stesso progetto Google Cloud.
Per nuovi tentativi, ti consigliamo vivamente di implementare un algoritmo di backoff esponenziale troncato con jitter introdotto.
Mantieni attiva
Quando invii il messaggio CONNECT
MQTT iniziale da un client, puoi fornire un valore facoltativo "keep-alive". Questo valore è un intervallo di tempo, misurato in secondi, durante il quale il mediatore prevede che un client invii un messaggio, ad esempio un messaggio PUBLISH
. Se il client non invia alcun messaggio al broker durante l'intervallo, la connessione viene chiusa automaticamente. Tieni presente che il valore keep-alive specificato viene moltiplicato per 1,5, quindi impostando un valore keep-alive di 10 minuti si ottiene un intervallo di 15 minuti.
Per ulteriori informazioni, consulta la specifica MQTT.
Impostazioni client
Cloud IoT Core non fornisce un proprio valore keep-alive predefinito; se scegli di specificare un intervallo keep-alive, devi impostarlo nel client.
Per ottenere risultati ottimali, imposta un intervallo minimo di conservazione di 60 secondi per il client. Molte librerie client open source, incluse le librerie MQTT di Paho per C, Python, Node.js e Java, utilizzano 60 secondi per impostazione predefinita.
Limite di tempo di inattività
Separato dall'intervallo keep-alive, Cloud IoT Core ha un proprio limite di tempo di inattività di 20 minuti. In base a questo limite, la connessione client viene terminata automaticamente se il client non invia messaggi per 20 minuti, anche se l'intervallo keep-alive è più lungo. Se non viene fornito un valore keep-alive, viene comunque applicato il timeout di inattività predefinito di 20 minuti.
Risolvere i problemi
In caso di problemi di connessione, consulta la sezione Risoluzione dei problemi.