l3cam_ros

This package is an ROS driver for the L3Cam device manufactured by Beamagine. The driver relies on the library provided by Beamagine as part of the L3Cam SDK. For more info on the L3Cam check the L3Cam User Manual.

This package is supported only on Linux systems and has only been tested with ROS noetic on an Ubuntu 20.04 system.

Installation

Dependencies

First, you will need to install the L3Cam SDK.

Download the required package from Beamagine's L3Cam SDK repository depending on your hardware architecture and install:

sudo dpkg -i <PACKAGE>

ROS Driver

Once the SDK is successfully installed, you can continue with the ROS driver install:

sudo apt install ros-<ROS_DISTRO>-l3cam-ros

Or clone this repository in your catkin workspace (e.g. catkin_ws):

cd ~/catkin_ws/src && git clone https://github.com/beamaginelidar/l3cam_ros

Operational Advice

MTU Size

You will need to increase the MTU (Maximum Transmission Unit) on the network interface attached to the camera.

You can check what your current MTU setting is by running the following command:

ip a | grep mtu

You should increase the MTU to 9000 to allow jumbo frames. If you use Network Manager, this can be done by opening the network interface settings and editing the "MTU" box under the "Identity" tab.

See the "Linux host configuration" section of the L3Cam User Manual for full details.

Receive Buffer Size

It is also recommended to increase your network default and maximum receive buffer size.

You can check what your current buffer size is:

sudo sysctl 'net.core.rmem_max'
sudo sysctl 'net.core.rmem_default'

Update the buffer size with the following commands:

sudo sh -c "echo 'net.core.rmem_default=268435456' >> /etc/sysctl.conf"
sudo sh -c "echo 'net.core.rmem_max=268435456' >> /etc/sysctl.conf"
sudo sysctl -p

Port usage

libL3Cam uses the following ports for streaming and communications:

TCP is used internally by libL3Cam and is transparent to the user. However, the system host must have the required port available.

Launch

l3cam

To run the l3cam_ros driver, launch the l3cam.launch file specifying (if wanted) if the stream launch file, the configure launch file, rviz (for visualization GUI) and rqt_reconfigure (for dynamic reconfigure GUI) have to be launched too. By default, the values are as follows:

roslaunch l3cam_ros l3cam.launch stream:=true configure:=true rviz:=false rqt_reconfigure:=false

This will launch the l3cam_ros_node, which is the main node that connects to and controls the L3Cam, and the stream_l3cam.launch and configure_l3cam.launch files.

More parameters can be set if wanted for the default network and sensors parameters, this is seen in the parameters section. The default parameters specified will be passed to the main node (l3cam_ros_node) and the configure launch file.

stream_l3cam

This launch file launches all the stream nodes for all the sensors and rviz if specified. Once the main node connects to the L3Cam it will only keep open the stream nodes of the sensors the L3Cam has available, the other ones will shut down automatically.

The stream nodes stream automatically their sensor data to each sensor topic when data is available.

configure_l3cam

This launch file launches all the configure nodes for all the sensors and rqt_reconfigure if specified. Once the main node connects to the L3Cam it will only keep open the configure nodes of the sensors the L3Cam has available, the other ones will shut down automatically.

The configure nodes function like a dynamic reconfigure interface to change parameters, which is more user friendly. In reality, the parameters are changed with the main node through services, the configure nodes call services when a dynamic reconfigure parameter is changed.

If using rqt_reconfiugre, the window might show up before the driver is connected to the L3Cam, so you might need to click refresh for it to show the available parameters.

ROS Nodes

l3cam_ros_node

The l3cam_ros_node is the main node that connects to the L3Cam and configures it according to ROS parameters/services. See the parameters and services sections for documentation regarding the various parameters that can be used to configure the L3Cam.

pointcloud_stream

The pointcloud_stream is the node that publishes pointcloud frames if the LiDAR sensor is available. See the topics section for documentation regarding the topics each sensor topic.

polarimetric_stream

