Build Guide + Upgrade Log

Pi Kiln Controller (TheKilnGod)

This is my practical guide for building a kiln controller from the Bruce lineage and moving to TheKilnGod. I use this page as a living reference for hardware, setup, upgrades, and future improvements.

Project Links

Why Start From TheKilnGod

If you are deciding where to begin, this is the best starting point because it keeps the familiar kiln-control workflow while adding modern architecture, better safety behavior, stronger telemetry, and active improvements to connectivity and UI.

  • 2023+ backend rewrite with clearer runtime separation (kiln-controller.py + lib/oven.py)
  • Blinka-oriented hardware support beyond Raspberry Pi
  • Expanded controls: seek_start, catch-up, auto-restart, min_on_time, low-temp throttling
  • Run-health tracking and trend analysis for long-term kiln behavior
  • Optional tokens for monitor/control API hardening
  • Legacy UI improvements plus React/Vite UI v2 at /v2

1. What Stayed Familiar

Core workflow continuity from the Bruce baseline.

  • Profile-based firing schedules
  • Browser-based control and monitoring
  • PID-driven control loop model
  • Local-network deployment on small Linux hosts

2. Biggest Upgrades I Kept

Why this branch is a better long-term base.

  • MAX31855 and MAX31856 support with broad thermocouple type options
  • Run-health metrics (within_5deg_pct, switches_per_hour, overshoot_max, and more)
  • MQTT/Home Assistant integration and optional ntfy notifications
  • Optional OLED runtime display and passive piezo buzzer feedback

3. UI Direction

Two usable paths today.

  • Legacy UI: stable and expanded with schedule builder quality-of-life updates
  • UI v2: React + TypeScript + Vite dashboard with health trends and event timeline
  • UI v2 serves from public/v2 and opens at /v2

4. Safety Notes

Do not skip this section during build.

  • Emergency shutoff and thermocouple fault handling are configurable in config.py
  • Use a properly sized zero-cross SSR plus heatsink/fan where needed
  • Keep mains switching external to controller logic board
  • Verify local electrical code compliance before live firing

5. Migration Checklist

Bruce to TheKilnGod sanity check.

  • GPIO map and output inversion settings
  • SPI mode and thermocouple board configuration
  • Service/startup paths and system user
  • Monitor/control tokens if auth is enabled
  • Legacy UI path and v2 build path validation

6. Why This Is Future-Proof

What makes this a strong ongoing platform.

  • No heavy infrastructure required (single-host, file-based persistence)
  • Proven on low-power Pi hardware with simulation mode for safer changes
  • Active docs for API, run health, migration, and troubleshooting
  • Easy to keep evolving without rewriting safety-critical core logic from scratch

Parts To Buy

Recommended starter set for a practical build:

  • Controller host: Raspberry Pi (or another Blinka-supported board with SPI + network)
  • Thermocouple board: Adafruit MAX31855 or MAX31856 breakout
  • Thermocouple probe: kiln-rated probe matched to your board/type
  • Power switching: zero-cross SSR sized for kiln load, plus heatsink
  • Wiring/prototyping: breadboard or controller PCB, jumpers, terminals, GPIO header cable
  • Controller enclosure: non-conductive enclosure with strain relief and airflow management
  • Safety hardware: inline fusing, disconnect method, and emergency-stop/interlock path
  • Optional upgrade: SSD1309 OLED display (I2C)
  • Optional upgrade: passive piezo buzzer on GPIO 12
  • Optional upgrade: 5V SSR cooling fan and fan driver path

Build Steps (Practical Order)

  1. Assemble hardware with SSR control, thermocouple board, and clean grounding.
  2. Install Raspberry Pi OS, clone repo, create venv, and install requirements.
  3. Set config.py (or secrets.py) for pins, thermocouple type, units, safety limits, and tokens.
  4. Enable SPI (and I2C if using OLED) using raspi-config.
  5. Run hardware tests: ./test-thermocouple.py, ./test-output.py, and optional display tests.
  6. Start controller and validate web UI run/pause/resume/stop paths.
  7. Test simulation and low-temp live profile before full firing profiles.
  8. Review logs and run-health trends after each firing, then tune and iterate.

Connectivity Upgrades I Use

  • Home Assistant MQTT publishing for kiln status and temperature entities
  • Optional notifications pipeline (lib/notifications.py)
  • Watcher patterns for out-of-range conditions and fault visibility
  • Monitor/control token separation for safer network exposure

UI Upgrades I Use

  • Legacy schedule builder improvements for quick profile authoring
  • UI v2 dashboard for cleaner telemetry visibility and timeline context
  • Run-health trend panel with run inclusion/exclusion control
  • Profile preflight checks and better control-state UX patterns

Image Requests / Placeholders

Controller enclosure and wiring layout photo.
UI v2 dashboard screenshot with health trend panel.
Comparison diagram (Bruce baseline vs TheKilnGod architecture).
Parts flat-lay photo with labels (Pi, thermocouple board, SSR, probe, OLED, buzzer).

Recommended Docs To Keep Handy

Upgrade Log Template

Use one entry per meaningful change:

  • Date: YYYY-MM-DD
  • Area: Hardware / Safety / Connectivity / UI / API / Telemetry
  • Change: What I changed
  • Reason: Why I changed it
  • Result: What improved (or regressed)
  • Follow-up: Next test or next action