TraCI/Protocol

This page details the TraCI protocol. Please see there for a general introduction.

1 Basic Flow
2 Messages
- 2.1 Status Response
3 Data types
- 3.1 Atomar Types
- 3.2 Composed Types

Basic Flow

After starting SUMO, a client connects to SUMO by setting up a TCP connection to the appointed SUMO port.

Figure:TraCI: establishing a connection to SUMO

The client application sends commands to SUMO to control the simulation run, to influence single vehicle's behavior or to ask for environmental details. SUMO answers with a Status-response to each command and additional results that depend on the given command.

The client has to trigger each simulation step in SUMO using the TraCI/Control-related commands#Command 0x02: Simulation Step command. If any subscriptions have been done, the subscribed values are returned.

The client is responsible for shutting down the connection using the close command. See Simulation/Basic Definition#Defining the Time Period to Simulate for further information on differences between running the simulation in TraCI-mode. The simulation will end, freeing all resources.

Figure:TraCI: closing a connection to SUMO

Messages

A TCP message acts as container for a list of commands or results. Therefore, each TCP message consists of a small header that gives the overall message size and a set of commands that are put behind it. The length and identifier of each command is placed in front of the command. A scheme of this container is depicted below:

 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         |  |
+--------------------------------------+  /

In some cases the length of a single command may not suffice, since the maximum command length is limited to 255. In those cases an extended length can be used by setting the original ubyte length field to zero and adding an integer length field. This extended scheme for a command looks as follows:

 0                 7 8               15
+--------------------------------------+  \
|   Length = 0      |                  |  |
+-------------------+                  |  |
|        32 bit Integer Length         |  |
|                   +------------------+   > Command
|                   |   Identifier     |  |
+--------------------------------------+  |
|            Command content           |  |
+--------------------------------------+  /

To simplify the usage of TraCI, we provide a class for handling the socket connection and another for composing a message out of basic data types. The C++ implementation of these classes is available by using subversion and the repository path https://shawn.svn.sourceforge.net/svnroot/shawn/src/apps/tcpip. The Java implementation will be published soon. The class tcpip::Socket handles a TCP connection on server as well as on client side. The class tcpip::Storage is designed to hold a list of elementary data types. By using the method tcpip::Socket::sendExact(tcpip::Storage) and tcpip::Socket::receiveExact(Storage), messages can be send and received as Storage objects.

Status Response

Result	Description
ubyte	string

Each command is acknowledged by a status response, included are a Result and a Description. The identifier refers to the identifier of the respective command that is acknowledged.
Result can have the following values:

0x00 in case of succes
0xFF if the requested command failed
0x01 if the requested command is not implemented in the network simulator (in addition, a Description text must be added)

Data types

Atomar Types

The following table shows the supported elementary data types:

Data type	Size	Description	Identifier
ubyte	8 bit	integer numbers (0 to 255)	0x07
byte	8 bit	integer numbers (-128 to 127)	0x08
integer	32 bit	integer numbers (-2³¹ to 2³¹-1)	0x09
float	32 bit	IEEE754 floating point numbers (see note)	0x0A
double	64 bit	IEEE754 floating point numbers	0x0B
string	variable	32 bit string length, followed by text coded as 8 bit ASCII	0x0C
stringList	variable	32 bit string count n, followed by n strings	0x0E
compound object	variable	Compound object, internal structure depends on concrete object	0x0F

Composed Types

In the following, composed data types are described.

Position Representations

2DPosition (ubyte identifier: 0x01)

A cartesian 2D position within the simulation network, described by two double values (x and y coordinate).

0	0	0	0	0	0	0	1	X	Y
ubyte								double	double

3DPosition (ubyte identifier: 0x03) A cartesian 3D position within the simulation network, described by three double values (x, y and z coordinates).

0	0	0	0	0	0	1	1	X	Y	Z
ubyte								double	double	double

Road Map Position (ubyte identifier: 0x04) Alternative position description that is also used by SUMO in most cases. RoadId identifies a road segment (edge), Pos describes the position of the node in longitudinal direction (ranging from 0 to the road's length). LaneId identifies the driving lane on the road segment. Lanes are numbered sequentially from right to left starting with 0.

0	0	0	0	0	1	0	0	RoadId	Pos	LaneId
ubyte								string	double	ubyte

Lat-Lon-Position (ubyte identifier: 0x00) A position within the simulation network in geo-coordinates, described by two double values (latitude and longitude).

0	0	0	0	0	0	0	0	Latitude	Longitude
ubyte								double	double

Lat-Lon-Alt-Position (ubyte identifier: 0x02) A position within the simulation network in geo-coordinates with altitude, described by three double values (latitude, longitude, and altitude).

0	0	0	0	0	0	1	0	Latitude	Longitude	Altitude
ubyte								double	double	double

Boundary Box (ubyte identifier: 0x05)

A boundary box represented by its lower left and upper right corner.

0	0	0	0	0	1	0	1	LowerLeftX	LowerLeftY	UpperRightX	UpperRightY
ubyte								double	double	double	double

Polygon (ubyte identifier: 0x06)

A sequence of 2D points, representing a polygon shape. Length is the number of (x,y) points that make up the polygon.

0	0	0	0	0	1	1	0	Length	X	Y	...
ubyte								ubyte	double	double

Traffic Light Phase List (ubyte identifier: 0x0D)

This type is used to report the different phases of a traffic light. A total of Length phases is reported together with the preceding and succeeding roads that are affected by the respective light phase.

The following identifiers for a phase exist:

0x01: red
0x02: yellow
0x03: green
0x04: traffic light is off and blinking
0x05: traffic light is off, not blinking

0	0	0	0	1	1	0	1	Length	PrecRoad	SuccRoad	Phase	...
ubyte								ubyte	string	string	ubyte

Color (ubyte identifier: 0x11)

A R,G,B,A-quadruple of unsigned byte (0-255).

0	0	0	1	0	0	0	1	R	G	B	A
ubyte								ubyte	ubyte	ubyte	ubyte

This page was last modified on 14 September 2012, at 10:13.

User

Further Resources

Developer