FB_ESMADataAcquisition

Overview

Functional Description

The function block is used to collect data, convert it into a specific format and initiate the transmission of the formatted data through the linked communication function block.

The function block instance must not be called in your program. The functionalities are provided by the methods and properties.

The formatted data is in JSON format. The structure of the data corresponds to the Charlie format, which is supported by the EcoStruxure Machine Advisor for the transmission of machine data to the monitoring application interface.

For the initiation of the data transmission the function block uses the interface IF_ComClient. The communication function block FB_ESMAClientMonitoringApi provided by this library implements this interface and can be used for the transmission of the data messages created by this function block.

An instance of the communication client of type FB_ESMAClientMonitoringApi can be assigned to several instances of the FB_ESMADataAquisition function block.

Data Acquisition:

For the acquisition of the data there are two methods provided.

• AddValue(): With this method you can add a variable value immediately to the data telegram.

• Monitor(): With this method you can provide a list of variables that is monitored by the function block.

Depending on the configuration, the value of a monitored variable is added to the data telegram either on a value change or in a cyclic interval.

According to the data format Charlie, which is required by the EcoStruxure Machine Advisor monitoring application interface, the variables within a data telegram are assigned to an asset. An asset is defined by the asset-name that is determined by the property AssetName.

Controller Real Time Clock (RTC):

For each value in the data telegram a timestamp is required. Using the method AddValue(), the timestamp must be provided by your application program. When using the method Monitor(), the timestamp is retrieved from the controller RTC (Real Time Clock). The timestamp must be provided as UTC (Coordinated Universal Time).

The timestamp must not be too far in the past and not too far in future as well. Values, whose timestamp is outside of the allowed range, are discarded by the monitoring application interface and are not stored in the Machine Advisor data base.

Information about the EcoStruxure Machine Advisor monitoring application interface and its limitations are provided at the EcoStruxure Machine Advisor web page. To prevent data loss and data inconsistency, synchronize the controller RTC with a time server on a regular basis. For the update of the controller RTC, you can use the function block FB_SntpClient from the TimeSync library. For more information, refer to TimeSync Library Guide

Data Transmission:

The transmission of the created data telegrams is processed by the method Cyclic(). With the execution of this method, it is verified if there is a data telegram ready for transmission. If so, the data transmission is initiated using the interface to the communication client. The interface must be assigned to the property ComClient. The data telegram to send is then moved to an internal send queue and removed from there when the transmission is successful.

The method Cyclic() must be called cyclically in your application program. The status of an ongoing data transmission can be monitored by the property State.

Internal Memory:

For the data processing the function block requires an internal memory of a predefined size. The size of this memory can be specified for each instance by the corresponding input parameters (Interface). The created data telegram in JSON format is stored in the internal memory. The sizes are configured using the input parameter ic_uiNumOfValues.

Each data telegram, which is ready to send, is moved to an internal send queue. The number of messages that can be queued is defined by the input parameter ic_LengthSendBuffer.

For the monitoring of variables an internal memory is required to store information about the monitored variables. The size of this memory is configured by the input parameter ic_uiNumOfMonitoredVariables.

Example Code

PROGRAM SR_Equipment1_DocuExample
VAR
    xInitDone        : BOOL ;
    xCmdReset        : BOOL ;
    xCmdReinit       : BOOL ;
    xEnMonVar1       : BOOL ;
    xEnMonVar2       : BOOL ;
    xCmdAddVar1      : BOOL ;
    xCmdAddVar2      : BOOL ;
    etResultAddValue : IOTCC . ET_Result ;
    etResultMonitor  : IOTCC . ET_Result ;
    etResultCyclic   : IOTCC . ET_Result ;
    sResultMsgCyclic : STRING ( 80 ) ;
    sResultMsg       : STRING ( 80 ) ;
    etResultData     : IOTCC . ET_Result ;
    etStateData      : IOTCC . ET_StateDataTransmission ;
    xError           : BOOL ;

    astMonVars       : ARRAY [ 0 .. 1 ] OF IOTCC . ST_VariableToMonitor ;
    fbDataEquipment1 : IOTCC . FB_ESMADataAcquisition :=
                                   ( ic_uiNumOfValues := 10 ,
                                    ic_uiNumOfMonitoredVariables := 10 ) ;

    udiVar1          : UDINT ;
    rVar2            : REAL ;
    uliTimestamp     : ULINT ;
END_VAR

// Initialization
IF NOT xInitDone OR xCmdReinit THEN
    xInitDone        := TRUE ;
    xCmdReinit       := FALSE ;

    fbDataEquipment1 . InitData ( ) ;
    fbDataEquipment1 . ComClient := SR_ComClient_DocuExample . fbComClient ;
    fbDataEquipment1 . AssetName := "Equipment1" ;
END_IF

// Monitoring variables
IF xEnMonVar1 THEN
    astMonVars [ 0 ] := IOTCC . FC_VariableToStruct ( i_anyVar := udiVar1 ,
                                              i_wsVarName      := "Variable1" ,
                                              i_timInterval    := T#0S ) ; // on value change
ELSE
    astMonVars [ 0 ] . pbyVar := 0 ;
END_IF

IF xEnMonVar2 THEN
    astMonVars [ 1 ] := IOTCC . FC_VariableToStruct ( i_anyVar := rVar2 ,
                                              i_wsVarName      := "Variable2" ,
                                              i_timInterval    := T#60S ) ; // cyclic
ELSE
    astMonVars [ 1 ] . pbyVar := 0 ;
END_IF

etResultMonitor := fbDataEquipment1 . Monitor ( astMonVars ) ;

// add variables on demand
IF xCmdAddVar1 OR xCmdAddVar2 THEN
    SysTimeRtc . SysTimeRtcHighResGet ( uliTimestamp ) ;
END_IF

IF xCmdAddVar1 THEN
    xCmdAddVar1 := FALSE ;
    etResultAddValue := fbDataEquipment1 . AddValue ( i_anyVar := udiVar1 ,
    i_uliTimestamp := uliTimestamp ,
    iqc_wsVarName := "Variable1" ) ;
END_IF

IF xCmdAddVar2 THEN
    xCmdAddVar2 := FALSE ;
    etResultAddValue := fbDataEquipment1 . AddValue ( i_anyVar := rVar2 ,
                                              i_uliTimestamp   := uliTimestamp ,
                                              iqc_wsVarName    := "Variable2" ) ;
END_IF

// call the method cyclic
IF NOT xError THEN
    etResultCyclic := fbDataEquipment1 . Cyclic ( q_sResultMsg => sResultMsgCyclic ) ;
    IF etResultCyclic <> IOTCC . ET_Result . Ok THEN
        xError := TRUE ; // error detected
    END_IF
ELSIF xCmdReset THEN
    xCmdReset := FALSE ;
    xError := FALSE ;
    xCmdReinit := TRUE ;
END_IF

// status information
sResultMsg   := fbDataEquipment1 . ResultMsg ;
etResultData := fbDataEquipment1 . Result ;
etStateData  := fbDataEquipment1 . State ;

Interface

This function block provides only parameters of type INPUT CONSTANT. These input parameters need to be assigned during build time. A modification of these values during runtime is not supported. The initial values must be defined in the declaration of the instance of this function block.

For Example:

VAR
    fbData : IOTCC.FB_ESMADataAcquisition := (ic_uiNumOfValues := 10,
                                              ic_uLengthSendBuffer := 10,
                                              ic_uiNumOfMonitoredVariables := 10);
END_VAR