OwnTracks com seu próprio broker MQTT: configuração, TLS e ACLs

O OwnTracks é um app de localização de código aberto para Android e iOS que pode publicar a posição do seu celular diretamente em um broker MQTT. Com seu próprio broker, você decide quem vê os dados, por quanto tempo eles ficam armazenados e quais outros sistemas (Home Assistant, Node-RED, um banco de dados) os consomem. A configuração exige quatro valores no app (host, porta, usuário, senha), além de TLS e uma ACL no broker.

Este guia cobre as configurações do app, os topics e payloads que o OwnTracks usa, ACLs do broker para compartilhar com amigos, o OwnTracks Recorder e como verificar cada etapa pelo terminal.

O que você precisa

Um broker público de testes serve para verificar se o app conecta, mas não deixe um fluxo de localização real em um endpoint compartilhado: qualquer pessoa que assinar owntracks/# ali veria tudo.

Configure o app

No app, abra Preferences → Connection (Android) ou Settings (iOS) e mude o modo de HTTP para MQTT. Os nomes dos campos variam um pouco entre plataformas e versões, mas os valores são os mesmos:

Salve e puxe o mapa para baixo ou toque no botão de upload para publicar uma localização manualmente. A tela de status deve mostrar a conexão como conectada. Se não tiver certeza de que o broker aceita as credenciais, teste-as antes no notebook com o cliente MQTT online: isso separa problemas do broker de problemas do app.

Topics e payloads

Com o usuário alice e o device ID pixel, o app usa:

owntracks/alice/pixel          location messages (_type: location), retained by default
owntracks/alice/pixel/event    region enter/leave events (_type: transition)
owntracks/alice/pixel/info     card with name and avatar (_type: card)
owntracks/alice/pixel/cmd      commands TO the phone (_type: cmd)

Uma mensagem de localização é assim (campos abreviados; os campos exatos dependem da plataforma e da versão):

{
  "_type": "location",
  "tid": "AL",
  "lat": 48.856613,
  "lon": 2.352222,
  "acc": 12,
  "alt": 35,
  "batt": 78,
  "conn": "m",
  "t": "u",
  "tst": 1792236000
}

tst é o horário UTC da posição, acc a precisão em metros, batt o nível de bateria, conn o tipo de conexão (w Wi-Fi, m móvel) e t o gatilho (u usuário, p ping, c região, entre outros). O app também registra uma mensagem Last Will (_type: lwt) no topic base, para que um assinante saiba quando o celular se desconecta de forma abrupta.

O modo de monitoramento controla com que frequência o celular reporta: Significant (o padrão, econômico em bateria, baseado em mudanças significativas de localização), Move (atualizações frequentes em movimento, gasta mais bateria), Manual e Quiet. Comece com Significant.

Se você construir seu próprio rastreador de hardware, publique o mesmo JSON na mesma estrutura de topics e ele aparecerá ao lado dos celulares. O tutorial de rastreador GPS constrói um com ESP32.

Verifique pelo terminal

Assine com as credenciais de um usuário que possa ler os topics da Alice:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'owntracks/#' -v

Toque em publish no app; o JSON aparece em um ou dois segundos. Para testar o sentido inverso, peça uma localização ao celular com um comando remoto. Comandos remotos precisam estar ativados nas configurações avançadas do app, e no iOS a entrega em segundo plano não é garantida:

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'owntracks/alice/pixel/cmd' -q 1 \
  -m '{"_type":"cmd","action":"reportLocation"}'

Você também pode se passar por um celular para testar o Recorder ou um dashboard sem sair andando por aí:

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'owntracks/alice/pixel' -q 1 -r \
  -m "{\"_type\":\"location\",\"tid\":\"AL\",\"lat\":48.8584,\"lon\":2.2945,\"acc\":10,\"tst\":$(date +%s)}"

ACLs: quem vê quem

O app assina owntracks/+/+ por padrão e desenha como amigo cada localização recebida. Isso faz da ACL do broker o controle de privacidade: um usuário vê exatamente os topics que tem permissão de ler. Na sintaxe do Mosquitto:

# every user may publish and read under its own username
pattern readwrite owntracks/%u/#

# alice and bob share locations with each other
user alice
topic read owntracks/bob/#

user bob
topic read owntracks/alice/#

# the recorder reads everyone, publishes nothing
user recorder
topic read owntracks/#

Em um broker gerenciado, você expressa as mesmas regras como permissões por topic para cada usuário. Dois detalhes para lembrar:

• O usuário no app precisa coincidir com o segundo nível do topic; caso contrário, toda publicação é negada. Muitos brokers descartam uma publicação negada sem desconectar o cliente, então o celular parece conectado, mas nada chega. Veja ACL negada silenciosamente.
• Teste as regras de fora: entre como Bob e tente ler alguém que não compartilhou com ele. Há um script curto para isso em testar permissões ACL do MQTT.

Guarde o histórico com o Recorder

O OwnTracks Recorder assina o broker, grava cada localização em disco e serve um mapa web e uma API HTTP. A imagem Docker é configurada por variáveis de ambiente:

docker run -d --name ot-recorder -p 8083:8083 \
  -e OTR_HOST=broker.connectmq.com \
  -e OTR_PORT=8883 \
  -e OTR_USER=recorder \
  -e OTR_PASS="$MQTT_PASS" \
  -e OTR_CAFILE=/etc/ssl/certs/ca-certificates.crt \
  -v ot-store:/store \
  owntracks/recorder

Abra http://localhost:8083 para a interface web do próprio Recorder. Dê ao Recorder um usuário próprio somente leitura, como na ACL acima, e defina por quanto tempo você mantém o histórico. A porta 8083 aqui é a porta HTTP do Recorder na sua máquina, sem relação com a porta WebSocket do broker.

Criptografia ponta a ponta (opcional)

O OwnTracks pode criptografar os payloads com uma chave secreta compartilhada (libsodium). O broker passa a ver apenas {"_type":"encrypted","data":"…"} e todo leitor, inclusive o Recorder, precisa da chave. Isso protege os dados do operador do broker, mas você perde a capacidade de inspecionar mensagens com as ferramentas comuns. TLS com ACLs rígidas basta para a maioria das instalações; veja criptografia de payload MQTT para os prós e contras.

Solução de problemas

OwnTracks no seu próprio broker é uma das implantações MQTT úteis mais simples: um celular, um topic por dispositivo e algumas regras de ACL. Acerte primeiro o TLS e as permissões por usuário, verifique cada sentido com mosquitto_sub e mosquitto_pub e só depois adicione o Recorder ou integrações de automação residencial.

Perguntas frequentes