MindConnect Library – Migrating from 3.x to 4.x¶

With the release of MCL 4.x, support for MCL 3.x will continue but new features will be added to MCL 4.x only. Developers using MCL 3.x are encouraged to migrate to MCL 4.x.

The architecture of MCL is changed due to the plans to extend MCL with independent set of features. With MCL 4.x, the library is now designed as a core component and extensions to the core component. All functionality of MCL 3.x is delivered with the connectivity component together with the core component in MCL 4.x.

Separate binaries are generated for each component in MCL 4.x instead of a single binary in MCL 3.x. All functionality provided with MCL 3.x can be fulfilled with MCL 4.x by including mcl_connectivity.h header in a custom agent application.

In MCL 3.x, functions returned error codes with E_MCL_ERROR_CODE enumeration. In MCL 4.x, functions return new type mcl_error_t.

Configuration¶

With MCL 3.x, mcl_configuration_initialize() function was used to initialize a configuration structure and then the parameters of the configuration structure were set directly.

Code snippet below shows typical usage with MCL 3.x:

mcl_configuration_t *configuration = NULL;
mcl_configuration_initialize(&configuration);
configuration->mindsphere_hostname = "https://southgate.eu1.mindsphere.io";
configuration->mindsphere_port = 443;
...

With MCL 4.x, since there is a core component and a connectivity component, users need to initialize a configuration for the core component and a separate configuration for the connectivity component.

Configuration structure for the core component can be initialized using mcl_core_configuration_initialize() function. Instead of directly setting the parameters of the configuration, users will use mcl_core_configuration_set_parameter() function to set each parameter of the configuration. Parameters are enumerated in E_MCL_CORE_CONFIGURATION_PARAMETER.

Similarly, configuration structure for the connectivity component can be initialized using mcl_connectivity_configuration_initialize() function. Users will use mcl_connectivity_configuration_set_parameter() function to set each parameter of the configuration. Parameters are enumerated in E_MCL_CONNECTIVITY_CONFIGURATION_PARAMETER.

Code snippet below shows typical usage with MCL 4.x:

mcl_core_configuration_t *core_configuration = NULL;
mcl_uint16_t mindsphere_port = 443;

mcl_core_configuration_set_parameter(core_configuration, MCL_CORE_CONFIGURATION_PARAMETER_MDSP_HOST, "https://southgate.eu1.mindsphere.io");
mcl_core_configuration_set_parameter(core_configuration, MCL_CORE_CONFIGURATION_PARAMETER_MDSP_PORT, &mindsphere_port);
...

mcl_connectivity_configuration_t *connectivity_configuration = NULL;
mcl_size_t maximum_payload_size = 65536;

mcl_connectivity_configuration_initialize(&connectivity_configuration);
mcl_connectivity_configuration_set_parameter(connectivity_configuration, MCL_CONNECTIVITY_CONFIGURATION_PARAMETER_MAX_HTTP_PAYLOAD_SIZE, &maximum_payload_size);
...

Note that, store_path parameter no longer exists in configuration structure. Users are encouraged to use callbacks for loading and saving registration credentials.

Insights Hub certificate was provided as character string in MCL 3.x. With MCL 4.x, users also have the option to provide it as a file.

Communication¶

With MCL 3.x, mcl_communication_initialize() function was used to initialize a communication structure by passing the configuration structure to it.

Code snippet below shows typical usage with MCL 3.x:

mcl_configuration_t *configuration = NULL;
...

mcl_communication_initialize(configuration, &communication);

With MCL 4.x, instead of initializing a communication structure, core component will be initialized using mcl_core_initialize() function by passing the core configuration structure to it.

Similarly, connectivity component will be initialized using mcl_connectivity_initialize() function by passing the connectivity configuration structure to it.

Code snippet below shows typical usage with MCL 4.x:

mcl_core_configuration_t *core_configuration = NULL;
...

mcl_core_t *core = NULL;
mcl_core_initialize(core_configuration, &core);
...

mcl_connectivity_configuration_t *connectivity_configuration = NULL;
...

mcl_connectivity_t *connectivity = NULL;
mcl_connectivity_initialize(connectivity_configuration, &connectivity);
...

Onboarding, Key Rotation, Access Token Retrieval¶

With MCL 3.x, mcl_communication_onboard(), mcl_communication_rotate_key() and mcl_communication_get_access_token() functions were used to onboard, rotate key and get access token respectively.

With MCL 4.x, mcl_core_onboard(), mcl_core_rotate_key() and mcl_core_get_access_token() functions will be used instead.

Exchange¶

With MCL 3.x, mcl_communication_exchange() function were used to exchange data in a store. It was not possible to exchange data items individually. With MCL 4.x, mcl_connectivity_exchange() function will be used to exchange either individual data items or items in store.

There are changes in the way data items are created. With MCL 3.x, parameters of items were passed to the initialization functions. With MCL 4.x, initialization functions will allocate data structures for items and set default parameters. Separate functions will be used to set parameters of items.

For example, with MCL 3.x, mcl_store_new_timeseries() function was called to initialize a timeseries item in a store and all the parameters of the timeseries were passed to this function. With MCL 4.x, mcl_timeseries_initialize() function will be used to initialize a timeseries and the parameters of timeseries will be set by mcl_timeseries_set_parameter() function. Optionally, timeseries can be added to store using mcl_store_add() function.

The approach used for timeseries exchange will be followed for other data item types as well.

Please check the example agent applications distributed with source code to see the difference in code.

Logging¶

MCL 3.x depended on zflog library for logging. MCL 4.x does not have a dependency to zflog, nor to any other logging library. Users will provide a callback for logging using mcl_log_util_set_callback() function and MCL 4.x will call this callback to log. If a callback is not provided by the user, MCL 4.x will use its default callback which logs to stdout.