FB_ESMAClientMonitoringApi

Overview

Task

This function block is used for the connection and data transmission to the EcoStruxure Machine Advisor monitoring application interface.

Functional Description

The supported communication protocols are MQTTS and HTTPS.

The connection to the cloud server can be established as direct connection or throughout a proxy server. If the parameter xUseProxy is activated, a tunnel connection to the remote server is established through the proxy server. For this type of connection, an instance of a ProxyHandler function block is required. Using the parameter ifProxyHandler, an instance of a ProxyHandler function block can be assigned. If this parameter is not assigned and the parameter xUseProxy is activated, an internal instance of the function block PXCS.FB_ProxyHandlerHttpConnect is used to establish the tunnel connection.

For connections through MQTTS, the function block provides an automatic reconnect function after an interruption of the connection. This function is configurable by the corresponding parameters (refer to stClientConfiguartion).

The function block implements a DNS client, used to resolve a server address, which is given as hostname.

• If the proxy handler is used and the address for the proxy server is given as hostname, the DNS client is used to retrieve the IP address of the proxy server.

• If the proxy handler is not configured and the address for the cloud server is given as hostname, the DNS client is used to retrieve the IP address of the cloud server.

• The DNS client is executed during the connection process. Alternatively, it can be triggered from your application using the method ExecuteDnsClient().

• The retrieved IPv4 address is stored internally.

• The address of the DNS server is required as IPv4 address.

Additional Information for Implementation

The function block must not be called in the application.

For continuous operation of the communication client, the method Cyclic() must be called cyclically in your application.

The properties State, Result and ResultMsg indicate information about the status of the communication client.

The function block implements the interface IF_ComClient. Using this interface, the functionalities of the communication client can be accessed from different locations in your application.

Certificate Management

The connection to the cloud server is established as a secure connection using TLS. For the verification of the identity of the server, the server sends its certifcate. This certifcate or the certifcates of the issuer of this certifcate must be declared as trusted on your controller. For more information about the certifcate management on your controller, refer to How to Manage Certificates on the Controller

Example Code

The example points out the implementation of the FB_ESMAClientMonitoringApi. The instance of the function block FB_ESMAClientCredentials was created within a Persistent Variables object.

PROGRAM SR_ComClient_DocuExample
VAR
    xInitDone            : BOOL ;
    xCmdExecuteDns       : BOOL ;
    xCmdConnect          : BOOL ;
    xCmdAbort            : BOOL ;
    xCmdDisconnect       : BOOL ;
    xCmdReset            : BOOL ;
    xCmdInitialize       : BOOL ;
    xCmdReinit           : BOOL ;
    etResult             : IOTCC . ET_Result ;
    etState              : IOTCC . ET_StateComClient ;
    sResultMsg           : STRING ;
    etResult_Dns         : IOTCC . ET_Result ;
    etResult_Connect     : IOTCC . ET_Result ;
    etResult_Disconnect  : IOTCC . ET_Result ;

    fbComClient          : IOTCC . FB_ESMAClientMonitoringApi ;
    stClientConfiguration: IOTCC . ST_ClientConfiguration ;

    sConnectionString    : STRING ( 255 ) ;
    sProxyServerAddr     : STRING ( 15 ) ;
    sDnsServerIp         : STRING ( 15 ) ;
    etComProtocol        : IOTCC . ET_ComProtocol := IOTCC . ET_ComProtocol . Mqtts ;
    udiSentMessages      : UDINT ;
END_VAR

// Initialization

IF sConnectionString <> '***' THEN
    PersistentVars . fbCredentials . ConnectionString := sConnectionString ;
    sConnectionString := '***' ;
    xCmdReinit := TRUE ;
END_IF

IF NOT xInitDone OR xCmdReinit THEN
    xInitDone  := TRUE ;
    xCmdReinit := FALSE;
    stClientConfiguration . sCloudServerAddr                := PersistentVars . fbCredentials . ServerUrl ;
    stClientConfiguration . stProxySettings . xUseProxy          := sProxyServerAddr <> '' ;
    stClientConfiguration . stProxySettings . sProxyServerAddr   := sProxyServerAddr ;
    stClientConfiguration . sDnsServerIpAddr                := sDnsServerIp ;
    stClientConfiguration . etProtocol                      := etComProtocol ;
    fbComClient . ClientConfiguration                            := stClientConfiguration ;
    fbComClient . ClientCredentials                         := PersistentVars . fbCredentials ;
END_IF

// cyclic processing
fbComClient . Cyclic ( ) ;

// status and information
etState         := fbComClient . State ;
etResult        := fbComClient . Result ;
sResultMsg      := fbComClient . ResultMsg ;
udiSentMessages := fbComClient . SentMessagesCount ;

// commands
IF xCmdExecuteDns THEN
    xCmdExecuteDns := FALSE ;
    etResult_Dns := fbComClient . ExecuteDnsClient ( ) ;
END_IF

IF xCmdConnect THEN
    xCmdConnect := FALSE ;
    etResult_Connect := fbComClient . Connect ( ) ;
END_IF

IF xCmdDisconnect THEN
    xCmdDisconnect := FALSE ;
    etResult_Disconnect := fbComClient . Disconnect ( ) ;
END_IF

IF xCmdReset THEN
    xCmdReset := FALSE ;
    fbComClient . ResetError ( ) ;
END_IF

IF xCmdInitialize THEN
    xCmdInitialize := FALSE ;
    fbComClient . Initialize ( ) ;
END_IF