Writing code in and around V-REP

V-REP is a highly customizable simulator: every aspect of a simulation can be customized. Moreover, the simulator itself can be customized and tailored so as to behave exactly as desired. This is allowed through an elaborate Application Programming Interface (API). Six different programming or coding approaches are supported, each having particular advantages (and obviously also disadvantages) over the others, but all six are mutually compatible (i.e. can be used at the same time, or even hand-in-hand). The control entity of a model, scene, or the simulator itself can be located inside:

  • an embedded script (i.e. customizing a simulation (i.e. a scene or models) via scripting): this method, which consists in writing Lua scripts, is very easy and flexible, with guaranteed compatibility with every other default V-REP installations (as long as customized Lua-commands are not used, or are used with distributed plugins). This method allows customizing a particular simulation, a simulation scene, and to a certain extent the simulator itself. This is the easiest and most used programming approach.
  • an add-on: this method, which consists in writing Lua scripts, allows to quickly customize the simulator itself. Add-ons can start automatically and run in the background, or they can be called as functions (e.g. convenient when writing importers/exporters). Add-ons should not be specific to a certain simulation or model, they should rather offer a more generic, simulator-bound functionality.
  • a plugin (i.e. customizing the simulator and/or a simulation via a plugin): this method basically consists in writing a plugin for V-REP. Oftentimes, plugins are only used to provide a simulation with customized Lua commands, and so are used in conjunction with the first method. Other times, plugins are used to provide V-REP with a special functionality requiring either fast calculation capability (scripts are most of the time slower than compiled languages), a specific interface to a hardware device (e.g. a real robot), or a special communication interface with the outside world.
  • a remote API client (i.e. customizing the simulator and/or a simulation via a remote API client application): this method allows an external application (e.g. located on a robot, another machine, etc.) to connect to V-REP in a very easy way, using remote API commands. This makes it possible to have the exact same code located on a robot to control its virtual pendant inside V-REP.
  • a ROS node (i.e. customizing the simulator and/or a simulation via a ROS node): this method allows an external application (e.g. located on a robot, another machine, etc.) to connect to V-REP via ROS, the Robot Operating System.
  • a custom client/server (i.e. customizing the simulator and/or a simulation via an external application acting as client or server). The client or server application needs to work hand-in-hand with either a script, or a plugin, using a custom mean of communication (e.g. sockets, pipes, etc.). This way of doing is flexible, but requires more effort that any of the 3 other methods here above.
  • Above 6 methods are also discussed in the external controller tutorial. Following table describes in detail the respective advantages and disadvantages of each method:

    [The 6 possible types of control methods in and around V-REP]


    Colors in above table are used in a consistent manner throughout this user manual (including for code snippets related to above methods). Following figure illustrates the various customization possibilities in and around V-REP:

    [V-REP framework. Colored areas are custom or can be customized]


    The various communication or messaging mechanisms indicated in above figure are briefly described hereafter:

    1. C/C++ API calls from the main client application or a plugin to the regular API. Can originate from a non-C/C++ application if the language provides a mechanism to call C functions (e.g. in the case of Java, refer to the Java Native Interface (JNI)).
    2. Cascaded child script execution. Initiated with simHandleChildScripts in the main script.
    3. Lua API calls from the main script, a child script, a callback script or a customization script to the regular API. All calls are directed to the V-REP engine, except for custom Lua functions that are calling back plugins (see next item).
    4. Callback calls from the simulator to plugins. The callback calls originate from Lua script calls to custom Lua functions (see previous item).
    5. Event callback calls from the simulator to plugins. Refer to sim_message_eventcallback_-type messages.
    6. Remote API calls from external applications, robots, remote PCs, etc.
    7. ROS data exchange between V-REP (i.e. its RosInterface) and external applications, robots, remote PCs, etc.
    8. Socket-, pipe-, serial port-, etc. connections to/from external applications.
    9. Lua API calls from an add-on to the regular API. All calls are directed to the V-REP engine, except for custom Lua functions that are calling back plugins.
    10. Callback calls from the V-REP engine to callback scripts.
    11. Execution calls from the V-REP engine to customization scripts.

    Recommended topics

  • Means of communication in and around V-REP
  • The main script
  • Child scripts
  • Callback scripts
  • Customization scripts
  • Add-ons
  • Plugins
  • The main client application
  • Regular API
  • Remote API
  • ROS interfaces