Skip to content

MindConnect Library - Interfaces and References

If you want to use the MCL in your client application (which collects data and sends them to MindSphere) then you need to include MCL's exported interfaces (header files), which are located in /include/mcl/*.h.

In your client application you only need to include "mcl.h" which internally includes all other required header files.

Most of the MCL functions return an error code which can be used by the client application to react accordingly. The complete list of error codes together with their descriptions can be found in mcl_common.h as well as in doxygen documentation. For error codes returned by a specific function, please see the function reference in doxygen documentation.

The MCL interfaces are divided basically into following modules according to their context. The documentation can be referred to get more information about the parameters of each function.

Module: Configuration

This module can be used to provide MCL various configuration parameters which are used in the initialization phase of MCL.

mcl_configuration_t is a defined struct with following entries:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
typedef struct mcl_configuration_t
{
    char *mindsphere_hostname;
    mcl_uint16_t mindsphere_port;
    char *mindsphere_certificate;
    char *proxy_hostname;
    mcl_uint16_t proxy_port;
    E_MCL_PROXY proxy_type;
    char *proxy_username;
    char *proxy_password;
    char *proxy_domain;
    E_MCL_SECURITY_PROFILE security_profile;
    mcl_size_t max_http_payload_size;
    char *user_agent;
    char *initial_access_token;
    char *tenant;
    char *store_path;
    mcl_load_registration_information_callback_t load_function;
    mcl_save_registration_information_callback_t save_function;
    mcl_enter_critical_section_callback_t enter_critical_section;
    mcl_leave_critical_section_callback_t leave_critical_section;
} mcl_configuration_t;

mindsphere_hostname
Host name of MindSphere provided as baseURL in configuration object obtained using MindSphere Launchpad. This parameter is mandatory.

mindsphere_port
Port number of MindSphere which is typically 443. If not set by the user, port will be set to 443 for an https mindsphere_hostname by default.

mindsphere_certificate
Certificate of MindSphere as a PEM formatted string. This certificate will be used by MCL to verify server identity. Instead of MindSphere certificate, user can also provide the root certificate or the full certificate chain with this parameter since the server identity will be verified in these two cases as well. mindsphere_certificate is an optional parameter and it is NULL by default. In this case, MCL will try to use CA certificate store (provided at build-time of the http client used which is libCurl by default) to verify server identity. MindSphere Root CA Certificate can be found here.

proxy_hostname
Host name of the proxy server if the connection to MindSphere is preferred to be established through a proxy. This is an optional parameter and is NULL by default. If this parameter is NULL, proxy_port, proxy_type, proxy_username, proxy_password, proxy_domain parameters will be ignored by MCL.

proxy_port
Port number of the proxy server. This is a mandatory parameter if proxy_hostname is provided.

proxy_type
Type of the proxy server. This parameter has effect only if proxy_hostname is provided and has a default value of MCL_PROXY_UNKNOWN. Check E_MCL_PROXY type defined in mcl_common.h for available options.

proxy_username
User name used in proxy server. This is an optional parameter (NULL by default) and should have a length of maximum 32 characters.

proxy_password
Password for proxy_username. This is a required parameter only if proxy_username is provided and should have a length of maximum 32 characters.

proxy_domain
Domain for proxy_username. This is an optional parameter and domain with length up to 256 characters is accepted.

security_profile
Security profile for the communication with MindSphere. It can take values either MCL_SECURITY_SHARED_SECRET (default) or MCL_SECURITY_RSA_3072.

max_http_payload_size
Maximum payload size in bytes which will be used for all HTTP requests by MCL. With this parameter, user can adopt the size of HTTP requests to use depending on system limitations. The default value is 16384. Minimum value to set is 400 and maximum value to set is 10485760.

http_request_timeout
Timeout value for HTTP requests in seconds. This is an optional parameter with a default value of 300 seconds.

user_agent
User agent string which will be used in User-Agent header of HTTP requests together with MCL's version string as prefix. It is a mandatory parameter with a length of maximum 256 characters.

tenant
Tenant name on MindSphere. This is a mandatory parameter.

initial_access_token
Initial access token provided in configuration object obtained using MindSphere Launchpad. It is a mandatory parameter for agents which will onboard for the first time. This parameter will be used by MCL only if registration information is not provided by either load_function or store_path parameters.

store_path
Path of the file to load and save registration information. This parameter is an optional parameter with default value NULL.
The parameter will be ignored if both save_function and load_function parameters are set.
If callbacks are set to NULL and store_path parameter is set; file set by store_path parameter will be opened and read to check if registration information exists. If registration information exists, MCL will be initialized as already onboarded. If registration information does not exist, valid initial_access_token will be required to onboard and the registration artifacts will be saved to store_path.
If callbacks are set to NULL, and store_path is also not provided then initial_access_token parameter will be used to onboard but registration artifacts obtained after onboarding will not be saved although the mcl_communication_t handle will be fully operational until it is destroyed. MCL will not return an error in this case but will log the situation with MCL_LOG_UTIL_LEVEL_INFO log level.
Keep in mind that using store_path parameter is an unsecure way to save and load registration artifacts and the user is encouraged provide secure callbacks (load_function and save_function) instead.

