Optical Filament Runout Sensor with Discord Webhook

The Creality Ender 3 V2 has no stock filament sensor. If a spool runs out during a long print, the machine can continue moving without extruding material, wasting time and the partly printed part. Mechanical sensors can introduce contact, friction, and moving parts into the filament path. The printer also has no native remote notification for this event.

A Honeywell HOA0865-L51 infrared fork light barrier was used as a non-contact filament runout sensor. Klipper monitors the sensor input and pauses the print when filament runout is detected. A Bash script sends a JSON payload to a Discord webhook using `curl`.

Hardware

The sensor connects to the unused EXP1 display port on the Creality V4.2.2 mainboard. Pin 9 provides ground, Pin 10 supplies 5 V to the infrared LED through a 330 Ω series resistor, and the phototransistor signal connects to Pin 1 (`PC6`).

An external 10 kΩ pull-up resistor defines the logic level. With filament blocking the optical path, the input is held HIGH; without filament, the illuminated phototransistor pulls the signal LOW.

Software

Klipper monitors the input through a `[filament_switch_sensor]` configuration. A configured three-second delay and a check that the printer is actively printing reduce alerts during manual filament handling. The `gcode_shell_command` extension installed through KIAUH runs the notification script.

Mechanical

A custom 3D-printed enclosure mounts directly to the printer’s extruder bracket. The fork light barrier is held with heat-set inserts. Short PTFE Bowden-tube sections at the inlet and outlet guide the filament through the optical gap.

The Klipper configuration connects the `PC6` input to the filament sensor and print-pause behaviour. When runout is detected during a print, the shell-command extension invokes a Bash script that posts a Discord webhook message with `curl`.

The optical gap height required three CAD revisions to align the filament to actually block the light beam reliably. Testing also showed that the mainboard’s internal pull-up was insufficiently reliable for this circuit, so a soldered 10 kΩ pull-up resistor was added to provide a defined logic level.

The sensor was installed on the Ender 3 V2 and used successfully through a completed print. A test confirmed that filament runout triggered the configured automatic print pause and Discord webhook notification without observed issues. No long-term reliability or failure-rate measurement is recorded.