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 <max.abbattista@live.it>

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,

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]

docs/G-Codes.md

@@ -267,6 +267,28 @@ V3.0 or V3.1 may also support `set_5V_output_mode`,
 `BLTOUCH_STORE MODE=<output_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=<temp>] [POSITION=<x,y>]`:
+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.