Balluff - BVS CA-SF Technical Documentation
Working with ROS (Robot Operating System)

Recommended ROS Packages

If you are planning to use Balluff/MATRIX VISION GenICam™ devices in a ROS-application, we recommend to use two packages, maintained by the Roboception GmbH:

  • rc_genicam_api, which offers a GenICam™-based access to GenTL™ producers
  • rc_genicam_camera, which builds on the GenICam™ access provided by rc_genicam_api and provides a ROS-node for acquiring images from a camera

Since these packages can be a solid foundation for your ROS project, the following chapters describe how you can use them.

Initial Setup

  1. Make sure to install the Impact Acquire package. Afterwards, the GENICAM_GENTL64_PATH environment variable should point to a directory that contains the mvGenTLProducer.cti library.
  2. Install your ROS environment. Please refer to the ROS Project if you need more detailed advice.
  3. Install or download and build the Roboception packages.
    • For Ubuntu and Debian systems, use the package manager to install:
      1. ros-DISTRIBUTION-rc-genicam-api
      2. ros-DISTRIBUTION-rc-genicam-camera (e.g. apt install ros-noetic-rc-genicam-api ros-noetic-rc-genicam-camera if you are using ROS Noetic Ninjemys)
    • If you want to build it yourself, the packages are available on GitHub:
      1. rc_genicam_api like mentioned on the ROS description page http://wiki.ros.org/rc_genicam_api
      2. rc_genicam_camera

Testing The Setup

To test your setup, you may use the gc_info command-line tool, that comes with the rc_genicam_api package. This tool will use the GenICam Transport Layer that is found within the GENICAM_GENTL64_PATH. A first step might be to list all available devices:
gc_info -l

The output should look similar to this:

Example of the output from the 'gc_info -l' command

The GenICam Transport Layer assigns an individual DeviceID to all devices, which can be used to address the device.

Streaming From A Device

Start the node with the command:
rosrun rc_genicam_camera rc_genicam_camera _device:=DeviceID_from_step_before

Note
If the DeviceID contains one or more colons, it must be preceded by a colon (e.g. :deviceName_MAC:ADDRESS:PART).

With this setup, the node will publish images to the topic /image_raw. You can now use the tool of your choice to view the image data, for example RQT, that comes with the ROS distribution.

Initial Device Configuration

The rc_genicam_camera node accepts an optional config file on startup, to launch the device with a defined setup. There is some more information about this file on the GitHub page of rc_genicam_camera, but in short it is a list of <property>=<value>, using one line per property. The contents of this file could look like this:

# A comment line
Width=720
Height=480
ExposureAuto=Continuous
mvExposureAutoUpperLimit=20000

To launch the node with the config file, simply append it to the rosrun call:
rosrun rc_genicam_camera rc_genicam_camera _device:=DeviceID _config_file:=/path/to/config/file

Starting the node with DeviceID and config file.

To request a list of all available properties that are accepted by the device, use the gc_info tool again. Calling
gc_info DeviceID
will return a list, that contains all registered properties:

Listing of available properties from 'gc_info DeviceID'

You may also use ImpactControlCenter to search for available properties. There, you can find the possible options within the GenICam tree. If you are uncertain about valid values for a property, right click on it and choose 'Detailed Feature Information'.

Device Configuration While Streaming

Many properties can be changed while the device is already streaming. This can be accomplished with the set_genicam_parameter-service, offered by the rc_genicam_camera node. For testing, you may try to use the rosservice command. Call rosservice list to see all available services.
To set a property, e.g. the mvExposureAutoUpperLimit, execute:
rosservice call /rc_genicam_camera/set_genicam_parameter 'mvExposureAutoUpperLimit=10000'
This will attempt to set the mvExposureAutoUpperLimit property to the provided value and return 0 if successful.

Another service, get_genicam_parameter is available to read values from properties. E.g. if you want to get the image width, you could execute
rosservice call /rc_genicam_camera/get_genicam_parameter 'Width'
For a more detailed description of the services, have a look at the rc_genicam_camera Github page.