3.10 VSimRTI application simulator
3.10.5 Development of application
Overview
Developing custom applications is rather easy in VSimRTI. If you learn quicker by just looking at source code yourself: The applications that come with VSimRTI have the Java Source-Files included in their respective Jar-File. Just open the Jar-File with an archiver of choice and look around.
To develop your own application you have to know three important concepts of the simulator. One: The interfaces which every application has to implement.
Two: The interfaces you can use to retrieve information, send messages and exert control over the vehicle.
And three: In case you want to change the content of automatically sent CAMs you need to know about that as well.
The Application interface
The Application Simulator is the framework for the application and is responsible for basic housekeeping duties, such as time management, starting and initializing the application. Every application needs to
implement the Application interface, providing methods for the simulator to call in case of certain
events. These methods have to be implemented, even when left empty.
+initialize(applicationLayer : ApplicationLayer) : v... +receiveMessage(msg : TypedV2XMessage) : void +dispose() : void
<<Interface>> Application
<<Property>> <+minimalTimerCallInterval : l... +timerCall(time : long) : void
<<Interface>> TimerCall Visual Paradigm for UML Standard Edition(Technische Universitaet Berlin)
3 Simulators 3.10 VSimRTI application simulator
The Application layer
Every application has access to its own application layer.
<<Property>> <+>communicationPoolActive : bool... <<Interface>>
PoolCommunicationModule
+initialize(applicationLayer : ApplicationLayer) : v... +receiveMessage(msg : TypedV2XMessage) : void +dispose() : void <<Interface>> Application <<Property>> <+applicationT... +f() : ApplicationToFacility <<Interface>> ApplicationToFacilityReferen
ce <<Property>> <+>userTaggedValue : byte[] <<Interface>>
UserTaggedValueStorage
<<Property>> <+>cellCommunicationModuleActive : bool... <<Interface>>
CellCommunicationModule
<<Interface>>
FacilityLayer
<<Property>> <+nodes : HashMap<String, Double> <<Property>> <+routes : HashMap<String, ArrayList<Strin...
<<Interface>>
VehicleRoutingInformation
<<Property>> <+>wLANCommunicationModuleActive : bool... <<Interface>> WLANCommunicationModule <<Interface>> CommunicationMod ule +triggerTimerCallUpdate() : void <<Interface>> TriggerTimerCallUpdate <<Interface>> ApplicationLaye r
<<Property>> +>configuration : CFacilityTimerInterce... <<Property>> <+enabled : boolean <<Property>> +>facilityLayer : FacilityLayer
<<Interface>>
FacilityTimerInterceptor
<<Property>> <+minimalTimerCallInterval : l... +timerCall(time : long) : void
<<Interface>> TimerCall <<Interface>> PoolAccess +sendPUM() : void +sendCAM() : void <<Interface>> MessageSender
<<Property>> <+communicationModuleReference : CommunicationMo... <<Interface>>
CommunicationModuleReference
+sendUdpMessageTopo(msg : TypedV2XMessage) : void +sendTCPMessageTopo(msg : TypedV2XMessage) : void
<<Interface>> ApplicationLayerSendMessage <<Property>> <+p... <<Interface>> PoolAccessReferen ce
<<Property>> <+unitType : UnitType <<Property>> <+logger : Logger
<<Interface>>
ApplicationToFacility
-useFirstTimerCall : boolean = true -lastTimerCall : long +SafeTimerLong(timerCall : TimerC... +checkTimer(time : long) : boolean +reset() : void SafeTimerLong +facilityLayer -timerCall +poolAccessReference +applicationToFacility +communicationModuleReference
Visual Paradigm for UML Standard Edition(Technische Universitaet Berlin)
Figure 3.14: Application layer class diagram
Provider and Controller interface
Notice: The documentation for the VSimRTI specific component is freely available on
the DCAITI website, explaining all available options.
Applications can be specific to one of three types of entities:RSUs, traffic lights and of course vehicles.
Provider interface
<<Property>> +ctrLanes : Collection<String> <<Property>> +trafficLightGroup : TrafficLightGr...
<<Interface>>
TrafficLightProvider
<<Property>> +vehicleProviderReference : VehicleProvider <<Interface>>
VehicleProviderReference
<<Property>> +basicProviderReference : BasicProvider <<Interface>>
BasicProviderReference
<<Property>> +rSUProviderReference : RSUProvider <<Interface>>
RSUProviderReference
<<Property>> +trafficLightProviderReference : TrafficLightProvider <<Interface>>
TrafficLightProviderReference
<<Interface>>
RSUProvider
<<Property>> +heading : double <<Property>> +vehicleTau : double <<Property>> +vehicleSigma : double <<Property>> +vehicleMaxSpeed : double <<Property>> +vehicleMaxAcceleration : double <<Property>> +vehicleMaxDeceleration : double <<Property>> +vehicleClass : VehicleClass <<Property>> +currentCurveRadius : double <<Property>> +vehicleLeftBlinkerOn : boolean <<Property>> +vehicleRightBlinkerOn : boolean <<Property>> +vehicleBrakeLightOn : boolean <<Property>> +vehicleFogLightOn : boolean <<Property>> +vehicleFrontLightOn : boolean <<Property>> +vehicleHighBeamLightOn : boolean <<Property>> +cO2Emissions : double <<Property>> +currentRoadLength : double <<Property>> +currentRoadMaxSpeed : double <<Property>> +road : String <<Property>> +speed : double <<Property>> +lane : int <<Property>> +route : List<String> <<Property>> +routeId : String <<Property>> +stopped : boolean <<Property>> +charging : boolean <<Property>> +stateOfCharge : float <<Property>> +batteryEmpty : boolean <<Property>> +batteryFull : boolean
<<Interface>> VehicleProvider <<Interface>> PoolProviderReference <<Interface>> PoolProvider
<<Property>> +currentTime : long <<Property>> +longLat : Double <<Property>> +directPosition : DirectPosition <<Property>> +longTimeStamp : long <<Property>> +unitType : UnitType <<Property>> +unitName : String <<Property>> +systemState : SystemState <<Property>> +attribute : SystemState +getStateOfEnvironmentSensor(type : SensorType)... <<Interface>> BasicProvider +trafficLightProviderReference +basicProviderReference +vehicleProviderReference +rSUProviderReference
Visual Paradigm for UML Standard Edition(Technische Universitaet Berlin)
Figure 3.15: Provider class diagram
Controller interface
<<Interface>>
BasicControlle r
<<Property>> +basicControlReference : BasicController <<Interface>> BasicControllerReference <<Interface>> PoolController <<Interface>> PoolControllerReference <<Interface>> RSUController
<<Property>> +rSUControlReference : RSUController <<Interface>>
RSUControllerReference
<<Property>> +phaseRemainingDuration ... <<Property>> +programById : String
<<Interface>>
TrafficLightController
<<Property>> +trafficLightControlReference : TrafficLightContr... <<Interface>>
TrafficLightControllerReference
+setMaximumSpeed(speed : float, data : BehaviorDataStruct) : void +slowDown(speed : float, interval : int, data : BehaviorDataStruct) : void +changeRoute(longLat : Double, travelTime : long, data : BehaviorDataStruct) : void +changeRoute(edgeIdList : List<String>, data : BehaviorDataStruct) : void +changeTarget(longLat : Double, data : BehaviorDataStruct) : void +changeLane(targetLaneIndex : int, duration : int, data : BehaviorDataStruct) : void +changeLane(changeLaneMode : ChangeLaneMode, duration : int, data : BehaviorDataStruct) : void +sendSumoTraciByteArrayMessage(msgId : String, msg : byte [], data : BehaviorDataStruct) : void +stop(edgeID : String, position : double, laneIndex : byte, duration : int, stopFlag : byte, data : BehaviorDataSt... +resume(data : BehaviorDataStruct) : void
+requestStartCharging(vehicleID : String, time : long, vehiclePosition : Double) : void +requestStopCharging(vehicleID : String, time : long, vehiclePosition : Double) : void
<<Interface>>
VehicleController
<<Property>> +vehicleControlReference : VehicleController <<Interface>>
VehicleControllerReference
<<Property>> +maximumSpeed : float +slowDown(speed : float, interval : int) : void +changeRoute(longLat : Double, travelTime : long) : void +changeRoute(edgeIdList : List<String>) : void +changeTarget(longLat : Double) : void +changeLane(targetLaneIndex : int, duration : int) : void +changeLane(changeLaneMode : ChangeLaneMode, duration : int) : void +sendSumoTraciByteArrayMessage(msgId : String, msg : byte []) : void +stop(edgeID : String, position : double, laneIndex : byte, duration : int, ... +resume() : void <<Interface>> VehicleControllerNoBehavior +rSUControlReference +basicControlReference +vehicleControlReference +trafficLightControlReference
Visual Paradigm for UML Standard Edition(Technische Universitaet Berlin)
Figure 3.16: Contro class diagram
CAM content
The following section will show how CAMs are implemented in VSimRTI and how you can alter them. CAMs consist of four parts:
• Header with generic information • MessageBody
3 Simulators 3.10 VSimRTI application simulator
First of all generic information like protocol version, creation time stamp are transmitted. Normally this data set follows a network beacon, already containing data like position and speed. Nevertheless this functionality must be implemented in the network layer, that means in the network simulator. At the moment this is not supported and is therefore compensated in the next message part, the message body.
The body can contain either RSU or Vehicle awareness data. In the first case, only the RSU type is submitted, but this probably changes with a new CAM specification. In the second case, we provide data like vehicle width, length, position, speed, type and heading. However, the specification is not completely implemented, especially acceleration data, as well as light and brake status are missing. The third part of the CAM specification, the service list, is also not implemented. This will probably change, when a list of services is defined by the ETSI.
Last but not least a message can contain optional data. This is fully implemented and is used for our traffic light CAM messages, which provide the traffic light status.
The CAM sending interval can be configured, more information can be found in the configuration section of the application simulator.
User defined tagged values
You can also send an arbitrary byte field. In this way every byte sent via CAM can be controlled, nevertheless this is often connected with some serious work.
You may also want to safely serialize / deserialize objects.
If the control of every byte is not needed, the DefaultObjectSerialization can be used. This class converts an object into a byte field and vice versa.
The main advantage of this approach is the easy way to handle the marshalling: it is all already done. So the developer can focus on the main facts.
After the user defined tagged value was added, it will be sent with the nextCAM. For more information
have a closer look at the example applications.
Create a "’Hello world"’ application using eclipse
Create a new project in eclipse (File↦New↦Java Project). Name your application HelloWorldApp
and select JavaSE-1.7 as theJREversion. Confirm the creation of the project. Right click on the project
and choose "’Properties"’ to open the project specific configuration options. In the dialog window select "’Java Build Path"’ and click on the Libraries tab. Choose "’Add external JARs"’ and navigate to your
VSimRTI installation folder. Choose the followingJARand add it to your project:
• vsimrti/bin/fed/application/application-federate-x.x.x-shaded.jar
Right click on the "’Hello world"’ Project and choose (New↦Package). Name the package something
likecom.mycompany.vsimrti.applications.HelloWorldApp. Right click on the package and chose
com.dcaiti.vsimrti.fed.app.api.interfaces.Application
and confirm.
Figure 3.17: HelloWorldApp
You can now continue and make modifications. To deploy the application you have to export the project
(File↦Export↦Java/Jar File) and put theJARin the folder
vsimrti/scenarios/<scenarioName>/application/applications/vehicle
.
Notice: You can download the example Application "’HelloWorldApp"’ from the web-
3 Simulators 3.10 VSimRTI application simulator
Applications that access SUMO TraCI
If SUMO is used as a traffic simulator and a special functionality is required, the
sendSumoTraciByteArrayMessage function in the VehicleControl can be used.
The function expects a string (a unique identifier which will be assigned to the response) and a byte array
(representing the complete Traffic Control Interface (TraCI) request including the header). The message
identifier can be an empty string, but must be not null.
In many cases the command will trigger a response. The application can receive it if
it implements the SumoTraciByteArrayMessageApplication interface. The function
receiveSumoTraciByteArrayMessageResponse() must be implemented. This function will
receive a SumoTraciByteArrayMessageResponse object. This response contains the specified
identifier. The application must handle the identification process of the response itself.
Notice: A response is only delivered to the vehicle which issued the request, but to every
application which implements the SumoTraciByteArrayMessageResponse interface. To
prevent unintentional delivery each application should use an immutable universally unique identifier (UUID).
Important: Be careful when using this interface and theTraCIcommands. The
commands are delivered toTraCIwithout any prior checks.
An example use case: Get the speed from a specific vehicle
This is a short introduction to the deployed application TestSumoTraciByteArrayMessageApp. You should have a look at the source files for a better understanding.