ROS2-based Node for OMRON SENTECH Cameras

1. Overview

This stcamera_ros2 package is provided by OMRON SENTECH, CO.,LTD. Any cameras supported by SentechSDK are also supported by this package on ROS2. You can use ROS2 topics and services to retrieve images from the camera, configure the camera, generate triggers, and more. *Note that GenICam GenApi * nodes are completely different from the ones in ROS. Each GenICamGenApi node is used to get information and configure the camera using a generic interface. The detail of the GenICam GenApi can be found in the GenICam GenApi documentation.

2. Installation

This package has been tested on ROS2-Humble Hawksbill (Ubuntu 22.04 64bit). This package uses SentechSDK (v 1.2.1 or later), so please install SentechSDK before installing this package. If you are new to the SetenchSDK, you can check out the documentation that comes with the SentechSDK and make sure that the SentechSDK’s Viewer (StViewer) can capture images from your camera to make the rest of the process go smoothly. Also, if you use StViewer to change a camera’s settings in advance and then use UserSetSave/UserSetDefault to save those settings to the camera, you may not need to set the camera in ROS2. You can download the SentechSDK from the following URL:

SentechSDK download site

For more information about how to install and use the SentechSDK, see the documentation that accompanies the SentechSDK. If the environment variables for using the SentechSDK are not set, run the following command (if you installed the SentechSDK in/opt/sentech):

source /opt/sentech/.stprofile

If the ROS2 environment has not been set, execute the following command:

source /opt/ros/humble/setup.bash

Create a workspace (for example, ~/dev_ws) and move it to the current directory.

mkdir -p ~/dev_ws/src
cd ~/dev_ws/src

Clone the stcamera_ros2 project.

git clone https://github.com/ose-support-ros/stcamera_ros2.git -b humble

Check dependencies and install required packages.

cd ~/dev_ws
rosdep install -i --from-path src --rosdistro humble -y

Build.

colcon build

3. StCameraNode

Generating a StCameraNode in the package will start getting images from the specified camera according to the parameter camera_to_connect. A StCameraNode can be generated with one of the following commands:

source install/setup.bash
ros2 launch stcamera_launch stcamera_launch.py

or

source install/setup.bash
ros2 component standalone --node-name 'stcameras' --node-namespace '/stcamera_launch' stcamera_components stcamera::StCameraNode

or

source install/setup.bash
ros2 run rclcpp_components component_container

source install/setup.bash
ros2 component load /ComponentManager  -n 'stcameras' --node-namespace '/stcamera_launch' stcamera_components stcamera::StCameraNode``

The node names and name spaces listed in the second and third methods are optional, but you can make the sample program work by specifying them as above. If you start StCameraNode with the stcamera_launch file script, you can easily set camera connection parameters in default.yaml(./install/stcamera_launch/share/stcamera_launch/config/). See the next chapter for details on setting parameters.

3.1. Node Parameters

Parameter values are case sensitive. The parameters that can be set are as follows.

• camera_to_connect : Specify the camera to use with ROS2. This parameter must be set before StCameraNode is executed. If you change this parameter during a run, the change is not reflected. If the setting is empty, the first camera detected is used. If “all” is specified, all detected cameras are used. If CAMERA_ID or CAMERA_MODEL(SERIAL) is specified, only the specified camera will be used.

Examples:

• camera_to_connect: []: The first camera detected is used.
• camera_to_connect: [“all”]: All detected cameras are used.
• camera_to_connect: [“00:11:1c:f6:yy:xx”,”STC-MCS510U3V(00XXYY0)”]: Only GigEVision camera with MAC address “00:11:1c:f6:yy:xx” and USB3 Vision camera of which model is “STC-MCS510U3V”, with serial number “00XXYY0” will be used.
• camera_to_connect: [“14210003XXYY”]: A camera with ID “14210003 XXYY” will be used.

3.2. Camera Namespace

StCameraNode declares a topic and service for each camera. Each camera’s namespace used to access individual camera topics and services is automatically generated using the following rules:

• If camera_to_connect is empty or “all,” the format of the namespace is dev_{CAMERA_ID}. {CAMERA_ID} is the ID of the camera. If the connected camera ID is “14210003 xxYY”, the namespace will be “dev_14210003xxYY”. Non-alphanumeric characters in the camera ID, such as GigEVision’s MAC address, will be replaced with underscores.

• If camera_to_connect is CAMERA_MODEL(SERIAL) or CAMERA_ID, the namespace will be of the form dev_{CAMERA_MODEL_SERIAL_} or dev_{CAMERA_ID}. {CAMERA_MODEL_SERIAL_} is a rewritten string from CAMERA_MODEL(SERIAL). {CAMERA_ID} is the camera ID. Non-alphanumeric characters are replaced with underscores.

3.3. Published Topics

Topics published by StCameraNode include:

3.4. Services

StCameraNode offers the following services:

(The GenICam nodes listed below are completely separate from the ROS nodes.)

Attention:

• Some GenICam nodes are not accessible during image acquisition (error occurred). In that case, please stop the image acquisition and access again. You can stop image acquisition with the service call enable_image_acquisition. For example:
  

ros2 service call /stcamera_launch/dev_CAMERA-NS/enable_image_acquisition stcamera_msgs/srv/EnableImageAcquisition "{value: false}"

waiting for service to become available...
requester: making request: stcamera_msgs.srv.EnableImageAcquisition_Request(value=False)

response:
stcamera_msgs.srv.EnableImageAcquisition_Response()

