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 |
|
Path |
|
Port |
|
Rate |
Up to 20 reports per minute for a tap. |
Send a POST with a JSON body:
{
"token": "<tap token>",
"pour_volume": 0.35
}
tokenis the tap token. It goes in the body only; there is no query or path variant. A missing or unknown token is answered with401.pour_volumeis required, in litres, and must be a finite number. A value that is missing or is not a number is answered with422.Every other field is ignored.
A positive
pour_volumerecords 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
200and nothing is stored.A report over the per-minute allowance is answered with
429and 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#
Pour a small amount.
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_volumeis missing or is not a number.429: more than 20 reports in a minute. Send one report per pour.200but 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,503or504: 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.