es-ude · DavidFederl · May 14, 2025 · May 14, 2025
diff --git a/C/CONTRIBUTION.md b/C/CONTRIBUTION.md
@@ -0,0 +1,121 @@
+# Contributing
+
+## Set Up
+
+> [!IMPORTANT]
+> This Guide assumes you are using a UNIX-like System and have `git` already installed!
+
+### Get the Source Code
+
+At first, you have to download the source code from GitHub.
+This can be archived by running
+
+```bash
+git clone https://github.com/es-ude/elastic-ai.Protocol.git eaip  # Download the Repository
+cd eaip                                                            # Move inside the repository
+```
+
+in your shell.
+
+### Required Tools
+
+- **[GCC](https://gcc.gnu.org/)**
+  -> C Compiler
+  Can be installed via your local package manager like dnf, apt or brew.
+- **[CMake](https://cmake.org)**
+  -> Build System
+  Can be installed via your local package manager like dnf, apt or brew.
+- **[Ninja](https://ninja-build.org/)**
+  -> Build Tool
+  Can be installed via your local package manager like dnf, apt or brew.
+- **[Astral-UV](https://docs.astral.sh/uv/) [OPTIONAL]**
+  -> Python Runtime/Package Manager
+  Can be installed via your local package manager like dnf, apt or brew.
+- **[NodeJS](https://nodejs.org/en) [OPTIONAL]**
+  -> Javascript Runtime/Package Manager
+  Can be installed via your local package manager like dnf, apt or brew.
+
+#### Python Environment [OPTIONAL]
+
+> [!NOTE]
+> The Python environment is only required if you want to use pre-commit.
+
+To minimize the potential corruption of your system we recommend installing the dependencies inside
+a [virtual environment](https://python.land/virtual-environments/virtualenv#How_to_create_a_Python_venv).
+The python environment can be created and prepared by running:
+
+```bash
+uv venv .venv              # create a virtual python environment under `.venv/`
+source .venv/bin/activate  # load the virtual environment
+uv sync --group pre-commit # install all python dependencies
+```
+
+> [!TIP]
+> To use pre-commit for [conventional commit checks](documentation/CONTRIBUTION.md#contribution-guidelines) run
+>
+> ```bash
+> uv run pre-commit install --install-hooks
+> ```
+>
+> after initializing the Python environment
+
+> [!IMPORTANT]
+> To be able to use pre-commit and the other python tools you have to load the virtual python environment or execute the
+> script with uv
+>
+> > [!TIP]
+> > Use a tool like [direnv](https://direnv.net/) to automatically set up your environment when entering the folder
+> > inside your shell!
+
+### Compile the Source Code
+
+> [!NOTE]
+> This project is based on CMake.
+
+We provide one predefined profile with the [CMakePresets.json](CMakePresets.json):
+
+- host
+
+This profile provide the required settings to build for your local system (_host_) to locally run the tests.
+
+To initialize the CMake run:
+
+```bash
+cmake --preset host
+```
+
+> [!WARNING]
+> This may take a while because all required external dependencies are loaded from the internet.
+> See [external dependencies](#external-dependencies).
+
+### Local Test Execution
+
+The local execution of the unit tests is possible via the `ctest` function as follows:
+
+```bash
+ctest --preset unit_test
+```
+
+> [!NOTE]
+> The unit-test executables can then be found under [build/host/test/unit](build/host/test/unit).
+
+## Contribute your Changes
+
+Do **not** push your changes directly to the `main` branch.
+Push your modification to a new branch and open a pull request to `main`, so that the maintainers of this repository can
+review your modifications and merge them.
+
+## External Dependencies
+
+> [!IMPORTANT]
+> These dependencies will automatically be downloaded and initialized by CMake!
+
+Following external dependencies are used by this project:
+
+- [ThrowTheSwitch/CException](https://github.com/ThrowTheSwitch/CException)
+- [ThrowTheSwitch/Unity](https://github.com/ThrowTheSwitch/Unity)
+
+## Troubleshooting
+
+- To generate a clean CMake Build without deleting and reinitializing the build directory run
+  `cmake --build <build_dir> --target clean`.
diff --git a/C/README.md b/C/README.md
@@ -0,0 +1,16 @@
+# EAIP: C
+
+## Include via `CMakeFetchContent`
+
+To include this project with the `CMakeFetchContent` directives you can paste the following code snippet to your `CMakeLists.txt`
+
+```text
+FetchContent_Declare(
+        elasticai_protocol
+        GIT_REPOSITORY https://github.com/es-ude/elastic-AI.protocol.git
+        GIT_TAG v3.1.0)
+FetchContent_MakeAvailable(elasticai_protocol)
+```
+
+> [!IMPORTANT]
+> Update the tag inside the `FetchContent_Declare` directive if you want to use a different version of the elastic-AI protocol implementation.
diff --git a/PROTOCOL.md b/PROTOCOL.md
@@ -1,4 +1,4 @@
-# elastic-AU Protocol
+# elastic-AI Protocol
 
 The elastic-AI protocol (EAIP) provides a specification of a pub-sub-protocol.
 It is designed to work with MQTT, but this is **not** mandatory.
@@ -60,7 +60,9 @@ eiap://<base_domain>/<device_id>/<message_type>[/<type_dependent>]
   - The offline message is automatically sent by the broker after a connection loss (LWT).
   - The order of the data fields is arbitrary and not defined
 
-> [!NOTE] **Example message**
+> [!NOTE]
+>
+> **Example message**
 >
 > **Online Message of a elastic Node instance:**
 >
@@ -94,16 +96,18 @@ sequenceDiagram
 ### START
 
 - **Topic**
-   `eaip://<base_domain>/<device_id>/START/<data_id>`
+  `eaip://<base_domain>/<device_id>/START/<data_id>`
   - `<device_id>`: identifier of the participant to request data from
   - `<data_id>`: identifier of the data to request
 - **Message**
-   `device_id` of the requesting participant
+  `device_id` of the requesting participant
 - **Information**
   - Provider subscribes to topic to receive requests
   - Provided `data_id` can be published with an additional status field
 
-> [!NOTE] **Example message**
+> [!NOTE]
+>
+> **Example message**
 >
 > ```text
 > pub(topic="eaip://uni-due.de/es/client1/START/timer",msg="client2")
@@ -112,13 +116,15 @@ sequenceDiagram
 ### STOP
 
 - **Topic**
-   `eaip://<base_domain>/<object_id>/STOP/<data_id>`
+  `eaip://<base_domain>/<object_id>/STOP/<data_id>`
   - `<device_id>`: identifier of the participant to request data from
   - `<data_id>`: identifier of the data to request
 - **Message**
-   `device_id` of the requesting participant
+  `device_id` of the requesting participant
 
-> [!NOTE] **Example message**
+> [!NOTE]
+>
+> **Example message**
 >
 > ```text
 > pub(topic="eaip://uni-due.de/es/client1/STOP/timer",msg="client2")
@@ -127,15 +133,17 @@ sequenceDiagram
 ### DATA
 
 - **Topic**
-   `eip://<base_domain>/<device_id>/DATA/<data_id>`
+  `eip://<base_domain>/<device_id>/DATA/<data_id>`
   - `<device_id>`: identifier of the participant publishing data
   - `<data_id>`: identifier of the data to request
 - **Message**
-   Value encoded as a string
+  Value encoded as a string
 - **Information**
   - Interested participants can subscribe to this topic to receive new data
 
-> [!NOTE] **Example message**
+> [!NOTE]
+>
+> **Example message**
 >
 > ```text
 > pub(topic="eaip://uni-due.de/es/client1/DATA/light",msg="30.7")
@@ -194,13 +202,15 @@ sequenceDiagram
 ### DO
 
 - **Topic**
-   `eip://<base_domain>/<device_id>/DO/<command>`
+  `eip://<base_domain>/<device_id>/DO/<command>`
   - `<device_id>`: identifier of the participant publishing data
   - `<command>`: command to run
 - **Message**
-   command specific data
+  command specific data
 
-> [!NOTE] **Example message**
+> [!NOTE]
+>
+> **Example message**
 >
 > ```text
 > pub(topic="eaip://uni-due.de/es/client1/DO/led/01",msg="ON")
@@ -223,13 +233,15 @@ sequenceDiagram
 ### DONE
 
 - **Topic**
-   `eip://<base_domain>/<device_id>/DONE/<command>`
+  `eip://<base_domain>/<device_id>/DONE/<command>`
   - `<device_id>`: identifier of the participant publishing data
   - `<command>`: command to respond to
 - **Data**
-   command specific
+  command specific
 
-> [!NOTE] **Example message**
+> [!NOTE]
+>
+> **Example message**
 >
 > ```text
 > pub(topic="eip://uni-due.de/es/client1/DONE/led/1",msg="ON")

diff --git a/Python/CONTRIBUTION.md b/Python/CONTRIBUTION.md
@@ -0,0 +1,67 @@
+# Contributing
+
+## Set Up
+
+> [!IMPORTANT]
+> This Guide assumes you are using a UNIX-like System and have `git` already installed!
+
+### Get the Source Code
+
+At first, you have to download the source code from GitHub.
+This can be archived by running
+
+```bash
+git clone https://github.com/es-ude/elastic-AI.Protocol.git eaip  # Download the Repository
+cd eaip                                                            # Move inside the repository
+```
+
+in your shell.
+
+### Required Tools
+
+- **[Astral-UV](https://docs.astral.sh/uv/)**
+  -> Python Runtime/Package Manager
+  Can be installed via your local package manager like dnf, apt or brew.
+
+#### Python Environment
+
+To minimize the potential corruption of your system we recommend installing the dependencies inside
+a [virtual environment](https://python.land/virtual-environments/virtualenv#How_to_create_a_Python_venv).
+The python environment can be created and prepared by running:
+
+```bash
+uv venv .venv              # create a virtual python environment under `.venv/`
+source .venv/bin/activate  # load the virtual environment
+uv sync --all-groups       # install all python dependencies
+```
+
+> [!TIP]
+> To use pre-commit for [conventional commit checks](documentation/CONTRIBUTION.md#contribution-guidelines) run
+>
+> ```bash
+> uv run pre-commit install --install-hooks
+> ```
+>
+> after initializing the Python environment
+
+> [!IMPORTANT]
+> To be able to use pre-commit and the other python tools you have to load the virtual python environment or execute the
+> script with uv
+>
+> > [!TIP]
+> > Use a tool like [direnv](https://direnv.net/) to automatically set up your environment when entering the folder
+> > inside your shell!
+
+### Local Test Execution
+
+The local execution of the unit tests is possible via the `pytest` tool as follows:
+
+```bash
+uv run pytest
+```
+
+## Contribute your Changes
+
+Do **not** push your changes directly to the `main` branch.
+Push your modification to a new branch and open a pull request to `main`, so that the maintainers of this repository can
+review your modifications and merge them.
diff --git a/Python/README.md b/Python/README.md
@@ -0,0 +1,16 @@
+# EAIP: Python
+
+## Include via astral-uv
+
+To include this project with the uv package manger, include the following parts to your `pyproject.toml`:
+
+```toml
+[project]
+dependencies = [
+    ...
+    "elasticai_protocol",
+]
+
+[tool.uv.sources]
+elasticai_protocol = { git = "https://github.com/es-ude/elastic-AI.protocol.git", tag = "v.3.1.0" }
+```