Skip to main content

EDDY TAP Mode Debugging

This page covers the debugging process, inspection sequence, and common troubleshooting for EDDY in TAP mode. TAP mode determines the trigger threshold by lightly touching the nozzle to the bed. During debugging, pay attention to the nozzle, heated bed, and Z-axis motion status.

Power Off Operation

Before starting, completely turn off the printer and disconnect the power supply. Do not plug, unplug, or organize wiring harnesses or touch terminals while power is on.

Usage Notes
  • This page describes debugging methods and is not a complete printer.cfg to copy directly.
  • canbus_uuid, serial, probe pins, homing direction, Z-axis travel, and offsets must be modified according to actual hardware.
  • Before first use, ensure the status of EDDY, toolboard, mainboard, and Z-axis mechanical structure is normal.

Applicable Scope​

  • Uses EDDY / LDC1612 eddy current sensor, requiring METHOD=tap or TAP threshold trigger method.
  • Applicable to toolboards with EDDY support such as FLY SHT36 V3, SB2040 V3.
  • Basic EDDY wiring and standard height calibration completed, requiring further enabling or troubleshooting of TAP mode.

Version Requirements​

Version Update
  • Using FLY FAST system: Ensure system version >= V1.3.9.
  • Using other systems: Ensure Klipper is updated to the latest version.
  • The toolboard or related secondary MCU firmware must also be updated to the latest, otherwise the host may support TAP commands while the MCU firmware does not respond.

Required Configuration​

Using SHT36 V3 or SB2040 V3 as an example, [probe_eddy_current fly_eddy_probe] must include frequency: 40000000, otherwise EDDY may not function correctly.

[probe_eddy_current fly_eddy_probe]
sensor_type: ldc1612
# Modify i2c_mcu, i2c_bus, and offsets according to actual toolboard and installation position
i2c_mcu: SHT36
i2c_bus: i2c1e
i2c_speed: 400000
frequency: 40000000
x_offset: 0
y_offset: 21.42
descend_z: 2.5
tap_z_offset: 0

# Comment out before auto-calibrating TAP threshold; will be written by SAVE_CONFIG after successful calibration
# tap_threshold: 40000

After configuration, re-execute Drive Current Calibration and Height Calibration according to the corresponding product documentation.

Related Documents: SHT36 V3 EDDY Usage

Pre-Configuration Checks​

Power Off Operation

Before checking EDDY wiring, toolboard interface, probe fixing screws, nozzle, and structures around the heated bed, completely turn off the printer and disconnect power. Do not plug/unplug wires or adjust terminals while power is on.

  1. Nozzle and bed surface are clean, free of filament residue, adhesive bumps, or debris.
  2. EDDY is securely fixed, and the coil installation position has no loosening.
  3. Z-axis can move up and down normally without jamming, hitting limits, or colliding with the frame.
  4. For multi-Z-axis machines, complete basic mechanical leveling first.
  5. Basic EDDY configuration is completed, and sensor data can be read normally.

Reference Configuration Snippet​

This configuration keeps only the common EDDY TAP parts. mcu name, I2C bus, offsets, leveling method, and start macro parameters must be modified according to the actual machine. It is recommended to place this in a separate configuration file and include it via printer.cfg.

[respond]

[force_move]
enable_force_move: true

[probe_eddy_current fly_eddy_probe]
sensor_type: ldc1612
i2c_address: 42
i2c_mcu: SHT36
i2c_bus: i2c1e
i2c_speed: 400000
frequency: 40000000
x_offset: 0
y_offset: 21.42
descend_z: 2.5
speed: 5
samples: 3
sample_retract_dist: 5.0
samples_tolerance: 0.05
samples_tolerance_retries: 3
tap_z_offset: 0

# Comment out before auto-finding TAP threshold; will be written by SAVE_CONFIG after successful calibration
# tap_threshold: 40000

TAP Set Z Offset Macro​

