Adding push and pull devices

ThermalTrace accepts readings two ways: your hardware pushes JSON to an ingest URL, or we pull HTTPS JSON from a public feed on a schedule. Both are configured under Dashboard → Devices. New ESP / battery nodes should use push. Pull is for always-on LAN servers or relays that already expose HTTPS JSON.

A free account (no credit card) ties your ingest key to your household so history and alerts stay private. Browse the live demo first if you want to see readings without signing up.

Choose push or pull

Push device (recommended)

1. Sign in and open Devices.
2. Under Push devices, click Create push device (named Workshop probe by default: rename anytime).
3. On the ingest callout: scan the QR, or 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 (ingest URL or path pre-filled). The key stays on the page for 30 minutes and survives refresh until you dismiss it.
4. Lost the key later? On the device card use Reveal ingest key (when key recovery is enabled on the server) or Rotate key to issue a new one. Devices created before key recovery was enabled need one rotate to store a recoverable encrypted copy.
5. Flash an ESP32 (see flashing options: Arduino IDE, PlatformIO, MicroPython, or Espressif web esptool) or a Pico W ( CircuitPython / MicroPython / Arduino-Pico) or an STM32 Nucleo ( Zephyr C + Ethernet) or a CH32V307 ( WCHNET C + Ethernet) or an Uno in GNU AVR assembly ( ATmega328P + W5100) or a Teensy 4.1 ( QNEthernet) or a PIC18F67J60 ( MLA TCP/IP) or a Particle Boron ( LTE webhook). Need parts first? ESP32 freeze kit BOM, Pico W, STM32 Zephyr, CH32V RISC-V, AVR assembly, Teensy 4.1, PIC18 Ethernet, or cellular (waterproof DS18B20). Serial at 115200 should show POST 200 (or publish ok on Boron). Sensor keys import automatically (flat keys, temp object, SenML, or Home Assistant REST). Rename sensors on the Devices page afterward. Manual mapping under Advanced is optional for pre-mapping keys.
6. More samples (Uno Ethernet + DHT22, MAX31855, MAX6675, etc.): sketches/. W5100 cannot TLS. POST HTTP to a LAN relay (Python feeds / push_https_forward.py).
7. Smoke-test with curl, then open Home while signed in. Within about 30 minutes without a post, Home warns that a probe may be offline.

Example curl (push)

Fetch a live sample body from the example ingest feed (weather-driven), then POST it to your device key.

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

Payload styles: flat keys, classic temp object, typed sensors[], SenML (RFC 8428), or Home Assistant REST state JSON: are documented in ingest & webhooks and the developer push ingest reference. Try live samples: native, SenML, HA REST.

Pull feed

1. Confirm your feed returns HTTPS JSON. Classic shape (default root key 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. Open Devices → Pull feeds.
3. Add a feed: name, HTTPS URL, and JSON root key (default temp). Use Test feed URL before saving.
4. Click Save pull setup: probe keys auto-import from the live feed. Rename labels on the same page, or click Accept suggested names.
5. Click Fetch now to pull readings immediately, or wait for the next scheduled poll and confirm cards on Home.

Pull feeds expect nested probe objects under the configured root by default (not flat push-style keys). SenML JSON arrays and Home Assistant REST responses are auto-detected when that root is missing: paste the URL as-is and map the probe keys SenML or HA expose (e.g. 0, state). If the MCU cannot do TLS (Uno + W5100 Ethernet shield), use a local HTTPS relay (see Python feeds or the stdlib HTTP→HTTPS forwarder for push ingest).

Already on MQTT?

Keep Mosquitto or Home Assistant MQTT on your LAN and mirror readings over HTTPS. ThermalTrace is not an MQTT broker. Full recipe (curl, HA rest_command, Node-RED): MQTT bridge guide. See also ThermalTrace vs DIY MQTT.

Verify you’re live

• Home, live cards update; lagging probes show a yellow offline warning after ~30 minutes.
• Devices → Device health: last seen, battery, and RSSI when the payload includes them (after first live reading).
• Overview: space status plus Status metrics (freeze hours, coldest margin, indoor−outdoor ΔT, probe spread). Switch to Insights for nights-at-risk, door/power/motion cards, and air quality. Week charts can overlay humidity and dew point when RH is present.
• Freeze essentials, set freeze °F + email on Devices after first POST, or under Alerts → Essentials, then send a test.

Related

• Ingest API and alert webhooks
• Kit QR onboarding
• Configuring temperature feeds (pull deep-dive)
• Debugging stale readings
• MQTT bridge recipe · vs DIY MQTT · developer MQTT docs
• Developer: push ingest · pull feeds

FAQ

Should I use push or pull?
Use push for ESP/Arduino nodes that can POST outbound HTTPS. Use pull when you already have a public HTTPS JSON feed (or a TLS relay) that ThermalTrace can fetch on a schedule.

Why don’t readings show on Home after ingest succeeds?
POST JSON first: sensor keys auto-import on Devices. If Home is still empty, confirm the device received a POST and check Devices → Device health. Pull feeds: correct JSON root (default temp) unless the URL returns SenML or Home Assistant REST JSON, which auto-detect.