Nesta seção, explicamos como os dispositivos podem usar a ponte MQTT para se comunicar com o Cloud IoT Core. Para informações gerais sobre HTTP e MQTT, consulte Protocolos.
Consulte a documentação da API para ver detalhes completos sobre cada método descrito nesta seção. Consulte também as amostras relacionadas a MQTT (em inglês).
Para publicar pela ponte MQTT:
Instale um cliente MQTT no dispositivo.
Faça o download de um certificado do servidor MQTT para o dispositivo.
Configure o cliente MQTT para autenticar o dispositivo no Cloud IoT Core.
Inicie um handshake de TLS no
mqtt.googleapis.com
ou em um domínio de suporte de longo prazo.Publique eventos de telemetria ou defina o estado do dispositivo.
Servidor MQTT
O Cloud IoT Core oferece suporte ao protocolo MQTT executando um agente gerenciado que detecta a porta mqtt.googleapis.com:8883
. A porta 8883 é a porta TCP padrão reservada com IANA para conexões MQTT seguras. As conexões com essa porta precisam usar a transporte TLS, que é aceita por clientes de código aberto, como o Eclipse Paho (em inglês).
Se a porta 8883 estiver bloqueada pelo firewall, também será possível usar a porta 443: mqtt.googleapis.com:443
.
Qualidade de Serviço (QoS, na sigla em inglês)
A especificação MQTT descreve três níveis de Qualidade de Serviço (QoS):
- QoS 0, entregue no máximo uma vez
- QoS 1, entregue pelo menos uma vez
- QoS 2, entregue exatamente uma vez
O Cloud IoT Core não é compatível com QoS 2. A publicação de mensagens de Qo2 2 encerra a conexão. Fazer a assinatura de um tópico predefinido com QoS 2 faz downgrade do nível de QoS para QoS 1.
As funções QoS 0 e 1 funcionam do seguinte modo no Cloud IoT Core:
- Uma mensagem
PUBLISH
com QoS 1 será confirmada pela mensagemPUBACK
depois de ser enviada ao Cloud Pub/Sub. - As mensagens
PUBLISH
com QoS 0 não exigem respostasPUBACK
e podem ser descartadas se houver instabilidade na rota de entrega da mensagem (por exemplo, se o Cloud Pub/Sub estiver temporariamente indisponível). - A ponte MQTT do Cloud IoT Core mantém um pequeno buffer de mensagens não entregues para repeti-las. Se o buffer ficar cheio, a mensagem com QoS 1 poderá ser descartada e uma mensagem
PUBACK
não será enviada ao cliente. O cliente deverá reenviar a mensagem.
Para as configurações do dispositivo, os níveis de QoS são os seguintes:
- Quando a QoS é igual a zero, uma versão de configuração específica é publicada no dispositivo apenas uma vez. Se o dispositivo não receber a configuração, ele precisará assinar novamente. Assim, um QoS de 0 é útil quando uma configuração é atualizada com frequência (em segundos ou minutos) e não é necessário que o dispositivo receba todas as atualizações.
- Quando a QoS é 1, a atualização mais recente da configuração será repetida até que o dispositivo a reconheça com um PUBACK. Se uma configuração mais recente for enviada antes da confirmação da mais antiga, a mais antiga não será reenviada. Em vez disso, o novo será entregue (e reenviado). Esse nível é o modo mais seguro para configurações de dispositivos: garante que ele receba a configuração mais recente.
Como fazer o download de certificados do servidor MQTT
Para usar o transporte por TLS, os dispositivos precisam verificar os certificados do servidor do Cloud IoT Core para garantir que estão se comunicando com o Cloud IoT Core, em vez de falsificar a identidade. Os seguintes pacotes de certificado são compatíveis com a verificação:
O pacote completo de certificação de CA raiz do Google (128 KB) para
mqtt.googleapis.com
- Esse pacote estabelece a cadeia de confiança para se comunicar com os produtos e serviços do Google, incluindo o Cloud IoT Core.
- Os dispositivos com o pacote completo de certificação de CA raiz se comunicam diretamente com o servidor MQTT.
- Esse pacote é atualizado regularmente.
Conjunto mínimo de CAs raiz (<1 KB) do Google para
mqtt.2030.ltsapis.goog
. O conjunto mínimo de CA raiz inclui um certificado principal e de backup.- Esse conjunto é destinado a dispositivos com restrições de memória, como microcontroladores, e estabelece a cadeia de confiança para se comunicar apenas com o Cloud IoT Core.
- Os dispositivos com o conjunto mínimo de CAs raiz se comunicam com o Cloud IoT Core por meio de domínios de suporte de longo prazo.
- Esse conjunto foi corrigido até 2030. Os certificados principal e alternativo não serão alterados. Para ter mais segurança, o Google Trust Services pode alternar entre os certificados primário e de backup a qualquer momento e sem aviso prévio.
Depois de fazer o download dos certificados de CA raiz do Google para seu dispositivo, você pode configurar um cliente MQTT para autenticá-lo, conectar-se ao servidor MQTT e se comunicar pela ponte MQTT.
Como configurar clientes MQTT
Os clientes MQTT autenticam dispositivos conectando-se à ponte MQTT. Para configurar um cliente MQTT para autenticar um dispositivo:
- Defina o ID do cliente MQTT para o caminho completo do dispositivo:
projects/PROJECT_ID/locations/REGION/registries/REGISTRY_ID/devices/DEVICE_ID
- Associe o cliente MQTT a certificados de servidor MQTT.
- Defina o nome do host do MQTT como
mqtt.googleapis.com
ou um domínio de suporte de longo prazo (se você tiver usado o conjunto mínimo de CA raiz). - Especifique um nome de usuário. A ponte MQTT ignora o campo "nome de usuário", mas algumas bibliotecas de cliente MQTT não enviam o campo de senha, a menos que o campo de nome de usuário seja especificado. Para melhores resultados, forneça um nome de usuário arbitrário, como
unused
ouignored
. - Definir a senha. O campo senha precisa conter o JWT.
Veja na amostra a seguir como configurar o cliente MQTT para autenticar um dispositivo:
C++
As etapas para configurar o ID do cliente e autenticar um dispositivo estão destacadas abaixo:Java
Node.js
Python
Neste exemplo, usamos a biblioteca de cliente de APIs do Google para Python.Como usar um domínio MQTT de longo prazo
Os domínios com suporte de longo prazo (LTS, na sigla em inglês) permitem que você use uma configuração TLS por um longo período. Você pode definir um cliente MQTT uma vez, configurar o cliente MQTT para publicar mensagens por meio de um domínio LTS e, em seguida, comunicar-se pela ponte MQTT continuamente durante o período de tempo compatível.
O domínio LTS ativo atual é mqtt.2030.ltsapis.goog
. Este domínio LTS é compatível até 2030.
Para usar o domínio LTS:
Configurar um cliente MQTT para publicar mensagens por meio de um domínio LTS.
- Configure o cliente MQTT para autenticar o dispositivo no Cloud IoT Core.
- Ao configurar o dispositivo, associe os certificados principal e de backup do conjunto mínimo de CA raiz ao cliente MQTT.
Inicie um handshake de TLS na
mqtt.2030.ltsapis.goog
na porta 8883 ou 443. Use pelo menos os seguintes recursos de TLS.- TLS 1.2
- P-256, com SHA-256 como chave de certificado e algoritmo de hash
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 usando P-256 e pontos descompactados para o pacote de criptografia
- Indicação de nome do servidor (SNI, na sigla em inglês)
- DNS por TCP ou UDP
Para mais informações sobre como proteger o tráfego MQTT, incluindo mensagens enviadas para domínios LTS, consulte Recomendações de segurança do dispositivo.
Como publicar eventos de telemetria
Depois que o dispositivo for configurado com um cliente MQTT e conectado à ponte MQTT, ele poderá publicar um evento de telemetria emitindo uma mensagem PUBLISH
para um tópico MQTT no seguinte formato:
/devices/DEVICE_ID/events
O ID do dispositivo é o ID da string do dispositivo especificado no ID do cliente MQTT. O ID do dispositivo diferencia maiúsculas de minúsculas.
As mensagens publicadas neste tópico do MQTT são encaminhadas para o tópico de telemetria padrão do registro correspondente. O tópico de telemetria padrão é o tópico do Cloud Pub/Sub
especificado no campo eventNotificationConfigs[i].pubsubTopicName
no
recurso de registro.
Se não existir um tópico padrão do Pub/Sub, os dados de telemetria publicados serão perdidos.
Para publicar mensagens em outros tópicos do Cloud Pub/Sub, consulte Como publicar eventos de telemetria para tópicos adicionais do Cloud Pub/Sub.
O campo de dados de mensagem encaminhada contém uma cópia da mensagem publicada pelo dispositivo, e os seguintes atributos de mensagem são adicionados a cada mensagem no tópico do Cloud Pub/Sub:
Atributo | Descrição |
---|---|
deviceId |
O identificador de string definido pelo usuário para o dispositivo, por exemplo, thing1 . O ID do dispositivo precisa ser exclusivo no registro. |
deviceNumId |
O código numérico gerado pelo servidor do dispositivo. Quando você cria um dispositivo, o Cloud IoT Core gera automaticamente o ID numérico do dispositivo. ele é globalmente exclusivo e não editável. |
deviceRegistryLocation |
A região do registro do dispositivo do Google Cloud Platform, por exemplo, us-central1 . |
deviceRegistryId |
O identificador de string definido pelo usuário para o registro do dispositivo, por exemplo, registry1 . |
projectId |
O ID da string do projeto do Cloud proprietário do registro e do dispositivo. |
subFolder |
A subpasta pode ser usada como uma categoria ou classificação de evento. Para clientes MQTT, a subpasta é o subtópico depois de DEVICE_ID/events , que é copiado diretamente. Por exemplo, se o cliente publicar no tópico MQTT /devices/DEVICE_ID/events/alerts , a subpasta será a string alerts . |
O exemplo a seguir mostra como enviar mensagens PUBLISH
por meio da conexão MQTT:
C++
Neste exemplo, usamos a biblioteca de cliente de APIs do Google para Python.Java
Node.js
Python
Neste exemplo, usamos a biblioteca de cliente de APIs do Google para Python.Como publicar eventos de telemetria em tópicos adicionais do Cloud Pub/Sub
Os dispositivos podem publicar dados em tópicos adicionais do Cloud Pub/Sub. Por padrão, as mensagens MQTT publicadas em /devices/DEVICE_ID/events
são encaminhadas para o tópico de telemetria padrão do registro correspondente. É possível especificar uma subpasta no tópico MQTT para encaminhar dados para outros tópicos do Cloud Pub/Sub.
A subpasta é o subtópico após /devices/DEVICE_ID/events
.
As mensagens publicadas em uma subpasta são encaminhadas para o tópico do Cloud Pub/Sub com o mesmo nome. O registro correspondente precisa ser configurado com o tópico do Cloud Pub/Sub. Caso contrário, as mensagens serão encaminhadas para o tópico padrão do Cloud Pub/Sub.
As mensagens são encaminhadas para o tópico padrão do Cloud Pub/Sub, em vez do tópico adicional do Cloud Pub/Sub nos seguintes casos:
- Nenhuma subpasta foi especificada no tópico MQTT
- Uma subpasta é especificada no tópico MQTT, mas não há um tópico correspondente do Pub/Sub no registro do dispositivo
Por exemplo, se o dispositivo publicar no tópico MQTT /devices/DEVICE_ID/events/alerts
, a subpasta será a string alerts
. As mensagens serão encaminhadas para o tópico extra do Cloud Pub/Sub se os campos eventNotificationConfigs[i].subfolderMatches
e eventNotificationConfigs[i].pubsubTopicName
estiverem definidos alerts
. Caso contrário, as mensagens serão encaminhadas para o tópico padrão do Cloud Pub/Sub.
Configuração do estado do dispositivo
Os dispositivos conectados podem relatar o estado do dispositivo emitindo uma mensagem PUBLISH
para o seguinte tópico MQTT:
/devices/DEVICE_ID/state
Para categorizar e recuperar mensagens de estado, configure o registro com um tópico de estado do dispositivo. O tópico de estado do dispositivo é o tópico do Cloud Pub/Sub especificado no campo StateNotificationConfig.pubsubTopicName
. Se o registro estiver configurado com um tópico de estado do dispositivo, essas mensagens serão encaminhadas para o tópico do Cloud Pub/Sub correspondente da melhor maneira possível.
Para mais detalhes sobre como recuperar mensagens de estado, consulte Como saber o estado do dispositivo.
Como limitar o tráfego MQTT
O Cloud IoT Core limita os projetos que geram carga excessiva. Quando os dispositivos repetem operações com falha sem esperar, é possível acionar os limites que afetam todos os dispositivos no mesmo projeto do Google Cloud.
Para novas tentativas, é altamente recomendável implementar um algoritmo de espera exponencial truncada com instabilidade introduzida.
Keep-alive
Ao enviar a mensagem CONNECT
MQTT inicial de um cliente, é possível fornecer um valor de "sinal de atividade" opcional. Esse valor é um intervalo de tempo, medido em segundos, em que o agente espera que um cliente envie uma mensagem, como uma mensagem PUBLISH
. Se nenhuma mensagem for enviada do cliente ao agente durante o
intervalo, ele fechará automaticamente a conexão. Observe que o
valor do sinal de atividade especificado é multiplicado por 1,5.Portanto, definir um sinal de atividade
de 10 minutos realmente resulta em um intervalo de 15 minutos.
Para mais informações, consulte a especificação MQTT.
Configurações do cliente
O Cloud IoT Core não fornece o próprio valor de sinal de atividade padrão. Se você optar por especificar um intervalo de sinal de atividade, precisará configurá-lo no cliente.
Para melhores resultados, defina o intervalo do sinal de atividade do cliente para um mínimo de 60 segundos. Muitas bibliotecas de cliente de código aberto, incluindo as bibliotecas do Paho MQTT para C, Python, Node.js (links em inglês) e Java, use 60 segundos por padrão.
Limite de tempo de inatividade
Separado do intervalo de sinal de atividade, o Cloud IoT Core tem seu próprio limite de tempo de inatividade de 20 minutos. Com base nesse limite, uma conexão de cliente será encerrada automaticamente se o cliente não enviar nenhuma mensagem por 20 minutos, mesmo que o intervalo do sinal de atividade seja maior. Se um valor de sinal de atividade não for fornecido, o tempo limite padrão de inatividade de 20 minutos ainda entrará em vigor.
Solução de problemas
Se você tiver problemas para se conectar, consulte Solução de problemas.