Build Reliable ESP32 Home Automation Projects: MQTT Relay Controller

When building ESP32 home automation projects, reliability is the difference between a fun weekend hack and a system you actually trust to run your lights and HVAC. This guide walks through building a robust, MQTT-driven 4-channel relay controller. We are targeting the standard ESP32-WROOM-32 DevKit V1 (30-pin). It handles local WiFi dropouts gracefully, isolates your low-voltage logic from mains switching, and integrates directly with Home Assistant via MQTT.

Hardware BOM and Pin Mapping

The most common failure point in ESP32 home automation projects is driving 5V relay coils directly from 3.3V GPIO pins, which causes brownouts or fried silicon. We use a 3.3V-native opto-isolated relay module to eliminate level-shifting headaches and protect the microcontroller from inductive kickback.

Wiring the Mains and Low-Voltage Control

1. Prepare the Power Supply: Solder insulated 18 AWG pigtails to the AC input pins of the HLK-PM01. Route these through a 5A fast-blow fuse holder and a terminal block. The HLK-PM01 lacks internal overcurrent protection on the AC side; never wire it directly to mains without upstream fusing.
2. Low-Voltage Distribution: Connect the 5V DC output of the HLK-PM01 to the AMS1117-3.3 input. Route the 5V rail to the JD-VCC pin on the relay module. Critical step: Remove the VCC/JD-VCC jumper on the relay board to maintain true optical isolation. If you leave it in, mains transients can backfeed into your 3.3V logic rail and reset the ESP32.
3. Control Signal Routing: Run 22 AWG jumper wires from ESP32 GPIO 25, 26, 27, and 14 to the relay module's IN1, IN2, IN3, and IN4 pins. Connect ESP32 GND to the relay module's GND.
4. Mains Switching: Wire your AC Line (Hot) to the Common (COM) terminal of each relay. Wire the Normally Open (NO) terminal to the load. Keep AC wiring physically separated from the low-voltage DC wires by at least 1/4 inch inside the enclosure to prevent capacitive coupling and EMI.

Complete MQTT Control Firmware

The following C++ code targets the ESP32-WROOM-32 using the Arduino core. It uses the PubSubClient library. It includes non-blocking WiFi/MQTT reconnection loops and explicit pin state tracking to prevent out-of-sync Home Assistant toggles.

#include <WiFi.h>
#include <PubSubClient.h>

// --- PIN DEFINITIONS ---
#define RELAY_1 25
#define RELAY_2 26
#define RELAY_3 27
#define RELAY_4 14
const int relayPins[] = {RELAY_1, RELAY_2, RELAY_3, RELAY_4};

// --- NETWORK & MQTT CONFIG ---
const char* ssid = "YourNetworkSSID";
const char* password = "YourNetworkPassword";
const char* mqtt_server = "192.168.1.50";
const int mqtt_port = 1883;
const char* mqtt_user = "mqtt_user";
const char* mqtt_pass = "mqtt_pass";

WiFiClient espClient;
PubSubClient client(espClient);

String topicBase = "home/lights/esp32_01/relay_";

void setup_wifi() {
  delay(10);
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
  }
}

void callback(char* topic, byte* payload, unsigned int length) {
  String inTopic = String(topic);
  String message = "";
  for (int i = 0; i < length; i++) message += (char)payload[i];

  for (int i = 0; i < 4; i++) {
    if (inTopic == topicBase + String(i + 1) + "/set") {
      if (message == "ON") digitalWrite(relayPins[i], HIGH);
      else if (message == "OFF") digitalWrite(relayPins[i], LOW);
      
      // Publish state back to confirm
      client.publish((topicBase + String(i + 1) + "/state").c_str(), message.c_str(), true);
    }
  }
}

void reconnect() {
  while (!client.connected()) {
    String clientId = "ESP32_HomeAuto_01";
    if (client.connect(clientId.c_str(), mqtt_user, mqtt_pass)) {
      for (int i = 0; i < 4; i++) {
        client.subscribe((topicBase + String(i + 1) + "/set").c_str());
      }
    } else {
      delay(5000); // Wait 5 seconds before retrying
    }
  }
}

void setup() {
  Serial.begin(115200);
  for (int i = 0; i < 4; i++) {
    pinMode(relayPins[i], OUTPUT);
    digitalWrite(relayPins[i], LOW); // Start OFF
  }
  setup_wifi();
  client.setServer(mqtt_server, mqtt_port);
  client.setCallback(callback);
  client.setKeepAlive(60); // Prevent timeout drops
}

void loop() {
  if (!client.connected()) reconnect();
  client.loop();
}

Debugging Common ESP32 MQTT Failures

When your ESP32 home automation projects fail to communicate, the serial monitor is your best diagnostic tool. Here are the exact error strings and how to fix them.

1. "MQTT connect failed, rc=-2"

This is the most common PubSubClient error. The rc=-2 code specifically means the network connection was refused or timed out.

• Cause A (Most Likely): Incorrect MQTT broker IP or port. Verify your Home Assistant MQTT broker is actually running on 192.168.1.50:1883 and not using SSL (which requires port 8883 and a different library like WiFiClientSecure).
• Cause B: Broker rejected the credentials. Check mqtt_user and mqtt_pass in the code against your broker's ACL (Access Control List).
• Cause C: The ESP32 hasn't fully associated with the WiFi router before attempting the MQTT handshake. Add a 2-second delay after WiFi.begin() succeeds.

2. "Guru Meditation Error: Core 1 panic'ed (Interrupt wdt timeout on CPU1)"

This fatal crash happens when a blocking function starves the RTOS watchdog timer.

• Cause A: Using delay() inside the main loop() or blocking the while(!client.connected()) loop without yielding. The code provided above uses a non-blocking 5-second delay strategy, but if you add sensor reads, ensure you use millis() timing.
• Cause B: I2C bus lockup. If you add an I2C sensor (like a BME280) later and the SDA line gets pulled low, the Wire library will hang indefinitely, triggering the watchdog.

Scaling Your ESP32 Home Automation Projects

Once you have a single 4-channel node running reliably, you will inevitably want to expand. Here is how to scale the architecture without rewriting your core firmware, along with a comparison of when to stick with raw C++ versus switching to a managed framework.

Extending the Build: MQTT Auto-Discovery

Manually writing Home Assistant YAML for every new ESP32 relay gets tedious fast. You can extend the firmware to broadcast MQTT Discovery configuration payloads on boot. By publishing a retained JSON message to homeassistant/switch/esp32_01_relay1/config containing the device name, unique ID, and command topics, Home Assistant will automatically create the switch entities in your dashboard without a single line of YAML.

Simplifying the Build: Raw C++ vs ESPHome

If you realize you don't need custom C++ logic (like complex local PID temperature control or proprietary RF decoding), simplify your stack by switching to ESPHome. ESPHome uses a YAML-based configuration that compiles to optimized C++ under the hood. Use raw Arduino C++ only when you need to integrate unsupported hardware libraries or minimize footprint on memory-constrained boards.