🔹 What is rsiconfig?

rsiconfig is a command-line utility that allows you to generate XML configuration files, restore settings from XML configuration files, generate ENI files, check the RMP serial number, and check the RMP license.

🔹 What are XML configuration files for the RMP?

The RMP Motion Controller is software-based and does not have flash memory, nor are its configurations stored in a file.

XML configurations give your application the most flexibility for configuring the RMP as needed at runtime. This is better than using hard-coded values in your RapidCode application. Is also useful when upgrading to a new RMP version.

There are two types of XML configuration files:

rsiconfig Settings XML for RMP settings

SampleRate
Expected EtherCAT node count
Expected EtherCAT node types
Object counts (Axis, Motion, UserLimit, Recorder, Compensator, MathBlock)

For example, see settings.xml.

Axis XML for Axis settings

AxisNumber
UserUnits
Properties (Axis methods with a matching Get/Set method)
- hardware/software limit configuration
- settling criteria
- etc.
- OriginPosition (not included when generating, but can be entered manually for setting)
SDOConfig Values

Here's an example of an Axis XML file:

<SerializableAxis xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <AxisNumber>24</AxisNumber>
  <UserUnits>1234.56789</UserUnits>
  <Properties>
    <string>ErrorLimitAction=RSIActionABORT</string>
    <string>ErrorLimitTriggerValue=1</string>
    <string>ErrorLimitDuration=0</string>
    <string>PositionToleranceFine=0.1</string>
    <string>PositionToleranceCoarse=0.25</string>
    <string>VelocityTolerance=5000</string>
    <string>SettlingTime=0</string>
    <string>SettleOnStop=False</string>
    <string>SettleOnEStop=False</string>
  </Properties>
  <SDOConfig>
   <SDOConfigValues Index="8565" SubIndex="0" ByteCount="2">3</SDOConfigValues>
   <SDOConfigValues Index="0x2177" SubIndex="0" ByteCount="4">0x8F5C</SDOConfigValues>
   <SDOConfigValues Index="3000" SubIndex="4" ByteCount="8" IsByteArray="true">0100FF020100FF02</SDOConfigValues>
  </SDOConfig>
</SerializableAxis>

The <SDOConfig> element allows you to specify Service Data Object (SDO) configurations that will be sent to the NetworkNode of an Axis. Each <SDOConfigValues> entry defines an SDO write operation.

Attributes of `<SDOConfigValues>`

Index: The SDO index in decimal or hexadecimal format (e.g., "8565" or "0x2177").
SubIndex: The SDO sub-index (integer).
ByteCount: The number of bytes to write (integer).
IsByteArray (optional, added in 10.6.4): A boolean indicating if the value should be interpreted as a hex-encoded byte array. Defaults to false.

Content of `<SDOConfigValues>`

An integer value (decimal or hexadecimal), or
A string value, or
A hex-encoded byte array (when IsByteArray="true").

Using `IsByteArray` Attribute

When IsByteArray="true", the content is treated as a hex-encoded byte array. The system will parse the hex string and convert it into raw bytes to be written to the SDO.

Requirements when `IsByteArray` is true

The hex string may contain spaces and 0x prefixes (both are ignored).
The hex string must have an even number of hex digits after removing spaces and prefixes.
The ByteCount must match the number of bytes represented by the hex string.
Valid hex characters are 0-9, A-F, a-f.

Examples

Integer Value (Decimal)

Integer Value (Hexadecimal)

String Value

<SDOConfigValues Index="2000" SubIndex="3" ByteCount="6">Hello!</SDOConfigValues>

Hex-Encoded Byte Array Without Spaces

Hex-Encoded Byte Array With Spaces

Notes

If IsByteArray is not specified, it defaults to false, and the content is treated as an integer or string as before.
When IsByteArray="true", ensure that the ByteCount matches the actual number of bytes specified.
The system performs validation and will throw errors if the hex string is invalid or the byte counts do not match.

🔹 Why use the rsiconfig utility?

Using the rsiconfig utility will help guarantee that your RMP is correctly configured and ready to run before your RapidCode application starts. It allows you to keep hard-coded constants out of your source code. It also can help you generate XML configurations for your current settings, get the serial number, check the RMP license and generate ENI files.

