First draft.

Docs/adv_opendrive.md

@@ -0,0 +1,59 @@
+# OpenDRIVE standalone mode
+
+This feature allows users to ingest any OpenDRIVE file as a CARLA map out-of-the-box. In order to do so, the simulator will automatically generate a road mesh for actors to navigate through.  
+
+*	[__Overview__](#overview)  
+*	[__Run a standalone map__](#run-a-standalone-map)  
+*	[__Mesh generation__](#mesh-generation)  
+
+---
+## Overview
+
+This mode runs a full simulation using only an OpenDRIVE file, without the need of any additional gemotires or assets. To this end, the simulator takes an OpenDRIVE file and procedurally creates a temporal 3D mesh to run the simulation with.  
+
+The resulting mesh describes the road definition in a minimalistic manner. All the elements will correspond with the OpenDRIVE file, but besides that, there will be only void. In order to prevent vehicles from falling off the road, two measures have been taken. 
+
+*	Lanes are a bit wider at junctions, where the flow of vehicles is most complex.  
+*	Visible walls are created at the boundaries of the road, to act as a last safety measure. 
+
+Traffic lights, stops and yields will be generated on the fly, as happens when using any map. Pedestrians will navigate over the sidewalks and crosswalks that appear in the map. All of these elements, and every detail on the road, are based on the OpenDRIVE file. As the standalone mode uses the `.xodr` directly, any issues in it will propagate to the simulation. This could be an issue especially at junctions, where many lanes are mixed.
+
+*	OpenDRIVE maps created with RoadRunner present some issues related to tilted junction ??
+*	Lateral slope for roads is not supported yet ??
+*	The sidewalks height is currently hardcoded. This ensures collisions with them are detected even if the map definition does not include this field ??
+*	What .xml ??
+
+!!! Important
+    It is especially important to double check the OpenDRIVE file. Any issues in it will propagate when running the simulation.
+
+![opendrive_standalone](img/opendrive_standalone.png)
+
+---
+## Run a standalone map
+
+In order to test this feature, the `config.py` script in `PythonAPI/util/` has a new argument, `-x` or `--xodr-path`. This argument contains a string with the path to the `.xodr` file. The script calls a client method, [`client.generate_opendrive_world()`](python_api.md#carla.Client.generate_opendrive_world). This will block the simulation, as [`load_world()`](python_api.md#carla.World.load_world) would do, until the new map is active.
+
+```sh
+python3 config.py -x path/to/some/file.xodr
+```
+
+---
+## Mesh generation
+
+The generation of the mesh is the key element of this mode. The feature can only be successful if the resulting mesh is smooth and fits its definition perfectly. For that reason, this step is constantly being improved. In the last iterations, junctions have been polished to avoid inaccuracies that occur, especially where uneven lanes joined.  
+
+Besides that, instead of creating the whole map as a unique mesh, different fragments are created. Working smaller prevents unexpected issues. Also, by dividing the mesh, not all of it has to be rendered at a time. This is a step towards a larger goal, where the feature will be able to generate huge maps.
+
+
+---
+
+That covers all there is to know so far, regarding the OpenDRIVE standalone mode. Take the chance and use any OpenDRIVE map to test it in CARLA.  
+
+Doubts and suggestions in the forum. 
+
+<div class="build-buttons">
+<p>
+<a href="https://forum.carla.org/" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
+CARLA forum</a>
+</p>
+</div>

Docs/adv_sumo.md

@@ -0,0 +1,89 @@
+# SUMO co-simulation
+
+CARLA has developed a co-simulation feature with SUMO. This allows to distribute the tasks at will, and exploit the capabilities of each simulation in favour of the user.  
+
+*	[__Requisites__](#requisites)  
+	*	[Prepare a SUMO environment](#prepare-a-sumo-environment)
+*	[__Run the co-simulation__](#run-the-co-simulation)  
+	*	[Spawn vehicles](#spawn-vehicles)
+*	[__Spawn NPCs with SUMO__](#spawn-npcs-with-sumo)  
+
+---
+## Requisites
+
+First and foremost, it is necessary to [__install SUMO__](https://sumo.dlr.de/docs/Installing.html) to run the co-simulation. 
+
+Once that is done, the SUMO environment has to be set to run the co-simulation. 
+
+### Prepare a SUMO environment 
+
+The script `util/netconvert_carla.py` generates a SUMO network from an OpenDRIVE file. This script runs the *netconvert* tool to generate the main road network without traffic lights. These are then created one by one, using the OpenDRIVE definition. That way, inaccuracies are avoided.  
+
+```sh
+python netconvert_carla.py <PATH_TO_XODR> --output Test.net.xml
+```
+
+Once the net file has been generated, this can be opened in SUMO. Use it to prepare the SUMO environment for the co-simulation.  
+> What to know. Tips.  
+> Can this be done without that?  
+> How to store the environment.  
+
+---
+## Run the co-simulation
+
+Everything related with this feature can be found in `Co-Simulation/Sumo`. Several examples are provided for some CARLA maps, specifically __Town01__, __Town04__, and __Town05__. These contain some basic SUMO environments that will ease the usage of the feature.  
+
+Use one of this examples, or any other SUMO file, to start the co-simulation. There are some optional arguments that can be set.  
+
+*	__`--tls-manager <string>`__ chooses which simulator will change the state of the traffic lights. The other will update them accordingly.  
+	*	`carla` to put CARLA in charge of the traffic lights.  
+	*	`sumo` to put SUMO in charge of the traffic lights. 
+	*	`none` to disable the synchronization of traffic lights. Vehicles do not take them into consideration --> None of them, or only one? 
+
+*	__`--sumo-gui`__ will create a window to visualize the SUMO simulation. By default SUMO runs off-screen. 
+
+```sh
+python run_synchronization.py examples/TestTLS.sumocfg --tls-manager carla --sumo-gui
+```
+
+Both simulations will run in synchrony. The actions or events happening in one simulator will propagate to the other, e.g. positions, spawning, vehicle lights, etc.
+
+Traffic lights As long as they are defined in the OpenDRIVE road map, they will be generated in SUMO. Now the synchronization script has some additional arguments.
+> Landmarks? 
+> Pedestrians? 
+
+!!! Important
+    SUMO Traffic lights will not be generated in the released CARLA maps. They were added manually and cannot be retrieved from the OpenDRIVE.
+
+
+### Spawn vehicles
+
+There are some helper scripts that translate CARLA blueprints to SUMO vehicle types so that the vehicles’ specifications are the same in both simulators. If these are not used, CARLA will spawn a random vehicle based on the given SUMO vehicle type.
+
+
+---
+## SUMO Vs Traffic Manager
+
+The script `spawn_npc_sumo.py` is almost equivalent to the already-known `spawn_npc.py`. The difference is that vehicles will be managed using SUMO instead of the Traffic Manager. This script automatically generates a SUMO network in a temporal folder, based on the active town in CARLA. The script will create random routes and let the vehicles roam around.
+
+As the script runs a synchronous simulation, and spawns vehicles in it, the arguments are the same that appear in run_synchronization.py and spawn_npc.py.
+
+```sh
+# Spawn 10 vehicles, that will be managed by SUMO instead of Traffic Manager.
+# CARLA in charge of traffic lights.
+# Open a window for SUMO visualization.
+python spawn_sumo_npc.py -n 10 --tls-manager carla --sumo-gui
+```
+
+---
+
+That sets the basics regarding the RSS sensor in CARLA. Find out more about the specific attributes and parameters in the [sensor reference](ref_sensors.md#rss-sensor). 
+
+Open CARLA and mess around for a while. If there are any doubts, feel free to post these in the forum. 
+
+<div class="build-buttons">
+<p>
+<a href="https://forum.carla.org/" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
+CARLA forum</a>
+</p>
+</div>

Docs/index.md

@@ -59,12 +59,16 @@ CARLA forum</a>
 
 ## Advanced steps
   <p style="padding-left:30px;line-height:1.8">
+    [__OpenDRIVE standalone mode__](adv_opendrive.md)
+        — Use any OpenDRIVE file as a CARLA map.
     [__Recorder__](adv_recorder.md)
         — Register the events in a simulation and play it again.  
     [__Rendering options__](adv_rendering_options.md)
         — From quality settings to no-render or off-screen modes.  
     [__RSS sensor__](adv_rss.md)
         — An implementation of RSS in the CARLA client library.  
+    [__SUMO co-simulation__](adv_sumo.md)
+        — Run a synchronous simulation between CARLA and SUMO.  
     [__Synchrony and time-step__](adv_synchrony_timestep.md)
         — Client-server communication and simulation time.  
     [__Traffic Manager__](adv_traffic_manager.md)

mkdocs.yml

@@ -24,9 +24,11 @@ nav:
   - '3rd. Maps and navigation': 'core_map.md'
   - '4th. Sensors and data': 'core_sensors.md'
 - Advanced steps:
+  - 'OpenDRIVE standalone mode': 'adv_opendrive.md'
   - 'Recorder': 'adv_recorder.md'
   - 'Rendering options': 'adv_rendering_options.md'
   - 'RSS sensor': 'adv_rss.md'
+  - 'SUMO co-simulation': 'adv_sumo.md'
   - 'Synchrony and time-step': 'adv_synchrony_timestep.md'
   - 'Traffic Manager': 'adv_traffic_manager.md'
 - References: