# Plexe

The Platooning Extension for Veins.

# Plexe Documentation

## Latest release: 2.1

### Plexe-Veins files

The main Plexe sources on the Veins side are located into plexe-veins/src/veins/modules/application/platooning. Inside that folder you find the following files:

#### Main folder

• CC_Const.h: This file defines constant values that are shared between Plexe-Veins and Plexe-SUMO, permitting their communication. For example, the file includes the enum ACTIVE_CONTROLLER, which defines the set of available automated controllers. In your code, you can use one of those values to decide the active automated controller, and this value will be passed to SUMO via the TraCI interface.
• UnicastProtocol.*: Older Veins implementations of the IEEE 802.11p MAC layer transmit broadcast frames only, so we deveoped a higher-level unicast protocol. The protocol implements timeouts and retries, and can be used to send broadcast frames as well by specifiying the destination address -1. In Plexe, the protocol sits on top of the 802.11p NIC. This protocol might be removed in future releases, as Veins now supports standard 802.11 unicast frames as well.

#### apps/ folder

• apps/BaseApp.*: The aim of the application is mainly to pass wirelessly received data to the automated controllers (the application, in our case). In addition, the application takes care of logging mobility information such as speed, acceleration, distance, etc. The idea is to have a base application that provides basic functionalities. More sophisticated applications can inherit from this base application.
• apps/SimplePlatooningApp.*: This application extends the base application. In the provided examples there is no additional application duty to implement, so this class is basically empty, but it is provided as an example extension to the base class.
• apps/GeneralPlatooningApp.*: This application is meant to be a generic class that can possibly manage platooning in all its aspects, e.g., by managing all maneuvers. Currently, it simply manages a simple join maneuver and messages updating the platoon formation.

#### protocols/ folder

• protocols/BaseProtocol.*: The same concept applies to protocols. We implement a base protocol that takes care of loading parameters from configuration file, recording network statistics, and providing primitives for sending frames. This class defines a virtual messageReceived() method that inheriting classes can override to get notified about incoming data frames. In addition, BaseProtocol performs application multiplexing. Applications can register to BaseProtocol to obtain copies of received frames of a particular type.
• protocols/SimplePlatooningBeaconing.*: This class extends the base protocol and implements a classic periodic beaconing protocol sending a beacon every x milliseconds.
• protocols/SlottedBeaconing.*: This class extends the base protocol and implements a TDMA-like beaconing protocol. The platoon leader periodically sends beacons every x milliseconds, while the platoon members send their beacons one after the other, following their position.
• protocols/HumanInterferingProtocol.*: This class sends periodic beacons as the SimplePlatooningBeaconing class and it is used by human-driven vehicles in the fifth tutorial to generate interfering network traffic.

#### messages/ folder

• messages/PlatooningBeacon.msg: This OMNeT message defines the content of a period platooning beacon. It includes information such as source vehicle, current acceleration, speed, position, etc.
• messages/UnicastMessage.msg: This OMNeT message defines the messages handled by the unicast protocol. Basically, every packet that has to be sent through the radio (for example, a PlatooningBeacon) must be encapsulated inside a UnicastMessage.
• messages/UnicastProtocolControlMessage.msg: This OMNeT message defines a control message that can be sent to UnicastProtocol for configuration. One sample usage is setting the MAC address.
• messages/InterferingBeacon.msg: This OMNeT message is sent by human-driven vehicles in the fifth tutorial to generate network interference.
• messages/ManeuverMessage.msg: This message is a base class for a set of messages used in maneuvers that can be found in the same folder. Maneuver messages are used in the third tutorial.

#### scenarios/ folder

