ROS 2 Interface

You are currently viewing the documentation for the latest version (2.4.1). To access a different version, click the "Switch version" button located in the upper-right corner of the page.

■ If you are not sure which version of the product you are currently using, please feel free to contact Mech-Mind Technical Support.

This topic introduces how to install and use the ROS 2 interface for Mech-Eye SDK.

The latest ROS 2 interfaces are only compatible with Mech-Eye SDK 2.3.4 or above. If you wish to keep using the existing ROS program after installing the latest version of Mech-Eye SDK, please modify the ROS program according to Migration Guide.

Prerequisites

In order to use the ROS 2 interface of Mech-Eye SDK, the following prerequisites must be satisfied:

ROS 2 version: The stable version Humble Hawksbill is recommended.
Ubuntu version: 22.04 is recommended, which is the main target platform of ROS Humble Hawksbill.

The ROS 2 interface of Mech-Eye SDK has been tested with the above versions of ROS 2 and the Ubuntu. The command examples in this topic are based on the above versions.

Install Mech-Eye SDK: Please refer to Mech-Eye SDK Installation Guide (Ubuntu).
Install the dependent software libraries of the interface.

Install Dependent Software Libraries

The ROS 2 interface of Mech-Eye SDK depends on the following software libraries:

OpenCV: version 3.0 or above
PCL: version 1.8 or above
(If you need to use the ros2 launch command) xterm: no version requirement

The ros2 launch command allows you to conveniently visualize the obtained point cloud data in RViz without requiring additional operations.

After installing ROS Humble Hawksbill, execute the following commands to installed the dependent software libraries:

sudo apt install libopencv-dev
sudo apt install ros-humble-cv-bridge
sudo apt install libpcl-dev
sudo apt install ros-humble-pcl-conversions
sudo apt install python3-colcon-common-extensions

Clone and Build the Interface

Follow these steps to clone and build the ROS 2 interface for Mech-Eye SDK:

Execute the following commands to clone the ROS 2 interface:

mkdir -p ~/colcon_ws/src && cd ~/colcon_ws/src
git clone https://github.com/MechMindRobotics/mecheye_ros2_interface.git

Execute the following command to set up the environment:

If ROS 2 was installed with the Debian packages:

# Replace ".bash" with your shell if you're not using bash
# Possible values are: setup.bash, setup.sh, setup.zsh
source /opt/ros/humble/setup.bash

If ROS 2 was built from source:

# Replace ".bash" with your shell if you're not using bash
# Possible values are: setup.bash, setup.sh, setup.zsh
. ~/ros2_humble/install/local_setup.bash

Execute the following commands to build the ROS 2 interface:
```
cd ~/colcon_ws
colcon build
```

Use the Interface

Follow these steps to use the ROS 2 interface for Mech-Eye SDK:

(Optional) Change the configurations in the MechMindCamera C++ programming file (.cpp) in ~/colcon_ws/src/mecheye_ros2_interface/src/ according to your needs:
- Automatically save the obtained files to local: Set the value of save_file to true to automatically save the obtained files to the /tmp/ directory.
- Connect to a specific camera through the specified IP address:
  1. Set the value of camera_ip to the IP address of the camera.
  2. Comment the if (!findAndConnect(camera)) function, and uncomment the lines below this function.
- Transform the reference frame: Modify the values of fx, fy, u and v to transform the camera reference frame to another frame. Use quaternions for rotation.
  
  After modifying the C++ programming files or MechMindCamera header file (.h) in the working directory, execute the colcon build command again.

Open a terminal and execute the following command to start up the interface:

Use the ros2 launch command:

source ~/colcon_ws/install/setup.bash
ros2 launch ~/colcon_ws/src/mecheye_ros2_interface/launch/start_camera.py

Use the ros2 run command:

source ~/colcon_ws/install/setup.bash
ros2 run mecheye_ros_interface start

Input the index of the camera to which you want to connect according to the instruction, and press Enter to connect to the camera.
Open a new terminal and execute the following command to invoke a service. Replace service_name with the name of the service, ServiceName with the name of the service file, parameter_name with the name of the camera parameter, and parameter_value with the parameter value to be set.

The Services section provides the example commands of each service.
```
source ~/colcon_ws/install/setup.bash
    ros2 service call [/service_name] [mecheye_ros_interface/srv/ServiceName] "{parameter_name: parameter_value}"
```

Topics

The following are the topics provided for the ROS 2 interface of Mech-Eye SDK:

/mechmind/camera_info: camera intrinsic parameters
/mechmind/stereo_color_image_left: the left stereo 2D image encoded as bgr8
/mechmind/stereo_color_image_left: the left stereo 2D image encoded as bgr8
/mechmind/stereo_color_image_right: the right stereo 2D image encoded as bgr8
/mechmind/depth_map: the depth map encoded as a single-channel image, the channel containing a 32-bit float number
/mechmind/point_cloud: the untextured point cloud data
/mechmind/textured_point_cloud: the textured point cloud data

Services

The following are the services provided by the ROS 2 interface of Mech-Eye SDK and the command example of each service.

Acquire Data

capture_color_image: Acquire the 2D image.

Example:

ros2 service call /capture_color_image mecheye_ros_interface/srv/CaptureColorImage

capture_depth_map: Acquire the depth map.

Example:

ros2 service call /capture_depth_map mecheye_ros_interface/srv/CaptureDepthMap

capture_point_cloud: Acquire the untextured point cloud.

Example:

ros2 service call /capture_point_cloud mecheye_ros_interface/srv/CapturePointCloud

capture_textured_point_cloud: Acquire the textured point cloud.

Example:

ros2 service call /capture_textured_point_cloud mecheye_ros_interface/srv/CaptureTexturedPointCloud

capture_stereo_color_images: Acquire the 2D images from both 2D cameras.
This service is only available for the following models: DEEP-GL, LSR S-GL, LSR L-GL, LSR XL-GL, and PRO XS-GL.

Example:
ros2 service call /capture_stereo_color_images mecheye_ros_interface/srv/CaptureStereoColorImages

Manage Parameter Groups

get_all_user_sets: Obtain the names of all available parameter groups.
Example:
ros2 service call /get_all_user_sets mecheye_ros_interface/srv/GetAllUserSets
get_current_user_set: Obtain the name of the currently selected parameter group.
Example:
ros2 service call /get_current_user_set mecheye_ros_interface/srv/GetCurrentUserSet
set_current_user_set: Select the parameter group to be used.
This service has 1 parameter:
- value (string): the name of the parameter group to be selected.
Example: Select the parameter group named 123.
ros2 service call /set_current_user_set mecheye_ros_interface/srv/SetCurrentUserSet "{value: '123'}"
Parameter group names that consist of numbers only must be surrounded by single quotation marks.
add_user_set: Add a parameter group. The newly added parameter group is automatically selected as the current parameter group.
This service has 1 parameter:
- value (string): the name of the parameter group to be added.
Example: Add a parameter group named 123.
ros2 service call /add_user_set mecheye_ros_interface/srv/AddUserSet "{value: '123'}"
Parameter group names that consist of numbers only must be surrounded by single quotation marks.
delete_user_set: Delete the specified parameter group.
This service has 1 parameter:

value (string): the name of the parameter group to be deleted.

Example: Delete the parameter group named 123.
ros2 service call /delete_user_set mecheye_ros_interface/srv/DeleteUserSet "{value: '123'}"
Parameter group names that consist of numbers only must be surrounded by single quotation marks.

Obtain Camera Information

device_info: Obtain the information of the currently connected camera.

The obtained information includes:

Model
Serial number
Hardware version
Firmware version
IP address
Subnet mask
IP address assignment method
Port number

Example:

ros2 service call /device_info mecheye_ros_interface/srv/DeviceInfo

Adjust Camera Parameters

Mech-Eye SDK 2.3.4 and above provide methods according to the data types of the camera parameters, and the ROS 2 interface provides the corresponding services. To obtain or adjust the value of a camera parameter, call the service corresponding to the data type of the camera parameter and input the name of the camera parameter as the service’s parameter. The data types and names of the camera parameters can be found in the header files in the installation path of Mech-Eye SDK: /opt/mech-mind/mech-eye-sdk/include/area_scan_3d_camera/parameters/.

The following data types of camera parameters are distinguished:

_Int
_Float
_Bool
_Enum
_Roi
_Range
_FloatArray

get_int_parameter: Obtain the value of the specified _Int-type camera parameter.
This service has 1 parameter:
- name (string): the name of the camera parameter.
Example: Obtain the value of the Scan2DExpectedGrayValue parameter.
ros2 service call /get_int_parameter mecheye_ros_interface/srv/GetIntParameter "{name: Scan2DExpectedGrayValue}"
set_int_parameter: Set the value of the specified _Int-type camera parameter.
This service has 2 parameters:
- name (string): the name of the camera parameter.
- value (int): the new value of the camera parameter.
Example: Set the value of the Scan2DExpectedGrayValue parameter to 101.
ros2 service call /set_int_parameter mecheye_ros_interface/srv/SetIntParameter "{name: Scan2DExpectedGrayValue, value: 101}"
get_float_parameter: Obtain the value of the specified _Float-type camera parameter.
This service has 1 parameter:
- name (string): the name of the camera parameter.
Example: Obtain the value of the Scan2DExposureTime parameter.
ros2 service call /get_float_parameter mecheye_ros_interface/srv/GetFloatParameter "{name: Scan2DExposureTime}"
set_float_parameter: Set the value of the specified _Float-type camera parameter.
This service has 2 parameters:
- name (string): the name of the camera parameter.
- value (float): the new value of the camera parameter.
Example: Set the value of the Scan2DExposureTime parameter to 40.1.
ros2 service call /set_float_parameter mecheye_ros_interface/srv/SetFloatParameter "{name: Scan2DExposureTime, value: 40.1}"
get_bool_parameter: Obtain the value of the specified _Bool-type camera parameter.
This service has 1 parameter:
- name (string): the name of the camera parameter.
Example: Obtain the value of the Scan2DToneMappingEnable parameter.
ros2 service call /get_bool_parameter mecheye_ros_interface/srv/GetBoolParameter"{name: Scan2DToneMappingEnable}"
set_bool_parameter: Set the value of the specified _Bool-type camera parameter.
This service has 2 parameters:
- name (string): the name of the camera parameter.
- value (bool): the new value of the camera parameter.
Example: Set the value of the Scan2DToneMappingEnable parameter to True.
ros2 service call /set_bool_parameter mecheye_ros_interface/srv/SetBoolParameter "{name: Scan2DToneMappingEnable, value: True}"
get_enum_parameter: Obtain the value of the specified _Enum-type camera parameter.
This service has 1 parameter:
- name (string): the name of the camera parameter.
Example: Obtain the value of the Scan2DExposureMode parameter.
ros2 service call /get_enum_parameter mecheye_ros_interface/srv/GetEnumParameter "{name: Scan2DExposureMode}"
set_enum_parameter: Set the value of the specified _Enum-type camera parameter.
This service has 2 parameters:
- name (string): the name of the camera parameter.
- value (string): the new value of the camera parameter.
Example: Set the value of the Scan2DExposureMode parameter to Timed.
ros2 service call /set_enum_parameter mecheye_ros_interface/srv/SetEnumParameter "{name: Scan2DExposureMode, value: Timed}"
get_roi_parameter: Obtain the value of the specified _Roi-type camera parameter.
This service has 1 parameter:
- name (string): the name of the camera parameter.
Example: Obtain the value of the Scan2DROI parameter.
ros2 service call /get_roi_parameter mecheye_ros_interface/srv/GetROIParameter "{name: Scan2DROI}"
set_roi_parameter: Set the value of the specified _Roi-type camera parameter.
This service has 5 parameters:
- name (string): the name of the camera parameter.
- x (uint32): the new x-coordinate of the upper-left corner of the ROI.
- y (uint32): the new y-coordinate of the upper-left corner of the ROI.
- width (uint32): the new width of the ROI.
- height (uint32): the new height of the ROI.
Example: Set the value of the Scan2DROI parameter to 20, 20, 600, 800 (which is an ROI that is 600 px wide, 800 px high and has its upper-left corner at the (20,20) pixel).
ros2 service call /set_roi_parameter mecheye_ros_interface/srv/SetROIParameter "{name: Scan2DROI, x: 20, y: 20, width: 600, height: 800}"
get_range_parameter: Obtain the value of the specified _Range-type camera parameter.
This service has 1 parameter:
- name (string): the name of the camera parameter.
Example: Obtain the value of the DepthRange parameter.
ros2 service call /get_range_parameter mecheye_ros_interface/srv/GetRangeParameter "{name: DepthRange}"
set_range_parameter: Set the value of the specified _Range-type camera parameter.
This service has 3 parameters:
- name (string): the name of the camera parameter.
- lower (int32): the new minimum value of the camera parameter’s value range.
- upper (int32): the new maximum value of the camera parameter’s value range.
Example: Set the value of the DepthRange parameter to 200–1000.
ros2 service call /set_range_parameter mecheye_ros_interface/srv/SetRangeParameter "{name: DepthRange, lower: 200, upper: 1000}"
get_float_array_parameter: Obtain the value of the specified _FloatArray-type camera parameter.
This service has 1 parameter:
- name (string): the name of the camera parameter.
Example: Obtain the value of the Scan2DHDRExposureSequence parameter.
ros2 service call /get_float_array_parameter mecheye_ros_interface/srv/GetFloatArrayParameter "{name: Scan2DHDRExposureSequence}"
set_float_array_parameter: Set the value of the specified _FloatArray-type camera parameter.
This service has 2 parameters:
- name (string): the name of the camera parameter.
- array (float64[]): the new value of the camera parameter.
Example: Set the value of the Scan2DHDRExposureSequence parameter to [30.0, 35.5, 40.0].
ros2 service call /set_float_array_parameter mecheye_ros_interface/srv/SetFloatArrayParameter "{name: Scan2DHDRExposureSequence, array: [30.0,35.5,40.0]}"

We Value Your Privacy

We use cookies to provide you with the best possible experience on our website. By continuing to use the site, you acknowledge that you agree to the use of cookies. If you decline, a single cookie will be used to ensure you're not tracked or remembered when you visit this website.

I accept

I don't accept