VISSIM信号控制机接口

VISSIM 信号控制机DLL接口

LK 2007-05-23

本文档说明了在仿真运行期间外部信号控制机是怎么样通过VISSIM全新的DLL接口来使用的（从VISSIM4.10起可以使用）。

简介

VISSIM中有两种可以直接使用信号控制机的类型，一种是定周期的，一种是VAS。其他所有的信号控制机类型都是外部的，并且每一种都需要相应的程序文件来支持。如果该程序文件是使用了老的DDE接口的可执行文件（.exe），在仿真执行期间每个信号控制机都会创建一个.exe的实例。如果我们的程序文件是使用了最新DLL接口的动态链接库文件（.dll）。这就意味着在仿真运行期间，我们只需要加载一次dll文件就可以控制相关的信号控制机的逻辑和数据。

信号控制机的频率（通常为1/S）是指每一仿真秒信号控制机刷新（通过控制机的逻辑）的次数。在程序初始化时由外部信号控制机来设置。VISSIM仿真的精度（每一仿真秒的仿真时间步长）必须是信号控制机频率的倍数。非倍数的数值会引起运行时的错误（例如：如果仿真精度为10，信号控制机的频率为2，VISSIM在2个信号逻辑中间会完成5个时间仿真步长）。

在每个信号控制机的时间步长中，VISSIM在当前仿真时间步长结束时都会和所有信号控制机的DLL通信。首先，当前的信号灯状态和所有信号控制机的检测器数据都将传送到相关的DLL文件中。第二步，DLL文件被要求来计算稍后会回传到VISSIM的期望的信号灯的状态。根据控制机逻辑的参数设置，无论是信号状态立即响应还是自动插入相应的转换状态（例如，当从绿灯变为红灯时，需要加入黄灯），都会像VISSIM中定义信号灯组参数一样。在下一仿真时间步长，VISSIM中的车辆将会检测到新的信号灯状态。

模块结构

VISSIM信号控制DLL的源代码由控制与VISSIM通信的框架以及包含了感应控制逻辑的主函数组成。PTV已经完成这个框架的C（++）源代码，用户只需要编写

sc_dll_main.cpp这个文件来实现与主函数的连接。当然，主函数也必须是以C

（++）源代码的形式存在。合适的主函数必须通过sc_dll_main.cpp来调用，同时它也能从自身的sc_dll_functions.cpp/.h文件中调用数据读取函数。主函数DLL通信的具体技术细节是开放透明的。

（如果一个含有存在接口(例如，TCP/IP)的控制进程连接到VISSINM，我们建议用户在VISSIM数据格式和控制机数据格式间，创建一个信号控制DLL文件。在这种情况下，信号控制DLL和控制机进程间的通信操作需要在主函数中定义完成。）

控制流程

仿真一开始VISSIM就会加载当前路网文件中至少一个信号控制机的DLL。（DLL文件必须和vissim.exe存放在同一目录下或在当前的数据路径中。） 随后按顺序进行的SC初始化包含两个步骤：

第一，VISSIM调用SC_DLL_ReadDataFiles()函数。这个函数具有最多2个数据文件名做为参数，该参数可以输入到VISSIM的SC对话框中。如果外部信号控制机使用数据文件，例如，不是所有的程序都必须在dll中编写代码，一个需要读取这些数据文件的主函数需要通过SC_DLL_ReadDataFiles()调用。

第二，VISSIM调用SC_DLL_Init()函数。如果需要的话，主函数通过该函数来初始化控制机的逻辑。如果信号控制机的频率不是默认值，SC_DLL_Init()将会调用

SC_SetFrequency()函数。

在每一个控制时间步长里，VISSIM都会为每一个SC调用一次

SC_DLL_Calculate()。通过这个函数，主函数被调用并通过信号控制机逻辑来执

行。通过sc_dll_functions.cpp/.h函数模块，主函数可以连接到检测器数据和获得信号灯的信息（全部使用该DLL的SC）。在同一模块里，还具有可以设置信号灯新状态以及传送其它路网参数到VISSIM中功能的函数，以及运行错误信息显示函数。从SC_DLL_Calculate()中返回后，新的信号灯状态将被设置，其它需要从DLL传回VISSIM的参数将被自动传回。

在运行仿真结束后，VISSIM会为每一个SC调用一次SC_DLL_Cleanup()。如果需要，信号控制逻辑函数将退出。

如果在仿真期间，用户选择仿真/保存Snapshot，VISSIM将会调用

SC_DLL_WriteSnapshotFile()函数。控制机的DLL会在snapshot文件中保存完整的

内部状态，使用原有的文件名（*.snp加SC编号）。

如果用户在VISSIM菜单中选择仿真/加载Snapshot，VISSIM将会先调用

SC_DLL_ReadDataFiles()函数后再调用SC_DLL_ReadSnapshotFile()函数而不是

