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) |
|