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
- Assign values for each parameter in the
mcl_configuration_thandle. You can omit optional parameters.
- Initialize MCL with the
mcl_configuration_thandle using the
mcl_communication_initializefunction, which creates a new
mcl_configuration_thandle is not required anymore after initialization of MCL. You can destroy it using the
- 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
3. Initializing a Store¶
- Initialize an
mcl_store_thandle using the
mcl_store_initializefunction. 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_configurationfunction, which returns an
- Use the
mcl_data_source_configuration_thandle to add a data source to the data source configuration using the
This function returns a
- Use the
mcl_data_source_thandle to add data point(s) to the data source using the
This function asks for a globally unique identifier for each data point, which can be generated using the
The user must keep the data source configuration ID (randomly generated by MCL and accessible using the
mcl_data_source_configuration_get_idfunction) and data point ID(s) for time series upload.
- Call the
mcl_communication_exchangefunction 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_destroyfunction 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 MindSphere 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_seriesfunction 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_setfunction for every timestamp you want to exchange data for.
- Set values for every data point in each value set using
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
Note that the
file_pathparameter is the full path of the file in your system and the
file_nameparameter defines the name used on MindSphere.
MCL opens and reads data from
file_pathand uploads its content to MindSphere as a file with name
- Call the
mcl_communication_exchangefunction to upload the store containing both time series and file data.
Note that if your token to exchange data is expired, the
mcl_communication_exchangefunction returns an
MCL_UNAUTHORIZEDerror. In that case, you can try to get a new access token using
- Destroy the store using the
- Destroy the
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.
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.
This example onboards a newly created agent and uploads events to MindSphere. 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 MindSphere. It is provided as part of the MCL distribution. Refer to the files
/examples/critical_section.h for the implementation.
Note that this example is a Windows application.
Any questions left?
Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.