flexCommunicator 0.1.0__py3-none-any.whl

flexcommunicator-0.1.0.dist-info/METADATA

@@ -0,0 +1,568 @@
+Metadata-Version: 2.4
+Name: flexCommunicator
+Version: 0.1.0
+Summary: Protocol-agnostic Python client library for building software components for industrial automation applications.
+Author-email: Bert Van Acker <bert.vanacker@uantwerpen.com>
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright [yyyy] [name of copyright owner]
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+        
+Project-URL: Homepage, https://github.com/BertVanAcker/flexCommunicator
+Project-URL: Repository, https://github.com/BertVanAcker/flexCommunicator
+Project-URL: Issues, https://github.com/BertVanAcker/flexCommunicator/issues
+Keywords: flexia,industrial-automation,iot,iiot,mqtt,opc-ua,plc,digital-twin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: jsonpickle>=3.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: packaging>=23.0
+Requires-Dist: bcrypt>=4.0
+Requires-Dist: redis>=5.0
+Provides-Extra: mqtt
+Requires-Dist: paho-mqtt>=2.0; extra == "mqtt"
+Provides-Extra: rabbitmq
+Requires-Dist: pika>=1.3; extra == "rabbitmq"
+Provides-Extra: kafka
+Requires-Dist: kafka-python>=2.0; extra == "kafka"
+Provides-Extra: zenoh
+Requires-Dist: eclipse-zenoh; extra == "zenoh"
+Provides-Extra: websocket
+Requires-Dist: websocket-client>=1.8; extra == "websocket"
+Requires-Dist: websockets>=10.3; extra == "websocket"
+Provides-Extra: opcua
+Requires-Dist: asyncua>=1.1; extra == "opcua"
+Provides-Extra: twincat
+Requires-Dist: pyads; extra == "twincat"
+Provides-Extra: fmi
+Requires-Dist: fmpy>=0.3; extra == "fmi"
+Provides-Extra: ros2
+Requires-Dist: opencv-python; extra == "ros2"
+Provides-Extra: memcached
+Requires-Dist: python-memcached; extra == "memcached"
+Provides-Extra: ignite
+Requires-Dist: pyignite; extra == "ignite"
+Provides-Extra: hazelcast
+Requires-Dist: hazelcast-python-client; extra == "hazelcast"
+Provides-Extra: tarantool
+Requires-Dist: tarantool; extra == "tarantool"
+Provides-Extra: aerospike
+Requires-Dist: aerospike; extra == "aerospike"
+Provides-Extra: all
+Requires-Dist: paho-mqtt>=2.0; extra == "all"
+Requires-Dist: pika>=1.3; extra == "all"
+Requires-Dist: kafka-python>=2.0; extra == "all"
+Requires-Dist: eclipse-zenoh; extra == "all"
+Requires-Dist: websocket-client>=1.8; extra == "all"
+Requires-Dist: websockets>=10.3; extra == "all"
+Requires-Dist: asyncua>=1.1; extra == "all"
+Requires-Dist: pyads; extra == "all"
+Requires-Dist: fmpy>=0.3; extra == "all"
+Requires-Dist: opencv-python; extra == "all"
+Requires-Dist: python-memcached; extra == "all"
+Requires-Dist: pyignite; extra == "all"
+Requires-Dist: hazelcast-python-client; extra == "all"
+Requires-Dist: tarantool; extra == "all"
+Requires-Dist: aerospike; extra == "all"
+Dynamic: license-file
+
+# flexCommunicator
+
+**flexCommunicator** is the Python client library (`flcpy`) for building distributed, protocol-agnostic software components ("flexNodes") for industrial automation applications. It is one of the core technology building blocks of the **FlexIA** framework, developed at the University of Antwerp (Cosys-Lab).
+
+> ⚠️ Not yet released on PyPI — the package is prepared for release (`pyproject.toml`), install from source in the meantime (see [Installation](#installation)).
+
+## Table of contents
+
+- [About FlexIA](#about-flexia)
+- [About flexCommunicator](#about-flexcommunicator)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Core concepts](#core-concepts)
+- [API reference](#api-reference)
+- [Features](#features)
+- [Examples](#examples)
+- [Releasing to PyPI](#releasing-to-pypi)
+- [License](#license)
+
+## About FlexIA
+
+**FlexIA – Flexible Industrial Automation** is a framework for the design, implementation, and deployment of software-intensive industrial automation, developed under an IOF Proof-of-Concept project at the University of Antwerp. Its goal is to enable a **"develop once, deploy anywhere"** paradigm that gives industrial automation engineers true hardware/software flexibility — reducing vendor lock-in and simplifying the integration of advanced software (AI, computer vision, digital twins, autonomous robotics) into classical, PLC-centric automation systems.
+
+FlexIA is decomposed into four cooperating technology building blocks:
+
+| Building block | Role |
+|---|---|
+| **flexModeler** | AADL-based architectural modeling environment for automation systems, with code generation into multiple implementation formalisms (C/C++, Python, Rust, IEC 61131-3). |
+| **flexCommunicator** *(this repository)* | Client libraries for building the actual software components ("flexNodes") of an automation application — IT/OT communication, monitoring, and flexCloud connectivity. |
+| **flexCloud** | Centralized environment for building, packaging, deploying, and managing FlexIA applications; provides logging, monitoring, and online reconfiguration. |
+| **flexEngine** | Lightweight on-device runtime/agent that connects a target platform (PLC, SBC, microcontroller) to the flexCloud and handles native, container-free deployment. |
+
+The FlexIA software architecture is inspired by (adaptive) AUTOSAR, ROS2, and Autoware, adapted to the constraints and needs of industrial automation.
+
+## About flexCommunicator
+
+**flexCommunicator** is a set of client libraries that enable the construction of modular and interoperable software components ("flexNodes") for industrial automation applications. It provides a uniform, protocol-agnostic API on top of a variety of IT and OT communication protocols, so that application logic does not need to be rewritten when the underlying transport changes.
+
+Client libraries exist for multiple formalisms:
+
+| Language | Status |
+|---|---|
+| Python (`flcpy`, this repository) | Feature-rich, reference implementation |
+| C/C++ | Reduced feature set |
+| Rust | Reduced feature set |
+
+Every flexCommunicator application is built out of one or more **`flexNode`** instances — the base class in `flexCommunicator/clientLibraries/flcpy/flexNode.py`. A `flexNode`:
+
+- exposes and consumes named **properties** (variables/messages) over any supported transport protocol, resolved through a **communication matrix**;
+- can expose higher-level interaction patterns (publish/subscribe, request/response services, actions) on top of that transport layer;
+- connects to the **flexCloud** for centralized logging, remote monitoring, online reconfiguration, and remote command handling (ping, dynamic transport switching, ...);
+- can expose **contracts** (assumptions/guarantees), **requirements traceability**, **application profiling**, and **validity-frame runtime monitors** for observability and safety assurance;
+- can wrap **FMI/FMU** models as regular flexNode components, either stepped manually or run standalone in real time.
+
+## Installation
+
+flexCommunicator is not yet published on PyPI, but the package is fully prepared for release (`pyproject.toml`). Once released:
+
+```bash
+pip install flexCommunicator
+```
+
+Only a minimal core is installed by default: `PyYAML`, `jsonpickle`, `numpy`, `packaging`, `bcrypt`, and `redis` (the backend used by the flexCloud connection and knowledge store every `flexNode` relies on). Everything protocol-/backend-specific is an **extra**, so you only pull in what you actually use:
+
+```bash
+pip install "flexCommunicator[mqtt]"                 # MQTT transport
+pip install "flexCommunicator[opcua,twincat]"         # OPC-UA + TwinCAT ADS
+pip install "flexCommunicator[mqtt,rabbitmq,fmi]"     # combine as needed
+pip install "flexCommunicator[all]"                   # everything
+```
+
+| Extra | Adds support for |
+|---|---|
+| `mqtt` | MQTT transport (`paho-mqtt`) |
+| `rabbitmq` | RabbitMQ transport (`pika`) |
+| `kafka` | Kafka transport (`kafka-python`) |
+| `zenoh` | Zenoh transport (`eclipse-zenoh`) |
+| `websocket` | WebSocket transport (`websocket-client`, `websockets`) |
+| `opcua` | OPC-UA transport (`asyncua`) |
+| `twincat` | TwinCAT ADS transport (`pyads`) |
+| `fmi` | FMU components (`fmpy`) |
+| `ros2` | ROS2 message codec (`opencv-python`) |
+| `memcached` / `ignite` / `hazelcast` / `tarantool` / `aerospike` | Alternative knowledge-store backends |
+| `all` | All of the above |
+
+Until the package is published, install from source instead:
+
+```bash
+git clone https://github.com/BertVanAcker/flexCommunicator.git
+cd flexCommunicator
+pip install .                    # or: pip install ".[all]"
+```
+
+Some protocols/backends require the corresponding server/broker to be reachable at runtime — most examples assume a local Redis instance for the flexCloud knowledge store.
+
+## Quick start
+
+A minimal publisher/subscriber pair (see [`examples/GettingStarted/pubsub_data`](examples/GettingStarted/pubsub_data)):
+
+```python
+from flexCommunicator.clientLibraries.flcpy.flexNode import flexNode
+from flexCommunicator.clientLibraries.flcpy.messages.StandardizedMessages import DataMessage
+
+class Publisher(flexNode):
+    def __init__(self, config, communicationMatrix):
+        super().__init__(config=config, communicationMatrix=communicationMatrix, loaded_config=True)
+        self.timer = self.create_timer(timer_period=0.5, callback=self.send_data)
+
+    def send_data(self):
+        msg = DataMessage()
+        msg.dataType, msg.dataUnit, msg.value = "Float", "m", 3.14
+        self.set_data(data_name="CustomMessage", data=msg)
+
+publisher = Publisher(config, communicationMatrix="communicationMatrix.yaml")
+publisher.spin()
+```
+
+Each flexNode is configured through:
+
+- a **`config.yaml`** — logger, knowledge/storage backend, flexCloud connection, communication managers (one per transport protocol used), and application descriptor (id, connector id);
+- a **`communicationMatrix.yaml`** — the list of named properties the node uses, each bound to a transport protocol and its protocol-specific endpoint (MQTT topic, Redis key, OPC-UA node path, ...).
+
+## Core concepts
+
+- **Property-based communication** — application code reads/writes named properties (`set_data` / `get_data` / `register_data_callback`) without knowing the concrete transport; the **`PropertyRegistry`**, built from the communication matrix, resolves the active protocol and endpoint binding for each property name, and that binding can be changed at runtime.
+- **Multi-transport** — a single flexNode can have multiple `CommunicationManager`s active simultaneously (e.g. MQTT for one property, OPC-UA for another).
+- **Knowledge/storage** — a separate, addressable key/value store (currently Redis-backed) for component-local or shared data, with optional history.
+- **flexCloud** — every flexNode registers itself with the flexCloud (status, variables, config parameters, requirements, profiling, validity frames) and listens for remote commands.
+- **Timers** — periodic callback execution used to drive a node's control loop.
+
+## API reference
+
+Public API of the `flexNode` base class (`flexCommunicator/clientLibraries/flcpy/flexNode.py`). Every custom flexNode subclasses `flexNode` and calls `super().__init__(...)`.
+
+### Lifecycle & metadata
+
+| Member | Description |
+|---|---|
+| `name`, `ID`, `description`, `version` | Read/write properties for application metadata (`version` is parsed as a `packaging.version.Version`). |
+| `load_config(config_file)` | Loads a YAML configuration file into a dict. |
+| `logInit()` | Logs the node's name, ID, and version. |
+| `spin()` | Starts all communication managers, auto-start timers, and the flexCloud connection. |
+| `shutdown()` | Sets the application status to `STOPPED` and stops communication managers, timers, and the flexCloud connection. |
+
+### Timers
+
+| Member | Description |
+|---|---|
+| `create_timer(timer_period=0.1, callback=None, autostart=True)` | Creates a periodic timer that invokes `callback` every `timer_period` seconds. |
+
+### Property-based data communication (multi-transport)
+
+| Member | Description |
+|---|---|
+| `set_data(data_name, data)` | Publishes/writes a property's value over its currently bound transport protocol. |
+| `get_data(data_name)` | Reads a property's current value over its currently bound transport protocol. |
+| `register_data_callback(data_name, callback, isService=False)` | Subscribes a callback to updates of a given property. |
+| `update_property_endpoint(property_name, endpoint)` | Updates the concrete endpoint (e.g. topic/path) a property is bound to. |
+
+### Component knowledge / shared datastore
+
+| Member | Description |
+|---|---|
+| `store_data(data_name, data, history=False)` | Stores a value under a property name in the knowledge backend, optionally keeping history. |
+| `retrieve_data(data_name)` | Retrieves a value previously stored via `store_data`. |
+| `delete_data(data_key, data)` | Deletes stored data *(not yet implemented)*. |
+| `exists_data(data_key, data)` | Checks whether data exists *(not yet implemented)*. |
+
+### Events
+
+| Member | Description |
+|---|---|
+| `emit_event(event_key, data)` | Publishes an event message. |
+| `register_event_callback(event_key, callback)` | Subscribes a callback to an event. |
+
+### flexCloud variables, config parameters & contracts
+
+| Member | Description |
+|---|---|
+| `register_flexCloud_variable(variable)` | Registers a `flexCloudVariable` (or `flexCloudConfigParameter`) so its value is mirrored to/from the flexCloud. |
+| `register_contract_variable(variable)` | Registers a `contractVariable` (assumption or guarantee) with the flexCloud. |
+| `register_runtime_monitor(monitor)` | Registers a validity-frame `runtimeMonitor` with the flexCloud. |
+
+### Services (request/response)
+
+| Member | Description |
+|---|---|
+| `create_service(protocol, service, serviceName, callback)` | Creates and registers a service endpoint (request/response) over MQTT or Redis. |
+| `create_client(protocol, service, serviceName)` | Creates a client for calling a remote service; returns a `client` object. |
+| `generic_service_callback(topic, request)` | Framework-internal dispatcher that routes an incoming service request to the matching service's callback. |
+
+### Actions (goal / feedback / result)
+
+| Member | Description |
+|---|---|
+| `create_action_server(protocol, action, actionName, callback)` | Creates and registers an action server (ROS2-style goal/feedback/result) over MQTT or Redis. |
+| `create_action_client(protocol, action, actionName)` | Creates an action client; returns an `action_client` object supporting feedback/done callbacks. |
+| `publish_action_feedback(goal_handle)` | Publishes an in-progress feedback update for an active goal. |
+| `publish_action_success(goal_handle)` | Marks a goal as succeeded and publishes the final feedback. |
+| `generic_action_callback(topic, request)` | Framework-internal dispatcher that instantiates the goal handle and invokes the action server's callback. |
+
+### FMI / FMU integration
+
+| Member | Description |
+|---|---|
+| `create_fmu_component(name, description, stepsize, fmuPath)` | Wraps an FMU as a manually-stepped component within the node. |
+| `create_standalone_rt_fmu(protocol, name, description, stepsize, fmuPath)` | Wraps an FMU as a real-time component, auto-stepped by an internal timer, with inputs/outputs auto-exposed as properties (only one per node). |
+
+### Validity frames
+
+| Member | Description |
+|---|---|
+| `loadVF(path_to_vf, verbose=False)` | Loads a Validity Frame (`.vf`) file, exposes its architecture and traceability graph to the flexCloud, and registers its runtime monitors. |
+| `update_vf_monitor(monitor_name, value)` | Updates a runtime monitor by name *(not yet implemented)*. |
+
+## Features
+
+### Supported communication protocols
+
+flexCommunicator's `CommunicationManager` supports the following transports for property-based data exchange (`set_data` / `get_data` / `register_data_callback`), selected per property via the communication matrix and switchable at runtime:
+
+- **MQTT**
+- **Redis** (pub/sub)
+- **RabbitMQ**
+- **Kafka**
+- **Zenoh**
+- **WebSocket**
+- **OPC-UA** (read/write PLC variables by name)
+- **TwinCAT ADS** (Beckhoff PLC integration)
+
+The flexCloud connection itself (logging, variables, commands, requirements, profiling, validity frames) currently uses **Redis** as its backing knowledge store.
+
+### Basic functionality
+
+- **Property-based communication** — protocol-agnostic `set_data` / `get_data` / `register_data_callback`, resolved through the `PropertyRegistry` / communication matrix, with runtime endpoint updates (`update_property_endpoint`).
+- **Standardized messages** — reusable message types (e.g. `DataMessage`) and a ROS2-compatible message codec for interoperability with ROS2-based systems.
+- **Timers** — periodic, auto-startable callback execution (`create_timer`) driving a node's control loop.
+- **Component knowledge/datastore** — key/value storage independent of the transport layer, with optional history (`store_data` / `retrieve_data`).
+- **Event messaging** — lightweight publish/subscribe of discrete events (`emit_event` / `register_event_callback`).
+- **Centralized logging** — a custom logging handler that mirrors log records to the flexCloud alongside local terminal/file/MQTT/Redis sinks.
+- **Signed flexCloud commands** — an authenticated command channel (HMAC-signed) used for remote `PING`/`PONG` health checks and dynamic transport-protocol updates (`UPDATE_TRANSPORT`) on running nodes.
+
+### Higher-level communication patterns
+
+- **Publish/subscribe** — data-oriented pub/sub over any supported protocol via `set_data` / `register_data_callback` (see [`examples/GettingStarted/pubsub_data`](examples/GettingStarted/pubsub_data)).
+- **Service (request/response)** — synchronous-style RPC between flexNodes, with auto-generated request/response properties and a generic service dispatcher (`create_service` / `create_client`) (see [`examples/GettingStarted/service`](examples/GettingStarted/service)).
+- **Action (goal / feedback / result)** — long-running, cancellable-style asynchronous operations modeled after ROS2 actions, with request/feedback/response properties and client-side feedback/done callbacks (`create_action_server` / `create_action_client`) (see [`examples/GettingStarted/action`](examples/GettingStarted/action)).
+- **flexCloud variable** — application variables (`flexCloudVariable`) automatically mirrored to the flexCloud, with optional history, for remote observability (see [`examples/GettingStarted/flexCloud_variable`](examples/GettingStarted/flexCloud_variable)).
+- **flexCloud config parameter** — application parameters (`flexCloudConfigParameter`) that can be reconfigured remotely from the flexCloud at runtime, enabling online reconfiguration without redeployment (see [`examples/GettingStarted/flexCloud_configParameter`](examples/GettingStarted/flexCloud_configParameter)).
+- **flexCloud commands** — remote, signed command/response exchange with a running flexNode (health-check `PING`/`PONG`, `UPDATE_TRANSPORT` to switch a property's active protocol on the fly) (see [`examples/GettingStarted/flexCloud_commands`](examples/GettingStarted/flexCloud_commands)).
+- **Orchestrated startup** — dependency-ordered, coordinated startup of multiple cooperating flexNodes via `flexCloudOrchestrator` (`StartupOrchestrator` / `ComponentSpec`), so components come up in the right order and become `RUNNING` before dependents start (see [`examples/GettingStarted/orchestrated_startup`](examples/GettingStarted/orchestrated_startup)).
+- **Requirements traceability** — the `@flexRequirements(id, description, expectedExecutionTime=None)` decorator links application functions to requirement IDs, tracking pass/fail status (and optional execution-time bounds) in the flexCloud for end-to-end traceability from requirement to implementation (see [`examples/GettingStarted/requirementsAndContracts`](examples/GettingStarted/requirementsAndContracts)).
+- **Contracts (assumptions/guarantees)** — `contractVariable`s registered via `register_contract_variable`, expressing design-by-contract assumptions and guarantees (with bound/allowed-value/custom validity checks) reported to the flexCloud.
+- **Application profiling** — the `@flexProfiler()` decorator measures and reports function execution time history to the flexCloud, for lightweight runtime performance profiling (see [`examples/GettingStarted/application_profiling`](examples/GettingStarted/application_profiling)).
+- **Validity frames & runtime monitors** — `loadVF` loads a Validity Frame (`.vf`) describing a safety architecture and traceability graph, publishes them to the flexCloud, and auto-registers its `runtimeMonitor`s (local or remote checks against bounds/allowed values/custom functions) for continuous runtime safety monitoring (see [`examples/GettingStarted/validityFrames`](examples/GettingStarted/validityFrames)).
+- **FMI/FMU integration** — wrap Functional Mock-up Units as flexNode components, either manually stepped (`create_fmu_component`) or run standalone in real time with auto-exposed input/output properties (`create_standalone_rt_fmu`) (see [`examples/GettingStarted/FMI`](examples/GettingStarted/FMI)).
+
+## Examples
+
+The [`examples/GettingStarted`](examples/GettingStarted) folder contains minimal, runnable examples for each feature above. Each example ships its own `config.yaml`, `communicationMatrix.yaml`, and `main.py` entry point.
+
+| Example | Description |
+|---|---|
+| [`pubsub_data`](examples/GettingStarted/pubsub_data) | Minimal publisher/subscriber pair exchanging a `DataMessage` over MQTT, plus storing/retrieving data in the knowledge datastore. |
+| [`service`](examples/GettingStarted/service) | Request/response service (`AddTwoInts`) with a sync and an async client calling a `flexNode` service. |
+| [`action`](examples/GettingStarted/action) | ROS2-style action server/client (`Fibonacci`) demonstrating goal execution with streamed feedback and a final result. |
+| [`flexCloud_variable`](examples/GettingStarted/flexCloud_variable) | Mirrors a local variable (`Temperature`) to the flexCloud using `flexCloudVariable`, readable remotely. |
+| [`flexCloud_configParameter`](examples/GettingStarted/flexCloud_configParameter) | Exposes a runtime parameter (`multiplier`) as a `flexCloudConfigParameter` that can be reconfigured remotely from the flexCloud. |
+| [`flexCloud_commands`](examples/GettingStarted/flexCloud_commands) | Sends signed `PING` and `UPDATE_TRANSPORT` commands to a running `flexNode` and handles its responses. |
+| [`orchestrated_startup`](examples/GettingStarted/orchestrated_startup) | Coordinated, dependency-ordered startup of multiple cooperating `flexNode`s via `StartupOrchestrator`. |
+| [`requirementsAndContracts`](examples/GettingStarted/requirementsAndContracts) | Links application functions to requirement IDs with `@flexRequirements`, and registers assumption/guarantee `contractVariable`s. |
+| [`application_profiling`](examples/GettingStarted/application_profiling) | Uses the `@flexProfiler()` decorator to measure and report function execution time to the flexCloud. |
+| [`validityFrames`](examples/GettingStarted/validityFrames) | Loads a Validity Frame (`.vf`), exposes its architecture/traceability graph, and drives runtime safety monitors on a BLDC motor rig. |
+| [`opcua`](examples/GettingStarted/opcua) | Reads/writes variables on a simulated OPC-UA PLC (Arduino Opta), with flexCloud logging and variable mirroring. |
+| [`opcua_opta`](examples/GettingStarted/opcua_opta) | Same as `opcua`, but connected to a real Arduino Opta OPC-UA PLC instead of a simulator. |
+| [`twincat_ads`](examples/GettingStarted/twincat_ads) | Reads/writes variables on a Beckhoff PLC over the TwinCAT ADS protocol. |
+| [`FMI/manual`](examples/GettingStarted/FMI/manual) | Wraps an FMU as a `flexNode` component that is stepped manually (`create_fmu_component`). |
+| [`FMI/realtime`](examples/GettingStarted/FMI/realtime) | Runs an FMU as a standalone real-time component, auto-stepped by a timer with I/O auto-exposed as properties (`create_standalone_rt_fmu`). |
+
+Larger, integrated demonstrators live under [`examples/Demonstrator`](examples/Demonstrator) and [`examples/SAIfety`](examples/SAIfety).
+
+## Releasing to PyPI
+
+Maintainer-facing packaging/release process (versioning, Trusted Publishing setup, the GitHub Actions workflow, manual fallback) is documented separately in [RELEASING.md](RELEASING.md).
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).

flexcommunicator-0.1.0.dist-info/RECORD

@@ -0,0 +1,53 @@
+flexCommunicator/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/flexNode.py,sha256=XAXibRKfNc4J2KRKGRPT0ffmEASaE7AsD-YLWjuLYfE,48135
+flexCommunicator/clientLibraries/flcpy/node.py,sha256=LVhLVKP3qOm0MBFSB4uleUq7PQX9ZE-vUigQDfLKKA0,23414
+flexCommunicator/clientLibraries/flcpy/action/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/action/action.py,sha256=3Wp6L2vTq41_o_DJfusvrifb2ppduYcsyQ6uowFNync,2187
+flexCommunicator/clientLibraries/flcpy/action/action_client.py,sha256=Hny8jKMTCb9mnLmMxRZXnjfLIOWo-bHF6dbffRi4uJw,2420
+flexCommunicator/clientLibraries/flcpy/action/goal_handle.py,sha256=OVyBNKfxZZL9ahLTgLqJvc35Kdgx3T3Pq-apUDonCNQ,1283
+flexCommunicator/clientLibraries/flcpy/codec/ROS2Codec.py,sha256=JNiA1Ilo7qQGTC8NYzNqATuk982um_3HwibeAOTArg4,6564
+flexCommunicator/clientLibraries/flcpy/codec/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/commands/commandProcessor.py,sha256=EPVNnF-zhqYWPoauelQyShBhrwIvOuLchZHeSavxdQ4,4486
+flexCommunicator/clientLibraries/flcpy/commands/composer.py,sha256=6I8Mdry5gHFXHoBMhmC1O5kKP3kxcuIljS_oh-eCvx0,1008
+flexCommunicator/clientLibraries/flcpy/communication/CommunicationManager.py,sha256=5MIwjC-nhCbWBvwVfTZDxtSKu_s4vI-l3AM76hZ-vaA,26435
+flexCommunicator/clientLibraries/flcpy/communication/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/contracts/contractVariable.py,sha256=F5GMeKq879nyMaFGReqQ4QkUMUG74dveK0YCoJXtlSA,3440
+flexCommunicator/clientLibraries/flcpy/flexCloud/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/flexCloud/flexCloudConfiguration.py,sha256=4yEZTB3tQs0c8Zqi7f6iyZQM5_Gvy4aV4yiytW4BcAI,856
+flexCommunicator/clientLibraries/flcpy/flexCloud/flexCloudManager.py,sha256=CXc7fkfFf9XNjfOCYEsNNNOX-iavd8FuT-CSvMivt-o,5865
+flexCommunicator/clientLibraries/flcpy/flexCloud/flexCloudOrchestrator.py,sha256=_-6i37kpm4Knh0Um5ipG1eCk8dXMsr3SdqPRojKS1Vo,8399
+flexCommunicator/clientLibraries/flcpy/flexCloud/flexCloudVariable.py,sha256=Psg3_qjGekS_TCFgx6m_eGezyuAAyXo-ZJtw9VJByes,5474
+flexCommunicator/clientLibraries/flcpy/fmi/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/fmi/fmuNode.py,sha256=i1tycENalxlBBwmjspk-Q1x9MDROcswKnXmxOkefca4,7074
+flexCommunicator/clientLibraries/flcpy/fmi/node.py,sha256=qtnycbU68Lr6vximlbl_RGpcNlWejIz7SGtHlaK5ozk,11214
+flexCommunicator/clientLibraries/flcpy/knowledge/KnowledgeManager.py,sha256=mKWSoji9h-4mkET6QVitYwbEpuL7bJi-YOEti24mKAk,12038
+flexCommunicator/clientLibraries/flcpy/knowledge/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/logging/LoggingAndTracking.py,sha256=mGoGd1EVec3d5op_ZskZkltOLi5FAMNKHyHZ2J2X4e8,6253
+flexCommunicator/clientLibraries/flcpy/logging/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/messages/StandardizedMessages.py,sha256=WOaZmnwoeyuuZ5HdzFZ34G5o4m24Qpd0zz-kAcR9r9c,1778
+flexCommunicator/clientLibraries/flcpy/messages/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/security/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/security/security.py,sha256=ffXhHWR5J8ECVRKNihDNc6Y-AhMutLaYJvjrmSAAhWg,6539
+flexCommunicator/clientLibraries/flcpy/service/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/service/client.py,sha256=hI_NfbKd82Z8F_9wcI_IMK5xeJ_SbzZt33oudeiLQZU,2043
+flexCommunicator/clientLibraries/flcpy/service/service.py,sha256=9FVDD9TuRdm2VVMKcS2Ig_EfAlul8723PBuZ2pllxcc,1722
+flexCommunicator/clientLibraries/flcpy/transport/PropertyBinding.py,sha256=KlFz23EMzqked3emfuV6ZeoN6z3vluOM7Fm1xHvFwm0,3552
+flexCommunicator/clientLibraries/flcpy/transport/PropertyRegistry.py,sha256=A2A7pNNRc4AL18ZYNEpW6OtgBec-QLnoU5kXzyANed0,5891
+flexCommunicator/clientLibraries/flcpy/transport/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/utils/Timer.py,sha256=5NFUT_huVvJaKhHTA69tt6zroLKb3BVoTg_XxVlB38U,519
+flexCommunicator/clientLibraries/flcpy/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/utils/auxiliary.py,sha256=TvF9KowM9L5_9Fpiht-U2mjm0tgX2wlVNFt7KuN96BU,7749
+flexCommunicator/clientLibraries/flcpy/utils/constants.py,sha256=FM5Q2YeYyVlCrALPKOA5d0YM9tXDXcIRVaK8jFId4TA,8480
+flexCommunicator/clientLibraries/flcpy/utils/decorators.py,sha256=eQWdFiD0XYVJ4SFsgEKwFhjR7AiVbhu-wmzxouO4wi8,3079
+flexCommunicator/clientLibraries/flcpy/validityFrame/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flexCommunicator/clientLibraries/flcpy/validityFrame/runtimeMonitor.py,sha256=lcFAYVinCutY2L0zbnCJS7IckFD74uWmgQBxhl1Nylg,4111
+flexCommunicator/clientLibraries/flcpy/validityFrame/validityFrameManager.py,sha256=l1JMD3wchylq3SUcW0r1P1M-8UVWBjavqKnVtbPQW5Q,41105
+flexcommunicator-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+flexcommunicator-0.1.0.dist-info/METADATA,sha256=Mljd0IpSQkWsXOVJztcL8Icif9IPuoxO4Mbc5bnCo4o,37824
+flexcommunicator-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flexcommunicator-0.1.0.dist-info/top_level.txt,sha256=J0BQPoAI-s-VjQ651vwrARTlor32OhOPZbaiWVYL5zQ,17
+flexcommunicator-0.1.0.dist-info/RECORD,,

flexcommunicator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+