l3cam_ros

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

If you are looking for this package for ROS2, go to the l3cam_ros2 package.

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 package from Beamagine's L3Cam SDK 0.1.15 release repository and install the required package depending on your hardware architecture:

sudo dpkg -i <PACKAGE>

ROS Driver

Clone this repository in your catkin workspace (e.g. catkin_ws) and build:

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

Access Permission

You will need to give permission to the cfg files.

cd ~/catkin_ws/src/l3cam_ros/cfg
chmod a+x Network.cfg Lidar.cfg Polarimetric.cfg Rgb.cfg Thermal.cfg AlliedWide.cfg AlliedNarrow.cfg

Operational Advice

Jumbo frames

You will need to enable jumbo frames on your ethernet adapter by increasing the MTU (Maximum Transmission Unit) on the network interface attached to the camera.

A jumbo frame is an Ethernet frame that is larger than 1500 bytes. Most Ethernet adapters support jumbo frames, however it is usually turned off by default. Please note in order to set a 9000 byte packet size on the camera, the Ethernet adapter must support a jumbo frame size of 9000 bytes or higher.

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

ifconfig | 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.

Note:

• If in any case this node dies without printing Terminating... and Terminated. you might have problems with the sensors as the library might have terminated wrongly the last time. If this happens, it will output error 235 (Error binding TCP socket) when trying to run it again, reboot the device to solve the problem.

lidar_stream

The lidar_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_wide_stream

The polarimetric_wide_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_narrow_stream

The rgb_narrow_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 or the network parameters section for documentation regarding the various parameters that can be used to configure the network parameters of the L3Cam.

lidar_configuration

The lidar_configuration is a node that configures the lidar 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/Lidar.cfg or the lidar parameters section for documentation regarding the various parameters that can be used to configure the lidar parameters of the L3Cam.

polarimetric_configuration

The polarimetric_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/Polarimetric.cfg or the polarimetric parameters section for documentation regarding the various parameters that can be used to configure the polarimetric camera parameters of the L3Cam.

rgb_configuration

The rgb_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/Rgb.cfg or the rgb parameters section for documentation regarding the various parameters that can be used to configure the RGB camera parameters of the L3Cam.

thermal_configuration

The thermal_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/Thermal.cfg or the thermal parameters section for documentation regarding the various parameters that can be used to configure the thermal camera parameters of the L3Cam.

allied_wide_configuration

The allied_wide_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/AlliedWide.cfg or the allied wide parameters section for documentation regarding the various parameters that can be used to configure the Allied Wide camera parameters of the L3Cam.

allied_narrow_configuration

The allied_narrow_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/AlliedNarrow.cfg or the allied narrow parameters section for documentation regarding the various parameters that can be used to configure the Allied Narrow camera parameters of the L3Cam.

Note:

• When changing a parameter from a configuration node, if the parameter could not be changed, it will be set to its previous value. This might not directly take effect on the rqt_reconfigure node and might lead to misunderstandings. Please check for any RCLCPP messages, any parameter that could not be changed will be informed. You can refresh the actual values of a configuration node in rqt_reconfigure by hiding and showing again the node parameters.

Parameters

Default parameters for the L3Cam can be set by loading params files, by editing the l3cam.launch file or by specifying them when launching it:

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

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

Initialization parameters

Network parameters

Lidar parameters

Polarimetric parameters

RGB parameters

Thermal parameters

Allied Wide parameters

Allied Narrow parameters

Note:

• The following parameters might not match the real value as they depend on another parameter to be able to be set, and getters for sensors parameters, except allied cameras, are not supported yet.

  • bias_value_right depends on auto_bias.
  • bias_value_left depends on auto_bias.
  • polarimetric_camera_auto_gain_range_minimum depends on polarimetric_camera_auto_gain.
  • polarimetric_camera_auto_gain_range_maximum depends on polarimetric_camera_auto_gain.
  • polarimetric_camera_gain depends on polarimetric_camera_auto_gain.
  • polarimetric_camera_auto_exposure_time_range_minimum depends on polarimetric_camera_auto_exposure_time.
  • polarimetric_camera_auto_exposure_time_range_maximum depends on polarimetric_camera_auto_exposure_time.
  • polarimetric_camera_exposure_time depends on polarimetric_camera_auto_exposure_time.
  • rgb_camera_white_balance depends on rgb_camera_auto_white_balance.
  • rgb_camera_exposure_time depends on rgb_camera_auto_exposure_time.

• The following parameters will change when the parameter they depend on changes. These changes will not be shown directly in rqt_reconfigure, so you might have to hide and show the parameter's node.

  • allied_wide_camera_exposure_time changes when allied_wide_camera_auto_exposure_time is set to false.
  • allied_wide_camera_gain changes when allied_wide_camera_auto_gain is set to false.
  • allied_narrow_camera_exposure_time changes when allied_narrow_camera_auto_exposure_time is set to false.
  • allied_narrow_camera_gain changes when allied_narrow_camera_auto_gain is set to false.

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 index in the /change_bias_value service must be 1 por right or 2 for left. Any other value will return out of range error.
• The arg allied_type must be 0 for Wide or 1 for Narrow (see alliedCamerasIds). 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: