MindConnect Library – Samples¶
Basic Use Case for a Custom Agent¶
A typical use case for a custom agent requires the following steps:
1. Initializing MCL¶
- Create a new configuration handle (
mcl_configuration_t
) using themcl_configuration_initialize
function. - Assign values for each parameter in the
mcl_configuration_t
handle. You can omit optional parameters. - Initialize MCL with the
mcl_configuration_t
handle using themcl_communication_initialize
function, which creates a newmcl_communication_t
handle.
Note thatmcl_configuration_t
handle is not required anymore after initialization of MCL. You can destroy it using themcl_configuration_destroy
function.
2. Onboarding¶
- Pass the
mcl_communication_t
handle tomcl_communication_onboard
function to onboard the agent.
Continue with the following steps only if this function returnsMCL_OK
orMCL_ALREADY_ONBOARDED
.
3. Initializing a Store¶
- Initialize an
mcl_store_t
handle using themcl_store_initialize
function. This is the container for your exchange data.
4. Uploading a Data Source Configuration¶
- Create a new data source configuration in the store using the
mcl_store_new_data_source_configuration
function, which returns anmcl_data_source_configuration_t
handle. - Use the
mcl_data_source_configuration_t
handle to add a data source to the data source configuration using themcl_data_source_configuration_add_data_source
function.
This function returns amcl_data_source_t
handle. - Use the
mcl_data_source_t
handle to add data point(s) to the data source using themcl_data_source_configuration_add_data_point
function.
This function asks for a globally unique identifier for each data point, which can be generated using themcl_random_generate_guid
function.
The user must keep the data source configuration ID (randomly generated by MCL and accessible using themcl_data_source_configuration_get_id
function) and data point ID(s) for time series upload. - Call the
mcl_communication_exchange
function to upload the store containing the data source configuration.
Make sure the data source configuration is uploaded before the first time series upload. The data source configuration is uploaded only once per agent as long as it does not change.
If the exchange is successful (i.e. the function returnsMCL_OK
), the data source configuration is automatically deleted from the store. You are expected to destroy the store using themcl_store_destroy
function if you don't intend to use it for further exchange operations.
After the data source configuration upload, you need to do data point mapping using Launchpad before time series data can be uploaded.
5. Uploading Time Series and Files¶
- Create a time series in the store using the
mcl_store_new_time_series
function or use the one initialized in Step 3. This requires the data source configuration ID, see Step 4. - Add a new value set to time series using
mcl_time_series_new_value_set
function for every timestamp you want to exchange data for. - Set values for every data point in each value set using
mcl_time_series_add_value
.
Make sure that data points correspond with the data points previously added to the data source configuration.
You can either exchange this data as described in Step 4 or follow the next steps to upload time series and file data together. - Create a file in the store using the
mcl_store_new_file
function.
Note that thefile_path
parameter is the full path of the file in your system and thefile_name
parameter defines the name used on Insights Hub.
MCL opens and reads data fromfile_path
and uploads its content to Insights Hub as a file with namefile_name
. - Call the
mcl_communication_exchange
function to upload the store containing both time series and file data.
Note that if your token to exchange data is expired, themcl_communication_exchange
function returns anMCL_UNAUTHORIZED
error. In that case, you can try to get a new access token usingmcl_communication_get_access_token
function. - Destroy the store using the
mcl_store_destroy
function. - Destroy the
mcl_communication_t
handle usingmcl_communication_destroy
function.
You can find custom agent examples using MCL in the /examples
folder of the MCL distribution.
Onboard and Data Source Configuration Upload¶
This example onboards a newly created agent, checks if the onboarding is successful, then creates and uploads a data source configuration. The example is provided as part of the MCL distribution. Refer to the file /examples/onboard_dsc_upload.c
for the implementation.
Uploading Time Series¶
This example initializes MCL for an already onboarded agent with available data source configuration and then uploads time series data. The example is provided as part of the MCL distribution. Refer to the file /examples/timeseries_upload.c
for the implementation.
Uploading Files¶
This example initializes MCL for an already onboarded agent and uploads a file. The example is provided as part of the MCL distribution. Refer to the file /examples/file_upload.c
for the implementation.
Uploading Events¶
This example onboards a newly created agent and uploads events to Insights Hub. The example is provided as part of the MCL distribution. Refer to the file /examples/event.c
for the implementation.
Using Multiple Processes for an Agent¶
This example agent initializes MCL in multiple processes with the same registration information and exchanges data with Insights Hub. It is provided as part of the MCL distribution. Refer to the files /examples/multi_process_agent.c
, /examples/critical_section.cpp
and /examples/critical_section.h
for the implementation.
Note that this example is a Windows application.
Except where otherwise noted, content on this site is licensed under the Development License Agreement.