.. first line of index.rst template


================================
FinderOpta Library Documentation
================================

:Company: Finder SPA
:Title: FinderOpta
:Version: 1.0.0.0
:Namespace: Opta
:Author: Finder SPA
:Placeholder: FinderOpta

.. _index_description:

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:
---------

.. toctree::

   FinderOpta </FinderOpta/fld-FinderOpta>
   Library Information </Library-Information/fld-Library-Information>

Indices and tables
------------------

.. toctree::
   :hidden:

   info
   libraries

.. only:: libdoc_html

    * :ref:`genindex`
    * :ref:`search`
    * :ref:`info`
    * :ref:`libraries`

.. only:: libdoc_chm

    * :ref:`info`
    * :ref:`libraries`

.. only:: libdoc_lmd

    * :ref:`info`
    * :ref:`libraries`

.. [1] | Based on FinderOpta.library, last modified 29.09.2026, 18:06:40. LibDoc 4.7.0.0
       | The content file FinderOpta.json was generated with CODESYS V3.5 SP21 Patch 6 on 29.09.2026, 18:07:27.
.. last line of index.rst template
