APIs, concepts, guides, and more
RMP Linux iPC300

Getting Started with RMP-Linux

We are thrilled to introduce the integration of our robust RMP Motion Controller with Linux. For a hassle-free experience, we've crafted a custom hard drive image, included with our PC, containing only the essential files required to operate the RMP and ensure its accessibility through our RapidServer. With RapidServer active, you can seamlessly access the RMP via our gRPC RapidCodeRemote API or our innovative RapidSetupX multi-platform tool.

🔹 PC Info

Type iPC300
CPU i7-6700TE
Name ermp (embedded RMP)
OS Linux, Debian 12.0 “Bookworm” (Headless, CLI-based, no GUI)
Kernel 6.1.0-21-RT
Username rsi
Password admin

iPC300 Linux

🔹 Keywords

RMP RSI’s EtherCAT Motion Controller
RapidServer 🔗 An application/process that provides services via a Remote Procedure Call (RPC) framework. Client applications can communicate with a RapidServer instance from any operating system (Windows, Linux, MacOS, etc). The RapidServer application itself can run on Windows and INtime.
RapidSetupX Multi-platform (Linux, Windows, MacOS) UI client that allows you to connect to RapidServer instances and view, configure, and troubleshoot the RMP. Can be downloaded via portal.roboticsys.com
ENI File EtherCAT Network Information file. This must be created once your EtherCAT topology is ready.
rsiconfig 🔗 An application/process used to configure parts of the RMP during runtime.

🔹 Get up and Running

Follow these steps to get RapidServer, RapidSetupX UI, and the RMP controller up and running:

  1. Power on the PC
    Your PC is equipped with a custom hard drive image. Upon powering on, the RapidServer initiates automatically, providing you access to the RMP. Note, however, that the RMP does not start on its own. To start it, you must do it manually via the RapidCodeRemote API or RapidSetupX.
  2. Log in to the PC
    Username ➜ rsi
    Password ➜ rsi
    This image of Linux is CLI only and has no GUI.
  3. Verify RapidServer is Running (Optional)
    Run CLI Command ➜ top or htop or more specific systemctl status rapidserver

    This step is optional, but it is useful in case you would like to see if RapidServer is running and what other processes are running.

  4. Configure the EtherCAT Network
    Verify all your EtherCAT node(s) are powered on, connected to each other, and connected to the PC EtherCAT “enp5s0” NIC.
    Refer to the PC picture above or the “PC NICs” section below to identify your EtherCAT NIC port.\
  5. Generate the ENI File

    Run CLI Command ➜
    sudo rsiconfig -eni --cpu-affinity 3 --primary-nic enp5s0

    The ENI file is necessary to start the EtherCAT network communication between your nodes and the RMP controller. Make sure this file has been created before you try starting the EtherCAT network. Once the command is run it will use our utility rsiconfig to create a new ENI (EtherCAT.xml) file in the /rsi directory.

  6. Open RapidSetupX GUI Client
    1. Download from portal.roboticsys.com/downloads (recommended)
    2. Request the download link for your preferred OS at tech@roboticsys.com

      This UI client is designed to aid in visualizing and configuring the RMP across Linux, Windows, or MacOS platforms. RapidSetupX allows you to connect to any RapidServer running on the same network. As RapidSetupX is currently in the Beta stage.

🔹 Useful Commands

Here are some Linux Debian CLI commands that can be useful:

Command Description
~$ top Open a command-line utility that provides a real-time, dynamic view of the processes running on a system, displaying information about system performance and usage.
~$ q Quit certain command-line utilities.
~$ sudo Stands for “super user do”. It is appended to commands you wish to run with elevated privileges, typically as the root user.
~$ ls /rsi List the contents of the directory /rsi . This folder contains everything the RMP needs to run. Things like: NodeInfo.xml, RapidCode.NET.dll, rapidserver, rmpnetwork, rmp, rsi.lic, rsiconfig, protos, ESI, etc.
~$ sudo rsiconfig -eni --cpu-affinity 3 --primary-nic enp5s0 Generate a new ENI (EtherCAT.xml) file with the rsiconfig utility that comes pre-installed. sudo: Run with elevated privilege. rsiconfig -eni: Run our rsiconfig utility with the parameter ‘eni’ to create an ENI file. --cpu-affinity 3: Run this command in specifically in CPU core #3. --primary-nic enp5s0: Designate what network interface to use, in this case ‘enp5s0’. This should be where your EtherCAT cable is connected.
~$ sudo apt install rmp_10.4.4.0-1_amd64.deb Install the RMP. This is our first release candidate version.
~$ sudo apt remove rmp Remove the RMP if any is available. This is useful if you wish to download a new version. Delete before downloading another version.
~$ rapidserver & Run rapidserver (inside the /rsi folder) as a background process. rapidserver runs when the PC is powered ON. Regardless, you can use this command to start it.

🔹 General Information

Expand Advanced Information

The RMP EtherCAT Motion Controller is our open, powerful, and economical PC-based EtherCAT soft motion controller for OEM machine builders. The RMP APIs allow developers to quickly create machine control applications in C++, C#, VB.NET, Python, and more, and it can now run on Linux!

