SICK LiDAR-LOC - sick_lidar_localization package

ROS driver and core communication library for SICK LiDAR-LOC. Furthermore, the following product variants are supported as well:

• PicoScan-LOC
• Triton Floor-LOC
• CODE-LOC
• VLN

For the sake of clarity, only the term "SICK LiDAR-LOC" is used below.

Table of contents

• Introduction
• Supported OS and ROS distributions
• Build on Linux
• Build on Windows
• ROS2 Wrapper
• Core C++ library
• UDP Stream messages
• REST API
• Timestamps and time synchronization

Introduction

This repository contains a core driver library the communication with the software SICK LiDAR-LOC version 2 and a wrapper which ports the functionality into ROS2.

SOPASair is used to setup and configure SICK LiDAR-LOC on the used localization controller. See the operation manuals published on SICK Support Portal (SICK ID is needed to login) for details and further information.

The repository is structured in two packages. First and foremost the sick_lidar_localization_driver package contains the implementation of the core library and the correspondig ROS2 wrapper. The package sick_lidar_localization_msgs contains all relevant messages and services for ROS2.

Supported OS and ROS distributions

The following table lists supported OS for building the core driver library and the supported ROS distros to build the ROS2 nodes.

Tier	OS (for core build)	Supported ROS Versions
Tier 1 ✅	Ubuntu Noble 24.04	Jazzy Jalisco
↳	Ubuntu Jammy 22.04	Humble Hawksbill
↳	Ubuntu Focal 20.04 (EOL)	❌ Not available
Tier 3 ⚠️	↳	Foxy Fitzroy (EOL)
↳	Windows 10	Jazzy Jalisco
↳	↳	Humble Hawksbill

Build on Linux

A. Core library (Linux)

To build and install the core library, follow the steps below:

1. If not yet done, install libcurl:

   sudo apt-get install libcurl4-openssl-dev

2. Clone repository:

   git clone https://github.com/SICKAG/sick_lidar_localization.git

3. Build project sick_lidar_localization_driver with cmake:

   cd sick_lidar_localization
   # Build sick_lidar_localization_driver
   cmake -S sick_lidar_localization_driver -B build/sick_lidar_localization_driver -DROS_VERSION=0
   cmake --build build/sick_lidar_localization_driver

B. ROS2 package (Linux)

To build and install sick_lidar_localization on Linux using ROS2, follow the steps below:

1. If not yet done, install libcurl:

   sudo apt-get install libcurl4-openssl-dev

2. Clone repository:

   mkdir -p ./src
   pushd ./src
   git clone https://github.com/SICKAG/sick_lidar_localization.git
   popd

3. Build project sick_lidar_localization_msgs:

   Use your ROS distro as <your-ros2-distro>, e.g. if you have ROS2 Jazzy Jalisco use source /opt/ros/jazzy/setup.bash. This makes the ROS_VERSION environment variables available.

   source /opt/ros/<your-ros2-distro>/setup.bash
   colcon build --packages-select sick_lidar_localization_msgs --event-handlers console_direct+
   source ./install/setup.bash

4. Build project sick_lidar_localization_driver:

   source /opt/ros/<your-ros2-distro>/setup.bash 
   colcon build --packages-select sick_lidar_localization_driver --event-handlers console_direct+
   source ./install/setup.bash

Build on Windows

⚠️ Tier 3 support ⚠️

A. Core library (Windows)

To build and install sick_lidar_localization on Windows without ROS, follow the steps below:

1. If not yet done, install Visual Studio. Visual Studio 2022 Community or Professional Edition is recommended.

2. Clone repository:

   git clone https://github.com/SICKAG/sick_lidar_localization.git

3. Build project sick_lidar_localization with cmake and Visual Studio 2022:

   cd sick_lidar_localization
   cmake -S sick_lidar_localization_driver -B build/sick_lidar_localization_driver -DROS_VERSION=0 -G "Visual Studio 17 2022" -A x64
   cmake --build build/sick_lidar_localization_driver --config Release

You could also open file build\sick_lidar_localization.sln in Visual Studio and build all targets.

Should also work with Visual Studio 16 2019. Alternative build:

cd sick_lidar_localization
cmake -S sick_lidar_localization_driver -B build/sick_lidar_localization_driver -DROS_VERSION=0 -G "Visual Studio 16 2019" -A x64
cmake --build build/sick_lidar_localization_driver --config Release

B. ROS2 package (Windows)

To build and install sick_lidar_localization on Windows with ROS2, follow the steps below:

1. If not yet done, install Visual Studio and vcpkg (same as native Windows).

2. Build project sick_lidar_localization_msgs:

   colcon build --packages-select sick_lidar_localization_msgs --event-handlers console_direct+
   call .\install\setup.bat

3. Build project sick_lidar_localization_driver:

   colcon build --packages-select sick_lidar_localization_driver --event-handlers console_direct+
   call .\install\setup.bat

ROS2 Wrapper

The ROS2 wrapper translates between ROS2 topics/services and the LiDAR-LOC UDP stream protocol and REST API. All topics are prefixed with the configurable device name (default: localizationcontroller). For the full topic and service reference, including detailed field mappings for the standard ROS message types, see the ROS2 wrapper documentation.

Run sick_lidar_localization on ROS2

Start sick_lidar_localization using the ROS-corresponding configuration file: sick_lidar_localization_driver_config.yaml

For Linux using ROS2:

source ./install/setup.bash
ros2 launch sick_lidar_localization_driver sick_lidar_localization_driver.launch.py [options] # calling the yaml-File implicitly

For Windows using ROS2:

call .\install\setup.bat
ros2 launch sick_lidar_localization_driver sick_lidar_localization_driver.launch.py [options] # calling the yaml-File implicitly

Options and configuration

Parameter can be configured in the via the mentioned yaml configuration file above and overwritten by CLI arguments.

Common parameters are:

parameter name	default value	parameter type	example	description
lls_device_ip	192.168.0.1	string	lls_device_ip:=192.168.0.1	IP address of the SIM LLS device
lls_device_udp_port	5009	int	lls_device_udp_port:=5009	UDP port to use of the SIM LLS device
verbose	0	bool	verbose:=True	Print informational messages (verbose == true, otherwise error messages only)
local_machine_ip	""	string	local_machine_ip:=192.168.0.100	IP address of your local machine (i.e. the receiver of stream messages)

Core C++ library

The sick_lidar_localization_driver package contains a platform-independent core C++ library (sick_localization_lib) that handles all communication with the LiDAR-LOC device — UDP stream message sending and receiving, REST API calls, and timestamp conversion. It has no dependency on ROS and can be built and linked into any native Linux (or Windows) application.

Time synchronization between LiDAR device ticks and system time is provided through the abstract interface TimeSyncBase. The library does not implement any concrete synchronization policy; consumers must supply their own implementation (see Software-PLL for the approach used by the ROS2 wrapper, or PassthroughTimeSync in the example localization_result_example.cpp for a minimal stand-in).

The ROS2 wrapper in this repository itself is built on top of this library. Custom applications can follow the same approach: link against sick_localization_lib, implement a MessageListener subclass to handle the message types relevant to the application, and register it with the UdpReceiver.

The cpp localization_result_example.cpp of the executable of the same name demonstrates the minimal integration pattern:

// Implement a listener for the message types you care about
class LocalizationResultListener : public sick_lidar_localization::core::MessageListener
{
public:
  void messageReceived(const sick_lidar_localization::core::Message::LocalizationResultPayload0502& msg) override
  {
    // process pose: msg.x [mm], msg.y [mm], msg.heading [mdeg], msg.loc_status, ...
  }
};

// Initialize the driver and register the listener
sick_lidar_localization::core::SickLidarLocalization driver(time_sync, config);
driver.init();
driver.getUdpReceiver()->registerListener(std::make_shared<LocalizationResultListener>());

See localization_result_example.cpp for the full example and Core C++ library documentation for further details.

UDP Stream messages

The localization device running LiDAR-LOC receives and sends messages from/to the local machine using UDP. Using ROS2, these UDP-messages are converted into ROS messages and vice-versa. On native Linux and Windows systems, these UDP-messages can be processed using the Core C++ library.

The ROS2 message definitions are showing the content of the different UDP stream messages, linked in the table below. Direction in means sending from the driver running on the local machine to the SICK LiDAR-LOC device (e.g. SIM1000FX), direction out means sending from the SICK LiDAR-LOC device to the local machine running the driver.

Direction	UDP stream messages
in/out	Odometry messages type 1 version 4
in/out	Odometry messages type 1 version 5
in/out	Line measurement messages type 4 version 3
in/out	Line measurement messages type 4 version 4
in	Encoder measurement messages type 2 version 2
in	Code measurement messages type 3 version 3
in	Code measurement messages type 7 version 1
out	Code measurement messages type 3 version 4
out	Localization result messages type 5 version 2

See UDP communication sequence for further information about the UDP communication, the source Ids and their configuration.

When using ROS2 this is utilized within the topic names, for example:

• Topic /localizationcontroller/out/localization_result_message_0502 delivers the localization result from SICK LiDAR-LOC, so you application can subscribe on it.
• Topic /localizationcontroller/in/encoder_measurement_message_0202 pipes the encoder measurements to SICK LiDAR-LOC, so you application can publish on it.

For further information have a look at the ROS2 wrapper documentation.

REST API

LiDAR-LOC can be configured using a JSON REST API. This API is available via ROS services or the tool lidar_loc_rest_cli (on all target systems) via CLI. See REST API documentation for details. The implementation can be used as an example.

Timestamps and time synchronization

The localization timestamps in output messages are converted to system time using a Software-PLL. See Time synchronization and Software-PLL for details.