Documentation

Home Assistant mode

Home Assistant mode is free forever. Your sign reads the sensors from a PerfectDraft Pro integration you already run, so there is no subscription and nothing to sign in to. In exchange, you are doing the setup work yourself. Everything you need is on this page, in the order you need to do it.

1. Prerequisites

You need all five of these before the sign can show you anything.

• A working Home Assistant installation, on a machine that stays on. Any of the supported install types is fine, since what matters is only that it can run a custom integration.
• A PerfectDraft Pro machine, already paired with the PerfectDraft app and reporting a keg there. A PerfectDraft or PerfectDraft Black has no app or API for Home Assistant to read, so this mode cannot work with one. Manual mode exists for those.
• Your PerfectDraft account email and password. Home Assistant signs in to PerfectDraft, not the sign.
• Your sign and Home Assistant on the same network, and a network that allows devices to discover each other. Guest networks and client isolation will stop the sign being found.
• A GitHub account. Free to create, and you may well have one already. The Home Assistant Community Store (HACS), which is where the PerfectDraft integration is distributed, downloads from GitHub and asks you to sign in there the first time you set it up. Nothing of yours is published; it is only how HACS fetches things on your behalf.

Which install type do I have?

This only matters for the next step, because it decides how you install HACS. All of these work with the sign.

• Home Assistant OS, the recommended install. This includes Home Assistant Green, which arrives with it already installed, the Yellow, and the older Blue. Blue is no longer sold but still gets every release, so a Blue is perfectly fine here. It also includes a DIY install on a Raspberry Pi or a spare PC.
• Home Assistant Supervised, managed by you on Debian.
• Home Assistant Container, usually Docker.
• Home Assistant Core, run directly in a Python environment.

2. Install HACS

HACS is not preinstalled on any Home Assistant install, including Green and the other boxes, so you will need to add it yourself even if everything else came ready to go. It is the store that the PerfectDraft integration is distributed through.

How you install it depends on the type you identified above.

• Home Assistant OS or Supervised: add https://github.com/hacs/addons as an add-on repository, then install and start the HACS add-on from your add-on list and follow the instructions it prints in its own log.
• Container: get a terminal inside the running container and run wget -O - https://get.hacs.xyz | bash -
• Core: switch to the Home Assistant user account and run that same command.

Then restart Home Assistant, add HACS from Settings → Devices & services → Add integration, and authorise it against your GitHub account when it asks. The current steps live in the HACS documentation, which is worth following directly if anything here has drifted.

3. Install the PerfectDraft Pro integration

The sign reads a fork of Falkvinge’s integration. Full instructions are in the repository’s README, and the short version is:

• In HACS, open the three-dot menu, choose Custom repositories, paste https://github.com/brettjenkins/hassio-integration-perfectdraft-pro and set the category to Integration.
• Search HACS for PerfectDraft and download it.
• Restart Home Assistant. It will not appear until you do.
• Add it from Settings → Devices & services → Add integration → PerfectDraft and enter your PerfectDraft email and password.

Setup also asks for a one-time verification token, which takes about thirty seconds to fetch from the PerfectDraft login page using your browser’s developer console. The README has the exact command to run. Two things to know before you start: the token expires about two minutes after you generate it, so have the Home Assistant dialog open and ready, and it is genuinely one-time, since the integration refreshes its own access from then on.

Once it is set up you should have a PerfectDraft device in Home Assistant with sensors for the keg, how much is left, temperature, freshness, connection and the door. Confirm you can see live values there before touching the sign. The sign only mirrors these, so if they are wrong or missing, nothing on the sign will be right.

4. Set the sign to Home Assistant mode

Now go through the sign’s own setup, in a browser. Plug it in, join the Wi-Fi hotspot it creates, and tell it which Wi-Fi network to join. When it asks which mode you want, open Only for technical users and choose Home Assistant. Because this mode is free, the sign skips the subscription step entirely and takes you straight to the sensor names.

Those fields are prefilled with the integration’s default entity ids, so if you have not renamed anything, you can leave every one of them alone. If you have, put your own entity ids in. You can find them under Settings → Devices & services → Entities.

The fridge one is the odd one out and is nothing to do with the integration. If you happen to have a temperature sensor in the fridge your keg lives in, name it here and the sign will show it. Leave it as it is if you don’t, and the sign hides that row.

5. Add the sign to Home Assistant

The sign is an ESPHome device, so Home Assistant adopts it the same way as any other. You do not need the ESPHome Device Builder add-on for this: that is for building firmware, and your sign already has ours.

Once the sign is on your Wi-Fi, Home Assistant finds it by itself and offers it to you as a discovered device under Settings → Devices & services. Click Configure and confirm, and that is the whole job. If discovery does not happen, which usually means your network is blocking it, add ESPHome manually from Add integration and give it the sign’s address. The sign shows its own IP address on screen and in its settings pages.

6. Save, and pour something

Finish the rest of the sign’s setup, which is whether the screens rotate, how long each one stays up, and when it installs updates. Then press Finish. The sign restarts and your keg should be on screen within a few seconds.

If it isn’t working

• The sign sits on a loading screen. It is not getting anything from Home Assistant. Check the sign appears as connected in Home Assistant, then check the entity ids you entered match your real ones exactly.
• Home Assistant never discovers the sign. Almost always the network. Confirm both are on the same one, and that it is not a guest network or one with client isolation switched on. Adding ESPHome by IP address gets round discovery entirely.
• The sensors are empty in Home Assistant too. Then the problem is between Home Assistant and PerfectDraft, not the sign. Check the integration itself and confirm the official PerfectDraft app is showing your keg.
• The keg figures look wrong. The sign shows exactly what the API reports, and the official app will agree with it. See the FAQ on keg readings.