# Flexiv Sim Plugin

![CMake Badge](https://github.com/flexivrobotics/flexiv_sim_plugin/actions/workflows/cmake.yml/badge.svg)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)


## 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](https://developer.nvidia.com/isaac/sim) (a template workspace is available [here](https://github.com/flexivrobotics/isaac_sim_ws))
- [MuJoCo](https://mujoco.org/)

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.12, 3.14       |


## 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 [docs/elements_studio_setup.md](docs/elements_studio_setup.md).

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 [docs/elements_studio_setup.md](docs/elements_studio_setup.md).

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.