|
Plugins
A plugin is a shared library (e.g. a dll) that is automatically loaded by CoppeliaSim's main client application at program start-up, or dynamically loaded/unloaded via sim.loadModule/sim.unloadModule. It allows CoppeliaSim's functionality to be extended by user-written functions (in a similar way as with add-ons). The language can be any language able to generate a shared library and able to call exported C-functions (e.g. in the case of Java, refer to GCJ and IKVM). A plugin can also be used as a wrapper for running code written in other languages or even written for other microcontrollers (e.g. a plugin was written that handles and executes code for Atmel microcontrollers).
Plugins are usually used to customize the simulator and/or a particular simulation. Often, plugins are only used to provide a simulation with custom script commands, and so are used in conjunction with scripts. Other times, plugins are used to provide CoppeliaSim with a special functionality requiring either fast calculation capability (scripts are most of the times slower than compiled languages) or an interface to a hardware device (e.g. a real robot).
Each plugin is required to have following 3 entry point procedures:
extern "C" __declspec(dllexport) unsigned char simStart(void* reserved,int reservedInt);
extern "C" __declspec(dllexport) void simEnd();
extern "C" __declspec(dllexport) void* simMessage(int message,int* auxiliaryData,void* customData,int* replyData);
If one procedure is missing then the plugin will be unloaded and won't be operational. Refer to the console window at start-up for the loading status of plugins. Following briefly describes above three entry point purpose:
simStart
This procedure will be called one time just after the main client application loaded the plugin. The procedure should:
check whether the version of CoppeliaSim is same or higher than the one that was used to develop the plugin (just make sure all commands you use in the plugin are supported!).
allocate memory, and prepare GUI related initialization work (if required).
register custom script functions (if required).
register custom script variables (if required) .
return the version number of this plugin if initialization was successful, otherwise 0. If 0 is returned, the plugin is unloaded and won't be operational. Due to backward compatibility, the version number is limited to values between 1 and 255. To overcome this limitation, one can additionaly also use following API functions: simSetModuleInfo / simGetModuleInfo.
simEnd
This procedure will be called one time just before the simulation loop exits. The procedure should release all resources reserved since simStart was called.
simMessage
This procedure will be called very often while the simulator is running. The procedure is in charge of monitoring messages of interest and reacting to them. It is important to react to following events (best by intercepting the sim_message_eventcallback_instancepass message) depending on your plugin's task:
When objects were created, destroyed, scaled, or when models are loaded: make sure you reflect the change in the plugin (i.e. synchronize the plugin with the scene content)
When scenes were loaded or the undo/redo functionality called: make sure you erase and reconstruct all plugin objects that are linked to the scene content
When the scene was switched: make sure you erase and reconstruct all plugin objects that are linked to the scene content. In addition to this, remember that a scene switch will discard handles of following items:
signals
drawing objects
etc.
When the simulator is in an edit mode: make sure you disable any "special functionality" provided by the plugin, until the edit mode was ended. In particular, make sure you do not programmatically select scene objects.
When a simulation was launched: make sure you initialize your plugin elements if needed
When a simulation ended: make sure you release any memory and plugin elements that are only required during simulation
When the object selection state was changed, or a dialog refresh message was sent: make sure you actualize the dialogs that the plugin displays
Refer to the messages of type sim_message_eventcallback_ for more details. When writing plugins several additional points have to be observed or taken into account:
Plugins have to be put into the same directory as the main client application and respect following naming: simExtXXXX.dll (Windows), libsimExtXXXX.dylib (Mac OSX), libsimExtXXXX.so (Linux), where XXXX is the name of the plugin. Use at least 4 characters and don't use underscores since the plugin would be ignored (however you should use underscores when your plugin itself loads some additional libraries (e.g. language resources like simExtXXXX_de.dll, etc.)).
When registering customized script functions or script variables, use a prefix and stick to it for all functions and variables that the module registers (e.g. simLab.testMemory(), simLab.errorValue, etc.).
Threads created in the plugin should be used very carefully, and should never call any simulator command (use them for background calculations or communication with hardware).
When outputting messages, use simAddLog.
You are free to compile your plugin with whatever compiler you wish. If, however, you wish to write a Qt plugin (i.e. a plugin using the Qt framework) you should remember following:
You are required to compile the plugin with the same Qt version as the one used to compile CoppeliaSim. Have a look at the CoppeliaSim [Help --> About] menu bar item for details about Qt version
You should compile the plugin with the same compiler as CoppeliaSim
For more information on plugins, refer to following repositories:
simExtPluginSkeleton: represents a plugin template that you can use to create your own plugin. See also simExtSkel
simExtVision: a plugin that handles specific vision tasks (e.g. simulation of the Velodyne sensor, or simulation of an omnidirectional camera).
simExtBubbleRob: illustrates how to add customized script functions and how to handle several specific models. Refer also to the related plugin tutorial.
simExtK3: the plugin related to the KheperaIII model.
simExtROS: the ROS package allowing you to build the ROS Interface for CoppeliaSim.
simExtROS2: the ROS 2 package allowing you to build the ROS 2 Interface for CoppeliaSim.
simExtMTB: illustrates a Qt plugin which integrates a robot language interpreter (or other emulator) into CoppeliaSim. Refer also to its related tutorial.
CoppeliaSim plugins may be published under any license.
|