There are three ways to install RTXI:

Standard
Use our Ubuntu-based live CDs. It's easier than manually installing RTXI, but differences between your system and the one used to make the live CD could affect real-time performance.

Custom
Install a generic Linux image, compile a Xenomai-patched kernel, and then install RTXI from source. It's more difficult, but the end result is better optimized. We recommend this option.

Upgrade
If you already use a previous version of RTXI, you can update your system without recompiling a kernel or reintstalling any of your OS.

1. Download the live RTXI 2.0 image.

We currently have Ubuntu live CDs. You can use them to test RTXI without touching your hard drive, format your hard drive, and install RTXI alongside existing operating systems.

 

Our legacy version, RTXI 1.4, is available for now. Keep in mind that v1.4 runs on the no-longer-maintained Ubuntu 10.04, and it requires now-deprecated libraries.

 

2. Burn the image to a DVD or a USB drive.

You can use whatever DVD burner is available on your operating system. If you want a live USB, you may need additional software. For different operating systems, check out:

Linux
Clone the ISO image from the command line with dd or use applications like UNetbootin or USB Creator. Check your distro's package repository to see if they're available.
Windows
Try LinuxLive USB Creator or UNetbootin.
MacOS
Same programs. Try LinuxLive USB Creator or UNetbootin.

For live-USB-creating applications, look through the instructions on their websites or let their UIs guide you through making a bootable USB image. When prompted for a CD image, point the program to the ISO image you just downloaded, and when prompted for a installation destination, choose a USB drive you inserted into your computer.

We cannot not guarantee these installation programs will produce bootable live USBs for your system. This area tends to be a bit finnicky. Should you have any difficulties, let us know.

 

3. Boot from the live image.

If your computer isn't already set to boot from USB or DVD, you'll need to enter your BIOS settings. When cold-booting your computer, hit the necessary keys, usually F2 or F4, and open the menu. (If you miss the timing, restart your computer and try again.)

From the menu, look for your boot options. There you can manually override the boot order of devices on your system. If you're booting from a DVD or USB, look for your DVD drive or USB label, respectively, and set them to be first in your boot order. Save you changes and exit your BIOS menu.

Reminder: In the next step, you will be installing an operating system on your hard drive. Back up any files that are on it, because depending on how you choose to install Linux, they will be lost once the installation is complete.

 

4. Install RTXI via the installer.

When booting, you can choose to go directly to the installer or boot into the live desktop. The installer will guide you through setting up the system name, passwords, networks, and partitioning. If unsure of what to do, use defaults when available.

 

5. Reboot into RTXI.

When the installer is done, you will be prompted to reboot your system. Reboot (and be careful to not re-enter the live image). RTXI is now installed!

See how your system is performing. You may have graphics issues, but at this point, what do you is specific to your system. Look through our documentation page to see pointers for dealing with graphics issues.

Below is an installation demo. Note that when you install RTXI on your own machine, you may get prompted to configure your network settings.

 

6. Install modules.

By default, a clean installation of RTXI only contains system modules. To use custom modules, you will need to download and install them separately. All RTXI modules are available on our GitHub repository. You can view all our modules and instructions for installing them on our modules page.

1. Download a generic Linux installation image.

You can install RTXI on any Linux distribution you like. Keep in mind that the installation scripts we use work for Ubuntu and Debian. Your distribution may name or organize packages differently, so you'll have to account for that on your own. Below are download links for generic Ubuntu GNOME live CDs.

 

2. Burn the image to a DVD or a USB drive.

You can use whatever DVD burner is available on your operating system. If you want a live USB, you may need additional software. For different operating systems, check out:

Linux
Clone the ISO image from the command line with dd or use applications like UNetbootin or USB Creator. Check your distro's package repository to see if they're available.
Windows
Try LinuxLive USB Creator or UNetbootin.
MacOS
Same programs. Try LinuxLive USB Creator or UNetbootin.
 

3. Follow the built-in installer and install the operating system.

Boot into the live CD. When prompted, start the installation process. There are no special considerations to be made at this step. Installers are generally intuitive, but if you have issues, there is a plethora of information online for how to install various Linux distributions. You can find help for installing Ubuntu GNOME here.

When the installation is finished, reboot and log into your system. Be sure to remove the live media, or you might boot back into the live CD.

Note: You may have to edit your BIOS settings to let you boot from media other than your hard drive. When cold-booting your computer, hit the necessary keys, usually F2 or F4, and open the menu. From the menu, look for your boot options. There you can manually override the boot order of devices on your system. If you're booting from a DVD or USB, look for your DVD drive or USB label, respectively, and set them to be first in your boot order. Save you changes and exit your BIOS menu.

 

4. Clone the RTXI repository using git.

Open a terminal. You can use the applications menu or enter the CTRL+ALT+t shortcut. From the terminal, install the git package. Git is a version control system that can synchronize files over many machines. We use it for developing RTXI source code, which is hosted on GitHub.

$ sudo apt-get install git

Once git is installed, use it to download the RTXI source code and access the source code for v2.0.

$ git clone https://github.com/rtxi/rtxi
$ cd rtxi

Tip: The above code will download the source files to wherever you are in your filesystem. If you are within your own user directory, then the source files will only be accessible to your account, not anyone else's. To download the source code in a central location that all users can access, consider:

$ git clone https://github.com/rtxi/rtxi
$ sudo mv rtxi /home/
$ cd /home
$ sudo find rtxi \( -type d -exec chmod u+rwx,g+rwx,o+rx {} \; -o -type f -exec chmod u+rw,g+rw,o+r {} \; \)
$ cd /home/rtxi/

Note: Don't do this if you have a user named "rtxi". Rename the RTXI folder you cloned to something else.

 

5. Install RTXI and real-time kernel dependencies.

Install the dependencies for RTXI and for installing the real-time (RT) kernel. Assuming you are in the cloned RTXI directory, run:

$ cd scripts
$ ./install_dependencies.sh

The script will run for a while, updating your current packages and installing ones needed later.

 

6. Compile and install the real-time kernel.

From the same directory, run:

$ ./install_rt_kernel.sh

The script will download the sources for the Linux kernel and the Xenomai patch. Before the kernel starts compiling, you will be prompted to edit the kernel config flags. A UI will pop up that looks as follows:

This is the config menu that allows you to edit what you want compiled into the kernel. For optimal performance, edit the following options:

  1. Enable ANALOGY drivers.

    From the top menu, follow the path:
    --> Real-Time sub-system
    --> Drivers
    --> Analogy

    Hit SPACE on all the drivers to have them built into the kernel. A "*" beside the field means that the drivers are set properly. Note that "M" means that the drivers will be built as kernel modules, not built into the kernel itself. "*" is the desired setting here, not "M".

    Hit ESC to get back to the top menu from where you started. Be careful to not exit the configuration menu.

  2. Select your processor type.

    From the top menu, follow the path:
    --> Processor type and features
    --> Processor family

    Select the option that corresponds to your processor type. If unsure of what processor you have, open another terminal run:

    $ cat /proc/cpuinfo

    This will display the CPU information needed to correctly select your configuration. Most newish computers with Intel processors usually have an i3, i5, or i7. For them, select Core 2/newer Xeon.

    Note: For 32-bit systems, Enable -fstack-protector buffer overflow detection should also be disabled

  3. Disable power management options.

    You need to disable some CPU scaling capabilities of the kernel that can otherwise interrupt the real-time framework. From the top menu, follow the path and disable:
    --> Power Management and ACPI options
    --> Suspend to RAM (disable)
    --> Hibernation (disable)
    --> ACPI Support
    --> Processor (disable)
    --> Frequency Scaling (disable)
    --> CPU Idle driver for Intel (disable)
    --> CPU Idle PM support (disable)

    To disable drivers, move the cursor to the item and hit SPACE until the field the left is blank.

  4. Disable COMEDI drivers.

    The COMEDI drivers should be disabled, otherwise they will conflict with the ANALOGY drivers. From the top menu, follow the path and disable:
    --> Device Drivers
    --> Staging Drivers
    --> Data Acquisition (comedi) (disable)

Once all the flags have been set properly, exit to the top menu. Hit ESC again and choose to save the configuration and compile the kernel. Compilation, depending on your system, can take 10 minutes to a few hours. You are free to leave the system. The install_rt_kernel.sh script will compile the kernel and install it automatically. When the script terminates successfully, reboot the system.

From the boot menu, select the "Advanced" option from the GRUB bootloader to open up a submenu that lists all the available kernels. The real-time kernel will be named 3.8.13-xenomai-2.6.3. Select it and boot the system.

 

7. Install RTXI.

Install RTXI with the install_rtxi.sh script. Navigate back to your rtxi/scripts/ directory and rum:

$ ./install_rtxi.sh

Give your password when prompted. The script will also prompt you for an installation mode.

Xenomai
Install RTXI so that it uses the real-time kernel.
Posix (non-rt)
RTXI will not perform in real-time, but with this option, it can be installed this way on systems without a real-time kernel.

If you want real-time performance, enter "1" to use Xenomai and wait for RTXI to be installed. When the installation script terminates, RTXI is ready for you to use. To start RTXI, run:

$ sudo rtxi
 

8. Install modules.

By default, a clean installation of RTXI only contains system modules. To use custom modules, you will need to download and install them separately. All RTXI modules are available on our GitHub repository. You can view all our modules and instructions for installing them on our modules page.

Note: If you are currently using older distributions, like Ubuntu 10.04 and Debian 7, the following instructions will fail because RTXI depends on newer versions of the boost libraries and gcc, which aren't available. Though you can compile these dependencies from source, we recommend you use a newer LTS distro, like Ubuntu 14.04. Incompatibilities with older distros will only increase with time, especially as they exceed their support lifespan.

 

1. Clone the RTXI GitHub repository.

If you haven't already cloned our GitHub repo, run the following in the terminal.

$ git clone https://github.com/rtxi/rtxi.git
$ cd rtxi

If you already have a clone of the repository, go to it and run:

$ git pull origin master
 

