ESPHome for pours#

Cloud Hosted: beta

Note

ESPHome for pours is in beta. It is open on every plan in the Cloud Hosted beta, but it has been tested on simulated payloads only, not yet on a real flow meter. It is not available on Self Hosted. The setup below follows how BrewGraph receives the report; tell us if something does not work as described.

An ESPHome node with a turbine flow meter can report the volume of each pour to a tap. BrewGraph records the pour and lowers the remaining volume of the keg on that tap. This page describes the request the node sends and an ESPHome http_request example. Counting the pulses of the flow meter and turning them into litres is done on your node, and depends on the meter.

To report a temperature from an ESPHome node instead, see ESPHome for temperature. For a load-cell based device, see KegMon.

What you need#

  • A tap added in BrewGraph, with a keg on it that holds a batch. The flow meter belongs to the tap, not to a device: BrewGraph shows the tap token on the tap page. See Device Tokens.

  • An ESPHome node with a turbine flow meter that can work out the volume of each pour in litres.

Endpoint and payload#

Field

Value

Host

ingest.brewgraph.com

Path

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

Port

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

Rate

Up to 20 reports per minute for a tap.

Send a POST with a JSON body:

{
  "token": "<tap token>",
  "pour_volume": 0.35
}
  • token is the tap token. It goes in the body only; there is no query or path variant. A missing or unknown token is answered with 401.

  • pour_volume is required, in litres, and must be a finite number. A value that is missing or is not a number is answered with 422.

  • Every other field is ignored.

  • A positive pour_volume records one pour and lowers the keg’s remaining volume, never below zero. A negative value is a correction: it raises the level again.

  • The payload has no event id, so the same body sent twice records two pours. Send each pour once.

  • A tap with no keg, or a keg with no batch, accepts the report and ignores it: the answer is 200 and nothing is stored.

  • A report over the per-minute allowance is answered with 429 and is not stored.

ESPHome example#

The node posts once when a pour ends. In the ESPHome secrets file, add the tap token:

brewgraph_tap_token: "YOUR-TAP-TOKEN"

In the node’s configuration, add a script that posts a volume. Call it from your own pour detection with the pour in litres, for example script.execute with litres: 0.35:

substitutions:
  brewgraph_tap_token: !secret brewgraph_tap_token

http_request:
  timeout: 10s

script:
  - id: send_pour
    parameters:
      litres: float
    then:
      - http_request.post:
          url: http://ingest.brewgraph.com/ingest/esphome-flow
          request_headers:
            Content-Type: application/json
          json: |-
            root["token"] = "${brewgraph_tap_token}";
            root["pour_volume"] = litres;

How the node detects a pour is up to your configuration, for example a pulse counter that is read when the flow stops. On an ESP32, use https:// in url if you prefer HTTPS.

Check that it works#

  1. Pour a small amount.

  2. Open the tap in BrewGraph. The pour and the new volume of the keg should appear.

Troubleshooting#

  • 401: the tap token is missing or mistyped. Copy it again from the tap page, and send it in the body.

  • 422: pour_volume is missing or is not a number.

  • 429: more than 20 reports in a minute. Send one report per pour.

  • 200 but nothing appears: the tap has no keg, or the keg has no batch, so the report is ignored. Connect a keg that holds a batch.

  • 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.

More information#