• Object Variable Subscription

Object Variable Subscription

---

Introduction#

Variable subscriptions allow you to ask once for a set of a structure's variables and retrieve them periodically. In accordance to plain value retrieval commands (0xa0-0xae) the subscription commands are split by the "domain" - the type of the structure:

• command 0xd0: retrieve information from an induction loop (for a list of retrievable variables, see Induction Loop Value Retrieval)
• command 0xd1: retrieve information from a multi-entry/multi-exit detector (see Multi-Entry-Exit Detectors Value Retrieval)
• command 0xd2: retrieve information from a traffic light (see Traffic Lights Value Retrieval)
• command 0xd3: retrieve information from a lane (see Lane Value Retrieval)
• command 0xd4: retrieve information from a vehicle (see Vehicle Value Retrieval)
• command 0xd5: retrieve information from a vehicle type (see Vehicle Type Value Retrieval)
• command 0xd6: retrieve information from a route (see Route Value Retrieval)
• command 0xd7: retrieve information from a point-of-interest (see PoI Value Retrieval)
• command 0xd8: retrieve information from a polygon (see Polygon Value Retrieval)
• command 0xd9: retrieve information from a junction (see Junction Value Retrieval)
• command 0xda: retrieve information from an edge (see Edge Value Retrieval)
• command 0xdb: retrieve information from the simulation (see Simulation Value Retrieval)

The subscription for a structure's variables is initiated using a "Subscribe ... Variable" command (0xd0-0xde). The command is evaluated immediately on request, verifying it this way. It returns a "Subscribe ... Variable" response (0xe0-0xee). In the case of vehicles, the subscription is descheduled as soon as the vehicle leaves the simulation.

As soon as the subscription was accepted, it is executed after each call of Simulation Step(2) command.

Command 0xdX: Subscribe ... Variable#

time	time	string	ubyte	ubyte[n]
begin Time	end Time	Object ID	Variable Number	The list of variables to return

Some notes:

• begin Time: the subscription is executed only in time steps >= this value; in ms
• end Time: the subscription is executed in time steps <= this value; the subscription is removed if the simulation has reached a higher time step; in ms
• The size of the variables list must be equal to the field "Variable Number".

Response 0xeX: ... Subscription Response#

string	ubyte	ubyte	ubyte	ubyte	<return_type>	...	ubyte	ubyte	ubyte	<return_type>
Object ID	Variable Count	Variable #1 Id	Variable #1 status	Return type of the variable #1	<VARIABLE_VALUE#1>	...	Variable #n Id	Variable #n status	Return type of the variable #n	<VARIABLE_VALUE#n>

The respond to a "Subscribe ... Variable".

The status is 0x00 (RTYPE_OK) if the variable could be retrieved successfully. If not, the status is 0xff (RTYPE_ERR). In the second case, the variable type is set to string and the variable value contains the error message.

Variable Count is the number of subscriptions which are returned.

Client library methods#

• In the python library, all domains support the methods subscribe and unsubscribe
• In the C++ library, the method simulation.subscribe takes an additional argument that encodes the domain

Special Cases#

• The VAR_LEADER variable is special because the getLeader (0x68) command requires an additional distance argument. To subscribe to VAR_LEADER, the function subscribeLeader is provided by the python client.
• The VAR_PARAMETER_WITH_KEY generic variable is special because the getParameterWithKey (0x3e) command requires an additional key argument. To subscribe to VAR_PARAMETER_WITH_KEY, the function subscribeParameterWithKey is provided by the python client.

Subscriptions with Parameters#

In addition to the two special cases above there is a general mechanism to subscribe to values which need extra parameters. In general you need to provide an additional map as parameter to the function where the key is the variable you want to subscribe to and the value is the value of the parameter (wrapped in the corresponding TraCIResult object in the C++ / Java case).

If you need to subscribe to a value with multiple parameters this is currently only possible in python. You need to give a tuple of values where the first item describes the types of the parameters (always starting with a "t" for tuple and then "d", "i", "s" for floats, integers and strings respectively). The second item is the number of parameters and then the actual parameter values. One example would be: param = {traci.constants.VAR_STOP_SPEED: ("tdd", 2, 0., 0.)}.