Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
788ae28c44 | ||
|
|
203d0fd228 | ||
|
|
542c7599ab | ||
|
|
d43f1d675d | ||
|
|
e8977143c5 | ||
|
|
30138df1a5 | ||
|
|
16ea0267d7 | ||
|
|
4a879e84bd | ||
|
|
01b4247cf3 | ||
|
|
74b5e36ef1 | ||
|
|
45f1e6f394 | ||
|
|
1452620f0a | ||
|
|
1d0c014111 | ||
|
|
2d3c5c0faf | ||
|
|
d0748e7e4f | ||
|
|
672a41a5df | ||
|
|
b28aa89404 | ||
|
|
a2319363d6 | ||
|
|
5adce69c23 | ||
|
|
c086437ce5 | ||
|
|
571d2837f6 | ||
|
|
a53485a927 | ||
|
|
3d8344b9bf | ||
|
|
ffe8006840 | ||
|
|
2134576537 | ||
|
|
a44f5ab9cf | ||
|
|
d1b64fd9c7 | ||
|
|
7493721d4a | ||
|
|
6de5f6a960 |
@@ -0,0 +1,72 @@
|
||||
# Agent Handoff — PerfectDraft Card
|
||||
|
||||
## Current State (2026-04-18)
|
||||
|
||||
The PerfectDraft Card custom Lovelace card is working and deployed on a Sonoff NSPanel Pro 120 in landscape mode. Current release is **v0.1.5** on GitHub via HACS.
|
||||
|
||||
## What's Done
|
||||
|
||||
- Full card implementation: two-zone layout (beer label left ~1/4, emoji grid right ~3/4)
|
||||
- 72-beer catalog with brand color palettes
|
||||
- 21 real keg product images (full resolution from PerfectDraft CDN)
|
||||
- CSS Grid emoji layout with fixed slots (6×3 for 330mL, etc.)
|
||||
- Glass size selection dialog (250/330/500/UK pint/US pint)
|
||||
- Beer selection dialog with search
|
||||
- Freshness warning system (CSS-only, 4 tiers)
|
||||
- Visual card editor with HA device registry auto-discovery
|
||||
- HACS-compatible, deployed via GitHub releases
|
||||
- Screenshot in both repos' READMEs
|
||||
- Editor version marker for debugging
|
||||
|
||||
## What Needs Doing Next (Immediate)
|
||||
|
||||
### 1. Add 31 newly downloaded beer images to catalog
|
||||
|
||||
**31 new keg images** were downloaded from the PerfectDraft store DOM and are sitting in:
|
||||
```
|
||||
.worktree/perfectdraft-card/src/assets/kegs/
|
||||
```
|
||||
|
||||
These need to be wired into `src/beer-catalog.ts` by adding `imagePath: kegImage("slug")` to each beer entry that now has an image file. The beers that gained images are:
|
||||
|
||||
leffe-dete, hoegaarden, stella-artois-0, leffe-0, kwak, dupont, san-miguel, fruh-kolsch, castelain, lowenbrau, schneider, hasseroder, camden-pale, camden-hells, camden-ipa, camden-eazy, becks, trooper, northern-monk, st-austell, old-speckled-hen, anoesteke, vocation-hop-skip, vocation-life-death, franziskaner-royal, saint-feuillien, leffe-prestige, leffe-brune, hoegaarden-rosee, rousse-mont-blanc, ninkasi
|
||||
|
||||
Also discovered from the DOM:
|
||||
- **New beers to add to catalog**: Castelain Ch'ti Blonde (slug: `castelain-chti`), Hertog Jan Grand Pilsener (slug: `hertog-jan-grand`), Anheuser-Busch Bud uses filename `keg-abb_2x.png` (already have as `bud.png`)
|
||||
- **Leffe d'Été** image filename is `keg--leffe-summer-e_te__2x.png` (not `keg--leffe_d_ete`)
|
||||
- **Haake-Beck** image is a JPG (`haake_beck.jpg`) at `/h/a/` path — the cached version is too small (9KB). May need to find from UK store DOM.
|
||||
- **Diebels** image returned a placeholder — no real image found yet.
|
||||
|
||||
After updating the catalog: rebuild (`npm run build` in the worktree), commit, merge to main, push to both remotes, create GitHub release v0.1.6.
|
||||
|
||||
### 2. Test ghost emojis after D&D session
|
||||
|
||||
User will drink some beers and report back on how the greyed-out empty emoji slots look on the NSPanel Pro. Current implementation: `opacity: 0.15; filter: grayscale(1)`.
|
||||
|
||||
### 3. Test freshness warnings
|
||||
|
||||
Untested — will activate naturally as the keg approaches 14 days old.
|
||||
|
||||
### 4. Test tap dialogs on NSPanel Pro
|
||||
|
||||
Beer picker and glass size dialogs haven't been tested on the NSPanel Pro's touch screen yet.
|
||||
|
||||
## Architecture Notes
|
||||
|
||||
- **Worktree**: Implementation branch is at `.worktree/perfectdraft-card/` on branch `impl/perfectdraft-card`
|
||||
- **Main branch**: Merged and pushed to both remotes after each release
|
||||
- **Remotes**: `origin` = Gitea (git.falkvinge.net), `github` = GitHub (Falkvinge/hassio-component-perfectdraft-pro)
|
||||
- **Credentials**: `.git/credentials` store file with PATs for both remotes
|
||||
- **Build**: `npm run build` in worktree produces `dist/perfectdraft-card.js` + `dist/kegs/*.png`
|
||||
- **HACS**: Downloads from GitHub release tags. `dist/` is committed (not gitignored).
|
||||
- **Entity resolution**: Uses `hass.entities` registry with `platform === "perfectdraft"` and `translation_key` for sensor mapping. Entity IDs do NOT contain "perfectdraft" — they use user-chosen device names.
|
||||
- **Editor version**: Shown in top-right of card editor. Keep in sync with GitHub release tags.
|
||||
- **Image base URL**: Detected at runtime via `getCardBaseUrl()` scanning `<script>` tags for "perfectdraft-card".
|
||||
|
||||
## Sibling Project
|
||||
|
||||
The PerfectDraft Pro HA integration is at `/home/rick/Lab/Dev/Hassio-PerfectDraftPro`. The card reads its sensors via the HA entity registry. The integration's `DISCOVERY.md` has the full API documentation.
|
||||
|
||||
## OpenSpec
|
||||
|
||||
The change `perfectdraft-card` has all artifacts complete in `openspec/changes/perfectdraft-card/`. Tasks file tracks progress at 65/73 (remaining are manual testing tasks).
|
||||
@@ -4,18 +4,21 @@ A custom Lovelace card for the [PerfectDraft Pro Home Assistant integration](htt
|
||||
|
||||
Designed and optimised for the Sonoff NSPanel Pro 120 in landscape mode, but works on any HA dashboard.
|
||||
|
||||

|
||||
|
||||
## Features
|
||||
|
||||
- **Beer emoji pictogram** — see how many glasses remain in your keg at a glance
|
||||
- **Built-in beer catalog** — 45+ PerfectDraft beers with brand color palettes
|
||||
- **Five layouts** — landscape, portrait, compact, hero, or single-vessel gauge; choose what fits your dashboard (defaults to landscape, so existing cards are unchanged)
|
||||
- **Beer emoji pictogram** — see how many glasses remain in your keg at a glance, in a grid that shrinks to fit narrow cards
|
||||
- **Automatic beer detection** — the card reads the tapped keg from the integration and shows the right beer on its own; nothing to select
|
||||
- **Built-in beer catalog** — every keg the integration can identify, 68 with real keg photos; brand-tinted fallback art for the rest so every beer looks intentional
|
||||
- **Glass size selector** — tap the emoji zone to choose between 250 mL, 330 mL, 500 mL, UK pint, or US pint
|
||||
- **Beer selector** — tap the label zone to pick your current beer from the catalog
|
||||
- **Freshness warnings** — escalating CSS-animated alerts as your keg approaches its 30-day expiry
|
||||
- **UI-driven configuration** — no YAML editing required; everything is set up through the visual card editor
|
||||
|
||||
## Requirements
|
||||
|
||||
- [PerfectDraft Pro integration](https://github.com/Falkvinge/hassio-integration-perfectdraft-pro) installed and configured
|
||||
- [PerfectDraft Pro integration](https://github.com/Falkvinge/hassio-integration-perfectdraft-pro) **0.4.0 or later**, installed and configured — the card reads the keg sensors added in that release
|
||||
- Home Assistant 2024.8 or later
|
||||
|
||||
## Installation
|
||||
@@ -35,23 +38,61 @@ Designed and optimised for the Sonoff NSPanel Pro 120 in landscape mode, but wor
|
||||
3. Go to **Settings → Dashboards → Resources** and add `/local/perfectdraft-card/perfectdraft-card.js` as a JavaScript Module
|
||||
4. Refresh your browser
|
||||
|
||||
### Confirming which version is running
|
||||
|
||||
Browsers cache dashboard resources aggressively, so after an update it is worth
|
||||
checking which bundle actually loaded. The card logs a `PERFECTDRAFT-CARD
|
||||
v<version>` banner to the browser console on load. If that version is not the one
|
||||
you installed, hard-reload the page (Ctrl/Cmd + Shift + R) — the card behaviour
|
||||
you are seeing is the old bundle's, not the new one's.
|
||||
|
||||
## Configuration
|
||||
|
||||
**No YAML editing required.** Add the card through the HA dashboard UI:
|
||||
|
||||
1. Edit your dashboard → Add Card → search for "PerfectDraft Card"
|
||||
2. The editor auto-discovers your PerfectDraft device(s)
|
||||
3. Select your default beer and glass size
|
||||
4. Done!
|
||||
3. Pick your glass size and layout
|
||||
4. Done! The beer is detected automatically from the keg in your machine.
|
||||
|
||||
### Beer detection
|
||||
|
||||
The card identifies the tapped beer from the integration's keg sensors, matching
|
||||
on the keg's product ID first and its reported name second. When no keg is
|
||||
tapped, the card says so rather than showing a beer.
|
||||
|
||||
If your keg is not recognised, or is shown as the wrong beer, use **Correct the
|
||||
beer for the keg in the machine** in the card editor. The correction is saved
|
||||
against that keg's product ID (`beer_overrides` in YAML), so it applies while
|
||||
that keg is tapped and stops applying when you swap kegs — a correction can
|
||||
never outlive the keg it was for. The card marks any beer it is showing because
|
||||
of a correction, so an override is never mistaken for a detection result.
|
||||
|
||||
Reports of unrecognised or mis-detected kegs are welcome as issues — the fix is
|
||||
usually a one-line catalog addition, which is better for everyone than a local
|
||||
correction.
|
||||
|
||||
#### Upgrading from 0.3.x or earlier
|
||||
|
||||
`beer_name` is no longer supported and is ignored when present. Versions before
|
||||
0.3.0 required it — the editor always wrote it and new cards were seeded with
|
||||
it — and 0.3.1 then treated those leftover values as permanent overrides, which
|
||||
made cards show a beer that was no longer in the machine. Ignoring the key
|
||||
returns those cards to auto-detection. No automatic migration is possible,
|
||||
because the old value records no product ID; re-apply the correction from the
|
||||
editor if you still need it.
|
||||
|
||||
### YAML reference (for power users)
|
||||
|
||||
```yaml
|
||||
type: custom:perfectdraft-card
|
||||
device_id: "perfectdraft_pro"
|
||||
beer_name: "Leffe Blonde"
|
||||
glass_size: 330
|
||||
# beer_entity: sensor.perfectdraft_pro_keg_name # future: auto beer detection
|
||||
layout: landscape # landscape | portrait | compact | hero | vessel
|
||||
# matrix_columns: auto # "auto" or a fixed number of emoji columns
|
||||
# max_matrix_width: "480px" # cap + centre the emoji grid on wide cards
|
||||
# beer_overrides: # corrections keyed by keg product ID; normally unset
|
||||
# "1095": "Leffe Ruby" # applies only while that keg is tapped
|
||||
# custom_beers:
|
||||
# - name: "My Homebrew IPA"
|
||||
# brewery: "Home"
|
||||
@@ -64,10 +105,24 @@ glass_size: 330
|
||||
|
||||
| Action | What happens |
|
||||
|--------|-------------|
|
||||
| Tap the **left zone** (beer label) | Opens beer selection dialog |
|
||||
| Tap the **right zone** (emoji grid) | Opens glass size selection dialog |
|
||||
|
||||
Selections persist in your browser across page refreshes.
|
||||
The beer is detected rather than chosen, so the label zone is display-only. Your
|
||||
glass size choice persists in your browser across page refreshes.
|
||||
|
||||
## Layouts
|
||||
|
||||
Set `layout` (or pick it in the visual editor) to match where the card lives:
|
||||
|
||||
| Layout | Best for |
|
||||
|--------|----------|
|
||||
| `landscape` (default) | Wall panels (NSPanel Pro), wide cards — label left, emoji grid right |
|
||||
| `portrait` | Phones and tall/narrow columns — label on top, grid below |
|
||||
| `compact` | Dense dashboards — a single row with a remaining-beer bar |
|
||||
| `hero` | Showing off the beer — full-bleed keg photo with status overlaid |
|
||||
| `vessel` | A calm single glass that fills to show how much is left |
|
||||
|
||||
The emoji grid is width-tolerant: it shrinks to fit narrow cards instead of overflowing. Power users can force a column count with `matrix_columns` or cap/centre the grid with `max_matrix_width`.
|
||||
|
||||
## Supported glass sizes
|
||||
|
||||
@@ -88,6 +143,11 @@ The card reads these sensors from the PerfectDraft integration:
|
||||
| `*_temperature` | Beer temperature display |
|
||||
| `*_keg_remaining` | Glasses remaining calculation |
|
||||
| `*_keg_freshness` | Freshness warning system |
|
||||
| `*_keg_product` | Identifying the tapped beer (product ID match) |
|
||||
| `*_keg` | Identifying the tapped beer (name match fallback) |
|
||||
|
||||
The last two arrive with integration 0.4.0. If they are missing, the card tells
|
||||
you to update the integration instead of guessing at a beer.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
|
Before Width: | Height: | Size: 10 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 46 KiB |
|
Before Width: | Height: | Size: 16 KiB |
|
After Width: | Height: | Size: 35 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 35 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 31 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 23 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 27 KiB |
|
Before Width: | Height: | Size: 15 KiB |
|
After Width: | Height: | Size: 39 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 20 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 26 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 24 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 22 KiB |
|
After Width: | Height: | Size: 35 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 22 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 23 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 26 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 29 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 34 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 33 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 32 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 31 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 23 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 21 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 32 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 31 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 31 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 28 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 29 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 36 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 33 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 34 KiB |
|
Before Width: | Height: | Size: 12 KiB |
|
After Width: | Height: | Size: 24 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 25 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 24 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 27 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 28 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 26 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 26 KiB |
|
Before Width: | Height: | Size: 15 KiB |
|
After Width: | Height: | Size: 30 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 28 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 34 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 33 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 27 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 27 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 31 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 31 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 27 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 29 KiB |