usb_cam ROS 2 Driver

The driver supports three IO methods for transferring video frames. These can be configured via parameters:

• read: Copies the video frame between user and kernel space.
• mmap: Uses memory-mapped buffers allocated in kernel space.
• userptr: Uses memory buffers allocated in user space.

If image_transport_plugins is installed, usb_cam automatically publishes a compressed topic. Because tools like rviz2 or show_image.py may not support compressed images directly, you can use image_transport to republish the stream as raw uncompressed data.

ros2 run image_transport republish compressed raw --ros-args --remap in/compressed:=image_raw/compressed --remap out:=image_raw/uncompressed

If you have a supported ROS 2 distribution installed on Linux, you can install the usb_cam package using apt-get. Replace <ros2-distro> with your actual ROS 2 distribution name (e.g., humble, foxy).

sudo apt-get install ros-<ros2-distro>-usb-cam

If binaries are unavailable, follow these steps to build from source in your colcon workspace:

1. Clone the repository into your src directory.
2. Install dependencies using rosdep.
3. Build the package using colcon.
4. Source the workspace setup file.

# 1. Clone
cd /path/to/colcon_ws/src
git clone https://github.com/ros-drivers/usb_cam.git

# 2. Install dependencies
cd /path/to/colcon_ws
rosdep install --from-paths src --ignore-src -y

# 3. Build
colcon build

# 4. Source
source /path/to/colcon_ws/install/setup.bash

You can start the camera driver in three different ways. Choose only one:

1. Default settings: Runs the node without any external parameters.
2. With YAML parameters: Runs the node using a specific configuration file (e.g., usb_cam/config/params.yaml).
3. Using Launch file: Launches the node with parameters loaded from the default config file and starts an additional image viewer node.

# Option 1: Default settings
ros2 run usb_cam usb_cam_node_exe

# Option 2: Using a YAML parameters file
ros2 run usb_cam usb_cam_node_exe --ros-args --params-file /path/to/colcon_ws/src/usb_cam/config/params.yaml

# Option 3: Launch with image viewer
ros2 launch usb_cam camera.launch.py

To debug memory leaks, build the package with the SANITIZE=1 flag. After building, run the executable directly with ASAN_OPTIONS to enable reporting upon shutdown.

# Build with sanitizer enabled
colcon build --packages-select usb_cam --cmake-args -DSANITIZE=1

# Run the executable directly
ASAN_OPTIONS=new_delete_type_mismatch=0 ./install/usb_cam/lib/usb_cam/usb_cam_node_exe

To run multiple cameras simultaneously, use ROS 2 remapping to assign each node a unique namespace (__ns) and provide unique parameter files for each.

# Camera 0
ros2 run usb_cam usb_cam_node_exe --ros-args --remap __ns:=/usb_cam_0 --params-file /path/to/usb_cam/config/params_0.yaml

# Camera 1
ros2 run usb_cam usb_cam_node_exe --ros-args --remap __ns:=/usb_cam_1 --params-file /path/to/usb_cam/config/params_1.yaml

To verify the installation and code integrity, use colcon to run tests.

Unit Tests:

colcon build --packages-select usb_cam
colcon test --pacakges-select usb_cam

Integration Tests (requires specific CMake flag):

colcon build --packages-select usb_cam --cmake-args -DINTEGRATION_TESTS=1
colcon test --pacakges-select usb_cam

There are two levels of format support to consider:

1. Device Support: Run the node and check the console output to see what formats your hardware (V4L device) supports (e.g., Motion-JPEG, YUYV).
2. Driver Support: To see which formats the usb_cam driver can handle, run the node with an invalid pixel_format parameter. The driver will report its supported list.

Once identified, set the desired format in your parameters file using the pixel_format key.

# Check driver supported formats by passing an invalid string
ros2 run usb_cam usb_cam_node_exe --ros-args -p pixel_format:="test"