Knowledge Base
Voltar ao Dashboard

Kezpo Tag — Base de Conhecimento

Documentacao tecnica, troubleshooting e FAQ do sistema de rastreamento BLE

Nenhum resultado encontrado

Tente buscar com outras palavras-chave

Como Funciona o Sistema
Q
Como funciona o rastreamento via Apple FindMy?

As tags BLE transmitem uma chave publica via Bluetooth Low Energy. Quando um iPhone (ou iPad/Mac) passa proximo, ele:

  1. Capta o sinal BLE da tag
  2. Encripta sua localizacao GPS com a chave publica da tag
  3. Envia o blob encriptado anonimamente para os servidores da Apple
  4. Quando consultamos via proxy, baixamos o blob e decriptamos com a chave privada correspondente, obtendo lat/lng/precisao
O iPhone nao sabe de quem e a tag — o processo e totalmente anonimo. A Apple tambem nao consegue ver a localizacao (ela esta encriptada com nossa chave).
Q
O que e o findmy-proxy?

E um servidor Node.js que roda no Mac Mini. Ele:

  • Mantem o banco de chaves (serial -> chave publica + privada)
  • Consulta os servidores Apple via macless-haystack
  • Decripta os relatorios de localizacao
  • Armazena em cache as posicoes
  • Expoe uma API REST para o dashboard e apps consumirem
Q
O que e o macless-haystack?

E um container Docker que simula um dispositivo Apple para consultar os servidores FindMy sem precisar de um Mac real com iCloud. Ele usa o container anisette para gerar tokens de autenticacao Apple.

Q
Qual e a estrutura do advertisement BLE?

O payload tem 31 bytes:

  • Bytes 0-1: Tipo (Manufacturer Specific Data)
  • Bytes 2-3: Company ID (Apple = 0x4C00)
  • Bytes 4-5: Tipo Offline Finding + comprimento
  • Byte 6: Status byte (bateria + flags)
  • Bytes 7-28: 22 bytes da chave publica
  • Byte 29: 2 bits superiores da chave
  • Byte 30: Hint byte
O endereco MAC BLE e derivado dos primeiros 6 bytes da chave publica.
Q
O que e o Status Byte (byte 6)?

E um byte de 8 bits que acompanha o payload:

  • Bits 7-6: Nivel de bateria (00=full, 01=medium, 10=low, 11=critical)
  • Bit 5: Flag de suporte a bateria (1=tag reporta bateria)
  • Bits 4-0: Counter/reservados (potencialmente utilizaveis para dados customizados)

Este byte e encriptado junto com a localizacao e retorna quando decriptamos o relatorio. Estamos testando quais bits passam de forma confiavel pela rede Apple.

Q
De onde vem a precisao (accuracy) da posicao?

A precisao depende de:

  • Qualidade do GPS do iPhone que captou o sinal
  • Numero de relatorios (mais reports = melhor triangulacao)
  • Ambiente (indoor vs outdoor)

Valores tipicos:

  • 10-50m outdoor
  • 50-200m indoor
  • >500m = impreciso
Problemas Comuns e Diagnostico
Q
Tag nunca posicionou — o que fazer?

Verificar em ordem:

  1. Bateria: A tag esta ligada? LED piscou ao inserir bateria?
  2. Chave: A chave da tag foi registrada no proxy? Consulte via API: /v1/tags/SERIAL/positions/latest — se retornar "Tag not found", a chave nao esta no sistema
  3. Firmware: O firmware foi gravado corretamente? Se usou o template sem patch de chave, a tag transmite uma chave placeholder invalida
  4. Ambiente: A tag esta num local com trafego de iPhones? Locais isolados (galpao industrial, zona rural) podem nao ter dispositivos Apple por perto
  5. Tempo: Apos ligar a tag, pode levar 15-60 minutos para o primeiro report aparecer, dependendo do trafego de iPhones
Q
Tag posicionou uma vez e depois parou — o que aconteceu?

