VISSIM信号控制机接口

本文格式为Word版，下载可任意编辑——VISSIM信号控制机接口VISSIM信号控制机DLL接口

LK2023-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必需在预处理程序中定义（MicrosoftVisual

C++7.0underProperties–C/C++–Preprocessor–PreprocessorDefinitions）?英文的错误信息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中相关对象。假使控制机规律使用了不同的内部编号，主函数必需自己来寻觅对应关系。当所有的VISSIMSC使用同一个控制机DLL文件时，主函数需要操作多个信号控制机的数据-除非每一个VISSIMSC都分派一个不同的DLL。

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

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

VISSIM中的执行

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

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

VISSIMSignalControllerGUIDLLInterface===================================

外部的GUIDLL用于SC的“NEMA〞和“外部的〞信号控制类型。这种控制机的所有数据只能在DLL的GUI中编辑并且只能保存在一个（或两个）独立的数据文件中。在VISSIM中，用户只可以编辑DLL和信号控制机的名称（数据文件的名称将会在“外部信号控制机〞对话框中显示，但是用户不能在此修改）。这四个文件名全部保存在*.INP文件中。

GUIDLL函数在下面的两种状况下被调用：

A）当用户在“控制机（外部的）〞标签中选择了“参数〞选项。B）仿真运行开始时

在状况A下，用户想要编辑信号控制机的参数然后回到VISSIM。流程如下：1)VISSIM使用SIGNALGUI_COMMAND_INIT_CONTROLLER和所选的信号控制机

编号作为参数来调用SignalGUIExecuteCommand()函数。DLL初始化控制机的数据结构（特别是该信号控制机信号灯组的配置）。

2)通过屡屡调用DLL函数SignalGUISetValue()，VISSIM将input文件名，路径和数

据文件名（假使之前未选择DLLGUI则为空）传回到DLL中。

3)VISSIM使用SIGNALGUI_COMMAND_READ_DATA_FILES作为参数来调用

SignalGUIExecuteCommand()函数。GUIDLL读取数据文件（假使存在）。4)通过屡屡调用DLL函数SignalGUISetValue()，VISSIM将定义好的信号灯组传回到

DLL中。（假使控制机类型为NEMA，来自VISSIM许可的NEMA层将同样被传回。）5)VISSIM

使用

SIGNALGUI_COMMAND_EDIT_SC_PARAMETERS

或是

_SG_PARAMETERS作为参数来调用SignalGUIExecuteCommand()函数。GUIDLL显示了一个对话框/窗口（可能是子对话框）。

用户可以在其中编辑信号控制的参数并通过“取消〞或“确定〞来关闭它。假使点击了“确定〞，DLL将保存所有的修改到数据文件。DLL关闭对话框。

返回被调用的的函数SignalGUIExecuteCommand()。

6)VISSIM通过屡屡调用DLL函数SignalGUISetValue()来获得控制机的基本数据（周

期和数据文件的名称）和新的信号灯组配置：首先所有信号灯组的编号改变（它将

传送到所有涉及到旧编号的路网元素，例如，信号灯，红灯右转标志，优先规则），然后新的信号灯组编号被创立，最终（可能会）改变所有信号灯组的名称。在状况B下，VISSIM需要将基本的信号控制数据回传到控制机EXE中（通过DDE接口）。流程如下：

1）VISSIM使用SIGNALGUI_COMMAND_INIT_CONTROLLER和所选的信号控制机编号作为参数来调用SignalGUIExecuteCommand()函数。DLL初始化控制机的数据结构（特别是该信号控制机信号灯组的配置）

2）通过屡屡调用DLL函数SignalGUISetValue()，VISSIM将input文件名，路径和数据文件名（假使之前