ChillCheck 🌡️

Automatic fridge and freezer temperature records for food businesses.

Wireless probes sit in your fridges and freezers. A small computer on the premises logs every appliance at a fixed interval, flags anything outside your safe limits, and turns the whole lot into a printable Temperature Monitoring Record you can hand to an Environmental Health Officer.

No paper chart. No one forgetting the 9am check. No monthly subscription.

Probes in the appliances ──Zigbee──► USB stick ──► Zigbee2MQTT ──►  ChillCheck  ──► records + CSV
                                                  (on a small PC)   (same PC)          │
                                                                                       ▼
                                                                        optional copy on your own server

---

What it gives you

Live board	Every appliance on one screen, green or red at a glance
Automatic logging	A row per appliance every 15 min (or 1 min, or hourly — your call)
Breach flagging	Anything outside the limits you set is flagged, live and in the record
Printable record	A per-period Temperature Monitoring Record, ready to print or save as PDF
CSV export	The raw numbers, for your own files or your consultant
Sign-off	A named person attests each period; signed records build a permanent history
Keeps working offline	No internet needed. If you use the optional server, readings queue up and back-fill later
Password protected	Nothing is readable or changeable without signing in

---

Do I need to buy anything?

Depends what you already have. docs/BUY-LIST.md has the full shopping list with three starting points:

• Starting from nothing — about £170–£190 for a four-appliance setup.
• You already run Home Assistant / Zigbee2MQTT — just buy probes (~£20 each). ChillCheck talks to the MQTT broker you already have.
• You already have a spare Pi or mini PC — buy the USB stick and probes.

It works with any temperature sensor that Zigbee2MQTT supports — Sonoff, Aqara, Tuya, whatever you can get hold of. It also works with any other device that publishes temperature to MQTT (ESPHome, Tasmota, Shelly). Nothing is hard-coded to one brand.

---

Try it in 2 minutes, before buying anything

This runs the whole app with five invented sensors, so you can see exactly what you would be getting. No hardware, no broker, no risk.

git clone https://github.com/PrimroseHA/chillcheck.git
cd chillcheck
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
SIMULATE=1 .venv/bin/python app.py

Open http://localhost:5005. The terminal prints a one-off password — paste it in. Name a monitoring period, add a couple of appliances, assign the fake sensors, and watch it log.

---

Setting it up for real

🤖 You can hand the whole install to Claude. Put Claude Code on the machine with curl -fsSL https://claude.ai/install.sh | bash, then paste a prompt from docs/CLAUDE-PROMPTS.md — there's one for a fresh Pi, one for an existing Home Assistant setup, one for the server, and one that works out what to buy. It runs the commands itself.

Two halves. The second one is optional.

1. On the premises — required

The bit that reads the probes and keeps the record. 👉 docs/INSTALL-PI.md

2. On a server — optional

A second copy of every reading, off site, plus the printable records and the signed-off history. Worth it if you want the record to survive the on-site device being stolen, flooded or wiped. 👉 docs/INSTALL-SERVER.md — covers Plesk, cPanel, plain nginx/Apache, and Docker.

Skip it and everything still works; the record just lives on the one device.

Then

👉 docs/DAILY-USE.md — what staff actually do, and what to hand an inspector. 👉 docs/SECURITY.md — what's protected and how to change a password. 👉 docs/MORE-FROM-THE-PI.md — the same box and the same Zigbee network will also do allergen labels, menu screens, leak and door-open alerts, and out-of-hours security.

Stuck at any point? docs/CLAUDE-PROMPTS.md has copy-and-paste prompts for Claude (or any AI assistant) that do the whole install, diagnose common faults, and adapt the app to your setup.

---

Configuration

Everything lives in a .env file that the installer writes for you. Full list of settings in .env.example and server/.env.example. The ones people change:

Setting	Default	What it does
SITE_NAME	ChillCheck	Your business name, shown in the app and on printed records
MQTT_HOST	127.0.0.1	Where your sensors publish. Point at an existing Home Assistant box if you have one
LOG_INTERVAL	900	Seconds between log rows (900 = every 15 min)
DEFAULT_MAX_TEMP	5	Default upper limit for a new appliance; set real limits per appliance in the UI
CLOUD_URL	(empty)	Off-site back-up. Empty = everything stays on this device

---

Testing

No hardware needed:

bash tests/run.sh

52 checks covering sign-in, CSRF, recording, breach detection, CSV export, token-authenticated ingest, idempotent back-fill, roles and sign-off.

---

Good to know

• Run a single worker on site. The MQTT subscriber and the logger are in-process threads sharing one store, so the service uses gunicorn -w 1. More workers would log every reading twice. The installer handles this.
• Probe placement matters more than anything else. Radio does not escape a closed metal cabinet. Use probes on a lead: tip inside, body and aerial outside. This is the single most common reason these systems "stop working".
• Deleting an appliance never rewrites history. Each reading stores its own copy of the name and limits at the time it was taken.
• This is a monitoring aid, not a calibrated instrument. Typical probe accuracy is ±0.5 °C. Keep doing whatever manual verification your food safety management system requires, and check probes annually against a reference thermometer. See docs/DAILY-USE.md.

Licence

MIT — see LICENSE. No warranty; you are responsible for your own food safety compliance.