VRep: External Control using Matlab through the remote API

From Macro Wiki
Jump to: navigation, search

This tutorial aims to present the basic functions of the software V-Rep, developed and distributed by Coppelia Robotics, guiding the user into the implementation of a simulation environment externally controled by a routine implemented in Matlab.

What is V-Rep?

V-Rep is a virtual reality simulation software that allows the simulation of many robotic systems. All objects and models can be individually controlled using, for instance, embedded routines, plug-in's, ROS nodes, or remote servers connected through API's. These routines can be implemented using C/C++, Python, Java, Lua, Matlab, Octave, or Urbi. In this tutorial, the external control is made by an external client connected through an API, which is implemented in Matlab.

This API is provided by the developers, and it allows to control a simulation environment (and the software itself) using an external application, or even a remote computer. The API offers a list of useful functions, which can be called by a routine (implemented in the aforementioned programming languages). The comunication with V-REP is made through sockets, and can be synchronous or asynchronous, using the client-server structure, being the external application the client and the simulation environment in V-REP the server.

This communication can be made in two different ways: the server operating with a continuous remote API or with a temporary remote API.

Remote API: client-server connection

Initializing the server
The server can operate in two modes: continuous and temporary operation. In the continuous remote API operation, after the computer initialization the API plug-in check the file "remoteApiConnections" available in the root instalation folder of V-REP, and triggers the server in the specified communication port. In this mode, the server stays available even when the simulation is not running, and the software istelf can be externally controlled (start, stop, and pause commands), using the proper API functions. The following lines must be added at the end of the configuration file "remoteApiConnections" so as to provide communication through the desired port, using the continuous remote API mode.

portIndex1_port = *port_number*
portIndex1_debug = false
portIndex1_syncSimTrigger = true

In the temporary remote API operation, the user controls manually when the server will be initialized by pressing "play" in the simulation environment. When the simulation is stopped, the server becomes unavailable. In order to provide communication using the temporary remote API mode, the following line must be added in any script embedded to V-REP objects.


Initializing clients
To initialize the client in a Matlab routine, two files must be included in the folder where the Matlab routine is located: "remoteApiProto.m" and "remApi.m". Both files are found in the V-REP installation folder, in the path programming/remoteApiBindings/matlab. Furthermore, a configuration file must be included in the Matlab routine folder: "remoteApi.dll" (for Windows x86 e x64), "remoteApi.so" (for Linux x86 e x64) or "remoteApi.dylib" (for MacOS). These files are also found in the V-REP installation folder, in the path programming/remoteApiBindings/lib/lib. You may copy the configuration file to the Matlab routine folder, however, for Windows users, the file can be copied only once to the path C:\Windows\System32. As long as all the aforementioned files are in the proper folders, the following command must be included within the Matlab routine code:

vrep = remApi('remoteApi');

This command creates the client object in which all API functions are available.

Finally, to initizalize the client, the following line must be included afterall:

clientID = vrep.simxStart ('IPaddress', port, true, true, 5000, 5);

In this command, "IPaddress" is the address of the computer where the server is running, and "port" is the same port where the server is connected. If the server is running at the same computer of the client, you may use the address ''.

Preparing a simulation environment in V-REP

Hereafter an example will be explained step by step. In this example, a basic environment in V-REP externally controlled by a Matlab routine is going to be built.
The reading and consultation of V-REP User Manual is recommended before and throughout this tutorial.
An overview about some GUI components will be detailed.