ThermalTrace in Home Assistant

Install via HACS

1. In Home Assistant: HACS → Integrations → ⋮ → Custom repositories
2. Add repository https://github.com/doodersrage/thermaltrace-home-assistant (category: Integration)
3. Install ThermalTrace and restart Home Assistant
4. Settings → Devices & services → Add integration → ThermalTrace
5. Create a live share link under Dashboard → Share (Free includes one family live link; Pro adds history/metrics and never-expire) and paste the token from /share/YOUR_TOKEN

Extended developer walkthrough (GitHub Pages): Home Assistant guide ↗ · Manual YAML recipes still work if you prefer REST sensors over HACS.

What shows up in HA

• Sensors: temperature, humidity, CO₂, pressure, PM2.5, VOC, level, energy, and generic numeric probes
• Binary sensors: door, flood/leak, motion, and power states
• Polling. HACS defaults to every 5 minutes (60–3600 s configurable). That is fine for dashboards; for time-critical freeze thresholds and wet contacts prefer native push ingest (ESP/Arduino → ThermalTrace) so alerts fire on the reading, not after the next HA poll. Dual-run is normal: push for freeze and leak SMS, HACS for local entities.
• Services (optional inbound webhook + secret from Dashboard → Share): thermaltrace.snooze, vacation, clear_snooze, clear_vacation, status
• Push service (optional ingest key): thermaltrace.push with a JSON payload dict

Native JSON formats (push & pull)

Beyond the HACS share-link path, ThermalTrace auto-detects JSON your HA stack may already emit, no custom wrapper required.

• Home Assistant REST sensor. POST or pull { "state": "65.3", "attributes": { "unit_of_measurement": "°F" } }; map probe key state on Devices
• SenML (RFC 8428). JSON array with Cel / %RH units; common on IoT gateways
• thermaltrace.push: native sensors[] from automations (see indoor temperature below)
• MQTT bridge: unwrap LAN MQTT payloads via POST /api/ingest/mqtt

Live samples: HA REST · SenML · Ingest formats guide

Indoor temperature via Home Assistant

Prefer house vs probe context on Overview and History. Two paths: Nest OAuth on Pro (when available), or push any HA climate entity as Plan B: useful when Ecobee developer signups are closed or you use another thermostat brand.

Nest OAuth (Pro, preferred when available)

On thermaltrace.dev, Pro households can connect Nest from Dashboard → Temperature for live indoor temp, setpoint, and HVAC mode next to attic/crawlspace/shop probes: freeze alerts can include that context. History stores thermostat snapshots on the same ~15-minute cron as other Pro collectors.

• End-user compare: ThermalTrace vs Nest
• Self-hosted operators enabling OAuth secrets: Nest & Ecobee operator setup

Plan B: push indoor air from Home Assistant

Ecobee’s developer program signups are often closed, so Ecobee OAuth may not be available even on Pro. Any thermostat already in HA (Ecobee, Nest via HA, generic climate.*) can still feed ThermalTrace: push indoor air with thermaltrace.push, then choose that probe as your Indoor reference under Dashboard → Devices.

1. Expose your thermostat in HA (e.g. climate.living_room).
2. Every 15 minutes, call thermaltrace.push with a temperature sensor (key house_indoor).
3. In ThermalTrace: Devices → Indoor reference: pick that sensor.

automation:
  - alias: Push house temp to ThermalTrace
    trigger:
      - platform: time_pattern
        minutes: "/15"
    action:
      - service: thermaltrace.push
        data:
          sensors:
            - key: house_indoor
              kind: temperature
              value: "{{ state_attr('climate.living_room', 'current_temperature') }}"
              unit: F

Also useful for Ecobee via HA when OAuth is unavailable: see ThermalTrace vs Ecobee. Extended payload notes (GitHub Pages): developer docs ↗

Dual-run with MQTT (usual pattern)

ThermalTrace is not an MQTT broker. Most homelabbers keep Mosquitto / ESPHome / HA MQTT on the LAN and mirror selected topics over HTTPS when they want cloud freeze and leak alerts and history.

• MQTT → HTTPS bridge recipe POST /api/ingest/mqtt with your device key
• Node-RED flow for Mosquitto subscribers
• ThermalTrace vs self-hosted MQTT, when hosted alerts beat running your own stack

Alerts into Home Assistant

Pro outbound webhooks fire when ThermalTrace sends a freeze, leak, or custom-rule alert. Point the URL at your HA webhook endpoint or import the blueprint.

• Download webhook blueprint YAML
• Entity naming YAML for push devices
• Product guide: Ingest & webhooks
• Configure outbound + inbound tokens under Dashboard → Share

Verify X-Signature when you set a webhook signing secret in ThermalTrace. HA (or any receiver) should reject POSTs that fail the HMAC check. The blueprint documents the header; details in the ingest & webhooks guide and FAQ below.

Example automation

Snooze ThermalTrace freeze and leak alerts while a door is open for maintenance:

automation:
  - alias: Snooze ThermalTrace while door open
    trigger:
      - platform: state
        entity_id: cover.garage_door
        to: "open"
    action:
      - service: thermaltrace.snooze
        data:
          hours: 4