RTXI

RTXI 3.0.0 Released!

Thu, 30 Nov 2023 00:00:00 -0500

RTXI v3.0.0 is now available

This release modernizes RTXI architecture and leverages newer techniques on performance and maintainability patterns.

The need for these updates originates primarily from the difficulty of updating RTXI 2.4 to the new Xenomai API, as well as the unfortunate news that the Analogy drivers used for hardware access would not be supported any longer under Xenomai. These and other architectural issues made it necessary to apply the lessons learned from years of use to improve software architecture and flexibility. This update relies on proven methods, and uses existing code to create a modern RTXI application. Some of the changes introduced: New Functionality

- New abstractions that reduces user and developer cognitive load
- Introduces a new scheduler and connector classes for faster and more accurate plugin real-time scheduling
- A redesign of the event system to have stronger typing and safer abstractions
- Support for the newest Xenomai framework now called EVL
- Introduction of new DAQ driver model to support non Analogy devices
- Support for National Instruments DAQ PCIe devices
- Introduction of the Real-Time Platform Abstraction Layer (RTPAL) for non Xenomai real-time support
- Automatic driver and real-time platform detection scheme for ease of use
- Central logging system to capture events fired by RTXI components and plugins
- Retire the DefaultGuiModel classes and introduction of the widget classes (plugin, component, and panel)
- Migration from autotools build system to cmake
- Update to installation instructions for both main RTXI components and DSO plugins
- Major updates to the builtin plugins such as data recorder and oscilloscope
- and many more

You can download the new version at the repository and run the install_rtxi.sh script. Test it out and let us know what you think.

Happy sciencing!

RTXI 2.3 Release

Thu, 22 Jul 2021 00:00:00 -0400

A new version of RTXI is now available!

New features include:

Support for New Linux LTS Base: Now RTXI 2.3 runs on Ubuntu 20.04 LTS.
Support for Xenomai 3.1: RTXI can now be installed with Xenomai 3.1; A newer version of the real-time framework.
Minor Bug fixes: for improved stability and long term maintenance

Along with the newer version of rtxi there are also updated installation steps and website contact information. Let us know if you have any issues installing RTXI by emailing us at help@rtxi.org

Getting Started

Wed, 01 Jan 2020 00:00:00 -0500

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.

If you are not familiar with RTXI or what it can do, we recommend looking through the manual first.

You will need:

Computer
Data acquisition card (DAQ)
Graphics card (may come with computer)

Computer

Most computers built in the last few years will run Linux, but some will perform better for real-time applications. Here are some points to consider when buying new hardware:

What is the CPU type? We recommend using Intel processors, though AMD ones work, too.
How many PCI/PCIe slots are there? Most computers now come with only PCIe slots, so make sure to get a PCIe compatible DAQ card. Currently RTXI only supports National Instrument DAQ cards.

Also, you should have a machine with at least 4 GB of RAM. While Linux can run with less, you will see degraded performance. Over the past few years, operating systems have been built under the assumption of increasingly capable hardware, and Linux has been no exception.

DAQ

RTXI is tested and developed on systems using National Instruments (NI) cards. The Xenomai project may still support PCI cards, but not PCIe, and we do not test them so we cannot give you a recommendation to use them. Instead we advice downloading and installing the NIDAQmx library, which supports a wide range of National Instruments DAQ cards and is the interface used by RTXI. Here are a list of resources for downloading and installing NIDAQmx:

Graphics Card

NOTE: The information in this section was compiled over a decade ago, and a lot has changed since then. Nvidia now provides better support for linux drivers. Research whether your graphics card has driver support for linux.

You should get a discrete graphics card. Using integrated graphics will cause UI computation to be offloaded to the CPU, which at the same time has to handle real-time processes. Based on the systems we’ve benchmarked so far, you’re better off using an AMD card than an Nvidia one. You are also recommended to use open-source drivers instead of their proprietary counterparts.

What this means for you is that when buying/acquiring a computer, you need to check the type of graphics card it has. You also need to check whether it is supported by open-source drivers. (Often, newer hardware needs some time for the people who code the drivers to extend support for them.)

Here is a list of graphics card supported by the Nvidia open-source driver (nouveau) and the AMD one (radeon):

Installing RTXI

Look through our installation instructions to see how to install RTXI 3.0.0. If you run into issues, look through our available documentation, and if it doesn’t help, email us or submit an issue on GitHub. We recommend you do the latter.

Note

Let us know if any links are broken. They are all supposed to point directly to lists of hardware compatible with drivers. If they don’t, something went terribly wrong, and we need to fix the links.

RTXI 2.2 Released

Tue, 09 Jan 2018 00:00:00 -0500

New version with long-term support and a new real-time kernel!

New features:

New Linux Base: RTXI 2.2 runs on Ubuntu GNOME 16.04 LTS - with it, you’ll get a stable desktop with hardware and software support for the next few years through Ubuntu and the RTXI team.
Enhanced Performance: We’ve upgraded to the latest version of Xenomai - which includes a number of under-the-hood updates to the real-time system, but still the same robust performance.

Try out v2.2. You can use the live CD to demo RTXI and later install it, or you can install a generic Linux distribution of your choice and use our installation scripts. We’ve included two different live CDs - one for Core 2/Newer Xeon processors and one for generic x64 processors.

Look through all the documentation on the website to find installation instructions, notes on hardware configurations, RTXI modules, documentation, and more. Let us know if you have issues or questions.

Technical overview of RTXI

Thu, 01 Jun 2017 00:00:00 -0400

Ever been curious about how RTXI works? Check out the new paper recently published in PLOS Computational Biology:

Patel, Y.A., George, A., Dorval, A.D., White, J.A., Christini, D.J. and Butera, R.J., 2017. Hard real-time closed-loop electrophysiology with the Real-Time eXperiment Interface (RTXI). PLOS Computational Biology, 13(5), p.e1005430.

Kilohertz frequency nerve block enhances anti-inflammatory effects of vagus nerve stimulation

Thu, 05 Jan 2017 00:00:00 -0500

Efferent activation of the cervical vagus nerve (cVN) dampens systemic inflammatory processes, potentially modulating a wide-range of inflammatory pathological conditions. In contrast, afferent cVN activation amplifies systemic inflammatory processes, leading to activation of the hypothalamic-pituitary-adrenal (HPA) axis, the sympathetic nervous system through the greater splanchnic nerve (GSN), and elevation of pro-inflammatory cytokines. Ideally, to clinically implement anti-inflammatory therapy via cervical vagus nerve stimulation (cVNS) one should selectively activate the efferent pathway. Unfortunately, current implementations, in animal and clinical investigations, activate both afferent and efferent pathways. We paired cVNS with kilohertz electrical stimulation (KES) nerve block to preferentially activate efferent pathways while blocking afferent pathways. Selective efferent cVNS enhanced the anti-inflammatory effects of cVNS. Our results demonstrate that: (i) afferent, but not efferent, cVNS synchronously activates the GSN in a dose-dependent manner; (ii) efferent cVNS enabled by complete afferent KES nerve block enhances the anti-inflammatory benefits of cVNS; and (iii) incomplete afferent KES nerve block exacerbates systemic inflammation. Overall, these data demonstrate the utility of paired efferent cVNS and afferent KES nerve block for achieving selective efferent cVNS, specifically as it relates to neuromodulation of systemic inflammation.

Illuminating Myocyte-Fibroblast Homotypic and Heterotypic Gap Junction Dynamics Using Dynamic Clamp

Tue, 23 Aug 2016 00:00:00 -0400

Fibroblasts play a significant role in the development of electrical and mechanical dysfunction of the heart; however, the underlying mechanisms are only partially understood. One widely studied mechanism suggests that fibroblasts produce excess extracellular matrix, resulting in collagenous septa that slow propagation, cause zig-zag conduction paths, and decouple cardiomyocytes, resulting in a substrate for cardiac arrhythmia. An emerging mechanism suggests that fibroblasts promote arrhythmogenesis through direct electrical interactions with cardiomyocytes via gap junction (GJ) channels. In the heart, three major connexin (Cx) isoforms, Cx40, Cx43, and Cx45, form GJ channels in cell-type-specific combinations. Because each Cx is characterized by a unique time- and transjunctional voltage-dependent profile, we investigated whether the electrophysiological contributions of fibroblasts would vary with the specific composition of the myocyte-fibroblast (M-F) GJ channel. Due to the challenges of systematically modifying Cxs in vitro, we coupled native cardiomyocytes with in silico fibroblast and GJ channel electrophysiology models using the dynamic-clamp technique. We found that there is a reduction in the early peak of the junctional current during the upstroke of the action potential (AP) due to GJ channel gating. However, effects on the cardiomyocyte AP morphology were similar regardless of the specific type of GJ channel (homotypic Cx43 and Cx45, and heterotypic Cx43/Cx45 and Cx45/Cx43). To illuminate effects at the tissue level, we performed multiscale simulations of M-F coupling. First, we developed a cell-specific model of our dynamic-clamp experiments and investigated changes in the underlying membrane currents during M-F coupling. Second, we performed two-dimensional tissue sheet simulations of cardiac fibrosis and incorporated GJ channels in a cell type-specific manner. We determined that although GJ channel gating reduces junctional current, it does not significantly alter conduction velocity during cardiac fibrosis relative to static GJ coupling. These findings shed more light on the complex electrophysiological interplay between cardiac fibroblasts and myocytes.

Cell-specific Dynamic Clamp analysis of the role of funny I f current in cardiac pacemaking

Mon, 21 Dec 2015 00:00:00 -0500

We used the Dynamic Clamp technique for i) comparative validation of conflicting computational models of the hyperpolarization-activated funny current, If, and ii) quantification of the role of If in mediating autonomic modulation of heart rate. Experimental protocols based on the injection of a real-time recalculated synthetic If current in sinoatrial rabbit cells were developed.

Preliminary results of experiments mimicking the autonomic modulation of If demonstrated the need for a customization procedure to compensate for cellular heterogeneity. For this reason, we used a cell-specific approach, scaling the maximal conductance of the injected current based on the cell’s spontaneous firing rate. The pacemaking rate, which was significantly reduced after application of Ivabradine, was restored by the injection of synthetic current based on the Severi-DiFrancesco formulation, while the injection of synthetic current based on the Maltsev-Lakatta formulation did not produce any significant variation. A positive virtual shift of the If activation curve, mimicking the Isoprenaline effects, led to a significant increase in pacemaking rate (+17.3 ± 6.7%, p < 0.01), although of lower magnitude than that induced by real Isoprenaline (+45.0 ± 26.1%). Similarly, a negative virtual shift of the activation curve significantly lowered the pacemaking rate (−11.8 ± 1.9%, p < 0.001), as did the application of real Acetylcholine (−20.5 ± 5.1%).

