blob: 013a1f960d45b2a386b8f212ea6fece2d4f30dac [file] [log] [blame]
<!DOCTYPE html><html lang="en-us" >
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="generator" content="Source Themes Academic 4.8.0">
<meta name="author" content="Fraunhofer FOKUS">
<meta name="description" content="The Simulation of Urban Mobility (SUMO) simulator is an open source microscopic, multi-modal traf- fic simulation package which is developed by the Institute of Transportation research at the German Aerospace Centre.">
<link rel="alternate" hreflang="en-us" href="https://www.eclipse.org/mosaic/docs/extending_mosaic/sumo_ambassador_details/">
<meta name="theme-color" content="#68145C">
<script src="/mosaic/js/mathjax-config.js"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/academicons/1.8.6/css/academicons.min.css" integrity="sha512-MCWBwPSput2UWNwyznVFLbD2iUc1e5VsdD1zahsWVzkDSUzyHhMZ4kCS3wgYSRm0mU+glwD/Q9lSJrDPwbUL2A==" crossorigin="anonymous">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.0-1/css/all.min.css" integrity="sha512-ZYg+hQvLlM0W9C3P6vTpes5LmJ66G2EsroxDNzwD6qiulckldb29eD9I672HL2X+LH5nRhY1sQqZLJGB+aUUPg==" crossorigin="anonymous">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/fancybox/3.5.7/jquery.fancybox.min.css" integrity="sha512-H9jrZiiopUdsLpg94A333EfumgUBpO9MdbxStdeITo+KEIMaNfHNvwyjjDJb+ERPaRS6DpyRlKbvPUasNItRyw==" crossorigin="anonymous">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/styles/atom-one-light.min.css" crossorigin="anonymous" title="hl-light">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/styles/atom-one-light.min.css" crossorigin="anonymous" title="hl-dark" disabled>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.5.1/leaflet.css" integrity="sha512-xwE/Az9zrjBIphAcBb3F6JVqxf46+CDLwfLMHloNu6KEQCAWi6HcDUbeOfBIptF7tcCzusKFjFw2yuvEpDL9wQ==" crossorigin="anonymous">
<script src="https://cdnjs.cloudflare.com/ajax/libs/lazysizes/5.2.2/lazysizes.min.js" integrity="sha512-TmDwFLhg3UA4ZG0Eb4MIyT1O1Mb+Oww5kFG0uHqXsdbyZz9DcvYQhKpGgNkamAI6h2lGGZq2X8ftOJvF/XjTUg==" crossorigin="anonymous" async></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.1.0/es5/tex-chtml.min.js" integrity="sha512-uwL1UtpYdWra2iqJlAW8Ts0s9Os6IxWLDJDF/BnWdhDmT7DEMFba3GPsFwmV3QiTNcUyl2GB5vsgycB/MOvo9g==" crossorigin="anonymous" async></script>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,400i,700,700i%7CRoboto+Mono&display=swap">
<link rel="stylesheet" href="/mosaic/css/academic.css">
<link rel="manifest" href="/mosaic/index.webmanifest">
<link rel="icon" type="image/png" href="/mosaic/images/icon_hu6bdfb97c7e23190c70e41ca0e15a9fce_30436_32x32_fill_lanczos_center_2.png">
<link rel="apple-touch-icon" type="image/png" href="/mosaic/images/icon_hu6bdfb97c7e23190c70e41ca0e15a9fce_30436_192x192_fill_lanczos_center_2.png">
<link rel="canonical" href="https://www.eclipse.org/mosaic/docs/extending_mosaic/sumo_ambassador_details/">
<meta property="twitter:card" content="summary">
<meta property="og:site_name" content="Eclipse MOSAIC – A Multi-Domain and Multi-Scale Simulation Framework for Connected and Automated Mobility">
<meta property="og:url" content="https://www.eclipse.org/mosaic/docs/extending_mosaic/sumo_ambassador_details/">
<meta property="og:title" content="Sumo Ambassador Implementation | Eclipse MOSAIC – A Multi-Domain and Multi-Scale Simulation Framework for Connected and Automated Mobility">
<meta property="og:description" content="The Simulation of Urban Mobility (SUMO) simulator is an open source microscopic, multi-modal traf- fic simulation package which is developed by the Institute of Transportation research at the German Aerospace Centre."><meta property="og:image" content="https://www.eclipse.org/mosaic/images/logo.svg">
<meta property="twitter:image" content="https://www.eclipse.org/mosaic/images/logo.svg"><meta property="og:locale" content="en-us">
<meta property="article:published_time" content="2019-05-05T00:00:00&#43;01:00">
<meta property="article:modified_time" content="2019-05-05T00:00:00&#43;01:00">
<title>Sumo Ambassador Implementation | Eclipse MOSAIC – A Multi-Domain and Multi-Scale Simulation Framework for Connected and Automated Mobility</title>
</head>
<body id="top" data-spy="scroll" data-offset="70" data-target="#TableOfContents" class=" page-mosaic page-docs page-extending_mosaic page-sumo_ambassador_details ">
<aside class="search-results" id="search">
<div class="container">
<section class="search-header">
<div class="row no-gutters justify-content-between mb-3">
<div class="col-10 col-md-3">
<div class="logo" style="background-image: url(/mosaic/img/logos/mosaic/EclipseMOSAIC-Logo-RGB-positiv.svg)"></div>
</div>
<div class="col-2 col-md-4 col-search-close">
<a class="js-search" href="#"><i class="fas fa-times-circle text-muted" aria-hidden="true"></i></a>
</div>
</div>
<div id="search-box">
<input name="q" id="search-query" placeholder="Search..." autocapitalize="off"
autocomplete="off" autocorrect="off" spellcheck="false" type="search">
</div>
</section>
<section class="section-search-results">
<div id="search-hits">
</div>
</section>
</div>
</aside>
<nav class="navbar navbar-expand-lg navbar-light compensate-for-scrollbar" id="navbar-main">
<div class="container">
<div class="d-none d-lg-inline-flex">
<a style="visibility:visible;" class="navbar-brand" href="/mosaic/"><img src="/mosaic/images/logo.svg" alt="Eclipse MOSAIC – A Multi-Domain and Multi-Scale Simulation Framework for Connected and Automated Mobility"></a>
</div>
<button type="button" class="navbar-toggler" data-toggle="collapse"
data-target="#navbar-content" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
<span><i class="fas fa-bars"></i></span>
</button>
<div class="navbar-brand-mobile-wrapper d-inline-flex d-lg-none">
<a class="navbar-brand" href="/mosaic/"><img src="/mosaic/images/logo.svg" alt="Eclipse MOSAIC – A Multi-Domain and Multi-Scale Simulation Framework for Connected and Automated Mobility"></a>
</div>
<div class="navbar-collapse main-menu-item collapse justify-content-start" id="navbar-content">
<ul class="navbar-nav d-md-inline-flex">
<li class="nav-item">
<a class="nav-link " href="/mosaic/about"><span>About</span></a>
</li>
<li class="nav-item">
<a class="nav-link " href="/mosaic/news"><span>News</span></a>
</li>
<li class="nav-item">
<a class="nav-link active" href="/mosaic/docs"><span>Documentation</span></a>
</li>
<li class="nav-item">
<a class="nav-link " href="/mosaic/tutorials"><span>Tutorials</span></a>
</li>
<li class="nav-item">
<a class="nav-link " href="/mosaic/download"><span>Download</span></a>
</li>
<li class="nav-item">
<a class="nav-link " href="/mosaic/community"><span>Community</span></a>
</li>
</ul>
</div>
<ul class="nav-icons navbar-nav flex-row ml-auto d-flex pl-md-2">
<li class="nav-item">
<a class="nav-link js-search" href="#" aria-label="Search"><i class="fas fa-search" aria-hidden="true"></i></a>
</li>
<li class="nav-item ">
<a href="https://github.com/eclipse/mosaic" target="blank">
<i class="fab fa-github" aria-hidden="true"></i>
</a>
</li>
</ul>
</div>
</nav>
<div class="docs container">
<div class="row flex-xl-nowrap">
<div class="docs-sidebar col-12 col-md-3 col-xl-3">
<div class="docs-version">
<a class="" data-bs-toggle="tooltip" data-bs-placement="bottom" title="The documentation corresponds to the latest version of Eclipse MOSAIC 20.1-SNAPSHOT." href="https://github.com/eclipse/mosaic">
<i class="fab fa-github"></i>&nbsp;Eclipse MOSAIC 20.1-SNAPSHOT
</a>
</div>
<form class="docs-search d-flex align-items-center">
<button class="btn docs-toggle d-md-none p-0 mr-3" type="button" data-toggle="collapse" data-target="#docs-nav" aria-controls="docs-nav" aria-expanded="false" aria-label="Toggle section navigation">
<span><i class="fas fa-bars"></i></span>
</button>
<input name="q" type="search" class="form-control" placeholder="Search..." autocomplete="off">
</form>
<nav class="collapse docs-links" id="docs-nav">
<div class="docs-toc-item">
<a class="docs-toc-link" href="/mosaic/docs/getting_started">Getting Started</a>
<ul class="nav docs-sidenav">
<li >
<a href="/mosaic/docs/getting_started/">Download</a>
</li>
<li >
<a href="/mosaic/docs/getting_started/run_mosaic/">Run Eclipse MOSAIC</a>
</li>
<li >
<a href="/mosaic/docs/getting_started/results/">Simulation Results</a>
</li>
</ul>
</div>
<div class="docs-toc-item">
<a class="docs-toc-link" href="/mosaic/docs/visualization">Visualization</a>
<ul class="nav docs-sidenav">
<li >
<a href="/mosaic/docs/visualization/">WebSocket Visualizer</a>
</li>
<li >
<a href="/mosaic/docs/visualization/filevis/">File Output</a>
</li>
<li >
<a href="/mosaic/docs/visualization/statistics/">Statistics Output</a>
</li>
<li >
<a href="/mosaic/docs/visualization/itef/">ITEF</a>
</li>
<li >
<a href="/mosaic/docs/visualization/phabmap/">PHABMap</a>
</li>
</ul>
</div>
<div class="docs-toc-item">
<a class="docs-toc-link" href="/mosaic/docs/simulators">Simulators</a>
<ul class="nav docs-sidenav">
<li >
<a href="/mosaic/docs/simulators/">Overview</a>
</li>
<li >
<a href="/mosaic/docs/simulators/application_simulator/">Application Simulator</a>
</li>
<li >
<a href="/mosaic/docs/simulators/traffic_simulator_sumo/">Traffic - Eclipse SUMO</a>
</li>
<li >
<a href="/mosaic/docs/simulators/network_simulator_omnetpp/">Network - OMNeT&#43;&#43;</a>
</li>
<li >
<a href="/mosaic/docs/simulators/network_simulator_ns3/">Network - ns-3</a>
</li>
<li >
<a href="/mosaic/docs/simulators/network_simulator_sns/">Network - SNS</a>
</li>
<li >
<a href="/mosaic/docs/simulators/network_simulator_cell/">Network - Cell</a>
</li>
<li >
<a href="/mosaic/docs/simulators/environment_simulator/">Environment Simulator</a>
</li>
<li >
<a href="/mosaic/docs/simulators/battery_simulator/">Battery Simulator</a>
</li>
<li >
<a href="/mosaic/docs/simulators/vms_simulator/">VMS Simulator</a>
</li>
</ul>
</div>
<div class="docs-toc-item">
<a class="docs-toc-link" href="/mosaic/docs/building_scenarios">Building Scenarios</a>
<ul class="nav docs-sidenav">
<li >
<a href="/mosaic/docs/building_scenarios/">Simulation Scenarios</a>
</li>
<li >
<a href="/mosaic/docs/building_scenarios/scenario_convert/">Scenario Convert</a>
</li>
<li >
<a href="/mosaic/docs/building_scenarios/scenario_configuration/">Additional Scenario Configuration</a>
</li>
</ul>
</div>
<div class="docs-toc-item">
<a class="docs-toc-link" href="/mosaic/docs/develop_applications">Create Applications</a>
<ul class="nav docs-sidenav">
<li >
<a href="/mosaic/docs/develop_applications/">Basics</a>
</li>
<li >
<a href="/mosaic/docs/develop_applications/communication/">V2X Communication</a>
</li>
<li >
<a href="/mosaic/docs/develop_applications/event_scheduler/">Event Scheduling</a>
</li>
<li >
<a href="/mosaic/docs/develop_applications/road_traffic/">Scenario Database</a>
</li>
</ul>
</div>
<div class="docs-toc-item">
<a class="docs-toc-link" href="/mosaic/docs/extending_mosaic">Extending Eclipse MOSAIC</a>
<ul class="nav docs-sidenav">
<li >
<a href="/mosaic/docs/extending_mosaic/">Core Concepts</a>
</li>
<li >
<a href="/mosaic/docs/extending_mosaic/simulator_coupling/">Simulator Coupling</a>
</li>
<li >
<a href="/mosaic/docs/extending_mosaic/interactions/">Interactions</a>
</li>
<li >
<a href="/mosaic/docs/extending_mosaic/application_ambassador_details/">Application Ambassador</a>
</li>
<li class="active">
<a href="/mosaic/docs/extending_mosaic/sumo_ambassador_details/">Sumo Ambassador</a>
</li>
<li >
<a href="/mosaic/docs/extending_mosaic/omnetpp_details/">OMNeT&#43;&#43; Federate</a>
</li>
<li >
<a href="/mosaic/docs/extending_mosaic/delay_models/">Delay Models</a>
</li>
</ul>
</div>
<div class="docs-toc-item">
<a class="docs-toc-link" href="/mosaic/docs/api_docs/">API Documentation</a>
<ul class="nav docs-sidenav">
<li >
<a href="/mosaic/docs/api_docs/">Javadoc</a>
</li>
</ul>
</div>
</nav>
</div>
<div class="docs-toc d-none d-xl-block col-xl-2">
<ul class="nav toc-top">
<li><a href="#" id="back_to_top" class="docs-toc-title">Contents</a></li>
</ul>
<nav id="TableOfContents">
<ul>
<li>
<ul>
<li><a href="#sumo-and-eclipse-mosaic">SUMO and Eclipse MOSAIC</a></li>
<li><a href="#simulation-of-vehicles">Simulation of Vehicles</a></li>
<li><a href="#traffic-lights-in-sumo">Traffic lights in SUMO</a></li>
<li><a href="#handling-of-traffic-lights-in-eclipse-mosaic">Handling of traffic lights in Eclipse MOSAIC</a></li>
<li><a href="#traci-client-implementation">TraCI Client Implementation</a></li>
</ul>
</li>
</ul>
</nav>
</div>
<style>
@media (min-width:1140px) {
.docs-sidebar {
flex: 0 1 320px;
}
.docs-toc {
flex: 0 1 280px;
}
main.docs-content.no-docs-toc {
padding-bottom: 0 !important;
max-width: calc(100% - 320px) !important;
flex: 0 1 calc(100% - 320px);
width: 100%;
}
main.docs-content {
padding-bottom: 0 !important;
max-width: calc(100% - 600px) !important;
flex: 0 1 calc(100% - 600px);
width: 100%;
}
}
@media (max-width: 770px) {
main.docs-content {
max-width: 100% !important;
width: 100%;
}
}
@media (min-width: 771px) and(max-width: 1139px) {
main.docs-content.no-docs-toc {
padding-bottom: 0 !important;
max-width: calc(100% - 320px) !important;
width: 100%;
}
}
</style>
<main class="docs-content col-12 col-md-9 col-xl-auto py-md-3 pl-md-4" role="main">
<article class="article">
<div class="docs-article-container">
<h1>Sumo Ambassador Implementation</h1>
<div class="article-style">
<p>The Simulation of Urban Mobility (SUMO) simulator is an open source microscopic, multi-modal traf-
fic simulation package which is developed by the Institute of Transportation research at the German
Aerospace Centre. It is designed to handle large road networks faster than real-time. Each vehicle has
an own route and is simulated individually. To simulate the movements of the vehicles on the network,
a model is used that uses discrete time steps of e.g. 1 s. Thousands of vehicles can be simulated in real
time on a desktop PC, including simulation of traffic lights, right-of-way rules, and lane changing models.
Simulations can either run via the command line or are visualized using the openGL-API (SUMO-GUI).
SUMO networks are created by importing other formats, such as OpenStreetMap data, Shapefiles or
TIGE-maps; or by generating artificial networks. Furthermore, vehicle routes, based on different routing
paradigms, can be computed.</p>
<h3 id="sumo-and-eclipse-mosaic">SUMO and Eclipse MOSAIC</h3>
<p>We have integrated the traffic simulator SUMO to be able to simulate heterogeneous driving vehicles and a set of vehicles that have a predefined routes based on an imported roadmap. Additionally, during
the runtime of a simulation, it is possible that routes of simulated vehicles are changed and that vehicle positions are extracted at arbitrary points in time. The integration of SUMO into a Eclipse MOSAIC based simulation is illustrated in the following figure. The integrated Traffic Control Interface (TraCI) Server offers an interface to exchange commands and positions using a socket interface with a proprietary byte protocol. Analogous to the TraCI Server, a TraCI Client is implemented that is integrated in an ambassador implementing the TraCI protocol. Therefore, SUMO can be integrated without modifications.</p>
<figure id="figure-sumo-connected-to-eclipse-mosaic">
<a data-fancybox="" href="../images/sumo-connected-to-mosaic.jpeg" data-caption="SUMO connected to Eclipse MOSAIC">
<img src="../images/sumo-connected-to-mosaic.jpeg" alt="" >
</a>
<figcaption data-pre="Figure " data-post=":" class="numbered">
SUMO connected to Eclipse MOSAIC
</figcaption>
</figure>
<p>During a simulation run, per default SUMO is paused and TraCI is listening for commands. After each
advanced time grant, SUMO offers the new vehicle positions which are broadcast by its ambassador
to other federates. Furthermore, if the ambassador receives a request to change the route of a specific
vehicle, it is forwarded to SUMO. Thus, at the next time-advancement, the new route is integrated.</p>
<h3 id="simulation-of-vehicles">Simulation of Vehicles</h3>
<p>For each vehicle which has been defined in the mapping configuration, a <code>VehicleRegistration</code> interaction is sent
to the <code>SumoAmbassador</code> which adds those vehicles to the simulation via TraCI. Furthermore, vehicle
data is subscribed which is updated with every simulation step. After each step of the simulation this
data is bundled into a <code>VehicleInfo</code> object which is distributed among other ambassadors within the
<code>VehicleUpdates</code> interaction. The following data is available for each vehicle:</p>
<ul>
<li>Position</li>
<li>Speed, Acceleration, Heading, Slope</li>
<li>State of vehicle signals (e.g. turn indicators)</li>
<li>Emission dispersion (CO2, NOX, etc.)</li>
<li>Fuel consumption</li>
<li>Information about the road the vehicle is driving on (road position)</li>
<li>Id of the route</li>
</ul>
<h3 id="traffic-lights-in-sumo">Traffic lights in SUMO</h3>
<p>Depending on which light is active (red, yellow or green), every traffic light got different phases. In theory,
any combination of dis- or enabled lights is possible, but SUMO only handles combinations which make
sense. In SUMOs traffic light concept every traffic light got a bitset of the status of each phase. Every
bitset is a combination as mentioned above. When a car approaches a junction, it gets the actual bitset
(combination) of the traffic light. To explain the code, an example is given:</p>
<pre><code class="language-xml">&lt;tl-logic type=&quot;static&quot;&gt;
&lt;key&gt;0&lt;/key&gt;
&lt;subkey&gt;my program&lt;/subkey&gt;
&lt;phaseno&gt;8&lt;/phaseno&gt;
&lt;offset&gt;0&lt;/offset&gt;
&lt;phase duration=&quot;31&quot; state=&quot;GGggrrrrGGggrrrr&quot;/&gt;
&lt;phase duration=&quot;5&quot; state=&quot;yyggrrrryyggrrrr&quot;/&gt;
&lt;phase duration=&quot;6&quot; state=&quot;rrGGrrrrrrGGrrrr&quot;/&gt;
&lt;phase duration=&quot;5&quot; state=&quot;rryyrrrrrryyrrrr&quot;/&gt;
&lt;phase duration=&quot;31&quot; state=&quot;rrrrGGggrrrrGGgg&quot;/&gt;
&lt;phase duration=&quot;5&quot; state=&quot;rrrryyggrrrryygg&quot;/&gt;
&lt;phase duration=&quot;6&quot; state=&quot;rrrrrrGGrrrrrrGG&quot;/&gt;
&lt;phase duration=&quot;5&quot; state=&quot;rrrrrryyrrrrrryy&quot;/&gt;
&lt;/tl-logic&gt;
</code></pre>
<p>This example shows the traffic light program of one junction. It shows the different status’ of each light
of each traffic signal, which are positioned on the junction. In this example every string of a phase e.g.
&ldquo;GGggrrrrGGggrrrr&rdquo; (first phase) got 16 characters. Every char stands for one light on the junction. On
this junction are four traffic lights with four signals each. To understand the different status of each light
in one period (8 phases) the program should be read from top to the bottom. It is possible to change or
create your own program by editing the .net file with the tool Netedit.</p>
<h3 id="handling-of-traffic-lights-in-eclipse-mosaic">Handling of traffic lights in Eclipse MOSAIC</h3>
<p>After the TraCI connection has been established, all available traffic light groups are read out of SUMO via
TraCI. This information is packed into the three classes <code>TrafficLightGroup</code>, <code>TrafficLightSignal</code>,
and <code>TrafficLightPhase</code>. While a traffic light group contains a list of signals which control one intersec-
tion (which can consist of several nodes), a list of all existing traffic light groups is sent to the RTI via a
<code>ScenarioTrafficLightRegistration</code> interaction.</p>
<h3 id="traci-client-implementation">TraCI Client Implementation</h3>
<p>The SumoAmbassador communicates with the federate (SUMO process) via TraCI. In this socket based
communication protocol, the server (SUMO) listens to commands and responds accordingly.</p>
<p>Each message send to SUMO consist of a header and the command or result message, according to the
following scheme:</p>
<pre><code> 0 7 8 15
+--------------------------------------+
| Message Length including this header |
+--------------------------------------+
| (Message Length, continued) |
+--------------------------------------+ \
| Length | Identifier | |
+--------------------------------------+ &gt; Command / Result_0
| Command / Result_0 content | |
+--------------------------------------+ /
...
+--------------------------------------+ \
| Length | Identifier | |
+--------------------------------------+ &gt; Command / Result_n -1
| Command / Result_n-1 content | |
+--------------------------------------+ /
</code></pre>
<p>A more detailed description can be found here:
<a href="http://sumo.dlr.de/wiki/TraCI/Protocol" target="_blank" rel="noopener">http://sumo.dlr.de/wiki/TraCI/Protocol</a></p>
<h4 id="commands">Commands</h4>
<p>Each TraCI command is identified by an command identifier. For example, the command 0xC4 is used to
change the state of a vehicle. Most of the commands need further specification, such as the parameter of
the vehicle which is required to be changed. Those parameters are usually accessed by variable identifiers
(e.g. 0x40 addresses the speed of an entity). A full list of commands and variables supported by TraCI can
be found here:
<a href="http://sumo.dlr.de/wiki/TraCI" target="_blank" rel="noopener">http://sumo.dlr.de/wiki/TraCI</a></p>
<p>Here is an example of a command message to change the speed of the vehicle &ldquo;veh_0&rdquo; to 14m/s:</p>
<pre><code> 0 7 8 15 23 24 31
+-----------------------------------------------------------------------------+
| 25 (Message length) |
+-----------------------------------------------------------------------------+
| 21 (Length) | 0xC4 (Command) | 0x40 (Variable) |
+-----------------------------------------------------------------------------+
5 (String length as 4 Byte Integer) | &quot;v&quot; |
+-----------------------------------------------------------------------------+
| &quot;e&quot; | &quot;h&quot; | &quot;_&quot; | &quot;0&quot; |
+-----------------------------------------------------------------------------+
| 0x0B (Double type)| 40.0 (8 Byte Double)
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|
+-------------------+
</code></pre>
<h4 id="abstracttracicommand">AbstractTraciCommand</h4>
<p>In the TraCI client implementation of the <code>SumoAmbassador</code> the whole construction of messages is done in
the class <code>AbstractTraciCommand</code>. The message header containing the message and command lengths
is constructed automatically as well as all parameters defined by the specific command. To achieve this,
each class which extends the <code>AbstractTraciCommand</code> needs to define the command, the variable and
all parameters which are required for the specific command:</p>
<pre><code class="language-java">protected VehicleSetSpeed() {
super(TraciVersion.LOWEST);
write()
.command(0xC4) // = change vehicle state
.variable(0x04) // = set speed of entity
.writeStringParam() // = vehicle id
.writeDoubleParamWithType(); // = speed value
}
</code></pre>
<p>This example shows the command implementation for setting the speed for a vehicle. In the constructor,
the write methods provides a builder-like construct allowing to define the command, the variable, and all
parameters which are later passed dynamically to the command. Here, the command is specified as <code>0xC4</code> (= change vehicle state) and the variable as <code>0x04</code> (= speed of the entity). Furthermore, two parameters are
defined: The first string parameter represents the ID of the vehicle, the second double parameter defines
the speed value to be set (according to
<a href="http://sumo.dlr.de/wiki/TraCI/Change_Vehicle_State" target="_blank" rel="noopener">http://sumo.dlr.de/wiki/TraCI/Change_Vehicle_State</a>).
Note, the order of the specified command contents is from crucial importance. E.g. the <code>command</code> must
always be specified before the <code>variable</code>, and the variable before all parameters.</p>
<p>All parameters defined in the constructor (here: <code>[String, Double]</code> ), need to be assigned with values
as soon as the command is executed. For this purpose, the command implementation needs to call the
method execute of the super class with the parameter values in the specified order:</p>
<pre><code class="language-java">public void setSpeed(TraciConnection traciCon, String vehicleId, double speedValue) {
super.execute(traciCon, vehicleId, value);
}
</code></pre>
<p>Within the execute method, the <code>AbstractTraciCommand</code> constructs the whole message and sends it to
the TraCI server (SUMO). Furthermore, the <code>AbstractTraciCommand</code> also reads the response, extracts the
status of the response (successful or error) and reads all values returned by the server. Usually, commands
which changes the state of an entity only (like <code>VehicleSetSpeed</code>) do not respond with complex results.
However, a command which wants to retrieve a value of an entity needs to read out the result from the
response (e.g. <code>VehicleGetRouteId</code> which returns the current route identifier of the vehicle). For this
purpose, each command needs to specify how the response should be handled:</p>
<pre><code class="language-java">protected VehicleGetRouteId() {
super(TraciVersion.LOWEST);
write()
.command(0xA4) // = retrieve vehicle state
.variable(0x53) // = route id of entity
.writeStringParam(); // = write vehicle id
read()
.skipBytes(2) // = skip command and variable in response
.skipString() // = skip vehicle id, not relevant
.readStringWithType(); // = read route id
</code></pre>
<p>This example shows the command implementation for getting the route id of a vehicle. As well as <code>write</code>,
the method read returns a builder-like construct which provides methods to define how the response is
handled. Here, the first two bytes of the response should be skipped, as well as the string which follows
afterwards. The value the command is interested in is the following string value which holds the id of
the route. By using the method <code>readStringWithType</code> the string is read out and is passed to the method
<code>constructResult</code> which needs to be implemented by the command as well:</p>
<pre><code class="language-java">public String getRouteId(TraciConnection con, String vehicle) {
return super.executeAndReturn(con, vehicle);
}
@Override
protected String constructResult(Status status, Object... objects) {
return (String) objects[0];
}
</code></pre>
<p>In this simple case the result of the command consists of one result object only (the route id). Therefore,
it is just extracted from the array of result objects and directly returned.</p>
<h4 id="writing-parameters">Writing parameters</h4>
<p>In order to write parameters and read results according to the specification of the protocol, several reader
and writer implementations exist. For parameters to be written in the command various writers exists
to write single bytes, strings, integers, and doubles, or special writers for writing lists. The same is for
readers.</p>
<p>In the following example, the IntegerTraciWriter is shown:</p>
<pre><code class="language-java">public class IntegerTraciWriter extends AbstractTraciParameterWriter&lt;Integer&gt; {
public IntegerTraciWriter() {
super(4);
}
public IntegerTraciWriter(int value) {
super(4, value);
}
@Override
public int getVariableLength(Integer argument) {
return getLength();
}
@Override
public void write(DataOutputStream out) throws IOException {
out.writeInt(value);
}
@Override
public void writeVariableArgument(DataOutputStream out, Integer argument) {
out.writeInt(argument);
}
}
</code></pre>
<p>Each writer has two tasks. Firstly, it needs to determine the length of the parameter value. For example,
an integer parameter is always 4 bytes long, whereas the length of a string parameter depends on the
size of the argument. Therefore, each writer needs to be able to determine the variable length according
to a given value. Secondly, it needs to write out the actual value into the <code>DataOutputStream</code> (which
represents the channel to the TraCI server). Furthermore is each writer able to write fixed values, such as
the command identifier which does not change, or variable arguments, such as the vehicle id.</p>
<h4 id="reading-results">Reading results</h4>
<p>In the following example, the IntegerTraciReader is shown:</p>
<pre><code class="language-java">public class IntegerTraciReader extends AbstractTraciResultReader&lt;Integer&gt; {
public IntegerTraciReader() {
super(null);
}
public IntegerTraciReader(Matcher&lt;Integer&gt; matcher) {
super(matcher);
}
@Override
protected Integer readFromStream(DataInputStream in) throws IOException {
return readInt(in);
}
}
</code></pre>
<p>A reader has three tasks. Firstly, it reads out a value from the <code>DataInputStream</code> (which represents the
response channel to the TraCI client) according to the protocol specification. For example, an integer
can be read out directly, while a string requires several single reading operations. Secondly, the reader
needs to take track of the number of bytes it has read in total. To achieve this it is recommended to use
the provided methods of the super class, such as <code>readInt</code>, <code>readString</code>, or <code>readByte</code> .However, if values
need to be read directly from the DataInputStream, the protected field <code>numBytesRead</code> must always be
increased accordingly. Thirdly, the reader needs to define if the read out value fulfils certain requirements.
Such requirement can be, that a certain value is expected. In this case, a matcher might be passed to the
super constructor.</p>
<h4 id="accessing-the-commands">Accessing the commands</h4>
<p>For each command, only one object should be instantiated during runtime. To achieve this, the
<code>CommandRegister</code> is used. This class stores a command once it is created returns only one instance per
command class:</p>
<pre><code class="language-java">final RouteAdd routeAddCommand = commandRegister.getOrCreate(RouteAdd.class);
//... do something
</code></pre>
<p>However, commands should not be accessed directly in the code, but rather using the various facades
available:</p>
<ul>
<li><code>TraciRouteFacade</code> - Route specific command calls, such as addRoute and getRouteEdges .</li>
<li><code>TraciSimulationFacade</code> - Provides methods to control the simulation, such as simulateStep .</li>
<li><code>TraciTrafficLightFacade</code> - Provides methods to get or set values for traffic lights.</li>
<li><code>TraciVehicleFacade</code> - Provides methods to get or set values for vehicles.
All those facades can be accessed via the <code>TraciClient</code>.</li>
</ul>
<h4 id="exception-handling">Exception handling</h4>
<p>Exceptions are thrown and handled as following:</p>
<ul>
<li>
<p>If a command results in a status response with the status code Error, a <code>TraciCommandException</code>
is thrown. If this exception is thrown, the TraCI connection is still alive and can be used for
further commands. The facades decide how to handle this exception then and may throw an
<code>InternalFederateException</code> or log a warning message.</p>
</li>
<li>
<p>If a command could not be written properly, or the result could not be read out as wished, an
<code>InternalFederateException</code> is thrown and an <code>Emergency Exit</code> is initiated, which eventually
shuts down the TraCI connection. This also happens if a reader or writer throws any kind of
Exception.</p>
</li>
</ul>
<h4 id="version-handling">Version handling</h4>
<p>With future releases of SUMO new TraCI commands will emerge. To achieve downward compatibility
each command can define the lowest TraCI Version it supports. For example, a command which was
introduced with SUMO 0.30.0 and is annotated accordingly, would be skipped automatically if the version
of the TraCI server is lower. However, this concept has not been tested yet properly.</p>
</div>
<div class="article-widget">
<div class="post-nav prev-next-pages col-12">
<div class="row">
<div class="post-nav-item col-6">
<div class="meta-nav">Previous</div>
<a href="/mosaic/docs/extending_mosaic/application_ambassador_details/" rel="next">Application Ambassador - Implementation Details</a>
</div>
<div class="post-nav-item col-6 align-self-end">
<div class="meta-nav">Next</div>
<a href="/mosaic/docs/extending_mosaic/omnetpp_details/" rel="prev">OMNeT&#43;&#43; Federate Implementation</a>
</div>
</div>
</div>
</div>
</div>
<footer class="site-footer">
<div class="row">
<div class="col-sm-4 mb-3 mb-md-0">
<b>Eclipse MOSAIC</b>
<ul>
<li>
<a href="/mosaic/download/" title="Download Eclipse MOSAIC" >
Download Eclipse MOSAIC
</a>
</li>
<li>
<a href="/mosaic/docs" title="Documentation" >
Documentation
</a>
</li>
<li>
<a href="/mosaic/tutorials" title="Tutorials" >
Tutorials
</a>
</li>
<li>
<a href="/mosaic/community/#projects" title="Projects" >
Projects
</a>
</li>
<li>
<a href="/mosaic/publications" title="Publications" >
Publications
</a>
</li>
</ul>
</div>
<div class="col-sm-4 mb-3 mb-md-0">
<b>Community</b>
<ul>
<li>
<a href="/mosaic/community" title="Eclipse MOSAIC Community" >
Eclipse MOSAIC Community
</a>
</li>
<li>
<a href="/mosaic/contribution" title="How to contribute" >
How to contribute
</a>
</li>
<li>
<a href="https://github.com/eclipse/mosaic" title="Github" target="_blank" rel="noopener">
Github
</a>
</li>
<li>
<a href="/mosaic/get_in_contact" title="Contact &amp; Mailing list" >
Contact & Mailing list
</a>
</li>
</ul>
</div>
<div class="col-sm-4 mb-3 mb-md-0">
<b>Eclipse Foundation</b>
<ul>
<li>
<a href="https://www.eclipse.org/" title="About Eclipse Foundation" target="_blank" rel="noopener">
About Eclipse Foundation
</a>
</li>
<li>
<a href="https://www.eclipse.org/legal/privacy.php" title="Privacy Policy" target="_blank" rel="noopener">
Privacy Policy
</a>
</li>
<li>
<a href="https://www.eclipse.org/legal/termsofuse.php" title="Website terms of use" target="_blank" rel="noopener">
Website terms of use
</a>
</li>
<li>
<a href="https://www.eclipse.org/legal/copyright.php" title="Copyright" target="_blank" rel="noopener">
Copyright
</a>
</li>
<li>
<a href="https://www.eclipse.org/legal" title="Legal" target="_blank" rel="noopener">
Legal
</a>
</li>
</ul>
</div>
</div>
<div class="row justify-content-center mt-3 position-relative">
<p class="powered-by text-center font-italic mb-0 pb-0">
Powered by the
<a href="https://sourcethemes.com/academic/" target="_blank" rel="noopener">Academic theme</a> for
<a href="https://gohugo.io" target="_blank" rel="noopener">Hugo</a>.
<br>
Header image &#169; fanjianhua/ iStock
</p>
</div>
</footer>
</article>
</main>
</div>
</div>
<script src="https://code.jquery.com/jquery-3.4.1.min.js" integrity="sha384-vk5WoKIaW/vJyUAd9n/wmopsmNhiy+L2Z+SBxGYnUkunIxVxAv/UtMOhba/xskxh" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/2.6.0/umd/popper.min.js" integrity="sha512-BmM0/BQlqh02wuK5Gz9yrbe7VyIVwOzD1o40yi1IsTjriX/NGF37NyXHfmFzIlMmoSIBXgqDiG1VNU6kB5dBbA==" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.imagesloaded/4.1.4/imagesloaded.pkgd.min.js" integrity="sha512-S5PZ9GxJZO16tT9r3WJp/Safn31eu8uWrzglMahDT4dsmgqWonRY9grk3j+3tfuPr9WJNsfooOR7Gi7HL5W2jw==" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.isotope/3.0.6/isotope.pkgd.min.js" integrity="sha512-Zq2BOxyhvnRFXu0+WE6ojpZLOU2jdnqbrM1hmVdGzyeCa1DgM3X5Q4A/Is9xA1IkbUeDd7755dNNI/PzSf2Pew==" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/fancybox/3.5.7/jquery.fancybox.min.js" integrity="sha512-uURl+ZXMBrF4AwGaWmEetzrd+J5/8NRkWAvJx5sbPSSuOb0bZLqf+tOzniObO00BjHa/dD7gub9oCGMLPQHtQA==" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.4.8/mermaid.min.js" integrity="sha512-1tS1YUns336Mtxl+vkaLcADPwE1CPNVy3WEf7nrI7DGMMb6/FAVBgL2IzAWVBkB6vVuK94s2zVoiXcw1QZ9S1g==" crossorigin="anonymous" title="mermaid"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/highlight.min.js" integrity="sha512-1LdB3V708w6G4QRl7NsVdTr7MDibyRXr9stQZ+EGjEE0ZPMZkA//ir7kCWmFyxdAJNIRXdR/ZeJmCV0boyiCXw==" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/languages/java.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/languages/json.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/languages/xml.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/languages/shell.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/languages/dos.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.5.1/leaflet.js" integrity="sha512-GffPMF3RvMeYyc1LWMHtK8EbPv0iNZ8/oTtHPx9/cc2ILxQ+u905qIwdpULaqDkyBKgOaB57QTMg7ztg8Jm2Og==" crossorigin="anonymous"></script>
<script>const code_highlighting = true;</script>
<script>const isSiteThemeDark = false;</script>
<script>
const search_config = {"indexURI":"/mosaic/index.json","minLength":1,"threshold":0.3};
const i18n = {"no_results":"No results found","placeholder":"Search...","results":"results found"};
const content_type = {
'post': "Posts",
'project': "Projects",
'publication' : "Publications",
'talk' : "Talks"
};
</script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/4.1.1/anchor.min.js" integrity="sha512-aZotBPy6dqn8yVaLJwSrkJ+QxuxV695A4dgodAMvTU5JyNi5mhrr+LeaD3GSS+lx1SMFKNs0tu5ZMJEgNZQP2Q==" crossorigin="anonymous"></script>
<script>
anchors.add();
</script>
<script id="search-hit-fuse-template" type="text/x-template">
<div class="search-hit" id="summary-{{key}}">
<div class="search-hit-content">
<div class="search-hit-name">
<a href="{{relpermalink}}">{{title}}</a>
<div class="article-metadata search-hit-type">{{type}}</div>
<p class="search-hit-description">{{snippet}}</p>
</div>
</div>
</div>
</script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/fuse.js/3.2.1/fuse.min.js" integrity="sha512-o38bmzBGX+hD3JHWUFCDA09btWaqrNmoJ3RXLlrysA7PP01Kgs4UlE4MhelE1v5dJR3+cxlR4qQlotsW7jKsnw==" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mark.js/8.11.1/jquery.mark.min.js" integrity="sha512-mhbv5DqBMgrWL+32MmsDOt/OAvqr/cHimk6B8y/bx/xS88MVkYGPiVv2ixKVrkywF2qHplNRUvFsAHUdxZ3Krg==" crossorigin="anonymous"></script>
<script type="application/javascript" src="/mosaic/js/academic.min.0992ad8b8d033c3858bb90b03966346a.js"></script>
<script type="application/javascript" src="/mosaic/js/mosaic-wg-cards.js"></script>
<script>
var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
tooltipTriggerList.map(function (tooltipTriggerEl) {
return new window.bootstrap.Tooltip(tooltipTriggerEl)
})
</script>
<div id="modal" class="modal fade" role="dialog">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title">Cite</h5>
<button type="button" class="close" data-dismiss="modal" aria-label="Close">
<span aria-hidden="true">&times;</span>
</button>
</div>
<div class="modal-body">
<pre><code class="tex hljs"></code></pre>
</div>
<div class="modal-footer">
<a class="btn btn-outline-primary my-1 js-copy-cite" href="#" target="_blank">
<i class="fas fa-copy"></i> Copy
</a>
<a class="btn btn-outline-primary my-1 js-download-cite" href="#" target="_blank">
<i class="fas fa-download"></i> Download
</a>
<div id="modal-error"></div>
</div>
</div>
</div>
</div>
</body>
</html>