PetTracker — documentação técnica visual

#1. Visão Geral

PetTracker é um sistema de rastreamento e monitoramento de cães baseado em coleiras inteligentes equipadas com GPS, rádio LoRa de longo alcance, sensores ambientais e atuadores remotos.

A inovação principal está na rede mesh colaborativa entre coleiras: dispositivos de diferentes proprietários trocam pacotes de rádio entre si de forma anônima e criptografada, ampliando dramaticamente a área de cobertura sem depender de infraestrutura celular ou Wi-Fi. Os dados chegam ao dono através de um receptor portátil que faz ponte com o aplicativo Android.

#Diferenciais

• Sem dependência de operadora móvel — não requer chip 4G na coleira
• Cobertura colaborativa anônima — inspirada no conceito Find My / AirTag
• Privacidade ponta a ponta — criptografia entre coleira e app do dono
• Autonomia estendida — meta de 15-30 dias com bateria 18650
• Bidirecional — dono pode acionar lanterna, buzzer e vibrador remotamente
• Multi-pet — uma conta gerencia múltiplos cães

#2. Arquitetura do Sistema

#2.1 Visão de alto nível

[Coleira A] ─┐                                    ┌──► Push Notifications
[Coleira B] ─┤                                    │
[Coleira C] ─┼─► LoRa Mesh ──► [Receptor] ──BT──► [App Android] ──HTTPS──► [Nuvem]
[Coleira X] ─┤  (anônima e                                                    │
[Coleira Y] ─┘   criptografada)                                               ▼
                                                                       [Outros devices
                                                                        da mesma conta]

#2.2 Princípios arquiteturais

#2.3 Decisão arquitetural fundamental

O receptor não se comunica diretamente com a nuvem. A nuvem é alcançada exclusivamente através do app Android. Justificativas:

• Receptor mais simples e barato (sem Wi-Fi/4G obrigatórios)
• Segurança simplificada (tokens ficam no app)
• App é único ponto de gerenciamento e configuração
• Receptor preserva bateria sem rádios adicionais

#3. Atores

#4. Componentes Físicos

#4.1 Coleira

Dispositivo embarcado preso ao cão, autônomo, resistente a água, baixo consumo.

#Hardware

#4.2 Receptor portátil

Dispositivo handheld que o dono carrega consigo.

#Hardware

#4.3 App Android

Aplicativo nativo (Kotlin) ou Flutter, instalado no celular do dono.

#Requisitos mínimos

• Android 8.0 (API 26) ou superior
• Bluetooth Classic e BLE
• Permissões de localização (para BLE scan em Android 12+)
• Mínimo 100 MB de armazenamento livre

#4.4 Backend / Nuvem (futuro)

• API REST hospedada em VPS
• MQTT broker para ingestão
• MySQL/PostgreSQL com PostGIS
• Firebase Cloud Messaging para push

#5. Fluxo de Dados

#5.1 Caminho de um pacote de telemetria

1. Coleira lê sensores (GPS, AHT20, IMU, bateria)
2. Monta payload estruturado
3. Cifra com chave do dono
4. Adiciona header de rede (ID rotativo, seq, TTL, hops)
5. Transmite via LoRa
   │
   ├─► (opcional) Coleira vizinha relayar anonimamente
   │
6. Receptor escuta canal LoRa
7. Filtra: aceita apenas pacotes cuja descriptografia funciona com sua chave
8. Encaminha via Bluetooth para o app
   │
9. App recebe, atualiza UI em tempo real
10. App salva em SQLite local
11. App avalia regras (geofence, alertas)
12. App dispara notificações locais se aplicável
   │
13. (Quando há internet) App envia lote para nuvem via HTTPS
14. Nuvem persiste em banco
15. Nuvem dispara push para outros dispositivos da conta

#5.2 Estratégia de buffer

A sincronização sempre flui no sentido inferior → superior, com ACKs explícitos. Dados confirmados podem ser purgados localmente.

#5.3 Caminho de um comando do dono

1. Dono toca "Acionar Bipe" no app
2. App envia comando via Bluetooth ao receptor
3. Receptor encapsula em pacote LoRa (cifrado)
4. Receptor transmite via LoRa
   │
   ├─► (eventualmente) Coleiras vizinhas relayar
   │
5. Coleira do dono recebe, valida MAC
6. Coleira executa (aciona buzzer por X segundos)
7. Coleira responde com ACK + estado atual
8. ACK volta pelo mesmo caminho até o app
9. App exibe confirmação "Bipe acionado ✓"

#6. Funcionalidades da Coleira

#6.1 Aquisição de localização

• Leitura contínua de GPS quando ativo: lat, lon, altitude, velocidade, rumo
• Indicadores de qualidade do fix (válido/inválido, satélites, HDOP)
• Estados de energia do GPS: ligado, sleep, desligado
• Hot-start preservando efemérides via VBACKUP (fix em <2s)

#6.2 Telemetria ambiental

• Temperatura ambiente externa (AHT20)
• Umidade relativa do ar
• Temperatura interna do MCU (saúde térmica do dispositivo)
• Detecção de condições críticas (calor extremo no animal)

#6.3 Detecção de movimento e atividade

• Acelerômetro detecta movimento
• Classificação de estados: parado, andando, correndo, possível queda
• Wake-on-motion: GPS só liga com movimento detectado
• Estatísticas de tempo em atividade vs. tempo parado

#6.4 Gerenciamento de energia

• Monitoramento de tensão e percentual da bateria
• Detecção de status de carregamento
• Modos adaptativos: normal, economia, crítico
• Deep sleep entre transmissões
• Estimativa de autonomia restante

#6.5 Comunicação por rádio

• Transmissão periódica de telemetria via LoRa
• Participação em mesh: retransmissão de pacotes vizinhos
• Identificação rotativa (rolling ID) a cada 15 min
• Criptografia AES-256 com chave do dono
• Adaptação de potência conforme distância

#6.6 Recepção de comandos

#6.7 Modo perdido (Lost Mode)

Ativado pelo dono quando o cão escapa.

• Aumenta frequência de transmissão GPS (1-5s vs. 60s normal)
• Aumenta potência LoRa para máxima
• Ativa beacon BLE secundário (qualquer celular próximo detecta)
• Buzzer/LED escalonam conforme proximidade do dono
• Maior consumo de bateria — uso temporário

#6.8 Persistência local

• Buffer FIFO em flash com últimas N posições
• Salva quando não há cobertura mesh
• Sincroniza automaticamente ao recuperar enlace
• Marca pacotes com flag cached para distinguir tempo real

#7. Rede Mesh Colaborativa

#7.1 Conceito

Inspirada no Apple Find My, mas usando LoRa em vez de BLE. Coleiras de qualquer dono participam da rede como relays anônimos.

#7.2 Roteamento

• TTL inicial de 3-5 hops
• Detecção de duplicatas via cache de IDs recentes
• Coleiras vizinhas reenviam sem conseguir ler o conteúdo
• Receptores também atuam como sumidouros mesh

#7.3 Privacidade

• Rolling ID: identificador da coleira muda a cada 15 minutos via HMAC-SHA256
• Payload cifrado: somente o dono recupera os dados
• Sem metadata sensível: relay nunca sabe origem nem destino real
• Opt-in da comunidade: usuários podem habilitar contribuição como super-relays

#7.4 Métricas de rede expostas na telemetria

• RSSI e SNR de vizinhos
• Número de hops do pacote
• Quantidade de pacotes retransmitidos como relay
• Topologia local dinâmica

#8. Funcionalidades do Receptor Portátil

#8.1 Recepção de telemetria

• Escuta contínua da rede LoRa
• Filtragem: aceita apenas pacotes do(s) cão(es) do dono
• Repassa pacotes de outros donos sem decodificar (relay anônimo opcional)

#8.2 Posicionamento próprio

• GPS local indica onde o dono está
• Cálculo de distância e rumo até cada cão
• Indicador "quente/frio" via RSSI quando GPS sem fix

#8.3 Interface visual

• Display TFT colorido com múltiplas telas:
  • Status geral
  • Detalhe por cão
  • Mapa rudimentar com setas direcionais
  • Configurações
• Indicadores: fix GPS, bateria, BLE conectado, sinal de cada coleira

#8.4 Acionamento direto

• 3 botões físicos: bipe, lanterna, vibrar
• Atalho de pressão longa para modo perdido emergencial
• Não requer celular conectado

#8.5 Ponte Bluetooth

• Pareamento BLE ou Classic com app
• Encaminhamento contínuo de telemetria
• Recebe comandos do app, transmite via LoRa
• Reconexão automática

#8.6 Buffer offline

• Armazena telemetria recebida quando app desconectado
• Política FIFO
• Sincroniza ao reconectar
• Indicador de pacotes pendentes

#8.7 Bridge transparente

• Receptor não interpreta payload — apenas valida, descriptografa e repassa
• Comandos do app trafegam transparentes para a coleira
• Versionamento de protocolo independente

#9. Funcionalidades do App Android

#9.1 Conta e cadastro

• Cadastro do dono (email/telefone)
• Cadastro de cães (nome, raça, foto, peso, observações médicas)
• Pareamento de coleiras à conta
• Compartilhamento da coleira com familiares

#9.2 Visualização em tempo real

• Mapa interativo com posição atual de cada cão
• Indicadores: bateria, temperatura, movimento, sinal, último update
• Trilha das últimas X horas
• Distância dono ↔ cão

#9.3 Histórico

• Mapa de calor das áreas mais visitadas
• Trilhas por dia/semana/mês
• Estatísticas de atividade (tempo em movimento, distância)
• Gráficos de temperatura e bateria ao longo do tempo

#9.4 Geofencing

• Criação de áreas seguras/proibidas no mapa
• Alertas de entrada/saída
• Múltiplas geofences simultâneas
• Geofences por cão ou compartilhadas

#9.5 Sistema de alertas

#9.6 Acionamento de atuadores

• Botões grandes: lanterna, buzzer, vibrador
• Confirmação de execução pela coleira
• Histórico de comandos enviados

#9.7 Modo busca

• Ativa modo perdido na coleira
• Tela dedicada com seta direcional, distância e RSSI
• Alerta sonoro/visual ao se aproximar
• Última posição conhecida em destaque

#9.8 Configurações da coleira

• Intervalo de transmissão (denso/normal/econômico)
• Sensibilidade do detector de movimento
• Sensibilidade do detector de queda
• Limiares de alerta personalizáveis
• OTA: atualização remota do firmware

#9.9 Multi-pet

• Múltiplos cães em uma conta
• Visualização simultânea no mapa
• Cores/ícones distintos por cão
• Telas dedicadas por animal

#9.10 Sincronização com nuvem

• Upload automático quando há internet
• Modo "somente Wi-Fi" opcional
• Indicador de última sincronização
• Reenvio automático em falhas

#9.11 Funcionamento offline

• App totalmente funcional sem internet
• Mapa em cache
• Fila de comandos pendentes
• Histórico local sempre disponível

#9.12 Serviço em background

• Foreground service para manter Bluetooth ativo
• Notificação persistente do status
• Wake locks gerenciados
• Reconexão automática ao receptor

#10. Backend / Nuvem (fase futura)

#10.1 Endpoints da API

#10.2 Persistência

• Banco relacional (MySQL/PostgreSQL)
• PostGIS para geofencing pesado
• Tabelas: usuários, cães, coleiras, telemetria, eventos, comandos, geofences

#10.3 Notificações push

• Firebase Cloud Messaging
• Alertas mesmo com app fechado
• Multi-device (vários celulares na mesma conta)

#10.4 Comunidade

• Heatmap anônimo de áreas com cães
• Sistema opt-in de busca colaborativa
• Bonificação para super-relays

#11. Casos de Uso

#11.1 Passeio rotineiro

Dono sai para passear → app mostra posição em tempo real, velocidade, tempo de passeio, distância de casa.

#11.2 Cão escapa do quintal

Geofence dispara → alerta no celular → dono ativa modo busca → receptor portátil indica direção via RSSI.

#11.3 Cão perdido em área desconhecida

Modo perdido ativado → outras coleiras retransmitem anonimamente → beacon BLE detectável por celulares próximos com o app.

#11.4 Monitoramento de saúde

Alertas de imobilidade prolongada → temperatura ambiental crítica → histórico de atividade decrescente indica problema.

#11.5 Treinamento

Vibrador como reforço positivo/negativo, sem dispositivo separado.

#11.6 Compartilhamento familiar

Múltiplos membros da família com o app instalado, todos veem a mesma coleira.

#11.7 Idoso esquecido em casa

Cão senil que se perde dentro da própria casa → buzzer ajuda a localizar pela acústica.

#12. Requisitos Não-Funcionais

#12.1 Autonomia

#12.2 Alcance

#12.3 Privacidade

• Criptografia AES-256 ponta a ponta
• Coleiras vizinhas nunca identificam outras coleiras
• Histórico preferencialmente local
• Nuvem opcional, com opt-in explícito

#12.4 Robustez

• IP67 (coleira)
• Operação de -10°C a +50°C
• Carga sem conector exposto (pogo pins magnéticos)
• Mecanismo de reset acessível externamente

#12.5 Escalabilidade

• Suporte a múltiplos relays simultâneos
• Mesh com TTL e deduplicação anti-tempestade
• Backend horizontalmente escalável

#12.6 Manutenibilidade

• OTA via receptor ou Wi-Fi
• Logs persistentes em flash
• Bootloader sempre acessível
• Versionamento de protocolo

#13. Stack Tecnológico

#13.1 Firmware (Coleira e Receptor)

