ESPHome for temperature#

Cloud Hosted: needs validation

Note

ESPHome temperature is available in the Cloud Hosted beta, on every plan, but has not been validated on real hardware yet. It is not available on Self Hosted. The setup below follows how BrewGraph receives the reading; tell us if something does not work as described.

An ESPHome node, or any temperature sensor you already have in Home Assistant, can report a temperature to BrewGraph, for example the air temperature of a fermentation fridge or a keg fridge. This page shows two ways to set it up with Home Assistant: an ESPHome node that posts directly, and Home Assistant forwarding an existing temperature entity.

What you need#

  • An ESPHome device added in BrewGraph under Devices. BrewGraph shows its device token on the device page. See Device Tokens.

  • The device linked to a batch or to a vessel. The reading is stored as an ambient temperature for the batch linked to the device or its vessel. If the device is linked to neither, the reading is dropped, although BrewGraph still answers 200.

  • Home Assistant, and for the first setup an ESPHome node with a temperature sensor.

Endpoint and payload#

Field

Value

Host

ingest.brewgraph.com

Path

/ingest/esphome-temp. The API also accepts /api/ingest/esphome-temp.

Port

80 for plain HTTP, which is recommended on an ESP8266. HTTPS on 443 also works on an ESP32.

Interval

Not shorter than the reporting interval of your plan. In the beta this is about 900 seconds.

Send a POST with a JSON body:

{
  "token": "<device token>",
  "temperature": 4.2
}
  • temperature is required, in °C, and must be a finite number. Anything else is answered with 422.

  • The device token can also be sent as ?token=<token> on the address or as a path segment, /ingest/esphome-temp/<token>. If the body also has a token, the body wins.

  • An unknown token is answered with 401.

  • A reading that arrives faster than your plan’s reporting interval is answered with 429 and is not stored.

Setup A: an ESPHome node posts directly#

Use this when the temperature sensor is attached to an ESPHome node. The node sends each reading with the ESPHome http_request component.

  1. Add the device in BrewGraph and copy its token.

  2. In the ESPHome secrets file, add the token:

    brewgraph_token: "YOUR-DEVICE-TOKEN"
    
  3. Add the following to the node’s configuration. Replace the comment with the platform of your own temperature sensor and keep the id and the on_value block.

    substitutions:
      brewgraph_token: !secret brewgraph_token
    
    http_request:
      timeout: 10s
    
    sensor:
      - platform: ...      # your temperature sensor
        id: fridge_temp
        name: "Fridge temperature"
        update_interval: 960s
        on_value:
          then:
            - http_request.post:
                url: http://ingest.brewgraph.com/ingest/esphome-temp/${brewgraph_token}
                request_headers:
                  Content-Type: application/json
                json: |-
                  root["temperature"] = x;
    

    The address carries the token, so the body only holds the temperature. This keeps the token in the secrets file. ESPHome puts a number into the JSON body with the root["temperature"] = x; form; the plain json: mapping form can send text only. x is the new sensor value in °C.

  4. Install the configuration on the node.

The sensor value is posted every time it is published. Set update_interval to at least the reporting interval of your plan. If the sensor publishes more often than that, add a throttle filter so the faster values are not sent:

filters:
  - throttle: 960s

Plain HTTP is used above because it works on an ESP8266. For HTTPS on an ESP32, use https:// in url; certificates are then checked by default.

Setup B: Home Assistant forwards an existing entity#

Use this when Home Assistant already has a temperature entity that you want in BrewGraph, whatever its source: an ESPHome node, a Zigbee sensor, or a thermostat.

  1. Add the device in BrewGraph and copy its token.

  2. In the Home Assistant secrets.yaml, add the full address with the token:

    brewgraph_esphome_temp_url: "http://ingest.brewgraph.com/ingest/esphome-temp/YOUR-DEVICE-TOKEN"
    
  3. In configuration.yaml, add a REST command that posts the temperature. Replace sensor.fridge_temperature with your own entity:

    rest_command:
      brewgraph_temperature:
        url: !secret brewgraph_esphome_temp_url
        method: post
        content_type: "application/json"
        payload: '{"temperature": {{ states("sensor.fridge_temperature") | float }} }'
    

    Restart Home Assistant, or reload the REST commands, after the change.

  4. Add an automation that calls the command on a schedule. The time pattern below runs every 20 minutes, and the condition skips a moment when the entity is unavailable or unknown:

    automation:
      - alias: "Send fridge temperature to BrewGraph"
        triggers:
          - trigger: time_pattern
            minutes: "/20"
        conditions:
          - condition: template
            value_template: "{{ is_number(states('sensor.fridge_temperature')) }}"
        actions:
          - action: rest_command.brewgraph_temperature
    

The temperature must be in °C. If your entity reports °F, convert it in the payload template first.

Choose a schedule that is not shorter than your plan’s reporting interval (about 900 seconds in the beta). A reading that comes in earlier is answered with 429 and is not stored.

Check that it works#

  1. Wait for one reporting interval.

  2. Open the device in BrewGraph. The latest temperature should appear on the device page.

  3. Make sure the device is linked to the batch or vessel you want to follow. The temperature then shows with that batch.

Troubleshooting#

  • 401: the token is missing or mistyped. Copy it again from the device page and check the secret.

  • 422: temperature is missing, is not a number, or is not finite. In Home Assistant, check that the entity has a number and not unavailable.

  • 429: raise the interval to at least your plan’s reporting interval.

  • 200 but nothing appears: the device is not linked to a batch or a vessel, so the reading is dropped. Link it under Devices.

  • 502, 503 or 504: check that the host is the ingest host, not the address you use to open the app.

For every status code and what to do about it, see Ingest error codes.

Coming later#

An ESPHome turbine flow meter that reports pours to a tap is in beta on Cloud Hosted and will not come to Self Hosted; see ESPHome for pours.

More information#