• scenarios/BaseScenario.*: Plexe 2.0 introduced scenarios, which define how vehicles behave in a particular simulation. In the first Plexe version, this was included within applications (apps/*), possibly leading to confusion. The base scenario configures controller parameters, while inheriting classes actually define the behavior.
• scenarios/BBaseScenario.ned: In release 2.0, each module extending BaseScenario had to define default values for the OMNeT parameters. The introduction of a new parameter required the user to change every ned file. Default parameters are now defined in BBaseScenario.ned, and scenario implementations extend this module.
• scenarios/SinusoidalScenario.*: This class defines a sinusoidal behavior. Each platoon leader will change its speed in a sinusoidal fashion, continuously accelerating and decelerating, with a certain frequency and amplitude that can be chosen through configuration parameters.
• scenarios/BrakingScenario.*: This class implements an emergency braking. The leader will drive at a constant speed and the brake down to a complete stop. The deceleration can be chosen through configuration parameters.
• scenarios/AccelerateAndBrakeScenario.*: With this class, the leading vehicle will accelerate as much as possible for a certain amount of time and then slow down to a complete stop. This scenario is very useful to test engine and brake models.
• scenarios/JoinManeuverScenario.*: the scenario used in the join maneuver tutorial.

#### traffic/ folder

• traffic/PlatoonsTrafficManager.*: This class injects platoons in the simulation. By using the new vehicle injection feature, vehicles can be inserted directly from the Veins side, instead of using SUMO flows. This permits, for example, to inject platoons already at steady state with very small inter-vehicle distances. The PlatoonsTrafficManager class extends the TraCIBaseTrafficManager class located in src/veins/modules/mobility/traci/. The base class provides vehicle injection methods, and all inheriting classes can use such methods. The PlatoonsTrafficManager class has three configuration parameters which are nCars, platoonSize, and nLanes. The parameters represent the total number of vehicles to inject, the number of vehicles per platoon, and the number of lanes to use, respectively. The injected platoons have all the same size: to have platoons of different sizes you need to modify the class or to implement your own, as well as performing some changes in the utilities/ folder (see later). nCars must be a multiple of platoonSize * nLanes. For example, by setting nCars = 12, platoonSize = 3, nLanes = 2, vehicles will be injected in the following way:

Manual vehicle injection is not mandatory, and can still be performed using SUMO flows. To do so, it is sufficient to choose the SumoTrafficManager class in the configuration file. The SumoTrafficManager is an empty extension of TraCIBaseTrafficManager, thus injecting no vehicles.

• traffic/PlatoonsPlusHumanTraffic.*: This class is used in the fifth tutorial for injecting platooning and human-driven vehicles. It is a modified version of the PlatoonsTrafficManager class.
• traffic/RingTrafficManager.*: Traffic manager that injects vehicles in the ring example. Be aware that the ring example (and all related code samples and features) are experimental.

#### utilities/ folder

• BasePositionHelper.*: Plexe 2.0 introduces position helpers. Most classes need to know in which platoon a car is traveling, which vehicles is the leader, which vehicle is in front, etc. For this reason it is very useful to have a class that provides and enable changing this information. One example is the application, which needs to send received data to the CACC. When getting a beacon, the application might need to know if it comes from the vehicle in front and, in case, forward the data to the CACC. Another application might dynamically create platoons, so it can change the information about the platoon composition at run time. The BasePositionHelper class defines function prototypes that needs to be implemented by inheriting classes. Example methods are getId(), getPosition(), getLeaderId(), isLeader(), etc.
• PositionHelper.*: The PositionHelper class provides information about platoon composition for the PlatoonsTrafficManager class. By taking again the following sample configuration

if vehicle 11 calls the getLeaderId() method, 7 will be returned. getFrontId() returns 9, getPosition() returns 2 (the leader is in position 0). This class implementation is specific to the way the PlatoonsTrafficManager class injects vehicles into the simulation. If you change PlatoonsTrafficManager, you will also need to change the PositionHelper.

• utilities/DynamicPositionManager.*: this class is used in the ring example, where platoons of different sizes are present. The RingTrafficManager inject platoons in the scenario and informs this class, which stores the information about platoons in the simulation.
• utilities/DynamicPositionHelper.*: this position helper is used in the ring example and communicates with the DynamicPositionManager to retrieve information about a vehicle.
• utilities/LocalPlatoonPositionHelper.*: a position helper that is local to each vehicle, i.e., it only has knownledge about the platoon the vehicle is currently in. The information stored in this position helper can be modified at runtime.

### Plexe-SUMO files

Besides the Plexe-Veins side, Plexe also changes SUMO to implement platooning controllers and engine models. All but one Plexe source files are located into the folder sumo/src/microsim/cfmodels, starting from the main repository root folder. The only file located elsewhere is one folder up.

• CC_Const.h: see the description for this file above, as this is a copy of the file located in the Plexe-Veins source release.
• MSCFModel_CC.*: this is the core of Plexe models within SUMO. It implements all the automated controllers, it reproduces the behavior of a real vehicle by invoking the engine models, and it is the point where all the data from and to Veins pass through. If you want to implement a new CACC, or to exchange additional information through the TraCI interface, this is where to work on.
• CC_VehicleVariables.*: this class maintains the state of a vehicle, including current speed, acceleration, controllers’ parameters, etc.
• GenericEngineModel.*: this class is a generic engine model, a base class which all engine models should inherit from. It defines some basic functions to parse parameters passed to a model, and a pure virtual method getRealAcceleration() which, given the current vehicle state, computes what the vehicle would really do when required to apply a certain acceleration.
• FirstOrderLagModel.*: this class extends the GenericEngineModel class and implements a first order lag model.
• RealisticEngineModel.*: this class extends the GenericEngineModel class and implements a realistic engine model which takes into account torque characteristics, mass, aerodynamic characteristics, gear ratios, etc.
• EngineParameters.*: this is a helper class which computes engine parameters used by the realistic engine model from the parameters set by the user. For example it multiply/divides all the constant values when instantiated to reduce the computational power at run time.
• VehicleEngineHandler.*: this is an XML handler class (SAX handler) used to parse engine parameters from the XML configuration file.

### API

Please refer to the specific API section. The source code documentation for the examples is under production. It’s much more work (for me at least) producing the documentation than the actual simulator. Still, the documentation is fundamental to understand the simulator, including its structure and its code, as well as modifying it to suite your purposes. Please wait some more days for it. In the meanwhile, the original Plexe paper, my PhD Thesis, and the tutorials 1, 2, 3, and 4 should give you a good starting point. In addition, you can refer to the API section. Of course you can refer to the old Plexe documentation, but be careful that several things changed (compiling, paths, running the simulation, and plotting the results), so you might get lost at some point.

## Release 2.0

### Plexe-Veins files

The main Plexe sources on the Veins side are located into plexe-veins/src/veins/modules/application/platooning. Inside that folder you find the following files:

#### Main folder

• CC_Const.h: This file defines constant values that are shared between Plexe-Veins and Plexe-SUMO, permitting their communication. For example, the file includes the enum ACTIVE_CONTROLLER, which defines the set of available automated controllers. In your code, you can use one of those values to decide the active automated controller, and this value will be passed to SUMO via the TraCI interface.
• UnicastProtocol.*: As the current Veins implementation of the IEEE 802.11p MAC layer transmits broadcast frames only, we deveoped a higher-level unicast protocol. The protocol implements timeouts and retries, and can be used to send broadcast frames as well by specifiying the destination address -1. In Plexe, the protocol sits on top of the 802.11p NIC.

#### apps/ folder

• apps/BaseApp.*: The aim of the application is mainly to pass wirelessly received data to the automated controllers (the application, in our case). In addition, the application takes care of logging mobility information such as speed, acceleration, distance, etc. The idea is to have a base application that provides basic functionalities. More sophisticated applications can inherit from this base application.
• apps/SimplePlatooningApp.*: This application extends the base application. In the provided examples there is no additional application duty to implement, so this class is basically empty, but it is provided as an example extension to the base class.

#### protocols/ folder

• protocols/BaseProtocol.*: The same concept applies to protocols. We implement a base protocol that takes care of loading parameters from configuration file, recording network statistics, and providing primitives for sending frames. This class defines a virtual messageReceived() method that inheriting classes can override to get notified about incoming data frames. In addition, BaseProtocol performs application multiplexing. Applications can register to BaseProtocol to obtain copies of received frames of a particular type.
• protocols/SimplePlatooningBeaconing.*: This class extends the base protocol and implements a classic periodic beaconing protocol sending a beacon every x milliseconds.
• protocols/SlottedBeaconing.*: This class extends the base protocol and implements a TDMA-like beaconing protocol. The platoon leader periodically sends beacons every x milliseconds, while the platoon members send their beacons one after the other, following their position.
• protocols/HumanInterferingProtocol.*: This class sends periodic beacons as the SimplePlatooningBeaconing class and it is used by human-driven vehicles in the fifth tutorial to generate interfering network traffic.

#### messages/ folder

• messages/PlatooningBeacon.msg: This OMNeT message defines the content of a period platooning beacon. It includes information such as source vehicle, current acceleration, speed, position, etc.
• messages/UnicastMessage.msg: This OMNeT message defines the messages handled by the unicast protocol. Basically, every packet that has to be sent through the radio (for example, a PlatooningBeacon) must be encapsulated inside a UnicastMessage.
• messages/UnicastProtocolControlMessage.msg: This OMNeT message defines a control message that can be sent to UnicastProtocol for configuration. One sample usage is setting the MAC address.
• messages/InterferingBeacon.msg: This OMNeT message is sent by human-driven vehicles in the fifth tutorial to generate network interference.

#### scenarios/ folder

• scenarios/BaseScenario.*: Plexe 2.0 introduces scenarios, which define how vehicles behave in a particular simulation. In the first Plexe version, this was included within applications (apps/*), possibly leading to confusion. The base scenario configures controller parameters, while inheriting classes actually define the behavior.
• scenarios/SinusoidalScenario.*: This class defines a sinusoidal behavior. Each platoon leader will change its speed in a sinusoidal fashion, continuously accelerating and decelerating, with a certain frequency and amplitude that can be chosen through configuration parameters.
• scenarios/BrakingScenario.*: This class implements an emergency braking. The leader will drive at a constant speed and the brake down to a complete stop. The deceleration can be chosen through configuration parameters.
• scenarios/AccelerateAndBrakeScenario.*: With this class, the leading vehicle will accelerate as much as possible for a certain amount of time and then slow down to a complete stop. This scenario is very useful to test engine and brake models.

#### traffic/ folder

• traffic/PlatoonsTrafficManager.*: This class injects platoons in the simulation. By using the new vehicle injection feature, vehicles can be inserted directly from the Veins side, instead of using SUMO flows. This permits, for example, to inject platoons already at steady state with very small inter-vehicle distances. The PlatoonsTrafficManager class extends the TraCIBaseTrafficManager class located in src/veins/modules/mobility/traci/. The base class provides vehicle injection methods, and all inheriting classes can use such methods. The PlatoonsTrafficManager class has three configuration parameters which are nCars, platoonSize, and nLanes. The parameters represent the total number of vehicles to inject, the number of vehicles per platoon, and the number of lanes to use, respectively. The injected platoons have all the same size: to have platoons of different sizes you need to modify the class or to implement your own, as well as performing some changes in the utilities/ folder (see later). nCars must be a multiple of platoonSize * nLanes. For example, by setting nCars = 12, platoonSize = 3, nLanes = 2, vehicles will be injected in the following way:

Manual vehicle injection is not mandatory, and can still be performed using SUMO flows. To do so, it is sufficient to choose the SumoTrafficManager class in the configuration file. The SumoTrafficManager is an empty extension of TraCIBaseTrafficManager, thus injecting no vehicles.

• traffic/PlatoonsPlusHumanTraffic.*: This class is used in the fifth tutorial for injecting platooning and human-driven vehicles. It is a modified version of the PlatoonsTrafficManager class.

#### utilities/ folder

• BasePositionHelper.*: Plexe 2.0 introduces position helpers. Most classes need to know in which platoon a car is traveling, which vehicles is the leader, which vehicle is in front, etc. For this reason it is very useful to have a class that provides and enable changing this information. One example is the application, which needs to send received data to the CACC. When getting a beacon, the application might need to know if it comes from the vehicle in front and, in case, forward the data to the CACC. Another application might dynamically create platoons, so it can change the information about the platoon composition at run time. The BasePositionHelper class defines function prototypes that needs to be implemented by inheriting classes. Example methods are getId(), getPosition(), getLeaderId(), isLeader(), etc.
• PositionHelper.*: The PositionHelper class provides information about platoon composition for the PlatoonsTrafficManager class. By taking again the following sample configuration

if vehicle 11 calls the getLeaderId() method, 7 will be returned. getFrontId() returns 9, getPosition() returns 2 (the leader is in position 0). This class implementation is specific to the way the PlatoonsTrafficManager class injects vehicles into the simulation. If you change PlatoonsTrafficManager, you will also need to change the PositionHelper.

### Plexe-SUMO files

Besides the Plexe-Veins side, Plexe also changes SUMO to implement platooning controllers and engine models. All but one Plexe source files are located into the folder sumo/src/microsim/cfmodels, starting from the main repository root folder. The only file located elsewhere is one folder up.

• MSCACCLaneChanger.*: this is the only file located into the sumo/src/microsim folder and provides a version of the SUMO lane changer that is used to make an automated vehicle drive on a particular lane.
• CC_Const.h: see the description for this file above, as this is a copy of the file located in the Plexe-Veins source release.
• MSCFModel_CC.*: this is the core of Plexe models within SUMO. It implements all the automated controllers, it reproduces the behavior of a real vehicle by invoking the engine models, and it is the point where all the data from and to Veins pass through. If you want to implement a new CACC, or to exchange additional information through the TraCI interface, this is where to work on.
• CC_VehicleVariables.*: this class maintains the state of a vehicle, including current speed, acceleration, controllers’ parameters, etc.
• GenericEngineModel.*: this class is a generic engine model, a base class which all engine models should inherit from. It defines some basic functions to parse parameters passed to a model, and a pure virtual method getRealAcceleration() which, given the current vehicle state, computes what the vehicle would really do when required to apply a certain acceleration.
• FirstOrderLagModel.*: this class extends the GenericEngineModel class and implements a first order lag model.
• RealisticEngineModel.*: this class extends the GenericEngineModel class and implements a realistic engine model which takes into account torque characteristics, mass, aerodynamic characteristics, gear ratios, etc.
• EngineParameters.*: this is a helper class which computes engine parameters used by the realistic engine model from the parameters set by the user. For example it multiply/divides all the constant values when instantiated to reduce the computational power at run time.
• VehicleEngineHandler.*: this is an XML handler class (SAX handler) used to parse engine parameters from the XML configuration file.

Plexe also makes changes to some SUMO core files. For example, it extends the TraCI interface to enable communication with the MSCFModel_CC class. Such changes, however, are not of interest for the standard Plexe user, and they are omitted here. The interested user can use git to explore all the changes made from the original SUMO to the Plexe-SUMO version.

### API

Please refer to the specific API section. The source code documentation for the examples is under production. It’s much more work (for me at least) producing the documentation than the actual simulator. Still, the documentation is fundamental to understand the simulator, including its structure and its code, as well as modifying it to suite your purposes. Please wait some more days for it. In the meanwhile, the original Plexe paper, my PhD Thesis, and the tutorials 1, 2, 3, and 4 should give you a good starting point. In addition, you can refer to the API section. Of course you can refer to the old Plexe documentation, but be careful that several things changed (compiling, paths, running the simulation, and plotting the results), so you might get lost at some point.

## Release 1.1

Plexe 1.1 documentation