load_function
User provided function to be used when loading registration information during initialization of MCL.
This is an optional parameter which is NULL by default. It is used together with save_function parameter. If any one of save_function and load_function is NULL, then both of them will be ignored.
Check mcl_common.h for function signature.
The function is expected to set values for every argument provided to it and return MCL_OK in case of success.
The function is expected to return MCL_REGISTRATION_INFO_IS_NOT_LOADED in case there are no registration information to load and MCL is expected to use initial_access_token parameter to onboard for the first time.
The function is expected to return MCL_FAIL in case of a failure.

save_function
User provided function to save registration information after onboarding.
This is an optional parameter which is NULL by default. It is used together with load_function parameter. If any one of save_function and load_function is NULL, then both of them will be ignored.
Check mcl_common.h for function signature.
The function is expected to return MCL_OK in case of success. The function is expected to return MCL_FAIL in case of failure. If the registration artifacts are not saved, the agent will have to onboard again with a new initial_access_token after the mcl_communication_t handle is destroyed.

enter_critical_section
User provided function which is called internally by MCL when entering the critical section. The critical section in MCL is the section where the registration information (keys, token, etc.) is accessed. This is an optional parameter which is NULL by default. User does not have to set it in case concurrent programming is not a requirement.

leave_critical_section
User provided function which is called internally by MCL when leaving the critical section. The critical section in MCL is the section where the registration information (keys, token, etc.) is accessed. This is an optional parameter which is NULL by default. User does not have to set it in case concurrent programming is not a requirement.

Create an mcl_configuration_t instance using mcl_configuration_initialize function and then assign each parameter. Pass this mcl_configuration_t instance to mcl_communication_initialize function to initialize MCL.

You may destroy mcl_configuration_t instance using mcl_configuration_destroy function once you initialized MCL.

Use of callback functions (load_function and save_function) to save and load registration artifacts are encouraged instead of store_path for security reasons.

Module: Communication

This module can be used to communicate with MindSphere.

You need to call mcl_communication_initialize function passing configuration parameters (mcl_configuration_t) to it to obtain a communication handle of type mcl_communication_t. This handle will be used by other functions in this module.

Every newly created agent on MindSphere needs to be onboarded first using mcl_communication_onboard function before exchanging any data.

Onboarded agents can rotate their keys using mcl_communication_rotate_key function usually when their keys expire.

Onboarded agents with valid keys can get access token to be used in exchange calls using mcl_communication_get_access_token function. mcl_communication_get_access_token function is also called within mcl_communication_onboard and mcl_communication_rotate_key functions.

Before you can exchange data with MindSphere it is required to prepare a store of type mcl_store_t which will contain all data you want to upload. See next section for details about initializing and adding data to store.

mcl_communication_process is similar to mcl_communication_exchange but additionally, it automatically renews access token if it expires, rotates key if the client secret expires and then retries the exchange operation once more.

Module: Store

This module can be used to create a store for all types of data that your client application wants to exchange with MindSphere. Store is a container and any type of data is required to be exchanged within this container. After calling the initialization function a new store will be created which then can be used to add new items like time series, event or file to it. When the store is ready to be exchanged you may use the communication module to start the exchange operation.

Module: Time series

This module can be used to add/modify entries inside a time series which is created by the store module.

Module: Stream data

This module can be used to add/modify entries inside a stream data which is created by the store module. Stream data is provided via a callback function.

Module: Data source configuration

This module can be used to add/modify entries inside a data source configuration which is created by the store module.

Module: Json util

This module can be used to create json strings which may be used by other mcl modules.

Module: Random

This module provides a single function to generate globally unique identifier.

Module: Logging

This module enables you to configure how log messages will be stored according to your needs. It is possible to decide during compilation of MCL whether log messages for a certain log level will be removed. Any log message statements in MCL with lower log level than the selected one will be replaced by no-op instruction. Thus, the size of the MCL can be reduced. In order to set the log level for compilation please refer to the option MCL_LOG_UTIL_LEVEL in above cmake command options.

The log level in compilation time can be used together with the runtime log level in order to achive desired logging behaviour. Log level in compilation time shadows the runtime log level, e.g. if you set during compilation time the log level to ERROR you won't be able to log DEBUG messages at runtime. In this example you can only decide whether ERROR, FATAL or NONE log messages are active during runtime.

Module: Event

This module can be used to set optional parameters of an event that will be uploaded to MindSphere.

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.