Klipper

Klipper is the firmware and software responsible for running the 3D printer. It is different from traditional 3D printer firmware in that it has two components: a firmware that runs on the microcontroller of the BTT Octopus board, and a software that runs on a Raspberry Pi computer. With most firmwares, such as Marlin, g-code instructions are sent directly to the microcontroller, which are then processed into stepper motor movement commands. With Klipper, this processing is done on the much more powerful Raspberry Pi, which then sends the stepper motor commands to the microcontroller which executes them.

Klipper is configured to use Mainsail as its web interface

KIAUH

Klipper, Mainsail, and the backup addon are managed using the KIAUH program. Its GUI can be opened by running ~/kiauh/kiauh.sh

Configuration File

~~Klipper's~~The ~~configuration file is as follows as of~~ ~~4/6/2025~~ ~~(If the text is cut off, view the page in edit mode):~~

~~klipper.~~printer.cfg

[include mainsail.cfg]
# This file contains common pin mappings for the BigTreeTech Octopus
# and Octopusother Proimportant boards. To use this config, start by identifying the
# micro-controller on the board - it may be an STM32F446, STM32F429,
# or an STM32H723.  Select the appropriate micro-controller in "make
# menuconfig" and select "Enable low-level configuration options". For
# STM32F446 boards the firmware should be compiled with a "32KiB
# bootloader" and a "12MHz crystal" clock reference. For STM32F429
# boards use a "32KiB bootloader" and an "8MHz crystal". For STM32H723
# boards use a "128KiB bootloader" and a "25Mhz crystal".

# See docs/Config_Reference.md for a description of parameters.

## X Stepper on MOTOR0(B Motor)
[stepper_x]
step_pin: PF13
dir_pin: PF12
enable_pin: !PF14
rotation_distance: 40
step_pulse_duration: 0.000004 #0.000003
microsteps: 16
full_steps_per_rotation:200  #set to 400 for 0.9 degree stepper
endstop_pin: !PG6
position_min: 0
position_endstop: 740 #800
position_max: 745  # Actual maximum
homing_speed: 100   #Max 100
homing_retract_dist: 5
homing_positive_dir: true #true

[gcode_macro MOVE_Z_BEFORE_HOME]
description: Lower the bed 10mm without homing
gcode:
  G90
  SET_KINEMATIC_POSITIONZ=0
  G0 Z100 F100
  M84

# OLD  [X in MOTOR0] - B Motor
#[stepper_x]
#step_pin: PF13
#dir_pin: PF12
#enable_pin: !PF14
#microsteps: 16
#rotation_distance: 40
#step_pulse_duration: 0.000004 #0.000003
#endstop_pin: PG6
#position_endstop: 0
#position_max: 914
#homing_speed: 50

## Y Stepper on MOTOR1 (A Motor)
[stepper_y]
step_pin: PG0
dir_pin: !PG1
enable_pin: !PF15
rotation_distance: 40
step_pulse_duration: 0.000004 #0.000003
microsteps: 16
full_steps_per_rotation:200  #set to 400 for 0.9 degree stepper
endstop_pin: !PG9
position_min: 0
position_endstop: 0
position_max: 885 # Actual max is 890, -5mm for safety
homing_speed: 100  #Max 100
homing_retract_dist: 5
homing_positive_dir: false

## OLD [Y in MOTOR1] - A Motor
#[stepper_y]
#step_pin: PG0
#dir_pin: PG1
#enable_pin: !PF15
#microsteps: 16
#rotation_distance: 40
#step_pulse_duration: 0.000004 #0.000003
#endstop_pin: PG9
#position_endstop: 0
#position_max: 914
#homing_speed: 50

##	Z0 Stepper - Front Left on MOTOR2
[stepper_z]
step_pin: PF11
dir_pin: PG3
enable_pin: !PG5
microsteps: 16
rotation_distance: 1.9
#endstop_pin: PG10
#position_endstop: 0.5
endstop_pin: probe:z_virtual_endstop # BL-Touch
position_max: 500
position_min: -10
homing_speed: 25

##	Z1 Stepper - Rear Left on MOTOR3
[stepper_z1]
step_pin: PG4
dir_pin: !PC1
enable_pin: !PA0
rotation_distance: 1.9
microsteps: 16