As causas mais provaveis:

  1. Sem watchdog no firmware: Se a tag sofreu um brownout (queda momentanea de tensao na bateria), o processador pode ter travado permanentemente. Sem watchdog timer, nao ha como reiniciar automaticamente.
  2. Contato de bateria: Vibracao durante transporte pode ter afrouxado o contato da bateria. Verificar fisicamente.
  3. Bateria esgotada: Para baterias finas (coin cell), a capacidade pode ser menor que o esperado.
Nota: Isso NAO e causado pela Apple bloqueando a tag. O sistema e anonimo e passivo — a Apple nao pode identificar nem bloquear tags individuais.
Q
Muitas tags numa caixa — isso causa problemas?

Sim, por congestionamento RF:

  • 1000 tags transmitindo a cada 5s nos mesmos 3 canais BLE (37, 38, 39) causam colisoes
  • Um iPhone proximo nao consegue captar todos os pacotes
  • Resultado: nem todas as tags sao reportadas a cada ciclo

Solucao: Aumentar intervalo de advertising ou separar tags em caixas menores.

Importante: NAO e bloqueio da Apple — e limitacao fisica do espectro de radio.
Q
A Apple pode bloquear, ignorar ou pausar nossas tags?

Nao.

  • O sistema e totalmente anonimo — o iPhone nao sabe de quem e a tag
  • Tags OpenHaystack nao sao AirTags — nao ativam alertas anti-stalking
  • A Apple nao pode "banir" uma chave publica
  • Nao existe throttling, blacklist ou pause no lado da Apple
Se a tag para de ser reportada, o problema e sempre local (bateria, firmware, ambiente).
Q
Qual a diferenca entre posicao "stale" (>7 dias) e tag morta?
  • Stale: A tag pode estar funcionando mas em local sem iPhones (galpao, zona rural). Ultima posicao conhecida e mantida.
  • Morta: A tag parou de transmitir (firmware travou, bateria morreu). Tambem mostra posicao stale.
Para diferenciar: se outras tags no mesmo local estao atualizando, a tag stale provavelmente esta morta.
Q
Tag mostra posicao errada / muito imprecisa — por que?

Possiveis causas:

  • iPhone com GPS ruim: O iPhone que captou estava indoor ou com GPS degradado
  • Poucos relatorios: Com apenas 1-2 reports, nao ha triangulacao
  • Outliers: Um relatorio muito impreciso pode puxar a media. O proxy aplica filtros de outlier, mas nem sempre e suficiente

Use a funcao "Ver Raw" no mapa para comparar os pontos brutos vs o centroid filtrado.

Q
Por que ~8-10% das tags falham apos transporte?

Analise empirica do nosso sistema mostrou:

  • Taxa real de falha: ~3-5% (tags que pararam de transmitir completamente)
  • Causa principal: brownout + ausencia de watchdog timer no firmware
  • O contato da bateria oscila com vibracao do transporte, causando queda momentanea de tensao, o processador trava e sem watchdog = tag morta

Fix planejado: Adicionar watchdog timer no firmware (reinicia automaticamente apos crash).

Firmware e Hardware
Q
Qual hardware as tags usam?
  • Processador: nRF52810 (Nordic Semiconductor)
  • BLE: Integrado no nRF52
  • Bateria: Coin cell / flat lithium primary
  • Flash: 192KB, RAM: 24KB
  • SoftDevice: s112 (BLE stack da Nordic)
Q
Quais sao os parametros do firmware atual?
  • Intervalo de advertising: 5 segundos
  • TX Power: +4 dBm (maximo do nRF52810)
  • DCDC converter: Habilitado (melhor eficiencia energetica)
  • Chaves: 1 por tag (sem rotacao)
  • Watchdog: NAO implementado (bug conhecido)
  • Leitura de bateria: NAO implementada no nRF52 (sempre retorna 100%)