The polarimetric_stream is the node that publishes polarimetric or Allied Wide image frames if the polarimetric or the Allied Wide sensor is available. See the topics section for documentation regarding the topics each sensor topic.

rgb_stream

The rgb_stream is the node that publishes RGB or Allied Narrow image frames if the RGB or the Allied Narrow sensor is available. See the topics section for documentation regarding the topics each sensor topic.

thermal_stream

The thermal_stream is the node that publishes thermal image frames if the thermal sensor is available. See the topics section for documentation regarding the topics each sensor topic.

network_configuration

The network_configuration is a node that configures the network parameters by using dynamic reconfigure and the services to communicate with the l3cam_ros_node. See the config file cfg/Network.cfg for documentation regarding the various parameters that can be used to configure the network parameters of the L3Cam.

pointcloud_configuration

The pointcloud_configuration is a node that configures the pointcloud parameters (if a LiDAR sensor is available) by using dynamic reconfigure and the services to communicate with the l3cam_ros_node. See the config file cfg/Pointcloud.cfg for documentation regarding the various parameters that can be used to configure the pointcloud parameters of the L3Cam.

polarimetric_camera_configuration

The polarimetric_camera_configuration is a node that configures the polarimetric camera parameters (if a polarimetric sensor is available) by using dynamic reconfigure and the services to communicate with the l3cam_ros_node. See the config file cfg/PolarimetricCamera.cfg for documentation regarding the various parameters that can be used to configure the polarimetric camera parameters of the L3Cam.

rgb_camera_configuration

The rgb_camera_configuration is a node that configures the RGB camera parameters (if an RGB sensor is available) by using dynamic reconfigure and the services to communicate with the l3cam_ros_node. See the config file cfg/RgbCamera.cfg for documentation regarding the various parameters that can be used to configure the RGB camera parameters of the L3Cam.

thermal_camera_configuration

The thermal_camera_configuration is a node that configures the thermal camera parameters (if a thermal sensor is available) by using dynamic reconfigure and the services to communicate with the l3cam_ros_node. See the config file cfg/ThermalCamera.cfg for documentation regarding the various parameters that can be used to configure the thermal camera parameters of the L3Cam.

allied_wide_camera_configuration

The allied_wide_camera_configuration is a node that configures the Allied Wide camera parameters (if aan Allied Wide sensor is available) by using dynamic reconfigure and the services to communicate with the l3cam_ros_node. See the config file cfg/AlliedWideCamera.cfg for documentation regarding the various parameters that can be used to configure the Allied Wide camera parameters of the L3Cam.

allied_narrow_camera_configuration

The allied_narrow_camera_configuration is a node that configures the Allied Narrow camera parameters (if aan Allied Narrow sensor is available) by using dynamic reconfigure and the services to communicate with the l3cam_ros_node. See the config file cfg/AlliedNarrowCamera.cfg for documentation regarding the various parameters that can be used to configure the Allied Narrow camera parameters of the L3Cam.

Parameters

Default parameters for the L3Cam can be set by editing the l3cam.launch file or specifying them when calling it:

roslaunch l3cam_ros l3cam.launch <PARAMETER>:=<VALUE>

Some parameters are enumerate's declared on the libL3Cam, check the L3Cam User Manual for more info.

Network parameters

Pointcloud parameters

Polarimetric parameters

RGB parameters

Thermal parameters

Allied Wide parameters

Allied Narrow parameters

Services

Once the nodes are launched, the parameters can be changed through services. While streaming, some parameters cannot be changed, and the driver starts streaming when it connects to the L3Cam.

Only the changeable parameters while streaming will appear on the dynamic reconfigure of the configure nodes. Even though all the parameters are available, if a non changeable parameter is attempted to be changed, the service will return error.

The ranges shown in the parameters section also apply to the services as the same parameters are being changed.

Note: The arg allied_type must be 1 for Wide or 2 for Narrow. Any other value will return out of range error.

Sensor msg

On /get_sensors_available a custom message is returned with the following structure:

Being protocol a number contained in the enum streamingProtocols and sensor_type a number contained in the enum sensorTypes.

Topics

All sensors stream their data to each topic: