MindConnect Library - Samples¶
Basic use case for a custom agent¶
A typical agent use case would require these steps:
- Create a new configuration handle (mcl_configuration_t) using mcl_configuration_initialize function.
- Assign values for each parameter in mcl_configuration_t handle. You can omit optional parameters.
- Initialize MCL with the mcl_configuration_t handle using mcl_communication_initialize function
which will create a new mcl_communication_t handle.
Note that mcl_configuration_t handle will not be necessary after initialization of MCL, so you can destroy it using mcl_configuration_destroy function.
- 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. Store Initialization¶
- Initialize an mcl_store_t handle using mcl_store_initialize function.
This will be the container for your exchange data.
4. Uploading Data Source Configuration¶
- Create a new data source configuration in the store using mcl_store_new_data_source_configuration function which will return mcl_data_source_configuration_t handle.
- Use mcl_data_source_configuration_t handle to add data source to data source configuration with mcl_data_source_configuration_add_data_source function.
This function will return mcl_data_source_t handle.
- Use mcl_data_source_t handle to add data point(s) to data source with mcl_data_source_configuration_add_data_point function.
This function will ask for a globally unique identifier for each data point added which can be generated using mcl_random_generate_guid function.
User must keep data source configuration ID (randomly generated by MCL internally and can be accessed with mcl_data_source_configuration_get_id function) and data point ID(s) for time series upload.
- Call mcl_communication_exchange function to upload the store containing the data source configuration.
Make sure data source configuration is uploaded before the first time series upload.
Data source configuration is uploaded only once for an agent as long as the data source configuration is not changed.
If the exchange is successful (i.e. the function returns MCL_OK), data source configuration will be automatically deleted from the store.
You are expected to destroy the store using mcl_store_destroy function if you are not going to use it for further exchange operations.
After data source configuration upload, you will need to do data point mapping from MindSphere Launchpad before starting to upload time series data.
5. Uploading Time Series and Files¶
- Create time series in the store (you can use the one initialized in Step-3 or create a new one) using mcl_store_new_time_series function. You will need 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 exchange data for.
- Set values for every data point in each value set using mcl_time_series_add_value.
Remember that data points in each value set correspond to the data points previously added to data source configuration.
You can exchange this data just like you did in Step-4 or you can follow the next steps before an exchange to upload time series and file data together.
- Create file in the store using mcl_store_new_file function.
Note that file_path parameter of mcl_store_new_file function is the full path of the file in your system you want to upload and file_name parameter is the name of the file to be used on MindSphere.
MCL opens and reads data from file_path and uploads its content to MindSphere as a file with name file_name.
- Call 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, you get MCL_UNAUTHORIZED error from the mcl_communication_exchange function.
In that case, you can try to get new access token using mcl_communication_get_access_token function.
- Destroy the store using mcl_store_destroy function.
- Destroy mcl_communication_t handle using mcl_communication_destroy function.
You can find custom agent examples using MCL in /examples folder of 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. Check /examples/onboard_dsc_upload.c file for the implementation.
Uploading time series¶
This example initializes MCL for an already onboarded agent of which data source configuration is also uploaded and then uploads time series data. Check /examples/timeseries_upload.c file for the implementation.
This example initializes MCL for an already onboarded agent and then uploads a file. Check /examples/file_upload.c file for the implementation.
This example onboards a newly created agent, then uploads events to MindSphere. Check /examples/event.c file 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. Check /examples/multi_process_agent.c, /examples/critical_section.cpp and /examples/critical_section.h file 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.