Use SUMO from another program

[RobertHilbrich]

As a
Regular User

I want to
use SUMO from another program

In order to
model how road traffic participants behave

Acceptance criteria

• my software stack will be able to tell me whether a compatible version of SUMO is being used
• my software stack will be able to tell me if SUMO has started successfully and when it is ready to serve requests from other components of the stack
• within reason, I can upgrade to a more modern version of SUMO without having to upgrade other parts of the software stack (and vice versa)

[behrisch]

Compatibility is always subject to the part of the API being used. Currently this is ensured by the TraCI version number. What else do we need here?

• Ask for the presence of single functions / commands (some kind of reflection API)?
• Always maintain backwards compatibility?

The current behavior of traci.start (and init) is to return the version number when everything is set up and usable. Does this already solve point 2?

[sommer]

Sure! This is why I introduced command 0x00 (CMD_GETVERSION) to allow obtaining an API version number back in the year 2010 :-)

I don't think I've every clearly communicated what I wanted with this number, though. Today, the Wiki (now: docs) has a mix of what I hoped and didn't hope to achieve. This way, in the past, this number has sometimes been incremented when SUMO introduced new commands and not been incremented when SUMO expected different data for existing commands.

This, however, is contrary to what I hoped to have:

• If a new SUMO version introduces a new command or new, optional parameters, there's no need to change the API version: no existing software breaks just because a new command is offered. Old software sending the same data still results in the same behavior of SUMO.
• If a new SUMO version changes the order in which parameters are expected (or changes the expected data type), however, the API version should change, even though the "feature set" is the same: Old software sending the same data would now result in different behavior (or crashes) of SUMO.

[behrisch]

@sommer I completely agree with the intended use of the API version (and must admit that in the past we probably incremented it rather too often). The question here is rather: Do we need something more fine grained or is this all just a matter of "discipline"? Should we, for instance, have a version number for every domain (vehicle, edge, etc.)?

[kschrab]

So the API version should not be increased if a new feature /command is introduced? Let's suppose I want to support a new TraCI command. How can I check then if the connected SUMO instance supports the command I want to excute or not, if the API version has not been increased with the new feature?

[behrisch]

You can check the SUMO version then, which is transmitted as well.

[sommer]

Right. I would argue that, when writing external software, it is rather straightforward to say whether it is safe to be used with any known version of SUMO (worst case by maintaining a whitelist of version identifiers).

The hard question, in my view, is "I am connected to a version of SUMO that is newer than what I know. Can I just treat it like the latest version I know and everything will work as expected?".

The API version scheme I outlined in #2 (comment) should make this possible. We'd just need a tweak of the documentation outlining the "new rules" for when to (and when not to) increment API version (and, of course, put them into practice).

If a whitelist of version identifiers is undesirable, adopting something like semantic versioning (e.g., https://semver.org/) for the TraCI API might be an option (then presence of a feature could be checked via a comparison of minor version numbers).

[behrisch]

Currently this seems to be rather a policy issue than one where coding is involved. So we decided on the meeting in Ludwigsburg to discuss this in the next openMobility meeting but as of now do not derive any SUMO issues here.

[behrisch]

I tried to give a reasoning about SUMO version numbers here: https://sumo.dlr.de/docs/Versioning.html and especially about TraCI here: https://sumo.dlr.de/docs/TraCI/Control-related_commands.html Please give feedback.

[sommer]

Sounds perfect to me