Plexe API

Plexe APIs extends the TraCI methods that standard Veins provides to enable some specific platooning functionalities. The methods are defined and implemented in src/plexe/mobility/CommandInterface.*. API methods can be invoked using the plexeTraciVehicle interface pointer in the modules. You find the plexeTraciVehicle interface pointer already declared in most of the modules in src/plexe. To load the pointer on your own, declare the following variables

1
2
traci::CommandInterface* plexeTraci;
std::unique_ptr<traci::CommandInterface::Vehicle> plexeTraciVehicle;

and set their values in the following way within the initialize method of your module

1
2
3
auto plexe = FindModule<PlexeManager*>::findGlobalModule();
plexeTraci = plexe->getCommandInterface();
plexeTraciVehicle.reset(new traci::CommandInterface::Vehicle(plexeTraci, mobility->getExternalId()));

Through plexeTraciVehicle Plexe offers the following APIs:

• unsigned int getLanesCount() Returns the number of lanes of the edge the vehicle is currently traveling on.
• void setLeaderVehicleData(double controllerAcceleration, double acceleration, double speed, double positionX, double positionY, double time) Pass leader information to SUMO to be used by the CACC. This information is used by the California PATH and the Flatbed CACCs. This method substitutes the old setPlatoonLeaderData(), which is still available but deprecated. Parameters:
  • controllerAcceleration: control input (desired acceleration) in m/s/s
  • acceleration: acceleration in m/s/s
  • speed: speed in m/s
  • positionX: leader x position in m
  • positionY: leader y position in m
  • time: time at which the data has been measured in s
• void setFrontVehicleData(double speed, double acceleration, double positionX, double positionY, double time) Pass front vehicle information to SUMO to be used by the CACC. This information is used by the California PATH, the Ploeg’s, and the Flatbed CACCs. This method substitutes the old setPrecedingVehicleData(), which is still available but deprecated. The definition of the parameters is the same as for setLeaderVehicleData.
• void getVehicleData(Plexe::VEHICLE_DATA *data) Returns information about the own vehicle. The parameter is a struct to make it easy to extend the information returned by this function.
• void setParameter(const std::string &parameter, value) This method is the main access points to the SUMO model via the TraCI interface. It permits to set values and parameters for the platooning car following model. The constants are defined within CC_Const.h (on both SUMO and Veins). This method substitutes the old setGenericInformation(), which is not available anymore. The parameters are the following:
  • parameter: a string identifying the parameter. Please see below
  • value: an int, a double, or a string with the value of the parameter to be set For a complete list of parameters, please see the CC_Const.h file. Some of them include:
  • CC_PAR_VEHICLE_POSITION: sets the position of the vehicle in the platoon (0 based)
  • CC_PAR_PLATOON_SIZE: sets the number of vehicles in the platoon of this vehicle
  • CC_PAR_CACC_XI: sets the Xi parameter of the PATH CACC
  • CC_PAR_CACC_OMEGA_N: sets the Omega_n parameter of the PATH CACC
  • CC_PAR_CACC_C1: sets the C1 parameter of the PATH CACC
  • CC_PAR_ENGINE_TAU: sets the engine time constant in seconds when using a first order lag engine model
  • CC_PAR_PLOEG_H: sets the headway time in seconds for the Ploeg CACC
  • CC_PAR_PLOEG_KP: sets the kp parameter for the Ploeg CACC
  • CC_PAR_PLOEG_KD: sets the kd parameter for the Ploeg CACC
  • CC_PAR_VEHICLE_ENGINE_MODEL: sets the engine model to be used. Possible values are CC_ENGINE_MODEL_FOLM and CC_ENGINE_MODEL_REALISTIC for choosing the first order lag and the realistic model, respectively.
  • CC_PAR_VEHICLES_FILE: sets the XML files to be used by the realistic engine model for loading engine parameters of different vehicles.
  • CC_PAR_VEHICLE_MODEL: sets the vehicle model to be loaded from the specified XML file. Possible values available in the sample vehicles file in examples/engine/sumocfg/vehicles.xml are alfa-147, bugatti-veyron, and audi-r8.
• void getParameter(const std::string &parameter, &value) This is the getter counterpart of setParameter, used to retrieve information from a vehicle.This method substitutes the old getGenericInformation(), which is not available anymore. This method is mainly used by the Plexe APIs to retrieve information from the model, and it might not even be needed for the majority of use cases. The parameters are:
  • parameter: a string identifying the parameter
  • value: an int, a double, or a string where the value of the parameter will be stored
• void setCruiseControlDesiredSpeed(double desiredSpeed) Sets the desired speed (in m/s) for the cruise control when using the ACC.
• void setActiveController(enum ACTIVE_CONTROLLER activeController) Sets the controller longitudinally driving the vehicle. Possible values (defined in CC_Const.h) are:
  • Plexe::DRIVER: let the car be controlled by a human-behavioral model. In the current implementation, Plexe uses the Krauss model
  • Plexe::ACC: use a standard Adaptive Cruise Control
  • Plexe::CACC: use the Cooperative Adaptive Cruise Control developed in the California PATH project
  • Plexe::FAKED_CACC: use the Cooperative Adaptive Cruise Control developed in the California PATH project but use the data set via the setLeaderVehicleFakeData and setFrontVehicleFakeData methods. This can be useful to bring the vehicle close to a platoon for joining using the CACC
  • Plexe::PLOEG: use the Cooperative Adaptive Cruise Control developed by Ploeg et. al.
  • Plexe::CONSENSUS: use the Cooperative Adaptive Cruise Control developed by Santini et. al.
  • Plexe::FLATBED: use the Cooperative Adaptive Cruise Control developed by Ali et. al.
