Callback scripts

V-REP supports an unlimited number of callback scripts per scene. A callback script is usually needed to customize low-level control loops. Two types of callback scripts are currently supported:

  • an unlimited number of joint control callback scripts: each joint that is dynamically enabled can be controlled via a callback script.
  • one contact callback script: the way the physics engine handles contacts can be customized via a C/C++ callback mechanism, or via a callback script.
  • Following caracterises a callback script:

  • a callback script is always non-threaded.
  • a callback script might be called more than once for each simulation step.
  • a callback script handles low-level control items that the user wishes to customize. They should execute as quickly as possible, to avoid slowing down a simulation.


  • The joint control callback script

    The joint control callback script can be enabled via the joint dynamics dialog. When enabled for a given joint, then the physics engine will call the callback script with appropriate arguments, allowing the user to customize the control loop of the related joint. The joint control callback script might be called quite often, normally 10 times per simulation step for a given joint (remember that the physics engine time step, by default, is 10 times smaller that the simulation time step). For that reason, keep things simple, in order to avoid slowing down the simulation. Following represents a simple PID joint control callback script:

    -- Following data is handed over from V-REP:
    init,revolute,cyclic,jointHandle,passCnt,totalPasses,currentPos,targetPos,errorValue,
    effort,dynStepSize,lowLimit,hightLimit,targetVel,maxForceTorque,velUpperLimit=...
    
    -- The control happens here:
    -- 1. PID parameter def:
    if not PID_P then
    	PID_P=0.1
    	PID_I=0
    	PID_D=0
    end
    -- 2. Clear some values when the dynamic joint calls this the first time
    (this can happen several times, if the joint is reset dynamically):
    if init then
    	pidCumulativeErrorForIntegralParam=0
    	pidLastErrorForDerivativeParam=0
    end
    -- 3. Proportional part:
    ctrl=errorValue*PID_P
    -- 4. Integral part:
    if PID_I~=0 then
    	pidCumulativeErrorForIntegralParam=pidCumulativeErrorForIntegralParam+errorValue
    else
    	pidCumulativeErrorForIntegralParam=0
    end
    ctrl=ctrl+pidCumulativeErrorForIntegralParam*PID_I
    -- 5. Derivative part:
    ctrl=ctrl+(errorValue-pidLastErrorForDerivativeParam)*PID_D
    pidLastErrorForDerivativeParam=errorValue
    -- 6. Calculate the velocity needed to reach the position in one dynamic time step:
    velocityToApply=ctrl/dynStepSize
    if (velocityToApply > velUpperLimit) then
    	velocityToApply=velUpperLimit
    end
    if (velocityToApply < -velUpperLimit) then
    	velocityToApply=-velUpperLimit
    end
    forceOrTorqueToApply=maxForceTorque
    
    -- Following data must be returned to V-REP:
    return forceOrTorqueToApply,velocityToApply


    The contact callback script

    The contact callback script can be enabled via the environment dialog. When enabled, and the physics engine detected a collision between two respondable shapes, then the callback script will be called with appropriate arguments, allowing the user to customize the handling of contacts. The contact callback script might be called very often, sometimes more than several hundreds of times per simulation step (remember also that by default, the physics engine will be called 10 times for one simulation step). For that reason, keep things simple, in order to avoid slowing down the simulation.

    Remember that custom contact handling is linked to a given scene, and objects/models will be behaving differently in a different scene. Contact callback scripts are only recomended for users that know exactly what they are doing. Following represents a default contact callback script:

    -- Following data is handed over from V-REP:
    objectHandle1,objectHandle2,engine=...
    
    if not retTable1 then
    	if engine==sim_physics_bullet then
        	-- refer to simRegisterContactCallback for parameter description:
    		retTable1={0,0,0}
    		retTable2={1,0,0,0,0,0,0,0,0,0,0,0,0,0}
    	end
    	if engine==sim_physics_ode then
        	-- refer to simRegisterContactCallback for parameter description:
    		retTable1={0,4,4+8+16+2048}
    		retTable2={0.25,0,0,0,0.25,0,0,0,0,0,0,0,0,0}
    	end
    end
    
    -- Following data must be returned to V-REP:
    -- -1 if you don't want to handle that contact here (i.e. the default handling will be used,
    --    or the C/C++ callback will decide)
    --  0 if the 2 items should not react to collision (this overrides the default contact handling)
    --  1,tableValues1,tableValues2 if you handle this contact (this overrides the default contact handling)
    
    return 1,retTable1,retTable2

    Refer also to the regular API function simRegisterContactCallback.


    Recommended topics

  • Embedded scripts