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 the mcl_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 the mcl_communication_initialize function, which creates a new mcl_communication_t handle.
  Note that mcl_configuration_t handle is not required anymore after initialization of MCL. You can destroy it using the mcl_configuration_destroy function.

2. Onboarding¶

• Pass the mcl_communication_t handle to mcl_communication_onboard function to onboard the agent.
  Continue with the following steps only if this function returns MCL_OK or MCL_ALREADY_ONBOARDED.

3. Initializing a Store¶

• Initialize an mcl_store_t handle using the mcl_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 an mcl_data_source_configuration_t handle.
• Use the mcl_data_source_configuration_t handle to add a data source to the data source configuration using the mcl_data_source_configuration_add_data_source function.
  This function returns a mcl_data_source_t handle.
• Use the mcl_data_source_t handle to add data point(s) to the data source using the mcl_data_source_configuration_add_data_point function.
  This function asks for a globally unique identifier for each data point, which can be generated using the mcl_random_generate_guid function.
  The user must keep the data source configuration ID (randomly generated by MCL and accessible using the mcl_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 returns MCL_OK), the data source configuration is automatically deleted from the store. You are expected to destroy the store using the mcl_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 the file_path parameter is the full path of the file in your system and the file_name parameter defines the name used on Insights Hub.
  MCL opens and reads data from file_path and uploads its content to Insights Hub as a file with name file_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, the mcl_communication_exchange function returns an MCL_UNAUTHORIZED error. In that case, you can try to get a new access token using mcl_communication_get_access_token function.
• Destroy the store using the mcl_store_destroy function.
• Destroy the mcl_communication_t handle using mcl_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.