SET_Z_FROM_PROBE METHOD=tap updates the current Z coordinate after a TAP trigger. It is recommended to execute it several times consecutively and observe if the results are consistent. If there is significant variation, do not save; instead, check the nozzle, bed, Z-axis backlash, and TAP threshold.

[gcode_macro _RELOAD_Z_OFFSET_FROM_PROBE]
description: Refresh current Z coordinate based on the last PROBE result
gcode:
  {% set Z = printer.toolhead.position.z %}
  {% set position_endstop = 0 %}
  {% set raw_config = printer.configfile.config %}
  {% if 'stepper_z' in raw_config and 'position_endstop' in raw_config.stepper_z %}
    {% set position_endstop = raw_config.stepper_z.position_endstop|trim|float %}
  {% endif %}
  {% set setZ = Z - printer.probe.last_probe_position.z + position_endstop %}
  SET_KINEMATIC_POSITION Z={setZ}
  RESPOND MSG="position_Z={'%0.3f' | format(Z)} probe_Z={'%0.3f' | format(printer.probe.last_probe_position.z)} position_endstop={'%0.3f' | format(position_endstop)} set_Z={'%0.3f' | format(setZ)}"

[gcode_macro SET_Z_FROM_PROBE]
description: TAP mode set Z offset, usage: SET_Z_FROM_PROBE METHOD=tap
gcode:
  {% set METHOD = params.METHOD | default("automatic") %}
  G0 Z5 F300
  PROBE METHOD={METHOD} SAMPLES=3
  _RELOAD_Z_OFFSET_FROM_PROBE
  G0 Z5 F300

If using this macro to save and reuse position_endstop, ensure the configuration contains a savable stepper_z position_endstop value. During initial debugging, it can be set to 0, then confirm the actual value through manual Z offset and first layer testing.

In the start macro, simply call TAP to set the Z offset after heating, homing, and any necessary leveling is complete. The nozzle can be kept at a lower temperature before reaching printing temperature to avoid oozing affecting the TAP.

[gcode_macro PRINT_START]
gcode:
  {% set BED = params.BED|default(60)|int %}
  {% set EXTRUDER = params.EXTRUDER|default(200)|int %}
  {% set X_CENTER = printer.toolhead.axis_maximum.x|float / 2 %}
  {% set Y_CENTER = printer.toolhead.axis_maximum.y|float / 2 %}

  SET_GCODE_OFFSET Z=0
  G21
  G90
  G28

  G1 X{X_CENTER} Y{Y_CENTER} Z15 F9000
  M190 S{BED}
  M109 S150

  # Keep your original pre-print preparation process here
  # ...

  # If you have a nozzle wipe macro, consider cleaning the nozzle before TAP
  # CLEAN_NOZZLE
  SET_Z_FROM_PROBE METHOD=tap

  # Continue with original print preparation process after TAP

  M109 S{EXTRUDER}
  G92 E0

If the nozzle tends to ooze, perform a nozzle wipe before and after SET_Z_FROM_PROBE METHOD=tap, and repeat SET_Z_FROM_PROBE METHOD=tap once to improve stability.

Auto-Calibrate TAP Threshold​

Klipper supports automatic measurement of the TAP threshold after 2026-05-02. Before using it, first comment out the manually filled tap_threshold, then use the following commands to re-find the threshold.

TAP threshold calibration command: PROBE_EDDY_CURRENT_TAP_CALIBRATE TAP=xxx, common values are guess, refine, verify.

Emergency Stop Preparation

The following steps will cause the nozzle to move towards and lightly touch the bed. Before starting, ensure you can execute an emergency stop (M112) at any time. If the nozzle continues descending after contacting the bed, immediately emergency stop.

① guess: Initial Rough Threshold​

Ensure the nozzle and bed are clean. After homing, move the toolhead near the center of the bed, with the nozzle 3~10mm above the bed.