• Integer-type GenICam nodes may have limited values that can be set. For the settings below, increment is set to 16, so if the value to be increased or decreased is not a multiple of that, an error occurs.
  

ros2 service call /stcamera_launch/dev_CAMERA-NS/get_genicam_node_info stcamera_msgs/srv/GetGenICamNodeInfo "{genicam_module: 'RemoteDevice', genicam_node: 'Width'}"

requester: making request: stcamera_msgs.srv.GetGenICamNodeInfo_Request(genicam_module='RemoteDevice', genicam_node='Width')

response:
stcamera_msgs.srv.GetGenICamNodeInfo_Response(name='Width', description='Width of the image provided by the device (in pixels).', name_space='Standard', interface_type='IInteger', access_mode='Read Only', is_cachable='Yes', visibility='Beginner', caching_mode='Write to register, write to cache on read', is_streamable=True, enum_value_str_list=[], enum_value_int_list=[], current_value='2448', min_value='64', max_value='2448', increment='16', unit='', child_node_list=[])

• For camera settings that do not need to be changed during use, you can save the trouble of setting them every time by setting them in StViewer that comes with the Sentech SDK beforehand, saving them to the camera (UserSetSave), and setting them to be reflected when the camera is turned on (UserSetDefault).

3.5. Error codes

Codes | Description —: | — < 0 | GenTL error codes. Please refer to GenICam GenTL documentation. 0 | No error. 30000 | GenICam GenericException occurred. 30001 | Module name is invalid. 30002 | (GenICam) Node is either invalid or inaccessible. 30003 | Event already ON. 30004 | Event already OFF. 30005 | Image acquisition already ON. 30006 | Image acquisition already OFF. 30007 | Chunk is not supported. 30008 | Chunk name is not valid. 30009 | Trigger is not supported. 30010 | Trigger name is not valid. 30011 | Event is not supported. 30012 | Event name is not valid.

4. Usage

4.1. Displaying acquired images withrqt_image_view and Changing Camera Gain:

• Generates a StCameraNode.

cd ~/dev_ws
source install/setup.bash
ros2 launch stcamera_launch stcamera_launch.py

• Check the name of the current published topic.

ros2 topic list

• Run rqt_image_view and select/xxxx/xxxx/image_raw to view the images.
  

ros2 run rqt_image_view rqt_image_view

If the camera is in trigger mode, no images can be captured until a trigger is generated. Discard the node, switch to free run mode with StViewer, etc., and check again.

• You can check the currently issued service and its type with a command like this:

ros2 service list -t

• You can check the type details with a command like this:

ros2 interface show stcamera_msgs/srv/GetGenICamNodeInfo

• Get information for GenICam node “Gain”.

ros2 service call /stcamera_launch/dev_142100000000/get_genicam_node_info stcamera_msgs/srv/GetGenICamNodeInfo '{genicam_module: "RemoteDevice", genicam_node: "Gain"}'

waiting for service to become available...
requester: making request: stcamera_msgs.srv.GetGenICamNodeInfo_Request(genicam_module='RemoteDevice', genicam_node='Gain')

response:
stcamera_msgs.srv.GetGenICamNodeInfo_Response(error_info=stcamera_msgs.msg.ErrorInfo(error_code=0, description=''), name='Gain', description='Controls the selected gain as an absolute physical value. This is an amplification factor applied to the video signal.', tool_tip='Controls the selected gain as an absolute physical value.', display_name='Gain', name_space='Standard', interface_type='IFloat', access_mode='Read and Write', is_cachable='Yes', visibility='Beginner', caching_mode='Does not use cache', polling_time=-1, is_streamable=True, is_implemented=True, is_available=True, is_readable=True, is_writable=True, is_feature=True, enum_value_str_list=[], enum_value_int_list=[], current_value='0', min_value='0.000000', max_value='192.000000', increment='', unit='', child_node_list=[])

• Reads the value of the GenICam node “Gain” (of type IFloat).
  

ros2 service call /stcamera_launch/dev_142100000000/read_node_float stcamera_msgs/srv/ReadNodeFloat '{genicam_module: "RemoteDevice", genicam_node: "Gain"}'

waiting for service to become available...
requester: making request: stcamera_msgs.srv.ReadNodeFloat_Request(genicam_module='RemoteDevice', genicam_node='Gain')

response:
stcamera_msgs.srv.ReadNodeFloat_Response(error_info=stcamera_msgs.msg.ErrorInfo(error_code=0, description=''), value=0.0)

• Set the GenICam node “Gain” (type IFloat) to 100.
  

ros2 service call /stcamera_launch/dev_142100000000/write_node_float stcamera_msgs/srv/WriteNodeFloat '{genicam_module: "RemoteDevice", genicam_node: "Gain", value: 100}'

requester: making request: stcamera_msgs.srv.WriteNodeFloat_Request(genicam_module='RemoteDevice', genicam_node='Gain', value=100.0)

response:
stcamera_msgs.srv.WriteNodeFloat_Response(error_info=stcamera_msgs.msg.ErrorInfo(error_code=0, description=''))

4.2. Get images in free run or trigger mode

The node “grabber” in the stcamera_demos folder uses the StCameraNode to retrieve the image data. There are C++ and Python versions, and the C++ version is code that doubles as a test of how services and topics work, covering a variety of services and topics.

5. About Support

OMRON SENTECH does not provide direct support for this package. For questions, glitches, etc., please utilize the issuues on GitHub.