The Dynamic Clamp approach, applied to the If study in cardiomyocytes for the first time and rate-adapted to manage intercellular variability, indicated that: i) the quantitative description of the If current in the Severi-DiFrancesco model accurately reproduces the effects of the real current on rabbit sinoatrial cell pacemaking rate and ii) a significant portion (50–60%) of the physiological autonomic rate modulation is due to the shift of the If activation curve.fferent activation of the cervical vagus nerve (cVN) dampens systemic inflammatory processes, potentially modulating a wide-range of inflammatory pathological conditions. In contrast, afferent cVN activation amplifies systemic inflammatory processes, leading to activation of the hypothalamic-pituitary-adrenal (HPA) axis, the sympathetic nervous system through the greater splanchnic nerve (GSN), and elevation of pro-inflammatory cytokines. Ideally, to clinically implement anti-inflammatory therapy via cervical vagus nerve stimulation (cVNS) one should selectively activate the efferent pathway. Unfortunately, current implementations, in animal and clinical investigations, activate both afferent and efferent pathways. We paired cVNS with kilohertz electrical stimulation (KES) nerve block to preferentially activate efferent pathways while blocking afferent pathways. Selective efferent cVNS enhanced the anti-inflammatory effects of cVNS. Our results demonstrate that: (i) afferent, but not efferent, cVNS synchronously activates the GSN in a dose-dependent manner; (ii) efferent cVNS enabled by complete afferent KES nerve block enhances the anti-inflammatory benefits of cVNS; and (iii) incomplete afferent KES nerve block exacerbates systemic inflammation. Overall, these data demonstrate the utility of paired efferent cVNS and afferent KES nerve block for achieving selective efferent cVNS, specifically as it relates to neuromodulation of systemic inflammation.

RTXI Fall Newsletter

Fri, 09 Oct 2015 00:00:00 -0400

There have been lots of new developments in RTXI over the past few months. Look forward to the upcoming release of RTXI 2.1, and we encourage those of you attending SfN 2015 to check out our poster!

Upcoming Features in RTXI 2.1

New Plotting Tools - We’ve created a new analysis-tools module that will directly plot HDF data saved by the data recorder.
UI Upgrades - We’ve upgraded RTXI’s UI framework from Qt4 to Qt5, the most up-to-date version available.
Bugfixes and Tweaks - RTXI is continually improving under the hood, and for 2.1, we bundled in lots of bugfixes, UI tweaks, and performance enhancements.
Improved User-friendliness - RTXI now checks for updates, and the new module-installer makes finding and installing the modules you need easier than ever.
Arduino Support - The new Arduino module provides an interface between RTXI and Arduino computers. Note that this is non-RT.
New Module Installer - A new Module Installer allows you to find and install modules within RTXI itself.

Check us out at SfN:

We’ll be presenting a poster at this year’s Society for Neuroscience Conference. If you’re also attending, feel free to stop by. Look out for poster 267.23 / BB66 during the 1:00 -5 :00 PM session on October 18. We’ll be in Hall A.

Contact Us:

You can reach out to us via email and through GitHub. Let us know if you have any questions or issues. We’re around 24/7, and we’ll do whatever we can to get RTXI working for you. We’ll even come to you in person.

IKr Impact on Repolarization and Its Variability Assessed by Dynamic-Clamp

Tue, 23 Jun 2015 00:00:00 -0400

Repolarization and its stability are exquisitely sensitive to IKr features. Information on the relative importance of specific IKr abnormalities is missing and would assist in the evaluation of arrhythmogenic risk.

In single guinea-pig myocytes, endogenous IKr was replaced by modelled IKr (mIKr) by Dynamic-Clamp (DC) at a cycle length of 1 s. mIKr parameters were systematically modified and the resulting changes in action potential duration (APD) and its short term variability (SD1) were measured. We observed that: 1) IKr blockade increased SD1 more than expected by its dependency on APD; 2) mIKr completely reversed APD and SD1 changes caused by IKr blockade; 3) repolarization was most sensitive to inactivation shifts, which affected APD and SD1 concordantly; 4) activation shifts of the same magnitude had marginal impact on APD but, only when reducing mIKr, they significantly increased SD1; 5) changes in maximal conductance resulted in a pattern similar to that of activation shifts.

The largest effect on repolarization and its stability are expected from changes in IKr inactivation. APD is less sensitive to changes in other IKr gating parameters, which are better revealed by SD1 changes. SD1 may be more sensitive than APD in detecting IKr-dependent repolarization abnormalities.

RTXI 2.0 Released

Tue, 12 May 2015 00:00:00 -0400

We’ve been working hard over the past year to put together the new and improved Real-Time eXperiment Interface.

New features:

Improved UI: We’ve upgraded the UI framework from Qt3 to Qt4, which provides RTXI with many built-in performance improvements.
New Linux Base: RTXI 2.0 runs on Ubuntu GNOME 14.04 LTS - with it, you’ll get a stable desktop.
Enhanced Performance: For 2.0, we’ve switched from RTAI to Xenomai, a more versatile real-time kernel, providing a more robust and stable hard real-time system.
Open Development: We’ve migrated the project to GitHub, an excellent forum for development and all our documentation. Submit an issue; make a feature request; or watch our repository to stay up-to-date.

Try out v2.0. You can use the live CD to demo RTXI and later install it, or you can install a generic Linux distribution of your choice and use our installation scripts.

Cell-Specific Cardiac Electrophysiology Models

Thu, 30 Apr 2015 00:00:00 -0400

The traditional cardiac model-building paradigm involves constructing a composite model using data collected from many cells. Equations are derived for each relevant cellular component (e.g., ion channel, exchanger) independently. After the equations for all components are combined to form the composite model, a subset of parameters is tuned, often arbitrarily and by hand, until the model output matches a target objective, such as an action potential. Unfortunately, such models often fail to accurately simulate behavior that is dynamically dissimilar (e.g., arrhythmia) to the simple target objective to which the model was fit. In this study, we develop a new approach in which data are collected via a series of complex electrophysiology protocols from single cardiac myocytes and then used to tune model parameters via a parallel fitting method known as a genetic algorithm (GA). The dynamical complexity of the electrophysiological data, which can only be fit by an automated method such as a GA, leads to more accurately parameterized models that can simulate rich cardiac dynamics. The feasibility of the method is first validated computationally, after which it is used to develop models of isolated guinea pig ventricular myocytes that simulate the electrophysiological dynamics significantly better than does a standard guinea pig model. In addition to improving model fidelity generally, this approach can be used to generate a cell-specific model. By so doing, the approach may be useful in applications ranging from studying the implications of cell-to-cell variability to the prediction of intersubject differences in response to pharmacological treatment.

Repolarization Reserve Evolves Dynamically During the Cardiac Action Potential: Effects of Transient Outward Currents on Early Afterdepolarizations

Mon, 20 Apr 2015 00:00:00 -0400

Background — Transient outward K currents (Ito) have been reported both to suppress and facilitate early afterdepolarizations (EADs) when repolarization reserve is reduced. Here we used the dynamic clamp technique to analyze how Ito accounts for these paradoxical effects on EADs by influencing the dynamic evolution of repolarization reserve during the action potential.

Methods and Results — Isolated patch-clamped rabbit ventricular myocytes were exposed to either oxidative stress (H2O2) or hypokalemia to induce bradycardia-dependent EADs at a long pacing cycle length (PCL) of 6 s, when native rabbit Ito is substantial. EADs disappeared when the PCL was shortened to 1 s, when Ito becomes negligible due to incomplete recovery from inactivation. During 6-s PCL, EADs were blocked by the Ito blocker 4-aminopyridine, but reappeared when a virtual current with appropriate Ito-like properties was reintroduced using the dynamic clamp (n=141 trials). During 1-s PCL in the absence of 4-aminopyridine, adding a virtual Ito-like current (n=1,113 trials) caused EADs to reappear over a wide range of Ito conductance (0.005-0.15 nS/pF), particularly when inactivation kinetics were slow (τinact≥20 ms) and the pedestal (non-inactivating component) was small (<25% of peak Ito). Faster inactivation or larger pedestals tended to suppress EADs.

Conclusions — Repolarization reserve evolves dynamically during the cardiac action potential. Whereas sufficiently large Ito can suppress EADs, a wide range of intermediate Ito properties can promote EADs by influencing the temporal evolution of other currents affecting late repolarization reserve. These findings raise caution in targeting Ito as an antiarrhythmic strategy.

List of Resources

Thu, 16 Apr 2015 00:00:00 -0400

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.

Using the Command Line

http://ryanstutorials.net/linuxtutorial/ (see sections on how to navigate around the filesystem and manipulate files)

Using Git

Using GitHub

https://guides.github.com/

Learning Programming and C++

http://www.cplusplus.com/doc/tutorial/ (prior programming experience helps)
http://www.penguinprogrammer.co.uk/c-beginners-tutorial/

Qt and GUI Creation

http://doc.qt.io/qt-4.8/
Note: Be careful with some of the Qt tutorials. You don’t need to instatiate things like QApplication objects, create qmake.pro files, etc. because RTXI takes care of that. Pay attention to what the UI classes are and how to use the signal/slot API.

Again, this is a non-exhaustive list of a tiny subset of all that’s available online and in print. It takes some time to learn these things, just as it does with anything else. It also wouldn’t hurt to learn these things in general, Qt excepted. Unix-like environments are very common on clusters for computational research; Git and GitHub are widely used for coding projects; and C++ very fast and good to learn, especially given that other languages often use it as a backend to speed up loops and other heavy sections of code.

Making New Modules in RTXI

Fri, 10 Apr 2015 00:00:00 -0400

Outlined here is the development process for making new RTXI modules. For simplicity, we provide a shell script, called create_template_plugin.sh, for users to customize without needing to writing everything from scratch. You can access this script under the scripts folder in RTXI’s root directory. When run, it will create a source directory with source files and cmake build file in the current directory.

To create RTXI modules:

1. Generate the RTXI plugin project.

Enter or create the directory where you wish to create the plugin, then run the following command:

$ RTXI_SOURCE_LOCATION/scripts/create_template_plugin.sh

where RTXI_SOURCE_LOCATION is the full directory path to RTXI’s source code. Once you run the script, the program will ask for a name and a description of your plugin. Afterwards it will use this information to generate a widgets.hpp, widgets.cpp, and CMakeLists.txt.

The name of the directory created is the same as the name of the plugin. An explanation of the header and source files is available in our user manual.

2. Modify files.

Modify the RTXI files to run the code you want. The CMakeLists.txt file generated will automatically search for the RTXI library, but you should modify it if there are additional dependencies to your plugins. Check CMake and your library’s documentation on how to find and link the depenency.

Additionally, it’s good practice to document your code. As a general rule, document it so that you’re confident that anyone with programming experience will be able to understand what your code and overall module do.

3. Configure, Compile, and install.

Once you’re ready to compile and install your module, go to the base of your module directory and execute:

$ cmake -S . -B build
$ cmake --build ./build
$ sudo cmake --install ./build

Posting Bugs and Issues on GitHub

Thu, 09 Apr 2015 00:00:00 -0400

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.

Note: For the sake of absolute clarity, please do not actually create an issue in the process of going though this tutorial.

1. Navigate to the repository.

Go to our GitHub page ( https://github.com/rtxi). On the page, use the search bar or scroll down until you find the software you want to report. If you experience a bug within RTXI and its built-in modules, look for the rtxi repository. If it's a module you have problems with, find the repository that correponds to the module name. Also, if you have questions about anything on this website, go to the rtxi.github.io repository.

2. Open an issue on the repository page.

Each module has an issue page where you can view, submit, and comment on current development issues. Pictured is the repository page for rtxi. To navigate to its issues page, click on Issues on the right sidebar.

Click on Issues. It’s on the sidebar to the right. If you haven’t logged in to GitHub already, you will be prompted to now. This will open up a new page that shows all the issues posted to the repository. Look through them to see if the issue you are having is related to something someone else posted. If it is, you can add to the existing discussion. If not, then open up a new issue.

3. Write up your issue.

Click the appropriate button for whether you’re opening a new issue or joining an existing thread. Please be as clear and detailed as possible in your comments, as only posting things like “RTXI is crashing” or “X isn’t working” doesn’t help us figure out what the issue is.

For your posts, we ask (but don’t require) you do provide the following information when appropriate:

The version of RTXI you are using. If you used a live CD to install RTXI, just say that. If you compiled from source, go to your clone of the RTXI repository and run git log. The most recent commit will have a string associated with it that looks like a random list of letters. Give us the string.
Error messages from RTXI in the terminal. If there are no error messages, no problem. If RTXI is crashing, it would be incredibly helpful if you used gdb to provide a backtrace.
A clear description of the bug. Describe the behavior you expect, the behavior that is happening, and the set of steps that trigger the error.

Clear issue postings are incredibly helpful for us to start debugging your issues, and it also helps anyone else fully understand the issues you have.

How to Use Git

Tue, 07 Apr 2015 00:00:00 -0400

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.

Unlike many applications, such as Microsoft Word, editing and saving files overwrites data. This makes it difficult to track changes without creating different file names, a process that can get messy very quickly.

Git takes snapshots of files a user wants to track and maintains a history of changes that have occurred. This makes backtracking and checking revisions a simple process, which is especially helpful for large projects with many developers. It also functions as a collaborative tool by enabling users to make local copies of a common project and modify them as needed. Users track their own changes and those of others, and Git incorporates tools that enable branching and merging of whatever changes people make.

Note: Installing git is not the same as using GitHub. GitHub uses git, but it is a remote server that users can use as a central location for storing data. See the instructions for opening a GitHub account.

Installing Git on Linux

Open the terminal. You can do this from within the Applications menu in GNOME or by using the CTRL+Alt+t shortcut. Enter:

$ sudo apt-get install git

Note: When telling people to enter commands, it is common practice to use $ at the start of each line to signify that it is to be entered in the terminal. Also, # is used to signify root permissions rather than having people enter sudo. In either case, you DO NOT have to enter $ or # in the terminal. For example, in the above command. just enter the text sudo apt-get install git and hit ENTER.

Once Git is installed, configure it with your username and/or email address. This is preferred in development scenarios so that everyone can identify what modifications were made by which user. GitHub also maps Git user email addresses to GitHub accounts. Note that you do not have to give your real name. Any name will do, as all that is needed is a way to identify who has done what. Technically, Git does not check email address validity, either, but for collaborate work, it is best to provide some address so that people can ask each other questions about changes.

$ git config --global user.name 'Your name here'
$ git config --global user.email your@address.here

The git part of each command specifies that the script that follows contains Git commands. Git provides a library of functions for executing version control. Rather than have them directly incorporated into system libraries, they are made accessible by preceding the command with git. Therefore, these commands and all other git commands we will use start with git.

The second part, config, is used to configure information, which is stored in a hidden file. The tag --global means that the changes to the user configuration are to affect all user repositories. The details are saved in a hidden file called .gitconfig stored at the base of the user’s home directory (~/.gitconfig). Other options allow for different scopes of the effects of configuration changes. --local is the default behavior and specifies that changes be written to hidden file in the working directory called .git/config. You can see what has been set in the config files by running git config --list.

Note: Should you ever need help with a Git command, you can use `git help

` to check the Git documentation in the terminal. For example, if unsure about `config`, run `git help config`. ### Using Local Repositories #### Initialization Git enables users to track local changes and development paths. First, go the base of your home directory and create some new directories:

$ cd ~/
$ mkdir plugins
$ cd plugins
$ mkdir practice
$ cd practice
$ cd ..

Now, from within the plugins directory, run:

$ git init

This command specifies that the directory is to be treated as a Git repository. By default, Git does not track *any* files. User must enable it in a directory of their choosing. Once executed, this function creates a hidden directory called `.git/` that stores information regarding the repository contained in the directory. **Note:** Git exists as a version control system. It is not advisable to use it for backing up big files, such as videos, binaries, etc. The entire process gets encumbered quickly. #### Adding Files to the Staging Area The directory is currently empty, so create some files:

$ touch file1.txt
$ touch file2.txt
$ touch file3.txt

These files have been added to the repository, or in Git terminology, the **working tree**. The working tree refers to all of the files that originate from the base of the directory, which in this case is `~/plugins`. By default, Git does not track files that are added to the directory. Users have to specify that they be tracked. This is done by the `add` command. Git does, though tell what files are and are not being tracked. Simply use `git status`

$ git add file1.txt file2.txt file3.txt

`git add` adds the files to what is called the **staging area**. Basically, this command generates a snapshot of the files and stores them without adding them to the permanent version history. In other words, Git is aware of the files, but it has not added them to the permanent version history. Basically, git has a 2-stage revision process. The first is to send modified or new files to the staging area, and the second is to commit them to the permanent version history. This has its advantages in that it enables users to add files to a repository as a group that together functions properly. Reverting from one set of changes to another is simply a process of switching to another snapshot in the permanent history. This process is explained later. To show what files are in the stating area, use:

$ git status

If needed, it is possible to unstage files that were added with `git add`. Git gives the user the command `git rm --cached `. Try it on one of the files and see the changes made to the staging area.

$ git rm --cached file1.txt
$ git status

The following assumes that all three files are added to the staging area. You can add all files to the staging area by running `git add -A`. #### Commiting Files With the files added to the staging area, the next step is to add them to the permanent version history. In Git, this process is called a **commit**. Use the `commit` command.

$ git commit file1.txt file2.txt file3.txt -m "First commit"

The `commit` command adds files in the staging area to the repository. Each commit requires a message that is intended to describe the changes that took place. This can be done in the command line by using `-m` followed by the message in quotation marks. If this is omitted, Git defaults to a text editor where users can type the message. The `commit` command is completed when the user saves the message and exits the editor. If you opt to not specify the filenames for the commit, git will commit all the files in the staging area. Because all the files in the staging area were committed in the last command, there are all removed from the staging area. You can check with `git status`. The version history is in essence a list of commits. To view the complete history of the project, use:

$ git log

This outputs a list of all the commits, when they were made, the author, the commit messages, and other information. The string at the top of seemingly random letters is an encrypted hash of the changes that were made. A hash is a string that encodes data and is produced by a hash function. Ideally, a hash function is implemented such that a small change in the data it encodes results in a large, unpredictable change in the hash. This enables users to check the file's integrity and makes it exceedingly difficult to alter the commit history. #### (Optional) Undo a Commit If you ever commit something and wish to revert your changes, use the `reset` command. There are several options. The first is:

$ git reset --hard HEAD~1

This command erases **everything** that was altered after the previous commit and sets the working tree to the previous commit. The `--hard` induces the erasure, and `HEAD~1` moves to the previous commit. `HEAD` is a pointer that Git uses to point to a specific commit in a branch. `HEAD` by default points to the latest commit, so to access previous ones, use `~X` where X is the number of commits ago you want to go. Be very careful when using `--hard`. The second option:

$ git reset --mixed HEAD~1

-OR-

$ git reset HEAD~1

This file preserves the changes made but reverts the HEAD pointer back one commit. The changes are unstaged, so the working directory matches the previous commit. The last option:

$ git reset --soft HEAD~1

The only change is that the most recent commit is reversed. The staging area is the same; it reflects the changes that have been made between the commit to be erased and its predecessor. This option exactly reverses the effects of a `git commit` command. The following assumes that the commit has not been reversed. All three files are committed in the repository. #### Branching Repositories Now that a commit has been made, branch off and create a new working tree. Currently, HEAD points to the last commit of the original branch, called `master`. This is the default name for a new git repository. It is generally best practice to branch off of master to make changes and then merge changes back to master once they have been thoroughly audited. That way, whatever code is in the master branch is guaranteed to work. Create a branch called `testing`:

$ git branch testing

This creates a new branch called `testing`. By default, it copies the state pointed to by HEAD, but it is possible to branch off of previous commits. To list the available branches, use `git branch`. To switch to the newly created branch, use:

$ git checkout testing

Now, HEAD is pointing to `testing` instead of `master`. Any commits made will be applied to `testing` as long as it is checked out. #### Commiting Branches Change the current files. This command will add text to the files saying, "This is ". You can use `more ` or `cat ` to output the contents of a file into the terminal.

$ find . -maxdepth 1 -type f | xargs -I {} bash -c "echo 'This is '{} > {}"

Now that the files have been altered, run `git status` to see what Git has noticed. Stage the changes and commit them:

$ git add .
$ git commit . -m "First Branch Commit"

The `.` operator causes commands to affect all files in a directory. Using it is easier than typing individual file names. #### Comparing Branches Now that `master` and `testing` differ with one another, switch between them to see the differences.

$ ls | xargs cat
$ git checkout master
$ ls | xargs cat

Individually looking through files in different branches can be cumbersome. To output the differences directly, use the `diff` command.

$ git diff master testing

The output should look like: #### Merging Branches Now, merge the changes in `testing` to `master`. Check out the `master` branch and use the `merge` command.

$ git checkout master
$ git merge testing

You will see an output that summarizes the changes. The `merge` command creates a new commit that follows the previous version of `master`. If the merge is successful, there is no need for the `testing` branch. Delete it. Make sure that the `testing` branch isn't currently checked out.

$ git branch -d testing

### Using Remote Repositories Remote repositories refer to storage locations outside a user's local repository. The remote in this example is GitHub, and the repository we'll be using is for the plugin template. If you want to have your own remote repository on GitHub, you will need to create an account with them and using their website to initialize the repository. #### Cloning a GitHub Repository The format for cloning repositories from GitHub is:

$ git clone https://github.com/<username>/<repository-name>.git

To clone from our repositories, the username is `rtxi` and the repositories are all listed on https://github.com/rtxi. To install the plugin template:

$ cd ~/ # this line isn't really needed
$ git clone https://github.com/rtxi/plugin-template.git
$ cd plugin-template

In addition to the files copied from GitHub, Git stores the address of the remote repository. By default, the name is `origin`. See details on remote repositories with `git remote -v`. #### Pushing to a Remote Make some changes to the directory. Add some files, edit them, etc. Then, stage and commit them.

$ touch file1 file2 file3
$ git add .
$ git commit . "Local commit to push to remote repository"

**Note:** You will not actually be able to execute the command below successfully. We don't allow everyone to push to our repositories. This is what you'd do, though, if you could. Now, send these changes to the remote. The command Git uses for this is `push`.

$ git push https://github.com/<username>/plugin-template.git master # will fail

Git pushes the changes to the master branch of the remote repository referenced by the URL. Git also supports aliases for remote URLs. By default, the URL from which you clone a repository is saved as `origin`. You can view the remotes tracked by a repository by running `git remote -v`. #### Pulling Changes from a Remote Just as one can push changes from a local machine to a remote, it is possible to 'pull' changes back from the remote to the local machine. This comes into play when modifying the same project on several machines or by several people. To pull the code and automatically merge the differences, use:

$ git pull origin

If you want to observe the changes but not merge them, use:

$ git fetch origin

This command fetches the changes from the remote repository for the user to compare with files on the local machine. Once they are determined to be safe for merging, enter the following from within the directory to which changes are to be merged:

$ git merge <fetchedremote>

You can use this method to keep your modules and RTXI up to date. ### Summary The above tutorial is a very basic introduction to Git. Git has many functions, and many of them overlap in their functionality. As such, there are often many ways to implement what was described above. Should you need more detail, the [Git documentation](http://git-scm.com/documentation) is an excellent place to start. Additional help can be found throughout the web: - An [interactive tutorial](http://try.github.io/levels/1/challenges/1) for Git syntax. - A [user-made tutorial](http://www.vogella.com/tutorials/Git/article.html) - A detailed site by Atlassian with [tutorials on Git and workflow](https://www.atlassian.com/git/)

Setting a Default Boot Kernel

Wed, 01 Apr 2015 00:00:00 -0400

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.

By default, the GRUB bootloader sorts your installed kernels in descending version based on the kernel version number, and boots from the first one. You can save yourself some frustration by changing GRUB to boot from the real-time kernel by default.

Note: This is only for convenience. It has no effect on real-time performance or the functioning of RTXI.

While it is possible to specify a specific kernel, it is much easier to tell GRUB to use the kernel used last time. To make GRUB do this, open /etc/default/grub as root and make the following edits:

Change GRUB_DEFAULT=0 to GRUB_DEFAULT=saved.
Add a new line that says GRUB_SAVEDEFAULT=true.

Save your edits (again, you need to be root), and update GRUB by running:

$ sudo update-grub

From now on, GRUB will boot the last-used kernel by default. If you want to choose a different one, select it manually.

Note: If you have a LUKS-encrypted volume or otherwise encrypt your boot partition, this will fail. You will have to manually change the GRUB_DEFAULT options to something like "1>2", for example, which will make GRUB boot the kernel listed as the third option in the submenu opened on the second line of the main menu.

Why won't RTXI open?

Wed, 01 Apr 2015 00:00:00 -0400

There are several reasons for RTXI to not open.

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.
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.

RTXI 2015 Deadline Approaching

Fri, 27 Mar 2015 00:00:00 -0400

The deadline for registering for the RTXI 2015 conference is fast approacing. Register now to book your position here. Noteworthy dates:

Registration: April 30
Hotel: April 15

The conference is May 7-8 at the Georgia Academy of Medicine. Registration is $75 for students and $125 for everyone else. Fee waivers are liberally available upon request.

Linux Freezes after Reboot

Mon, 02 Mar 2015 00:00:00 -0500

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.

The kexec-tools utility normally is used to perform ‘warm reboots,’ which is when the computer reloads a kernel without fully shutting the system down. (In contrast, a cold reboot is when you fully shut down the computer, meaning that the machine fully stops and it begins to cool down.) The lag you experience is probably because kexec-tools is rebooting to a non-RT kernel. Your system is at that point should not be relied on for running real-time applications.

To temporarily fix this, fully shutdown the computer to do a cold reboot. To permanently fix it, disable kexec-tools from handling reboots:

Open /etc/default/kexec (as root).
Change LOAD_KEXEC from true to false
Save and exit.

Now, kexec-tools will no longer handle reboots, and your system reboot as one would expect.

Using Graphics Cards

Mon, 23 Feb 2015 00:00:00 -0500

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.

For RTXI, we strongly encourage you to use the open-source drivers. Nouveau is the open-source one for Nvidia cards, and radeon is for AMD ones. No configuration or input on your part is needed to use them. When you install Linux and boot, your kernel will detect the graphics hardware and load the corresponding driver. You can check to see if your driver is loaded by running:

$ lsmod | grep "radeon\|nouveau"

The reason we use open-source drivers is that they use the kernel to directly leverage the graphics card to compute things like the UI and desktop. Proprietary drivers, while technically doing the same thing, function differently and can degrade real-time performance by causing latencies to spike to as high as 100us on some machines. Skipping the drivers altogether forces the CPU to compute the UI, which when coupled with the RT kernel, will make the UI slow and laggy and the real-time performance poorer.

Here are some guidelines for using graphics cards:

Newer cards are less likely to be supported by open-source drivers.
AMD provides better support for its open-source radeon driver than Nvidia does for nouveau.
Nvidia’s proprietary driver performs better than AMD’s proprietary driver (fglrx) and generally provides better support for newer hardware.
If you have an AMD card, use it. If you have an Nvidia one, try it. Tell us if you have issues. We want to keep track of what works and what doesn’t.

Lastly, if you have issues with your display looking weird or distorted, it’s probably your graphics card. Check our graphics troubleshooting page for suggestions on what to do or browse though forums online. Someone’s probably had the same issue as you at some point.

My System Is Frozen or Slow!

Mon, 23 Feb 2015 00:00:00 -0500

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

When does the system freeze or slow down?
- Does it freeze after you pick a kernel in the GRUB menu?
- Does RTXI cause the slowdown or is it slow upon boot?
- Does the freeze affect all kernels? Or is it just the real-time one(s)?
What graphics card are you using?
- Is it Nvidia or AMD?
- Are you using open-source or proprietary drivers?
If running an RT kernel, are the DAQ drivers loaded? Open the Control Panel module in RTXI and see if the “analogy0” channel is open. If not, the drivers aren’t detecting your DAQ.
How is your BIOS configured? Some settings, such as multithreading, frequency scaling, and spread-spectrum clocking, degrade real-time performance and should be disabled.

These types of issues can have several causes. It can be your graphics card not being fully supported by the driver, the DAQ driver interfering with framebuffers, interrupt line collisions, etc. If you have issues, you are encouraged to contact us for help. Here are some tips and fixes for common problems:

Freezing at Boot

If your system freezes when it boots, it couls be caused by interrupt collisions between the graphics driver and the analogy driver. We've noticied this happening most frequently on machines with Nvidia cards. You can fix this by opening up the computer and moving the graphics card to a different PCI slot.

If that doesn't fix your system, you can delve deeper to find out whether there are still interrupt collisions. When Linux freezes, you can drop to another tty by entering Ctrl+Alt+F2. You can then enter you login information. From the new shell, enter:

$ lspci -v | less

Scroll through the output and check if anything has the same IRQ number as the DAQ (the National Instuments card) or the graphics card. Occasionally, things like the Ethernet card or a USB port can interfere. If you don't have a spare port, you'll need to get a new graphics card. We recommend AMD cards that have been released long enough for Ubuntu to fully support them. A list of compatible cards is available on Ubuntu's site.

Poor Performance

If your system has consistently poor performance, visible within the Performance Measurement Module, that worsens when the DAQ channels are opened, it is likely because the graphics drivers are not using kernel modesetting properly. What that means is that the CPU is handling things the graphics card should, causing it to interfere with the real-time processes it needs to devote time to doing.

This is likely caused by the graphics card being not fully supported by open-source drivers. You may need to replace your driver. To see if your system is using the graphics driver, run:

$ sudo lshw -C display | grep configuration

If you don't see your graphics driver (radeon or nouveau) listed, then it's not being properly used. You can also check this by looking at the dmesg output:

$ dmesg | grep "radeon\|nouveau"

If the driver is working properly, you'll see a lot of output. If not, you probably won't see anything.

Let us know if you need help with this issue. Sending us the output from the above commands will help immensely in figuring out your problem.

Hardware can be idiosyncratic and interfere with real-time, but lucky for you, we’re here to help.

RTXI 2015 Registration Open!

Wed, 21 Jan 2015 00:00:00 -0500

Just reminding everyone that registration for RTXI 2015 is now open! Check out our conference page to learn about our upcoming conference. Registration is open until April 1st at 5:00 PM Eastern Time.

Why are there negative latencies?

Tue, 20 Jan 2015 00:00:00 -0500

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.