Documentation

The RTXI user manual will be available here soon. Until then, look through our tutorials, troubleshooting guides, and faqs on this page for further documentation. For developers, you can also look through our Doxygen pages to get a better understanding of the source code.

 

Getting Started

To get started with RTXI for your experiments, there are some hardware requirements you need to satisfy. They’re pretty easy to meet, and they’ll get you set up with a properly performing RTXI installation.
 

Porting to RTXI v2.1

RTXI v2.3 introduced many changes over the v1.4 release. Most of these changes should have a limited impact on your modules, but even in that case, you will need to make some edits to your code to port it to 2.3. This tutorial will focus on some common changes that should cover most use-cases. The changes mostly have to do with: Upgrading from Qt3 to Qt5 Upgrading Qwt5 to Qwt6 Changes to the DefaultGUIModel class
 

List of Resources

There are a lot of things you need to know to be able to fully use RTXI. Fortunately, these things aren’t hard to learn, and there is already plenty of documentation online to help you learn it. This is a non-exhaustive list of some good resources to learn what you need. They aren’t listed in any specific order.
 

Making New Modules in RTXI

Outlined here is the development process for making new RTXI modules. For simplicity, we provide a template module, called Plugin Template, for users to customize without needing to writing everything from scratch. Plugin Template defines a basic GUI with customizable widgets and is found on our GitHub repository.
 

How to Use Git

Below are instructions for installing and using Git. Git is a version control tool that enables users to track revisions and changes in files and coordinate with collaborators. It is often used for software development.
 

Setting a Default Boot Kernel

It can get annoying choosing the real-time kernel from the submenu every time you boot your computer, especially if you miss the timing and it boots generic Linux.
 

Using Graphics Cards

Choosing graphics cards can be a thorny issue in standard Linux alone, let alone real-time Linux. Often, open-source drivers lag behind proprietary ones in terms of compatibility with newer hardware and displays. The two main types, AMD and Nvidia, are supported for the most part within Linux.
 

What Is Real-time Computing?

In general, an operating system is responsible for managing the hardware resources of a computer. A real-time operating system is a refinement in that it perfoms tasks with extreme precision and reliability. This is important in automated process control systems where a delay can cause a critical failure of the overall system.
 

RTXI Architecture

RTXI uses a two-thread architecture consisting of a real-time (RT) thread and a non-real-time user interface (UI) thread. RTXI can run on single or multiprocessor computers. RTXI consists of both system and custom user modules, each of which spans both threads. RTXI modules communicate and share data in real-time using a system of signals and slots that supports synchronous scheduling, as well as asynchronous event handling. On every clock cycle, the RT thread wakes and signals each active DAQ driver to acquire all active inputs from external experiment hardware. These data are made available to other components while the RT...
 

Using RTXI for Dynamic Clamp

The dynamic clamp is a real-time electrophysiology technique where simulated membrane conductances are artificially injected into a cell via intracellular electrodes. It works by reading membrane potentials, amplifiing, and then feeding them into a dynamic clamp system that contains a model of the desired membrane conductance and generates a current to be injected back into the cell in real time. For digital systems, the membrane conductance is a set of equations that must be computed, whereas for an analog system, the current is the output of a dedicated electrical circuit. The injected dynamic clamp current acts on the cell in...
 

RTXI HDF5 Data Files

The HDF5 file format is a portable and extensible binary data format designed for complex data. It features support for an unlimited variety of datatypes, and has flexible and efficient I/O. HDF5 features a hierarchical structure that allows you to access chunks of data without loading the entire file into memory. An HDF5 file produced by RTXI’s Data Recorder is organized as shown on the right:
 

Manually Configuring RTXI

You can manually configure RTXI with many options. For example, you can run RTXI 2.3 using the RTAI rather than the default Xenomai, and you can set up RTXI in non-real-time mode using the POSIX interface. You may also direct RTXI to libraries/packages in non-standard locations. The full configure options for are below:
 

32 or 64 Bit? Your Processor Explained

64-bit and 32-bit refer to how addresses and memory are handled in different instruction set architectures. For clarity, the terms ‘32-bit’ and ‘64-bit’ have dual meanings. The first refers to the size of addressable chunks of memory. Memory is organized in chunks, called words, that a processor can handle at once. 32 and 64-bit systems respectively handle chunks of memory that are 32 and 64 bits in size. The second meaning refers to the size of the addresses used to catalog all of the addressable points in memory. In other words, each word in memory has an address that the...

Please submit any issues you have on our GitHub repo.

Posting Bugs and Issues on GitHub

RTXI is in active development, and our work depends heavily on user feedback. This tutorial provides instructions for creating bug reports, posting questions about issues, making feature requests, etc. through GitHub. Though email will also work, we strongly encourage using GitHub so that users can see existing issues and contribute to overall discussion. To use GitHub, you will need to create a GitHub account.
 

Linux Freezes after Reboot

If you do an OS-based reboot of your the computer and your log-in screen is laggy or displays errors, it’s probably because kexec-tools are handling reboots. When compiling an RT kernel, you were prompted whether or not to let kexec-tools handle reboots. You are advised in the installation instructions (and here) to not allow that.
 

My System Is Frozen or Slow!

This issue can be caused by many tings, and getting to its specific cause will require patience. Here are some things to look for:
 

Benchmarking Real-time Performance

Here is a list of tools for benchmarking real-time performance, both for the operating system and for the RTXI application itself. In general, you should use these to test newly installed kernels, but you can also use them to help diagnose performance issues experienced when running RTXI.
 
 

1. Why won't RTXI open?

There are several reasons for RTXI to not open.

  1. RTXI is already running.

    If you run rtxi in the terminal and get this output, RTXI is already running:

    $ sudo rtxi
../src/rt_os-xenomai.cpp:123:RT::OS::createTask : failed to create task
../src/rt.cpp:157:RT::System::System : failed to create realtime thread

    The error happens because only one instance of RTXI can be running on the system. Check who is running it by entering:

    $ ps ax -o euser,comm | grep rtxi

    If the command shows someone else's username, that means they have RTXI open. Bug them about closing it or close it yourself by running $ sudo pkill rtxi. Note that workspaces, open files, etc. will not be saved when force-closing RTXI.

    If it's your username, RTXI may not have exited cleanly from sometime earlier. You can run $ sudo pkill rtxi for this case, too.

    Now, you should be able to run RTXI.

  2. You aren't using a real-time kernel.

    Check the kernel you are using. Run this in the terminal:

    $ uname -r

    You will get one line of output that tells you what kernel you are using. If it has the word "xenomai" in it, then it's a real-time kernel. If not, then it isn't.

    If it's not a real-time kernel, you'll have to reboot your computer and pick a real-time kernel in the GRUB boot menu that pops up. If you don't see it, enter the "Advanced options..." submenu and look there.

    Also, see this page about setting a default kernel.

 

2. Why are there negative latencies?

Negative latencies mean that the latency test has not been properly calibrated. The test calculates latencies based on when tasks are expected to be completed, with some overhead going toward computing the timer. To avoid including the time it takes to compute the timer, xenomai offsets the measured latency with a static value, written in nanoseconds and stored in /proc/xenomai/latency. If the value is negative, then xenomai is overcompensating.

You can correct this behavior by running (as root):

# echo 0 > /proc/xenomai/latency

What this means is that the latency test will not try to factor out the time to compute the timer.

 

3. Can I run RTXI in non-real-time?

RTXI can be run in non-real-time to debug your code. This will require that you manually configure and recompile RTXI. In the RTXI directory, go to the scripts directory and run:

$ sudo ./install-rtxi.sh

You will be prompted to enter your system configuration. Select “2” to run in non-real-time (POSIX).

Running RTXI in non-real-time is useful for debugging purposes mainly, and it also allows the application to be installed without having to install a real-time kernel beforehand.

 

4. How do I use more than one DAQ?

RTXI has no built-in software limitations on the number of DAQ cards. You will need to edit the configuration file, however. Here is the relevant excerpt of /etc/rtxi.conf:

<OBJECT component="plugin" library="analogy_driver.so" id="2" >
<PARAM name="0" >/dev/analogy0</PARAM>
<PARAM name="Num Devices" >1</PARAM>
<OBJECT id="13" name="0" />
</OBJECT>

Edit the lines to add another ANALOGY device and change the number of devices:

<PARAM name="0" >/dev/analogy0</PARAM>
<PARAM name="0" >/dev/analogy1</PARAM>
<PARAM name="Num Devices" >2</PARAM>
 

5. Can I use RTAI instead of Xenomai?

We currently do not support RTAI. Earlier versions (1.x) did, but limited time and other development priorities mean we no longer focus any effort on maintaining our RTAI/COMEDI interface.

If you need to use RTXI with RTAI, the old source code is still available for you to use. Just remember that you will need to compile and install an RTAI-patched kernel and the COMEDI drivers for you data acquisition card on your own. You can find the old code in our git history:

$ git clone https://github.com/rtxi/rtxi
$ cd rtxi
$ git checkout 8178f288310377284c1058ca2d188a1a8ae309fc

Look for src/rt_os-rtai.cpp, plugins/comedi_device, and plugins/comedilib_device.

 

6. Can I use a different Linux distribution?

Yes. RTXI has been successfully installed on Ubuntu, openSUSE, Debian, and Fedora. Keep in mind that we use Debian for bugtesting, benchmarking, etc. and that different distributions have different ways of automating scripts, inserting kernel modules, and escalating priveleges.

 
NIH grant R01EB029763
RTXI on GitHub