• enum ACTIVE_CONTROLLER getActiveController() Returns which control model is driving the car.
• void setCACCConstantSpacing(double spacing) Sets the constant spacing (in meters) for the PATH’s CACC.
• double getCACCConstantSpacing() Returns the constant spacing (in meters) for the PATH’s CACC.
• void setACCHeadwayTime(double headway) Sets the headway time (in seconds) for the ACC.
• void setFixedAcceleration(int activate, double acceleration) Imposes a constant acceleration to a vehicle. This can be used to speed up or to brake the car. The parameters are:
  • activate: to enable a constant acceleration, set this parameter to 1. By setting it to 0, the model uses the acceleration computed by the controller chosen via the setActiveController method
  • acceleration: the acceleration in m/s/s. Set to a negative value to make the car brake. If the activate parameter is 0, this parameter is ignored
• bool isCrashed() Returns whether the vehicle has collided with another one. By using automated controller vehicles can crash in case of, for example, network failure. Plexe detects collisions and logs them, but it does not realistically simulate the collision. This method can thus be used to detect whether a collision has occurred and to stop the simulation.
• void setFixedLane(int laneIndex, bool safe) Moves the car to a specific lane whenever possible (i.e., avoiding collisions with other vehicles). The index is 0-based, with 0 being the rightmost lane. If safe is set to true, the vehicle will respect the safety distances, while if set to false, the vehicle will change lane without doing so, but always avoiding a crash with other vehicles. For example, if the vehicle wants to change lane but on its side there is another one, the lane change will take place only when the blocking vehicle moves away.
• void getRadarMeasurements(double &distance, double &relativeSpeed) Returns the distance (in meters) and the relative speed (in meters per second) to the vehicle in front. The distance and relative speed parameters are taken by reference. If no vehicle within 250 m is detected, the method returns -1 as distance and 0 as relative speed.
• void setLeaderVehicleFakeData(double controllerAcceleration, double acceleration, double speed) Set the data of the leader used by the FAKED_CACC. This method substitutes the the setControllerFakeData API, which is not available anymore. Parameters:
  • controllerAcceleration: control input (desired acceleration) in m/s/s
  • acceleration: acceleration in m/s/s
  • speed: speed in m/s
• void setFrontVehicleFakeData(double controllerAcceleration, double acceleration, double speed, double distance) Set the data of the front vehicle used by the FAKED_CACC. This method substitutes the the setControllerFakeData API, which is not available anymore. Parameters:
  • controllerAcceleration: control input (desired acceleration) in m/s/s
  • acceleration: acceleration in m/s/s
  • speed: speed in m/s
  • distance: distance to the front vehicle in m
• double getDistanceToRouteEnd() Gets the distance that a vehicle has to travel to reach the end of its route
• double getDistanceFromRouteBegin() Gets the distance that a vehicle has traveled since the beginning
• double getACCAcceleration() Gets acceleration that the ACC has computed while the vehicle is controlled by the faked CACC
• void setVehicleData(const struct Plexe::VEHICLE_DATA *data) Sets data information about a vehicle in the same platoon. This data is used by the CONSENSUS controller
• void getStoredVehicleData(struct Plexe::VEHICLE_DATA *data, int index) Gets data information about a vehicle in the same platoon, as stored using setVehicleData
• void useControllerAcceleration(bool use) Determines whether PATH’s and PLOEG’s CACCs should use the controller (control input) or the real acceleration when computing the control action
• void getEngineData(int &gear, double &rpm) If the vehicle is using the realistic engine model, this method returns the current gear and the engine RPM. If the realistic engine model is not used, then the gear is set to -1
• void enableAutoFeed(bool enable, std::string leaderId="", std::string frontId="") Activates or deactivates autofeeding, meaning that the user is not simulating inter-vehicle communication, so the CACCs will automatically take the required data from other vehicles automatically. This API only works for PATH, FAKED_CACC, Ploeg, and Flatbed CACCs. Parameters:
  • enable: enables/disables autofeeding
  • leaderId: SUMO vehicle id of the leader vehicle. This can be left empty when using Ploeg
  • frontId: SUMO vehicle id of the preceding vehicle
• void usePrediction(bool enable) Activates or deactivates prediction, i.e., interpolation of missing data for the control system. For example, when using PATH’s CACC, Plexe will predict the current speed of the leader and the front vehicle using the data included in the last received beacon
• void enableAutoLaneChanging(bool enable) EXPERIMENTAL. BUGS KNOWN. Enables/disables automatic, coordinated, whole-platoon lane changes. This function should be invoked on the leader which decides whether the platoon can gain speed by changing lane. The leader will then check whether lane changing is possible for all vehicles in the platoon and, in case, perform the operation
• void addPlatoonMember(std::string memberId, int position) This method should be invoked by the leader to add members to its platoon before enabling the automatic lane changing logic with enableAutoLaneChanging. Parameters:
  • memberId: SUMO vehicle id of the member
  • position: position within the platoon
• void removePlatoonMember(std::string memberId) This method should be invoked by the leader to remove members from its platoon. Parameters:
  • memberId: SUMO vehicle id of the member