Skip to content

getting-linuxcnc.adoc

Latest commit

 

History

History
433 lines (346 loc) · 17.9 KB

getting-linuxcnc.adoc

File metadata and controls

433 lines (346 loc) · 17.9 KB

Getting LinuxCNC

Table of Contents

This section describes how to install LinuxCNC version 2.9 on a PC already running Debian Bookworm (Debian 12). Linuxcnc requires the PREEMPT_RT real time kernel to ensure the strict timing required for CNC operations are met. We will also cover how to install Debian Bookworm optimised for Linuxcnc on the x86/AMD64 and ARM64 platforms for first time users. We will also cover some troubleshooting steps and common problems you may experience.

Note
 The PREEMPT_RT kernel is a dependency of LinuxCNC so on most computer platforms, eg AMD64/x86, it will be installed with LinuxCNC. On some platforms such as the Raspberry Pi, it needs to be installed separately. Some environments (eg. Armbian) may support installation of Debian Bookworm but require special procedures to install PREEMPT_RT which are beyond the scope of this document.

There are other versions of LinuxCNC which work with Xenomai and RTAI kernels. See the table at the end of this document for details.

Installing LinuxCNC on Debian 12 or higher

Log in an ordinary user with sudo rights (the normal case) Open a Terminal window and type these commands to ensure your system is up to date:

sudo apt-get update
sudo apt-get dist-upgrade

On a Raspberry Pi, Install the PREEMPT_RT kernel. Type:

sudo apt install linux-image-rt-arm64 linux-headers-rt-arm64

Now install LinuxCNC (any platform)

sudo apt install linuxcnc-uspace linuxcnc-uspace-dev

Optionally you can install mesaflash if you are using a Mesa card:

sudo apt install mesaflash

Reboot and log in again as the same user. Open a terminal window and check PREEMPT_RT is installed

uname -v

PREEMPT_RT should be displayed in the results.

That’s it! You are done! You will find LinuxCNC under the CNC menu.

Install Debian Bookworm on a X86/AMD64 machine

  1. Download Balena Etcher from https://etcher.balena.io/

  2. Download a Debian Boookworm ISO. There are two versions to consider.

    1. The small netinst .ISO that requires a connection to the internet during the installation (recommended) https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-12.0.0-amd64-netinst.iso

    2. The much larger full live install that includes everything in Debian (use if you do not have an internet connection). https://cdimage.debian.org/debian-cd/current-live/amd64/iso-hybrid/debian-live-12.0.0-amd64-xfce.iso

  3. Burn the Debian Image to a USB drive using Balena Etcher

  4. Connect the PC to install Linuxcnc on to a wired internet connection (only use wifi if you must)

  5. Boot the PC from the USB image. This may require changing the boot order to boot from a USB first.

  6. Follow the prompts to install Debian Bookworm

  7. When asked to partition the drive, use all of the available space and install all files on one partition

  8. Do NOT add a password to the root account

    Warning
    		 Do not enter a root password, if you do sudo is disabled and you won’t be able to install software.

  9. When asked to install a desktop environment during the netinst installation , Choose XFCE and deselect other desktops.

  10. When complete, install Linuxcnc following the steps above.

Install Debian Bookworm on a Raspberry Pi

Note
 Raspberry Pis (and most other Single Board Computers, or SBUs) are ARM64 machines. These instructions will feature arm64 kernel and can’t be used for AMD64 machines (which is what many PCs are, including all Intel based machines.)

  1. Download a Debian Bookworm image from https://raspi.debian.net/daily-images/ and burn to an SD card and install in the usual way.

    Note
    		 There have been reported black screen lockout with the "tested" images on some Pis. It may be that removing dtoverlay=vc4-fkms-v3d-pi4 from /boot/config.txt resolves that problem. These instructions were tested using the 2023/05/15 daily build.

  2. Ensure the Pi is connected to the internet. Boot the Pi. It will open a text based terminal

  3. Login using the root account (which does not have a password yet). Type:

root

and hit enter . Add a password to the root user account. Type:

passwd

and allocate a password you will never forget!

Add a new user and allocate a password. I used pi:

adduser pi

Add your user to the sudo group. Type:

