Skip to main content

EDDY TAP Mode Debugging

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

Power Off Operation

Before starting, completely shut down the printer and disconnect the power supply. Do not plug or unplug wiring harnesses, organize interface wiring sequences, or touch terminals while powered on.

Usage Instructions
  • This page explains the debugging method and is not a complete printer.cfg that can be directly copied.
  • canbus_uuid, serial, probe pins, homing direction, Z-axis travel, and offsets must be modified according to the actual hardware.
  • Before first use, ensure the EDDY, toolboard, mainboard, and Z-axis mechanical structure are in normal condition.

Applicable Scope​

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

Version Requirements​

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

Required Configuration​

Taking SHT36 V3 or SB2040 V3 as an example, [probe_eddy_current fly_eddy_probe] must be configured with frequency: 40000000, otherwise EDDY may not function correctly.

[probe_eddy_current fly_eddy_probe]
sensor_type: ldc1612
# The following i2c_mcu, i2c_bus, and offsets must be modified according to the 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; it will be written by SAVE_CONFIG upon 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 the EDDY wiring harness, toolboard interface, probe mounting screws, nozzle, and structure around the heated bed, completely shut down the printer and disconnect the power supply. Do not plug or unplug wiring harnesses or adjust terminals while powered on.

  1. Nozzle and bed surface are clean, free of filament residue, glue bumps, or foreign objects.
  2. EDDY is securely fastened, and the coil installation position is not loose.
  3. Z-axis can move up and down normally without jamming, binding, or colliding with the frame.
  4. For machines with multiple Z-axes, complete basic mechanical leveling first.
  5. Basic EDDY configuration is complete, and sensor data can be read normally.

Reference Configuration Snippet​

The following configuration retains only the common parts for EDDY TAP. The 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, which is then included by 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; it will be written by SAVE_CONFIG upon successful calibration
# tap_threshold: 40000

TAP Set Z Offset Macro​

SET_Z_FROM_PROBE METHOD=tap is used to update the current Z coordinate after a TAP trigger. It is recommended to execute it several times consecutively and observe if the results are close; if there are large differences, do not save yet, go back and check the nozzle, bed surface, Z-axis backlash, and TAP threshold.

[gcode_macro _RELOAD_Z_OFFSET_FROM_PROBE]
description: Refreshes the 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: Sets Z offset using TAP mode, 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 there is a saveable stepper_z position_endstop value in the configuration. For initial debugging, it can be set to 0, then the actual value can be confirmed through manual Z offset adjustment and first layer inspection.

In the start macro, simply call TAP to set the Z offset after the machine has completed heating, homing, and necessary leveling. Before the nozzle reaches printing temperature, a lower temperature can be maintained 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 wiping macro, it is recommended to clean the nozzle before TAP
  # CLEAN_NOZZLE
  SET_Z_FROM_PROBE METHOD=tap

  # Continue with the original print preparation process after TAP is complete

  M109 S{EXTRUDER}
  G92 E0

If the nozzle is prone to oozing, a nozzle wipe can be performed both before and after SET_Z_FROM_PROBE METHOD=tap, and SET_Z_FROM_PROBE METHOD=tap can be repeated once to improve stability.

Auto-Calibrating TAP Threshold​

Klipper supports automatic TAP threshold measurement after 2026-05-02. Before using, comment out the manually filled tap_threshold, then use the following commands to 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 the bed surface and make light contact. Ensure you can execute an emergency stop (M112) at any time before starting. If the nozzle continues to descend after contacting the bed, perform an emergency stop immediately.

① guess: Initial Rough Threshold​

Confirm the nozzle and bed surface are clean. After homing, move the toolhead near the center of the bed surface, with the nozzle 3~10mm from 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 one light touch probe. Ideally, the probe descends until the nozzle contacts the bed, then retracts and reports a valid probe result.

② refine: Refine Threshold​

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

PROBE_EDDY_CURRENT_TAP_CALIBRATE TAP=refine

This command uses data from the last 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 surface five times consecutively. Passing means all five probes complete normally with stable results.

④ Save Configuration​

After all the above steps succeed, execute:

