Veins

The Platooning Extension for Veins.

Plexe APIs

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

Veins::TraCIMobility *mobility;
Veins::TraCICommandInterface::Vehicle *traciVehicle;
and set their values in the following way within the initialize method of your module
mobility = Veins::TraCIMobilityAccess().get(getParentModule());
traciVehicle = mobility->getVehicleCommandInterface();
Among other TraCI methods, in traciVehicle you find the following Plexe methods:
  • unsigned int getLanesCount(): Returns the number of lanes of the edge the vehicle is currently traveling on.
  • void setPlatoonLeaderData(double leaderSpeed, double leaderAcceleration, double positionX, double positionY, double time): Pass leader information to SUMO to be used by the CACC. Only the California PATH CACC currently uses this information. Parameters:
    • leaderSpeed: leader speed in m/s
    • leaderAcceleration: leader acceleration in m/s/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 setPrecedingVehicleData(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 and the Ploeg's CACC. The definition of the parameters is the same as for setPlatoonLeaderData.
  • void getVehicleData(double &speed, double &acceleration, double &controllerAcceleration, double &positionX, double &positionY, double &time): Returns information about the own vehicle. Parameters are all taken by reference to be filled with the required information:
    • speed: speed in m/s
    • acceleration: actual acceleration in m/s/s
    • controllerAcceleration: acceleration computed by the controller (control input) in m/s/s
    • positionX: x position in m (SUMO coordinates)
    • positionY: y position in m (SUMO coordinates)
    • time: time at which the data has been measured in s
  • void setGenericInformation(int type, const void* data, int length): This method the main access points to the SUMO model via the TraCI interface. In principle, to send or to retrieve data from the model via TraCI, there was the need to change several SUMO and Veins core files, including TraCIConstants.h (on both Veins and SUMO), TraCIServerAPI_Vehicle.cpp (on SUMO), and TraCIScenarioManager.{h,cc} and TraCIMobility.h (on Veins). In TraCIConstants.h you needed to define a new constant which identified your new TraCI command, while the other files needed to be modified to handle it. The result was an amount of constants growing indefinitely. Moreover, it is not desirable to change core files when unneeded. For such reasons, we define this message passing mechanism which is able to deal with generic data structures using pointers. The constants are defined within CC_Const.h (on both SUMO and Veins). When adding new setters, it is sufficient to add a new constant in CC_Const.h and handle it in the SUMO module (see later). The parameters are the following:
    • type: a unique identifier for the set operation
    • data: pointer to the data to be passed, either a single variable or a data structure
    • length: size of the passed data in bytes
    We already define some set operations in CC_Const.h which are:
    • CC_SET_VEHICLE_DATA (data type struct VEHICLE_DATA *, length sizeof(struct VEHICLE_DATA)): sets information about a vehicle like setPlatoonLeaderData and setPrecedingVehicleData, but about any vehicle in the platoon. This is useful for the CONSENSUS CACC controller, which uses information about possibly any vehicle in the platoon. The VEHICLE_DATA structure is defined in CC_Const.h
    • CC_SET_VEHICLE_POSITION (data type int *, length sizeof(int)): sets the position of the vehicle in the platoon (0 based)
    • CC_SET_PLATOON_SIZE (data type int *, length sizeof(int)): sets the number of vehicles in the platoon of this vehicle
    • CC_SET_CACC_XI (data type double *, length sizeof(double)): sets the Xi parameter of the PATH CACC
    • CC_SET_CACC_OMEGA_N (data type double *, length sizeof(double)): sets the Omega_n parameter of the PATH CACC
    • CC_SET_CACC_C1 (data type double *, length sizeof(double)): sets the C1 parameter of the PATH CACC
    • CC_SET_ENGINE_TAU (data type double *, length sizeof(double)): sets the engine time constant in seconds when using a first order lag engine model
    • CC_SET_PLOEG_H (data type double *, length sizeof(double)): sets the headway time in seconds for the Ploeg CACC
    • CC_SET_PLOEG_KP (data type double *, length sizeof(double)): sets the kp parameter for the Ploeg CACC
    • CC_SET_PLOEG_KD (data type double *, length sizeof(double)): sets the kd parameter for the Ploeg CACC
    • CC_SET_VEHICLE_ENGINE_MODEL (data type int *, length sizeof(int)): 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_SET_VEHICLES_FILE (data type const char *, length strlen(string) + 1): sets the XML files to be used by the realistic engine model for loading engine parameters of different vehicles.
    • CC_SET_VEHICLE_MODEL (data type const char *, length strlen(string) + 1): 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 getGenericInformation(int type, const void* params, int paramsLength, void *result): this is the getter counterpart of setGenericInformation, used to retrieve information from a vehicle. The parameters are:
    • type: a unique identifier for the get operation
    • params: pointer to potential params needed by the get operation. If none, set to 0
    • paramsLength: size of the passed parameters in bytes. If none, set to 0
    • result: generic pointer to the memory location where the result should be stored. The size of the allocated memory depends on the specific get operation
    So far, the only available get operation in CC_Const.h is:
    • CC_GET_VEHICLE_DATA (params type int *, paramsLength sizeof(int), return type struct VEHICLE_DATA): returns the information the own vehicle stored about another one. The parameter to be passed to the get operation is an integer indicating the index of the vehicle (0 based)
  • 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 setControllerFakeData method. 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.
  • 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.
  • bool isCruiseControllerInstalled(): returns whether the vehicle is ACC/CACC capable or not.
  • void setLaneChangeAction(enum PLATOONING_LANE_CHANGE_ACTION action): sets a lane change strategy. This method can be used to force a vehicle to stay in its current lane or to given lane change control back to the human-behavioral model. Possible action values are:
    • Plexe::DRIVER_CHOICE: let the human-behavioral model decide how to change lane. This is actually the only action you might need, as it can be used when a car leaves a platoon and you want to given control back to the driver
    • Plexe::STAY_IN_CURRENT_LANE: the vehicle should stay in the lane it is currently travelling
    • Plexe::MOVE_TO_FIXED_LANE: tell the model to move the vehicle to a particular lane. You should never need this, as you can use the setFixedLane method
  • enum PLATOONING_LANE_CHANGE_ACTION getLaneChangeAction(): returns the lane change action currently used by the model
  • void setFixedLane(int laneIndex): 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.
  • 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 setControllerFakeData(double frontDistance, double frontSpeed, double frontAcceleration, double leaderSpeed, double leaderAcceleration): set the data used by the FAKED_CACC. This method sets the data about the front vehicle (distance to the front vehicle in meters, speed of the front vehicle in m/s, and acceleration of the front vehicle in m/s/s) and about the leading vehicle (speed and acceleration in m/s and m/s/s, respectively). The method can be used to set the data of both vehicles at the same time, or only about one of the two. By setting a negative speed for one of the two vehicle, its data will be ignored. Parameters:
    • frontDistance: distance to the front vehicle in meters. Ignored if frontSpeed is negative
    • frontSpeed: speed of the front vehicle in m/s. Set to a negative value if front vehicle data should not be set
    • frontAcceleration: acceleration of the front vehicle in m/s/s. Ignored if frontSpeed is negative
    • leaderSpeed: speed of the leading vehicle in m/s. Set to a negative value if leading vehicle data should not be set
    • leaderAcceleration: acceleration of the leading vehicle in m/s/s. Ignored if leaderSpeed is negative
  • double getDistanceToRouteEnd(): returns the distance to the route end for the vehicle in meters
  • double getDistanceFromRouteBegin(): returns the distance from the beginning of the route of the vehicle in meters
  • double getACCAcceleration(): returns the acceleration computed by the ACC when using the FAKED_CACC. This is useful to check whether the vehicle is getting closer to a slower vehicle in front when using the FAKED_CACC and avoid a collision.