Adicionar dispositivos push e pull

O ProbeHarbor aceita leituras de duas formas: seu hardware envia (push) JSON para uma URL de ingestão, ou nós buscamos (pull) JSON via HTTPS de um feed público em intervalos programados. As duas são configuradas em Dashboard → Devices. Nós ESP ou a bateria novos devem usar push. Pull é para servidores na rede local sempre ligados ou relays que já expõem JSON via HTTPS.

Uma conta gratuita (sem cartão de crédito) vincula sua chave de ingestão à sua casa, para que o histórico e os alertas continuem privados. Se quiser ver leituras sem se cadastrar, dê uma olhada antes na demo ao vivo.

Escolha push ou pull

Dispositivo push (recomendado)

1. Entre na sua conta e abra Devices.
2. Em Push devices, clique em Create push device (o nome padrão é Workshop probe; dá para renomear quando quiser).
3. No aviso de ingestão: escaneie o QR ou use Download Arduino .ino / MicroPython .py / CircuitPython code.py / Zephyr main.c / CH32V main.c / AVR main.S / Teensy 4.1 .ino / PIC18 main.c / Particle Boron .ino / ESPHome snippet (URL ou caminho de ingestão já preenchido). A chave fica na página por 30 minutos e sobrevive a uma atualização até você fechá-la.
4. Perdeu a chave depois? No cartão do dispositivo, use Reveal ingest key (quando a recuperação de chaves estiver ativada no servidor) ou Rotate key para gerar uma nova. Dispositivos criados antes de a recuperação de chaves ser ativada precisam de uma rotação para guardar uma cópia criptografada recuperável.
5. Grave um ESP32 (veja as opções de gravação: Arduino IDE, PlatformIO, MicroPython ou o esptool web da Espressif), uma Pico W (CircuitPython / MicroPython / Arduino-Pico), uma STM32 Nucleo (Zephyr C + Ethernet), um CH32V307 (WCHNET C + Ethernet), um Uno em assembly GNU AVR (ATmega328P + W5100), uma Teensy 4.1 (QNEthernet), um PIC18F67J60 (MLA TCP/IP) ou uma Particle Boron (webhook LTE). Precisa das peças antes? Lista de materiais do kit de congelamento ESP32, Pico W, STM32 Zephyr, CH32V RISC-V, assembly AVR, Teensy 4.1, PIC18 Ethernet ou celular (DS18B20 à prova d’água). O monitor serial a 115200 deve mostrar POST 200 (ou publish ok na Boron). As chaves dos sensores são importadas automaticamente (chaves planas, objeto temp, SenML ou Home Assistant REST). Depois, renomeie os sensores na página Devices. O mapeamento manual em Advanced é opcional, para mapear as chaves antecipadamente.
6. Mais exemplos (Uno Ethernet + DHT22, MAX31855, MAX6675 etc.): sketches/. O W5100 não faz TLS: envie um POST HTTP para um relay na rede local (feeds em Python / push_https_forward.py).
7. Faça um teste rápido com curl e abra Live com a conta conectada. Depois de uns 30 minutos sem envios, o Live avisa que uma sonda pode estar off-line.

Exemplo com curl (push)

Pegue um corpo de exemplo ao vivo no feed de ingestão de exemplo (baseado no clima) e envie com POST para a chave do seu dispositivo.

curl -X POST "https://probeharbor.dev/api/ingest/YOUR_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"temp1": 42.5, "door1": false, "battery": 87, "rssi": -62}'

Formatos de payload: chaves planas, o objeto clássico temp, sensors[] tipado, SenML (RFC 8428) ou JSON state do Home Assistant REST. Eles estão documentados em ingestão e webhooks e na referência para desenvolvedores de ingestão push. Teste exemplos ao vivo: nativo, SenML, HA REST.

Feed pull

1. Confirme que seu feed retorna JSON via HTTPS. Formato clássico (chave raiz padrão temp):

{
  "temp": {
    "0": { "c": 18.5, "f": 65.3, "h": 42 },
    "1": { "c": 19.0, "f": 66.2, "h": 40 },
    "avg": { "f": 65.75, "c": 18.75, "h": 41 }
  },
  "battery_pct": 87,
  "rssi": -62
}

2. Abra Devices → Pull feeds.
3. Adicione um feed: nome, URL HTTPS e JSON root key (padrão temp). Use Test feed URL antes de salvar.
4. Clique em Save pull setup: as chaves das sondas são importadas automaticamente do feed ao vivo. Renomeie os rótulos na mesma página ou clique em Accept suggested names.
5. Clique em Fetch now para buscar leituras na hora, ou espere a próxima consulta programada e confira os cartões em Live.

Por padrão, os feeds pull esperam objetos de sonda aninhados sob a raiz configurada (não chaves planas no estilo push). Arrays JSON SenML e respostas do Home Assistant REST são detectados automaticamente quando essa raiz não existe: cole a URL como está e mapeie as chaves de sonda que o SenML ou o HA expõem (ex.: 0, state). Se o microcontrolador não faz TLS (Uno + shield Ethernet W5100), use um relay HTTPS local (veja feeds em Python ou o encaminhador HTTP→HTTPS com a biblioteca padrão para ingestão push).

Já usa MQTT?

Mantenha o Mosquitto ou o MQTT do Home Assistant na sua rede local e espelhe as leituras via HTTPS. O ProbeHarbor não é um broker MQTT. Receita completa (curl, rest_command do HA, Node-RED): guia da ponte MQTT. Veja também ProbeHarbor vs. MQTT caseiro.

Confira se está tudo funcionando

• Live: os cartões se atualizam ao vivo; sondas atrasadas mostram um aviso amarelo de off-line depois de uns 30 minutos.
• Devices → Status: última conexão, bateria e RSSI quando o payload os inclui (depois da primeira leitura ao vivo).
• O essencial contra congelamento: defina o limite de congelamento e o e-mail em Devices após o primeiro POST, ou em Alerts → When to alert, e envie um teste (libera o Overview completo após a configuração inicial).
• Overview: status do espaço; depois do essencial, as métricas de Status (horas abaixo de zero, margem mais fria, ΔT interno−externo, dispersão entre sondas) e Insights (noites de risco, porta/energia/movimento, qualidade do ar). Os gráficos semanais podem sobrepor umidade e ponto de orvalho quando há UR.

Relacionados

• API de ingestão e webhooks de alerta
• Ativação pelo QR do kit
• Configurar feeds de temperatura (pull em detalhes)
• Depurar leituras desatualizadas
• Receita da ponte MQTT · vs. MQTT caseiro · documentação MQTT para desenvolvedores
• Desenvolvedores: ingestão push · feeds pull

Perguntas frequentes

Devo usar push ou pull?
Use push para nós ESP/Arduino que conseguem fazer POST HTTPS de saída. Use pull quando você já tem um feed JSON HTTPS público (ou um relay TLS) que o ProbeHarbor pode buscar em intervalos programados.

Por que as leituras não aparecem em Home depois que a ingestão funciona?
Faça POST do JSON primeiro: as chaves dos sensores são importadas automaticamente em Devices. Se Home continuar vazio, confirme que o dispositivo recebeu um POST e confira Devices → Device health. Feeds pull: raiz do JSON correta (padrão temp), a menos que a URL retorne SenML ou JSON REST do Home Assistant, que são detectados automaticamente.