Filament Blockage Detection Optimization

Feature Description

FAST version 1.3.8 optimizes the filament blockage detection feature, providing more precise blockage detection capabilities and flexible configuration options. This feature can monitor the extruder's material output in real-time and automatically pause printing and notify the user when blockage or filament runout is detected.

Important Notice

System Version Requirement: This feature requires FlyOS-Fast system version greater than or equal to v1.3.8 to function properly.

---

Configuration Method

• Add the following configuration to the printer.cfg file:
• Please note that this is a reference configuration, and specific parameters may need to be adjusted according to actual conditions

[filament_blockage_detection my_sensor]
switch_pin: ^PA10
extruder: extruder
distance_per_edge: 0.232
detection_length: 3
pause_on_runout: True
runout_gcode: M118 Blockage during printing
insert_gcode: M118 Recovery during idle

Basic Parameters:

Parameter	Default Value	Description
switch_pin	Required	Pin of the blockage detection sensor, ^ indicates enabling the pull-up resistor
extruder	extruder	Name of the associated extruder
distance_per_edge	Required	Filament movement distance corresponding to each pulse of the sensor (mm), automatically updated after calibration
detection_length	7.0	Blockage is determined when the slip distance exceeds this threshold (mm) and is confirmed multiple consecutive times
recovery_length	detection_length * 0.5	Returns to normal state when the slip distance falls below this value (mm)
pause_on_runout	—	Whether to automatically pause printing when blockage is detected
runout_gcode	—	G-code executed when blockage is detected
insert_gcode	—	G-code executed when filament recovery is detected

Advanced Parameters (usually the default values are sufficient):

Parameter	Default Value	Description
window_length	detection_length * 3	Sliding window length (mm)
retraction_min_delta	0.050	Minimum extrusion displacement to determine retraction movement (mm), below this value is considered stationary
blockage_sample_count	2	Number of consecutive over-threshold confirmations required to determine blockage (1-5)

Auto-calibration instructions

The distance_per_edge parameter will automatically calculate the optimal value after executing the CALIBRATE_FILAMENT_BLOCKAGE calibration command, and will be permanently saved to the configuration file via the SAVE_CONFIG command. Any value can be entered during initial configuration, and it will be automatically overwritten after calibration.

---

Calibration Steps

To ensure detection accuracy, it is recommended to calibrate the sensor before use.

Step 1: Heat the nozzle

Heat the nozzle to the normal operating temperature (220°C recommended):

M104 S220
M109 S220

Step 2: Execute the calibration command

After the nozzle reaches the target temperature, execute the following calibration command:

CALIBRATE_FILAMENT_BLOCKAGE SENSOR=my_sensor TEMPERATURE=220

Command parameters:

Parameter	Default value	Description
SENSOR	Required	Sensor name, corresponding to [filament_blockage_detection my_sensor] in the configuration
TEMPERATURE	Required	Nozzle temperature during calibration (°C)
DISTANCE	30.0	Extrusion length per calibration round (mm)
COUNT	5	Number of calibration rounds (1-20), using the average of multiple rounds
SPEED	2.0	Extrusion speed (mm/s)
SETTLE_TIME	0.375	Settling time to wait for the sensor report after each extrusion round (seconds)
MIN_EDGES	1	Minimum number of pulses captured per round; an error is reported if below this value

During calibration, the system automatically performs multiple extrusion rounds, counts the encoder pulses for each round, calculates the optimal distance_per_edge, and prompts the result.

Example calibration output:

Filament blockage sensor my_sensor calibration round 1/5:
  edge_count_delta: 130
  implied_distance_per_edge: 0.230769 mm
...
Filament blockage sensor my_sensor calibration result:
  samples: 130, 129, 131, 130, 128
  average_edge_count: 129.600
  calibrated_distance_per_edge: 0.231481 mm
The SAVE_CONFIG command will update the printer config file
with this parameter and restart the printer.

Step 3: Save the calibration result

After calibration is complete, execute the following command to save the new distance_per_edge to the configuration file and restart Klipper:

SAVE_CONFIG

---

Query Sensor Status

Use the QUERY_FILAMENT_BLOCKAGE command to view the sensor's measurement data in real time, including key information such as extrusion length, encoder measured distance, and slip distance.

QUERY_FILAMENT_BLOCKAGE SENSOR=my_sensor

Returned Field Description:

Field	Description
total_extruded_distance	Cumulative extruder commanded movement distance (mm) — that is, the total length the Klipper command has advanced the extruder
total_measured_distance	Cumulative encoder actual measured distance (mm) — the amount of filament movement actually detected by the sensor
raw_measured_distance	Raw encoder measured distance (mm) — the cumulative value without direction determination
expected_distance	Expected extrusion distance since the last change in movement direction (mm)
measured_distance	Actual measured distance within the current window (mm)
slip_distance	Slip distance (mm) — the difference between expected distance and actual measurement; when it exceeds detection_length, blockage determination is triggered
measured_speed	Current measured speed (mm/s)
edge_count	Cumulative encoder pulse count
pending_blockage_count	Current consecutive over-threshold confirmation count; when it reaches blockage_sample_count, blockage is determined
in_retraction	Whether currently in retraction state (True/False)
blocked	Whether blockage has been determined (True/False)
printing	Whether currently in printing state (True/False)

Usage Scenarios:

• Troubleshooting false blockage alarms: Compare total_extruded_distance and total_measured_distance. If the difference between them continues to increase, it indicates that the filament movement detected by the encoder is lagging behind the extrusion command, and slipping may exist
• Confirming whether the sensor is normal: Query measured_speed during printing; during normal extrusion there should be a stable speed reading
• Checking slip trend: Pay attention when slip_distance approaches detection_length; if it continues to exceed it, pause printing

---

Important Reminder

Firmware Update Requirement

After upgrading to FAST 1.3.8, the MCU firmware must be updated, otherwise filament blockage detection may not work properly.

Refer to Firmware Compilation Instructions and follow the mainboard product documentation to compile and flash the MCU firmware.

---

Troubleshooting

Issue 1: Filament Blockage Detection Not Triggering

Possible Causes:

• The sensor is not properly connected
• Incorrect switch_pin configuration
• Lower-level machine firmware not updated

Solutions:

1. Check the sensor hardware connection
2. Verify the pin configuration matches the actual hardware
3. Update the lower-level machine firmware to the latest version

Issue 2: False Blockage Alarms

Possible Causes:

• Inaccurate distance_per_edge parameter
• The detection_length threshold is set too small

Solutions:

1. Re-execute the calibration command
2. Appropriately increase the detection_length value (recommended 3-5mm)

Issue 3: Calibration Failure

Possible Causes:

• Nozzle temperature does not meet the requirement
• Sensor hardware malfunction

Solutions:

1. Confirm the nozzle has been heated to the specified temperature
2. Check whether the sensor is functioning properly
3. Try restarting the Klipper service

---

Usage Recommendations

• It is recommended to recalibrate the sensor whenever changing filament brand or diameter
• Regularly check the sensor status to ensure detection accuracy
• If the filament blockage detection feature has not been used for an extended period, it is recommended to recalibrate before use

---