Flexiv Sim Plugin

Overview

Flexiv Sim Plugin is a C++/Python library that bridges Flexiv Elements Studio and any external physics simulator, so that simulated Flexiv robots are driven by the same high-performance force-torque controller used on real robots — without requiring you to deal with the underlying IPC.

┌──────────────────────────────────────────┐
│       User Program with RDK Client       │
│          (send robot commands)           │
└────────────────────┬─────────────────────┘
                     │ RDK API
                     ▼
┌──────────────────────────────────────────┐
│         Flexiv Elements Studio           │
│   (simulated controller + RDK Server)    │
└────────────────────┬─────────────────────┘
                     │ Flexiv Sim Plugin API
                     ▼
┌────────────────────────────────────────────┐
│          External Simulator                |
│ (Flexiv Sim Plugin API + External sim API) │
└────────────────────────────────────────────┘

Supported External Simulators

The following external simulators are tested and known to work with Flexiv Sim Plugin:

• NVIDIA Isaac Sim (a template workspace is available here)
• MuJoCo

In theory, any simulator that meets the following criteria should work:

1. Has a C++ or Python interface.
2. Provides joint positions and velocities of the simulated robot.
3. Actuates the joints of the simulated robot by torque.

Environment Compatibility

OS	Platform	C++ compiler kit	Python interpreter
Linux (Ubuntu 20.04+)	x86_64	GCC v9.4+	3.10, 3.11, 3.12

Quick Start - Python

Install the Python package

On all supported platforms, the Python package of Sim Plugin for a specific Python version can be installed using the pip module:

python3 -m pip install flexivsimplugin

NOTE: replace python3 with a specific version (e.g. python3.10) if your default python3 is not one of the versions listed in the table above.

Use the installed Python package

After the flexivsimplugin Python package is installed, it can be imported from any Python script. Test with the following commands in a new Terminal, which should start Flexiv Sim Plugin:

python3
import flexivsimplugin
node = flexivsimplugin.UserNode("Rizon4-123456")
print("Connected = ", node.connected())

The program should print some info messages and "Connected = False" at the end.

Run the example Python script

An example script that mocks an external simulator is provided and can be used to test the plugin with the following steps:

1. Setup and run Flexiv Elements Studio simulation. See the relevant instructions at the end of this README.

2. Start the mock program:

   cd flexiv_sim_plugin/example_py
   python3 -m pip install spdlog
   python3 ./mock_external_simulator.py [robot_serial_number]
   

   NOTE: the robot serial number provided to the program is the same one you noted down when creating the simulated robot in Flexiv Elements Studio.

3. Wait for the connection to establish. If the connection is successful, you should see the visualized robot in Elements Studio moving every joint back and forth. NOTE: a software error should occur in Elements Studio which is expected because the mock external simulator did not close the loop by applying the calculated joint torques command to the simulated robot in it. This won't happen to real external simulators.

Quick Start - C++

Prepare build tools

Linux

1. Install compiler kit using package manager:

   sudo apt install build-essential
   

2. Install CMake using package manager:

   sudo apt install cmake
   

Install the C++ library

The following steps are identical on all supported platforms.

1. Choose a directory for installing the C++ library of Sim Plugin and its dependencies. This directory can be under system path or not, depending on whether you want Sim Plugin to be globally discoverable by CMake. For example, a new folder named sim_plugin_install under the home directory.

2. In a new Terminal, run the provided script to compile and install all dependencies to the installation directory chosen in step 1:

   cd flexiv_sim_plugin/thirdparty
   bash build_and_install_dependencies.sh ~/sim_plugin_install
   

3. In a new Terminal, configure the flexiv_sim_plugin CMake project:

   cd flexiv_sim_plugin
   mkdir build && cd build
   cmake .. -DCMAKE_INSTALL_PREFIX=~/sim_plugin_install
   

   NOTE: -D followed by CMAKE_INSTALL_PREFIX sets the absolute path of the installation directory, which should be the one chosen in step 1.

4. Install flexiv_sim_plugin C++ library to CMAKE_INSTALL_PREFIX path, which may or may not be globally discoverable by CMake:

   cd flexiv_sim_plugin/build
   cmake --build . --target install --config Release
   

Use the installed C++ library

After the library is installed as flexiv_sim_plugin CMake target, it can be linked from any other CMake projects. Using the provided flexiv_sim_plugin-examples project for instance:

cd flexiv_sim_plugin/example
mkdir build && cd build
cmake .. -DCMAKE_PREFIX_PATH=~/sim_plugin_install
cmake --build . --config Release -j 4

NOTE: -D followed by CMAKE_PREFIX_PATH tells the user project's CMake where to find the installed C++ library. This argument can be skipped if the Sim Plugin library and its dependencies are installed to a globally discoverable location.

Run the example C++ program

An example program that mocks an external simulator is provided and can be used to test the plugin with the following steps:

1. Setup and run Flexiv Elements Studio simulation. See the relevant instructions at the end of this README.

2. Start the mock program:

   cd flexiv_sim_plugin/example/build
   ./mock_external_simulator [robot_serial_number]
   

   NOTE: the robot serial number provided to the program is the same one you noted down when creating the simulated robot in Flexiv Elements Studio.

3. Wait for the connection to establish. If the connection is successful, you should see the visualized robot in Elements Studio moving every joint back and forth. NOTE: a software error should occur in Elements Studio which is expected because the mock external simulator did not close the loop by applying the calculated joint torques command to the simulated robot in it. This won't happen to real external simulators.

API Documentation

The API documentation can be generated using Doxygen. For example, on Linux:

sudo apt install doxygen-latex graphviz
cd flexiv_sim_plugin
doxygen doc/Doxyfile.in

Open any html file under flexiv_sim_plugin/doc/html/ with your browser to view the doc.

Flexiv Elements Studio Setup

Install Elements Studio on Ubuntu

1. Contact Flexiv to obtain the installation package of Elements Studio.

2. Extract the package to a non-root directory.

3. Install Elements Studio:

   bash setup_FlexivElements.sh
   

4. Switch physics engine from the default built-in to external:

   bash switch_physics_engine.sh
   

   Select External when prompted.

Create a simulated robot in Elements Studio

1. Start Flexiv Elements Studio from the application menu.
2. In the Robot Connection window, select Simulator, and click CREATE.
3. Choose "Create according to the selected robot type" and select one from the list, then click CONFIRM. A new simulated robot will be added to the simulator list.
4. Toggle on the Connect button for the newly added one, then wait for loading.
5. When loading is finished, you'll see a robot at its upright pose, with an "Exception" error at the bottom right corner. This is expected because the external simulator is not started yet. But if you see a normally operating robot, that again means you are running the wrong version of Elements Studio that only supports the built-in physics engine.
6. At the bottom of the window, click on the small robot icon with a "SIM" tag on it, then a small window will pop up, note down the displayed robot serial number.
7. Toggle the virtual motion bar slider button to the "auto" position. In resulting popup window, select "AUTO (REMOTE)"