Local-LLM Home Controller using ESP32, MQTT and Ollama

Cloud voice assistants can switch home appliances on and off, but they are black boxes: sensor data leaves the house for remote servers, they need accounts and subscriptions, and they never say why they did anything. At the other extreme, most student IoT demos are threshold switches — an ESP32 flipping a relay at 30 °C — which cannot reason or explain. Neither teaches how modern edge-AI systems are actually architected: a fast, reliable real-time layer plus a slower, smarter supervisory layer on top. This project builds exactly that split. The ESP32 does the sensing and actuating with hard safety rules baked into its firmware, while a Python agent on the student's laptop consults a locally hosted LLM (Ollama, e.g. Llama 3.1:8b) that proposes actions and justifies each one in plain language. The student sees the full agentic-IoT loop — sense, publish, reason, command, acknowledge — with every decision explained in a timestamped log.

1. The DHT22 measures room temperature and humidity; the ESP32 publishes readings over Wi-Fi to local MQTT topics (home//state) on a 5-second cadence.
2. The Python agent on the laptop subscribes to these topics and builds a prompt with current readings, relay states, time of day and house rules.
3. The local Ollama model (e.g. Llama 3.1:8b) replies with a proposed action plus a justification — supervisory, taking seconds, never real-time control.
4. The agent forwards allowed actions as MQTT set-commands (home/relay//set); the ESP32 applies them only if its own safety rules permit, then acknowledges (.../ack).
5. Every decision, its justification and its latency appear in the dashboard's agent decision log in real time.
6. Blocked requests (e.g. heater ON at 27.8 °C) are refused by the agent with the contradicting reading; unsafe states (60 °C cut-off) are handled by ESP32 rules regardless of the LLM.
7. If Wi-Fi or the laptop drops, the ESP32 falls back to rule-based control on its own until the agent reconnects.

Tech stack:

• ESP32 (Arduino C/C++ firmware)
• MQTT via Mosquitto broker (local)
• Python 3 with paho-mqtt (agent)
• Ollama with Llama 3.1:8b (local LLM)
• DHT22 temperature/humidity sensor
• 4-channel relay module
• HTML5 + CSS + JavaScript dashboard
• Arduino IDE

• [Honest edge-plus-AI split] The ESP32 handles sensing and relay actuation with rule-based safety in firmware; the laptop runs the Mosquitto broker, Python agent and Ollama LLM. The LLM is supervisory only — it advises, the edge decides.
• [Explained decisions, not black-box actions] Every agent action lands in the dashboard decision log with its plain-language justification (e.g. "fan on: 29.4 °C with 68% humidity") and the measured LLM round-trip time.
• [Safety rules the LLM cannot override] Max-ON timers, a 500 W power ceiling and a 60 °C fire cut-off are enforced on the ESP32. Blocked or held actions are logged with their reasons.
• [Fully local, no cloud] Broker, agent and LLM all run on the student's own network. No accounts, no API keys, no sensor data leaving the home — Ollama needs the model downloaded once.
• [Live telemetry dashboard] Single-file HTML dashboard showing temperature/humidity sparklines, relay states, MQTT topic activity and the agent log — genuinely working, fed by the same topics as the hardware.
• [Graceful degradation] If the laptop or Wi-Fi drops, the ESP32 keeps running its rule-based control standalone; the agent simply resumes when connectivity returns.
• [Natural-language control] The student can ask for actions in plain words; the agent checks them against live sensor readings and refuses with an explanation when the request contradicts conditions.

• Working ESP32 prototype (sensor node + relay board, wired and labeled)
• ESP32 firmware source (sensing, MQTT, relay control, safety rules)
• Python agent code (MQTT glue + Ollama prompting + decision parsing)
• Mosquitto broker setup guide for the laptop
• Working single-file HTML dashboard
• Circuit/wiring documentation and component list
• Project report PDF (architecture, methodology, safety design)
• PPT presentation for final review
• Viva Q&A preparation document (MQTT, edge vs supervisory control, local LLMs)

• LLM decisions take seconds (design target ~2–6 s) — the LLM is a supervisory layer, not real-time control; time-critical safety always lives in ESP32 firmware rules.
• The laptop must stay on and on the same Wi-Fi network for the agent and LLM to work; without it, only rule-based ESP32 control runs.
• DHT22 readings follow the sensor's datasheet accuracy (±0.5 °C, ±2–5% RH) and need ~2 s between reads; it is not a precision instrument.
• Ollama needs a one-time model download (several GB) and a laptop with enough RAM for the chosen model; smaller models trade decision quality for speed.
• Relay contacts are rated for the module's printed specification — mains wiring must be done carefully and is demonstrated with low-voltage test loads in the classroom setup.
• The LLM can misread ambiguous requests; the agent validates every action against live readings and the ESP32 rules are the final authority.