Skip to content

MindConnect Library – 示例

自定义代理的基本用例

使用自定义代理通常需要以下几个步骤：

1.初始化 MCL

  • 使用 mcl_configuration_initialize 函数创建新的配置句柄 (mcl_configuration_t)。
  • 为 mcl_configuration_t 句柄中的每个参数分配值。可忽略可选参数。
  • 使用 mcl_communication_initialize 函数通过 mcl_configuration_t 句柄初始化 MCL，该函数将创建一个新的 mcl_communication_t 句柄。
    请注意，MCL 初始化后就不再需要 mcl_configuration_t 句柄。您可以使用 mcl_configuration_destroy 函数销毁该句柄。

2.上线

  • 将 mcl_communication_t 句柄传给 mcl_communication_onboard 函数，用于上线代理。
    仅当该函数返回 MCL_OK 或 MCL_ALREADY_ONBOARDED 时才能继续执行后续步骤。

3.初始化存储

  • 使用 mcl_store_initialize 函数初始化 mcl_store_t 句柄。存储是用于交换数据的容器。

4.上传数据源配置

  • 使用 mcl_store_new_data_source_configuration 函数在存储中新建一个数据源配置，该函数将返回一个 mcl_data_source_configuration_t 句柄。
  • 使用 mcl_data_source_configuration_t 句柄通过 mcl_data_source_configuration_add_data_source 函数将数据源添加到数据源配置。
    该函数将返回一个 mcl_data_source_t 句柄。
  • 使用 mcl_data_source_t 句柄通过 mcl_data_source_configuration_add_data_point 函数将数据点添加到数据源。
    每个数据点必须为该函数提供全局唯一标识符，该标识符可以使用 mcl_random_generate_guid 函数生成。
    要进行时间序列上传，用户必须保留数据源配置 ID（由 MCL 随机生成，可使用 mcl_data_source_configuration_get_id 函数访问）和数据点 ID。
  • 调用 mcl_communication_exchange 函数上传包含数据源配置的存储。
    请务必在上传第一个时间序列之前先上传数据源配置。每个代理仅上传一次数据源配置，除非数据源配置有变更。
    如果数据交换成功（即函数返回 MCL_OK），将自动删除存储中的数据源配置。如果您不想继续使用该存储进行交换操作，可使用 mcl_store_destroy 函数销毁该存储。
    上传数据源配置后，您需要使用 Launchpad 进行数据点映射，然后才能上传时间序列数据。

5.上传时间序列和文件

  • 使用 mcl_store_new_time_series 函数在存储中创建时间序列，或使用步骤 3 中初始化的时间序列。此过程需要数据源配置 ID（见步骤 4）。
  • 针对每个数据交换时间戳，使用 mcl_time_series_new_value_set 函数为时间序列添加一个新值集。
  • 使用 mcl_time_series_add_value 为各值集中的每个数据点设置值。
    确保数据点与之前添加到数据源配置中的数据点相对应。 您可以按照步骤 4 交换此数据，或根据后续步骤同时上传时间序列和文件数据。
  • 使用 mcl_store_new_file 函数在存储中创建一个文件。
    请注意，file_path 参数是文件在系统中的完整路径，file_name 参数定义文件在 MindSphere 上的名称。
    MCL 打开 file_path 并从中读取数据，然后将其内容作为以 file_name 命名的文件上传到 MindSphere。
  • 调用 mcl_communication_exchange 函数上传包含时间序列和文件数据的存储。
    请注意，如果您用于交换数据的令牌已过期，则 mcl_communication_exchange 函数将返回 MCL_UNAUTHORIZED 错误。此时，您可以尝试使用 mcl_communication_get_access_token 函数获取新的访问令牌。
  • 使用 mcl_store_destroy 函数销毁存储。
  • 使用 mcl_communication_destroy 函数销毁 mcl_communication_t 句柄。

您可以在 MCL 分发的 /examples 文件夹中找到使用 MCL 的自定义代理示例。

上线和数据源配置上传

此示例将上线一个新建代理并验证上线是否成功，然后创建并上传数据源配置。MCL 分发中将提供该示例。有关具体实现过程，请参见文件 /examples/onboard_dsc_upload.c。

上传时间序列

此示例使用可用数据源配置为已上线的代理初始化 MCL，然后上传时间序列数据。MCL 分发中将提供该示例。有关具体实现过程，请参见文件 /examples/timeseries_upload.c。

上传文件

此示例为已上线的代理初始化 MCL 并上传文件。MCL 分发中将提供该示例。有关具体实现过程，请参见文件 /examples/file_upload.c。

上传事件

此示例将上线一个新建代理，然后将事件上传到 MindSphere。MCL 分发中将提供该示例。有关具体实现过程，请参考文件 /examples/event.c。

为代理使用多进程

在此示例中，代理将使用相同的注册信息在多个进程中初始化 MCL，然后与 MindSphere 交换数据。MCL 分发中将提供该示例。有关具体实现过程，请参考文件 /examples/multi_process_agent.c、/examples/critical_section.cpp 和 /examples/critical_section.h。
请注意，该示例是一个 Windows 应用。

Last update: March 22, 2023