APIs, concepts, guides, and more
rsiconfig

A command-line utility that allows XML configuration, ENI generation, and more.

🔹 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 (not included when generating, but can be entered manually for setting)

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>
</SDOConfig>
</SerializableAxis>

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