== Interacting with SUMO using TraCI ==

TraCI stands for Traffic Control Interface, a protocol that defines messages that can be used to control a traffic simulation that runs in client-server mode. 

Communication uses TCP messages with the following structure:
{{{
+--------------------------+-----------+-----------+-----+-----------+
| message length (4 bytes) | command_1 | command_2 | ... | command_n |
+--------------------------+-----------+-----------+-----+-----------+

message length = the length of the message, including this header
}}}

A command contains the following:
{{{
+-----------------+---------------------+---------+
| length (1 byte) | identifier (1 byte) | content |
+-----------------+---------------------+---------+

length - ubyte = the length of the command (including this header)
identifier - ubyte = the identifier of the command
content = command body, contains one or  more values of predefined types
}}}
or, for longer commands
{{{
+------------+------------------+---------------------+---------+
| 0 (1 byte) | length (4 bytes) | identifier (1 byte) | content |
+------------+------------------+---------------------+---------+

Note: this makes sense because the first byte of the shorter form can never be zero.
}}}

The server will reply with a single message contaning the responses to every command received, in the same order. Every command is first acknowledged by the server with the following response
{{{
+-----------------+---------------------+-----------------+-------------+
| length (1 byte) | identifier (1 byte) | result (1 byte) | description |
+-----------------+---------------------+-----------------+-------------+

length - ubyte = the length of the response
identifier - ubyte = matches the identifier of the command sent by the client
result - ubyte = can have the following values:
   - 0x00 = success
   - 0xff = failure
   - 0x01 = not implemented
description - string = some commands also offer a description of the result
}}}

Most commands also return some values. These values are packed in a separate response that follows the acknowledge message. The general form of such a response is the following:
{{{
+-----------------+---------------------+---------+
| length (1 byte) | identifier (1 byte) | content |
+-----------------+---------------------+---------+

length - ubyte = length of the response
identifier - ubyte = identifier of the response (usually associated with the identifier of the command)
content = response body, contains the requested information
}}}

Stopping the simulation:
{{{
+---------------+-------------------+
| 0x02 (length) | 0x7f (identifier) |
+---------------+-------------------+

closes the simulation and replies with an acknowledge message
}}}

Retrieving information about lanes
{{{
+--------+-------------------+------------------+------------------+
| length | 0xa3 (identifier) | variable (ubyte) | lane ID (string) |
+--------+-------------------+------------------+------------------+

lane ID = the id of the lane
variable = the value to be retrived for the lane
   - 0x00 = list of all lane ID's (sent ID is ignored) (string*)
   - 0x31 = edge id (string)

the response has the form
+--------+-------------------+------------------+------------------+---------------------+--------------+
| length | 0xb3 (identifier) | variable (ubyte) | lane ID (string) | return type (ubyte) | return value |
+--------+-------------------+------------------+------------------+---------------------+--------------+

variable = matches the sent value
lane ID = matches the sent value
return type = the identifier of the return type
return value = value that corresponds to the return type
}}}