之前的SC_DLL_Init()函数。

框架的执行

作为一种新的信号控制类型，VISSIM的信号控制DLL只需要用户编写

sc_dll_main.cpp 和 lsa_rahm.h两个文件。框架中的其它模块不用更改。（PTV公

司在将来可能会对框架进行修改，但是从两方面同时进行修改的难度较大。当然，我们始终欢迎广大的用户为我们提出宝贵的意见和建议。）

lsa_rahm.h中需要修改的部分：

? 定义CONTROLLER_DLL_NAME为一个包含了新DLL名称的字符串

sc_dll_main.cpp中需要添加的部分

? SC_DLL_ReadDataFiles()用来读取控制机的数据文件，该数据文件需要和

*.inp文件放置在同一目录下。

? SC_DLL_Init()用来初始化控制机（如果该初始化函数存在）

? SC_SetFrequency()用来设置控制机的频率，当控制机的频率不同于默认值

时。它位于SC_DLL_Init()函数中。所有外部信号控制机的频率需要一致（未来可能会修改。）

? SC_DLL_Calculate()用来计算每一个时间步长的信号逻辑。如果信号控制机

是网络控制类型，它可能只需要调用一次控制逻辑在每一个控制时间步长，但是SC_DLL_Calculate()为VISSIM中SC的调用由DLL来控制。在这种情况下，一些检测代码需要插入，如果这是一个新的控制时间步长，例如，在上次调用SC_DLL_Calculate()期间，比较Sim_Time()当前返回值和分配到该值的静态变量。

? SC_DLL_Cleanup()用来退出控制，清空分配的内存。

? SC_DLL_WriteSnapshotFile()用来将控制机的内部状态写入到snapshot 文件

中 (*.snp)

? SC_DLL_ReadSnapshotFile()用来读取之前写入snapshot 文件 (*.snp)的控

制机数据。先调用初始化函数（如果存在）。 所有的说明都在源代码中使用###中标出。 项目属性：

? SC_DLL_EXPORTS为了编译DLL必须在预处理程序中定义（Microsoft Visual

C++ 7.0 under Properties – C/C++ – Preprocessor – Preprocessor Definitions） ? 英文的错误信息lsa_ra_e.rc德文的错误信息lsa_rahm.rc需要包含在项目

内（头文件都是lsa_rahm.rh）

主函数的执行

在执行SC_DLL_Calculate()期间，所有在sc_dll_functions.h头文件中的函数都可以通过主函数来调用，例如，连接检测器数据和从VISSIM获得信号灯信息。新的信号灯的状态也是从主函数通过函数SG_SetState()来设置，并自动将

SC_DLL_Calculate()的返回值传回到VISSIM。如果SC具有不同的周期时长，

SC_SetCycleSecond()函数将被调用，以便使VISSIM获得当前的周期时间。通过SC_WriteRecordValue()函数信号控制机/检测器的数据或信号时间表窗口都会被反

馈给VISSIM。所有的SC，信号灯组和检测器的编号做为sc_dll_functions.cpp中的参数用于定义VISSIM中相关对象。如果控制机逻辑使用了不同的内部编号，主函数必须自己来寻找对应关系。当所有的VISSIM SC使用同一个控制机DLL文件时，主函数需要操作多个信号控制机的数据-除非每一个VISSIM SC都分配一个不同的DLL。

如果函数IsConsoleMode()返回值为TRUE，主程序将不会在屏幕（对话框或窗口）显示任何内容。如果VISSIM运行在控制台模式下，例如，并行计算版本中，多次运行或用户通过COM来调用启动程序。

DLL文件创建的输出文件名应该包含了函数的ProcessSimRunID()返回值，如果返回值不是0。该代码由VISSIM生成，用来指示进程的ID（在并行计算中）和仿真运行的索引（在多运行模式下）：100 * 进程 ID + 仿真运行索引 (从1开始).

VISSIM中的执行

通常一个新的信号控制DLL能过直接连接到VISSIM而不需要改变任何源代码。在这种情况下，SC的类型需要选择为“外部”。（请看文档Signal GUI DLL Interface，来在VISSIM附加的窗口中编辑控制机和信号灯组数据）。只有PTV的开发部门才可以在VISSIM SC列表中添加新的控制类型。如果信号控制方案需要额外的数据，而VISSIM现有框架中又不能直接提供的话，这就需要PTV开发人员来参与支持开发。

每一个VISSIM使用的信号控制DLL都需要由一个或多个*.wtt文件组成（用户在信号控制窗口中定义）。通常，我们只需要一个空白文件，但是如果需要额外的参数（除了VISSIM中直接可用的信号灯组的状态和检测器的状态）从DLL中发送到信号时间表或SC/检测器记录中，用户就需要自定义一个*.wtt 文件。