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:

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#

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.