How to configure the Klipper module

This "How to" is dedicated to the configuration of the SMuFF Klipper Module

Please notice: The method described here is meant to connect the SMuFF controller board via a USB cable to one of the USB ports on your Raspberry Pi, since this is the standard and most convenient method for setting it all up, as shown in the picture to the left, regardless whether you're using a Bowden or DDE configuration on your printer.

Please keep in mind: Even though I'm referencing Mainsail in the description below, the same applies to Fluidd, as both apps act as the presentation layer for Klipper.

Initial install of the files

The first thing you wanna do is to open a SSH session to your Raspberry Pi and log on. Then use these commands on the SSH console:

cd ~

git clone https://github.com/technik-gegg/SMuFF-Klipper.git

cd SMuFF-Klipper

chmod 755 install-smuff.sh

./install-smuff.sh

This will install all the files necessary to control the SMuFF from Klipper.
Next, open moonraker.conf from the Machine section and add the update_manager settings for the SMuFF in order to get automatic updates as I release a newer version. To do so, you can simply copy and paste the contents of the moonraker_update_mananger.txt file on my Github repository for SMuFF-Klipper.

Keep in mind: You may also have to modify the moonraker  [update_manager] section of this file and add the line"enable_repo_debug: True", in case Moonraker claims that this repository is not "pristine".

Now open the smuff.cfg configuration file in Mainsail (also in the Machine section) and set up the serial property so that it reflects the port where your SMuFF is connected to.
You may want to read the description "In order to determine..." down below before you go on with that.

However, you can always come back and change the setting in here if necessary.

Finally, edit your printer.cfg file and add this include somewhere at the top of the file to it:
 [include smuff.cfg]

Reset Klipper after you've finished all steps and if all is going well, the console will spit out the SMuFF firmware info string. 

As you will see while you're editing the smuff.cfg file, there's more than just the module configuration. This files also contains some "convenience" macros, which allow you to add those to the Mainsail Dashboard. Simply add a new group to the Macros section of your Interface Settings and name it SMuFF. Then add all macros you want to see in this panel, for example:

At the very bottom of the smuff.cfg file you'll find an extension for the default display menu, which allows you to control your SMuFF from the display, in case you have one attached to your printers controller. All related functions are located in the >SMuFF sub menu of the main menu.

In order to determine the correct serial port, do this...

udevadm monitor

Make sure your 3D printer is connected to the Raspberry Pi first, then connect the SMuFF to one of the free USB ports on the Raspberry Pi. UDEV is supposed to spit out something like this:

...
UDEV  [2398.910490] add      /devices/platform/scb/fd500000.pcie/pci0000:00/0000:00:00.0/0000:01:00.0/usb1/1-1/1-1.4/1-1.4:1.0/tty/ttyACM2 (tty)
UDEV  [2398.910707] bind     /devices/platform/scb/fd500000.pcie/pci0000:00/0000:00:00.0/0000:01:00.0/usb1/1-1/1-1.4/1-1.4:1.0 (usb)
UDEV  [2398.931582] bind     /devices/platform/scb/fd500000.pcie/pci0000:00/0000:00:00.0/0000:01:00.0/usb1/1-1/1-1.4 (usb)
...

The USB port id (devpath) needed is reported at the very end of the 2nd bind command, for example ".../1-1.4 (usb)". Write this information down, as you're going to need that in the next step.

Please notice: In case you have connected the SMuFF to an USB hub, which connects to the Raspberry Pi, the devpath may also be listed as 1.1.4. In either case, the devpath we need comes after the 1- prefix and must not include the (usb) suffix. 

Change directory to the /etc/udev/rules.d folder and create a new rule set named "98-usb-serial.rules" using, i.e.:

cd /etc/udev/rules.d

sudo nano 98-usb-serial.rules

Then copy & paste in the following line into that file (in some rare case, it can happen that this file already exists containing some other assignment(s). In such case simply append the next line to that file).

Please notice the pink line: You need to use this alternatively in case your SMuFF controller board is not a SKR E3-DIP / V1.2 / V2.0  but one of the newer boards like the SKR E3 V3.0 or E3 RRF, since those boards are using the native STM Vendor-ID (VID) and Product-ID (PID) on the USB port. You also have to have SMuFF firmware version 3.x to run these boards.

SUBSYSTEM=="tty", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0004", ATTRS{devpath}=="1.4", SYMLINK+="ttySMuFF"

or

SUBSYSTEM=="tty", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="5740", ATTRS{devpath}=="1.4", SYMLINK+="ttySMuFF"

Make sure you've entered the correct string into the ATTRS{devpath}, which is the one you've written down from the UDEV monitor (1.4 in this case, excluding the preceding '1-' and the appendix '(usb) '). 

Now save the file and exit nano using Ctrl+S / Ctrl+X, then reboot the Raspberry Pi while leaving the SMuFF and 3D printer connected. After the Raspberry Pi has rebooted, check whether it has recognized the SMuFF right away by re-connecting the SSH session and entering the ls command:

ls -l /dev/ttySMuFF 

lrwxrwxrwx 1 root root 7 Jan 29 11:17 /dev/ttySMuFF -> ttyUSB0

If the device ttySMuFF is not being listed, make sure you go through the procedure shown above once again.

If it's listed, Raspberry Pi is now able to distinguish for which device to create the symbolic link ttySMuFF (which may point to either ttyACM1 / ttyUSB0 or ttyACM0 / ttyUSB1) and you can use that device name for the  serial property in smuff.cfg. 

Please notice: The reason why this procedure is a bit complicated is, if your 3D printer controller is from the same manufacturer as the SMuFF controller (Bigtreetech in this case), the Raspberry Pi can't distinguish which is which because they both come with the same Vendor and Product ID. Hence, it's important to define the exact USB port for the symbolic link.
This also means, whenever you unplug the SMuFF from that particular USB port and plug it back into another port, the Raspberry Pi won't create the ttySMuFF link anymore and the communication between Klipper and SMuFF is disrupted! So, please keep that in mind.
 In case you need to switch the USB port for some reason, run through the procedure above and change the devpath-id in the 98-usb-serial.rules file.

Mandatory settings on SMuFF

In order to make the SMuFF work correctly, you'll need to enable the "Is Shared" option in menu Steppers/Servo -> Feeder and also the "External Ctrl." option. Set both options to "Yes". Keep in mind: The "Is Shared" option requires using the relay board (which you should always have, regardless of the printers controller).

In SMuFF-WebInterface those options are located under Settings->General "Use Shared Stepper" and Settings->Feeder "External Control".

Troubleshooting

In case the SMuFF is not accessible after the configuration of the module, look into the klipper.log file. Messages related to the SMuFF are easy to filter by looking for the "SMUFF" keyword. The easiest way of monitoring live what's going on, is by using the following command in the SSH console:

tail -f ~/klipper_logs/klippy.log | grep -A10 "SMuFF" || "Trace"

With this command only SMuFF related log entries and Tracebacks (Exceptions) are being shown as they occur.