Mastering the ESP8266 Scheduler: Non-Blocking Tasks and WDT Fixes

The ESP8266 is a single-core 80MHz (or 160MHz overclocked) microcontroller that handles your application code and the underlying TCP/IP WiFi stack on the same core. When you block the main execution loop with a delay() or a long-running while() loop, the WiFi stack starves. The hardware watchdog timer (WDT) assumes the chip has locked up and forces a reboot. Implementing a proper ESP8266 scheduler replaces blocking delays with cooperative multitasking, ensuring your sensors, network uploads, and the RF radio all get CPU time.

Scheduling Methods Compared: Why TaskScheduler Wins

Before writing code, you need to choose the right concurrency model. The native Arduino loop() is technically a scheduler, but it relies on the programmer to manually manage state machines. Here is how the four primary scheduling approaches on the ESP8266 compare in real-world overhead and limitations.

For standard Arduino IDE workflows, Arkhipenko’s TaskScheduler library provides the best balance. Unlike Ticker.h, which fires in an interrupt context (where calling Wire.requestFrom() or WiFiClient.print() will instantly crash the chip), TaskScheduler runs in the main loop context. It cooperatively yields to the ESP8266 background RF tasks, preventing watchdog resets while allowing you to use blocking I2C and network libraries safely.

Hardware BOM and Pin Mapping

This build uses an I2C environmental sensor to demonstrate how to schedule a slow bus read without stalling the WiFi connection. We are targeting the NodeMCU v3 (ESP-12F) variant, which features 4MB of flash and breaks out GPIO4 and GPIO5 to the D2 and D1 silkscreen pins, respectively.

Implementing the TaskScheduler: Complete Code

The following code initializes three distinct tasks: a fast LED heartbeat (500ms), a medium-speed sensor read (5 seconds), and a slow WiFi telemetry upload (30 seconds). By decoupling these intervals, a delayed WiFi DNS resolution will not prevent the sensor from reading or the heartbeat from blinking.

#include <ESP8266WiFi.h>
#include <Wire.h>
#include <Adafruit_BME280.h>
#include <TaskScheduler.h>

// --- Pin Definitions ---
#define PIN_I2C_SDA 4   // NodeMCU D2
#define PIN_I2C_SCL 5   // NodeMCU D1
#define PIN_LED     2   // NodeMCU D4 (Built-in LED, Active LOW)

// --- Network Credentials ---
const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";

// --- Task Declarations ---
Scheduler runner;
void taskHeartbeat();
void taskReadSensor();
void taskUploadData();

Task tHeartbeat(500, TASK_FOREVER, &taskHeartbeat);
Task tReadSensor(5000, TASK_FOREVER, &taskReadSensor);
Task tUploadData(30000, TASK_FOREVER, &taskUploadData);

// --- Globals ---
Adafruit_BME280 bme;
float lastTempC = 0.0;
float lastHum = 0.0;
bool sensorReady = false;
bool ledState = false;

void setup() {
  Serial.begin(115200);
  pinMode(PIN_LED, OUTPUT);
  digitalWrite(PIN_LED, HIGH); // LED OFF (Active LOW)

  // Initialize I2C with explicit pins
  Wire.begin(PIN_I2C_SDA, PIN_I2C_SCL);
  
  // Error Handling: Sensor Init
  if (!bme.begin(0x76)) { // Try 0x76, fallback to 0x77 if needed
    if (!bme.begin(0x77)) {
      Serial.println(F("[FATAL] BME280 not found. Check I2C wiring."));
      // Disable sensor and upload tasks if hardware is missing
      tReadSensor.disable();
      tUploadData.disable();
    }
  } else {
    sensorReady = true;
  }

  // Connect to WiFi (Non-blocking approach would use WiFi events, 
  // but for setup, a brief blocking wait with yields is acceptable)
  WiFi.begin(ssid, password);
  Serial.print("Connecting to WiFi");
  int timeout = 0;
  while (WiFi.status() != WL_CONNECTED && timeout < 40) {
    delay(250); // Acceptable ONLY in setup()
    Serial.print(".");
    timeout++;
    yield(); // Feed the watchdog
  }
  
  if (WiFi.status() == WL_CONNECTED) {
    Serial.println("\nWiFi Connected.");
  } else {
    Serial.println("\nWiFi Failed. Upload task will retry later.");
  }

  // Initialize Scheduler
  runner.init();
  runner.addTask(tHeartbeat);
  runner.addTask(tReadSensor);
  runner.addTask(tUploadData);
  
  tHeartbeat.enable();
  if (sensorReady) {
    tReadSensor.enable();
    tUploadData.enable();
  }
}

void loop() {
  // The scheduler handles all execution. Never put blocking code here.
  runner.execute();
}

// --- Task Callbacks ---

void taskHeartbeat() {
  ledState = !ledState;
  digitalWrite(PIN_LED, ledState ? LOW : HIGH);
}

