From 9e8ecbbe2e0f30e05b2f492d4b2fb3f11bfb7e7e Mon Sep 17 00:00:00 2001 From: Peguen <73380451+Peguen@users.noreply.github.com> Date: Mon, 5 Aug 2024 08:22:09 +0200 Subject: [PATCH] [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: https://github.com/eclipse-ecal/ecal/issues/1672 --- doc/rst/advanced/ecal_in_docker.rst | 4 +- doc/rst/advanced/layers/shm.rst | 61 +- doc/rst/advanced/layers/shm_zerocopy.rst | 47 +- doc/rst/advanced/layers/tcp.rst | 47 +- doc/rst/configuration/cloud.rst | 25 +- doc/rst/configuration/local.rst | 25 +- doc/rst/configuration/npcap.rst | 9 +- doc/rst/configuration/options.rst | 604 ++++++++++++------ .../configuration/runtime_configuration.rst | 8 +- .../configuration/src/hello_config/main.cpp | 14 +- .../src/publisher_config/main.cpp | 8 +- doc/rst/getting_started/cloud.rst | 28 +- 12 files changed, 610 insertions(+), 270 deletions(-) diff --git a/doc/rst/advanced/ecal_in_docker.rst b/doc/rst/advanced/ecal_in_docker.rst index d97594b6bd..0b03698740 100644 --- a/doc/rst/advanced/ecal_in_docker.rst +++ b/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. diff --git a/doc/rst/advanced/layers/shm.rst b/doc/rst/advanced/layers/shm.rst index 6341fa0510..5ad1e038e9 100644 --- a/doc/rst/advanced/layers/shm.rst +++ b/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,10 +160,16 @@ 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):** @@ -160,11 +177,21 @@ You can activate the feature in the following ways. .. code-block:: cpp - // Create a publisher (topic name "person") - eCAL::protobuf::CPublisher pub("person"); + #include + + ... + + // 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 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. \ No newline at end of file diff --git a/doc/rst/advanced/layers/shm_zerocopy.rst b/doc/rst/advanced/layers/shm_zerocopy.rst index d2e374db53..20d922d5c6 100644 --- a/doc/rst/advanced/layers/shm_zerocopy.rst +++ b/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 + + ... + + // 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 pub("person"); + // Create a publisher (topic name "person") and pass the configuration object + eCAL::protobuf::CPublisher 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 + 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. diff --git a/doc/rst/advanced/layers/tcp.rst b/doc/rst/advanced/layers/tcp.rst index 518c8f9167..b284f69ccb 100644 --- a/doc/rst/advanced/layers/tcp.rst +++ b/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 pub("person"); + #include + + ... - // 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 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 diff --git a/doc/rst/configuration/cloud.rst b/doc/rst/configuration/cloud.rst index 7ff2d546ce..de431e11b0 100644 --- a/doc/rst/configuration/cloud.rst +++ b/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! diff --git a/doc/rst/configuration/local.rst b/doc/rst/configuration/local.rst index b413868781..4d2b1632ef 100644 --- a/doc/rst/configuration/local.rst +++ b/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 `. \ No newline at end of file diff --git a/doc/rst/configuration/npcap.rst b/doc/rst/configuration/npcap.rst index f2d493ceb4..377f880682 100644 --- a/doc/rst/configuration/npcap.rst +++ b/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 diff --git a/doc/rst/configuration/options.rst b/doc/rst/configuration/options.rst index 07e5789610..35689decdd 100644 --- a/doc/rst/configuration/options.rst +++ b/doc/rst/configuration/options.rst @@ -39,254 +39,474 @@ In addition, some eCAL applications support providing a path from the command li If you are compiling eCAL yourself and don't provide the SYSCONFDIR, CMake will usually use ``/usr/local/etc/ecal/ecal.yaml``. ecal.yaml options -================ +================= -[network] ---------- +Registration settings are listed in the section ``registration`` +---------------------------------------------------------------- -The network setting drive how and which ... +.. option:: registration -.. option:: network_enabled + .. option:: registration_refresh - ``true`` / ``false``, default: ``true`` - - ``true`` = all eCAL components communicate over network boundaries - - ``false`` = local host only communication - -.. option:: multicast_config_version + ``< registration_timeout/2``, default ``1000`` - ``v1`` / ``v2``, default: ``v1`` + topic registration refresh cycle (has to be smaller than registration timeout!) - UDP configuration version (Since eCAL 5.12.) - - ``v1`` = default behavior + .. option:: registration_timeout + + ``1000 + (x * 1000)``, default ``60000`` - ``v2`` = new behavior, comes with a bit more intuitive handling regarding masking of the groups + timeout for topic registration in ms -.. option:: multicast_group + .. option:: loopback - IPV4 Adress, default ``239.0.0.1`` + ``true`` / ``false``, default ``true`` + + enable to receive registration information on the same local machine - UDP multicast group base. All registration and logging information is sent on this address. + .. option:: host_group_name -.. option:: multicast_mask + ````, default ``""`` - ``v1`` **behavior:** - - ``0.0.0.1``-``0.0.0.255`` + host group name that enables interprocess mechanisms across (virtual) host borders (e.g. Docker); + by default equivalent to local host name - Mask maximum number of dynamic multicast group + .. option:: network_enabled - ``v2`` **behavior:** - - ``255.0.0.0``-``255.255.255.255`` - - Mask for the multicast group. Topic traffic may be set on any of the unmasked addresses. - - With ``multicast_group``: ``239.0.0.1`` and ``multicast_mask``: ``255.255.255.0``, topic traffic will be sent on addresses ``239.0.0.0``-``239.0.0.255``. - -.. option:: multicast_port - - ``14000 + x`` + ``true`` / ``false``, default: ``true`` + + ``true`` = all eCAL components communicate over network boundaries + + ``false`` = local host only communication - UDP multicast port number (eCAL will use at least the 2 following port numbers too, so please modify in steps of 10 (e.g. 1010, 1020 ...) + .. option:: layer -.. option:: multicast_ttl - - ``0 + x`` - - UDP ttl value, also known as hop limit, is used in determining the intermediate routers being traversed towards the destination + .. option:: shm + + .. option:: enabled -.. option:: multicast_sndbuf - - ``1024 * x`` - - UDP send buffer in bytes + ``true`` / ``false``, default: ``false`` -.. option:: multicast_rcvbuf - - ``1024 * x`` + enable shared memory layer - UDP receive buffer in bytes + .. option:: domain -.. option:: bandwidth_max_udp - - ``1048576`` - - UDP bandwidth limit for eCAL udp layer (-1 == unlimited) + ``ecal_mon`` -.. option:: shm_rec_enabled + Domain name for shared momory based registration - ``true`` + .. option:: queue_size - Enable to receive on eCAL shared memory layer + ``1024`` -.. option:: udp_mc_rec_enabled - - ``true`` + Queue size of registration events - Enable to receive on eCAL udp multicast layer + .. option:: udp + + .. option:: enabled + + ``true`` / ``false``, default: ``true`` + + enable UDP multicast layer + + .. option:: port + + ``14000 + x`` + + UDP port for registration information if UDP is enabled + + +Monitoring settings are listed in the section ``monitoring`` +---------------------------------------------------------- + +.. option:: monitoring + + .. option:: timeout + + ``1000 + (x * 1000)`` default ``1000`` + Timeout for topic monitoring in ms + If no additional registration information for the topic has be received in that time period, topics will no longer be shown in eCAL Monitor. + + + .. option:: filter_excl + + topics blacklist as regular expression (will not be monitored) + Per default includes all eCAL internal topics. + + default = ``^__.*$`` + + .. option:: filter_incl + + topics whitelist as regular expression (will be monitored only) + + default = `` `` + + +Transportlayer settings are listed in the section ``transport_layer`` +--------------------------------------------------------------------- + +.. option:: transport_layer + + .. option:: udp + + .. option:: config_version + + ``v1`` / ``v2``, default: ``v2`` + + UDP configuration version (Since eCAL 5.12.) + + ``v1`` = default behavior + + ``v2`` = new behavior, comes with a bit more intuitive handling regarding masking of the groups + + .. option:: mode + + ``local`` / ``network``, default: ``local`` + + ``local`` = use local network settings - not configurable by the user + + ``network`` = use network settings - configurable by the user + + .. option:: port + + ``14000 + x`` + + UDP multicast port number + + .. option:: mask + + ``v1`` **behavior:** + + ``0.0.0.1``-``0.0.0.255`` + + Mask maximum number of dynamic multicast group + + ``v2`` **behavior:** + + ``255.0.0.0``-``255.255.255.255`` + + Mask for the multicast group. Topic traffic may be set on any of the unmasked addresses. + + With ``group``: ``239.0.0.1`` and ``mask``: ``255.255.255.0``, topic traffic will be sent on addresses ``239.0.0.0``-``239.0.0.255``. + + .. option:: send_buffer + + ``1024 * x`` default ``5242880`` + + UDP send buffer in bytes + + .. option:: receive_buffer + + ``1024 * x`` default ``5242880`` + + UDP receive buffer in bytes + + .. option:: join_all_interfaces + + ``true`` / ``false`` default ``false`` + + Linux specific setting to join all network interfaces independend of their link state. + Enabling ensures that eCAL processes receive data when they are started before the + network devices are up and running. + + .. option:: npcap_enabled + + ``true`` / ``false`` default ``false`` + + Enable to receive UDP traffic with the Npcap based receiver + + .. option:: local + + In local mode the UDP multicast group is set to the local host address ("127.0.0.1") and the multicast TTL is set to 0 by default. + This is not configurable. + + .. option:: network + + .. option:: group + + ``xxx.xxx.xxx.xxx`` IP address as text, default ``239.0.0.1`` + + Multicast group base: all registration and logging is sent on this address + + .. option:: ttl + + ``0 + x`` default ``3`` + + TTL (hop limit) is used to determine the amount of routers being traversed towards the destination + + .. option:: tcp + + .. option:: number_executor_reader + + ``1 + x`` default ``1`` + + Number of reader threads that shall execute workload + + .. option:: number_executor_writer + + ``1 + x`` default ``1`` + + Number of writer threads that shall execute workload + + .. option:: max_reconnections + + ``1 + x`` default ``1`` + + Reconnection attemps the session will try to reconnect in case of an issue + + .. option:: shm + + .. option:: memfile_min_size_bytes + + ``x * 4096 kB`` default ``4096`` + + Default memory file size for new publisher + + + .. option:: memfile_reserve_percent + + ``20 .. x`` default ``50`` + + Dynamic file size reserve before recreating memory file if topic size changes + + +Publisher settings are listed in the section ``publisher`` +---------------------------------------------------------- + +.. option:: publisher + + .. option:: layer + + .. option:: shm -.. option:: npcap_enabled - - ``false`` - - Enable to receive UDP traffic with the Npcap based receiver + .. option:: enable + ``true`` / ``false`` default ``true`` -[common] --------- + Enable shared memory layer -.. option:: registration_timeout - - ``1000 + (x * 1000)``, default ``60000`` + .. option:: zero_copy_mode - timeout for topic registration in ms + ``true`` / ``false`` default ``false`` -.. option:: registration_refresh + Enable zero copy mode for shared memory transport mode - ``< registration_timeout/2``, default ``1000`` + .. option:: acknowledge_timeout_ms - topic registration refresh cylce (has to be smaller then registration timeout !) + ``0 + x`` default ``0`` + 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). -[time] ------- + .. option:: memfile_buffer_count -.. option:: timesync_module_rt - - default: ``"ecaltime-localtime"`` - - module (dll / so) name time sync interface. The name will be extended with debug suffix (d) and platform extension (.dll|.so) + ``1 + x`` default ``1`` - Available modules are: - - - ecaltime-localtime local system time without synchronization - - ecaltime-linuxptp For PTP / gPTP synchronization over ethernet on Linux (device configuration in ecaltime.ini) - - ecaltime-simtime Simulation time as published by the eCAL Player. + Maximum number of used buffers (needs to be greater than 0, default = 1) -[process] ---------- + .. option:: udp + + .. option:: enable + + ``true`` / ``false`` default ``true`` + + Enable UDP multicast layer + + .. option:: tcp + + .. option:: enable + + ``true`` / ``false`` default ``false`` + + Enable TCP layer + + .. option:: share_topic_type + + ``true`` / ``false`` default ``true`` + + Share topic type via registration layer + + + + .. option:: share_topic_description + + ``true`` / ``false`` default ``true`` + + Share topic description via registration layer. + If set to false, reflection is completely disabled. It is not possible then to monitor the content of messages in the eCAL Monitor. + + .. option:: priority_local + + ``["shm", "udp", "tcp"]`` default ``["shm", "udp", "tcp"]`` + + A list of transport layers as text that specifies the prioritized layer for local communication. + + .. option:: priority_remote + + ``["udp", "tcp"]`` default ``["udp", "tcp"]`` + + A list of transport layers as text that specifies the prioritized layer for remote communication. + + +Subscriber settings are listed in the section ``subscriber`` +------------------------------------------------------------ + +.. option:: subscriber + + .. option:: layer + + .. option:: shm + + .. option:: enable + + ``true`` / ``false`` default ``true`` + + Enable shared memory layer + + .. option:: udp + + .. option:: enable + + ``true`` / ``false`` default ``true`` + + Enable UDP multicast layer + + .. option:: tcp + + .. option:: enable + + ``true`` / ``false`` default ``false`` + + Enable TCP layer -.. _ecalini_option_terminal_emulator: + .. option:: drop_out_of_order_messages -.. option:: terminal_emulator - - default: ``""`` + ``true`` / ``false`` default ``false`` + + Enable dropping of payload messages that arrive out of order - command for starting applications with an external terminal emulator. - If empty, the command will be ignored. - Ignored on Windows. - - e.g: - - ``/usr/bin/x-terminal-emulator -e`` - - ``/usr/bin/gnome-terminal -x`` - - ``/usr/bin/xterm -e`` +Time settings are listed in the section ``time`` +------------------------------------------------ -[publisher] ------------ - -.. option:: use_shm - - use shared memory transport layer - - - 0 = off - - 1 = on - - 2 = auto - - default = 2 - -.. option:: use_udp_mc - - use udp multicast transport layer - - - 0 = off - - 1 = on - - 2 = auto - - default = 2 - +.. option:: time + .. option:: rt + + default: ``"ecaltime-localtime"`` + + Module (dll / so) name time sync interface. The name will be extended with debug suffix (d) and platform extension (.dll|.so) -.. option:: memfile_minsize = x * 4096 kB - - default memory file size for new publisher (``x * 4096 kB``) - - default = 4096 + Available modules are: + + - ecaltime-localtime local system time without synchronization + - ecaltime-linuxptp For PTP / gPTP synchronization over ethernet on Linux (device configuration in ecaltime.ini) + - ecaltime-simtime Simulation time as published by the eCAL Player. -.. option:: memfile_reserve + .. option:: replay - dynamic file size reserve before recreating memory file if topic size changes (``20 .. x``) + default ``""`` - default = 50 + Module name of time plugin for replaying -.. option:: memfile_ack_timeout - Publisher timeout for ack event from subscriber that memory file content is processed - - default = 0 +Service settings are listed in the section ``service`` +------------------------------------------------------ -.. option:: share_ttype +.. option:: service - share topic type via registration layer ( ``0, 1``) + .. option:: protocol_v0 + + ``true`` / ``false`` default ``true`` - default = 1 + Support service protocol v0, eCAL 5.11 and older -.. option:: share_tdesc + .. option:: protocol_v1 + + ``true`` / ``false`` default ``false`` - share topic description via registration layer ( ``0, 1``) - If set to 0, reflection is completely disabled. It is not possible then to monitor the content of messages in the eCAL Monitor. - - default = 1 + Support service protocol v1, eCAL 5.12 and newer -[monitoring] ------------- -Monitor settings are listed in the section ``monitoring`` +Application settings are listed in the section ``application`` +-------------------------------------------------------------- -.. option:: timeout +.. option::application + + .. option:: sys + + .. option:: filter_excl + + Text as regex, default ``"^eCALSysClient$|^eCALSysGUI$|^eCALSys$*"`` + + Apps blacklist to be excluded when importing tasks from cloud. + + .. option:: terminal + + .. option:: emulator + + External terminal emulator as text, default ``""`` + + Linux only command for starting applications with an external terminal emulator. + e.g. + /usr/bin/x-terminal-emulator -e + /usr/bin/gnome-terminal -x + /usr/bin/xterm -e + + If empty, the command will be ignored. + + +Logging settings are listed in the section ``logging`` +------------------------------------------------------ + +.. option:: logging + + .. option:: sinks + + Log levels are: "info", "warning", "error", "fatal", "debug1", "debug2", "debug3", "debug4" + + .. option:: console + + .. option:: enable - timeout for topic monitoring in ms (``1000 + (x * 1000)``) - If no additional registration information for the topic has be received in that time period, topics will no longer be shown in eCAL Monitor. - - default = 5000 - -.. option:: filter_excl - - topics blacklist as regular expression (will not be monitored) - Per default includes all eCAL internal topics. - - default = ``^__.*$`` - -.. option:: filter_incl - - topics whitelist as regular expression (will be monitored only) - - default = `` `` - -.. option:: filter_log_con - - log messages to console (all, info, warning, error, fatal, debug1, debug2, debug3, debug4) - - default = ``error, fatal`` - -.. option:: filter_log_file - - log messages to log file - - default = ``error, fatal`` - -.. option:: filter_log_udp - - log messages to udp bus - - default = ``info, warning, error, fatal`` - -[sys] ------ - -.. option:: filter_excl - - Apps blacklist to be excluded when importing tasks from cloud. + ``true`` / ``false`` default ``false`` + + Enable console logging + + .. option:: level + + List of log levels as text, default ``["info", "warning", "error", "fatal"]`` + + .. option:: file + + .. option:: enable + + ``true`` / ``false`` default ``false`` + + Enable file logging + + .. option:: level + + List of log levels as text, default ``[]`` + + .. option:: path + + Path as text, default ``ecal.log`` + + .. option:: udp + + .. option:: enable + + ``true`` / ``false`` default ``false`` + + Enable udp logging + + .. option:: level + + List of log levels as text, default ``["info", "warning", "error", "fatal"]`` + + .. option:: port + + ``14000 + x`` default ``14001`` + + UDP port for logging information diff --git a/doc/rst/configuration/runtime_configuration.rst b/doc/rst/configuration/runtime_configuration.rst index 5c62120e76..f8d8ed6b95 100644 --- a/doc/rst/configuration/runtime_configuration.rst +++ b/doc/rst/configuration/runtime_configuration.rst @@ -12,7 +12,7 @@ The corresponding structure reflects the configuration file (:ref:`configuration Custom types ============ -In order to rule out configuration errors, custom datatypes for IP addresses (IpAddressV4) and sizes (constrained integer) are introduced. +In order to rule out configuration errors, custom datatypes for IP addresses (IpAddressV4) and sizes (ConstrainedInteger) are introduced. **IpAddressV4:** For assigning an IP address simply assign a string with the desired address. Decimal and hexadecimal format is supported. @@ -22,7 +22,7 @@ The IP address can be used like a normal string object. For example: .. code-block:: c++ - eCAL::Types::IpAddressV4 ip_address = std::string("192.168.7.1"); // in hex: "C0.A8.7.1" + eCAL::Types::IpAddressV4 ip_address = "192.168.7.1"; // in hex: "C0.A8.7.1" std::cout << ip_address << "\n"; **ConstrainedInteger**: ConstrainedInteger are specified with a minimum (default: 0), step (default: 1) and maximum (default: maximum of int) value. @@ -41,12 +41,12 @@ Global configuration initialization =================================== The configuration will be first initialized with the default values specified by eCAL. -If you want to use the systems eCAL .ini file, call the ``InitConfigWithDefaultIni()`` function of the config object. +If you want to use the systems eCAL .ini file, call the ``InitConfigWithDefaultYaml()`` function of the config object. In case the .ini to use is specified via command line parameter, this one is chosen instead. The object will throw an error, in case the specified .ini file cannot be found. -It is also possible to specify the .ini by calling the function ``InitConfig(std::string _ini_path)`` of the config object. +It is also possible to specify the .ini by calling the function ``checkForValidConfigFilePath(const std::string yaml_path_)`` of the config object. * |fa-file-alt| :file:`hello_config/main.cpp`: diff --git a/doc/rst/configuration/src/hello_config/main.cpp b/doc/rst/configuration/src/hello_config/main.cpp index 68a4967ad1..e35cdc70d7 100644 --- a/doc/rst/configuration/src/hello_config/main.cpp +++ b/doc/rst/configuration/src/hello_config/main.cpp @@ -8,24 +8,24 @@ int main(int argc, char** argv) // Create a configuration object with the command line arguments eCAL::Configuration custom_config(argc, argv); - // Use the .ini file of the system if available - custom_config.InitConfigWithDefaultIni(); + // Use the .yaml file of the system if available + custom_config.InitConfigWithDefaultYaml(); // Set the values in a try/catch block, as wrong configuration leads to exceptions try { - // In case you decided to specify an own .ini file to use + // In case you decided to specify an own .yaml file to use // Configuration based on previous ini file will be overwritten - custom_config.InitConfig("C:\\eCAL_local.ini"); + custom_config.InitConfigFromFile("C:\\eCAL_local.yaml"); // Set the communication layer to network - custom_config.transport_layer.network_enabled = true; + custom_config.registration.network_enabled = true; // Set a custom udp multicast group, correct IP address necessary - custom_config.transport_layer.mc_options.group = std::string("239.0.1.1"); + custom_config.transport_layer.udp.network.group = std::string("239.0.1.1"); // Increase the send buffer, size increase in 1024 bytes steps - custom_config.transport_layer.mc_options.sndbuf = (5242880 + 10 * 1024); + custom_config.transport_layer.udp.send_buffer = (5242880 + 10 * 1024); } catch (std::invalid_argument& e) { diff --git a/doc/rst/configuration/src/publisher_config/main.cpp b/doc/rst/configuration/src/publisher_config/main.cpp index c3cea80141..a2bf982cba 100644 --- a/doc/rst/configuration/src/publisher_config/main.cpp +++ b/doc/rst/configuration/src/publisher_config/main.cpp @@ -14,15 +14,15 @@ int main(int argc, char** argv) eCAL::Publisher::Configuration pub_config; // disable all layers except for SHM - pub_config.shm.enable = true; - pub_config.udp.enable = false; - pub_config.tcp.enable = false; + pub_config.layer.shm.enable = true; + pub_config.layer.udp.enable = false; + pub_config.layer.tcp.enable = false; // create publisher 1 eCAL::string::CPublisher pub_1("topic_1", pub_config); // enable for the second publisher also tcp - pub_config.tcp.enable = true; + pub_config.layer.tcp.enable = true; // create publisher 2 eCAL::string::CPublisher pub_2("topic_2", pub_config); diff --git a/doc/rst/getting_started/cloud.rst b/doc/rst/getting_started/cloud.rst index d2168e1aff..7ab97d84eb 100644 --- a/doc/rst/getting_started/cloud.rst +++ b/doc/rst/getting_started/cloud.rst @@ -47,13 +47,27 @@ 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 - -The ``multicast_ttl`` setting configures the *time to live* of the UDP datagrams, i.e. the number of hops a datagram can take before it is discarded. +.. 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: 2 + +The ``transport_layer->udp->network->ttl`` setting configures the *time to live* of the UDP datagrams, i.e. the number of hops a datagram can take before it is discarded. Usually, ``2`` is sufficient, but if you have a network with many routers, you may have to increase that number. .. seealso::