Q
Quais bugs foram identificados no firmware?
  1. Memory leak (CRITICO para tags com key rotation): malloc() sem free() a cada rotacao de chave. Com 1 chave apenas (producao atual), nao e problema.
  2. Sem watchdog timer (CRITICO): Qualquer crash = tag morta permanentemente
  3. APP_TIMER_INIT duplo: Timer de rotacao pode ser invalidado
  4. Battery nao lida no nRF52: Sempre reporta 100% — o ADC do nRF52 nunca e usado
  5. printf em embedded: Codigo de debug que consome RAM sem UART
Q
O que e o DCDC converter e por que importa?

O nRF52810 tem um conversor DC-DC interno que e mais eficiente que o regulador LDO padrao. Com DCDC habilitado, o consumo em modo ativo cai ~20-30%, estendendo a vida da bateria. Nosso firmware de producao ja usa DCDC.

Operacoes e Manutencao
Q
Como atualizar o cache de posicoes?

O cache do proxy atualiza automaticamente a cada 10 minutos. Para forcar:

  • No mapa: clique "Atualizar Cache"
  • Via API: POST /v1/cache/refresh
O refresh consulta TODAS as tags no macless-haystack e pode levar 5-15 minutos para lotes grandes.
Q
Como adicionar um novo lote de tags ao sistema?
  1. Gerar chaves e firmware: usar o tag-firmware-generator
  2. Flash nas tags via programmer
  3. Importar chaves no proxy (adicionar ao lotes_1502_full_keys.json)
  4. Reiniciar o findmy-proxy: pkill + nohup node findmy-proxy.js
  5. Atualizar client-serials.json com o novo lote/cliente
Q
Como consultar uma tag via API?
  • Posicao mais recente: GET /v1/tags/{serial}/positions/latest
  • Historico: GET /v1/tags/{serial}/history
  • Comparacao raw: GET /v1/tags/{serial}/positions/compare
  • API externa (com autenticacao): GET http://host:3005/api/tag/{serial} (header X-API-Key)
Q
O que sao os containers Docker e para que servem?
  • anisette: Gera tokens de autenticacao Apple (necessario para consultar FindMy)
  • macless-haystack: Consulta os servidores Apple FindMy
  • kezpo-web: Dashboard web (Node.js/Express)
  • kezpo-nginx: Reverse proxy com SSL
O findmy-proxy roda nativo (fora do Docker) na porta 3001.
Dados e Status Byte (Experimental)
Q
E possivel transmitir dados customizados pela rede Apple?

Estamos testando. O Status Byte (byte 6 do advertisement) tem 5 bits potencialmente utilizaveis (bits 4-0). Se passarem pela rede Apple sem modificacao, podemos encodar:

  • Nivel de bateria real (lido pelo ADC do nRF52)
  • Temperatura (com sensor externo)
  • Estado de sensor (porta aberta/fechada)
  • Contador de eventos

Os testes estao em andamento — acessar /test-bits.html para acompanhar.

Q
O que e Key Rotation e serve para transmitir dados?

Key rotation e trocar a chave publica que a tag transmite periodicamente. Em teoria, pode-se encodar dados escolhendo QUAL chave transmitir (ex: chave 3 = temperatura 10-15C).

Para tags em transito com poucos iPhones ao redor, isso nao e pratico — fragmenta os relatorios entre multiplas chaves, reduzindo a chance de cada uma ser captada. O Status Byte e melhor para nosso cenario.
Q
Quantos bits de dados conseguimos enviar por relatorio?

Depende do resultado dos testes:

  • Status byte (bits 4-0): ate 5 bits garantidos + 2 bits de bateria
  • Se todos os 8 bits passarem: 256 combinacoes por relatorio
  • Combinado com chave + posicao GPS: cada report carrega localizacao + timestamp + ate 8 bits de telemetria
Kezpo Solutions — Sistema de Rastreamento BLE — Base de Conhecimento v1.0