Skip to content

Electronics Setup

Electronics setup

Once you have the Klipper stack up and running, you may proceed with its configuration.

Configuration consists mainly of assigning the correct pin names to stepper motors, endstops, or other electronic components connected to the robot's micro-controller units (MCUs).

Note

This guide is aimed at advanced makers, engineers, or wisepeople that know what they are doing.

Warning

Instructions below may involve mains power, which is extremely dangerous. We assume no liability for any equipment damage or physical harm produced by the use of these instructions, which are given as-is, and with no guarantee.

Install the firmware

Before you start, stop the Klipper service:

sudo service klipper stop

# If using systemd:
# sudo systemctl stop klipper.service

# If using the user unit:
# systemctl --user stop klipper.service

Info

More details available at Klipper's documentation.

To install Klipper in an Arduino MCU from a Raspberry Pi:

  1. Connect the Raspberry Pi to the Arduino using a USB-USB-B cable.
  2. On the Raspberry Pi, run the following commands:
cd ~/klipper/
make menuconfig
  1. In the menu that appears, select the microprocessor that corresponds to your Arduino.
  2. For the Duet2 WiFi, select the SAM3/SAM4/SAM E70 (Due and Duet) architecture, and the SAM4e8e (Duet Wifi/Eth) processor model, and you're done.
  3. For Arduino UNO boards, select the Atmega AVR architecture, and the atmega328p processor model.
    • Additionally, enable the Enable extra low-level configuration options, and enter the Optional features (to reduce code size) menu.
    • There, uncheck all options. Then press ESC to return to the main menu.
    • If you find errors, read the troubleshooting section.
  4. Press q and then y to exit the application and save the configuration.
  5. This will create a .config file.

Run the following command to compile the firmware:

# Compile the firmware.
make

Question

Have you encountered an error while flashing for the Arduino UNO similar to the following?

/usr/lib/gcc/avr/5.4.0/../../../avr/bin/ld: address 0x800931 of out/klipper.elf section `.bss' is not within region `data'

If so, read the troubleshooting section here.

Before flashing the firmware, we need to identify which "serial devices" correspond to the Arduinos connected to the Raspberry Pi (or Linux PC).

To this end, run the following commands, which will list the serial device IDs of all connected USB devices:

Tip

An easy way to be sure which ID corresponds to a device is to compare the output of the ls -l /dev/serial/by-id/ command before and after plugging it through USB.

There should be a device in the second output which is not in the first output. That one should the device you just plugged in.

# List MCUs by ID.
ls -l /dev/serial/by-id/

# You can also try listing MCUs by path.
# ls -l /dev/serial/by-path/

Now identify the device ID for your MCU. Here are some examples of what yours may look like:

  • Original Arduino UNO: usb-Arduino__www.arduino.cc__0043_557303238313513132A0-if00.
  • UNO "clone": usb-1a86_USB_Serial-if00-port0.
  • Duet 2 WiFi: usb-Klipper_sam4e8e_00323053354B50483031303332303133-if00

Warning

Arduino clones may have duplicated IDs, which will conflict with each other if more than one is connected simultaneously. In this case, list them by path by using the second command above, and replace /dev/serial/by-id/ with /dev/serial/by-path/ in the commands above.

  1. Run the following command, replacing YOUR-ARDUINO-ID-REPORTED-BEFORE with the serial device ID of your Arduino, once for each MCU:
make flash FLASH_DEVICE=/dev/serial/by-id/YOUR-ARDUINO-ID-REPORTED-BEFORE

Question

Have you encountered this error while flashing Klipper on a Duet 2?

No device found on /dev/serial/by-id/usb-Duet3D_Duet-if00
Failed to flash to /dev/serial/by-id/usb-Duet3D_Duet-if00: Error running bossac
make: * [src/atsam/Makefile:63: flash] Error 255

If so, read the troubleshooting section here.

  1. Restart the Klipper service:
sudo service klipper start

# If using systemd:
# sudo systemctl start klipper.service

# If using the user unit:
# systemctl --user start klipper.service
  1. Open Mainsail and check that Klippy has connected to the MCUs successfully (e.g. visit your Pi's IP address, or try http://raspberrypi.local if mDNS is enabled and working).

Using a different board

The procedure to use a different controller board is almost identical, as long as Klipper supports its microcontroller.

You would need to:

  1. Choose the appropriate MCU in the make menuconfig appliction.
  2. Change all pins in Klipper's configuration files to match your board's connections.

Configure the CNC firmware

For this section, you'll need:

  • MCUs with firmware installed.
  • A Raspberry Pi set-up and running, and its IP address
  • Electronic connections between the boards, motors, limit-switches, etc.

Base configuration

Each version of the robot has a defined set of Klipper configuration files. You can get them from this folder at the main repository.

Tip

Look for README.md files in those directories, and the wisdom within.

Because you may have already downloaded the main repository to a directory named pipettin-bot at the home folder, those configurations would be available to you locally at ~/pipettin-bot/code/klipper-setup/configs/.

  1. Copy the base configurations to ~/printer_data/config with the following command: cp -r ~/pipettin-bot/code/klipper-setup/configs/* ~/printer_data/config/
  2. Edit the ~/printer_data/printer.cfg file to select a base configuration that is closest to the robot you are building (e.g. 2x-CNC-Shield, Duet 2 Wifi, single-tool, multi-tool, etc.).

To this end, you may open the main printer.cfg file (i.e. the one at the top-level directory in Mainsail) and include the path of the secondary printer.cfg file, that resides in the folder of the configuration set you selected.

To include it, add a line to the main printer.cfg file looking like this:

[include folder_name/printer.cfg]

Tip

You can also open Mainsail in your browser and upload them on a folder on the MACHINE section. We also recommend to have your own folder in order to create a copy of the following files. By doing that, you can modify them freely and keep a backup.

folder_name.png

Note

If there are other lines including printer.cfg files from other subdirectories, you must comment them out by adding a # symbol, as shown below.

# [include an_old_config/printer.cfg] # Commented out.
[include new_shiny_config/printer.cfg]

Only one printer.cfg file must be included here.

Advanced configuration

This section provides brief explanations of all the configuration files. For a more comprehensive understanding, we highly recommend referring to Klipper's Configuration Reference as it was our source of information for this setup.

Because we have forked Klipper for this project, a few configuration options are explained in the fork's repository at GitLab: https://gitlab.com/pipettin-bot/forks/firmware/klipper

printer.cfg

This file is the central configuration file, it's commonly used to define fundamental settings for your robot.

At this step you may, for example, specify your machine's kinematics (e.g. cartesian_abc), withing in the [printer] section of the file.

The remaining configuration options have been organized into different files, which must be included. These are:

The files must be included with this syntax:

[include some_subdirectory/file_name.cfg]
mcu.cfg

You must add the paths of the serial devices of each controller board in the mcu.cfg file.

If we used two Arduino boards, we would include both of them as shown below:

[mcu] # main mcu, used for the XYZ axes.
serial: /dev/serial/by-id/arduino_id_1  # <-- update this value with yours

[mcu tools] # second mcu, used for the tools.
serial: /dev/serial/by-id/arduino_id_2  # <-- update this value with yours

You can obtain the MCU IDs with the ls -l /dev/serial/by-id/ command, as previously explained.

steppers_xyz.cfg

This file defines settings for different stepper motors (X, Y, Y1, and Z) and end-stops that control the movement of different axes. Each [stepper_...] section contains specific parameters to the corresponding motor configuration.

The pin configuration in this file must reflect exactly the connections made in the electronics assembly guide (specifically the stepper motor and endstop connections sections).

Triple-check the pin assignments in the steppers_xyz.cfg file.

steppers_extruder.cfg

We've set aside this file specifically to configure the stepper motors and end-stops for the micropipette tools, which are configured as "extruders". They contain essentially the same settings as the steppers_xyz.cfg file.

The key distinction lies in the specific pin referencing method required here, because the tools may be connected to a "secondary" MCU.

As mentioned in the 'mcu.cfg' section, the second MCU is labeled as [mcu tools]. Since we've connected the tools' electronics to this second Arduino, the pin referencing should follow this syntax:

step_pin: tools:PD4  # Set the step pin to PD4 from the "tools" MCU.

Note

Note the addition of "´tools:´" right before the pin's name (PD4). This indicates that the pin is on the tools MCU, and not on the main MCU.

home_extruder.cfg

This file sets the homing configuration for homing extruder stepper motors. It defines macros and configurations for homing two different "extruders": extruder (tool 1) and extruder1 (tool 2).

Example:

Note

The use of variables like active for different extruders is for managing the state or status of each extruder.

# Enable p20 extruder stepper homing commands.
[extruder_home extruder]

# Enable p200 extruder stepper homing commands.
[extruder_home extruder1]

# Homing macro for tool T0.
[gcode_macro HOME_T0]
gcode:
  # Let mainsail know that T0 is now active.
  T0
  HOME_EXTRUDER EXTRUDER=extruder

# Homing macro for tool T1.
[gcode_macro HOME_T1]
gcode:
  # Let mainsail know that T1 is now active.
  T1
  HOME_EXTRUDER EXTRUDER=extruder1
macros.cfg

This file defines various macros for setting origins, homing axes, switching between tools, among others.

Info

In Klipper, a macro refers to a sequence of predefined commands grouped together under a single name. These macros simplify complex operations by allowing users to execute a series of commands with a single line of code.

Essentially, instead of manually inputting numerous individual commands every time a specific action is needed, a macro condenses these commands into a single command, making it easier to perform repetitive tasks or abstract complex actions.

# Macros related to the "piper" GCODE-generator module.
[gcode_macro H_T_ALL]
gcode:
  HOME_T0
  HOME_T1

[gcode_macro H_T_P200]
gcode:
  HOME_T0

[gcode_macro H_T_P20]
gcode:
  HOME_T1

[gcode_macro HOME_ALL]
gcode:
  G28 Y
  G28 Z
  G28 X
  HOME_T0
  HOME_T1
mainsail.cfg

The mainsail.cfg file is a configuration file for Mainsail, a Klipper font-end. This file defines various custom G-code macros and settings to control how your robot behaves during certain events such as pausing, resuming, or canceling prints. If these macros are not included, several warnings will appear.

Note

We recommend not to make any modifications to this file.

Current adjustment

In stepper driver circuits, the "reference voltage" limits the maximum current, protecting the motors from overheating. This comes at the cost of reduced torque, which may cause loss of steps in situations requiring it (e.g. when changing tools, placing tips, high acceleration,etc.).

The reference voltage (Vref) in a stepper driver is what limits current flow through your steppers.

The main trade-off here is the following:

  • Limiting the current is a good idea! Their coils will be damaged by the excess heat produced by excess current. Furthermore, the 3D-printed supports for the steppers may waken or deform under this heat.

  • However, a lower current limit will cause loss of steps during high-force moves (i.e. docking tools and placing/ejecting tips).

How hot is too hot for a stepper motor?

A temperature around 60ºC is not terrible. If you can keep your fingers on it for at least one second, then it's not bad for the stepper.

Learn more over here: https://3dprinting.stackexchange.com/a/8485

However, any plastic parts will become softer and probably deform over time if exposed to minor heat. In some versions of the robot, its steppers are secured to the structure using 3D-printed parts. Excess temperature will deform or even melt the plastic parts, so limiting the current may be a great idea in the mid-term.

Check connections

A few checks before powering anything on:

  • Logic: triple-check all connections to endstops and sensors (voltages, polarity, etc.). Any accidental shorts will cause damage to your electronics.
  • Power: triple-check all power connections (voltages, polarity, etc.), ensuring that nothing will catch fire or explode.

Disclaimer

Failing to connect things properly will damage your boards, set something on fire, or possibly cause harm. These guides are provided as is, with no guarantees, and you are responsible for their use.

Pololu drivers

The current limit in the A4988 and DRV8825 divers can be changed by setting their "reference voltage" (i.e. Vref) to an appropriate value.

Tip

The all3DP and E3D guides are very helpful:

Follow these steps to adjust the reference voltage:

  1. Find the maximum current rating of your stepper motors in their specifications or datasheets.
  2. Calculate the reference voltage (Vref) for your stepper drivers and motors (e.g. A4988, DRV8225, and others).
  3. See the guides linked above for details.
  4. Connect the negative end of a multimeter to the controllers GND pin.
  5. Connect the positive end of the multimeter to a small screwdriver.
  6. Locate the Vref adjustment potentiometer on the drivers.
  7. Connect the controller board to the power supply and turn it on.
  8. Adjust the reference voltage using the screwdriver, while reading the voltage on the multimeter.

Tip

If the voltage reading is 0, you may need to connect the microcontroller (in this case an Arduino) to a USB power supply as well.

Tip

If steps are lost at the maximum Vref/current setting, use larger stepper motors. Also consider using a PSU with a voltage that is close to the driver's maximum voltage rating. This helps them produce sharper steps.

01_print_post11.png

TMC drivers

Current limits on the TMC drivers can be set by firmware configuration.

Klipper can set the current limit on TMC drivers. Lots of information can be found here.

TMC2660 drivers are found, for example, in the Duet2 WiFi board that we use in one variant of the Pipettin Bot. To set the current limit, edit the Klipper configuration files accordingly. For example:

[tmc2660 stepper_x]
run_current: 1.5A
#idle_current_percent: 100

Tip

Additonally, it is important to set a "hold current" (or "idle_current_percent") that is high enough. Low hold currents may cause step skipping. The A4988 and DRV8825 drivers do not have this feature, and thus don't cause this issue. Read more about this here.

End-stop adjustments

Endstops are a switch or trigger that is placed at the zero position of each axis so that the a CNC machine knows when the zero position is reached for a given axis.

Info

To learn where the end-stops are and what they do, visit this page.

Machine endstops

Warning

A guide is due.

Chech if you need to adjust:

  • The configuration of end-stops (e.g. active low/high).
  • The position of the X and Y end-stops.
  • The screw on the Z-axis that triggers its end-stop.

Tool endstops

Warning

A guide is due.

Chech if you need to adjust:

  • The position of the tool's opto-endstops (if any).
  • The screws of the parking end-stops (if any).
  • The screw of the tool end-stops (if any).

Tests

Electronics tests

TO DO

A guide is due.

  • Motors.
  • Direction.
  • End-stops.
  • Klipper: use mainsail to check that endstops are triggered when they should (e.g. check their state and trigger them manually).
  • Update CNC configuration if necessary.

CNC tests

Warning

A guide is due.

  • Set the origin by software (avoid homing moves at this stage).
  • Send some commands for small displacements (e.g. G1 X1), check that they turn in the expected directions.
  • Double check the end-stops, parking sensors, or probe sensors.
  • Home the axes one at a time (e.g. G28 X). Hold you finger above the emergency stop button, just in case.
  • Test torque with a tool-change.

Congrats!

You've setup the software and firmware for your robot. That was tough!

You may now:

Troubleshooting

Error while flashing: "address is not within region"

Have you encountered an error while flashing for the Arduino UNO similar to the following?

/usr/lib/gcc/avr/5.4.0/../../../avr/bin/ld: address 0x800931 of out/klipper.elf section `.bss' is not within region `data'

This is because Klipper has not kept up with newer OS libraries, which have made the firmware too large for the Arduino UNO.

We track this problem at this issue, and a workaround has been found here.

To fix this, we need to disable the features we don't need in the .config file, thereby making the firmware smaller.

Note

The .config file is created by the make config config, and does not exist before running it.

Manually edit the .config file in the klipper directory, such that it reads the following:

CONFIG_WANT_GPIO_BITBANGING=n
CONFIG_WANT_DISPLAYS=n
CONFIG_WANT_SENSORS=n
CONFIG_WANT_LIS2DW=n
CONFIG_WANT_SOFTWARE_I2C=n
CONFIG_WANT_SOFTWARE_SPI=n

#
# Optional features (to reduce code size)
#
# end of Optional features (to reduce code size)

CONFIG_CANBUS_FREQUENCY=1000000
CONFIG_HAVE_GPIO=y
CONFIG_HAVE_GPIO_ADC=n
CONFIG_HAVE_GPIO_SPI=y
CONFIG_HAVE_GPIO_I2C=y
CONFIG_HAVE_GPIO_HARD_PWM=y
CONFIG_HAVE_STRICT_TIMING=y
CONFIG_HAVE_LIMITED_CODE_SIZE=y
CONFIG_INLINE_STEPPER_HACK=y

Finally, run make clean and try running make once more.

Note

Even if you disabled all optional features in make menuconfig, some of the edits above are needed anyway. I had to disable CONFIG_HAVE_GPIO_SPI and CONFIG_HAVE_GPIO_I2C, for it to compile. Note that disabling CONFIG_HAVE_GPIO_ADC, which is ok since the UNO does not have GPIO ADC pins, causes a "protocol error" later on with the message Firmware constant 'ADC_MAX' not found.

Lost communication with MCU

This might be due to:

  • Poor power supply on the Raspberry Pi.
  • Bad USB cables.
  • Interference issues (EMI) due to nearby electronics or motor/Pi power supply.
  • Obscure USB connection issues that do now show up on dmesg.
  • Check the bytes_retransmit count in the klipper logfile. If its high, there is a connection quality issue.

There are some guides on this already:

Actions yo may take:

  • Check the links above,
  • Try reducing the baudrate (first in make menuconfig, then re-flash, and set it in the printer.cfg file too).
  • To check if its the Pi's fault, or something else, try connecting the MCU to a PC with Klipper setup (guide here).
  • If you're unable to resolve this, try another Pi, or use a PC.

Error while flashing: "Error running bossac"

This error may show up when running make flash on a Duet board, with more recent Raspbian distributions.

bossac-error

To flash Klipper to a Duet 2 Wifi board yo may need to:

  1. Compile Klipper for the Duet 2 WiFi, setting it to USB mode.
  2. Add a jumper between the "ERASE" pins on the Duet (image below).
  3. Press the RESET button.
  4. Remove the jumper.
  5. Flash Klipper using make flash.

We have some additional notes on flashing klipper on the Duet in GitLab, and a workaround for this issue exists.

jumper-cable-erase-pin-duet2