Build an ESP32 Filament Jam and Runout Monitor with Phone Alerts for Klipper Printers

A failed print caused by a filament jam or an empty spool wastes hours and material, and it often makes a mess of the hotend. Many Klipper printers already support filament sensors directly, but a stand-alone ESP32 monitor is useful when the sensor is on a printer without spare controller pins, when you want alerts on your phone, or when you want one monitor to watch several machines. This project reads a filament motion sensor, asks Moonraker whether the printer is actually printing, and pauses the print and sends a notification if filament stops moving.

How It Works

A motion sensor has two signals: a switch that reports whether filament is present, and a pulse output that toggles as the filament moves through it. The ESP32 counts pulses. Every few seconds it queries Moonraker's HTTP API for the print state. If the printer reports "printing" but no pulses have arrived for a set time while filament is present, that is a jam, a tangle or a stripped filament, and the ESP32 acts. If the presence switch reports no filament, that is a runout.

Safety

This project uses low-voltage electronics only. Do not mount anything near the hotend heat block. Keep wiring away from moving parts and use strain relief at the printer's toolhead. An automated pause does not replace a fire-safe setup, so never leave a printer unattended with only this as protection, and check the operating voltage of your particular sensor before connecting it to the 3.3 V logic on the ESP32.

Wiring

Sensor / partESP32 pinNotes Sensor pulse outputGPIO 27 (input with pull-up)Check the sensor's output voltage; use a level shifter or divider if it is 5 V Sensor filament switchGPIO 26 (input with pull-up)Normally closed or open depending on model, set in code BuzzerGPIO 25Through a transistor if it draws more than about 20 mA Status LEDGPIO 2 with resistorOr use the on-board LED Sensor power3V3 or 5V pinMatch the sensor's rated voltage GroundGNDCommon ground with the sensor

Build Steps

1. Print the mount. Mount the sensor along the filament path between the spool and the extruder, ideally on the printer frame just above the extruder, in PETG or ASA. Keep the filament path straight through the sensor so it does not add drag.
2. Wire the sensor. Use a JST connector so the sensor can be disconnected. Keep the cable short and tidy, and twist signal and ground wires together to reduce noise.
3. Flash the ESP32. Use the Arduino IDE with the ESP32 board package. Include WiFi, HTTPClient and ArduinoJson.
4. Attach an interrupt to the pulse pin that increments a counter, and record the time of the last pulse.
5. Poll Moonraker every 2 to 5 seconds with a GET request to /printer/objects/query?print_stats to read the state. Only enable jam detection while the state is "printing".
6. Set the jam timer. If no pulse arrives for 15 to 30 seconds while printing and the filament switch reports present, treat this as a jam. Slow or tiny moves, such as retractions and thin-wall segments, mean short periods with no motion, so do not set the timeout too low.
7. Respond. Send a POST request to /printer/print/pause on Moonraker, sound the buzzer, and send a notification, for example to ntfy.sh, Home Assistant or a Telegram bot.
8. Ignore first moves. Give a grace period after a print starts and after filament changes.

Configuration Tips

SettingSuggested startReason Poll interval3 sFast enough without flooding Moonraker Jam timeout20 sAvoids false alarms on slow features Startup grace60 sPriming and purge lines have irregular extrusion Runout debounce2 sIgnores switch bounce Wi-Fi retryEvery 10 sRecover if the router restarts

Testing

1. With the printer idle, pull filament through by hand and confirm the pulse counter changes.
2. Start a print and confirm the ESP32 reports "printing" and pulse counts rise.
3. Hold the filament stationary during a test print, or pinch it before the extruder, to simulate a jam. Confirm the pause command works.
4. Remove the filament to test the runout alert.
5. Unplug the router to confirm the ESP32 reconnects without needing a reset.

Troubleshooting

ProblemCauseFix False jam alertsTimeout too short or filament not driving the sensor wheelIncrease timeout, check the sensor's contact with the filament No pulses at allWrong pin or voltage levelCheck wiring with a multimeter and the sensor's datasheet Pause command failsWrong Moonraker address or trusted clients settingAdd the ESP32's IP to Moonraker's trusted clients ESP32 resets randomlyWeak power supplyUse a good 5 V adapter and short cable

Upgrades

Add an OLED to show filament status, add an MQTT publish so Home Assistant can log jams, or use several sensors with one ESP32 to monitor multi-material setups. Because Klipper supports native filament sensors, you can also wire a sensor directly to the printer board and use this ESP32 as an additional notification layer.

Closing

For a few dollars in parts, this monitor catches the most common cause of failed long prints, and the alert goes to your phone rather than a printer's local screen. Start with conservative timeouts, test with deliberate faults, and adjust from real print data.