Files

6.4 KiB

PerfectDraft Pro for Home Assistant

A Home Assistant custom integration for the PerfectDraft Pro beer dispenser. Monitor your keg's temperature, remaining volume, pour history, and more — right from your HA dashboard.

Sensors

Sensor Description Unit
Temperature Current beer temperature °C
Keg Name of the tapped beer, resolved from a bundled catalog of 117 kegs —
Keg Product Numeric product ID of the fitted keg —
Keg Remaining Beer left in the keg %
Keg Freshness Days remaining until 30-day freshness expires days
Connection Machine connectivity status —
Door Door open/closed state —
Pours Number of pours since keg was loaded —
Last Pour Volume of the most recent pour mL
Mode Current operating mode (standard, eco, etc.) —
Firmware Machine firmware version (disabled by default) —

Installation

  1. Open HACS in Home Assistant
  2. Click the three-dot menu > Custom repositories
  3. Add this repository URL and select Integration as the category
  4. Search for "PerfectDraft" and install
  5. Restart Home Assistant

Manual

  1. Copy the custom_components/perfectdraft folder to your HA config/custom_components/ directory
  2. Restart Home Assistant

Setup

Step 1: Credentials

Go to Settings > Devices & Services > Add Integration > PerfectDraft and enter your PerfectDraft app email and password.

Step 2: Verification Token

The integration needs a one-time verification token from PerfectDraft's website. This step looks more technical than it actually is — it takes about 30 seconds:

  1. Open perfectdraft.com/en-gb/customer/account/login in your browser (Chrome, Firefox, Edge, etc.) — you do not need to log in on this page, just open it
  2. Press F12 to open Developer Tools, then click the Console tab
  3. Paste this command at the console prompt and press Enter — once, not as a "Live expression", which re-runs it over and over:
grecaptcha.enterprise.execute('6LcZQiUoAAAAAAO3JUjLiT470c-pNXbWyepuvMtV', {action: 'Magento/login'}).then(t => { console.log(t); const b = document.body.appendChild(document.createElement('button')); b.textContent = 'Click THIS BLACK BOX to copy your PerfectDraft token'; b.style = 'position:fixed;top:40%;left:50%;transform:translateX(-50%);z-index:2147483647;padding:20px 40px;font-size:22px;background:#000;color:#fff;border-radius:8px;cursor:pointer'; b.onclick = () => navigator.clipboard.writeText(t).then(() => b.textContent = 'Copied! Paste it into Home Assistant', e => b.textContent = 'Copy failed: ' + e.message) })
  1. A black box saying Click THIS BLACK BOX to copy your PerfectDraft token appears in the middle of the page — click it, and it changes to Copied!
  2. Paste the token into the Home Assistant setup dialog
  3. Click Submit within 2 minutes (the token expires)

If the button says Copy failed, the same token is printed in the console: right-click it there and copy it.

That's it! The integration will authenticate and start polling your PerfectDraft Pro. Token refresh is automatic — you should not need to repeat this step. If the session does eventually expire, Home Assistant will prompt you to re-authenticate. (This is a new integration, so the exact session lifespan is still being determined — it's at least 30 days and may well be indefinite.)

Step 3: Configure polling

After setup, you can adjust the polling interval in the integration's options. Default is 15 minutes; minimum is 1 minute.

Companion Card

The PerfectDraft Card is a custom Lovelace card that visualises your keg data as a beer emoji pictogram — see at a glance what's on tap, how cold it is, and how many glasses remain. Designed for wall-mounted panels (Sonoff NSPanel Pro), works on any HA dashboard.

PerfectDraft Card showing Leffe Blonde at 3°C with 18 glasses remaining

Install via HACS (Dashboard category) or see the card repository for details.

How It Works

The integration communicates with PerfectDraft's cloud API to read your machine's telemetry data. Token refresh is handled automatically via AWS Cognito — no reCAPTCHA needed after the initial setup.

For the full technical story of how this integration was reverse-engineered, see DISCOVERY.md.

The keg name catalog

The machine reports the fitted keg as a numeric product ID, not a name. custom_components/perfectdraft/keg_catalog.json maps those IDs to beer names, and the Keg sensor is that lookup.

The catalog is maintained by hand, because it has to be: the PerfectDraft API will not return the ID-to-name mapping in bulk, so there is no endpoint to scrape and no way to infer an entry. Every name was observed directly from a machine with that keg actually fitted. It covers kegs that are no longer sold, since a discontinued keg can still be sitting in someone's machine.

If your Keg sensor is blank, the machine is reporting an ID the catalog does not have. Open an issue with the value of the Keg Product sensor and it can be added.

Credits

The keg name sensor and everything behind it are the work of Brett Jenkins, contributed from his fork at brettjenkins/hassio-integration-perfectdraft-pro:

  • Active-keg detection and the Keg / Keg Product sensors — #2, which also made keg freshness read from the API's own insertion date instead of waiting for a client-side detection, so the countdown is right immediately after setup rather than after the next keg change.
  • The keg name catalog — the original 114-entry mapping, built up across his fork's #1 and backported here. Brett also caught four names this repo had wrong, including one beer that had been renamed by the brewery and three carrying leftover shop-listing text.

The same mapping drives the tap sign at seemy.beer, where it has been running in production.