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 dettagliate su ogni 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 del 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 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 della porta mqtt.googleapis.com:8883
. La porta 8883 è la porta TCP standard riservata con IANA per le connessioni MQTT sicure. Le connessioni a questa porta devono utilizzare il trasporto 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, consegnato al massimo una volta
- QoS 1, consegnato almeno una volta
- QoS 2, consegnato esattamente una volta
Cloud IoT Core non supporta la funzionalità QoS 2. La pubblicazione di messaggi QoS 2 comporta la chiusura della connessione. L'abbonamento a un argomento predefinito con QoS 2 comporta il downgrade del livello QoS a QoS 1.
QoS 0 e 1 funzionano come segue in Cloud IoT Core:
- Un messaggio
PUBLISH
con QoS 1 verrà confermato dal messaggioPUBACK
dopo che sarà stato inviato correttamente a Cloud Pub/Sub. PUBLISH
messaggi con QoS 0 non richiedono rispostePUBACK
e potrebbero essere eliminati se è presente un tremolio lungo il percorso di consegna dei messaggi (ad esempio, se Cloud Pub/Sub non è temporaneamente disponibile).- Il bridge MQTT Cloud IoT Core mantiene un piccolo buffer di messaggi non recapitati per riprovare. Se il buffer viene esaurito, il messaggio con QoS 1 può essere eliminato e il messaggio
PUBACK
non viene inviato al client. Il client dovrebbe inviare di nuovo il messaggio.
Per le configurazioni dei dispositivi, i livelli di QoS sono i seguenti:
- Quando QoS è 0, una determinata versione di configurazione verrà pubblicata sul dispositivo una sola volta. Se il dispositivo non riceve la configurazione, deve riabbonarsi. Un QoS pari a 0 è quindi utile quando una configurazione viene aggiornata di frequente (in secondi o minuti) e non è necessario che il dispositivo riceva ogni aggiornamento.
- Quando QoS è 1, l'ultimo aggiornamento della configurazione verrà ripetuto fino a quando il dispositivo non lo confermerà con un PUBACK. Se viene eseguito il push di una configurazione più recente prima di accettare quella precedente, quella meno recente non verrà pubblicata nuovamente e verrà invece pubblicata (e ripubblicata) quella nuova. Questo livello è la modalità più sicura per le configurazioni dei dispositivi: garantisce che alla fine il dispositivo riceva la configurazione più recente.
Download dei certificati server MQTT
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é con un furto d'identità. I seguenti pacchetti di certificati supportano la verifica:
Il pacchetto di certificazione per la CA radice di Google completa (128 kB) per
mqtt.googleapis.com
.- Questo pacchetto definisce la catena di fiducia per comunicare con i prodotti e i servizi Google, incluso Cloud IoT Core.
- I dispositivi con il pacchetto completo di certificazione CA radice comunicano direttamente con il server MQTT.
- Questo pacchetto viene aggiornato regolarmente.
Set CA radice minimo di Google (<1 kB) per
mqtt.2030.ltsapis.goog
. Il set minimo di CA radice include un certificato principale e un certificato di backup.- Questo set è destinato ai dispositivi con limiti di memoria, come i microcontroller, e stabilisce la catena di affidabilità per comunicare solo con Cloud IoT Core.
- I dispositivi con il set minimo di CA radice comunicano con Cloud IoT Core tramite domini di assistenza a lungo termine.
- Questo insieme è stato risolto nel 2030 (i certificati principale e di backup non cambiano). Per maggiore sicurezza, Google Trust Services può passare dai certificati principali a quelli di backup in qualsiasi momento senza preavviso.
Dopo aver scaricato i certificati CA radice di Google sul tuo dispositivo, puoi configurare un client MQTT per autenticare il 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 l'autenticazione di un dispositivo:
- Imposta l'ID client MQTT sul percorso completo del dispositivo:
projects/PROJECT_ID/locations/REGION/registries/REGISTRY_ID/devices/DEVICE_ID
- Associa il client MQTT ai certificati per 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 minimo di CA radice). - 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 JWT.
L'esempio seguente mostra come configurare il client MQTT per autenticare un dispositivo:
C++
I passaggi per configurare l'ID client e l'autenticazione di un dispositivo sono evidenziati di seguito: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) ti consentono di utilizzare una configurazione TLS per un periodo di tempo prolungato. Puoi impostare un client MQTT una volta, configurare il client MQTT per pubblicare messaggi tramite un dominio LTS e quindi comunicare continuamente sul bridge MQTT durante il periodo di tempo supportato.
L'attuale dominio LTS attivo è mqtt.2030.ltsapis.goog
. Questo dominio LTS è supportato fino al 2030.
Per utilizzare il dominio LTS:
Configurare un client MQTT per pubblicare messaggi tramite un dominio LTS.
- Configura il client MQTT per autenticare il dispositivo in Cloud IoT Core.
- Durante la configurazione del dispositivo, associa i certificati radice minimi principali e il backup CA radice impostato con il client MQTT.
Avvia un handshake TLS su
mqtt.2030.ltsapis.goog
sulla porta 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 la suite di crittografia
- Indicazione del nome del server (SNI)
- DNS tramite TCP o UDP
Per ulteriori informazioni sulla protezione del traffico MQTT, inclusi i messaggi inviati ai 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 connesso al bridge MQTT, può pubblicare un evento di telemetria emettendo un messaggio PUBLISH
in 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 di sistema corrispondente. L'argomento predefinito di telemetria è 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 su altri argomenti Cloud Pub/Sub, consulta Pubblicazione di eventi di telemetria in altri argomenti Cloud Pub/Sub.
Il campo dei dati del messaggio inoltrato contiene una copia del messaggio pubblicato dal dispositivo e i seguenti attributi 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 registro. |
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 può essere modificato. |
deviceRegistryLocation |
L'area geografica di Google Cloud Platform del Registro di sistema del dispositivo, ad esempio us-central1 . |
deviceRegistryId |
L'identificatore di stringa definito dall'utente per il registro dispositivi, ad esempio registry1 . |
projectId |
L'ID stringa del progetto cloud proprietario del registry 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 l'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 altri argomenti 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 ulteriori 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 registry 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 è specificata una sottocartella, ma non esiste 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 dello stato del 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 relativo allo stato del dispositivo. L'argomento relativo allo stato del dispositivo è l'argomento Cloud Pub/Sub specificato nel campo StateNotificationConfig.pubsubTopicName
. Se il registry è configurato con un argomento relativo allo stato del dispositivo, questi messaggi vengono inoltrati all'argomento Cloud Pub/Sub corrispondente.
Per maggiori dettagli sul recupero dei messaggi di stato, vedi Recuperare lo stato del dispositivo.
Limitazione del traffico MQTT
Cloud IoT Core limita i progetti che generano un carico eccessivo. Quando i dispositivi ritengono le operazioni non riuscite senza attendere, possono attivare limiti che interessano tutti i dispositivi nello stesso progetto Google Cloud.
Per i nuovi tentativi, ti consigliamo vivamente di implementare un algoritmo di backoff esponenziale troncato con tremolio introdotto.
Keep-Alive
Quando invii il messaggio CONNECT
MQTT iniziale da un client, puoi fornire un
valore facoltativo "keep-alive" Questo valore è un intervallo di tempo, espresso in secondi,
durante il quale l'intermediario si aspetta che un client invii un messaggio, ad esempio un messaggio
PUBLISH
. Se durante il periodo di validità dell'intervallo non viene inviato
alcun messaggio dal client, quest'ultimo chiude automaticamente la connessione. Tieni presente che il valore keep-alive specificato viene moltiplicato per 1,5, pertanto l'impostazione di un keep-alive di 10 minuti dà origine a 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 l'intervallo keep-alive del client su un minimo di 60 secondi. Molte librerie client open source, tra cui le librerie Paho MQTT 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 il 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 applicato il timeout inattivo predefinito di 20 minuti.
Risolvere i problemi
Se hai difficoltà a connetterti, consulta la sezione Risoluzione dei problemi.