[python] Nanobind eCAL Core binding (#2151)

Provide a feature complete Python API for ecal core using nanobind.

Co-authored-by: Arifulla Shariff <[email protected]>

Author: 2 people

.github/workflows/build-macos.yml

@@ -79,7 +79,7 @@ jobs:
         -DECAL_BUILD_APPS=ON \
         -DECAL_BUILD_SAMPLES=ON \
         -DECAL_BUILD_TIMEPLUGINS=ON \
-        -DECAL_BUILD_PY_BINDING=ON \
+        -DECAL_BUILD_PY_BINDING=OFF \
         -DECAL_BUILD_CSHARP_BINDING=OFF \
         -DECAL_BUILD_TESTS=ON \
         -DECAL_INSTALL_SAMPLE_SOURCES=ON \

.github/workflows/build-ubuntu.yml

@@ -84,8 +84,10 @@ jobs:
           thirdparty/ecaludp/ecaludp \
           thirdparty/fineftp/fineftp-server \
           thirdparty/ftxui/ftxui \
+          thirdparty/nanobind/nanobind \
           thirdparty/qwt/qwt \
           thirdparty/recycle/recycle \
+          thirdparty/tsl-robin-map/tsl-robin-map \
           thirdparty/tcp_pubsub/tcp_pubsub \
           thirdparty/termcolor/termcolor
 

.gitmodules

@@ -49,3 +49,9 @@
 [submodule "thirdparty/ecaludp/ecaludp"]
 	path = thirdparty/ecaludp/ecaludp
 	url = https://github.com/eclipse-ecal/ecaludp.git
+[submodule "thirdparty/nanobind/nanobind"]
+	path = thirdparty/nanobind/nanobind
+	url = https://github.com/wjakob/nanobind.git
+[submodule "thirdparty/tsl-robin-map/tsl-robin-map"]
+	path = thirdparty/tsl-robin-map/tsl-robin-map
+	url = https://github.com/Tessil/robin-map.git

CMakeLists.txt

@@ -641,6 +641,7 @@ message(STATUS "ECAL_THIRDPARTY_BUILD_FINEFTP                       : ${ECAL_THI
 message(STATUS "ECAL_THIRDPARTY_BUILD_FTXUI                         : ${ECAL_THIRDPARTY_BUILD_FTXUI}")
 message(STATUS "ECAL_THIRDPARTY_BUILD_GTEST                         : ${ECAL_THIRDPARTY_BUILD_GTEST}")
 message(STATUS "ECAL_THIRDPARTY_BUILD_HDF5                          : ${ECAL_THIRDPARTY_BUILD_HDF5}")
+message(STATUS "ECAL_THIRDPARTY_BUILD_NANOBIND                      : ${ECAL_THIRDPARTY_BUILD_NANOBIND}")
 message(STATUS "ECAL_THIRDPARTY_BUILD_PROTOBUF                      : ${ECAL_THIRDPARTY_BUILD_PROTOBUF}")
 message(STATUS "ECAL_THIRDPARTY_BUILD_QWT                           : ${ECAL_THIRDPARTY_BUILD_QWT}")
 message(STATUS "ECAL_THIRDPARTY_BUILD_RECYCLE                       : ${ECAL_THIRDPARTY_BUILD_RECYCLE}")

cmake/submodule_dependencies.cmake

@@ -13,13 +13,15 @@ set(ecal_submodule_dependencies
   GTest
   HDF5
   #libssh2
+  nanobind
   Protobuf
   qwt
   recycle
   spdlog
   tclap
   tcp_pubsub
   termcolor
+  tsl-robin-map
   tinyxml2
   udpcap
   yaml-cpp

doc/rst/license/thirdparty_licenses.rst

@@ -149,6 +149,11 @@ They are used by Eclipse eCAL, but not associated to it in any way.
      - - |fa-file-alt| Copy in repository: :file:`/cpack/innosetup/modpath.iss`
        - |fa-windows| Binary distributions for Windows (Installer only)
 
+   * - `nanobind <https://github.com/wjakob/nanobind>`_
+     - :ref:`bsd_3`
+     - 2022, Wenzel Jakob
+     - - |fa-github| Git submodule ``/tirdparty/nanobind/nanobind``
+
    * - `nanopb <https://github.com/nanopb/nanopb>`_
      - :ref:`zlib_license`
      - 2011 Petteri Aimonen \<jpa at nanopb.mail.kapsi.fi\>
@@ -186,6 +191,11 @@ They are used by Eclipse eCAL, but not associated to it in any way.
      - - |fa-github| Git submodule ``/tirdparty/recycle/recycle``
        - |fa-windows| Binary distributions for Windows
        - |fa-ubuntu| Binary distributions for Linux
+       
+   * - `robin-map <https://github.com/Tessil/robin-map>`_
+     - :ref:`mit_license`
+     - 2017, Thibaut Goetghebuer-Planchon
+     - - |fa-github| Git submodule ``/tirdparty/tsl-robin-map/tsl-robin-map``
 
    * - `spdlog <https://github.com/gabime/spdlog>`_
      - :ref:`mit_license`

ecal/core/include/ecal/pubsub/types.h

@@ -159,3 +159,17 @@ namespace eCAL
   using SubEventCallbackT = std::function<void(const STopicId& topic_id_, const SSubEventCallbackData& data_)>;
 }
 
+
+namespace std
+{
+  template<>
+  class hash<eCAL::STopicId> {
+  public:
+    size_t operator()(const eCAL::STopicId& id) const
+    {
+      const std::size_t h1 = std::hash<std::string>{}(id.topic_name);
+      const std::size_t h2 = std::hash<uint64_t>{}(id.topic_id.entity_id);
+      return h1 ^ (h2 << 1); // basic combination
+    }
+  };
+}

ecal/core/include/ecal/service/types.h

@@ -205,3 +205,31 @@ namespace eCAL
   using ServerEventCallbackT = std::function<void(const SServiceId& service_id_, const struct SServerEventCallbackData& data_)>;
 
 }
+
+
+namespace std
+{
+  template<>
+  class hash<eCAL::SServiceId> {
+  public:
+    size_t operator()(const eCAL::SServiceId& id) const
+    {
+      const std::size_t h1 = std::hash<std::string>{}(id.service_name);
+      const std::size_t h2 = std::hash<uint64_t>{}(id.service_id.entity_id);
+      return h1 ^ (h2 << 1); // basic combination
+    }
+  };
+
+  template<>
+  class hash<eCAL::SServiceMethodInformation> {
+  public:
+    size_t operator()(const eCAL::SServiceMethodInformation& info) const
+    {
+      const std::size_t h1 = std::hash<std::string>{}(info.method_name);
+      const std::size_t h2 = std::hash<eCAL::SDataTypeInformation>{}(info.request_type);
+      const std::size_t h3 = std::hash<eCAL::SDataTypeInformation>{}(info.response_type);
+      return h1 ^ (h2 << 1) ^ (h3 << 2);
+    }
+  };
+}
+

ecal/core/include/ecal/types.h

@@ -102,3 +102,18 @@ namespace eCAL
     return os;
   }
 }
