Raspberry Pi com Grafana e InfluxDB para Dados de Sensores MQTT

Uma stack raspberry pi grafana influxdb é uma das formas mais práticas de guardar meses de histórico de sensores em um computador pequeno, silencioso e sob o seu controle. Neste tutorial você vai instalar InfluxDB 2, Telegraf e Grafana em um Raspberry Pi 64 bits, fazer o Telegraf assinar um broker MQTT e montar um dashboard no Grafana que se atualiza conforme novas leituras chegam. Todos os comandos e arquivos de configuração estão completos, então você pode acompanhar em um Pi recém-instalado.

Arquitetura: quem fala com quem

Antes de instalar qualquer coisa, vale entender bem o caminho dos dados, porque é aqui que a maioria das instalações dá errado:

1. Os sensores (placas ESP32, nós Pico W, outros Pis) publicam JSON em um broker MQTT.
2. O Telegraf no Pi se conecta a esse broker como um cliente MQTT comum, assina os topics dos sensores e interpreta o JSON.
3. O Telegraf grava os campos interpretados em um bucket do InfluxDB 2 no mesmo Pi.
4. O Grafana consulta o InfluxDB e desenha os painéis.

O broker em si não grava em banco de dados. Ele apenas roteia mensagens. Se quiser relembrar esse papel, leia o que faz um broker MQTT. Aqui o broker fica na nuvem, o que significa que sensores em outros prédios (outro galpão, a fazenda, a filial) podem publicar nele, e o seu Pi só precisa de uma conexão de saída. Sem redirecionamento de portas, sem DNS dinâmico.

Requisitos

• Raspberry Pi 4 ou 5 com pelo menos 2 GB de RAM. Um Pi 3 pode funcionar com cargas bem leves, mas fica apertado.
• Raspberry Pi OS 64 bits (Bookworm). Os pacotes do InfluxDB 2 são compilados para arm64, então a imagem 32 bits não serve.
• Um SSD via USB 3 é fortemente recomendado. Bancos de séries temporais gravam o tempo todo e cartões SD se desgastam.
• Um sensor que já publique via MQTT. Se você não tiver um, o tutorial de estatísticas do sistema do Raspberry Pi transforma o próprio Pi em fonte de dados em cinco minutos.

Confirme a arquitetura primeiro:

uname -m          # deve imprimir aarch64
cat /etc/os-release | grep VERSION_CODENAME

Instale o InfluxDB 2 e o Telegraf

Os dois vêm do repositório de pacotes da InfluxData. Adicione a chave de assinatura e o repositório e instale:

sudo apt update && sudo apt install -y curl gpg
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repos.influxdata.com/influxdata-archive.key \
  | sudo gpg --dearmor -o /etc/apt/keyrings/influxdata-archive.gpg
echo "deb [signed-by=/etc/apt/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main" \
  | sudo tee /etc/apt/sources.list.d/influxdata.list
sudo apt update
sudo apt install -y influxdb2 influxdb2-cli telegraf
sudo systemctl enable --now influxdb

Execute a configuração inicial, feita uma única vez. Ela cria a organização, o primeiro bucket e o usuário administrador. Escolha um período de retenção compatível com a capacidade do seu SD ou SSD; 90 dias é um bom ponto de partida para sensores de ambiente.

influx setup \
  --org home \
  --bucket sensors \
  --username admin \
  --password 'change-this-long-password' \
  --retention 90d \
  --force

Agora crie um token dedicado para o Telegraf em vez de reutilizar o token de administrador. O princípio do menor privilégio importa mesmo em uma rede doméstica:

influx auth create --org home --read-buckets --write-buckets \
  --description "telegraf writer"

Copie o token da saída. Você vai colocá-lo na configuração do Telegraf a seguir.

Configure o Telegraf para assinar o MQTT

O Telegraf vem com um arquivo de configuração de exemplo enorme. Substitua-o por um enxuto para ver exatamente o que ele faz. Use um client ID único e um prefixo de topic único; durante os testes, o servidor MQTT público em broker.connectmq.com funciona sem conta (apenas para testes, nunca para dados de produção).

sudo mv /etc/telegraf/telegraf.conf /etc/telegraf/telegraf.conf.sample
sudo nano /etc/telegraf/telegraf.conf

[agent]
  interval = "10s"
  flush_interval = "10s"
  omit_hostname = true

[[inputs.mqtt_consumer]]
  servers = ["tcp://broker.connectmq.com:1883"]
  client_id = "telegraf-pi-4b21c9"
  topics = ["connectmq/demo/4b21c9/+/climate"]
  qos = 1
  persistent_session = false
  data_format = "json_v2"

  [[inputs.mqtt_consumer.topic_parsing]]
    topic = "connectmq/demo/4b21c9/+/climate"
    tags = "_/_/_/room/_"

  [[inputs.mqtt_consumer.json_v2]]
    measurement_name = "climate"
    [[inputs.mqtt_consumer.json_v2.field]]
      path = "t"
      rename = "temperature"
      type = "float"
    [[inputs.mqtt_consumer.json_v2.field]]
      path = "rh"
      rename = "humidity"
      type = "float"

[[outputs.influxdb_v2]]
  urls = ["http://127.0.0.1:8086"]
  token = "PASTE_THE_TELEGRAF_TOKEN_HERE"
  organization = "home"
  bucket = "sensors"

O bloco topic_parsing transforma o quarto nível do topic em uma tag room, então uma mensagem em connectmq/demo/4b21c9/kitchen/climate vira um ponto com a tag room=kitchen. As tags são indexadas no InfluxDB, o que deixa as consultas por ambiente rápidas. Para mais opções de parser, veja o guia do Telegraf MQTT consumer.

Inicie o serviço e acompanhe o log. O Telegraf imprime ali os erros de conexão e de parsing, o que é muito mais fácil do que adivinhar:

sudo systemctl enable --now telegraf
sudo journalctl -u telegraf -f

Publique uma leitura de teste a partir de qualquer máquina:

mosquitto_pub -h broker.connectmq.com -p 1883 -i tester-4b21c9 -q 1 \
  -t connectmq/demo/4b21c9/kitchen/climate \
  -m '{"t":21.7,"rh":48.2}'

Depois consulte o InfluxDB diretamente para confirmar que o ponto chegou:

influx query --org home \
  'from(bucket:"sensors") |> range(start:-10m) |> filter(fn:(r) => r._measurement == "climate")'

Se aparecerem linhas com room=kitchen, a metade de ingestão está pronta.

Instale o Grafana no Raspberry Pi

O Grafana publica seu próprio repositório arm64:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://apt.grafana.com/gpg.key \
  | sudo gpg --dearmor -o /etc/apt/keyrings/grafana.gpg
echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" \
  | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt update
sudo apt install -y grafana
sudo systemctl enable --now grafana-server

Abra http://<pi-ip>:3000, entre com admin / admin e defina uma nova senha quando solicitado.

Conecte o Grafana ao InfluxDB

No Grafana, vá em Connections, Data sources, Add data source, InfluxDB e então:

1. Defina Query language como Flux.
2. URL: http://localhost:8086.
3. Em InfluxDB Details, defina Organization como home, cole um token (crie um somente leitura com influx auth create --org home --read-buckets, seguindo o menor privilégio) e defina Default Bucket como sensors.
4. Clique em Save and test. Você deve ver a contagem de buckets informada.

Monte um dashboard Raspberry Pi com Grafana e InfluxDB

Crie um novo dashboard, adicione um painel Time series e cole esta consulta Flux:

from(bucket: "sensors")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r._measurement == "climate" and r._field == "temperature")
  |> aggregateWindow(every: v.windowPeriod, fn: mean, createEmpty: false)
  |> yield(name: "temperature")

O Grafana desenha automaticamente uma linha por ambiente porque room é uma tag. Algumas escolhas de dashboard que fazem diferença real em um Pi:

• Use aggregateWindow. Sem ele, um intervalo de 30 dias puxa todos os pontos brutos e o Pi sofre. Com ele, o Grafana pede apenas a quantidade de pontos que o painel consegue exibir.
• Defina a atualização do dashboard em 30 segundos ou mais. Atualizações mais rápidas basicamente gastam CPU do Pi com dados que mudam devagar.
• Adicione um painel Stat com last() em vez de mean para a temperatura atual de cada ambiente.
• Use os alertas do Grafana com moderação. Eles são avaliados no Pi, então mantenha um intervalo de avaliação razoável.

Se preferir dispensar o banco de dados e plotar valores MQTT ao vivo diretamente, o guia da fonte de dados MQTT do Grafana mostra essa abordagem. É mais simples, mas não guarda histórico.

Migrando o broker para credenciais privadas

O servidor público pode ser lido por qualquer pessoa, então sensores de produção devem publicar em um broker privado. Com o ConnectMQ, um broker MQTT na nuvem e broker MQTT gerenciado, você cria um broker no portal e recebe usuário, senha e client ID. Altere três coisas no telegraf.conf:

[[inputs.mqtt_consumer]]
  servers = ["ssl://broker.connectmq.com:8883"]
  client_id = "YOUR_CLIENT_ID"
  username = "YOUR_USERNAME"
  password = "YOUR_PASSWORD"
  topics = ["home/+/climate"]
  qos = 1
  data_format = "json_v2"

O ConnectMQ usa um certificado Let's Encrypt, então o pacote de CAs do sistema do Pi o valida e nenhuma linha tls_ca é necessária. Lembre-se de que os client IDs ficam vinculados às credenciais emitidas: o Telegraf e cada sensor precisam do seu próprio client ID. Atualize o topic_parsing para refletir o novo formato de topic.

Surge assim uma divisão clara de responsabilidades: o ConnectMQ cuida da conectividade, da autenticação e do roteamento de todos os dispositivos, enquanto o Pi cuida do armazenamento e da visualização dos dados que você quer guardar. O ConnectMQ não armazena histórico de mensagens além das retained messages, então o InfluxDB é o lugar certo para os dados de longo prazo.

Mantendo a stack saudável

Faça backup periódico tanto do InfluxDB (influx backup /path/to/backup) quanto de /var/lib/grafana/grafana.db. Perder um dashboard que você levou uma noite inteira ajustando é mais irritante do que perder uma semana de dados de temperatura.

Comece com o ConnectMQ

Aponte seus sensores e o Telegraf para um broker privado em minutos: cadastre-se em app.connectmq.com, escolha o plano Serverless gratuito (sem cartão de crédito) e copie as credenciais geradas. Para a série completa sobre o Pi, comece pelo tutorial MQTT com Raspberry Pi e, se preferir contêineres, veja o guia do IOTstack no Raspberry Pi.

Perguntas frequentes

O InfluxDB consegue assinar o MQTT diretamente?

Não sozinho, no InfluxDB 2 OSS. O input mqtt_consumer do Telegraf é a ponte padrão e roda tranquilamente no mesmo Pi, com pouco consumo de memória.

Isso funciona no Raspberry Pi OS 32 bits?

O InfluxDB 2 exige um sistema 64 bits, então use a imagem arm64. O Grafana e o Telegraf têm versões 32 bits, mas o banco de dados é a peça limitante.

Quantos dados um Raspberry Pi consegue armazenar no InfluxDB?

Depende de quantas séries existem e com que frequência reportam, além do seu disco. Alguns sensores a cada dez segundos são uma carga leve; use um SSD e uma política de retenção para que o crescimento fique sob controle.

O Grafana consegue ler MQTT sem o InfluxDB?

Sim, com o plugin de fonte de dados MQTT ele mostra valores ao vivo, mas você perde histórico e agregação. Use o InfluxDB quando precisar de tendências ao longo de dias ou meses.