V-REP 插件教程

本教程将尝试解决如何为 V-REP 编写插件。与本教程相关的 V-REP  场景文件位于 V-REP 的安装文件夹 tutorials/BubbleRobExt。可以在此处找到本教程的插件项目文件。

V-REP 在程序启动时自动加载可以在其文件夹（即安装文件夹或与包含 vrep.exe 的文件夹）中找到的所有插件。 V-REP 使用以下掩码识别插件文件：Windows 上为“v_repExt * .dll”，Mac OS 上为“libv_repExt * .dylib”，Linux 上为“libv_repExt * .so”。另外，插件的文件名不应包含任何下划线（显然除了开头的那个）。本教程的插件文件是 v_repExtBubbleRob.dll。测试时，确保在 V-REP 启动时正确加载：通过取消选中用户设置对话框中的 Hide console window（[Menu bar --> Tools --> Settings]），将控制台窗口切换为可见。此选项仅在 Windows 版本中可用。在 Mac 上，查看系统的控制台，在 Linux 上尝试从控制台启动 V-REP。控制台窗口应显示类似于此的内容：

正如您已经了解的那样，这个插件是从 BubbleRob 教程为 BubbleRob 编写的。 加载相关的场景文件（tutorials\BubbleRobExt\BubbleRobExt.ttt）。 BubbleRob 插件添加了 4个新的 Lua 命令（自定义 Lua 命令应遵循约定：名称为 “simXXX.YYY”，例如 simRob.start）：

simBubble.create

函数说明	在插件中创建BubbleRob控制器的实例。
Lua简介	number bubbleRobHandle=simBubble.create(table_2 motorJointHandles,number sensorHandle,table_2 backRelativeVelocities)
Lua参数	motorJointHandles：包含被控制的 BubbleRob 的左右马达关节的句柄的表格 sensorHandle：接近传感器或被控制的 BubbleRob 的句柄 backRelativeVelocities：当BubbleRob检测到障碍物时，它将向后移动一段时间。 relativeBackVelocities [1]：是向后移动时左轮的相对速度。 relativeBackVelocities [2]：是向后移动时右轮的相对速度
Lua返回值	-1 表示出现错误，否则为插件的 BubbleRob 控制器的句柄

 

simBubble.destroy

说明	销毁先前使用 simBubble.create 创建的 BubbleRob 控制器实例
Lua 简介	boolean result = simBubble.destroy（number bubbleRobHandle）
Lua 参数	bubbleRobHandle：先前从 simBubble.create 返回的 BubbleRob 实例句柄
Lua 返回值	出错时为false

simBubble.moveAndAvoid

说明	将 BubbleRob 设置为给定时间的自动移动模式
Lua 简介	boolean result = simBubble.moveAndAvoid（number bubbleRobHandle，number movementDuration，boolean returnDirectly = false）
Lua 参数	bubbleRobHandle:先前从 simBubble.create 返回的 BubbleRob 实例的句柄。 movementDuration: 自动移动的持续时间（以秒为单位） returnDirectly:  如果为true，则函数直接返回（非阻塞操作），否则该函数仅在自动移动完成时返回（但这需要调用脚本进行线程化）。 可以是零或省略，在这种情况下操作是阻塞的。
Lua 返回值	result: 出错时为false

simBubble.stop

说明	停止 BubbleRob 的自动移动
Lua 简介	boolean result=simBubble.stop(number bubbleRobHandle)
Lua 参数	bubbleRobHandle: 先前从simBubble.create返回的BubbleRob实例的句柄
Lua 返回值	result: 出错时为false

现在打开附加到场景中 BubbleRob 模型的线程子脚本（例如，双击场景层次结构中对象 bubbleRob 旁边的脚本图标）。 检查代码：