Installation

This is pre-installed, but if you wish to re-install or install another version you could do the following:

Install ➜ ~$ sudo apt install rmp_10.3.3-1_amd64.deb Remove ➜ ~$ sudo apt remove rmp

Files Included in Installation

  • /rsi/rmp (RMP firmware executable, 32-bit x86)
  • /rsi/rmpnetwork (RMPNetwork firmware executable, 32-bit x86)
  • /rsi/rapidserver (RapidServer gRPC so RapidSetupX can connect, x64)
  • /rsi/rsiconfig(.NET executable for managing XML configuration & making ENI file, x64)
  • /rsi/NodeInfo.xml
  • /rsi/CustomNodeInfo.xml
  • /rsi/librapidcode.so (RapidCode C++ library)
  • /rsi/RapidCode.NET.dll (RapidCode .NET library)
  • /rsi/tune_my_nic.sh (optimize your NIC for EtherCAT)
  • /rsi/ESI/* (ESI files)
  • /rsi/protos/ (gRPC .proto files for rapidserver)

License

Licenses are not bundled with the RMP installation files. However, to save you time, RSI adds the ‘rsi.lic’ (license) file on your PC before shipping.

The RMP ‘rsi.lic’ license is tied to a Yubico YubiKey 5 Series dongle. The serial number of the Yubikey is the RMP serial number.

If your /rsi directory does not contain a ‘rsi.lic’ file, you can download it from portal.roboticsys.com. Once downloaded, it should be renamed ‘rsi.lic’ and then copied to the /rsi directory.

PC NICs

The NIFE300 PC shipped to you comes with 3 network interface cards:

EtherCat NIC Tuning

/rsi/tune_my_nic.sh allows you to isolate NIC interrupts to the same CPU core where rmp and rmpnetwork firmware runs. You must provide the NIC name and CPU core as arguments. Usage: tune_my_nic.sh enp5s0 3

Kernel Optimization

In the file /etc/default/grub, the following kernel boot parameters were added:

GRUB_CMDLINE_LINUX="isolcpus=3 processor.max_cstate=0 intel_idle.max_cstate=0 idle=poll nohz_full=3 rcu_nocbs=3 rcu_nocb_poll nosmt"

The provided kernel parameters are primarily aimed at optimizing the system for high-performance and low-latency tasks, especially concerning CPU core number 3. The isolcpus=3 and nohz_full=3 parameters isolate CPU core 3 from regular scheduling and timer interrupts, respectively. The processor.max_cstate=0, intel_idle.max_cstate=0, and idle=poll parameters prevent power-saving modes, ensuring the CPU is always active and responsive. rcu_nocbs=3 and rcu_nocb_poll adjust the kernel's Read-Copy-Update mechanism to offload certain tasks from the isolated core, further reducing overhead. Finally, nosmt disables Simultaneous multi-threading (or Hyper-Threading on Intel CPUs) to enhance security and deterministic performance.

Development Environment

When developing RapidCode applications on a Debian system, we use the VSCode text editor (remote-ssh) with the CMake Tools, C/C++, and C# extensions (both published by Microsoft) installed.

Motion Controller Create

We have added CreationParameters for Linux when using Create

C++ Compilation

The most basic way to compile a C++ program with RapidCode is to use g++ from the command line. A compilation command would look like the following:

g++ code.cpp -L/rsi/ -lrapidcode -o program

-L to specify link directories. -l to specify libraries to link.

In the actual source code, be sure to specify the appropriate creation parameters when creating the motion controller. These are the path to the rmp executable, network interface name, max thread priority, and CPU affinity. The rmpPath will likely be "/rsi/", and the primaryNetworkInterfaceName will likely be something along the lines of enp2s0.

Note
As of 10.5.3, you can build and run the C++ sample apps in the /rsi/examples/C++/ directory. Get started by following the instructions given here: Run a sample app in C++

RapidCode C# Usage (RapidCode.NET.dll) (linux-x64) (.NET 7.0)

To use RapidCode, add the following to your .csproj:

<ItemGroup>
<Reference Include="/rsi/RapidCode.NET.dll" />
</ItemGroup>

Follow this guide to set up a new console project:
https://learn.microsoft.com/en-us/dotnet/core/tutorials/with-visual-studio-code?pivots=dotnet-7-0

Minimum viable C# example code:

using RSI.RapidCode.dotNET;
MotionController mc;
MotionController.CreationParameters creationParameters = new();
Console.WriteLine("Hello, World!");
creationParameters.rmpPath = "/rsi/";
creationParameters.cpuAffinity = 3;
creationParameters.primaryNetworkInterfaceName = "enp3s0";
mc = MotionController.Create(creationParameters);
if(mc.ErrorLogCountGet() > 0)
{
Console.WriteLine("Error Log Count: " + mc.ErrorLogCountGet());
Console.WriteLine("Error Log: " + mc.ErrorLogGet().Message);
Environment.Exit(-1);
}
Console.WriteLine("Motion Controller SerialNumber: " + mc.SerialNumberGet());
mc.Delete();