🔹 Usage

rsiconfig /?
Description:
  rsiconfig is a utility to get or restore RMP settings to or from XML files, generate an ENI file, check the RMP serial number and whether RMP is
  licensed.
 
Usage:
  rsiconfig <settings file> [command] [options]
 
Arguments:
  <settings file>  The filename or path\filename of the XML settings file whose values will be restored to the RMP.
 
Options:
  -nonetwork, --no-network         to generate XML or set from XML without attempting to start the network (mainly used for software testing).
                                   [default: False]
  --cpu-affinity <cpu-affinity>    Linux: Set the CPU affinity for the process.
  --primary-nic <primary-nic>      Set the primary NIC name for the RMPNetwork process.
  --secondary-nic <secondary-nic>  Set the secondary NIC name for the RMPNetwork process.
  --verbose                        Verbose output.
  --version                        Show version information
  -?, -h, --help                   Show help and usage information
 
 
Commands:
  -generate <settings file>  The filename or path\filename where your RMP settings will be written to XML. [default: settings.xml]
  -example                   Outputs example.xml as an example of how you can create your own settings file by hand.
  -get-serial                Returns the serial number. 0 indicates the firmware is not running and the paths should be checked. Use --verbose to see
                             errors.
  -check-license             Returns whether or not the license (located at .\ rsi.lic) is valid for this system. Use --verbose to see errors.
  -eni                       Generate ENI file (EtherCAT.xml). This will overwrite any existing file. The network will be probed for nodes if the
                             network is not running. If the network is running, the ENI file will still be generated.

🔹 Use Cases

Generate XML configuration files

After the EtherCAT network is running and all Axis settings configured, use:

Windows

rsiconfig -generate settings.xml
Linux

Note
In Linux, you must specify the CPU affinity (for the RMP) --cpu-affinity and the Primary NIC (for RMP network) --primary-nic. See MotionController CreationParameters.

sudo rsiconfig -generate settings.xml --cpu-affinity {YOUR_CPU_INDEX} --primary-nic {YOUR_NIC_NAME}

Where {YOUR_CPU_INDEX} should be replaced with the CPU core index where RMP should run and {YOUR_NIC_NAME} should be replaced with the NIC name for your EtherCAT network.

Which will generate the file, settings.xml:

<?xml version="1.0" encoding="IBM437"?>
<XMLSettings xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ExpectedNodeCount>4</ExpectedNodeCount>
  <ExpectedNodeTypes>
    <RSINodeType>RSINodeTypeKOLLMORGEN_AKD</RSINodeType>
    <RSINodeType>RSINodeTypeBECKHOFF_EK1100</RSINodeType>
    <RSINodeType>RSINodeTypeUNKNOWN</RSINodeType>
    <RSINodeType>RSINodeTypeUNKNOWN</RSINodeType>
  </ExpectedNodeTypes>
  <NetworkStartTimeoutMilliseconds>30000</NetworkStartTimeoutMilliseconds>
  <SampleRate>1000</SampleRate>
  <AxisCount>1</AxisCount>
  <MotionCount>1</MotionCount>
  <UserLimitCount>0</UserLimitCount>
  <RecorderCount>0</RecorderCount>
  <RecorderBufferSize />
  <CompensatorCount>0</CompensatorCount>
  <CompensatorPointCount />
  <AxisFrameBufferSize>
    <int>1024</int>
  </AxisFrameBufferSize>
  <MathBlockCount>0</MathBlockCount>
  <XMLFiles>
    <AxisXML>
      <AxisNumber>0</AxisNumber>
      <XMLFile>Axis 0.xml</XMLFile>
    </AxisXML>
  </XMLFiles>
</XMLSettings>

This file, settings.xml, can be used to apply configurations to a freshly-started RMP in the future. It also creates the Axis XML files, such as Axis 0.xml.

Restore from XML configuration files

To initialize the RMP, its network and restore from XML files, use

Windows

rsiconfig settings.xml
Linux

Note
In Linux, you must specify the CPU affinity (for the RMP) --cpu-affinity and the Primary NIC (for RMP network) --primary-nic. See MotionController CreationParameters.

sudo rsiconfig settings.xml --cpu-affinity {YOUR_CPU_INDEX} --primary-nic {YOUR_NIC_NAME}

Where {YOUR_CPU_INDEX} should be replaced with the CPU core index where RMP should run and {YOUR_NIC_NAME} should be replaced with the NIC name for your EtherCAT network.

which should produce output similar to:

Settings file: settings.xml
Probing network...
Expected 4 nodes and found 4 nodes.
Node 0 Expected RSINodeTypeKOLLMORGEN_AKD and found RSINodeTypeKOLLMORGEN_AKD
Node 1 Expected RSINodeTypeBECKHOFF_EK1100 and found RSINodeTypeBECKHOFF_EK1100
Node 2 Expected RSINodeTypeUNKNOWN and found RSINodeTypeUNKNOWN
Node 3 Expected RSINodeTypeUNKNOWN and found RSINodeTypeUNKNOWN
Starting network...
Current Axis Count: 0
Setting Axis Count to 1
Current Motion Count: 1
Current UserLimit Count: 0
Current Recorder Count: 0
Current Compensator Count: 0
Current Axis 0 Frame Buffer Size: 1024
Current MathBlock Count: 0
Writing Axis 0.xml to Axis 0

The order of operations:

RMP MotionController is created
RMP sample rate is set
EtherCAT network is discovered
EtherCAT node count is checked
EtherCAT node types are checked
RMP EtherCAT network is started
RMP object counts are set
Axis settings are restored from Axis XML

Note: Use --no-network if you are testing software and do not want to start the network.

rsiconfig will return non-zero if there are unexpected nodes or an error restoring configurations.

Generate ENI file

To generate the ENI file, EtherCAT.xml, use

Windows

rsiconfig -eni
Linux

Note
In Linux, you must specify the CPU affinity (for the RMP) --cpu-affinity and the Primary NIC (for RMP network) --primary-nic. See MotionController CreationParameters.

sudo rsiconfig -eni --cpu-affinity {YOUR_CPU_INDEX} --primary-nic {YOUR_NIC_NAME}

Where {YOUR_CPU_INDEX} should be replaced with the CPU core index where RMP should run and {YOUR_NIC_NAME} should be replaced with the NIC name for your EtherCAT network.

This will first attempt to discover EtherCAT nodes on the network. If it finds any, it will (using the ESI files) generate the ENI file, EtherCAT.xml. If you have added any ESI files to the ESI directory, you may need to delete the ESICache.xml file to force a refresh.

Check RMP serial number

To check the RMP serial number, use:

Windows

rsiconfig -get-serial
Linux

Note
In Linux, you must specify the CPU affinity (for the RMP) --cpu-affinity and the Primary NIC (for RMP network) --primary-nic. See MotionController CreationParameters.

sudo rsiconfig -get-serial --cpu-affinity {YOUR_CPU_INDEX} --primary-nic {YOUR_NIC_NAME}

Where {YOUR_CPU_INDEX} should be replaced with the CPU core index where RMP should run and {YOUR_NIC_NAME} should be replaced with the NIC name for your EtherCAT network.

If 0 is returned, the serial number cannot be found.

Note: If your RMP is not licensed, optionally use --verbose to see errors, which will help you identify the unlicensed RMP serial number.

Check RMP license

To check the RMP license, use:

Windows

rsiconfig -check-license
Linux

Note
In Linux, you must specify the CPU affinity (for the RMP) --cpu-affinity and the Primary NIC (for RMP network) --primary-nic. See MotionController CreationParameters.

sudo rsiconfig -check-license --cpu-affinity {YOUR_CPU_INDEX} --primary-nic {YOUR_NIC_NAME}

Where {YOUR_CPU_INDEX} should be replaced with the CPU core index where RMP should run and {YOUR_NIC_NAME} should be replaced with the NIC name for your EtherCAT network.

Returns True if the license is valid, False if not.

Note: optionally use --verbose to see errors.

Table of Contents