About | Support | Discussion Forum | Index | Service Status | ros @ Robotics Stack Exchange

melodic noetic   Show EOL distros: 

Overview

The Willow Garage 100 Mbps Ethernet (WGE100) camera is a 752x480 Ethernet camera developed for the PR2 robot. The PR2's narrow stereo camera is a monochrome WGE100, while its wide stereo camera and forearm cameras are in color. This package contains the wge100_camera_node, a ROS driver for a monocular WGE100 camera, the wge100_multi_configurator node, which allows two cameras in a stereo pair to be configured from one centralized location, and a suite of command-line tools to manage the camera.

Using the Dual Stereo Cameras or Forearm Cameras on the PR2

Most PR2 users will not need the information on this page as the cameras are brought up at the same time as the robot. Instead they can refer to the following sources:

• For simplified instructions on setting up camera frame rate, or synchronization with the PR2's texture projector refer to the pr2_camera_synchronizer documentation.

• For calibrating the cameras or doing vision processing, you will also want to look at the image pipeline stack.

• Other packages are available to use and process data coming from monocular or stereo cameras.

• Tutorials are available showing how to dynamically reconfigure a node's parameters using a GUI, from the command-line, a launch file or C++ code.

• For a reference of the WGE100 parameters you can skip directly to the ROS API to learn about various parameters.

Concurrent Access

Except for the access_register and discover tools, which can be used at any time, the WGE100 tools are not designed for concurrent access to the camera.

If you try to use two tools on different IP addresses, the second one will override the settings from the previous one. If you try to use two nodes at once, they will fight each other, neither one managing to take control of the camera.

Time Stamping

The timestamps returned by the wge100_camera_node are with respect to the end of the exposure. The timestamps can be produced in one of two ways:

• If the camera is externally triggered, the driver expects timestamps to be provided on a roslib/Header topic. The topic the camera subscribes to is defined by the ~trig_timestamp_topic parameter. The driver then attempts to match timestamps with image arrival times.

• If the camera is internally triggered, the driver uses the arrival time of the first packet in the message, offset by first_packet_offset as an estimate of the end of the exposure. These estimates are then filtered based on the known frame rate to get a more accurate estimate with less jitter.

Camera URLs

When working with a WGE100 camera, the user needs to identify the camera she wishes to work with. Cameras are identified using URLs, which can refer either to the camera's serial number or to its descriptive name (set using set_name). If there is only one camera present, a URL can indicate that whatever camera is found should be used.

Types of URLs

There are three types of camera URLs:

• name URLs indicate the name of the camera to be found. You can set the name of a camera using the set_name utility. E.g.: name://wide_stereo_l

• serial URLs indicate the serial number of the camera to be found. E.g.: serial://2701025

• any URLs will match any camera. E.g.: any://

If a URL matches more than one camera, none of them will be selected, and an error will be reported. This situation cannot happen with a serial URL as camera serial numbers are unique.

Specifying an IP address

In normal use, the WGE100 camera has an IP address stored in flash that it will use for communication. However it is sometimes useful to have the camera use a different IP address, for example when the IP address in flash is invalid, or if is transiently placed on a different network from the one it is configured for. In that case, an IP address can be added to the URL. An IP address is introduced with the @ sign. E.g.: name://[email protected]

When an IP address is specified, WGE100 camera tools will configure the camera to use that address before they try to work with it. The IP address that is specified using @ will get reset each time a new tool is used. To set a camera's IP address permanently, use the set_name tool.

Specifying a Network Interface

In some cases, a single camera may be visible on multiple interfaces, or cameras with the same name may be visible on different network interfaces. In this case, an interface name can be included in the camera URL to force a particular interface to be used for communication. An interface name is introduced with the # sign. For example, on the PR2, only the lan0 interface is searched to avoid potential conflicts with identically named cameras on the wan0 interface: name://wide_stereo_l#lan0

Putting it all Together

The most general form for a WGE100 camera URL is:

name://camera_name[@camera_ip][#local_interface]
serial://serial_number[@camera_ip][#local_interface]
any://[@camera_ip][#local_interface]

Some example URLs:

ROS API

wge100_camera_node

wge100_camera_node is a driver for the WGE100 camera that is found in the PR2 forearms and in the PR2 dual stereo camera. The black and white cameras support two register sets in hardware, allowing the imager settings to be swapped back and forth between two settings for even and odd frames. The driver publishes the images for each register set in its own namespace. This is a purely monocular driver. A stereo WGE100 camera needs one wge100_camera_node for each camera in the pair.

Subscribed Topics

<~trig_timestamp_topic> (roslib/Header)

• In external mode only: topic on which the wge100_camera_node gets timestamps at which the camera was triggered. The node matches these timestamps to incoming images and uses them to timestamp the frame. The name of this topic is extracted from the ~trig_timestamp_topic parameter.