usermod -aG sudo pi

To update your system, and install the real time kernel, type the following lines:

apt update
apt upgrade
apt install linux-image-rt-arm64 linux-headers-rt-arm64

To improve performance there are several settings in two places:

To change the startup command line settings, which will be built into /boot/firmware/cmdline.txt we modify an upstream file by typing:

nano /etc/default/raspi-extra-cmdline

and add this to the empty file:

processor.max_cstate=1 isolcpus=2,3

Save and exit nano .. To change configuration settings, which will be built into /boot/firmware/config.txt we modify its upstream file by typing:

nano /etc/default/raspi-firmware-custom

and add to this empty file the following lines:

#dtoverlay=vc4-fkms-v3d-pi4
disable_overscan=1
dtparam=audio=off

Save and exit nano NOTE: These commands (a) use video graphics resources for 3D acceleration (increases performance considerably), (b) don’t overscan (fixes some black border issues), and (c) don’t use audio (unknown performance enhancement)

Warning
 The first command is only tested on RasPi 4 models, and it specifically references pi4. We have commented it out as on one test it seems to cause the Pi to hang. Experiment at your own risk.

  1. Issue the configuration update command, which will take those changes and write them to the /boot/firmware/cmdline.txt and /boot/firmware/config.txt files:

    update-initramfs -u -k all

    1. Install the XFCE graphical environment by typing

apt install task-xfce-desktop

During the install you will need to select a keyboard layout/language, then tab to the "OK" and press Enter.

Don’t panic if the screen display appears corrupt, just wait until completed.

Start the graphical environment

startx
Warning
 If static persists on your screen, the usual cause is an insufficient power supply or a faulty/low quality HDMI cable.
Note
 This has put you into a desktop as root. It is not best practice to work as root. . Reboot. Your graphical environment should start normally. Log in with the non-root username and password you created earlier.

Install Problems

Most problems booting the installation image are due to uefi hardware. Fortunately, Debian Bookworm has significantly better support for uefi systems than earlier versions of Linux.

Sometimes you can tell the BIOS to boot legacy (non-uefi) hardware.

In rare cases you might have to reset the BIOS to default settings if during the Live CD install it cannot recognize the hard drive during the boot up.

Bookworm Tweaks

Basic Tweaks

To make life easy, there are some standard tweaks you can make to Bookworm which should work on both X86 and the pi.

From the menu settings/Power manager set the power settings to suit your needs. You can turn off screen saver and screen lock here Install geany and grub-customizer (x86/AMD64 only):

sudo apt install geany grub-customizer

Finally now geany is installed, enable auto login

sudo geany /etc/lightdm/lightdm.conf

scroll down to about line 126 and uncomment (remove #) both of the following lines and add YOUR login user name. Eg an example for user matt.

autologin-user=matt
autologin-user-timeout=0

PREEMPT_RT Tweaks (x86/AMD64 only)

isolcpus can make a huge difference to latency on some systems because it isolates specific CPU cores so they are purely used by real time threads (eg the linuxcnc servo thread). The instructions below assume a 4 core CPU eg. Celeron, i3, i5 etc) those with 2 cores or more than 4 cores need different isolcpus settings. It is best to never isolate core 0 as it is used for system threads so it already includes a lot of running threads.

Isolate 2 cores for better RT performance on a 4 core machine.

sudo grub-customizer

On the General Settings in the kernel parameters field where it says

quiet

Change to

quiet isolcpus=2,3

Save the config, close grub-customiser and reboot for changes to take effect.

Review Latency

Use latency-histogram instead of latency-test to review latency particularly if you are using a mesa card or ethercat and don;t need a base thread:

latency-histogram --nobase --sbins 1000

How to evaluate latency is covered in the linuxcnc documents Among other things, latency is affected by: BIOS settings; Isolcpus and other boot time settings; Kernel version used

Note
 Optimal latency settings are still subject to review following recent changes to the Linux kernel.

Set fixed ip address - only for mesa card.

Usually we set up the mesa card to have the ip address 10.10.10.10. We need to set a fixed ip address of 10.10.10.1 to the network interface that connects to it. Type:

ip a

to determine the network interface name used for your mesa card. This is usually something like eth0 or enp2s0. Type

sudo geany /etc/network/interfaces

to append the following at the end of the file:

auto enp2s0
iface enp2s0 inet static
address 10.10.10.1
hardware-irq-coalesce-rx-usecs 0

The last line is only required for Intel network cards. It seems to be ignored on non-applicable hardware.

Save and close geany. Reboot to restart the network. Ping the mesa card to confirm it’s all working

ping 10.10.10.10

Updating Linuxcnc on Debian Bookworm (X86 only)

The version of linuxcnc in Bookworm is a bit dated because of the freeze process associated with the Debian release process. Fortunately, there is a Linuxcnc buildbot which rebuilds version 2.9 packages whenever the code base changes. We can "trick" Debian to get the linuxcnc repositories from this source. These instructions assume you have already installed linuxcnc from the Debian Bookworm repositories.

Start by creating a new configuration file to set a higher priority to our linuxCNC files than the default Debian repositories.

sudo nano /etc/apt/preferences.d/99linuxcnc-uspace

Then copy the following content into this file

package: linuxcnc-uspace
pin: release o=http://buildbot2.highlab.com/debian/
Pin-Priority: 500

package: linuxcnc-uspace-dev
pin: release o=http://buildbot2.highlab.com/debian/
Pin-Priority: 500

package: linuxcnc-uspace-doc-en
pin: release o=http://buildbot2.highlab.com/debian/
Pin-Priority: 500

package: linuxcnc-uspace-doc-de
pin: release o=http://buildbot2.highlab.com/debian/
Pin-Priority: 500

package: linuxcnc-uspace-doc-es
pin: release o=http://buildbot2.highlab.com/debian/
Pin-Priority: 500

package: linuxcnc-uspace-doc-fr
pin: release o=http://buildbot2.highlab.com/debian/
Pin-Priority: 500

package: linuxcnc-uspace-doc-zh-cn
pin: release o=http://buildbot2.highlab.com/debian/
Pin-Priority: 500

Hit Control-O, Y, Control-X to save the file and exit nano. Then type the following commands. . Before starting, you may wish to run linuxcnc from the command line and note the version number displayed as it loads. Exit the linuxcnc chooser and note the version number. Then type the following commands:

cd ~/Downloads
wget http://buildbot2.highlab.com/buildbot-archive-key.gpg
sudo cp ./buildbot-archive-key.gpg /etc/apt/trusted.gpg.d
sudo echo "deb http://buildbot2.highlab.com/debian/ bookworm 2.9-uspace" | sudo tee -a /etc/apt/sources.list.d/linuxcnc.list
sudo apt update
sudo apt upgrade

The second last line updates Linux to look at our buildbot.

The last line upgrades all Linux programs including our Linuxcnc files.

Repeat running linuxcnc and note the version. It should have changed to the latest version (which can change daily).

Now any time you wish to update your version of linuxcnc (and any other Debian programs installed on your PC, just type:

sudo apt update
sudo apt upgrade

Realtek network drivers

Some users have been reporting significant error finishing read issues with some Realtek NIC’s.

There are two additional device drivers available in Debian for realtek cards;

r8125-dkms for 2.5 Gb network cards - RTL8125, RTL8125B(S)(G)

r8168-dkms for the following network cards RTL8111B/RTL8111C, RTL8111D/RTL8111E, RTL8111F/RTL8111G(S), RTL8111H(S), RTL8118(A)(S), RTL8119i, RTL8111L, RTL8111K, RTL8168B, RTL8168E, RTL8168H, RTL8111DP, RTL8111EP, RTL8111FP, RTL8411/RTL8411B, RTL8101E, RTL8102E, RTL8103E, RTL8105E, RTL8106E, RTL8107E, RTL8401, RTL8402

Installing the r8168-dkms driver improved network latency by 400% on our R8111 network card. Similar results were reported on other affected hardware.

The r8168-dkms and r8125-dkms drivers are in the non-free packages which are not included in sources.list by default.

You can see your driver if you type the following to identify your NIC name:

ip a

Now display the NIC info eg:

sudo apt install ethtool
ethtool -i enps02

If it seems you could benefit from this driver, continue Type:

sudo geany /etc/apt/sources.list

Append a space followed by non-free to each of the 4 lines that end with firmware-non-free as follows:

deb http://deb.debian.org/debian/ bookworm main non-free-firmware non-free
deb-src http://deb.debian.org/debian/ bookworm main non-free-firmware non-free
deb http://security.debian.org/debian-security bookworm-security main non-free-firmware non-free
deb-src http://security.debian.org/debian-security bookworm-security main non-free-firmware non-free

Save and close geany. Type:

sudo apt update

you now need to install some utilities. Type:

sudo apt install build-essential dkms

If you have not installed a later kernel as described above install linux-headers. Type:

sudo apt install linux-headers-$(uname -r)

You can now install the r8168 or R8125 driver. Depending on your driver Type:

sudo apt install r8168-dkms

or type:

sudo apt install r8125-dkms

Reboot and check you still have a network driver with

ip a

Check you can still ping the mesa card

ping 10.10.10.10

If you have to remove this driver, it needs to be purged completely or you will have no network. Eg.

sudo apt purge r8168-dkms

Installing a later kernel

Since the release of Debian Bullseye (Linux kernel 5.10), real time performance has been disappointing. In particular, network latency when communicating with a Mesa ethernet card has been generating Error Finishing Read Errors. This means that the network latency left insufficient time for the servo thread cycle to complete in time.

This appears to have been more prevalent with Realtek Network interfaces. Fortunately, each iteration of the Linux kernel has improved results, particularly since the release of 6.x kernels. Debian Bookworm (Debian 12) is using the 6.1 kernel which is quite good. In our testing, we found that latency improved by 265% if we used the 6.3 kernel. We have compiled this version of the kernel for your convenience. This image was updated to the final 6.3 kernel on 1 May 2023 and may be updated form time to time.

Only try installing it if you have exhausted all options by following the steps below:

  1. Download the 2 deb files (image, source) from FIX_ME - can these be hosted on a LinuxCNC server? https://drive.google.com/drive/folders/1NzQIHnf9M_cHzuZCqSldVFGschOOxaER?usp=sharing

  2. The link above is to the latest kernel versions that have been built following the final release of 6.3 kernel and the matching preempt_rt patches.

  3. Navigate to your Downloads folder and open a new Terminal session. Install the debs as follows (pressing tab auto completes the command)

    dpkg -i linux-source(tab)
dpkg -i linux-image(tab)

  4. Reboot into the new kernel

  5. Check that uname -v shows the 6.3 kernel is installed

  6. If it isn’t, use grub-customizer mentioned earlier to change the kernel boot order and reboot again

Alternate Install Methods

The easiest, preferred way to install LinuxCNC is to use the Live/Install Image or Debian Bookworm as described above. Both methods are as simple and reliable as we can make it, and are suitable for novice users and experienced users alike. Both methods will typically replace any existing operating system on your hard drive.

Experienced users who are familiar with Debian system administration (finding install images, manipulating apt sources, changing kernel flavors, etc), new installs are supported on following platforms: ("amd64" means "64-bit", and is not specific to AMD processors, it will run on any 64-bit x86 system) Note that in Debian Bookworm, the preempt_rt kernel is a dependency of linuxcnc-uspace so it is automatically installed with linuxcnc so the Stock kernel is not listed.

If you wish to use RTAI or Xenomai, please follow the instructions in the Linuxcnc V2.8 documentation.

Distribution Architecture Kernel Package name Typical use

Debian Bookworm

amd64 & arm64

preempt-rt

linuxcnc-uspace

machine control & simulation

Debian Buster

amd64 & arm64

preempt-rt

linuxcnc-uspace

machine control & simulation

Debian Buster

amd64

RTAI

linuxcnc

machine control (known issues)

Debian Jessie

amd64 & i386

Stock

linuxcnc-uspace

simulation only

Debian Wheezy

i386

RTAI

linuxcnc

machine control & simulation

Debian Wheezy

amd64 & i386

Preempt-RT

linuxcnc-uspace

machine control & simulation

Debian Wheezy

amd64 & i386

Stock

linuxcnc-uspace

simulation only
Note
 LinuxCNC v2.8 and above is not supported on Ubuntu Lucid or older.