# Blickfeld ROS2 package  (:warning: ROS2 support is experimental )
This package provides a ROS2 node for publishing PointCloud2 messages from Blickfeld LiDAR devices.
The driver is not yet available publicly. Please request the sources from the Blickfeld Sales department.

## Supported devices
The Blickfeld ROS2 driver supports all currently available Blickfeld LiDARs such as Cube 1 and Cube Range 1.

## Supported ROS2 Distributions
The Blickfeld ROS2 driver supports the following ROS2 Distributions
* Eloquent Elusor
* Foxy Fitzroy

## Dependencies
To install the Blickfeld ROS2 driver, please make sure the following dependencies are installed on your system.

* [blickfeld-scanner-library (BSL) ](https://docs.blickfeld.com/cube/latest/external/blickfeld-scanner-lib/install.html) with system-wide protobuf installation. This package has been tested using **BSL Version 2.13.0**

* [ROS Eloquent Installation](https://index.ros.org/doc/ros2/Installation/Eloquent/Linux-Install-Debians/) with Ubuntu 18.04 **/**
  [ROS Foxy Installation](https://index.ros.org/doc/ros2/Installation/Foxy/Linux-Install-Debians/) with Ubuntu 20.04
* [diagnostic_updater](https://index.ros.org/p/diagnostic_updater/)  can be acquired via your distribution's package manager, ${ROS_DISTRO} should be your ROS 2 version. (e.g. foxy or eloquent)

      $ sudo apt install ros-${ROS_DISTRO}-diagnostic-updater
      $ sudo apt install ros-${ROS_DISTRO}-diagnostic-msgs

   or via

      $ rosdep update
      $ rosdep install --from-paths src --ignore-src -r -y --skip-keys "blickfeld-scanner"
  The -skip-keys will instruct rosdep to not check blickfeld-scanner, which is not a ros package.
* For using xml formatted launch files with ROS2 Eloquent, install the dependent packages as shown below.

  :information_source: In ROS2 Foxy, the support for xml formatted launch files are included by default, and hence not required to be installed

      $ sudo apt install ros-eloquent-launch-xml
      $ sudo apt install ros-eloquent-launch-yaml

* [colcon installation](https://colcon.readthedocs.io/en/released/user/installation.html): required for building the workspace

:warning: The default DDS of ROS2 Foxy **FastRTPS** is not compatible with BSL.
Hence for ROS2 Foxy, we need to install DDS from other vendors. (e.g. Eclipse Cyclone or RTI Connext)

* [Eclipse Cyclone DDS](https://index.ros.org/doc/ros2/Installation/DDS-Implementations/Working-with-Eclipse-CycloneDDS/) to bypass the default DDS of ROS2 Foxy(FastRTPS)

## Build
Before building ensure that your ROS DISTRO is sourced. You will need to run this command on every new shell you open to have access to the ROS 2 commands. ${ROS_DISTRO} should be your ROS 2 version. (e.g. foxy or eloquent)

    $ source /opt/ros/${ROS_DISTRO}/setup.bash

To build the ROS2 driver, request the ROS2 driver from the Blickfeld Sales department and decompress the archive into your ROS2 workspace and run.

    $ colcon build --symlink-install --cmake-clean-first

## Switching to desired DDS (:warning: Necessary only for ROS2 Foxy )

:information_source: In the case of ROS2 Eloquent the default DDS works flawlessly with Blickfeld scanner library. Hence, we can run the node using the standard ros2 run approach. But, in the case of **ROS2 Foxy, we need to switch from the default DDS to a compatible one**.  This can be done using **either of the two** approaches.

1. Exporting the RMW_IMPLEMENTATION for the present terminal session

       $ export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

2. [Switching to the desired RMW_IMPLEMENTATION](https://index.ros.org/doc/ros2/Tutorials/Working-with-multiple-RMW-implementations/) while running by adding a prefix before the ros2 run

       $ RMW_IMPLEMENTATION=rmw_cyclonedds_cpp ros2 run  PKG_NAME NODE_NAME ARGUMENTS


## Running the Blickfeld ROS node
Before running, ensure that your colcon workspace is sourced.
This is achieved by sourcing the setup script in your colcon workspace.

    $ source install/setup.bash

You can launch the ROS driver in a DHCP controlled Network by providing the Hostname of the LiDAR device (you can check and set the Hostname in the WebGUI of the device) e.g:

    $ ros2 run blickfeld_driver blickfeld_node --ros-args -p host:=cube-0056 --remap __node:=bf_lidar

If you connect the LiDAR directly to your PC or don't have a DHCP Server you can launch the driver by using the IP configured in the WebGUI of the Device or the Fallback-IP of the Device
(**make sure to adjust your network-settings accordingly**) e.g:

    $ ros2 run blickfeld_driver blickfeld_node --ros-args -p host:=192.168.26.26 --remap __node:=bf_lidar

You can also start it with more parameters, e.g.:

    $ ros2 run blickfeld_driver blickfeld_node --ros-args -p host:=cube-0056 -p publish_ambient_light:=true -p publish_intensities:=false

To visualize the published data, run rviz2

    $ ros2 run rviz2 rviz2

If you prefer a similar way to **launch**, like you would in ROS(1) (beware of the new ".xml"), you can start the driver like this:

    $ ros2 launch -a blickfeld_driver live_scanner.launch.xml host:=cube-0056

Or if you prefer to put the parameters into a yaml, run the python launch file. It reads the two yaml file containing the configurations.

    $ ros2 launch blickfeld_driver live_scanner_yaml.launch.py

The yaml files are located in the **ros2_blickfeld_driver/config** folder of the blickfeld_driver package. There are two yaml files:

 1. driver_config.yaml

	   Configures host id, output point cloud topic etc.

 2. blickfeld_scanner.rviz

       Configures the parameters for Rviz visualization, e.g. topic of point cloud, configuration of opened viewers etc.

### Parameters
All the following parameters are available in launch _and_ run:

| Argument | Default | Note |
| ------ | ------ | ------ |
| **host** (required) | | The host name or the IP of the device you want to publish the point clouds from, e.g., `cube-0028`, `192.168.26.26`. |
| node_name | `bf_lidar` | Name of this ROS node. |
| point_cloud_out | `$(var node_name)/points_raw` | Topic to publish the  PointCloud2 message to. |
| remap | `true` |Remap this node’s input/output topics to commonly used ones. <br/>If `false`, canonical names in the form of `$(var node_name)/foo_(in/out)` are used, depending on whether a topic is an input or an output topic. |
| lidar_frame_id | `lidar` | The ROS TF where the point cloud should be in. |
| rviz | `false` | Start rviz if this argument is true. |
| use_lidar_timestamp | `true` | Set to true if the timestamp in the ROS point cloud message should be generated from the device timestamp; otherwise the timestamp will be the ROS time when the frame was received on ROS. |
| publish_intensities | `true` | Set to true if the PointCloud2 message should contain intensities. |
| publish_ambient_light | `false` | Set to true if the PointCloud2 message should contain the ambient light level. |
| publish_explicit_range | `false` | Set to true if the PointCloud2 message should contain the `range` field. |
| publish_no_return_points | `false` | Set to true if the PointCloud2 message should contain points in a given range for pulses without a return. |
| no_return_point_range | `1.0` | Dummy range for points of pulses without a return. |
| publish_all_returns | `false` | Set to true to publish all the returns for every point. Adds the field `return_id` (ID for each returned point) to the point cloud. |
| publish_time_delta | `false` | If `true`, the PointCloud2 message will contain the timestamp field per point to represent the time offset from the start of the frame. |
| publish_point_id | `false` | Add the `scanline_id` field, the `scanline_point_index` field (= the point’s number in the scan line), and the `point_id` (= frame-global point ID) to PointCloud2 message. <br/> If the device is configured to return multiple return points (multiple reflections), all these three IDs will be identical; only the `return_id` will differ. |


### Debugging
Add '__log_level:=debug' to see details:

    $ ros2 run blickfeld_driver blickfeld_node --ros-args --remap __node:=bf_lidar -p host:=cube-0056 -p publish_ambient_light:=true -p publish_no_return_points:=true __log_level:=debug

#### ROS2 message content
To look at the ROS message sent by this ROS node, you can use

    $ debugging_tools/ros2-topic-echoparsed.py

It shows all the fields present in the message.


## License

This package is released under a [BSD 3-Clause License](LICENSE) (see also [https://opensource.org/licenses/BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause))