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.