[config] Updated documentation to new configuration structure (#1690)

Only doc changes. New yaml references and config settings in code snippets.

Issue link for current documentation checkup:
#1672

doc/rst/advanced/ecal_in_docker.rst

@@ -213,9 +213,9 @@ In eCAL, you are able to set host belonging over network borders by utilizing th
 
    * First, open :file:`/etc/ecal/ecal.yaml` from your preferred editor.
 
-   * Search for the line ``network_enabled`` and set it to ``true``.
+   * Search for the line ``registration->network_enabled`` and set it to ``true``.
 
-   * Search for the line ``host_group_name`` and write your preferred name.
+   * Search for the line ``registration->host_group_name`` and write your preferred name.
 
    * Save and close the :file:`ecal.yaml` file.
 

doc/rst/advanced/layers/shm.rst

@@ -51,16 +51,20 @@ To support one to many publisher/subscriber connections, the publisher creates o
 Configuration
 =============
 
-The SHM Layer is set to ``auto`` (= 2) by default.
-This means, that it is used automatically for all messages that need to be transmitted inside a single host.
+The SHM Layer is set to ``enable`` by default.
 
 The system-configuration-parameters in the :file:`ecal.yaml` are:
 
-.. code-block:: ini
-
-   [publisher]
-   use_shm                   = 2
+.. code-block:: yaml
 
+  # Publisher specific base settings
+  publisher:
+    layer:
+    # Base configuration for shared memory publisher
+      shm:
+        # Enable layer
+        enable: true
+        [..]
 
 There are a few options for tweaking the communication.
 Those options are explained below.
@@ -78,11 +82,18 @@ This event is signaled by a subscriber back to the sending publisher to confirm
 
 The handshake mechanism can be activated in the :file:`ecal.yaml`:
 
-.. code-block:: ini
+.. code-block:: yaml
 
-   [publisher]
-   ; activate synchronization via memory transfer acknowledge signal with a timeout of 100 milliseconds
-   memfile_ack_timeout = 100
+  # Publisher specific base settings
+  publisher:
+    layer:
+    # Base configuration for shared memory publisher
+      shm:
+        [..]
+        # Force connected subscribers to send acknowledge event after processing the message.
+        # The publisher send call is blocked on this event with this timeout (0 == no handshake).
+        acknowledge_timeout_ms: 5
+        [..]
 
 If the parameter is set to a non-zero timeout, the publisher will create an additional event and inform the subscriber to fire this event when the transmission of the payload is completed.
 
@@ -149,22 +160,38 @@ You can activate the feature in the following ways.
 
   Edit your :file:`ecal.yaml` and set a buffer count greater than 1:
 
-  .. code-block:: ini
+  .. code-block:: yaml
      
-     [publisher]
-     memfile_buffer_count      = 3
+    # Publisher specific base settings
+    publisher:
+      layer:
+      # Base configuration for shared memory publisher
+        shm:
+          [..]
+          # Maximum number of used buffers (needs to be greater than 0, default = 1)
+          memfile_buffer_count: 3
 
 - **Use multi-buffering for a single publisher (from your code):**
 
   Multibuffering can be enabled for a specific publisher using this ``CPublisher`` `API function <https://eclipse-ecal.github.io/ecal/_api/classeCAL_1_1CPublisher.html#_CPPv4N4eCAL10CPublisher17ShmSetBufferCountEl>`_:
 
   .. code-block:: cpp
       
-     // Create a publisher (topic name "person")
-     eCAL::protobuf::CPublisher<pb::People::Person> pub("person");
+     #include <ecal/config/publisher.h>
+
+    ...
+
+    // Create a publisher configuration object
+    eCAL::Publisher::Configuration pub_config;
+
+    // Set the option for buffer count in layer->shm->memfile_buffer_count to 3, so it will create 3 SHM files
+    pub_config.layer.shm.memfile_buffer_count = 3;
+
+    // Create a publisher (topic name "person") and pass the configuration object
+    eCAL::protobuf::CPublisher<pb::People::Person> pub("person", pub_config);
+
+    ...
 
-     // Set multi-buffering to 3, so it will create 3 SHM files
-     pub.ShmSetBufferCount(3);
 
 Combining the zero-copy feature with an increased number of memory buffer files (like 2 or 3) could be a nice setup allowing the subscriber to work on the memory file content without copying its content and nevertheless not blocking the publisher to write new data.
 Using Multibuffering however will force each Send operation to re-write the entire memory file and disable partial updates.

doc/rst/advanced/layers/shm_zerocopy.rst

@@ -22,22 +22,38 @@ Enabling eCAL Zero Copy
 
   Zero Copy can be enabled as system default from the :file:`ecal.yaml` file like follows:
 
-  .. code-block:: ini
+  .. code-block:: yaml
+
+    # Publisher specific base settings
+    publisher:
+      layer:
+      # Base configuration for shared memory publisher
+        shm:
+          [..]
+          # Enable zero copy shared memory transport mode
+          zero_copy_mode: true
 
-     [publisher]
-     memfile_zero_copy = 1
 
 - **Use zero-copy for a single publisher (from your code):**
 
-  Zero-copy can be activated (or deactivated) for a single publisher from the eCAL API:
+  Zero-copy can be activated (or deactivated) for a single publisher by using a specific publisher configuration:
 
   .. code-block:: cpp
+    
+    #include <ecal/config/publisher.h>
+
+    ...
+
+    // Create a publisher configuration object
+    eCAL::Publisher::Configuration pub_config;
+
+    // Set the option for zero copy mode in layer->shm->zero_copy_mode to true
+    pub_config.layer.shm.zero_copy_mode = true;
 
-     // Create a publisher (topic name "person")
-     eCAL::protobuf::CPublisher<pb::People::Person> pub("person");
+    // Create a publisher (topic name "person") and pass the configuration object
+    eCAL::protobuf::CPublisher<pb::People::Person> pub("person", pub_config);
 
-     // Enable zero-copy for this publisher
-     pub.ShmEnableZeroCopy(true);
+    ...
 
   Keep in mind, that using protobuf for serialization will still:
 
@@ -292,16 +308,21 @@ To send this payload you just need a few lines of code:
 
 .. code-block:: cpp
 
+  #include <ecal/config/publisher.h>
+
   int main(int argc, char** argv)
   {
     // initialize eCAL API
     eCAL::Initialize(argc, argv, "binary_payload_snd");
 
-    // publisher for topic "simple_struct"
-    eCAL::CPublisher pub("simple_struct");
+    // Create a publisher configuration object
+    eCAL::Publisher::Configuration pub_config;
 
-    // turn zero copy mode on
-    pub.ShmEnableZeroCopy(true);
+    // Set the option for zero copy mode in layer->shm->zero_copy_mode to true
+    pub_config.layer.shm.zero_copy_mode = true;
+
+    // publisher for topic "simple_struct"
+    eCAL::CPublisher pub("simple_struct", pub_config);
 
     // create the simple struct payload
     CStructPayload struct_payload;
@@ -369,6 +390,6 @@ Default eCAL SHM vs. Full Zero Copy SHM
 Combining Zero Copy and Multibuffering
 ======================================
 
-For technical reasons the Full Zero Copy mode described above is turned of if the Multibuffering option ``CPublisher::ShmSetBufferCount`` is activated. 
+For technical reasons the Full Zero Copy mode described above is turned off if the Multibuffering option ``CPublisher::ShmSetBufferCount`` is activated. 
 
 Default (subscriber side) Zero Copy is working in combination with Multibuffering as described.

doc/rst/advanced/layers/tcp.rst

@@ -65,11 +65,26 @@ You can activate TCP in the following ways:
 
    Modify the :file:`ecal.yaml` and change the following:
 
-   .. code-block:: ini
-
-      [publisher]
-      use_tcp                   = 2
-      use_udp_mc                = 0
+   .. code-block:: yaml
+
+    # Publisher specific base settings
+    publisher:
+      layer:
+      # Base configuration for shared memory publisher
+        shm:
+          # Enable layer
+          enable: true
+          [..]
+        
+        # Base configuration for UDP publisher
+        udp:
+          # Enable layer
+          enable: false
+            
+        # Base configuration for TCP publisher
+        tcp:
+          # Enable layer
+          enable: true 
    
    This will
 
@@ -88,19 +103,27 @@ You can activate TCP in the following ways:
 
    .. code-block:: cpp
 
-      // Create a publisher (topic name "person")
-      eCAL::protobuf::CPublisher<pb::People::Person> pub("person");
+      #include <ecal/config/publisher.h>
+
+      ...
 
-      // Switch UDP Multicast layer off
-      pub.SetLayerMode(eCAL::TLayer::tlayer_udp_mc, eCAL::TLayer::smode_off);
+      // Create a publisher configuration object
+      eCAL::Publisher::Configuration pub_config;
+
+      // Set enable shm and tcp, disable udp layer
+      pub_config.layer.shm.enable = true;
+      pub_config.layer.udp.enable = false;
+      pub_config.layer.tcp.enable = true;
+
+      // Create a publisher (topic name "person") and pass the configuration object
+      eCAL::protobuf::CPublisher<pb::People::Person> pub("person");
 
-      // Switch TCP layer on for Network connections (-> smode_uto)
-      pub.SetLayerMode(eCAL::TLayer::tlayer_tcp, eCAL::TLayer::smode_auto);
+      ...
 
 
    .. seealso:: 
 
       Also see the ``person_snd_tcp`` sample:
 
-      https://github.com/eclipse-ecal/ecal/tree/master/samples/cpp/pubsub/protobuf/person_snd_tcp
+      https://github.com/eclipse-ecal/ecal/tree/master/ecal/samples/cpp/pubsub/protobuf/person_snd_tcp
 

doc/rst/configuration/cloud.rst

@@ -11,11 +11,26 @@ To switch eCAL to cloud mode, edit your :file:`ecal.yaml` and change the followi
 * |fa-windows| Windows: |ecalini-path-windows|
 * |fa-ubuntu| Ubuntu: |ecalini-path-ubuntu|
 
-.. code-block:: ini
-
-   [network]
-   network_enabled           = true
-   multicast_ttl             = 2
+.. code-block:: yaml
+
+  # Registration layer configuration
+  registration:
+    [..]
+    # true  = all eCAL components communicate over network boundaries
+    # false = local host only communication (Default: false)
+    network_enabled: true
+
+  [..]
+  
+  # Transport layer configuration
+  transport_layer:
+    udp:
+      [..]
+
+      network:
+        [..] 
+        # TTL (hop limit) is used to determine the amount of routers being traversed towards the destination
+        ttl: 3
 
 .. important::
    Don't forget to set your multicast routes and make sure your hostname resolution works on all machines!

doc/rst/configuration/local.rst

@@ -6,7 +6,7 @@
 Local configuration
 ===================
 
-Using eCAL in local mode can be benefitial
+Using eCAL in local mode can be beneficial
 
 * to avoid network congestion if the data is not needed on other machines
 * to make eCAL work in VPN and Firewall scenarios where non-local traffic is blocked
@@ -16,11 +16,26 @@ To switch eCAL to local mode, edit your :file:`ecal.yaml` and change the followi
 * |fa-windows| Windows: |ecalini-path-windows|
 * |fa-ubuntu| Ubuntu: |ecalini-path-ubuntu|
 
-.. code-block:: ini
+.. code-block:: yaml
 
-   [network]
-   network_enabled           = false
-   multicast_ttl             = 0
+  # Registration layer configuration
+  registration:
+    [..]
+    # true  = all eCAL components communicate over network boundaries
+    # false = local host only communication (Default: false)
+    network_enabled: false
+
+  [..]
+
+  # Transport layer configuration
+  transport_layer:
+    udp:
+      [..]
+
+      network:
+        [..] 
+        # TTL (hop limit) is used to determine the amount of routers being traversed towards the destination
+        ttl: 0
 
 .. seealso::
    To learn about the differences between local mode and cloud mode, check out :ref:`this table <getting_started_cloud_local_mode_vs_cloud_mode>`.

doc/rst/configuration/npcap.rst

@@ -39,9 +39,14 @@ How to use Npcap
 
 #. Edit |ecalini-path-windows|:
 
-   .. code-block:: ini
+   .. code-block:: yaml
       
-      npcap_enabled = true
+      # Transport layer configuration
+      transport_layer:
+        udp:
+         [..]
+          # Windows specific setting to enable receiving UDP traffic with the Npcap based receiver
+          npcap_enabled: true
     
 #. Check eCAL Mon