• Linguagem: C++ / Arduino framework
• MCU: ESP32 / ESP32-S3
• RTOS: FreeRTOS (nativo no ESP-IDF)
• Bibliotecas principais:
  • RadioLib / Meshtastic — rádio LoRa
  • TinyGPSPlus — parser NMEA
  • Adafruit AHTX0 — sensor ambiental
  • ArduinoJson — serialização (protótipo)
  • NimBLE-Arduino / BluetoothSerial — Bluetooth
  • Adafruit GFX + ST7735 — display

#13.2 App Android

• Linguagem: Kotlin (nativo) ou Dart (Flutter)
• Mapa: Mapbox SDK ou Google Maps
• Persistência: Room (SQLite)
• Rede: Retrofit + OkHttp
• Bluetooth: Android Bluetooth API + nRF Connect lib
• Push: Firebase Cloud Messaging

#13.3 Backend

• Linguagem: PHP (Edy) ou Node.js
• Banco: MySQL com extensão espacial
• Broker MQTT: Mosquitto (futuro)
• Servidor: Nginx + PHP-FPM
• Auth: JWT
• CDN/Storage: S3-compatible para fotos dos cães

#14. Fases de Desenvolvimento

#Fase 1 — Bancada (atual)

• Validar leitura de sensores
• Definir payload de telemetria
• Comunicação Bluetooth coleira → celular
• Primeiras telas do app

#Fase 2 — Comunicação rádio

• nRF24L01 como rádio interino (prototipagem)
• Migração para SX1276 LoRa
• Protocolo coleira ↔ receptor
• ACK e retransmissão

#Fase 3 — Mesh básica

• Múltiplas coleiras em bancada
• TTL e deduplicação
• Beacons periódicos
• Entrega multi-hop

#Fase 4 — Energia e mecânica

• Bateria 18650 com proteção
• Deep sleep + wake-on-motion
• Encapsulamento IP67
• Carga magnética por pogo pins

#Fase 5 — App completo

• Mapa, geofences, alertas
• Histórico, multi-pet
• Modo busca
• Configuração da coleira

#Fase 6 — Nuvem e push

• Backend completo
• Notificações push
• Sincronização confiável
• Compartilhamento familiar

#Fase 7 — Comunidade e produção

• Heatmaps anônimos
• Busca colaborativa
• Migração de hardware para produção (ESP32-S3, MAX-M10S, PCB customizada)
• Certificações ANATEL

#15. Protocolo de Comunicação

#15.1 Estrutura do pacote LoRa

┌─────────────┬─────────────────────────────┬─────────┐
│   HEADER    │       PAYLOAD CIFRADO       │   MAC   │
│  (claro)    │       (AES-256-GCM)         │ (16 B)  │
└─────────────┴─────────────────────────────┴─────────┘

#Header (claro)

#Tipos de pacote (campo flags)

#15.2 Schema do payload de telemetria

{
  "id": "COLLAR-01",
  "fw": "0.1.0-dev",
  "seq": 42,
  "ts": 42127,
  "gps": {
    "valid": true,
    "lat": -16.686234,
    "lon": -49.264189,
    "alt": 749.3,
    "sat": 8,
    "hdop": 1.1,
    "age": 312
  },
  "mov": {
    "spd": 0.5,
    "crs": 127.3,
    "moving": false
  },
  "utc": "2026-05-14T17:42:08Z",
  "env": {
    "valid": true,
    "temp": 27.4,
    "hum": 62.1,
    "temp_mcu": 48.3
  },
  "pwr": {
    "vbat": 3.95,
    "pct": 78,
    "charging": false
  },
  "sys": {
    "mode": "normal",
    "uptime": 42,
    "rst": "POR"
  },
  "act": {
    "led": false,
    "buz": false,
    "vib": false
  },
  "net": {
    "rssi": -87,
    "snr": 9.2,
    "hops": 1,
    "relays": 0
  }
}

#15.3 Comandos

{
  "cmd": "BUZ_ON",
  "params": {
    "duration_s": 5,
    "pattern": "pulse"
  },
  "req_id": "abc123",
  "ts": 1715708528
}

#15.4 Versionamento

• Campo proto_ver no header indica versão da estrutura
• Mudanças minor são compatíveis para trás (campos opcionais)
• Mudanças major exigem atualização de coleira + receptor + app
• Receptor pode operar com coleiras de versões diferentes simultaneamente

#15.5 Migração futura JSON → CBOR

• Mesmo schema de campos
• Mudança transparente para o app (continua recebendo JSON do receptor)
• Receptor faz a conversão CBOR → JSON ao repassar
• Reduz payload LoRa em ~40%

#16. Glossário