Enabling the Remote API - server side

The remote API server side is implemented via a V-REP plugin that is based on the regular API. The remote API plugin project is located in V-REP's installation directory, under "programming/v_repExtRemoteApi". Should you miss one specific function, then you can easily implement it yourself into the remote API framework (see also the section on extending the remote API).

To enable the remote API on the server side (i.e. on V-REP's side), make sure the remote API plugin was successfully loaded at V-REP start-up (v_repExtRemoteApi.dll, libv_repExtRemoteApi.dylib or libv_repExtRemoteApi.so) (you can inspect the console window for information related to plugin loading). The remote API plugin can start as many server services as needed (each service will be listening/communicating on a different port). A server service can be started in two different ways:

  • At V-REP start-up (continuous remote API server service). The remote API plugin will try reading a configuration file named remoteApiConnections.txt and according to its content, start appropriate server services. Have a look at the configuration file for details. Use this method for remote control of the simulator itself. With this method remote API functions will always be executed on the server side, even if simulation is not running (which is not always the case with next method here below). There is another method to start a continuous remote API server service, via the command line.
  • From within a script (temporary remote API server service). This is most of the time the preferred method of starting a remote API server service. The user is in control when the service is started or stopped. When a temporary remote API server service is started from a simulation script however, the service will automatically be stopped at simulation end. A temporary remote API server service can be started or stopped with following 2 custom Lua functions (the 2 functions are exported by the plugin):
  • simExtRemoteApiStart

    Description Starts a temporary remote API server service on the specified port. When started from a simulation script, the service will automatically end when the simulation finishes
    Lua synopsis number result=simExtRemoteApiStart(number portNumber,number maxPacketSize=1300,Boolean debug=false,Boolean preEnableTrigger=false)
    Lua parameters
    portNumber: port where to install the server service. Ports above 20000 are preferred.
    maxPacketSize: the maximum size of a socket send-packet. Make sure to keep the value at 1300, unless the client side has a different setting.
    debug: if true, a window will display the data traffic on that port.
    preEnableTrigger: if true, the server service will be pre-enabled for synchronous trigger signals from the client.
    Lua return values
    -1 if operation was not successful. In a future release, a more differentiated return value might be available

    simExtRemoteApiStop

    Description Stops a temporary remote API server service on the specified port
    Lua synopsis number result=simExtRemoteApiStop(number portNumber)
    Lua parameters
    portNumber: port where the server service is running
    Lua return values
    -1 if operation was not successful. In a future release, a more differentiated return value might be available


    You can gather information about any remote API server service with following custom Lua function (the function is exported by the plugin):

    simExtRemoteApiStatus

    Description Fetches information about a server service. Use this function to enumerate all server services running.
    Lua synopsis number status, table_5 info, number serverVersion, number clientVersion, string clientIp=simExtRemoteApiStatus(number portNumber)
    Lua parameters
    portNumber: port where the server service is running.
    Lua return values
    status: -1 if no service is running on the given port. Otherwise a bit-coded value:
    bit 0: communication thread is running
    bit 1: client is connected
    info: nil if no service is running at the given index. Otherwise following values:
    info[1]: time when last client request was received
    info[2]: time when last client request was replied
    info[3]: time that passed between 2 successive requests from the client side
    info[4]: number of commands received during last client request
    info[5]: number of commands sent during last reply to client
    serverVersion: the version of the remote API server plugin
    clientVersion: the version of the remote API client, or -1 if that information is not (yet) available
    clientIp: the IP address of the connected client


    You can reset (i.e. destroy and recreate) any remote API server service with following custom Lua function (the function is exported by the plugin):

    simExtRemoteApiReset

    Description Resets a remote API server service on the specified port. This is equivalent to call simExtRemoteApiStop followed by simExtRemoteApiStart, but also works for continuous remote API server services. This can be useful to force disconnection from a client.
    Lua synopsis number result=simExtRemoteApiReset(number portNumber)
    Lua parameters
    portNumber: port where the server service is running.
    Lua return values
    -1 if operation was not successful. In a future release, a more differentiated return value might be available


    Recommended topics

  • Enabling the Remote API - client side
  • Remote API overview
  • Remote API modus operandi
  • Alphabetical remote API function list
  • Remote API function list by category
  • Remote API constants