function sysCall_threadmain()
    -- Check if the required plugin is there:
    moduleName=0
    moduleVersion=0
    index=0
    bubbleRobModuleNotFound=true
    while moduleName do
        moduleName,moduleVersion=sim.getModuleName(index)
        if (moduleName=='BubbleRob') then
            bubbleRobModuleNotFound=false
        end
        index=index+1
    end
    if (bubbleRobModuleNotFound) then
        sim.displayDialog('Error','BubbleRob plugin was not found. (v_repExtBubbleRob.dll)&&nSimulation will not run properly',
            sim.dlgstyle_ok,true,nil,{0.8,0,0,0,0,0},{0.5,0,0,1,1,1})
    else
        local jointHandles={sim.getObjectHandle('leftMotor'),sim.getObjectHandle('rightMotor')}
        local sensorHandle=sim.getObjectHandle('sensingNose')
        local robHandle=simBubble.create(jointHandles,sensorHandle,{0.5,0.25}) -- create a BubbleRob instance
        if robHandle>=0 then
            simBubble.start(robHandle,20) -- control happens here
            simBubble.stop(robHandle)
            simBubble.destroy(robHandle) -- destroy the BubbleRob instance
        end
    end
end

代码的第一部分负责检查运行此脚本所需的插件（即 v_repExtBubbleRob.dll）是否可用（即已找到并成功加载）。如果不是，则显示错误消息。否则，检索关节和传感器句柄并将其提供给自定义Lua函数，该函数在插件中创建BubbleRob的控制器实例。如果调用成功，那么我们可以调用 simBubble.moveAndAvoid。该功能指示插件移动 BubbleRob 模型，同时避开障碍物，持续 20 秒。该函数是阻塞的（默认情况下省略的第三个参数为 false），这意味着在函数完成之前（即在 20 秒之后）调用不会返回。运行模拟：BubbleRob 移动 20 秒然后按预期停止。现在退出 V-REP。暂时将插件重命名为 TEMP_v_repExtBubbleRob.dll，以便 V-REP 不再加载它，然后再启动 V-REP。加载上一个场景并运行模拟：现在出现一条错误消息，表示找不到所需的插件。退出 V-REP，将插件重命名为 v_repExtBubbleRob.dll 并再次启动 V-REP。

让我们看一下插件如何注册和处理上述 4 个自定义 Lua 函数。打开 BubbleRob 插件项目，看看文件 v_repExtBubbleRob.cpp：

注意 3 个必需的插件入口点：v_repStart，v_repEnd 和 v_repMessage：v_repStart 在插件加载（初始化）时调用一次，v_repEnd 在插件卸载（清理）时调用一次，并且 v_repMessage 在常规上调用基于几种类型的消息。

在初始化阶段，插件加载 V-REP 库（为了能够访问所有 V-REP 的 API 函数），然后注册 4 个自定义 Lua 函数。通过指定以下内容注册自定义 Lua 函数：

一个函数名

一个调用提示字符串

期望参数列表

回调地址

当脚本调用指定的函数名时，V-REP 将尝试将提供的参数转换为回调期望的值，然后调用回调地址。回调函数内部最困难的任务是正确读取输入参数，并正确写入输出值。为了简化任务，使用了两个辅助类，分别是 CLuaFunctionData 和 CLuaFunctionDataItem，分别位于 programming/common 和 programming/include 中。

在编写自己的自定义 Lua 函数时，请尝试使用与文件 v_repExtBubbleRob.cpp 中相同的代码布局/框架。

在 4 个自定义 Lua 函数回调中的任何一个中都不会控制 BubbleRob 实例：回调只是初始化/销毁/更新数据结构。控件发生在v_repMessage 中，消息为 sim_message_eventcallback_modulehandle：当主脚本调用 sim.handleModule(sim.handle_all,false) 时，所有插件都会调用该消息，每次模拟过程都会发生一次。

通常，回调例程应该尽可能快地执行，然后控制应该返回到 V-REP，否则整个模拟器将停止。

参考资料

1.V-REP官方文档：http://www.coppeliarobotics.com/helpFiles/