Release/v1.1

.github/workflows/cmake.yml

@@ -0,0 +1,21 @@
+name: CMake
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+env:
+  # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
+  BUILD_TYPE: Release
+
+jobs:
+  build-ubuntu-22:
+    # GitHub-hosted Ubuntu 22.04 runner
+    runs-on: ubuntu-22.04
+    # Use shared steps
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ./.github/workflows/shared_steps

.github/workflows/shared_steps/action.yml

@@ -0,0 +1,31 @@
+name: "Shared Build Steps"
+runs:
+  using: "composite"
+  # Note: working directory will be reset to the repo root for each new step
+  steps:
+    # Build and install all dependencies to RDK installation directory.
+    - name: Build and install dependencies
+      shell: bash
+      run: |
+        pwd
+        cd thirdparty
+        bash build_and_install_dependencies.sh ~/sim_plugin_install 4
+
+    # Configure CMake, then build and install flexiv_rdk library to RDK installation directory.
+    - name: Build and install library
+      shell: bash
+      run: |
+        pwd
+        mkdir -p build && cd build
+        cmake .. -DCMAKE_INSTALL_PREFIX=~/sim_plugin_install
+        cmake --build . --target install --config Release
+
+    # Find and link to flexiv_rdk library, then build all example programs.
+    - name: Build examples
+      shell: bash
+      run: |
+        pwd
+        cd example
+        mkdir -p build && cd build
+        cmake .. -DCMAKE_PREFIX_PATH=~/sim_plugin_install
+        cmake --build . --config Release -j 4

CMakeLists.txt

@@ -0,0 +1,82 @@
+cmake_minimum_required(VERSION 3.16.3)
+
+# ===================================================================
+#      PROJECT SETUP
+# ===================================================================
+project(flexiv_sim_plugin VERSION 1.1.0)
+
+# Configure build type
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "CMake build type" FORCE)
+endif()
+set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Release" "Debug" "RelWithDebInfo")
+
+# Set static library according to platform
+message(STATUS "OS: ${CMAKE_SYSTEM_NAME}")
+message(STATUS "Processor: ${CMAKE_SYSTEM_PROCESSOR}")
+if(${CMAKE_SYSTEM_NAME} MATCHES "Linux")
+  if(${CMAKE_SYSTEM_PROCESSOR} MATCHES "x86_64")
+    set(SIM_PLUGIN_STATIC_LIB "libflexiv_sim_plugin.x86_64-linux-gnu.a")
+  else()
+    message(FATAL_ERROR "Linux with ${CMAKE_SYSTEM_PROCESSOR} processor is currently not supported.")
+  endif()
+elseif(${CMAKE_SYSTEM_NAME} MATCHES "Darwin")
+    message(FATAL_ERROR "macOS is currently not supported.")
+elseif(${CMAKE_SYSTEM_NAME} MATCHES "Windows")
+    message(FATAL_ERROR "Windows is currently not supported.")
+endif()
+
+# ===================================================================
+#      PROJECT DEPENDENCIES
+# ===================================================================
+# Threads
+set(THREADS_PREFER_PTHREAD_FLAG ON)
+find_package(Threads REQUIRED)
+if(Threads_FOUND)
+  message(STATUS "Found Threads: HAVE_PTHREAD = ${THREADS_HAVE_PTHREAD_ARG}")
+endif()
+
+# spdlog
+find_package(spdlog REQUIRED)
+if(spdlog_FOUND)
+  message(STATUS "Found spdlog: ${spdlog_DIR}")
+endif()
+
+# Fast-DDS (Fast-RTPS)
+find_package(fastrtps 2.6.7 REQUIRED)
+if(fastrtps_FOUND)
+  message(STATUS "Found fastrtps: ${fastrtps_DIR}")
+endif()
+
+# ===================================================================
+#      CREATE LIBRARY
+# ===================================================================
+# Create an INTERFACE library with no source file to compile
+add_library(${PROJECT_NAME} INTERFACE)
+
+# Create an alias of the library using flexiv namespace,
+# to imitate the install target which uses flexiv namespace.
+add_library(flexiv::${PROJECT_NAME} ALIAS ${PROJECT_NAME})
+
+target_include_directories(${PROJECT_NAME} INTERFACE
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+  $<INSTALL_INTERFACE:include>
+)
+
+target_link_libraries(${PROJECT_NAME} INTERFACE
+  ${CMAKE_CURRENT_SOURCE_DIR}/lib/${SIM_PLUGIN_STATIC_LIB}
+  Threads::Threads
+  spdlog::spdlog
+  fastrtps
+)
+
+# Use moderate compiler warning option
+if(CMAKE_HOST_UNIX)
+  target_compile_options(${PROJECT_NAME} INTERFACE -Wall -Wextra)
+else()
+  target_compile_options(${PROJECT_NAME} INTERFACE /W1)
+endif()
+
+# Install the INTERFACE library
+include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/FlexivInstallLibrary.cmake)
+FlexivInstallLibrary()

README.md

@@ -11,6 +11,108 @@ A middleware plugin to connect Flexiv Elements Studio to any external simulator
 | --------------------- | ------------ | -------------------- | ---------------------- |
 | Linux (Ubuntu 20.04+) | x86_64       | GCC v9.4+            | 3.8, 3.10, 3.12        |
 
+## Tested 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. The joints of the simulated robot are actuated by torque.
+
+## Flexiv Elements Studio Setup
+
+### Install Elements Studio
+
+1. Prepare a Ubuntu 22.04 computer, all operations below are done on this computer.
+2. [Contact Flexiv](https://www.flexiv.com/contact) to obtain the installation package of Elements Studio.
+3. Extract the package to a non-root directory.
+4. Install Elements Studio:
+
+       bash setup_FlexivElements.sh
+
+5. Switch physics engine from the default built-in to external:
+
+       bash switch_physics_engine.sh
+
+   Select *External* or *Isaac Sim* 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. In the same small pop-up window, click *CHANGE CONNECTION*, then toggle off the *Connect* button to close the simulated robot. We will restart it later. Note that you do NOT need to close the whole Elements Studio program.
+
+## 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. 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.
+
+2. Go back to Elements Studio, then restart the exited simulator by toggling ON the *Connect* button.
+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. 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 - Python
 
 ### Install the Python package
@@ -32,6 +134,19 @@ After the ``flexivsimplugin`` Python package is installed, it can be imported fr
 
 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. Start the mock program:
+
+       cd flexiv_sim_plugin/example_py
+       python3.x ./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.
+
+2. The remaining steps are the same as documented in [Run the example C++ program](#run-the-example-c-program).
+
 ## API Documentation
 
 The API documentation can be generated using Doxygen. For example, on Linux:

cmake/FlexivInstallLibrary.cmake

@@ -0,0 +1,95 @@
+# This macro will install ${PROJECT_NAME} to ${CMAKE_INSTALL_PREFIX} when running make install
+#
+# FlexivInstallLibrary() will install all subfolders of ${CMAKE_CURRENT_SOURCE_DIR}/include
+# FlexivInstallLibrary(install_directories) will install only the specified install_directories
+#
+# Requirements:
+# 1. project structure should resemble:
+#    project
+#     - README.md
+#     - CMakeLists.txt that calls this macro
+#     - cmake/${PROJECT_NAME}-config.cmake.in
+#     - include/subfolder/*.h or *.hpp
+# 2. build the library using cmake target functions
+#    - add_library(${PROJECT_NAME} ...) before calling this macro
+#    - target_include_directories(${PROJECT_NAME} ...)
+#    - target_link_libraries(${PROJECT_NAME} ...)
+#    - target_compile_features(${PROJECT_NAME} ...)
+#    - target_compile_options(${PROJECT_NAME} ...)
+#
+# Installed files:
+# - include/subfolder/*.h or *.hpp
+# - lib/lib{PROJECT_NAME}
+# - lib/cmake/{PROJECT_NAME}/
+
+macro(FlexivInstallLibrary)
+    # copy the executables and libraries to the CMAKE_INSTALL_PREFIX DIRECTORY
+    # GNUInstallDirs will set CMAKE_INSTALL* to be the standard relative paths
+    include(GNUInstallDirs)
+    install(TARGETS ${PROJECT_NAME}
+        EXPORT "${PROJECT_NAME}-targets"
+        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        )
+
+    if(${ARGC} EQUAL 0)
+        # install all subfolders of ${CMAKE_CURRENT_SOURCE_DIR}/include
+        file(GLOB install_directories ${CMAKE_CURRENT_SOURCE_DIR}/include/*)
+        foreach(install_directory ${install_directories})
+            if(IS_DIRECTORY ${install_directory})
+                install(DIRECTORY ${install_directory}
+                        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+                        FILES_MATCHING 
+                        PATTERN "*.h"
+                        PATTERN "*.hpp"
+                )
+            endif()
+        endforeach()
+    elseif(${ARGC} EQUAL 1)
+        # install specified directories only
+        foreach(install_directory ${ARGV0})
+            install(DIRECTORY ${install_directory}
+                    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+                    FILES_MATCHING 
+                    PATTERN "*.h"
+                    PATTERN "*.hpp"
+                    )
+        endforeach()
+    else()
+        message(FATAL_ERROR "FlexivInstallLibrary take 0 or 1 argument, but given ${ARGC}")
+    endif()
+
+    # Create a *config-version.cmake file so that find_package can have a version specified
+    include(CMakePackageConfigHelpers)
+    write_basic_package_version_file(
+        "${PROJECT_NAME}-config-version.cmake"
+        VERSION ${PROJECT_VERSION}
+        COMPATIBILITY AnyNewerVersion
+        )
+
+    # copy the *-targets.cmake file to the CMAKE_INSTALL_PREFIX directory
+    install(EXPORT "${PROJECT_NAME}-targets"
+            FILE "${PROJECT_NAME}-targets.cmake"
+            NAMESPACE "flexiv::"
+            DESTINATION "lib/cmake/${PROJECT_NAME}"
+            )
+
+    # copy the *.-config file to the CMAKE_INSTALL_PREFIX directory. This will specify the dependencies.
+    configure_file("${CMAKE_CURRENT_SOURCE_DIR}/cmake/${PROJECT_NAME}-config.cmake.in" "${PROJECT_NAME}-config.cmake" @ONLY)
+    install(FILES "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}-config.cmake"
+                  "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}-config-version.cmake"
+            DESTINATION "lib/cmake/${PROJECT_NAME}"
+            )
+
+    # Use the CPack Package Generator
+    set(CPACK_PACKAGE_VENDOR "Flexiv")
+    set(CPACK_PACKAGE_CONTACT "[email protected]")
+    set(CPACK_PACKAGE_DESCRIPTION "Flexiv Sim Plugin")
+    set(CPACK_PACKAGE_VERSION_MAJOR ${PROJECT_VERSION_MAJOR})
+    set(CPACK_PACKAGE_VERSION_MINOR ${PROJECT_VERSION_MINOR})
+    set(CPACK_PACKAGE_VERSION_PATCH ${PROJECT_VERSION_PATCH})
+    set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE")
+    set(CPACK_RESOURCE_FILE_README  "${CMAKE_CURRENT_SOURCE_DIR}/README.md")
+    include(CPack)
+endmacro()

cmake/flexiv_sim_plugin-config.cmake.in

@@ -0,0 +1,10 @@
+include(CMakeFindDependencyMacro)
+
+# Find dependency
+set(THREADS_PREFER_PTHREAD_FLAG ON)
+find_dependency(Threads REQUIRED)
+find_dependency(spdlog REQUIRED)
+find_dependency(fastrtps 2.6.7 REQUIRED)
+
+# Add targets file
+include("${CMAKE_CURRENT_LIST_DIR}/@[email protected]")