Klipper-mcu Service Fails to Start

Knowledge Base
1

Background

The klipper-mcu process fails to start on certain Linux distributions, even when the relevant documentation is carefully followed.

This issue primarily affects Armbian Linux distributions or those based on Armbian.

Diagnosing the issue

The easiest way to recognize this problem is in the klippy.log where an error message like

mcu 'rpi': Unable to open port: [Errno 2] No such file or directory: '/tmp/klipper_host_mcu'

will appear.

Further issuing the command:

systemctl status klipper-mcu

yields following result:

klipper@bigtreetech-cb1:~# systemctl status klipper-mcu
● klipper-mcu.service - Starts the MCU Linux firmware for klipper on startup
     Loaded: loaded (/etc/systemd/system/klipper-mcu.service; enabled; preset: enabled)
     Active: activating (auto-restart) (Result: exit-code) since Mon 2023-12-11 19:39:56 CET; 4s ago
       Docs: https://www.klipper3d.org/RPi_microcontroller.html
    Process: 2408 ExecStart=/usr/local/bin/klipper_mcu -r -I ${KLIPPER_HOST_MCU_SERIAL} (code=exited, status=255/EXCEPTION)
   Main PID: 2408 (code=exited, status=255/EXCEPTION)
        CPU: 6ms

and finally, the commands:

sudo service klipper-mcu restart
# Wait around 30 seconds before issueing the following command:
sudo journalctl -u klipper-mcu

Produces following output:

Dec 11 19:17:48 cb1 systemd[1]: Started klipper-mcu.service - Starts the MCU Linux firmware for klipper on startup.
Dec 11 19:24:47 cb1 systemd[1]: Stopping klipper-mcu.service - Starts the MCU Linux firmware for klipper on startup...
Dec 11 19:24:48 cb1 systemd[1]: klipper-mcu.service: Deactivated successfully.
Dec 11 19:24:48 cb1 systemd[1]: Stopped klipper-mcu.service - Starts the MCU Linux firmware for klipper on startup.
Dec 11 19:24:48 cb1 systemd[1]: Started klipper-mcu.service - Starts the MCU Linux firmware for klipper on startup.
Dec 11 19:24:48 cb1 klipper_mcu[1934]: Got error -1 in sched_setscheduler: (1)Operation not permitted
Dec 11 19:24:48 cb1 systemd[1]: klipper-mcu.service: Main process exited, code=exited, status=255/EXCEPTION
Dec 11 19:24:48 cb1 systemd[1]: klipper-mcu.service: Failed with result 'exit-code'.
Dec 11 19:24:53 cb1 systemd[1]: klipper-mcu.service: Scheduled restart job, restart counter is at 1.
Dec 11 19:24:53 cb1 systemd[1]: Stopped klipper-mcu.service - Starts the MCU Linux firmware for klipper on startup.
Dec 11 19:24:53 cb1 systemd[1]: Started klipper-mcu.service - Starts the MCU Linux firmware for klipper on startup.
Dec 11 19:24:53 cb1 klipper_mcu[1937]: Got error -1 in sched_setscheduler: (1)Operation not permitted

The key error message here is:

Dec 11 19:24:53 cb1 klipper_mcu[1937]: Got error -1 in sched_setscheduler: (1)Operation not permitted

Reason for the error

To achieve highly precise timing, the klipper_mcu is operated in real-time mode. However, the kernel of these distributions requires Real-Time Group Scheduling, which is incompatible with systemd and causes relevant calls to fail.

Temporary Fix

To test the solution, a temporary fix can be deployed by issuing the command:

sudo sysctl -w kernel.sched_rt_runtime_us=-1
sudo service klipper-mcu restart

If now the service starts successfully, which can be again verified with systemctl status klipper-mcu, the fix can be made permanent.

Permanent Fix

Adjusting kernel parameters should only be done after confirming that this approach effectively solves the problem. Run the following command to make the changes permanent:

echo "kernel.sched_rt_runtime_us = -1" | sudo tee /etc/sysctl.d/10-disable-rt-group-limit.conf
# Now reboot the system to verify 
sudo reboot now

Credits go to @Piezo for this fix.

8 Likes