## old
#[stepper_z1]
#step_pin: PG4
#dir_pin: PC1
#enable_pin: PA0
#microsteps: 16
#rotation_distance: 8
##endstop_pin: PG10
##position_endstop: 0.5
##position_max: 500


##	Z2 Stepper - Rear Right on MOTOR4
[stepper_z2]
step_pin: PF9
dir_pin: PF10
enable_pin: !PG2
rotation_distance: 1.9
microsteps: 16

##	Z3 Stepper - Front Right on MOTOR5
[stepper_z3]
step_pin: PC13
dir_pin: PF0
enable_pin: !PF1
rotation_distance: 1.9
microsteps: 16

##  E0 on MOTOR6
[extruder]
step_pin: PE2
dir_pin: !PE3
enable_pin: !PD4
##	Update value below when you perform extruder calibration
##	If you ask for 100mm of filament, but in reality it is 98mm:
##	rotation_distance = <previous_rotation_distance> * <actual_extrude_distance> / 100
##  22.6789511 is a good starting point
rotation_distance: 22.5343727   #old 22.6789511 #Bondtech 5mm Drive Gears
gear_ratio: 50:10				#Clockwork 2 extruder ratio is 50:10
microsteps: 16
full_steps_per_rotation: 200	#200 for 1.8 degree, 400 for 0.9 degree
nozzle_diameter: 0.400
filament_diameter: 1.75
heater_pin: PA2
##	Validate the following thermistor type to make sure it is correct
sensor_type: ATC Semitec 104NT-4-R025H42G
sensor_pin: PF4
min_temp: 10
max_temp: 270
max_power: 1.0
min_extrude_temp: 170
control = pid
pid_kp = 20 # 26.213
pid_ki = 1.304
pid_kd = 131.721
##	Try to keep pressure_advance below 1.0
pressure_advance: 0.05
##	Default is 0.040, leave stock
pressure_advance_smooth_time: 0.040

##	E0 on MOTOR6
##	Make sure to update below for your relevant driver (2208 or 2209)
[tmc2209 extruder]
uart_pin: PE1
#interpolate: false
run_current: 0.5
#hold_current: 0.4
#sense_resistor: 0.110
#stealthchop_threshold: 0
#uart_address: 3

## Driver4 (OLD)
#[extruder]
#step_pin: PF9
#dir_pin: PF10
#enable_pin: !PG2
#microsteps: 16
#rotation_distance: 22.0
#nozzle_diameter: 0.400
#filament_diameter: 1.750
#gear_ratio: 50:10
#heater_pin: PA2 # HE0
#sensor_pin:  PF4 # T0
#sensor_type: ATC Semitec 104NT-4-R025H42G
#control: pid
#pid_Kp: 22.2
#pid_Ki: 1.08
#pid_Kd: 114
#min_temp: 0
#max_temp: 250

[bltouch]
sensor_pin: ^PB7   # white wire
control_pin: PB6   # yellow/green wire
x_offset: -1.184
y_offset: -44.464
#z_offset: 1

[safe_z_home]
home_xy_position: 400, 400 # Change coordinates to the center of your print bed
speed: 200
z_hop: 10                # Move up 15mm
z_hop_speed: 25

# [quad_gantry_level]
# gantry_corners:
#     0, 0
#     740, 885
# points:
    
# max_adjust: 5.0
# speed: 100
# horizontal_move_z: 10

# [gcode_macro G32]
# gcode:
#     QUAD_GANTRY_LEVEL
#     G28
#     BED_MESH_CALIBRATE

[bed_mesh]
speed: 300
horizontal_move_z: 5
mesh_min: 10, 10
mesh_max: 700, 700
probe_count: 20, 20    # number of probe points in x, y
mesh_pps: 3, 3
algorithm: bicubic
bicubic_tension: 0.2

[quad_gantry_level]
gantry_corners:
    0, 60
    740, 885
points:
    0, 60
	0, 885
	735, 885
	735, 60
max_adjust: 5.0
speed: 200
horizontal_move_z: 10

[gcode_macro G32]
gcode:
    QUAD_GANTRY_LEVEL
    G28
    BED_MESH_CALIBRATE