Published Topics

camera/image_raw (sensor_msgs/Image)

• Images taken with the primary register set

camera/camera_info (sensor_msgs/CameraInfo)

• Camera intrinsics for images published on camera/image_raw

camera_alternate/image_raw (sensor_msgs/Image)

• Images taken with the alternate register set

camera_alternate/camera_info (sensor_msgs/CameraInfo)

• Camera intrinsics for images published on camera_alternate/image_raw

/diagnostics (diagnostic_msgs/DiagnosticStatus)

• Diagnostic status information.

Services

~self_test (diagnostic_msgs/SelfTest)

• Starts the self test.

camera/set_camera_info (sensor_msgs/SetCameraInfo)

• Sets the camera's intrinsics

~board_config (wge100_camera/BoardConfig)

• Internal use only. (Used to set the camera's MAC address and serial number during production. Can only be used once.)

Parameters

Dynamically Reconfigurable Parameters

All the wge100_camera_node parameters are dynamically reconfigurable. See the dynamic_reconfigure package for details on dynamically reconfigurable parameters.

~camera_url (str, default: any://)

• URL defining which camera to connect to, on what interface and with which IP address.

~frame_id (str, default: )

• Sets the TF frame from which the camera is publishing.

~register_set (int, default: 0)

• Select the register set to work with. In auto mode, an extra pulse on the trigger signal indicates that the alternate set should be used. Possible values are: PrimaryRegisterSet (0): The primary register set is always used., AlternateRegisterSet (1): The alternate register set is always used., Auto (2): The trigger signal selects which register set to use.

~packet_debug (bool, default: false)

• If true, warns on diagnostics for any dropped packet event.

Region of Interest Parameters

The following parameters define the region of interest on the imager, and how it is mapped into the resulting image. The camera_info topics will only be valid if these parameters are set to the same values as when the camera was calibrated. Currently the camera driver will detect mismatches in width and height, but not for the other parameters.

~width (int, default: 640)

• Number of pixels horizontally. Range: 1 to 752

~height (int, default: 480)

• Number of pixels vertically. Range: 1 to 480

~imager_rate (double, default: 30.0)

• Sets the frame rate of the imager. In externally triggered mode this must be more than trig_rate Range: 1.0 to 100.0

~horizontal_binning (int, default: 1)

• Number of pixels to bin together horizontally. Range: 1 to 4

~vertical_binning (int, default: 1)

• Number of pixels to bin together vertically. Range: 1 to 4

~horizontal_offset (int, default: 0)

• Horizontal offset between the center of the image and the center of the imager in pixels. Range: -376 to 376

~vertical_offset (int, default: 0)

• Vertical offset between the center of the image and the center of the imager in pixels. Range: -240 to 240

~mirror_x (bool, default: False)

• Mirrors the image left to right.

~mirror_y (bool, default: False)

• Mirrors the image top to bottom.

~rotate_180 (bool, default: False)

• Rotates the image 180 degrees. Acts in addition to the mirror parameters

Triggering Parameters

The following parameters define how the camera is triggered, and how the driver estimates the time at which the exposure ended. Details of how camera timestamps are produced can be found here.

~ext_trig (bool, default: False)

• Set the camera to trigger from the external trigger input.

~rising_edge_trig (bool, default: True)

• Indicates that the camera should trigger on rising edges (as opposed to falling edges).

~trig_timestamp_topic (str, default: )

• Sets the topic from which an externally triggered camera receives its trigger timestamps.

~trig_rate (double, default: 30.0)

• Sets the expected triggering rate in externally triggered mode. Range: 1.0 to 100.0

~first_packet_offset (double, default: 0.0025)

• Offset between the end of exposure and the minimal arrival time for the first frame packet. Only used when using internal triggering. Range: 0.0 to 0.02

Shared Imager Settings

The following imager settings parameters are shared between the two register sets.

~brightness (int, default: 58)

• The camera brightness for automatic gain/exposure. Range: 1 to 64

~black_level (int, default: 0)

• Sets the black level. Range: -127 to 127

~max_exposure (double, default: 0.0)

• Maximum exposure time in seconds in automatic exposure mode. Zero for automatic. Range: 0.0 to 0.1

Primary Imager Settings

The following imager settings apply only to the primary register set.

~auto_exposure (bool, default: True)

• Sets the camera exposure duration to automatic. Causes the exposure setting to be ignored.

~exposure (double, default: 0.01)

• Maximum camera exposure time in seconds. The valid range depends on the video mode. Range: 0.0 to 0.1

~auto_gain (bool, default: True)

• Sets the analog gain to automatic. Causes the gain setting to be ignored.

~gain (int, default: 32)

• The camera analog gain. Range: 16 to 64

~companding (bool, default: True)

• Turns on companding (a non-linear intensity scaling to improve sensitivity in dark areas).

Alternate Imager Settings

The following imager settings apply only to the alternate register set.

~auto_exposure_alternate (bool, default: True)

• Sets the alternate camera exposure duration to automatic. Causes the exposure_alternate setting to be ignored.

~exposure_alternate (double, default: 0.01)

• Alternate camera exposure in seconds. The valid range depends on the video mode. Range: 0.0 to 0.1

~auto_gain_alternate (bool, default: True)

• Sets the alternate analog gain to automatic. Causes the gain_alternate setting to be ignored.

~gain_alternate (int, default: 32)

• The alternate camera analog gain. Range: 16 to 64

~companding_alternate (bool, default: True)

• Turns on companding for the alternate imager register set

wge100_multi_configurator

wge100_multi_configurator is a node that allows multiple wge100_camera_nodes to receive identical configurations. It acts like a dynamic_reconfigure that passes each request it receives to each one of the wge100_camera_nodes that it manages. This node's intended use is to allow both wge100_camera_nodes in a stereo pair to be configured from one centralized location.

Parameters

Dynamically Reconfigurable Parameters

See the dynamic_reconfigure package for details on dynamically reconfigurable parameters.

~camera_nodes (str, default: "wge100_camera")

• Space separated list of nodes that should be controlled by this multi-configurator.

~<any wge100_camera_node parameter except camera_url> (same, default: same)

• When this parameter is set, a reconfigure request is passed down to each underlying wge100_camera_node. Currently changes in the underlying nodes are not passed back up to this node's parameters.

Command-Line Tools

The following command-line tools are helpful when configuring the camera.

Camera Discovery: discover

The discover tool uses a broadcast packet to find cameras on the network. It can be run on a single network interface:

$ rosrun wge100_camera discover eth1
Found camera serial://13 name://test MAC: 00:24:cd:00:00:83 iface: eth2:avahi current IP: 169.254.8.124, PCB rev: C HDL rev: 400 FW rev: 118

or on all network interfaces:

$ rosrun wge100_camera discover
Found camera serial://13 name://test MAC: 00:24:cd:00:00:83 iface: eth2:avahi current IP: 169.254.8.124, PCB rev: C HDL rev: 400 FW rev: 118

The IP address that is reported by the discover tool is the currently configured address for the camera. This may be different from the IP address stored in the camera's flash, and to which the camera defaults when it is reset. This IP may or may not be valid for the interface on which the camera is located, and it is quite possible that you will not be able to communicate with the camera at this particular IP address.

Sometimes a camera can be seen from multiple interfaces. The discover tool only reports the first interface on which a response is seen. The camera can nevertheless be configured to run from an interface other than the one on which it was reported.

Camera Setup: set_name

The camera name and IP address that are stored in the camera's flash can be accessed using the set_name tool. With a single camera URL argument, set_name reports the current settings.

$ rosrun wge100_camera set_name serial://[email protected]
Previous camera name was: test.
Previous camera IP: 169.254.8.124.

With an additional name and IP argument, the values in the flash are modified, and the camera is automatically reset so that they become the new defaults.

$ rosrun wge100_camera set_name serial://[email protected] new_name 169.254.8.200
Previous camera name was: test
Previous camera IP: 169.254.8.124
Success! Restarting camera, should take about 10 seconds to come back up after this.
$ rosrun wge100_camera set_name serial://15
Previous camera name was: new_name
Previous camera IP: 169.254.8.200

Camera Intrinsics: set_calibration

The camera intrinsics that are stored in the camera's flash can be accessed using the set_calibration tool. With a single camera URL argument, set_name reports the current settings.

$ rosrun wge100_camera set_calibration name://wide_stereo_l
Unable to create ARP entry (are you root?), continuing anyway
Reading old calibration...
[image]
...

With an additional file name argument, the values in the flash are modified.

$ rosrun wge100_camera set_calibration serial://[email protected] intrinsics.ini

In general, calibration of the camera and uploading of the parameters should be done through the camera calibration package. These programs will perform the calibration, and make the service call to flash the intrinsics back onto the camera.

Resetting a Camera: reset_cam

The camera can be reset using the reset_cam command, which takes a single camera_url argument.

$ rosrun wge100_camera reset_cam any://

Note: The reconfigure_cam tool currently has the same effect as reset_cam. In future firmware versions reconfigure_cam will always cause the camera FPGA to reconfigure itself, whereas reset_cam may do a softer reset that resets all components without reconfiguring the FPGA.

Advanced Command-Line Tools

For advanced functionality such as

1. Accessing Imager Registers: access_register

2. Reflashing the Camera Firmware: upload_mcs

3. Checking Flash Programming: check_flash

4. Dumping the Flash Contents: read_all_flash

Flash Contents

For information on contents of the WGE100 flash memory, you may consult this page.

Tutorials