2. Install and/or update dependencies.

Run the install_dependencies.sh script to download dependencies. The script is maintained for Ubuntu 14.04. If you are using a different or outdated distribution, like Ubuntu 10.04, you will have to look for differently-named packages. For old operating systems, some of these packages may no longer exist, and if that's the case, we strongly encourage you to upgrade.

$ cd scripts/
$ ./install_dependencies.sh
 

3. Install RTXI 2.0.

Run the installation script, also in the scripts/ directory.

$ ./install_rtxi.sh

You will be prompted to select a configuration: 1 for Xenomai (real-time) or 2 for POSIX (non-real-time). Soon, RTXI will be compiled and installed. When finished, you can run v2.0 with:

$ sudo rtxi

Note: This will not work if you are running an RTAI-patched kernel. To compile RTXI v2.0 for RTAI kernels, see our relevant information on the FAQs section of the documentation page or the full documentation for configuration options.

 

4. Install modules.

All available modules in v1.4 came packaged with RTXI. For v2.0 onwards, modules are split into separate GitHub repositories. Customization also is on a per-module basis. Also, for v1.x, RTXI used the Qt3 framework to build the UI. For v2.0, we moved to Qt4, and with v2.1, we moved to Qt5.

What this means for you is that at this point, you've installed RTXI v2.0, but you need to recompile your modules to use updated dependencies. If you are using the DefaultGUI framework, this may be as simple as recompiling your code, but if you added custom Qt elements, you may need to port your code to reflect changes in Qt.

All modules on the modules page are up-to-date for v2.0. See the following documentation on porting to old Qt code to Qt5.

The final step of any RTXI installation is to benchmark RTXI and the real-time kernel it uses. Tests center around the built-in xenomai latency test and the RT benchmarking module within RTXI. An explanation of what exactly the tests measure is available in our documentation.

 

Xenomai latency test

Go to the base of the RTXI directory you cloned from GitHub and run:

$ cd scripts/dev/
$ ./test_rt_kernel.sh

This script will test kernel latencies at rate of 10 kHz while under stress. The test lasts 30 minutes. If at any point you need to stop the test, you can kill the process by entering CTRL+c in the terminal running the stress test. Then, run pkill stress. If you forget to use pkill, the system will stop measuring latencies, but it will still be under stress. Depending on your system, you may experience lag in your desktop during the test. Keep in mind that the stress test is designed to assess real-time performance under worst-case conditions. If your system performs well under heavy load, you can be reassured that it will perform well during your experiments.

Once completed, the script will generate a histogram of latencies. You can view it from the command line with the image viewer, eog (Eye of GNOME). Run:

$ eog test_rt_plot.svg

For systems with discrete graphics cards and somewhat recent processors, latencies should consistently remain on average below 2-3 μs. Worst case latencies may get as high as 20-30 μs, but keep in mind that these spikes occur often once or twice over the 30 minute duration of the stress test, which at 10 kHz constitutes 18 million cycles. A histogram of latencies will be generated at the end of the test, so you see can how often high latencies occur. Compare your performance to what is available on our stats and benchmarks page and let us know if your performance is problematic.

 

Record the RT benchmarks module

Record the RT Benchmarks module in RTXI using the Data Recorder module. RT Benchmarks displays runtime statistics for your system, such as the computation time, real-time period, and jitter. For those unfamiliar with the terms, here are brief definitions:

Computation Time
The time it takes to compute all the real-time components running, including all modules, data streams, and timers. It should always be less than the real-time period. Otherwise is an overrun.
Real-time Period
The elapsed time for one complete real-time cycle, encompassing the computation time, scheduler, sleep time, etc. This number is set by choosing the frequency in the System Control Panel module. Pay attention to the peak real-time period. A period twice what the period should be constitutes an overrun.
Real-time Jitter
Jitter is the standard deviation of all the real-time periods, starting from when the module was opened or the reset button pressed and ending at the last completed real-time period.

To record the RT Benchmarks module:

  1. Open RTXI and open the Data Recorder and RT Benchmarks module from the System drop-down menu.
  2. In the Data Recorder, click "Choose File" and name the file you want data to be written to.
  3. In the Data Recorder, for "Block," choose "Performance Measurement." For "Type," choose "State." For "Channel", select "Comp Time" and hit "Add." Repeat for the "Real-time Period" and "RT Jitter" channels.
  4. Hit "Start Recording."
  5. When done recording, hit "Stop Recording."
 

Note: You can change the frequency for your measurements via the System Control Panel. Just open the module, change the value for "Frequency," and hit "Apply" to save your changes.

Note: If you set the frequency high or record for a long time, the size of the generated files can become unwieldy. Make liberal use of the downsampling functionality in the Data Recorder.

Open up a terminal and move to your RTXI directory. In the scripts/dev/ folder, you will find a script called plot_rtxi_performance. This script will extract the performance data from an HDF file and plot it using R. To run it, do:

$ ./plot_rtxi_performance.sh FILENAME

FILENAME is the name of the *.h5 file you generated with the Data Recorder. Compare your output with ours, and let us know if you are having performance issues.