From d4b5650157f864f5b09a7e09451cafb74b6e2a32 Mon Sep 17 00:00:00 2001 From: maxabba Date: Wed, 27 Aug 2025 20:41:55 +0200 Subject: [PATCH] bltouch: Add automatic z-offset calibration using nozzle electrical contact This feature eliminates manual paper testing by using electrical conductivity detection between the nozzle and conductive bed surface. The two-phase calibration process uses BLTouch for reference positioning, then detects nozzle contact at the same coordinates to calculate precise z-offset values. The implementation adds the BLTOUCH_AUTO_Z_OFFSET command with configurable parameters for probe position, speeds, and nozzle temperature. It maintains full backward compatibility as an optional feature. Signed-off-by: Marco Abbattista --- docs/BLTouch.md | 75 ++++++++++++++++++++++++++++++++++++++++ docs/Config_Reference.md | 39 +++++++++++++++++++++ docs/G-Codes.md | 22 ++++++++++++ 3 files changed, 136 insertions(+) diff --git a/docs/BLTouch.md b/docs/BLTouch.md index 9d6a7983e..293558652 100644 --- a/docs/BLTouch.md +++ b/docs/BLTouch.md @@ -223,6 +223,81 @@ far above the nozzle as possible to avoid it touching printed parts. If an adjustment is made to the probe position, then rerun the probe calibration steps. +## Automatic Z-Offset Calibration + +The BLTouch supports automatic z-offset calibration using electrical +contact detection between the nozzle and a conductive bed surface. +This feature eliminates the need for manual paper testing and provides +accurate, repeatable results. + +### Hardware Requirements + +- **Conductive bed surface**: Aluminum, steel, or exposed metal +- **GPIO connection**: Bed surface connected to a GPIO pin with pull-up resistor +- **Electrical ground**: Nozzle/hotend connected to ground +- **Clean nozzle**: Free of plastic residue for reliable contact + +### Configuration + +Add the `nozzle_probe_pin` parameter to your [bltouch] section: + +``` +[bltouch] +# ... existing configuration ... +nozzle_probe_pin: ^!P1.25 # GPIO pin for bed connection +calibration_position: 100, 100 # XY position for calibration +nozzle_temp: 200 # Heating temperature during calibration +``` + +### Usage + +Basic automatic calibration: +``` +BLTOUCH_AUTO_Z_OFFSET +``` + +With options: +``` +# Calibration without heating (for testing) +BLTOUCH_AUTO_Z_OFFSET HEAT_NOZZLE=0 + +# Calibration at specific position +BLTOUCH_AUTO_Z_OFFSET POSITION=150,150 + +# Custom temperature +BLTOUCH_AUTO_Z_OFFSET NOZZLE_TEMP=210 +``` + +The calibration process: +1. Homes all axes if needed +2. Moves to the calibration position +3. Heats the nozzle (if enabled) +4. Performs BLTouch probing for reference +5. Detects electrical contact between nozzle and bed +6. Calculates and updates the z-offset + +After calibration, use `SAVE_CONFIG` to make the new z-offset permanent. + +### Bed Preparation + +**For PEI/PET coated beds**: Carefully scrape away a small 5x5mm area +of coating to expose the underlying metal at your calibration position. +Clean with isopropyl alcohol. + +**For non-conductive beds**: Apply copper tape or aluminum foil at the +calibration position and connect with wire to the GPIO pin. + +### Troubleshooting + +**"Nozzle probe already triggered" error**: Check GPIO pin configuration +(pull-up and inversion), verify wiring with multimeter. + +**Inconsistent results**: Clean nozzle thoroughly, check bed conductivity, +ensure stable electrical connections. + +**Large offset errors**: Verify BLTouch mounting security, confirm +electrical continuity with multimeter. + ## BL-Touch output mode * A BL-Touch V3.0 supports setting a 5V or OPEN-DRAIN output mode, diff --git a/docs/Config_Reference.md b/docs/Config_Reference.md index 83de96096..9a21d1e79 100644 --- a/docs/Config_Reference.md +++ b/docs/Config_Reference.md @@ -2181,6 +2181,45 @@ control_pin: #samples_tolerance: #samples_tolerance_retries: # See the "probe" section for information on these parameters. +#nozzle_probe_pin: +# Pin connected to the conductive bed surface for nozzle contact detection +# during automatic z-offset calibration. This parameter enables the +# BLTOUCH_AUTO_Z_OFFSET command. The pin should be configured with a +# pull-up resistor (prefix with ^) and may need logic inversion (prefix +# with !). Example: "^!P1.25" for an inverted pin P1.25 with pull-up. +# This parameter is optional; if not specified, auto calibration will +# not be available. +#calibration_position: 5, 5 +# X, Y coordinates (in mm) where automatic z-offset calibration will be +# performed. This should be a position on the bed with good electrical +# conductivity and within the probe's reachable area considering the +# probe offsets. The default is 5, 5. +#nozzle_temp: 200 +# Nozzle temperature (in Celsius) to use during automatic calibration. +# Heating ensures any residual filament is soft and won't interfere +# with electrical contact detection. The default is 200. +#calibration_probe_speed: 5.0 +# Speed (in mm/s) for initial probe movements during calibration. +# The default is 5.0. +#calibration_probe_speed_slow: 1.0 +# Speed (in mm/s) for final accurate probe movements during calibration. +# Lower speeds increase accuracy. The default is 1.0. +#calibration_lift_speed: 10.0 +# Speed (in mm/s) for lift movements between probing operations during +# calibration. The default is 10.0. +#calibration_retract_dist: 2.0 +# Distance (in mm) to lift between BLTouch probe attempts during +# calibration. The default is 2.0. +#calibration_nozzle_retract_dist: 2.0 +# Distance (in mm) to lift between nozzle touch attempts during +# calibration. The default is 2.0. +#calibration_nozzle_samples: 1 +# Number of nozzle touch samples to average for increased accuracy. +# More samples increase calibration time but may improve consistency. +# Must be between 1 and 10. The default is 1. +#calibration_nozzle_diameter: 0.4 +# Nozzle diameter (in mm) for informational purposes and future +# enhancements to the calibration algorithm. The default is 0.4. ``` ### [smart_effector] diff --git a/docs/G-Codes.md b/docs/G-Codes.md index 7a60aa8a0..12f6268ab 100644 --- a/docs/G-Codes.md +++ b/docs/G-Codes.md @@ -267,6 +267,28 @@ V3.0 or V3.1 may also support `set_5V_output_mode`, `BLTOUCH_STORE MODE=`: This stores an output mode in the EEPROM of a BLTouch V3.1 Available output_modes are: `5V`, `OD` +#### BLTOUCH_AUTO_Z_OFFSET +`BLTOUCH_AUTO_Z_OFFSET [HEAT_NOZZLE=<0|1>] [NOZZLE_TEMP=] [POSITION=]`: +Performs automatic z-offset calibration for the BLTouch using electrical +contact detection between the nozzle and a conductive bed surface. This +command requires `nozzle_probe_pin` to be configured in the [bltouch] +section. + +The calibration process: +1. Homes all axes if not already done +2. Moves to the calibration position +3. Heats the nozzle (if enabled) +4. Performs BLTouch probing to establish a reference +5. Detects electrical contact between nozzle and bed +6. Calculates and updates the z-offset + +Parameters: +- `HEAT_NOZZLE`: Set to 0 to skip nozzle heating, 1 to heat (default: 1) +- `NOZZLE_TEMP`: Override nozzle temperature in Celsius (default: from config) +- `POSITION`: Override calibration position as "x,y" in mm (default: from config) + +Note: After calibration, use `SAVE_CONFIG` to make the new z-offset permanent. + ### [configfile] The configfile module is automatically loaded.