husarion/camera

husarion/camera

适用于Husarion机器人的ROS 2 UVC相机节点——通过V4L2打开USB相机，将H.264/MJPEG/原始帧发布到ROS 2话题，还支持可选的***监听音频。原生编码的H.264/MJPEG直接透传；原始捕获帧会在主机上重新编码为H.264/MJPEG（优先使用硬件加速VAAPI/NVENC/v4l2m2m，无硬件加速时用软件libx264，详见下文硬件加速指南）。也可摄入上游ROS图像/H.264话题（如OAK相机）并重新封装或编码。

多架构支持：linux/amd64 + linux/arm64。

标签

• husarion/camera:X.Y.Z — 固定生产版本（推荐）
• husarion/camera:latest — 跟踪最新发布版本

每个X.Y.Z版本均在Husarion硬件上验证。查看上方Tags标签页获取所有可用版本。

快速启动

yaml
services:
  camera:
    image: husarion/camera:0.6.3
    network_mode: host
    ipc: host
    env_file:
      - /home/husarion/config/common/.env   # ROS_DOMAIN_ID、RMW、命名空间
    environment:
      - CAMERA_DEVICE=/dev/video0
      - CAMERA_FORMAT=h264
      - CAMERA_WIDTH=1920
      - CAMERA_HEIGHT=1080
      - CAMERA_FPS=30
    devices:
      - /dev/snd:/dev/snd
      # /dev/dri仅在有Mesa用户空间渲染节点的主机上使用（Intel/AMD桌面、NVIDIA通过容器工具包）
      # Pi4无/dev/dri——添加会导致Docker启动服务失败，详见下文“硬件视频加速”
      - /dev/dri:/dev/dri
    volumes:
      - /dev:/dev
    device_cgroup_rules:
      - "c 81:* rmw"   # V4L2设备
      - "c 116:* rmw"  # ALSA音频设备
    group_add: ["video", "audio"]
    restart: unless-stopped

发布的话题与服务

• 帧:
  • ~/image_raw/h264 — foxglove_msgs/CompressedVideo（H.264格式，原生或原始模式重新编码）
  • ~/image_raw/compressed — sensor_msgs/CompressedImage（MJPEG格式）
  • ~/image_raw — sensor_msgs/Image（原始透传，仅当有订阅者时延迟发布）
  • ~/image_raw/h264/parameter_sets — SPS+PPS辅助数据（仅原生H.264模式；原始模式会内联添加）
• 音频（可选）: ~/audio（***格式） + latch状态~/audio_info
• Latch状态: ~/capabilities、~/active_mode、~/connected、~/camera_info
• 服务: ~/set_format、~/set_mmap_buffers、~/pan/set、~/tilt/set、~/zoom/set、~/ptz/home

~为容器运行的ROS命名空间（通过ROS_NAMESPACE环境变量设置）。

配置

常用环境变量：

硬件视频加速

原生H.264相机（如GUV3100）直接透传帧，无需编码器；硬件加速仅在原始模式（相机发布未压缩帧，节点重新编码）或切换到相机不支持的分辨率时生效。

CAMERA_ENCODER=auto会在首次订阅时按优先级探测可用硬件路径并记录选择（如encoder selected: h264_v4l2m2m (h264) …）。若硬件存在但仍选择libx264，则主机配置未完成。

Intel/AMD x86主机——VAAPI

yaml
volumes:
  - /dev:/dev
devices:
  - /dev/dri:/dev/dri
group_add: ["video"]

auto会选择h264_vaapi（使用/dev/dri/renderD128）。若有多个渲染节点，可通过CAMERA_ENCODER_VAAPI_DEVICE指定路径。

Raspberry Pi4——V4L2 M2M（bcm2835-codec）

Pi4的有状态M2M H.264编码器位于/dev/video11，仅当固件加载完整VideoCore镜像时出现（默认Raspberry Pi OS使用精简镜像，需修改配置）：

bash
# 主机操作：
sudo sed -i 's/^gpu_mem=16$/gpu_mem=128/' /boot/firmware/config.txt
sudo reboot
# 重启后验证：
ls /dev/video11                          # 必须存在
v4l2-ctl --list-devices | grep codec     # 应显示bcm2835-codec-encode at /dev/video11

Compose服务中省略/dev/dri（Pi4无Mesa渲染节点，添加会导致容器启动失败）。通过/dev:/dev挂载和c 81:* rmw规则即可暴露/dev/video11，auto会选择h264_v4l2m2m。

若编码器仍显示libx264，可指定CAMERA_ENCODER=h264_v4l2m2m并尝试CAMERA_RAW_FOURCC=YUYV。

NVIDIA x86（桌面/工作站）——NVENC

主机安装https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html%EF%BC%8C%E7%84%B6%E5%90%8E%E5%9C%A8Compose%E4%B8%AD%E6%B7%BB%E5%8A%A0%EF%BC%9A

yaml
deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          capabilities: [video, compute]

auto会选择h264_nvenc。保留/dev/dri:/dev/dri可作为集成GPU的VAAPI fallback。

NVIDIA Jetson——V4L2 M2M

Jetson通过V4L2 M2M暴露硬件编码器（/dev/nvhost-msenc + nvv4l2encoder GStreamer元素）。镜像内置FFmpeg可通过h264_v4l2m2m使用，需传递设备节点：

yaml
volumes:
  - /dev:/dev
runtime: nvidia    # 若主机配置了nvidia-container-runtime
group_add: ["video"]

若auto未选择，可指定CAMERA_ENCODER=h264_v4l2m2m（优先尝试h264_nvenc可能因CUDA运行时缺失失败）。

软件 fallback——libx264

始终可用，但消耗CPU。Pi4未设置gpu_mem=128时，原始1080p@30会占用大量核心，建议切换到原生H.264捕获（CAMERA_FORMAT=h264）或降低分辨率至720p。

关于

由Husarion构建维护——专注机器人研究与商用UGV平台。预捆绑的机器人安装脚本（Compose栈 + 原生husarion-agent安装）见公开发布索引：https://github.com/husarion/husarion-cockpit-releases。

许可证：Apache-2.0。