Coffee Roasting with Hottop KN-8828B-2K+

Roast analysis tool for the Hottop KN-8828B-2K+ connected to Artisan. Analyzes .alog roast logs, looks up bean profiles, compares metrics against targets, and gives you actionable recommendations for the next roast.

After a Roast

Artisan logs auto-sync from the roaster to roast-logs/ via inotifywait + rsync (see log-sync/ for the watcher scripts and systemd service). Then:

run_roast-analyzer analyze.py full

This scans for new log files, shows a summary of the latest roast, compares it to targets, prints recommendations with a priority legend, and ends with a "Next Roast" box telling you exactly what to change.

Setup

Requires Python 3.10+ and uv:

uv sync

All commands run through the wrapper script (handles secrets):

run_roast-analyzer analyze.py <command>

Optional integrations (configured via env vars in the wrapper script):

Env var	Purpose
FIND_COFFEE_URL	find-coffee API URL for bean profile lookup
FIND_COFFEE_WRAPPER	Path to run_find-coffee script (auto-starts the server if needed)
SENTINEL_CAPTURES_DIRS	Colon-separated paths to r1-eye/GoPro capture directories for visual scoring

All three are optional — features are silently skipped when unset.

Commands

Command	What it does
full [id]	Scan + full report (summary, bean profile, targets, recommendations, next roast, trend)
full [id] -v	Same, with full professional cupping notes
full --force	Re-analyze all files first
scan	Ingest new .alog files into history
scan --force	Re-analyze everything from scratch
show [id]	Roast summary (temps, times, phases, RoR)
compare [id1 id2]	Side-by-side comparison of two roasts
recommend [id] [-v]	Target comparison + recommendations + next roast actions
list	All analyzed roasts with batch number, date, bean, metrics
cupping <id> -n "notes"	Attach tasting notes to a roast
cupping <id>	View existing cupping notes
bean <name>	Look up a bean in find-coffee

All commands use run_roast-analyzer analyze.py <command>.

Picking a Roast by ID

Most commands accept an optional roast identifier:

• Batch number — 3 (simplest, from list)
• Partial name — ethiopia (case-insensitive match)
• Full roast ID — 3_Ethiopia Gerba Hechere_2026-02-21

If you don't specify an ID, the command uses the latest roast.

What the Output Looks Like

Recommendations are prioritized:

• [!!!] — fix this first
• [ ! ] — worth improving
• [ ] — info

Phase Breakdown and Target Comparison show each phase's raw time and RoR next to the percentage — e.g. Drying: 61.6% (8:30 @ 26.8 F/min) — so you can tell whether a high drying % is coming from a long phase or a short total time.

CHARGE warning: if charge_bt wasn't recorded (missed/late CHARGE press), a warning line appears in the summary so you know to mark CHARGE manually next roast.

Next Roast box gives 2-4 concrete action items distilled from the analysis (e.g., "Charge hotter", "Hold heat steady longer between cuts").

Trend table shows key metrics across all roasts so you can see progress.

Visual Data

If the r1-eye or GoPro sentinel was running during the roast, visual development data (color scoring, uniformity) is automatically included in the analysis. No extra steps — just run full --force after sentinel captures have synced.

Sentinel sessions are linked to .alog files by UUID when Artisan's OFF button is configured to send send({"event": "OFF"}) via WebSocket. This triggers the sentinel to read the .alog that Artisan just saved and embed the roastUUID for deterministic matching. Without OFF configured, matching falls back to date/time.

Reference

• Hottop manuals: download from Hottop USA and place in reference/
• Roast logs: auto-synced from roaster to roast-logs/ (gitignored); see log-sync/ for setup
• Technical details: CLAUDE.md