Architecture

Language: English | Deutsch

Architecture — how the three GLP components work together

The GLP (Gaggiuino Local Profiler) ecosystem consists of three independent components that build on each other.

Overview

  Gaggiuino Machine
  └─ /api/shots          (shot history)
  └─ /api/system/status  (live brew data)
  └─ /api/system/info    (firmware version)
         │
         │  sync every N min + live polling during brew
         ▼
  ┌──────────────────────────────────┐
  │         GLP Add-on               │  ← HA add-on (this repo)
  │  Node.js server, port 8099       │
  │  stores shots in /data/          │
  │  REST API + web UI               │
  └────────┬─────────────────────────┘
           │                    ▲
           │  polls             │  HA Ingress (browser, authenticated)
           │  /api/status       │  port 8099 direct (integration, card)
           │  /shots.json       │
           │  /api/preheat      │
           │  /api/maintenance  │
           ▼                    │
  ┌─────────────────────┐       │
  │  GLP HA Integration │       │  ┌──────────────────────┐
  │  (custom component) │       └──│  GLP Lovelace Card   │
  │  creates sensors,   │          │  (custom card)       │
  │  fires HA events    │─────────►│  reads switch_entity │
  └─────────────────────┘  sensor  │  from machine_status │
           │               attrs   │  sensor attribute    │
           ▼                       └──────────────────────┘
    HA sensors, automations,
    energy monitoring, …

GLP Add-on

Repo: mxkissnr/gaggiuino-local-profiler

The central piece. It syncs shot history from the Gaggiuino machine, stores it locally in /data/shots.json, and serves:

• A web UI accessible via HA Ingress (the ☕ panel in the HA sidebar) — authenticated by HA
• A REST API on port 8099 consumed by the integration and the Lovelace card

The add-on also polls the machine's live status every second during a brew, accumulates datapoints, and saves the shot automatically once brewing stops.

GLP HA Integration

Repo: mxkissnr/gaggiuino-profiler-integration · Install via HACS

Polls the add-on every 60 s (configurable) and exposes all GLP data as native HA sensors:

Sensor	Description
sensor.glp_shot_count	Total number of shots stored
sensor.glp_shots_today	Shots pulled today
sensor.glp_last_shot_profile	Profile name of the last shot
sensor.glp_last_shot_score	Score (0–100) of the last shot
sensor.glp_last_shot_duration	Duration in seconds
sensor.glp_last_shot_weight	Yield in grams
sensor.glp_machine_status	online / error — also carries switch_entity as attribute
binary_sensor.glp_preheat_ready	true once preheat time has elapsed
sensor.glp_preheat_remaining	Seconds until machine is ready

Fires a gaggiuino_profiler_shot_completed event after each shot — use it to trigger automations.

GLP Lovelace Card

Repo: mxkissnr/glp-lovelace-card · Install via HACS

A custom Lovelace card showing machine status, last shot summary, preheat progress and a power button. It talks to port 8099 directly and reads switch_entity from the machine_status sensor attribute set by the integration — no manual configuration needed beyond the GLP URL.

API token

All three components authenticate automatically — no configuration required.

1. The add-on generates a random 64-character token at first start using crypto.randomBytes(32) (OS-level CSPRNG — no predictable pattern) and persists it in /data/api_token.txt.
2. /api/status is public and returns the token.
3. The browser UI and the integration read the token from /api/status on startup and include it as X-GLP-Token on all subsequent requests.
4. Requests via HA Ingress bypass the token check — HA already authenticated the user.

To rotate the token: delete /data/api_token.txt and restart the add-on.