+
+namespace std
+{
+  template<>
+  class hash<eCAL::SDataTypeInformation> {
+  public:
+    size_t operator()(const eCAL::SDataTypeInformation& datatype_info) const
+    {
+      const std::size_t h1 = std::hash<std::string>{}(datatype_info.name);
+      const std::size_t h2 = std::hash<std::string>{}(datatype_info.encoding);
+      const std::size_t h3 = std::hash<std::string>{}(datatype_info.descriptor);
+      return h1 ^ (h2 << 1) ^ (h3 << 2); // basic combination
+    }
+  };
+}

lang/python/CMakeLists.txt

@@ -1,6 +1,6 @@
 # ========================= eCAL LICENSE =================================
 #
-# Copyright (C) 2016 - 2024 Continental Corporation
+# Copyright (C) 2016 - 2025 Continental Corporation
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -28,8 +28,18 @@ option(ECAL_PYTHON_BUILD_SAMPLES "Includes the python samples"
 option(ECAL_PYTHON_BUILD_TESTS   "Includes the python tests"                    ON)
 option(ECAL_PYTHON_USE_HDF5      "Enables eCAL application cmd line interfaces" ON)
 
+if (NOT ECAL_PYTHON_USE_HDF5)
+  message(FATAL_ERROR "Building python bindings without hdf5 is not supported.")
+endif()
+
+
 set(ECAL_PYTHON_DIRECTORY ${CMAKE_CURRENT_LIST_DIR})
 
+# Try to make modules loadable by debug python version
+if(WIN32)
+  set(CMAKE_DEBUG_POSTFIX            _d)
+endif()
+
 # This function takes a list of python files to be copied to the package directory
 # and associates the files with a given python extension target
 # Using this function allows to create the whole python package editable in place
@@ -129,15 +139,14 @@ set(CMAKE_INSTALL_RPATH "\$ORIGIN")
 # for build tree use.
 set(CMAKE_BUILD_WITH_INSTALL_RPATH "ON")
 
-add_subdirectory(core)
+add_subdirectory(src/core)
 add_dependencies(${PROJECT_NAME} _ecal_core_py)
 
-if(ECAL_USE_HDF5)
-  add_subdirectory(ecalhdf5)
-  add_dependencies(${PROJECT_NAME} _ecal_hdf5_py)
-else()
-  message(WARNING "Building Python bindings without HDF5 support")
-endif()
+add_subdirectory(src/nanobind_core/src)
+add_dependencies(${PROJECT_NAME} nanobind_core)
+
+add_subdirectory(src/ecalhdf5)
+add_dependencies(${PROJECT_NAME} _ecal_hdf5_py)
 
 if (ECAL_PYTHON_BUILD_SAMPLES)
   add_subdirectory(samples)

lang/python/samples/CMakeLists.txt

@@ -23,6 +23,18 @@ set(python_samples_core
   core/service/minimal_service_server.py
 )
 
+set(python_samples_nanobind_core
+  nanobind_core/pubsub/nb_binary_rec.py
+  nanobind_core/pubsub/nb_binary_rec_cb.py
+  nanobind_core/pubsub/nb_binary_snd.py
+  nanobind_core/service/nb_minimal_service_client.py
+  nanobind_core/service/nb_minimal_service_server.py
+  nanobind_core/nb_logging.py
+  nanobind_core/nb_monitoring.py
+  nanobind_core/nb_process.py
+  nanobind_core/nb_util.py  
+)
+
 function(add_sample_to_solution python_filenname)
   cmake_path(GET python_filenname PARENT_PATH subfolder)
   cmake_path(GET python_filenname STEM        stem)
@@ -40,7 +52,13 @@ if(ECAL_PYTHON_USE_HDF5)
   endforeach()
 endif()
 
+# Core samples
 foreach(python_sample ${python_samples_core})
   add_sample_to_solution(${python_sample})
 endforeach()
+
+# Nanobind samples
+foreach(python_sample ${python_samples_nanobind_core})
+  add_sample_to_solution(${python_sample})
+endforeach()
 endif()

lang/python/samples/nanobind_core/nb_logging.py

@@ -0,0 +1,41 @@
+# ========================= eCAL LICENSE =================================
+#
+# Copyright (C) 2016 - 2025 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 =================================
+import ecal.nanobind_core as ecal_core
+
+def main():
+
+  # For pure logging, it's not necessary to modify the configuration.
+  # However, in order to also receive logging information it's necessary to be turned on
+  config = ecal_core.init.get_configuration()
+  config.logging.receiver.enable = True
+  config.logging.provider.udp.log_levels = [ecal_core.logging.LogLevel.INFO, ecal_core.logging.LogLevel.WARNING, ecal_core.logging.LogLevel.ERROR, ecal_core.logging.LogLevel.FATAL]
+  ecal_core.initialize(config, 'Logging Python Sample', ecal_core.init.ALL)
+  
+  ecal_core.logging.log(ecal_core.logging.LogLevel.INFO, "Hello Hello")
+  ecal_core.logging.log(ecal_core.logging.LogLevel.WARNING, "Help") 
+  
+  all_logging = ecal_core.logging.get_logging()
+  
+  for log in all_logging:
+    print(log)
+    print("\n")
+  
+  ecal_core.finalize()
+  
+if __name__ == "__main__":
+  main()

lang/python/samples/nanobind_core/nb_monitoring.py

@@ -0,0 +1,46 @@
+# ========================= eCAL LICENSE =================================
+#
+# Copyright (C) 2016 - 2025 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 =================================
+import time
+
+import ecal.nanobind_core as ecal_core
+
+def main():
+  ecal_core.initialize('Monitoring Python Sample', ecal_core.init.ALL)
+  
+  try:
+    while ecal_core.ok():
+        #TODO: is the naming good?
+        # or ecal_core.monitoring.
+        monitoring = ecal_core.monitoring.get_monitoring()
+        
+        print("There are {} publishers and {} subscribers in the system".format(len(monitoring.publishers), len(monitoring.subscribers)))
+
+        serialized_monitoring = ecal_core.monitoring.get_serialized_monitoring()
+        print("Length of serialized monitoring: {}".format(len(serialized_monitoring)))
+        # You could now use protobuf to deserialize the monitoring string
+        # We recommend to use the `get_monitoring` instead.
+
+        time.sleep(1)
+            
+  except KeyboardInterrupt:
+    pass
+  finally:  
+    ecal_core.finalize()
+  
+if __name__ == "__main__":
+  main()

lang/python/samples/nanobind_core/nb_process.py

@@ -0,0 +1,38 @@
+# ========================= eCAL LICENSE =================================
+#
+# Copyright (C) 2016 - 2025 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 =================================
+import os
+import time
+
+import ecal.nanobind_core as ecal_core
+
+def main():
+  ecal_core.initialize('Process Python Sample', ecal_core.init.ALL)
+
+  # We can query the eCAL Unit name which was set via `initialize`
+  unit_name = ecal_core.process.get_unit_name()
+  print("The name of this unit is '{}'".format(unit_name))
+  
+  # We can set a process state that will be shown in eCAL Monitor and eCALSys.
+  ecal_core.process.set_state(ecal_core.process.Severity.HEALTHY, ecal_core.process.SeverityLevel.LEVEL1, "I am doing fine")
+  
+  time.sleep(10)
+
+  ecal_core.finalize()
+  
+if __name__ == "__main__":
+  main()

lang/python/samples/nanobind_core/nb_util.py

@@ -0,0 +1,38 @@
+# ========================= eCAL LICENSE =================================
+#
+# Copyright (C) 2016 - 2025 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 =================================
+import os
+import time
+
+import ecal.nanobind_core as ecal_core
+
+def main():
+  ecal_core.initialize('Util Python Sample', ecal_core.init.ALL)
+
+  # Print the eCAL data directory
+  print("eCAL Data directory: {}".format(ecal_core.get_ecal_data_dir()))
+
+  # Print the eCAL logging directory, where file logs will be placed
+  print("eCAL Logging directory: {}".format(ecal_core.get_ecal_log_dir()))
+  
+  # Sets a shutdown signal to person_send, which will cause `eCAL::ok()` in that process to return false;
+  ecal_core.shutdown_process_by_name("person_send")
+
+  ecal_core.finalize()
+  
+if __name__ == "__main__":
+  main()