Enabling the legacy remote API - server side

The legacy remote API server side is implemented via a CoppeliaSim plugin that is based on the regular API. The legacy remote API plugin project is located here. Should you miss one specific function, then you can implement it yourself into the legacy remote API framework (see also the section on extending the legacy remote API).

To enable the legacy remote API on the server side (i.e. on CoppeliaSim's side), make sure the legacy remote API plugin was successfully loaded at CoppeliaSim start-up (simExtRemoteApi.dll, libsimExtRemoteApi.dylib or libsimExtRemoteApi.so) (you can inspect the console window for information related to plugin loading). The legacy 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 CoppeliaSim start-up (continuous legacy remote API server service). The legacy 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 legacy 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 legacy remote API server service, via the command line.
  • From within a script (temporary legacy remote API server service). This is most of the time the preferred method of starting a legacy remote API server service. The user is in control when the service is started or stopped. When a temporary legacy remote API server service is started from a simulation script however, the service will automatically be stopped at simulation end. A temporary legacy remote API server service can be started or stopped with following 2 custom script functions (the 2 functions are exported by the plugin):
  • simRemoteApi.start

    Description Starts a temporary legacy 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
    int result=simRemoteApi.start(int portNumber,int maxPacketSize=1300,bool debug=false,bool preEnableTrigger=false)
    Lua
    parameters
    portNumber: port where to install the server service. Ports above 20000 are preferred. Negative port numbers can be specified in order to use shared memory, instead of socket communication.
    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 a stepping mode.
    Lua
    return values
    -1 if operation was not successful
    Python
    synopsis
    int result=simRemoteApi.start(int portNumber,int maxPacketSize=1300,bool debug=false,bool preEnableTrigger=false)

    simRemoteApi.stop

    Description Stops a temporary legacy remote API server service on the specified port
    Lua
    synopsis
    int result=simRemoteApi.stop(int portNumber)
    Lua
    parameters
    portNumber: port where the server service is running
    Lua
    return values
    -1 if operation was not successful
    Python
    synopsis
    int result=simRemoteApi.stop(int portNumber)


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

    simRemoteApi.status

    Description Fetches information about a server service. Use this function to enumerate all server services running.
    Lua
    synopsis
    int status, table[5] info, int serverVersion, int clientVersion, string clientIp=simRemoteApi.status(int 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
    Python
    synopsis
    int status, list info, int serverVersion, int clientVersion, string clientIp=simRemoteApi.status(int portNumber)


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

    simRemoteApi.reset

    Description Resets a legacy remote API server service on the specified port. This is equivalent to call simRemoteApi.stop followed by simRemoteApi.start, but also works for continuous remote API server services. This can be useful to force disconnection from a client.
    Lua
    synopsis
    int result=simRemoteApi.reset(int portNumber)
    Lua
    parameters
    portNumber: port where the server service is running.
    Lua
    return values
    -1 if operation was not successful
    Python
    synopsis
    int result=simRemoteApi.reset(int portNumber)