SAVE_CONFIG

Klipper will restart after saving. At this point, only the TAP threshold has been saved; you still need to complete the Z offset confirmation.

Manually Finding the Threshold​

If the auto-calibration reports an inappropriate threshold, or if there is early triggering or failure to stop after contacting the bed, do not repeatedly execute the automatic commands. Instead, use PROBE_ACCURACY to manually find it:

PROBE_ACCURACY METHOD=tap tap_threshold=40000

When adjusting manually, start testing near 40000:

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

Once a stable manual threshold is found, you can return to TAP=refine and TAP=verify for verification.

Setting Z Offset​

After passing the TAP threshold, 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 and observe if the results are close. If there are large differences, do not save yet; check nozzle cleanliness, bed rigidity, Z-axis backlash, and TAP threshold.

Gap Fine-Tuning

In newer versions of Klipper, tap_z_offset can be used for fine-tuning the TAP gap. The actual first layer should still be confirmed based on print quality, not just a single probe value.

Manually Confirming Z Offset​

After both the TAP threshold and SET_Z_FROM_PROBE METHOD=tap have passed, manually confirm the actual gap between the nozzle and the bed:

  1. Clean the nozzle and bed surface, move the nozzle to near the center of the heated bed.
  2. Execute SET_Z_FROM_PROBE METHOD=tap and confirm no anomalies.
  3. Use a piece of paper or a first layer test to check the actual nozzle gap, and fine-tune the Z offset in the web interface.
  4. Save the configuration once the first layer is adequate.
  5. After subsequently modifying the nozzle, hotend, EDDY mounting position, or bed structure, reconfirm the offset.

Common Issues​

Unable to use normally after configuration​

  1. Confirm the FAST system version >= V1.3.9 (or Klipper is updated to the latest).
  2. Confirm the secondary MCU firmware is updated to the latest version.
  3. Confirm frequency: 40000000 is configured in [probe_eddy_current fly_eddy_probe].
  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 investigate based on the error content.

TAP probe results are unstable​

  1. Clean the nozzle and bed surface.
  2. Check if the EDDY mount is loose.
  3. Check if the Z-axis has binding or backlash.
  4. Re-execute TAP=refine and TAP=verify.

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

Communication failure or instability between the MCU where EDDY is located and the LDC1612.

Power Off Operation

Before checking the EDDY wiring harness, I2C interface, terminal crimping, or replacing the harness, completely shut down the printer and disconnect the power supply. Do not plug or unplug wiring harnesses or adjust terminals while powered on.

  1. Verify that i2c_mcu, i2c_bus, or software I2C pins match the actual toolboard.
  2. Lower i2c_speed to 400000 for testing first.
  3. Check if the EDDY wiring harness, terminals, and toolboard interface are loose.
  4. Confirm that both the EDDY and toolboard firmware are updated to a version 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 inappropriate, or the probe data does not form a sufficiently distinct TAP inflection point.

  1. Clean the nozzle and bed surface.
  2. Do not repeatedly execute auto-calibration; instead, use PROBE_ACCURACY METHOD=tap tap_threshold=40000 to manually find the threshold.
  3. Once the manual threshold is stable, return to TAP=refine and TAP=verify for verification.

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 inappropriate TAP threshold.

  1. Check if the nozzle, bed surface, and magnetic sheet are clean and flat.
  2. Check for significant looseness in the bed supports, Z-axis structure, and probe mounting.
  3. Lower the Z homing and probe speed and re-verify.
  4. If the same error occurs multiple times, do not save TAP parameters first; prioritize investigating mechanical rigidity and the threshold.
  5. It is not recommended for average users to directly modify klippy/extras/probe_eddy_current.py to loosen the error range; only personnel familiar with the Klipper source code should assess if adjustment is needed after confirming both hardware and threshold are normal.

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 acquiring data points is abnormal.

  1. Confirm that i2c_mcu, i2c_bus, or software I2C pins are filled in correctly.
  2. Test with i2c_speed initially set to 400000; do not set it too high at the start.
  3. Check if the EDDY wiring harness, 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 circuits affect the signal.
Loading...