Release 3.3.0

CHANGELOG.md

@@ -4,9 +4,16 @@ Possible types are **Added** for new features. **Changed** for changes to the ex
 features that will be removed in future versions **Removed** for deprecated features that were removed in this release.
 **Fixed** for all bug fixes. **Security** to prompt users to update in case of closed vulnerabilities.
 
-
 ## Released ##
 
+### Release v3.3.0
+
+  - **add** Option for MRS1xxx azimuth correction table 
+  - **add** Support for picoScan100 (single echo w/o addons)
+  - **add** API logging functions and verbosity (#270)
+  - **add** API documentation (multiple lidars not supported, #281)
+  - **changed** API extended (added topic in PointCloud messages, #271)
+
 ### Release v3.2.0
 
   - **add** IMU support for multiScan and picoScan

CHANGELOG.rst

@@ -4,19 +4,28 @@ Changelog for package sick_scan_xd
 
 Forthcoming
 -----------
-* add: IMU support for multiScan and picoScan
-* add: support bloom releases for ROS-2 humble
-* add: docker tests for ROS1 noetic incl. testcases for multiScan, picoScan, MRS1xxx
-* add: PR #255, support picoScan performance profiles
-* change: configuration time flag LMDscandatacfg switched off for the TiM240
-* fix: #218 (API reinit)
-* fix: #220 (Fullframe Laserscan messages multi- and picoScan)
-* fix: #221 (No scandata while activated scan range filter)
-* fix: #222 (rviz visualization of polar pointclouds)
-* fix: #247 (Launchfile option for laserscan topic)
-* fix: #256 (Clean API-exit picoScan and multiScan)
-* fix: #260 (Provide API-functions to query lidar status, error codes and error messages)
-* Contributors: Manuel Aiple
+* Release v3.3.0
+  * add: Option for MRS1xxx azimuth correction table 
+  * add: Support for picoScan100 (single echo w/o addons)
+  * add: API logging functions and verbosity (#270)
+  * add: API documentation (multiple lidars not supported, #281)
+  * changed: API extended (added topic in PointCloud messages, #271)
+
+3.2.0 (2024-02-12)
+------------------
+* Release v3.1.0
+  * add: IMU support for multiScan and picoScan
+  * add: support bloom releases for ROS-2 humble
+  * add: docker tests for ROS1 noetic incl. testcases for multiScan, picoScan, MRS1xxx
+  * add: PR #255, support picoScan performance profiles
+  * changed: configuration time flag LMDscandatacfg switched off for the TiM240
+  * fix: #218 (API reinit)
+  * fix: #220 (Fullframe Laserscan messages multi- and picoScan)
+  * fix: #221 (No scandata while activated scan range filter)
+  * fix: #222 (rviz visualization of polar pointclouds)
+  * fix: #247 (Launchfile option for laserscan topic)
+  * fix: #256 (Clean API-exit picoScan and multiScan)
+  * fix: #260 (Provide API-functions to query lidar status, error codes and error messages)
 
 3.1.0 (2023-11-21)
 ------------------

CMakeLists.txt

@@ -95,9 +95,11 @@ elseif(DEFINED SICK_TARGET_ENDIANESS)
 endif()
 
 # ROS Version
-message(STATUS "ROS_VERSION precheck: ENV{ROS_VERSION}=$ENV{ROS_VERSION} ROS_VERSION=${ROS_VERSION} CMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH}")
+message(STATUS "ROS_VERSION precheck: ENV{ROS_VERSION}=$ENV{ROS_VERSION} ENV{ROS_DISTRO}=$ENV{ROS_DISTRO} ROS_VERSION=${ROS_VERSION} CMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH}")
 if(DEFINED CMAKE_PREFIX_PATH AND "${CMAKE_PREFIX_PATH}" STREQUAL "/opt/ros/humble")
-    set(ROS_VERSION 2)
+    set(ROS_VERSION 2)  # required for ROS2 humble bloom releases with jenkins buildfarm
+elseif(NOT DEFINED ROS_VERSION AND EXISTS "/opt/ros/humble/setup.sh")
+    set(ROS_VERSION 2)  # required for ROS2 humble bloom releases with jenkins buildfarm
 endif()
 if(NOT DEFINED ROS_VERSION AND DEFINED ENV{ROS_VERSION})
     set(ROS_VERSION $ENV{ROS_VERSION})
@@ -656,7 +658,12 @@ else() # i.e. (ROS_VERSION EQUAL 0 OR ROS_VERSION EQUAL 2)
         target_link_libraries(${PROJECT_NAME}_shared_lib ${SICK_LDMRS_LIBRARIES})
     endif()
     add_executable(sick_generic_caller driver/src/sick_generic_caller.cpp)
-    target_link_libraries(sick_generic_caller ${PROJECT_NAME}_lib ${SICK_LDMRS_LIBRARIES})
+    if(ROS_VERSION EQUAL 0 AND NOT WIN32)
+        target_link_libraries(sick_generic_caller ${PROJECT_NAME}_lib ${SICK_LDMRS_LIBRARIES} "pthread") # pthread required for std::thread
+        target_link_options(sick_generic_caller PUBLIC "LINKER:--no-as-needed") # fixes exception "Enable multithreading to use std::thread: Operation not permitted" 
+    else()    
+        target_link_libraries(sick_generic_caller ${PROJECT_NAME}_lib ${SICK_LDMRS_LIBRARIES})
+    endif()
 
 endif()
 

INSTALL-ROS1.md

@@ -4,7 +4,7 @@ To build resp. install sick_scan_xd on Linux with ROS-1, you can build sick_scan
 
 ## Install prebuilt binaries
 
-Run the following steps to install sick_scan_xd on Linux with ROS 1:
+Run the following steps to install sick_scan_xd on Linux with ROS 1 noetic:
 
 ```
 sudo apt update

INSTALL-ROS2.md

@@ -1,5 +1,20 @@
 ## Build on Linux ROS2
 
+To build resp. install sick_scan_xd on Linux with ROS-2, you can build sick_scan_xd from sources or install prebuilt binaries.
+
+## Install prebuilt binaries
+
+Run the following steps to install sick_scan_xd on Linux with ROS 2 humble:
+
+```
+sudo apt update
+sudo apt-get install ros-humble-sick-scan-xd
+```
+
+After successful installation, you can run sick_scan_xd using `ros2 launch sick_scan_xd <launchfile>.py`, e.g. `ros2 launch sick_scan_xd sick_multiscan.launch.py` for multiScan. sick_scan_xd can be removed by `sudo apt-get remove ros-humble-sick-scan-xd`.
+
+## Build from sources
+
 Run the following steps to build sick_scan_xd on Linux with ROS 2:
 
 1. Create a workspace folder, e.g. `sick_scan_ws` (or any other name):

README.md

@@ -41,6 +41,28 @@ This project provides a driver for the SICK LiDARs and Radar sensors mentioned [
 * sick_scan_xd has no dependencies to 3rd party libraries like boost or pthread.
 * sick_scan_xd offers all features on all targets if the devices support the features.
 
+## Repository organization
+
+The repository supports two main branches.
+
+The **"master"** branch is the branch that contains official releases that are tagged and versioned and also included in the ROS distribution. 
+
+If you want to work with this official branch, you must explicitly specify this branch in the 'git clone' command by adding "-b master".
+
+The "develop" branch is the default branch and contains the latest development status.
+
+Example:
+
+Checking out the latest revision (usually older than the develop version, but officially released):
+```
+git clone -b master https://github.com/SICKAG/sick_scan_xd.git
+```
+
+Checking out the latest development status:
+```
+git clone https://github.com/SICKAG/sick_scan_xd.git
+```
+
 ## Build targets
 
 sick_scan_xd can be build on Linux and Windows, with and without ROS, with and without LDMRS. The following table shows the allowed combinations and how to build.

USAGE.md

@@ -274,22 +274,20 @@ The use of the parameters can be looked up in the launch files. This is also rec
 To start the scanner with a specific IP address, option `hostname:=<ip-address>` can be used.
 The hostname is the ip-address of the scanner, e.g.
 ```
-sick_generic_caller sick_tim_5xx.launch hostname:=192.168.0.71                      # Linux native
+sick_generic_caller sick_tim_5xx.launch hostname:=192.168.0.71                         # Linux native
 roslaunch sick_scan_xd sick_tim_5xx.launch hostname:=192.168.0.71                      # Linux ROS-1
 ros2 run sick_scan_xd sick_generic_caller sick_tim_5xx.launch hostname:=192.168.0.71   # Linux ROS-2
-sick_generic_caller sick_tim_5xx.launch hostname:=192.168.0.71                      # Windows native
+sick_generic_caller sick_tim_5xx.launch hostname:=192.168.0.71                         # Windows native
 ros2 run sick_scan_xd sick_generic_caller sick_tim_5xx.launch hostname:=192.168.0.71   # Windows ROS-2
 ```
 
 ### Further useful parameters and features
 
-- `timelimit`
-  Timelimit in [sec] for max. wait time of incoming sensor reply
+- **Timestamps**: If parameter`sw_pll_only_publish` is true (default), an internal Software PLL is used to sync the scan generation timestamps to system timestamps. See [software_pll.md](./doc/software_pll.md) for details.
 
-- `sw_pll_only_publish`
-  If true, the internal Software PLL is fored to sync the scan generation time stamp to a system timestamp
+- **Angle compensation**: For highest angle accuracy the NAV-Lidar series supports an [angle compensation mechanism](./doc/angular_compensation.md).
 
-- Angle compensation: For highest angle accuracy the NAV-Lidar series supports an [angle compensation mechanism](./doc/angular_compensation.md).
+- **Angle correction**: MRS-1xxx lidars transmit accurate azimuth angles for each scan point. Therefore, the stride (angle increment) of the MRS-1xxx azimuth angles in polar and cartesian point clouds is not exactly constant. Since laserscan messages assume a constant angle increment, scan points in point cloud and laserscan messages have slightly different azimuth angles.
 
 - **Field monitoring**: The **LMS1xx**, **LMS5xx**, **TiM7xx** and **TiM7xxS** families have [extended settings for field monitoring](./doc/field_monitoring_extensions.md).
 

doc/bloom.md

@@ -158,6 +158,10 @@
     * Check status: https://index.ros.org/p/sick_scan_xd/#noetic
     * Install binary release: `sudo apt update ; sudo apt-get install ros-noetic-sick-scan-xd`. Note from https://wiki.ros.org/bloom/Tutorials/FirstTimeRelease: Packages built are periodically synchronized over to the shadow-fixed and public repositories, so it might take as long as a month before your package is available on the public ROS debian repositories (i.e. available via apt-get). 
 
+* Troubleshooting, FAQ:
+   * bloom builds an old sick_scan_xd version:
+      * Check `devel_branch` in https://github.com/SICKAG/sick_scan_xd-release/blob/master/tracks.yaml. If devel_branch is an old branch, replace it with e.g. `develop` or `master`, or update the `<devel_branch>` to a new version.
+
 ## Release build for ROS-2
 
 For ROS-2 follow the instructions on https://docs.ros.org/en/humble/How-To-Guides/Releasing/Releasing-a-Package.html:
@@ -191,12 +195,18 @@ For ROS-2 follow the instructions on https://docs.ros.org/en/humble/How-To-Guide
     sudo rosdep init
     rosdep update
     ```
+* Troubleshooting, FAQ:
+   * bloom builds an old sick_scan_xd version:
+      * Check `devel_branch` in https://github.com/ros2-gbp/sick_scan_xd-release/blob/master/tracks.yaml. If devel_branch is an old branch, replace it with e.g. `develop` or `master`, or update the `<devel_branch>` to a new version.
 
 ## Check status
 
 * ROS-1 release repository: https://github.com/SICKAG/sick_scan_xd-release
 * ROS-2 release repository: https://github.com/ros2-gbp/sick_scan_xd-release.git
-* Jenkins: https://build.ros.org/search/?q=sick_scan_xd
+* ROS-1 jenkins build status: https://build.ros.org/job/Ndev__sick_scan_xd__ubuntu_focal_amd64/lastBuild/
+* ROS-2 jenkins build status: https://build.ros2.org/job/Hdev__sick_scan_xd__ubuntu_jammy_amd64/lastBuild/
+* ROS-1 jenkins: https://build.ros.org/search/?q=sick_scan_xd
+* ROS-2 jenkins: https://build.ros2.org/search/?q=sick_scan_xd
 * Documentation: https://index.ros.org/p/sick_scan_xd/#noetic , http://wiki.ros.org/sick_scan_xd
 
 ## Useful links and tutorials

doc/sick_scan_api/sick_scan_api.md

@@ -15,6 +15,7 @@ The generic sick_scan_xd API ships with the API-header, the library (binary or s
 ![apiComponentsDiagram1.png](apiComponentsDiagram1.png)
 
 **Note: Running multiple lidars simultaneously in one process is not supported.** Currently the sick_scan_xd API does not support the single or multi-threaded use of 2 or more lidars in one process, since the sick_scan_xd library is not guaranteed to be thread-safe. To run multiple lidars simultaneously, we recommend using ROS or running sick_scan_xd in multiple and separate processes, so that each process serves one sensor.
+
 ## Build and test shared library
 
 The shared library, which implements the C-API, is built native on Linux or Windows (i.e. without ROS). Follow the instructions on [Build on Linux generic without ROS](../../INSTALL-GENERIC.md#build-on-linux-generic-without-ros) for Linux resp. [Build on Windows](../../INSTALL-GENERIC.md#build-on-windows) for Windows.
@@ -167,6 +168,13 @@ The sick_scan_xd API can be used on Linux or Windows in any language with suppor
    * [Complete usage example in C++](#complete-usage-example-in-c)
    * [Complete usage example in Python](#complete-usage-example-in-python)
 
+   Note for multiScan and picoScan lidars:
+
+   * The WaitNext-functions of the API return the next received message. For multiScan and picoScan, this can be a scan segment (i.e. a part of the full scan) or a fullframe poincloud (i.e. all scan points of a 360 degree scan). Depending on the timing, you may not receive all messages, i.e. you may e.g. receive scan points of different segments. We therefore recommend to register a message callback instead of a WaitNext-function. With a registered message callback, you will get all fullframe and segment pointcloud messages.
+
+   * For multiScan and picoScan, pointcloud messages can contain a scan segment (i.e. a part of the full scan) or a fullframe poincloud  (i.e. all scan points of a 360 degree scan). The type can be determined by the topic (default: "/cloud_unstructured_segments" for segments, "/cloud_unstructured_fullframe" for fullframe pointclouds) or by segment index (-1 for fullframe, 0 up to 11 for segment pointclouds).
+
+
 3. Close lidar and API by
     * `SickScanApiDeregister<MsgType>Msg`-functions
     * SickScanApiClose
@@ -335,6 +343,8 @@ The API provides the following functions for diagnostics:
 
 * SickScanApiGetStatus queries the current status. This function returns the current status code (OK=0 i.e. normal operation, WARN=1, ERROR=2, INIT=3 i.e. initialization after startup or reconnection or EXIT=4) and the descriptional status message.
 
+* SickScanApiSetVerboseLevel and SickScanApiGetVerboseLevel sets resp. returns the verbose level. The verbose level can be 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR, 4=FATAL or 5=QUIET (equivalent to ros\:\:console\:\:levels). Default verbose level is 1 (INFO), i.e. sick_scan_xd prints informational, warnings and error messages on the console. Logging callbacks registered with SickScanApiRegisterLogMsg will receive all informational, warnings and error messages independant of the verbose level.
+
 To monitor sick_scan_xd resp. the lidar, it is recommended to register a callback for diagnostic messages using SickScanApiRegisterDiagnosticMsg and to display the error message in case for status code 2 (error). See [sick_scan_xd_api_test.cpp](../../test/src/sick_scan_xd_api/sick_scan_xd_api_test.cpp) and [sick_scan_xd_api_test.py](../../test/python/sick_scan_xd_api/sick_scan_xd_api_test.py) for an example.
 
 ### Simulation and unittest

driver/src/ldmrs/sick_ldmrs_driver.cpp

@@ -75,7 +75,6 @@ SickLDMRS::SickLDMRS(rosNodePtr nh, Manager *manager, std::shared_ptr<diagnostic
   std::string nodename;
   rosDeclareParam(nh, "nodename", nodename);
   rosGetParam(nh, "nodename", nodename);
-  std::string cloud_topic_val = "cloud";
   rosDeclareParam(nh, "cloud_topic", cloud_topic_val);
   rosGetParam(nh, "cloud_topic", cloud_topic_val);
   m_add_transform_xyz_rpy = sick_scan_xd::SickCloudTransform(nh, true);
@@ -169,8 +168,8 @@ void SickLDMRS::setData(BasicData &data)
 
       ros_sensor_msgs::PointCloud2 msg, msg_polar;
       ldmrsScanToPointCloud2(scan, m_add_transform_xyz_rpy, m_range_filter, scannerInfos[0].isRearMirrorSide(), config_.frame_id, msg, msg_polar);
-      sick_scan_xd::PointCloud2withEcho sick_cloud_msg(&msg, 1, 0);
-      sick_scan_xd::PointCloud2withEcho sick_cloud_msg_polar(&msg_polar, 1, 0);
+      sick_scan_xd::PointCloud2withEcho sick_cloud_msg(&msg, 1, 0, cloud_topic_val);
+      sick_scan_xd::PointCloud2withEcho sick_cloud_msg_polar(&msg_polar, 1, 0, cloud_topic_val);
       notifyPolarPointcloudListener(nh_, &sick_cloud_msg_polar);
       notifyCartesianPointcloudListener(nh_, &sick_cloud_msg);
       if(diagnosticPub_)

driver/src/sick_generic_callback.cpp

@@ -54,15 +54,15 @@
 */
 #include <sick_scan/sick_generic_callback.h>
 
-static sick_scan_xd::SickCallbackHandler<rosNodePtr,sick_scan_xd::PointCloud2withEcho>      s_cartesian_poincloud_callback_handler;
-static sick_scan_xd::SickCallbackHandler<rosNodePtr,sick_scan_xd::PointCloud2withEcho>      s_polar_poincloud_callback_handler;
+static sick_scan_xd::SickCallbackHandler<rosNodePtr,sick_scan_xd::PointCloud2withEcho>   s_cartesian_poincloud_callback_handler;
+static sick_scan_xd::SickCallbackHandler<rosNodePtr,sick_scan_xd::PointCloud2withEcho>   s_polar_poincloud_callback_handler;
 static sick_scan_xd::SickCallbackHandler<rosNodePtr,ros_sensor_msgs::Imu>                s_imu_callback_handler;
 static sick_scan_xd::SickCallbackHandler<rosNodePtr,sick_scan_msg::LIDoutputstateMsg>    s_lidoutputstate_callback_handler;
 static sick_scan_xd::SickCallbackHandler<rosNodePtr,sick_scan_msg::LFErecMsg>            s_lferec_callback_handler;
 static sick_scan_xd::SickCallbackHandler<rosNodePtr,sick_scan_msg::SickLdmrsObjectArray> s_ldmrsobjectarray_callback_handler;
 static sick_scan_xd::SickCallbackHandler<rosNodePtr,sick_scan_msg::RadarScan>            s_radarscan_callback_handler;
 static sick_scan_xd::SickCallbackHandler<rosNodePtr,ros_visualization_msgs::MarkerArray> s_visualizationmarker_callback_handler;
-static sick_scan_xd::SickCallbackHandler<rosNodePtr,sick_scan_xd::NAV350mNPOSData>          s_navposelandmark_callback_handler;
+static sick_scan_xd::SickCallbackHandler<rosNodePtr,sick_scan_xd::NAV350mNPOSData>       s_navposelandmark_callback_handler;
 
 namespace sick_scan_xd
 {

driver/src/sick_generic_laser.cpp

@@ -92,7 +92,7 @@
 #include <signal.h>
 
 #define SICK_GENERIC_MAJOR_VER "3"
-#define SICK_GENERIC_MINOR_VER "2"
+#define SICK_GENERIC_MINOR_VER "3"
 #define SICK_GENERIC_PATCH_LEVEL "0"
 
 #define DELETE_PTR(p) if(p){delete(p);p=0;}
@@ -147,6 +147,7 @@ static GenericLaserCallable* s_generic_laser_thread = 0;
 static NodeRunState runState = scanner_init;
 SICK_DIAGNOSTIC_STATUS s_status_code = SICK_DIAGNOSTIC_STATUS::INIT;
 std::string s_status_message = "";
+int32_t s_verbose_level = 1; // verbose level: 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR, 4=FATAL or 5=QUIET (equivalent to ros::console::levels), default verbose level is 1 (INFO), i.e. print informational, warnings and error messages.
 
 /*!
 \brief splitting expressions like <tag>:=<value> into <tag> and <value>
@@ -255,6 +256,20 @@ void getDiagnosticStatus(SICK_DIAGNOSTIC_STATUS& status_code, std::string& statu
  status_message = s_status_message;
 }
 
+// Set verbose level 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR, 4=FATAL or 5=QUIET (equivalent to ros::console::levels),
+// i.e. print messages on console above the given verbose level.
+// Default verbose level is 1 (INFO), i.e. print informational, warnings and error messages.
+void setVerboseLevel(int32_t verbose_level)
+{
+  s_verbose_level = verbose_level;
+}
+
+// Returns the current verbose level 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR, 4=FATAL or 5=QUIET. Default verbose level is 1 (INFO)
+int32_t getVerboseLevel()
+{
+  return s_verbose_level;
+}
+
 inline bool ends_with(std::string const &value, std::string const &ending)
 {
   if (ending.size() > value.size())

driver/src/sick_generic_radar.cpp

@@ -1668,7 +1668,7 @@ namespace sick_scan_xd
           if (numFilteredTargets < numTargets)
             m_range_filter.resizePointCloud(numFilteredTargets, cloud_); // targets dropped by range filter, resize pointcloud
 #ifndef ROSSIMU
-            sick_scan_xd::PointCloud2withEcho sick_cloud_msg(&cloud_, 1, 0);
+            sick_scan_xd::PointCloud2withEcho sick_cloud_msg(&cloud_, 1, 0, "radar");
             switch (iLoop)
             {
               case RADAR_PROC_RAW_TARGET: