FinderOpta Library Documentation

Company:

Finder SPA

Title:

FinderOpta

Version:

1.0.0.0

Namespace:

Opta

Author:

Finder SPA

Placeholder:

FinderOpta

Description [1]

FinderOpta provides utility functions for accessing services exposed by the Finder OPTA device from a CODESYS application.

The library is intended to simplify the integration of device-specific functionality into IEC 61131-3 applications by providing a PLC-oriented interface to services managed by the OPTA runtime.

Overview

Currently FinderOpta provides utility functions for accessing MQTT services available on the Finder OPTA device from a CODESYS application. The library is designed to simplify MQTT communication from IEC 61131-3 application code by providing PLC-oriented functions for subscribing to topics, receiving values, publishing values, and monitoring the MQTT connection state.

The library provides functions for:

  • subscribing to MQTT topics and retrieving received values;

  • publishing values to MQTT topics;

  • querying the current MQTT connection state.

The MQTT client is configured through the CODESYS device configuration. Connection parameters such as the MQTT broker, port, authentication settings, transport security, and other client-specific options are therefore managed independently of the application code.

The library functions operate on the configured MQTT client and use parameters supplied by the application, including the MQTT topic, Quality of Service (QoS) level, and an operation identifier.

Cyclic operation

MQTT communication is asynchronous with respect to the PLC task. Operations such as subscribing to a topic, waiting for a message, or publishing a value may therefore require multiple PLC cycles to complete.

The application should call the corresponding library function cyclically while the operation is active.

An operation identifier is passed as an input/output parameter to functions that require persistent operation state. This identifier is completely opaque to the application and is used internally by the runtime to associate successive function calls with the same MQTT operation across PLC cycles. The application must preserve the identifier value between calls, but must not initialize, interpret, modify, or otherwise manage it. Its contents have no application-level meaning and may change as required by the runtime.

MQTT read functions

The MQTT read functions subscribe the configured MQTT client to the specified topic and wait for a valid message to be received. Because message reception is asynchronous, a read operation may remain active for several PLC cycles. The application should continue calling the read function cyclically and preserve the associated operation identifier between calls.

When a valid MQTT message is received and successfully converted to the requested data type, the function copies the value to the corresponding output and sets valid to TRUE. Until valid data is available, valid remains FALSE and the corresponding value output should not be considered valid.

The following value types are supported:

  • Binary

  • Boolean

  • Integer

  • Real

  • String

For binary data, the read function additionally returns the number of valid bytes copied to the output buffer. This value indicates how much of the output buffer contains data received from the MQTT message.

MQTT publish functions

The MQTT publish functions send application values to the specified MQTT topic using the configured MQTT client. Publishing is asynchronous and may require multiple PLC cycles to complete. The application should therefore call the publish function cyclically and preserve the corresponding operation identifier until the operation has completed or terminated with an error.

The requested Quality of Service level determines the MQTT delivery semantics used for the publication, subject to the capabilities and configuration of the MQTT client and broker.

MQTT connection state

The library provides functions for querying the current state of the MQTT client connection. Applications can use this information to determine whether MQTT communication is currently available and to avoid starting operations when the client is disconnected. Because network connectivity may change at runtime, applications should handle broker disconnections, reconnections, timeouts, and communication errors without assuming that an MQTT operation completes within a single PLC cycle.

TLS/SSL configuration

When the MQTT connection is configured to use TLS/SSL, the server certificate file must be installed on the Finder OPTA filesystem.

The certificate file, named server.srt, must be placed in the MQTT directory on the device. The file can be transferred to the OPTA filesystem using the File Transfer panel in the CODESYS IDE.

If the MQTT broker requires client-certificate authentication, the client certificate and corresponding private key must also be placed in the same MQTT directory. The expected filenames are:

  • client.crt for the client certificate;

  • client.key for the client private key.

These files are used by the MQTT client during TLS connection establishment. The configured certificates and keys must match the authentication and trust requirements of the target MQTT broker.

Contents:

Indices and tables