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

Info

More details available at Klipper's documentation.

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

  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.
  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 path.
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 command below.

  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
  1. Restart the Klipper service:
sudo service klipper start
  1. Open Mainsail (e.g. visit http://raspberrypi.local) and check that Klippy has connected to the MCUs successfully.

Using a different board

Thanks to Klipper, the procedure is almost identical.

You 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. 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.).

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

Then, you should 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]

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

First you should search for the MCU's ID with the ls -l /dev/serial/by-id/ command, as previously explained.

You must then include the "id" of each Arduino Uno boards 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
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 section ([stepper_x], [stepper_y], etc.) contains specific parameters to the corresponding motor configuration.

You must configure the same pins that you connected in the electronics assembly guide, specifically the stepper motor connection's section.

If you connected something differently, adjust 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 tools. However, it essentially contains the same settings as the steppers_xyz.cfg file

The key distinction lies in the specific pin referencing method required here, because the tools are connected to the "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

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 is a a 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.

# p20 extruder stepper homing
# Config section for the new extruder_homing.py extras module.
[extruder_home extruder]

# p200 extruder stepper homing
# Config section for the new extruder_homing.py extras module.
[extruder_home extruder1]

# Macros for mainsail groups
[gcode_macro HOME_T0]
gcode:
  # Use mainsail's "tool change macro" (pasted below for reference).
  T0
  HOME_EXTRUDER EXTRUDER=extruder

[gcode_macro HOME_T1]
gcode:
  # Use mainsail's "tool change macro" (pasted below for reference).
  T1
  HOME_EXTRUDER EXTRUDER=extruder1
macros.cfg

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

# 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

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.

mainsail.cfg

The mainsail.cfg file is a configuration file for Klipper firmware, specifically designed to work with the Mainsail user interface. 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.

In short, manually edit the .config file in the klipper directory such that it reads the following:

Note

The .config file is created by make config. We need to disable the features we don't need, thereby making the firmware smaller.

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
CONFIG_NEED_SENSOR_BULK=y

#
# 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=n
CONFIG_HAVE_GPIO_I2C=n
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.