# https://www.klipper3d.org/Config_Reference.html#z_tilt
#[z_tilt]
#z_positions:
#   A list of X, Y coordinates (one per line; subsequent lines
#   indented) describing the location of each bed "pivot point". The
#   "pivot point" is the point where the bed attaches to the given Z
#   stepper. It is described using nozzle coordinates (the X, Y position
#   of the nozzle if it could move directly above the point). The
#   first entry corresponds to stepper_z, the second to stepper_z1,
#   the third to stepper_z2, etc. This parameter must be provided.
#points:
#   A list of X, Y coordinates (one per line; subsequent lines
#   indented) that should be probed during a Z_TILT_ADJUST command.
#   Specify coordinates of the nozzle and be sure the probe is above
#   the bed at the given nozzle coordinates. This parameter must be
#   provided.
#speed: 50
#   The speed (in mm/s) of non-probing moves during the calibration.
#   The default is 50.
#horizontal_move_z: 5
#   The height (in mm) that the head should be commanded to move to
#   just prior to starting a probe operation. The default is 5.
#retries: 0
#   Number of times to retry if the probed points aren't within
#   tolerance.
#retry_tolerance: 0
#   If retriesfiles are enabled then retry if largest and smallest probed
#   points differ more than retry_tolerance. Note the smallest unit of
#   change here would be a single step. However if you are probing
#   more points than steppers then you will likely have a fixed
#   minimum value for the range of probed points which you can learn
#   by observing command output.


#[filament_switch_sensor material_0]
#switch_pin: PG12


[fan]
pin: PA8

[heater_fan fan1]
pin: PE5

#[heater_fan fan2]
#pin: PD12

#[heater_fan fan3]
#pin: PD13

#[heater_fan fan4]
#pin: PD14

#[controller_fan fan5]
#pin: PD15

[mcu]
serial: /dev/serial/by-id/usb-Klipper_stm32f446xx_3E0040000450565843333620-if00
# CAN bus is also available on this board

[printer]
kinematics: corexy
max_velocity: 300
max_accel: 3000
max_z_velocity: 5
max_z_accel: 100

[board_pins]
aliases:
    # EXP1 header
    EXP1_1=PE8, EXP1_2=PE7,
    EXP1_3=PE9, EXP1_4=PE10,
    EXP1_5=PE12, EXP1_6=PE13,    # Slot in the socket on this side
    EXP1_7=PE14, EXP1_8=PE15,
    EXP1_9=<GND>, EXP1_10=<5V>,

    # EXP2 header
    EXP2_1=PA6, EXP2_2=PA5,
    EXP2_3=PB1, EXP2_4=PA4,
    EXP2_5=PB2, EXP2_6=PA7,      # Slot in the socket on this side
    EXP2_7=PC15, EXP2_8=<RST>,
    EXP2_9=<GND>, EXP2_10=PC5

# See the sample-lcd.cfg file for definitions of common LCD displays.

#[neopixel my_neopixel]
#pin: PB0

[force_move]
enable_force_move: True
#   Set to true to enable FORCE_MOVE and SET_KINEMATIC_POSITION
#   extended G-Code commands. The default is false.

[pause_resume]

[display_status]

[virtual_sdcard]
path: ~/printer_data/gcodes

#*# <---------------------- SAVE_CONFIG ---------------------->
#*# DO NOT EDIT THIS BLOCK OR BELOW. The contents are auto-generated.
#*#
#*# [bltouch]
#*# z_offset = 0.001

~~This is~~ automatically backed up after every change to this GitHub repo using ~~the~~Klipper-Backup, which was installed using kiauh ~~backup extension.~~. The access token for it is ~~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~~stored alongside the password for the "Printer Bookstack" Bookstack account.

Configuration Template

The Octopus board comes with a configuration file template for an Octopus v1.1 / Voron 2.4 / Klipper combo design. This can be found here. Only use as a general guide because it does not exactly match our printer setup.

Crowsnest Webcam Streamer

As Klipper/Moonraker/Mainsail is a modular, minimalist 3D printer control system, it does not have built-in support for webcam streaming. To add webcam streaming support, Crowsnest was installed via kiauh that take a USB webcam input and stream it via a web socket that Mainsail will automatically detect.

Useful Klipper Features

The greater computing power of the Raspberry Pi allows many more printer features to be implemented, such as input shaping. Below are some references for Klipper features that could be useful:

List of included input shapers
List of supported G-code commands; includes some Klipper-exclusive ones.