Skip to content

Installing for Klipper

Jump to bottom
Mark edited this page Jun 29, 2024 · 281 revisions

1. Hardware install

  1. Attach the sensor cable to the mainboard or the CAN bus toolhead board or the GPIOs on the RaspberryPi.

the wires CKL and SDA of BDsensor can be connected to any GPIO pins of your board. You can also connect the BDsensor cable into the Bltouch port directly (except all the boards from MKS), for example:

BLtouch    |    BDsensor
 GND      -->     GND
 5V       -->     5V
 S        -->     CLK/SCL    (Input)
 GND      -->     GND
 Zmin     -->     SDA    (Input/Output)

Since some of the pins in the connectors on the mainboard maybe not connected to the gpios of MCU directly (e.g. there maybe a filter capacitor on them or isolated by mosfet, diode or optocoupler, but it's OK if they are isolated by resistors or pullup/pulldown by resistors), they cannot work with BDsensor. and the firmware will report connection error. For example

  • The connectors for FANs and Heaters are isolated by mosfet,
  • The connectors for temperature thermistors and Endstops/Probe in some boards like MKS are normally connected to GND by filtered capacitors,
  1. Mount the BDsensor near to the hotend, as shown in the figure below. STL of mount, STL_mount_VzBot_Goliath short

https://raw.githubusercontent.com/markniu/Bed_Distance_sensor/new/doc/images/Connection1.jpg

Note: The black cable is original designed for the IPEX wireless antenna, it is a little stiff, please don't bend it too much.

2. Install software

ssh into your Klipper device and execute the following commands:

  • Clone and install the software
cd  ~
git clone https://github.com/markniu/Bed_Distance_sensor.git
  • Compile and flash the firmware into the MCU or the CANbus toolhead board which the BDsensor connected.
~/Bed_Distance_sensor/klipper/install_BDsensor.sh
cd ~/klipper/
make menuconfig
./make_with_bdsensor.sh
make flash

make sure there is Compiling out/src/BD_sensor.o on the SSH while run make_with_bdsensor.sh

Different board has different configuration in the step make menuconfig and the step of flash firmware make flash, please read the document of the board from the factory, we didn't change any of that.

  • BDsensor update (optional)

If you update the klipper later and don't forget to update BDsensor too.

you can update the code of BDsensor by command:

cd  ~/Bed_Distance_sensor/
git fetch --all &&  git reset --hard origin/new && git pull

or from Moonraker Update Manager:

$\color[RGB]{55,27,200} Configure Update Manager (optional)$

Add the following section to moonraker.conf if your printer is running Moonraker.and then you can update the BDsensor with 1 click via the web page or klipperscreen. 

[update_manager BDsensor]
type: git_repo
primary_branch: new
channel: dev
path: ~/Bed_Distance_sensor
origin: https://github.com/markniu/Bed_Distance_sensor.git
install_script: ./klipper/install_BDsensor.sh
is_system_service: False
managed_services: klipper
info_tags:
  desc=Bed Distance Sensor
  • Revert to the previous version(optional)

Please ignore this if you are installing for the first time.

git reset --hard HEAD~1 that can revert it to the previous version. HEAD~1 is the last commit. If you want to rollback 3 commits you could use HEAD~3. If you want to rollback to a specific revision number, you could also do that using its SHA hash.

3. Configuration

  • Copy the section [BDsensor] into your printer.cfg and modify the sda_pin and scl_pin to yours, also do not forgot to disable other probe section like BLtouch.
[BDsensor] 
# Don't use aliases for the board pins
sda_pin: PB1 # example of connecting to main board Creality V4.2.7
scl_pin: PB0
#scl_pin:MKS_THR:gpio20 # example of connecting to CAN module like MKS THR42 
#sda_pin:MKS_THR:gpio11 
#scl_pin:host:gpio17 # example of connecting to GPIO on RaspberryPi
#sda_pin:host:gpio27
delay: 20 # you can set it 10 if the BDsensor version is >=1.2
z_offset:0 #  within -0.6 to 0.6mm
x_offset: -34
y_offset: 0
no_stop_probe: # fast probe that the toolhead will not stop at the probe point,disable it by commenting out.
position_endstop: 1.2 #the triggered position, recommend value is 1~2.8
collision_homing:0 #  set it 1 to enable homing with nozzle collision sensing.
collision_calibrate:0 # set it 1 to enable auto calibrate BDsensor with nozzle collision sensing.
#QGL_Tilt_Probe:0 #set 1 to enable probe up and down when do quad_gantry_level
  • Modify the endstop_pin in section [stepper_z], and disable the position_endstop, Slow down the speed of z homing, e.g. homing_speed: 5 , second_homing_speed: 1 homing_retract_speed: 2 
[stepper_z]
endstop_pin: probe:z_virtual_endstop
#position_endstop: 0.5
homing_speed: 5
second_homing_speed: 1  #set this to 3 if homing with collision
homing_retract_speed: 2
homing_retract_dist:5
...
  • Make sure there are [safe_z_home],[bed_mesh], [force_move] in your printer.cfg .

Modify the horizontal_move_z to 1(0.7~1.0mm is recommended) in section [bed_mesh] and [quad_gantry_level].

[safe_z_home]
...

[bed_mesh]
horizontal_move_z:1 # 0.7~1.0mm is recommended
algorithm: bicubic  # this should be bicubic if the bed mesh points count is > 6*6
...

[quad_gantry_level]
horizontal_move_z:1 # 0.7~1.0mm is recommended
...

[force_move] 
enable_force_move: true   # required by the command SET_KINEMATIC_POSITION in the calibration step below.

Tip

if you printer has z_tilt or qual_gantry_level, please add this macro Z move or not automatically_Z_Tilt_QGL

Tip

[bed_mesh]
horizontal_move_z:1 # 0.7~1.0mm is recommended
zero_reference_position: 150, 160 # Set this value to be the same as home_xy_position that is in the section safe_z_home
....
$\color[RGB]{55,27,200}For Delta Printer$ 
[printer]
kinematics: delta
max_velocity: 300
max_accel: 3000
max_z_velocity: 150

[BDsensor] 
scl_pin:PB6
sda_pin:PB7
delay: 20 
z_offset:0 # this `z_offset` must be set to 0. 
x_offset: 0
y_offset: 0
samples:1
no_stop_probe: # enable this for fast probe, the toolhead will not stop at the probe point.
position_endstop: 0.5 # the Z axis will stop at this position (mm) while homing z, recommend value is 0.4~1.0

[bed_mesh]
speed: 200
horizontal_move_z: 1
mesh_radius: 80
mesh_origin: 0, 0
round_probe_count: 5

[delta_calibrate]
radius:100
horizontal_move_z: 20
speed:5

[force_move] 
enable_force_move: true   # must true, required in the calibration step below.

Don't forget to run DELTA_CALIBRATE before running BED_MESH_CALIBRATE

4. Check connection

M102   S-1     # Read sensor information
M102   S-2     # Read one distance value

Check the connection by M102 S-1. Here is an example of the return message

Send: M102 S-1
Recv: V1.0 pandapi3d.com

please check the connection and wire order if it return blank and check again if the pins can be used as GPIO that there must have no signal filter capacitor or diode.

5. Calibration

  • Clean the nozzle

  • Send command SET_KINEMATIC_POSITION Z=200 then move the Z axis down in the menu until the nozzle just touches the bed plate, the BDsensor will use this position as the zero position.

  • Sending gcode command M102 S-6.

  • After that you can check whether the BDsensor has been calibrated successful by M102 S-5 that will return the raw calibration data which stored in the BDsensor. If the first raw calibration data returned by the M102 S-5 is greater than 400, that means the sensor is mounted too high and needs to be remounted closer to the bed, the recommend value of first data is around 100. also make sure that the value of second data is greater than the first data by more than 10, else adjust the height of z and do calibarte again.

Tip

Make sure the line of the sensor and the nozzle is parallel with the bed, and recommend to calibrated it again after doing z tilt or QGL if your printer has multi z motors.

6. Check Endstop

Please do not Homing Z until you have checked this step or else the nozzle maybe cashes the printer bed.

This is the return message after sending M119 command(Reporting endstop status).

Send: M119
Recv: x:open y:open z:open

Put a metal piece close enough to the sensor, send M119 again.

Send: M119
Recv: x:open y:open z:TRIGGERED

If all above steps are right, then you can homing z axis now.

7. Check Accuracy

  • Move the z axis to 1mm after homing then read the distance value from BDsensor by M102 S-2, the returned value should be about 1mm too, e.g. 0.98~1.02mm.
G28
G1 Z1

waiting the toolhead stops then

M102 S-2
  • Check if the zero position is as expected by G1 Z0 after G28, if not please calibrate again.

Gcode Command for BDsensor:

BDSENSOR_VERSION                   # equals M102 S-1 , read the version of BDsensor
BDSENSOR_CALIBRATE                 # equals M102 S-6 , calibrate the BDsensor
BDSENSOR_READ_CALIBRATION          # equals M102 S-5 , read the raw calibrate data
BDSENSOR_DISTANCE                  # equals M102 S-2 , read the distance value measured by BDsensor
BDSENSOR_SET                       # set value, now only for setting z_adjust, for example BDSENSOR_SET z_adjust=0.1

Note

  • If the first raw calibration data returned by the M102 S-5 is greater than 400, that means the sensor is mounted too high and needs to be remounted > > closer to the bed, the recommend value of first data is 100. also make sure that the value of second data is greater than the first data by more than 10
    • FAQ: if calibration data begins with 1 and second value is 9 and third 24 what that means?
    • that means the resolution between 0-0.1mm is only 9,and the 0.1-0.2mm is 15.so recommend to calibrate again let the first resolution 0-0.1mm > bigger than 10
$\color[RGB]{55,27,200} FAQ$
  1. Unknown pin chip name 'probe'

  • Check if there is a file BDsensor.py in the ~/klipper/klippy/extras/, if not please install again by running cd ~/Bed_Distance_sensor/klipper/ and ./install_BDsensor.sh

  • One common reason is the updating of Fluidd or Mainsail that will remove the BDsensor.py file in Klipper, so need to run ./install_BDsensor.sh again.

  • Check the section name [BDsensor] is correct, note the capitalized and lowercase.

  • Make sure the username you login while running ./install_BDsensor.sh is the same as the installed klipper

  1. Report: Bed Distance Sensor, out of range.:3.90 while doing quad_gantry_level after Z_tilt
  • Please home again the printer because the Z_tilt has adjusted the Z axis height.
  1. Report : Probe triggered prior to movement while doing Z_tilt
  • Please increase the horizontal_move_z in the section [z_tilt], that will move the z higher before probing.
  1. The nozzle cashes to the bed while homing
  • Make sure you have check the endstop by M119.
  • Make sure the BDsensor has been calibrated again after install.
  • The BDsensor is used as the default homing sensor, do not homing with other endstop.
  1. Report Error while G28: Unknown value 'probe' in enumeration 'pin'
  • Don't use aliases for the board pins #57
  1. Random data error, for example:"V . anda i " after M102 S-1 or some error data like 1024.
  • make sure all the 2 GND wires are connected to the mainboard at the same time.
Clone this wiki locally