void taskReadSensor() {
  // I2C reads can take 10-20ms. TaskScheduler handles this gracefully.
  lastTempC = bme.readTemperature();
  lastHum = bme.readHumidity();
  Serial.printf("[SENSOR] Temp: %.2f C | Hum: %.2f %%\n", lastTempC, lastHum);
}

void taskUploadData() {
  if (WiFi.status() != WL_CONNECTED) {
    Serial.println("[NET] WiFi disconnected. Skipping upload.");
    return;
  }
  
  WiFiClient client;
  // Example: Connect to a local server on port 8080
  if (client.connect("192.168.1.100", 8080)) {
    String payload = String("GET /data?temp=") + lastTempC + "&hum=" + lastHum + " HTTP/1.1\r\nHost: 192.168.1.100\r\n\r\n";
    client.print(payload);
    Serial.println("[NET] Telemetry uploaded.");
    client.stop();
  } else {
    Serial.println("[NET] Upload failed.");
  }
}

Debugging: Fixing the "Soft WDT reset" Crash

If your ESP8266 reboots unexpectedly and dumps the following stack trace to the Serial Monitor, your scheduler has failed to yield to the background RF stack:

Soft WDT reset
ctx: cont
sp: 3ffffd90 end: 3fffffc0 offset: 01a0
>>>stack>>>
3ffffdf0: 40201b2c 3ffe84e8 3ffe8c80 40202c18
3ffffe00: 40201a54 3ffe84e8 3ffe8c80 40202c18

According to the ESP8266 Arduino Core Documentation, the software watchdog timer resets the chip if the main loop fails to call yield() or delay() (which implicitly yields) for more than 3.2 seconds. Here are the ranked causes and how to fix them.

Ranked Causes for WDT Resets

1. Hidden delay() Calls: You placed a delay(5000) inside a task callback or the main loop to "space out" network requests. Fix: Replace with a TaskScheduler interval.
2. I2C Clock Stretching: A slow sensor (like an SHT31 or BME280 waking from sleep) holds the SCL line low, freezing the Wire library indefinitely. Fix: Add 4.7kΩ pull-ups and ensure the sensor is fully initialized before the first read.
3. DNS Resolution Blocking: Using WiFiClient.connect("api.example.com", 443) forces the ESP8266 to perform a blocking DNS lookup, which can take up to 5 seconds on congested networks, tripping the WDT. Fix: Use static IP addresses for local servers, or implement asynchronous DNS resolution.

The First Three Things to Check

When this crash hits your bench, execute this diagnostic sequence:

1. Search your codebase for delay(: Use your IDE’s "Find in Files" feature. The only acceptable place for delay() is inside setup() during initial hardware initialization. If it exists in loop() or any task callback, delete it.
2. Verify runner.execute() isolation: Look at your loop() function. It should contain exactly one line of executable code: runner.execute();. If you have custom if() statements or while() loops wrapping the scheduler, you are starving the WiFi stack.
3. Measure I2C idle voltage: Set your multimeter to DC Voltage. Probe the SDA and SCL lines relative to GND. Both should read a stable 3.2V to 3.3V. If either reads below 2.5V, your pull-up resistors are missing or too weak, causing the I2C bus to hang and block the CPU.

Extending and Simplifying the Build

The modular nature of a software scheduler makes it trivial to scale the project up for production or strip it down for ultra-low-power battery operation.

How to Extend (Adding MQTT and OTA)

To upgrade this build to a production IoT node, replace the HTTP WiFiClient task with the PubSubClient MQTT library. Because MQTT requires a frequent keep-alive ping, add a fourth task:

Task tMqttLoop(100, TASK_FOREVER, &taskMqttLoop);

void taskMqttLoop() {
  if (mqttClient.connected()) {
    mqttClient.loop(); // Handles keep-alives and incoming messages
  }
}

Running the MQTT loop every 100ms ensures incoming commands are processed instantly without blocking the 5-second sensor reads. You can also add the ArduinoOTA library, placing ArduinoOTA.handle() inside a 50ms task to enable wireless firmware updates over the air.

How to Simplify (Deep Sleep Battery Nodes)

If you are powering this ESP8266 from a 18650 lithium cell and need months of battery life, a continuous scheduler is the wrong tool. The ESP-12F draws ~80mA while awake. Instead, simplify the build to use Deep Sleep:

1. Remove the TaskScheduler library entirely.
2. In setup(), read the sensor, connect to WiFi, upload the data, and immediately call ESP.deepSleep(300e6); (300 seconds).
3. Wire the D0 (GPIO16) pin directly to the RST pin on the NodeMCU. This is mandatory; without this physical jumper, the chip will sleep forever and require a manual button press to wake.

By understanding when to use a cooperative ESP8266 scheduler versus when to leverage hardware sleep states, you can optimize both the CPU utilization and the power envelope of your embedded designs.