Co-authored-by: Kerstin Keller <[email protected]…

….github.com>

Co-authored-by: Kristof Hannemann <[email protected]>

eCAL v5.5.1:
* eCAL python language binding added
  * ecal core wrapped to python
  * ecal hdf5 measurement API wrapped to python
  * python samples added

CMakeLists.txt

@@ -43,6 +43,7 @@ option(BUILD_DOCS                              "Build the eCAL documentation"
 option(BUILD_APPS                              "Build the eCAL applications"                                       ON)
 option(BUILD_SAMPLES                           "Build the eCAL samples"                                            ON)
 option(BUILD_TIME                              "Build the eCAL time interfaces"                                    ON)
+option(BUILD_PY_BINDING                        "Build eCAL python binding"                                        OFF)
 option(ECAL_LAYER_FASTRTPS                     "Provide fast rtps as communication layer"                         OFF)
 option(ECAL_LAYER_ICEORYX                      "Provide iceoryx as communication layer"                           OFF)
 
@@ -51,12 +52,12 @@ option(ECAL_INSTALL_SAMPLE_SOURCES             "Install the sources of eCAL samp
 option(ECAL_JOIN_MULTICAST_TWICE               "Specific Multicast Network Bug Workaround"                        OFF)
 option(ECAL_NPCAP_SUPPORT                      "Enable the eCAL Npcap Receiver (i.e. the Win10 performance fix)"  OFF)
 
-
 # Set option regarding third party library builds
 option(ECAL_THIRDPARTY_BUILD_CMAKE_FUNCTIONS   "Build CMakeFunctions with eCAL"                                    ON)
 option(ECAL_THIRDPARTY_BUILD_PROTOBUF          "Build Protobuf with eCAL"                                          ON)
 option(ECAL_THIRDPARTY_BUILD_SPDLOG            "Build spdlog with eCAL"                                            ON)
 
+set(ECAL_INSTALL_PYTHON_DIR "bin" CACHE PATH "Location to install the Python extension modules. Might be set by setupdtools install.")
 
 # there is a CMake issue with testing threading availibility via TEST_RUN
 if(${CMAKE_CROSSCOMPILING})
@@ -105,6 +106,7 @@ if (ECAL_THIRDPARTY_BUILD_PROTOBUF)
     # reset CMAKE_CXX_FLAGS variable
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS_OLD}")
   endif()
+  set(Protobuf_VERSION 3.5.1)
 endif()
 
 if (ECAL_THIRDPARTY_BUILD_SPDLOG)
@@ -143,6 +145,7 @@ set(eCAL_VERSION        ${eCAL_VERSION_STRING})
 include(helper_functions/ecal_add_functions)
 include(helper_functions/ecal_helper_functions)
 include(helper_functions/ecal_install_functions)
+include(helper_functions/ecal_python_functions)
 include(build_location)
 
 if(MSVC)
@@ -261,6 +264,7 @@ if(WIN32)
   set(eCAL_install_samples_src_dir       samples/src/)
   set(eCAL_install_tests_dir             tests)
 endif()
+set(BUILD_DEPLOY_DIRECTORY ${CMAKE_BINARY_DIR}/_deploy)
 
 set(THREADS_PREFER_PTHREAD_FLAG ON)
 
@@ -324,6 +328,13 @@ if(HAS_HDF5)
   add_subdirectory(contrib/message)
 endif()
 
+# --------------------------------------------------------
+# ecal core python binding
+# --------------------------------------------------------
+if(BUILD_PY_BINDING)
+  add_subdirectory(lang/python)
+endif()
+
 # --------------------------------------------------------
 # console applications
 # --------------------------------------------------------

README.md

@@ -63,6 +63,8 @@ eCAL is using CMake as build system. When configuring with CMake, you can turn o
   Build the eCAL sample applications
 - `BUILD_TIME`, default `ON`
   Build the eCAL time interfaces, necessary if you want to use ecal in time synchronized mode (based on ptp for example)
+- `BUILD_PY_BINDING`, default `OFF`
+  Build the eCAL python language binding
 - `ECAL_LAYER_FASTRTPS`, default `OFF`
   Provide fast rtps as communication layer, requires fast-rtps and fast-cdr installations
 - `ECAL_LAYER_ICEORYX`, default `OFF`
@@ -118,6 +120,13 @@ All options can be passed on the command line `cmake -D<option>=<value>` or in t
 	sudo apt-get -y install git cmake doxygen graphviz build-essential zlib1g-dev qt5-default libhdf5-dev libprotobuf-dev libprotoc-dev protobuf-compiler
 	```
 
+3. If you plan to create the eCAL python language extension (here as an example for the pythonm 3.6 version):
+	```bash
+	sudo apt-get install python3.6-dev
+	sudo apt-get install python3-pip
+	python3 -m pip install setuptools
+	```
+
 ### Compile eCAL
 1. Check out the repository as described [here](#checkout-the-repository).
 2. Compile eCAL:
@@ -132,6 +141,12 @@ All options can be passed on the command line `cmake -D<option>=<value>` or in t
 	cpack -G DEB
 	sudo dpkg -i eCAL-*
 	```
+3. Create and install the eCAL python egg:
+	```bash
+	cmake --build . --target create_python_egg --config Release
+	sudo python3 -m easy_install ecal-*
+	```
+
 ### UDP network configuration
 
 setup the correct ip address - here for adapter eth0, ip address 192.168.0.1
@@ -189,14 +204,16 @@ sudo gedit /etc/network/interfaces
 	HDF5_DIR = C:\Program Files\HDF_Group\HDF5\1.8.21\cmake
 	```
 
-4. Checkout the eCAL repository as described [here](#checkout-the-repository). Note that it has **submodules**, so use [Git for Windows](https://git-scm.com/download/win) to check out the repo.
+4. Install [Python for Windows](https://www.python.org/downloads/) (64 Bit, Version 3.x) if you plan to build the eCAl python language extension.
+
+5. Checkout the eCAL repository as described [here](#checkout-the-repository). Note that it has **submodules**, so use [Git for Windows](https://git-scm.com/download/win) to check out the repo.
 
 #### Build eCAL
 
-Run the following batch files to create the Visual Studio 2015 (2017 | 2019) solutions for 32 and 64 bit and to build both.
+Run the following batch files to create the Visual Studio 2015 (2017, 2019) solutions for 32 and 64 bit and to build both.
 
 ```bat
-build_win\win_make_cmake.bat v140 (v141 | v142)
+build_win\win_make_cmake.bat v140 (v141, v142)
 build_win\win_make_build.bat
 ```
 
@@ -214,7 +231,21 @@ If you installed all mentioned tools and dependencies correctly you can also sim
 win_make_all.bat
 ```
 
-to cmake eCAL build all configurations and create an installer. You will find the installer in the _setup subfolder finally.
+to cmake eCAL build all configurations and create an installer. You will find the installer in the _deploy subfolder inside your build folder finally.
+
+#### Create eCAL python extension
+
+If you configured cmake to build the python extension by setting `BUILD_PY_BINDING` to `ON` you can create the ecal python egg by calling
+
+```bat
+build_win\win_make_python_egg.bat
+```
+
+Afterwards you will find the python eCAL egg in the _deploy subfolder inside your build folder. Install the extesnion by
+
+```bat
+python -m easy_install ecal-X.Y.Z-pyX.Y.egg
+```
 
 ### UDP network configuration
 
@@ -968,6 +999,97 @@ int main(int argc, char **argv)
 }
 ```
 
+### Python
+
+#### The Publish-Subscribe Pattern
+
+The eCAL API is fully wrapped into python script language. The usage is quite simple ('help ecal' in your python shell ;-)). You can find samples for all common use cases in the eCAL installation. Let's demonstrate the famous publish-subscribe "hello world".
+
+##### Listing 17
+
+```python
+import sys
+import time
+
+# import ecal core and string publishing
+import ecal.core.core as ecal_core
+from ecal.core.publisher import StringPublisher
+
+# initialize eCAL API
+ecal_core.initialize(sys.argv, "minimal python publisher")
+
+# create publisher
+pub = StringPublisher("foo")
+msg = "HELLO WORLD FROM PYTHON"
+
+# sending hello's
+while ecal_core.ok():
+  pub.send(current_message)
+  time.sleep(0.01)
+
+# finalize eCAL API
+ecal_core.finalize()
+```
+
+eCAL is wrapped into python in different packages. ecal.core contains all basic functionalities, ecal.core.publisher and ecal.core.subscriber the publish/subscribe interface. In listing 17 we use a simple string publisher. After initializing the core in line 9 we instanciate a publisher with the topic name "foo" and start pubishing a hello message every 10 ms. This sample is fully communication compatible to the c++ hello world subscribers in the Listings 1-4.
+
+##### Listing 18
+
+```python
+import sys
+
+# import ecal core and string subscribing
+import ecal.core.core as ecal_core
+from ecal.core.subscriber import StringSubscriber
+
+# initialize eCAL API
+ecal_core.initialize(sys.argv, "minimal python subscriber")
+
+# create subscriber
+sub = StringSubscriber("foo")
+
+# receive messages
+while ecal_core.ok():
+  ret, msg, time = sub.receive(500)
+  if ret > 0: print("Received:  {} ms   {}".format(time, msg))
+  else:       print("Subscriber timeout ..")
+
+# finalize eCAL API
+ecal_core.finalize()
+
+```
+
+Listing 18 shows the python variant of the hello world subscriber. It uses a 500 ms blocking receive call to get the payload in the python msg variable and print it out. Finally Listing 19 shows the python hello world subscriber realized with a receive callback function.
+
+##### Listing 19
+
+```python
+import sys
+import time
+
+# import ecal core and string subscribing
+import ecal.core.core as ecal_core
+from ecal.core.subscriber import StringSubscriber
+
+# eCAL receive callback
+def onreceive(topic_name, msg, time):
+  print("Received:  {} ms   {}".format(time, msg))
+
+# initialize eCAL API
+ecal_core.initialize(sys.argv, "minimal python subscriber (callback)")
+
+# create subscriber and connect callback
+sub = StringSubscriber("foo")
+sub.set_callback(onreceive)
+
+# idle main thread
+while ecal_core.ok():
+  time.sleep(0.1)
+
+# finalize eCAL API
+ecal_core.finalize()
+```
+
 ## Command Line Interface
 
 If you pass the argc, argv command line arguments to the eCAL::Initialize API function (see Listing 23) you can set / overwrite all eCAL runtime parameter defined in the eCAL parameter ini file (ecal.ini). Moreover you can force your application to not load the default eCAL ini file but to specify your own parameter file for the system wide default settings.

build_win/win_make_python_egg.bat

@@ -0,0 +1,11 @@
+@echo off
+
+pushd %~dp0\..
+
+call build_win\win_set_vars.bat
+
+cd /d %BUILD_DIR%
+
+cmake --build . --target create_python_egg --config Release
+
+popd

cmake/helper_functions/ecal_python_functions.cmake

@@ -0,0 +1,112 @@
+# ========================= eCAL LICENSE =================================
+#
+# Copyright (C) 2016 - 2019 Continental Corporation
+#
+# 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.
+#
+# ========================= eCAL LICENSE =================================
+
+set(PYTHON_BINARY_DIR        ${CMAKE_BINARY_DIR}/python)
+set(PYTHON_BINARY_MODULE_DIR ${CMAKE_BINARY_DIR}/python/ecal)
+
+#! ecal_add_python_module : this function adds a python module
+#
+# This function
+#
+# \arg:TARGET_NAME the first argument
+# \param:SOURCES SOURCES specify the fooness of the function
+# \param:PYTHON_CODE PYTHON_CODE should always be 42
+# \group:GROUP1 GROUP1 is a list of project to foo
+#
+function(ecal_add_python_module TARGET_NAME)
+
+  set(multiValueArgs SOURCES)
+  set(singleValueArgs PYTHON_CODE)
+  cmake_parse_arguments(ARGUMENTS
+      ""
+      "${singleValueArgs}"
+      "${multiValueArgs}" ${ARGN} )
+
+  if(NOT ARGUMENTS_SOURCES AND NOT ARGUMENTS_PYTHON_CODE)
+    message(ERROR "Error in ecal_add_python_module: Please specify SOURCES and / or PYTHON_CODE arguments")
+  endif()
+
+
+  # if Sources are specified, a library is created
+  if(ARGUMENTS_SOURCES)
+    Python_add_library(${TARGET_NAME} MODULE ${ARGUMENTS_SOURCES})
+    set_target_properties(${TARGET_NAME}
+        PROPERTIES
+        PREFIX ""
+        LIBRARY_OUTPUT_DIRECTORY_DEBUG "${PYTHON_BINARY_MODULE_DIR}"
+        LIBRARY_OUTPUT_DIRECTORY_RELEASE "${PYTHON_BINARY_MODULE_DIR}"        
+        LIBRARY_OUTPUT_DIRECTORY "${PYTHON_BINARY_MODULE_DIR}"
+        DEBUG_POSTFIX "_d"
+        )
+  # if no sources are specified, then a custom target needs to be created
+  else()
+    add_custom_target(${TARGET_NAME} ALL
+        COMMENT "Custom python target: ${TARGET_NAME}")
+  endif()
+
+  if(ARGUMENTS_PYTHON_CODE)
+    # Copy all files from the source folder to the python binary directory.
+    get_filename_component(absolute_folder_python_files ${ARGUMENTS_PYTHON_CODE} ABSOLUTE)
+    file(GLOB_RECURSE relative_python_files
+     RELATIVE ${absolute_folder_python_files}
+     LIST_DIRECTORIES false
+     CONFIGURE_DEPENDS
+     ${absolute_folder_python_files}/*.py)
+
+    foreach (f ${relative_python_files})  
+      set(origin_file ${absolute_folder_python_files}/${f})
+      set(destination_file ${PYTHON_BINARY_MODULE_DIR}/${f})
+      configure_file(${origin_file} ${destination_file} COPYONLY) 
+    endforeach()
+  endif()
+endfunction()
+
+function(ecal_add_pybind11_module TARGET_NAME)
+  set(multiValueArgs SOURCES)
+  set(singleValueArgs PYTHON_CODE)
+  cmake_parse_arguments(ARGUMENTS
+      ""
+      "${singleValueArgs}"
+      "${multiValueArgs}" ${ARGN} )
+
+  if(NOT ARGUMENTS_SOURCES AND NOT ARGUMENTS_PYTHON_CODE)
+    message(ERROR "Error in ecal_add_python_module: Please specify SOURCES and / or PYTHON_CODE arguments")
+  endif()
+
+
+  pybind11_add_module(${TARGET_NAME} ${ARGUMENTS_SOURCES})
+  set_target_properties(${TARGET_NAME}
+    PROPERTIES
+    PREFIX ""
+    LIBRARY_OUTPUT_DIRECTORY_DEBUG "${PYTHON_BINARY_MODULE_DIR}"
+    LIBRARY_OUTPUT_DIRECTORY_RELEASE "${PYTHON_BINARY_MODULE_DIR}"
+    LIBRARY_OUTPUT_DIRECTORY "${PYTHON_BINARY_MODULE_DIR}"
+    DEBUG_POSTFIX "_d"
+  )
+
+  if(ARGUMENTS_PYTHON_CODE)
+    add_custom_command(
+        TARGET ${TARGET_NAME}
+        PRE_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy_directory ${ARGUMENTS_PYTHON_CODE} ${PYTHON_BINARY_MODULE_DIR}
+    )
+  endif()
+endfunction ()
+
+function(ecal_install_python_module)
+endfunction()

cpack/cpack_variables.cmake

@@ -10,7 +10,7 @@ set(CPACK_PACKAGE_VERSION_PATCH ${GIT_REVISION_PATCH})
 set(CPACK_PACKAGE_INSTALL_DIRECTORY ${PROJECT_NAME})
 set(CPACK_PACKAGE_CONTACT "[email protected]")
 set(CPACK_SOURCE_STRIP_FILES "")
-
+SET(CPACK_OUTPUT_FILE_PREFIX _deploy)
 
 
 if(WIN32)