diff --git a/Docs/carla_server.md b/Docs/carla_server.md index 055b52509..4dc3c1171 100644 --- a/Docs/carla_server.md +++ b/Docs/carla_server.md @@ -1,18 +1,32 @@ CARLA Server ============ +Build +----- + +Some scripts are provided for building CarlaServer on Linux + + $ Setup.sh + $ make + +The setup script downloads and compiles all the required dependencies. The +Makefile calls CMake to build CarlaServer and installs it under "Util/Install". + Protocol -------- -All the messages are prepended by a 32 bits unsigned integer (assumed -little-endian) indicating the size of the coming message. +All the messages are prepended by a 32 bits unsigned integer (little-endian) +indicating the size of the coming message. Three consecutive ports are used, * world-port (default 2000) - * stream-port = world-port + 1 + * measurements-port = world-port + 1 * control-port = world-port + 2 +each of these ports has an associated thread that sends/reads data +asynchronuosly. + ###### World thread Server reads one, writes one. Always protobuf messages. @@ -23,9 +37,9 @@ Server reads one, writes one. Always protobuf messages. [server] EpisodeReady ...repeat... -###### Stream thread +###### Measurements thread -Server only writes, first measurements then the raw images. +Server only writes, first measurements message then the bulk of raw images. [server] Measurements [server] raw images @@ -35,15 +49,59 @@ Every image is an array of uint32's [width, height, type, color[0], color[1],...] -where each color is an [FColor][fcolorlink] (BGRA) as stored in Unreal Engine. +where each color is an [FColor][fcolorlink] (BGRA) as stored in Unreal Engine, +and the possible types of images are + + 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) [fcolorlink]: https://docs.unrealengine.com/latest/INT/API/Runtime/Core/Math/FColor/index.html "FColor API Documentation" ###### Control thread -Server only reads, client sends Control every frame. +Server only reads, client sends Control message every frame. [client] Control ...repeat... -In the synchronous mode, the server waits each frame for a Control message. +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, +["carla/carla_server.h"](carlaserverhlink). + +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)`. + +[carlaserverhlink]: ../Util/CarlaServer/include/carla/carla_server.h + +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. diff --git a/Docs/how_to_build_on_linux.md b/Docs/how_to_build_on_linux.md index 10075394b..bbdec3e7c 100644 --- a/Docs/how_to_build_on_linux.md +++ b/Docs/how_to_build_on_linux.md @@ -45,15 +45,16 @@ Setup CARLA plugin ------------------ Go to "CARLAUE4/Plugins/Carla" folder and run the setup script. This downloads -and compile all the dependencies, takes a while but you only need to do this -once +and compile all the dependencies, takes a while $ ./Setup.sh Now you can use the Makefile to compile and test the code. However, the rebuild script of the main project will do that already, see next section. -It is recommended to do a check to see if everything worked fine +You can run the unit tests to check if everything worked fine (note that these +tests launch the python client, they require python3 and protobuf for python3 +installed) $ make check diff --git a/Docs/how_to_build_on_windows.md b/Docs/how_to_build_on_windows.md index 1be55c71d..3639ba739 100644 --- a/Docs/how_to_build_on_windows.md +++ b/Docs/how_to_build_on_windows.md @@ -1,10 +1,16 @@ How to build CARLA on Windows ============================= +**Building CARLA on Windows is not yet fully supported. Compilation is tedious +and fails often. We recommend to use the Linux version if possible.** + Install Unreal Engine 4.17 and Visual Studio 2015. (Later versions of Visual Studio work, but you will need to adapt "Rebuild.bat" to find the right "vcvarsall.bat"). +For running Rebuild.bat some Linux utilities are required (like make, cmake, +rm...), it is recommended to install Cygwin or a similar environment. + Setup CARLA plugin ------------------ diff --git a/Docs/img/carlaserver.svg b/Docs/img/carlaserver.svg new file mode 100644 index 000000000..697856dc6 --- /dev/null +++ b/Docs/img/carlaserver.svg @@ -0,0 +1 @@ +EncoderAsync ServerTCP ServerWorld ServerAgent ServerBufferBufferC APIWorld Thread(port 2000)EncoderAsync ServerTCP ServerMeasurements Thread(port 2001)EncoderAsync ServerTCP ServerControl Thread(port 2002)MessageMessage \ No newline at end of file