PROBE_EDDY_CURRENT_TAP_CALIBRATE TAP=guess

This command analyzes data from the main probe calibration to obtain an initial rough tap_threshold value, then performs a tap probe. Ideally, the probe descends, the nozzle contacts the bed, retracts, and reports a valid detection result.

② refine: Refine Threshold​

After TAP=guess succeeds, keep the nozzle near the bed center at 3~10mm and execute:

PROBE_EDDY_CURRENT_TAP_CALIBRATE TAP=refine

This command uses data from the previous successful probe to determine a more precise threshold.

③ verify: Verify Stability​

After TAP=refine succeeds, execute:

PROBE_EDDY_CURRENT_TAP_CALIBRATE TAP=verify

This command probes the bed five times consecutively. Passing requires all five probes to complete normally with stable results.

④ Save Configuration​

After all steps above succeed, execute:

SAVE_CONFIG

Save and restart Klipper. This only saves the TAP threshold. Z offset confirmation must still be completed.

Manual Threshold Finding​

If the auto-calibration reports an unsuitable threshold, or if there are issues like premature triggering or failure to stop after contacting the bed, do not keep repeatedly executing the automatic commands. Instead, use PROBE_ACCURACY to find the threshold manually:

PROBE_ACCURACY METHOD=tap tap_threshold=40000

When adjusting manually, start testing around 40000:

  • Triggers without contacting bed → Threshold too low, increase appropriately.
  • Does not stop after contacting bed → Threshold too high, immediately emergency stop and decrease.
  • Before each test, ensure nozzle and bed are clean, and the nozzle is 3~10mm above the bed.

Once a stable manual threshold is found, you can return to auto-calibration's TAP=refine and TAP=verify for validation.

Setting Z Offset​

After the TAP threshold passes, use Klipper's TAP method to set the Z offset:

SET_Z_FROM_PROBE METHOD=tap

It is recommended to execute this several times consecutively to observe if results are consistent. If there is significant variation, do not save; instead, check nozzle cleanliness, heated bed rigidity, Z-axis backlash, and TAP threshold.

Gap Fine-Tuning

In newer Klipper versions, tap_z_offset can be used for TAP gap fine-tuning. The actual first layer should still be confirmed by printing results, not just by single probe values.

Manual Z Offset Verification​

After both the TAP threshold and SET_Z_FROM_PROBE METHOD=tap pass, the actual gap between the nozzle and bed must still be confirmed manually:

  1. Clean the nozzle and bed, move the nozzle near the center of the heated bed.
  2. Execute SET_Z_FROM_PROBE METHOD=tap, confirm no anomalies.
  3. Use paper or a first-layer test to check the actual nozzle gap, fine-tune Z offset via the web interface.
  4. Save configuration once the first layer is satisfactory.
  5. If the nozzle, hotend, EDDY mounting position, or bed structure is changed later, re-confirm the offset.

Common Issues​

Still cannot use normally after configuration​

  1. Confirm FAST system version >= V1.3.9 (or Klipper updated to latest).
  2. Confirm secondary MCU firmware is updated to the latest version.
  3. Confirm [probe_eddy_current fly_eddy_probe] has frequency: 40000000 configured.
  4. Confirm i2c_speed is not too high. For SHT36 V3 / SB2040 V3, test with 400000 first.
  5. Re-execute drive current calibration and height calibration.
  6. Check klippy.log for the first EDDY or TAP related error, and troubleshoot based on the error content.

Unstable TAP probe results​

  1. Clean the nozzle and bed.
  2. Check if EDDY is loosely fixed.
  3. Check if Z-axis has stuttering or backlash.
  4. Re-execute TAP=refine and TAP=verify.

EDDY TAP / Z_TILT triggers Timer too close​

Typical error:

!! MCU 'xxx' shutdown: Timer too close

If this error only occurs during EDDY TAP, Z homing, Z_TILT_ADJUST, QUAD_GANTRY_LEVEL, or bed probing phases, it is usually necessary to check EDDY sampling, CAN communication, and host scheduling margin simultaneously.

  1. Check the Stats lines before and after the error in klippy.log to see if there are concurrent anomalies like bytes_retransmit, bytes_invalid, canstat_*, I2C errors, or increased host load.
  2. Ensure Klipper, toolboard MCU, and EDDY MCU firmware versions are consistent. After updating, re-flash all related MCUs.
  3. Temporarily disable camera streams, KlipperScreen, remote control plugins, and other high-usage services, then retest.
  4. If the error occurs during Z_TILT_ADJUST and the machine structure allows, temporarily switch to Z_TILT_ADJUST METHOD=scan for testing to reduce timing synchronization pressure in the TAP trigger path.
  5. Reduce unnecessary repeated homing, repeated TAP, and continuous bed probing actions in the start macro. If already homed and the machine state is trustworthy, the macro can avoid redundant G28.
  6. If EDDY I2C errors also appear, first follow I2C BUS_TIMEOUT to troubleshoot wiring, I2C speed, and toolboard interface.

System-level troubleshooting: Timer too close

MCU 'xxx' I2C request to addr 42 reports error BUS_TIMEOUT​

Communication between the MCU hosting EDDY and the LDC1612 has failed or is unstable.

Power Off Operation

Before checking EDDY wiring, I2C interface, terminal crimping, or replacing wiring, completely turn off the printer and disconnect power. Do not plug/unplug wires or adjust terminals while power is on.

  1. Verify i2c_mcu, i2c_bus, or software I2C pins match the actual toolboard.
  2. First, lower i2c_speed to 400000 for testing.
  3. Check if EDDY wiring, terminals, and toolboard interface are loose.
  4. Ensure EDDY and toolboard firmware are updated to versions compatible with the current Klipper.

Unable to detect tap: insufficient slope delta​

Typical error:

!! Unable to detect tap: insufficient slope delta (-36983.054918 vs 30633.703000)

The current tap_threshold is unsuitable, or the probe data does not form a sufficiently clear TAP inflection point.

  1. Clean the nozzle and bed.
  2. Do not repeatedly run auto-calibration. Instead, use PROBE_ACCURACY METHOD=tap tap_threshold=40000 to manually find the threshold.
  3. Once a stable manual threshold is found, return to TAP=refine and TAP=verify for validation.

Unable to detect tap: invalid depress distance​

Typical error:

!! Unable to detect tap: invalid depress distance (0.020411 vs 0.030000:0.250000)

The depress distance detected by Klipper is outside the expected range (0.03~0.25mm). Common causes: insufficient bed rigidity, unstable nozzle contact process, Z-axis backlash, or unsuitable TAP threshold.

  1. Check if the nozzle, bed surface, and build plate/surface are clean and flat.
  2. Check for significant looseness in bed support, Z-axis structure, or probe mounting.
  3. Lower Z homing and probe speed, then re-validate.
  4. If the same error appears multiple times, do not save TAP parameters initially. Prioritize troubleshooting mechanical rigidity and threshold.
  5. It is not recommended for ordinary users to directly modify klippy/extras/probe_eddy_current.py to relax the error range. Only after confirming hardware and thresholds are normal should someone familiar with Klipper source code evaluate if an adjustment is needed.

Eddy: CLKIN frequency too low​

Typical error:

!! Eddy: CLKIN frequency too low: 0.001 < 0.002

I2C communication is unstable, and the time interval for data point acquisition is abnormal.

  1. Confirm i2c_mcu, i2c_bus, or software I2C pins are filled correctly.
  2. Test with i2c_speed set to 400000 first; do not set it too high initially.
  3. Check if EDDY wiring, terminals, and toolboard interface are loose.
  4. If using software I2C, confirm the corresponding GPIO is not occupied by other functions and that no peripheral circuitry affects the signal.
Loading...