本页详细说明了 TraCI 协议。请参阅该页面以获取一般性介绍。
基本流程#
启动 sumo 后，客户端通过在指定的 sumo 端口上建立 TCP 连接来连接到 sumo。TraCI 支持多个客户端，并按顺序执行来自同一客户端的所有命令，直到该客户端发出 TraCI/控制相关命令#命令 0x02: 仿真步进 命令。为了有一个预定义的执行顺序，每个客户端应在第一个仿真步进之前发出 TraCI/控制相关命令#命令 0x03: SetOrder 命令。该命令为客户端分配一个编号，来自不同客户端的命令在同一个仿真步进中将按照该编号顺序执行（编号不需要连续或为正数，但必须是唯一的）。当使用多客户端设置时，启动 SUMO 时需要知道客户端的数量，并且所有客户端都需要在第一个仿真步进之前连接。
Caution
在 SUMO 0.30.0 及更早版本中，只有一个客户端可以连接到正在运行的 sumo 服务器。
图：TraCI：建立与 SUMO 的连接
客户端应用程序向 sumo 发送命令以控制仿真运行、影响单个车辆的行为或询问环境细节。sumo 对每个命令回复一个 状态 响应，以及根据给定命令返回的额外结果。
客户端必须使用 TraCI/控制相关命令#命令 0x02: 仿真步进 命令来触发 sumo 中的每个仿真步进。如果已经进行了任何 订阅，则会返回订阅的值。一旦所有客户端都发送了仿真步进命令，仿真将推进到下一步。目前，所有客户端都会收到所有订阅结果（即使订阅是由不同的客户端发出的）。
客户端负责使用 close 命令关闭连接。有关在 TraCI 模式下运行仿真的差异的更多信息，请参见 仿真/基本定义#定义要仿真的时间段。当所有客户端都发出 close 命令后，仿真将结束，并释放所有资源。
图：TraCI：关闭与 SUMO 的连接
消息#
TCP 消息充当命令或结果列表的容器。因此，每个 TCP 消息都由一个小的头部（给出整个消息的大小）和其后的一组命令组成。每个命令的长度和标识符都放在命令之前。此容器的结构如下所示：
0 7 8 15
+--------------------------------------+
| Message Length including this header |
+--------------------------------------+
| (Message Length, continued) |
+--------------------------------------+ \
| Length | Identifier | |
+--------------------------------------+ > Command_0
| Command_0 content | |
+--------------------------------------+ /
...
+--------------------------------------+ \
| Length | Identifier | |
+--------------------------------------+ > Command_n-1
| Command_n-1 content | |
+--------------------------------------+ /
在某些情况下，单个命令的长度可能不够，因为最大命令长度限制为 255。在这些情况下，可以通过将原始 ubyte 长度字段设置为零并添加一个整数长度字段来使用扩展长度。命令的扩展方案如下所示：
0 7 8 15
+--------------------------------------+ \
| Length = 0 | | |
+-------------------+ | |
| 32 bit Integer Length | |
| +------------------+ > Command
| | Identifier | |
+--------------------------------------+ |
| Command content | |
+--------------------------------------+ /
为了简化 TraCI 的使用，我们提供了一个用于处理套接字连接的类和另一个用于从基本数据类型组合消息的类。这些类的 C++ 实现可在 <SUMO_HOME>/src/foreign/tcpip 找到，Python 实现位于 <SUMO_HOME>/tools/traci/connection.py 和 <SUMO_HOME>/tools/traci/storage.py。有关 Java 实现，请查看 <SUMO_HOME>/tools/contributed/traas。类 tcpip::Socket 在服务器端和客户端处理 TCP 连接。类 tcpip::Storage 设计用于保存基本数据类型的列表。通过使用方法 tcpip::Socket::sendExact(tcpip::Storage) 和 tcpip::Socket::receiveExact(Storage)，可以将消息作为 Storage 对象发送和接收。
状态响应#
| ubyte | string |
|---|---|
| 结果 | 描述 |
每个命令都由一个状态响应确认，其中包括一个结果和一个描述。标识符指的是被确认的相应命令的标识符。 结果可以有以下值：
- 0x00 表示成功
- 0xFF 表示请求的命令失败
- 0x01 表示网络模拟器中未实现请求的命令（此外，必须添加描述文本）
数据类型#
原子类型#
下表显示了支持的基本数据类型：
| 数据类型 | 大小 | 描述 | 标识符 |
|---|---|---|---|
| ubyte | 8 位 | 整数 (0 到 255) | 0x07 |
| byte | 8 位 | 整数 (-128 到 127) | 0x08 |
| integer | 32 位 | 整数 (-231 到 231-1) 包括位集，其中 bit0 表示最低有效位 |
0x09 |
| double | 64 位 | IEEE754 浮点数 | 0x0B |
| string | 可变 | 32 位字符串长度，后跟以 8 位 ASCII 编码的文本 | 0x0C |
| stringList | 可变 | 32 位字符串计数 n，后跟 n 个字符串 | 0x0E |
| compound object | 可变 | 复合对象，内部结构取决于具体对象。复合对象标识符后总是跟着一个 32 位整数，表示组件类型的数量。然后按顺序给出组件。 | 0x0F |
组合类型#
以下描述组合数据类型。
位置表示#
2D 位置 (ubyte 标识符: 0x01)
仿真网络中的笛卡尔 2D 位置，由两个 double 值（x 和 y 坐标）描述。
3D 位置 (ubyte 标识符: 0x03) 仿真网络中的笛卡尔 3D 位置，由三个 double 值（x、y 和 z 坐标）描述。
道路地图位置 (ubyte 标识符: 0x04) 另一种位置描述，sumo 在大多数情况下也使用这种描述。RoadId 标识一个路段（边），Pos 描述节点在纵向方向上的位置（范围从 0 到道路长度）。LaneId 标识路段上的行驶车道。车道从右到左依次编号，从 0 开始。
经纬度位置 (ubyte 标识符: 0x00) 仿真网络中地理坐标系下的位置，由两个 double 值（经度和纬度）描述。
经纬度海拔位置 (ubyte 标识符: 0x02) 仿真网络中带海拔的地理坐标系下的位置，由三个 double 值（经度、纬度和海拔）描述。
多边形 (ubyte 标识符: 0x06)#
一系列 2D 点，表示一个多边形形状。Length 是构成多边形的 (x,y) 点的数量。
交通灯相位列表 (ubyte 标识符: 0x0D)#
此类型用于报告交通灯的不同相位。总共报告 Length 个相位，以及受相应交通灯相位影响的前置和后继道路。
相位存在以下标识符：
- 0x01: 红灯
- 0x02: 黄灯
- 0x03: 绿灯
- 0x04: 交通灯关闭并闪烁
- 0x05: 交通灯关闭，不闪烁
颜色 (ubyte 标识符: 0x11)#
一个 R,G,B,A 四元组，每个分量为无符号字节 (0-255)。