Runtime configuration

eCAL provides an interface to access and modify its options before initialization. The corresponding structure reflects the configuration file (ecal.ini).

Custom types

In order to rule out configuration errors, custom datatypes for IP addresses (IpAddressV4) and sizes (constrained integer) are introduced.

IpAddressV4: For assigning an IP address simply assign a string with the desired address. Decimal and hexadecimal format is supported. In case the IP address is not valid, the type will throw a std::invalid_argument exception.

The IP address can be used like a normal string object. For example:

eCAL::Types::IpAddressV4 ip_address = std::string("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. In case the assigned value does not fit into the specified limitation, the type will throw a std::invalid_argument exception.

The size object can be used like a normal integer.

eCAL::Types::ConstrainedInteger<1024, 512, 8192> size_4mb = 1024 + 6 * 512;
std::cout << size_4mb << "\n";

For specifying sizes in the ecal configuration object, refer to the .ini file or “ecal/config/configuration.h” for the limitations.

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.

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.

• |fa-file-alt| hello_config/main.cpp:

  #include <ecal/ecal.h>
  #include <ecal/ecal_config.h>
  #include <string>
  #include <stdexcept>
  
  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();
  
    // 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
        // Configuration based on previous ini file will be overwritten
      custom_config.InitConfig("C:\\eCAL_local.ini");
  
      // Set the communication layer to network
      custom_config.transport_layer.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");
  
      // Increase the send buffer, size increase in 1024 bytes steps
      custom_config.transport_layer.mc_options.sndbuf = (5242880 + 10 * 1024);
    }
    catch (std::invalid_argument& e)
    {
      throw std::runtime_error("Error while configuring eCALConfig: " + std::string(e.what()));
    }
  
    // Initialize eCAL with the prepared configuration object
    eCAL::Initialize(custom_config, "UserConfigExample", eCAL::Init::Default);
  
    // ...
    // Use eCAL for your needs
    // ...
  
    // Finalize eCAL API
    eCAL::Finalize();
  
    return 0;
  }
  

Individual publisher/subscriber configuration

Like a global configuration to pass at initialization, it is also possible to create indiviual configurations for publisher and subscriber. That means it is possible to, e.g., create two publisher which send on different transport layers:

• |fa-file-alt| publisher/main.cpp:

  #include <ecal/ecal.h>
  #include <ecal/msg/string/publisher.h>
  #include <string>
  #include <stdexcept>
  #include <thread>
  #include <chrono>
  
  int main(int argc, char** argv)
  {
    // initialize eCAL API
    eCAL::Initialize(0, nullptr, "PublisherConfig", eCAL::Init::All);
  
    // create publisher config
    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;
  
    // create publisher 1
    eCAL::string::CPublisher<std::string> pub_1("topic_1", pub_config);
  
    // enable for the second publisher also tcp
    pub_config.tcp.enable = true;
  
    // create publisher 2
    eCAL::string::CPublisher<std::string> pub_2("topic_2", pub_config);
  
    int counter {0};
    while (eCAL::Ok())
    {
      std::string msg = "Send message number: " + std::to_string(counter++);
      
      // send message
      pub_1.Send(msg);
      pub_2.Send(msg);
  
      std::this_thread::sleep_for(std::chrono::milliseconds(500));
    }
  
    // finalize eCAL API
    eCAL::Finalize();
  }