2018-03-22 01:16:56 +08:00
|
|
|
<h1>CARLA Server</h1>
|
2017-03-03 22:54:19 +08:00
|
|
|
|
2017-10-11 23:20:26 +08:00
|
|
|
Build
|
|
|
|
-----
|
|
|
|
|
2017-10-25 23:26:49 +08:00
|
|
|
Some scripts are provided for building and testing CarlaServer on Linux
|
2017-10-11 23:20:26 +08:00
|
|
|
|
2017-11-13 21:01:55 +08:00
|
|
|
$ ./Setup.sh
|
2017-10-11 23:20:26 +08:00
|
|
|
$ make
|
2017-10-25 23:26:49 +08:00
|
|
|
$ make check
|
2017-10-11 23:20:26 +08:00
|
|
|
|
|
|
|
The setup script downloads and compiles all the required dependencies. The
|
|
|
|
Makefile calls CMake to build CarlaServer and installs it under "Util/Install".
|
|
|
|
|
2017-07-26 17:12:39 +08:00
|
|
|
Protocol
|
2017-03-03 22:54:19 +08:00
|
|
|
--------
|
|
|
|
|
2017-10-11 23:20:26 +08:00
|
|
|
All the messages are prepended by a 32 bits unsigned integer (little-endian)
|
|
|
|
indicating the size of the coming message.
|
2017-03-30 20:25:37 +08:00
|
|
|
|
2017-07-26 17:12:39 +08:00
|
|
|
Three consecutive ports are used,
|
2017-03-30 20:25:37 +08:00
|
|
|
|
2017-07-26 17:12:39 +08:00
|
|
|
* world-port (default 2000)
|
2017-10-11 23:20:26 +08:00
|
|
|
* measurements-port = world-port + 1
|
2017-07-26 17:12:39 +08:00
|
|
|
* control-port = world-port + 2
|
2017-03-16 02:01:34 +08:00
|
|
|
|
2017-10-11 23:20:26 +08:00
|
|
|
each of these ports has an associated thread that sends/reads data
|
|
|
|
asynchronuosly.
|
|
|
|
|
2018-03-22 01:16:56 +08:00
|
|
|
<h4>World thread</h4>
|
2017-03-29 17:11:34 +08:00
|
|
|
|
2017-07-26 17:12:39 +08:00
|
|
|
Server reads one, writes one. Always protobuf messages.
|
2017-03-20 22:32:31 +08:00
|
|
|
|
2017-07-26 17:12:39 +08:00
|
|
|
[client] RequestNewEpisode
|
|
|
|
[server] SceneDescription
|
|
|
|
[client] EpisodeStart
|
|
|
|
[server] EpisodeReady
|
|
|
|
...repeat...
|
2017-03-20 22:32:31 +08:00
|
|
|
|
2018-03-22 01:16:56 +08:00
|
|
|
<h4>Measurements thread</h4>
|
2017-03-20 22:32:31 +08:00
|
|
|
|
2017-10-11 23:20:26 +08:00
|
|
|
Server only writes, first measurements message then the bulk of raw images.
|
2017-03-16 02:01:34 +08:00
|
|
|
|
2017-07-26 17:12:39 +08:00
|
|
|
[server] Measurements
|
|
|
|
[server] raw images
|
|
|
|
...repeat...
|
2017-03-30 01:05:26 +08:00
|
|
|
|
2018-06-27 18:59:12 +08:00
|
|
|
Every image is an array of
|
2017-03-30 01:05:26 +08:00
|
|
|
|
2018-06-27 18:59:12 +08:00
|
|
|
[frame_number, width, height, type, FOV, color[0], color[1], ...]
|
|
|
|
|
|
|
|
of types
|
|
|
|
|
|
|
|
[uint64, uint32, uint32, uint32, float32, uint32, uint32, ...]
|
2017-03-30 01:05:26 +08:00
|
|
|
|
2017-12-01 23:49:30 +08:00
|
|
|
where FOV is the horizontal field of view of the camera as float, each color is
|
|
|
|
an [FColor][fcolorlink] (BGRA) as stored in Unreal Engine, and the possible
|
|
|
|
types of images are
|
2017-10-11 23:20:26 +08:00
|
|
|
|
|
|
|
type = 0 None (RGB without any post-processing)
|
|
|
|
type = 1 SceneFinal (RGB with post-processing present at the scene)
|
|
|
|
type = 2 Depth (Depth Map)
|
|
|
|
type = 3 SemanticSegmentation (Semantic Segmentation)
|
2017-03-30 01:05:26 +08:00
|
|
|
|
2017-11-16 23:14:11 +08:00
|
|
|
The measurements message is explained in detail [here](measurements.md).
|
|
|
|
|
2017-09-07 22:04:18 +08:00
|
|
|
[fcolorlink]: https://docs.unrealengine.com/latest/INT/API/Runtime/Core/Math/FColor/index.html "FColor API Documentation"
|
2017-03-30 01:05:26 +08:00
|
|
|
|
2018-03-22 01:16:56 +08:00
|
|
|
<h4>Control thread</h4>
|
2017-03-30 01:05:26 +08:00
|
|
|
|
2017-10-11 23:20:26 +08:00
|
|
|
Server only reads, client sends Control message every frame.
|
2017-03-03 22:54:19 +08:00
|
|
|
|
2017-07-26 17:12:39 +08:00
|
|
|
[client] Control
|
|
|
|
...repeat...
|
2017-03-03 22:54:19 +08:00
|
|
|
|
2017-10-11 23:20:26 +08:00
|
|
|
In the synchronous mode, the server halts execution each frame until the Control
|
|
|
|
message is received.
|
|
|
|
|
|
|
|
C API
|
|
|
|
-----
|
|
|
|
|
|
|
|
The library is encapsulated behind a single include file in C,
|
2017-10-11 23:24:03 +08:00
|
|
|
["carla/carla_server.h"][carlaserverhlink].
|
2017-10-11 23:20:26 +08:00
|
|
|
|
|
|
|
This file contains the basic interface for reading and writing messages to the
|
|
|
|
client, hiding the networking and multi-threading part. Most of the functions
|
|
|
|
have a time-out parameter and block until the corresponding asynchronous
|
|
|
|
operation is completed or the time-out is met. Set a time-out of 0 to get a
|
|
|
|
non-blocking call.
|
|
|
|
|
|
|
|
A CarlaServer instance is created with `carla_make_server()` and should be
|
|
|
|
destroyed after use with `carla_server_free(ptr)`.
|
|
|
|
|
2017-11-13 21:01:55 +08:00
|
|
|
[carlaserverhlink]: https://github.com/carla-simulator/carla/blob/master/Util/CarlaServer/include/carla/carla_server.h
|
2017-10-11 23:20:26 +08:00
|
|
|
|
|
|
|
Design
|
|
|
|
------
|
|
|
|
|
|
|
|
The C API takes care of dispatching the request to the corresponding server.
|
|
|
|
There are three asynchronous servers each of them running on its own thread.
|
|
|
|
|
|
|
|
![CarlaServer design](img/carlaserver.svg)
|
|
|
|
|
|
|
|
Conceptually there are two servers, the _World Server_ and the _Agent Server_.
|
|
|
|
The _World Server_ controls the initialization of episodes. A new episode is
|
|
|
|
started every time it is requested to the World Server by a RequestNewEpisode
|
|
|
|
message. Once the episode is ready, the World Server launches the Agent Server.
|
|
|
|
The _Agent Server_ has two threads, one for sending the streaming of the
|
|
|
|
measurements and another for receiving the control. Both agent threads
|
|
|
|
communicate with the main thread through a lock-free double-buffer to speed up
|
|
|
|
the streaming of messages and images.
|
|
|
|
|
|
|
|
The encoding of the messages (protobuf) and the networking operations are
|
|
|
|
executed asynchronously.
|