Feature command mode (#3)

* add command mode feature and improvements: * add support to wait for act_con and act_term response * free response map if result is not awaited * simplify test certificate generation without prompt * update changelog, readme and linter config * fix readthedocs build * fix read command success detection * enhance code documentation
Fraunhofer-FIT-DIEN · Jan 30, 2024 · 94a3a6e · 94a3a6e
1 parent 8490a72
commit 94a3a6e
Show file tree

Hide file tree

Showing 46 changed files with 962 additions and 501 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,20 @@
+# Read the Docs configuration file for Sphinx projects
+
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,17 @@
 # Change log
 
+## v1.17
+
+- Add optional feature **Select-And-Execute** (also called Select-Before-Execute)
+  - Add enum c104.CommandMode
+  - Add properties point.command_mode, point.selected_by and incomingmessage.is_select_command
+  -  on_receive callback argument previous_state contains key selected_by
+  - Add select field to explain_bytes and explain_bytes_dict
+
+- Fix free command response state key if command was never send
+- Improve point transmission handling
+- Improve documentation
+
 ## v1.16
 
 - Add feature TLS (working versions: SSLv3.0, TLSv1.0, TLSv1.1, TLSv1.2; not working: TLSv1.3)

diff --git a/README.md b/README.md
@@ -49,13 +49,13 @@ command_point = station.add_point(io_address=12, type=c104.Type.C_RC_TA_1)
 client.start()
 ```
 
-See [examples](examples) folder for more detailed examples.
+See [examples](https://github.com/Fraunhofer-FIT-DIEN/iec104-python/tree/main/examples) folder for more detailed examples.
 
 ## Licensing
 
 This software is licensed under the GPLv3 (https://www.gnu.org/licenses/gpl-3.0.en.html).
 
-See [LICENSE](LICENSE) file for the complete license text.
+See [LICENSE](https://github.com/Fraunhofer-FIT-DIEN/iec104-python/blob/main/LICENSE) file for the complete license text.
 
 ### Dependencies
 
@@ -107,7 +107,7 @@ The library is used as testing framework for test-automation.
 * Debian/Ubuntu (x64): YES >= 20.04
 * Raspbian (arm32v7): YES
 * Windows (x64): YES
-* Raspbian (aarch64): Not yet
+* Raspbian (aarch64): Not yet tested
 
 ### Python versions
 * python >= 3.6, < 3.11
@@ -117,25 +117,25 @@ Please adjust the version number to the latest version or use a specific version
 
 ### Install from pypi.org
 ```bash
-python3 -m pip install c104~=1.16.0
+python3 -m pip install c104~=1.17.0
 ```
 
-### Install from git
+### Install from git with tag
 ```bash
-python3 -m pip install c104@git+https://github.com/fraunhofer-fit-dien/iec104-python.git@v1.16.0
+python3 -m pip install c104@git+https://github.com/fraunhofer-fit-dien/iec104-python.git@v1.17.0
 ```
 
-## Wiki
+## Documentation
 
-Read more about the **Classes** and their **Properties** in our [project Wiki](https://iec104-python.readthedocs.io/python/index.html).
+Read more about the **Classes** and their **Properties** in our [read the docs documentation](https://iec104-python.readthedocs.io/python/index.html).
 
 ## Contribution
 
 ### How to contribute
 
 1. Add feature requests and report bugs using GitHub's issues
 
-1. Create merge requests
+1. Create pull requests
 
 ### How to build for multiple python versions (linux with docker)
 
@@ -209,4 +209,4 @@ Read more about the **Classes** and their **Properties** in our [project Wiki](h
 
 ## Change log
 
-Track all changes in our [CHANGELOG](CHANGELOG.md) documentation.
+Track all changes in our [CHANGELOG](https://github.com/Fraunhofer-FIT-DIEN/iec104-python/blob/main/CHANGELOG.md) documentation.
diff --git a/bin/build-docs.py b/bin/build-docs.py
@@ -1,5 +1,13 @@
+#!/usr/bin/env python3
+
 from pathlib import Path
-from sphinx.cmd.build import main
+try:
+    from sphinx.cmd.build import main
+except ImportError:
+    import sys
+    print('Please install requirements first:\npython3 -m pip install -r docs/requirements.txt')
+    sys.exit(1)
+
 
 # path variables
 PROJECT_DIR = Path(__file__).parent.parent

diff --git a/bin/gen-certs.sh b/bin/gen-certs.sh
@@ -7,19 +7,24 @@ cd "$DIR" || exit 1
 
 echo "ROOT CA"
 openssl genrsa -out ca.key 4096
-openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.crt
+openssl req -x509 -new -nodes -key ca.key -sha256 -subj '/CN=Local Test Certificate Authority' -days 3650 -out ca.crt
 
-echo "SERVER"
-openssl genrsa -out server.key 4096
-openssl req -new -key server.key -out server.csr
-openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -sha256 -days 3650
+echo "SERVER1"
+openssl genrsa -out server1.key 4096
+openssl req -new -key server1.key -out server1.csr -subj '/CN=Local Test Server 1'
+openssl x509 -req -in server1.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server1.crt -sha256 -days 3650
+
+echo "SERVER2"
+openssl genrsa -out server2.key 4096
+openssl req -new -key server2.key -out server2.csr -subj '/CN=Local Test Server 2'
+openssl x509 -req -in server2.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server2.crt -sha256 -days 3650
 
 echo "CLIENT1"
 openssl genrsa -out client1.key 4096
-openssl req -new -key client1.key -out client1.csr
+openssl req -new -key client1.key -out client1.csr -subj '/CN=Local Test Client 1'
 openssl x509 -req -in client1.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client1.crt -sha256 -days 3650
 
 echo "CLIENT2"
 openssl genrsa -out client2.key 4096
-openssl req -new -key client2.key -out client2.csr
+openssl req -new -key client2.key -out client2.csr -subj '/CN=Local Test Client 2'
 openssl x509 -req -in client2.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client2.crt -sha256 -days 3650
diff --git a/bin/linux-build.sh b/bin/linux-build.sh
diff --git a/bin/profiler.sh b/bin/profiler.sh
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1,4 @@
 breathe==4.35.0
 cmake==3.26.3
 sphinx-autodoc-typehints==1.23.0
+sphinx-rtd-theme==2.0.0
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -10,11 +10,11 @@
 # -- Project information -----------------------------------------------------
 
 project = "iec104-python"
-copyright = "2020-2023, Fraunhofer Institute for Applied Information Technology FIT"
+copyright = "2020-2024, Fraunhofer Institute for Applied Information Technology FIT"
 author = "Martin Unkel <martin.unkel@fit.fraunhofer.de>"
 
 release = "1.0"
-version = "1.16.0"
+version = "1.17.0"
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/source/core/enums/responsestate.rst → ...ource/core/enums/commandresponsestate.rst b/docs/source/core/enums/responsestate.rst → ...ource/core/enums/commandresponsestate.rst
@@ -1,5 +1,5 @@
-ResponseState
+CommandResponseState
 ======================================================================
 
-.. doxygenenum:: ResponseState
+.. doxygenenum:: CommandResponseState
    :project: iec104-python
diff --git a/docs/source/core/enums/commandtransmissionmode.rst b/docs/source/core/enums/commandtransmissionmode.rst
@@ -0,0 +1,5 @@
+CommandTransmissionMode
+======================================================================
+
+.. doxygenenum:: CommandTransmissionMode
+   :project: iec104-python
diff --git a/docs/source/core/enums/debug.rst b/docs/source/core/enums/debug.rst
@@ -8,4 +8,5 @@ Quality
 InformationType
 ConnectionState
 ConnectionInit
-ResponseState
+CommandResponseState
+CommandTransmissionMode
diff --git a/docs/source/core/enums/index.rst b/docs/source/core/enums/index.rst
@@ -13,4 +13,5 @@ List
    informationtype
    connectionstate
    connectioninit
-   responsestate
+   commandresponsestate
+   commandtransmissionmode
diff --git a/docs/source/python/enum/commandmode.rst b/docs/source/python/enum/commandmode.rst
@@ -0,0 +1,8 @@
+.. _c104.CommandMode:
+
+CommandMode
+#############
+
+.. autoclass:: c104.CommandMode
+   :members:
+   :noindex:
diff --git a/docs/source/python/enum/index.rst b/docs/source/python/enum/index.rst
@@ -4,6 +4,7 @@ Enums
 .. toctree::
    :maxdepth: 4
 
+   commandmode
    connectionstate
    cot
    data

diff --git a/examples/simple_client.py b/examples/simple_client.py
@@ -29,7 +29,7 @@ def main():
     print("read")
     print("read")
     if point.read():
-        print("-> SUCCESS")
+        print(f"-> SUCCESS {point.value}")
     else:
         print("-> FAILURE")
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -6,3 +6,8 @@ requires = [
     "cmake>=3.12",
 ]
 build-backend = "setuptools.build_meta"
+
+[tool.black]
+line-length = 120
+target-version = ['py36', 'py37', 'py38', 'py39', 'py310']
+skip-string-normalization = true
diff --git a/setup.py b/setup.py
@@ -130,7 +130,7 @@ def build_extension(self, ext: CMakeExtension) -> None:
 
 setup(
     name="c104",
-    version="1.16.1",
+    version="1.17.0",
     author="Martin Unkel, Fraunhofer FIT",
     author_email="martin.unkel@fit.fraunhofer.de",
     description="iec104-python",

diff --git a/src/Client.h b/src/Client.h
@@ -166,7 +166,9 @@ class Client : public std::enable_shared_from_this<Client> {
    * @brief Create a new remote connection handler instance that acts as a
    * client
    * @details create a map of possible connections
+   * @param tick_rate_ms intervall in milliseconds between the client checks connection states
    * @param timeout_ms timeout in milliseconds before an inactive connection
+   * @param transport_security communication encryption instance reference
    * gets closed
    */
   Client(std::uint_fast32_t tick_rate_ms, std::uint_fast32_t timeout_ms,