:lang: en
:toc:

[[cha:getting-linuxcnc]]
= Getting LinuxCNC(((Getting LinuxCNC)))

This section describes the recommended way to download
and make a fresh install of LinuxCNC.  There are also
<<sec:_alternate_install_methods,Alternate Install Methods>> for the
adventurous.  If you have an existing install that you want to upgrade,
go to the <<cha:updating-linuxcnc,Updating LinuxCNC>> section instead.

NOTE: LinuxCNC requires a special kernel with real-time extensions.
There are three possibilities here: preempt-rt, RTAI or Xenomai. In
addition there are two versions of LinuxCNC which work with these kernels.
See the table below for details.

Fresh installs of LinuxCNC are most easily created using the Live/Install
Image.  This is a hybrid ISO filesystem image that can be written to a
USB storage device or a DVD and used to boot a computer.  At boot time
you will be given a choice of booting the "Live" system (to run LinuxCNC
without making any permanent changes to your computer) or booting the
Installer (to install LinuxCNC and its operating system onto your
computer's hard drive).

The outline of the process looks like this:

. Download the Live/Install Image.
. Write the image to a USB storage device or DVD.
. Boot the Live system to test out LinuxCNC.
. Boot the Installer to install LinuxCNC.

== Download the image

This section describes some methods for downloading the Live/Install
Image.

[[sec:_normal_download]]
=== Normal Download

For x86 PCs Download the Live/Install CD by clicking here:

https://linuxcnc.org/iso/linuxcnc-2.8.4-buster.iso

For the Raspberry Pi a complete SD card image is available here:

https://linuxcnc.org/iso/linuxcnc-2.8.1-pi4.zip (this will auto-update
to 2.8.4)

This can be installed using the normal Pi
https://www.raspberrypi.org/documentation/installation/installing-images/README.md[install process]
including with the Raspberry Pi Imager app.

This SD image is reported not to work with the Raspberry Pi4 8GB model.
Note also that this version of the SD image limits available memory to
3GB as this is necessary to persuade it to run with both WiFi and USB
working  on some versions of the Pi. You can experiment with removing
this limit by editing the config-rt.txt file in the boot directory. If
you can't boot after the change then the file can be edited back by
mounting the SD card in a a different computer (maybe even a Pi with a
USB card reader).

=== Download using zsync

zsync is a download application that efficiently resumes interrupted
downloads and efficiently transfers large files with small modifications
(if you have an older local copy).  Use zsync if you have trouble
downloading the image using the <<sec:_normal_download,Normal Download>>
method.

.zsync in Linux

* Install zsync using Synaptic or, by running the following in a
  <<faq:terminal,terminal>>
+
----
sudo apt-get install zsync
----

* Then run this command to download the iso to your computer
+
----
zsync https://linuxcnc.org/iso/linuxcnc-2.8.4-buster.iso
----
+
or
+
----
zsync https://linuxcnc.org/iso/linuxcnc-2.8.1-pi4.zip.zsync
----

.zsync in Windows

There is a Windows port of zsync. It works as a console application. It
can be downloaded from:

https://www.assembla.com/spaces/zsync-windows/documents

=== Verify the image

(This step is unnecessary if you used zsync)

. After downloading, verify the checksum of the image to ensure integrity.
+
----
md5sum linuxcnc-2.8.4-buster.iso
----
+
or
+
----
sha256sum linuxcnc-2.8.4-buster.iso
----

. Then compare to these checksums
+
-----
md5sum: 8a6e6abd2c792c3e06fbee0ed049ed41
sha256sum: 0bfeac3ddfe1bdbf5ca4dad84eeec165741d3f253a16b75e4405c06b7b489700
-----

.Verify md5sum on Windows or Mac
Windows and Mac OS X do not come with an md5sum program, but there are
alternatives.  More information can be found at:
https://help.ubuntu.com/community/HowToMD5SUM[How To MD5SUM]

== Write the image to a bootable device

The Raspberry Pi image is a completes SD card image and should be
written to an SD card in
https://www.raspberrypi.org/documentation/installation/installing-images/README.md[the normal way].

The LinuxCNC Live/Install ISO Image is a hybrid ISO image which can
be written directly to a USB storage device (flash drive) or a DVD and
used to boot a computer. The image is too large to fit on a CD.

.Writing the image to a USB storage device in Linux
. Connect a USB storage device (for example a flash drive or thumb
  drive type device).
. Determine the device file corresponding to the USB flash drive.
  This information can be found in the output of `dmesg` after
  connecting the device.  `/proc/partitions` may also be helpful.
. Use the `dd` command to write the image to your USB storage device.
  For example, if your storage device showed up as `/dev/sde`,
  then use this command:
+
-----
dd if=linuxcnc-2.8.4-buster.iso of=/dev/sde
-----

.Writing the image to a USB storage device in Mac OSX
. Open a terminal and type
+
-----
diskutil list
-----

. Insert the USB and note the name of the new disk that appears, eg
  /dev/disk5
. unmount the USB. The number found above should be substituted in place
  of the N
+
-----
diskutil unmountDisk /dev/diskN
-----

. Transfer the data with dd, as for Linux above. Note that the disk name
  has an added "r" at the beginning
+
-----
sudo dd if=/path-to.iso of=/dev/rdiskN bs=1m
-----

. Note that this may take a long time to complete and there will be no
  feedback during the process.

.Writing the image to a DVD in Linux
. Insert a blank DVD into your burner. A 'CD/DVD Creator' or 'Choose
  Disc Type' window will pop up. Close this, as we will not be using it.
. Browse to the downloaded image in the file browser.
. Right click on the ISO image file and choose Write to Disc.
. Select the write speed. It is recommended that you write at the lowest
  possible speed.
. Start the burning process.
. If a 'choose a file name for the disc image' window pops up, just pick
  OK.

.Writing the image to a DVD in Windows
. Download and install Infra Recorder, a free and open source image
  burning program: http://infrarecorder.org/
. Insert a blank CD in the drive and select Do nothing or Cancel if an
  auto-run dialog pops up.
. Open Infra Recorder, and select the
  'Actions' menu, then 'Burn image'.

.Writing the image to a DVD in Mac OSX
. Download the .iso file
. Right-click on the file in the Finder window and select "Burn to disc"
  (The option to burn to disc  will only appear if the machine has an
  optical drive fitted or connected)

== Testing LinuxCNC

With the USB storage device plugged in or the DVD in the DVD drive,
shut down the computer then turn the computer back on. This will boot
the computer from the Live/Install Image and choose the Live boot option.

NOTE: If the system does not boot from the DVD or USB stick it might be
necessary to change the boot order in the PC BIOS.

Once the computer has booted up you can try out LinuxCNC without
installing it. You can not create custom configurations or modify most
system settings in a Live session, but you can (and should) run the
latency test.

To try out LinuxCNC: from the Applications/CNC menu pick LinuxCNC. A
dialog box will open from which you can choose one of many sample
configurations. At this point it only really makes sense to pick a "sim"
configuration. Some of the sample configurations include onscreen
3D simulated machines, look for "Vismach" to see these.

To see if your computer is suitable for software step pulse generation
run the Latency Test as shown <<sec:latency-test,here>>.

At the time of writing the Live-Image is only available with the
preempt-rt kernel and a matching LinuxCNC. On some hardware this might
not offer good enough latency. There is an experimental version available
using the RTAI realtime kernel which will often give better latency.

== Installing LinuxCNC

To install LinuxCNC from the LiveCD select 'Install (Graphical)' at
bootup.

== Updates to LinuxCNC(((Updates to LinuxCNC)))

With the normal install the Update Manager will notify you of updates
to LinuxCNC when you go on line and allow you to easily upgrade with no
Linux knowledge needed.
It is OK to upgrade everything except the operating system when asked to.

[WARNING]
Do not upgrade the operating system if prompted to do so. You
should accept OS _updates_ however, especially security updates.

[[linuxcnc:install-problems]]
== Install Problems(((LinuxCNC:Installation Problems)))(((Installation:Problems)))

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.

[[sec:_alternate_install_methods]]
== Alternate Install Methods(((LinuxCNC:Alternate Install Methods)))(((Installation:Alternate Methods)))

The easiest, preferred way to install LinuxCNC is to use the Live/Install
Image as described above.  That method is as simple and reliable as we
can make it, and is suitable for novice users and experienced users alike.
However, this will typically replace any existing operating system.

In addition, for 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)

[options="header"]
|===
| Distribution   | Architecture  | Kernel     | Package name    | Typical use
| Debian Buster  | amd64 & i386  | Stock      | linuxcnc-uspace | simulation only
| Debian Buster  | amd64 & armhf | preemp-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
| Ubuntu Precise | i386          | RTAI       | linuxcnc        | machine control & simulation
| Ubuntu Precise | amd64 & i386  | Stock      | linuxcnc-uspace | simulation only
|===

NOTE: LinuxCNC v2.8 is not supported on Ubuntu Lucid or older.

.Preempt-RT kernels
The Preempt-rt kernels are available for Debian from the regular debian.org archive.
The preempt-rt kernel for RaspBerry Pi is available from the LinuxCNC repository.
The package is called `linux-image-rt-*`.
Simply install the package in the same way as any other package from the Synaptic Package manager or with `apt-get` at the command-line.

.RTAI Kernels
The RTAI kernels are available for download from the linuxcnc.org debian archive.
The apt source is:

* Debian Buster: `deb https://linuxcnc.org buster base`
* Debian Wheezy: `deb https://linuxcnc.org wheezy base`
* Ubuntu Precise: `deb https://linuxcnc.org precise base`

[NOTE]
Debian Wheezy and Ubuntu Precise are both extremely old, and are out of their support period.
It is strongly advised not to use either for a new install, and to seriously consider upgrading an existing installation.

The Buster / RTAI package is only available on amd64, but there are very few surviving systems that can not run a 64-bit OS.

[WARNING]
There are known issues with the 64-bit RTAI 5.2 kernel with this version of LinuxCNC.
The system will occasionally lock solid.
However, this has, so far, been seen only during system exit.
While running the system appears to be stable.
But should nevertheless be considered experimental at this point.

[NOTE]
If you decide to use the RTAI 5.2 kernel and see a problem outside the circumstances described above,
then please report it immediately to the project developers.

=== Installing on Debian Buster (with Preempt-RT kernel)

. Install Debian Buster (Debian 10), amd64 version. You can download the
  installer here: https://www.debian.org/releases/buster/ .

. After burning the iso and booting up, if you don't want Gnome desktop,
  select 'Advanced Options' > 'Alternative desktop environments' and pick the one you like.

. Then select 'Install' or 'Graphical Install'.

[WARNING]
Do not enter a root password, if you do sudo is disabled and you won't be able to complete the following steps.

. Run the following in a <<faq:terminal,terminal>> to bring the machine up to date with the latest packages.
+
----
sudo apt-get update
sudo apt-get dist-upgrade
----

. Install the Preempt-RT kernel and modules
+
----
sudo apt-get install linux-image-rt-amd64
----

. Re-boot, and select the Linux 4.19.0-9-rt-amd64 kernel (the exact kernel version might be different, look for the "-rt" suffix).
  This might be hidden in the "Advanced options for Debian Buster" sub-menu in Grub.
  When you log in, verify that `PREEMPT RT`is reported by the following command.
+
----
uname -v
----

. Open Applications Menu > System > Synaptic Package Manager,
  search for 'linux-image', right click on the original non-rt and select 'Mark for Complete Removal'.
  Reboot. This is to force the system to boot from the RT kernel.
  If you prefer to retain both kernels then the other kernels need not be deleted,
  but grub boot configuration changes will be needed beyond the scope of this document.

. Add the LinuxCNC Archive Signing Key to your apt keyring by running
+
----
sudo apt-key adv --keyserver hkp://keys.openpgp.org --recv-key 3cb9fd148f374fef
Alternate keyserver: keyserver.ubuntu.com
----

. Add the apt repository:
+
----
echo deb https://linuxcnc.org/ buster base 2.8-rtpreempt | sudo tee -a /etc/apt/sources.list.d/linuxcnc.list
echo deb-src https://linuxcnc.org/ buster base 2.8-rtpreempt | sudo tee -a /etc/apt/sources.list.d/linuxcnc.list
----

. Update the package list from linuxcnc.org
+
----
sudo apt-get update
----

. Install uspace (a reboot may be required prior to installing uspace)
+
----
sudo apt-get install linuxcnc-uspace
----

. Optionally you can install mesaflash if you are using a Mesa card.
+
----
sudo apt install mesaflash
----

[[cha:Installing-RTAI]]
=== Installing on Debian Buster (with experimental RTAI kernel)

[WARNING]
This kernel has known stability problems. It appears to run reliably once LinuxCNC is loaded.
However, kernel panics have been seen at system shut-down.

. This kernel and LinuxCNC version can be installed on top of the LiveDVD install,
  or alternatively on a fresh Install of Debian Buster 64-bit as described above.
. Add the LinuxCNC Archive Signing Key to your apt keyring
  (Not necessary if switching the realtime mode of a LinuxCNC Live-CD image).
+
----
# Alternate keyserver: keyserver.ubuntu.com
sudo apt-key adv --keyserver hkp://keys.openpgp.org --recv-key 3cb9fd148f374fef
----

. Add the apt repository:
+
----
echo deb https://linuxcnc.org/ buster base 2.8-rt | sudo tee /etc/apt/sources.list.d/linuxcnc.list
echo deb-src https://linuxcnc.org/ buster base 2.8-rt | sudo tee -a /etc/apt/sources.list.d/linuxcnc.list
----

. Update the package list from linuxcnc.org
+
----
sudo apt-get update
----

. Install the new realtime kernel, RTAI and the rtai version of linuxcnc
+
----
sudo apt-get install linux-image-4.19.195-rtai-amd64
----

. Install the RTAI application layer
+
----
sudo apt-get install rtai-modules-4.19.195
----

. Install LinuxCNC (may be necessary to reboot before installing)
+
----
sudo apt-get install linuxcnc
----

Reboot the machine, ensuring that the system boots from the new 4.19.195-rtai kernel.

=== Installing on Raspbian 10

. Download a stock Raspbian image to an SD card and install in the
  https://www.raspberrypi.org/documentation/installation/installing-images/README.md[usual way].
. Boot the Pi and open a terminal.
. Add the LinuxCNC Archive Signing Key to your apt keyring.
+
----
# Alternate keyserver: keyserver.ubuntu.com
sudo apt-key adv --keyserver hkp://keys.openpgp.org --recv-key 3cb9fd148f374fef
----

. Add the apt repository:
+
-----
echo deb https://linuxcnc.org/ buster base 2.8-rtpreempt | sudo tee /etc/apt/sources.list.d/linuxcnc.list
-----

. Update the package list from linuxcnc.org
+
----
sudo apt-get update
----

. install the realtime kernel
+
----
sudo apt-get install linux-image-4.19.71-rt24-v7l+
----

. Install linuxcnc (a reboot may be required prior to installing)
+
----
sudo apt-get install linuxcnc-uspace
----

=== Installing on Ubuntu Precise

. Install Ubuntu Precise 12.04 x86 (32-bit). Any flavor should work (regular Ubuntu, Xubuntu, Lubuntu, etc).
  64-bit (AMD64) is currently not supported. You can download the installer here:
  http://releases.ubuntu.com/precise/
  Note the warnings that this release is out of support.
  But it is a way to install LinuxCNC with a well-tested RTAI kernel.

. Run the following to bring the machine up to date with the latest packages in Ubuntu Precise.
+
----
sudo apt-get update
sudo apt-get dist-upgrade
----

. Add the LinuxCNC Archive Signing Key to your apt keyring by running
+
----
# Alternate keyserver: keyserver.ubuntu.com
sudo apt-key adv --keyserver hkp://keys.openpgp.org --recv-key 3cb9fd148f374fef
----

. Add a new apt source
+
----
sudo add-apt-repository "deb https://linuxcnc.org/ precise base 2.8-rt"
----

. Fetch the package list from linuxcnc.org.
+
----
sudo apt-get update
----

. Install the RTAI kernel and modules by running
+
----
sudo apt-get install linux-image-3.4-9-rtai-686-pae rtai-modules-3.4-9-rtai-686-pae
----

. If you want to be able to build LinuxCNC from source using the git repo, also run
+
----
sudo apt-get install linux-headers-3.4-9-rtai-686-pae
----

. Reboot, and make sure you boot into the rtai kernel. When you log in,
  verify that the kernel name is 3.4-9-rtai-686-pae.
+
----
uname -r
----

. Run
+
----
sudo apt-get install linuxcnc
----

// vim: set syntax=asciidoc:
